Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 13 additions & 4 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,15 +16,24 @@ updates:
dependency-type: development
update-types: [minor, patch]
ignore:
# Pinned exactly to the version actions/package.json vendors into the
# single-page bundles (tests/artifact-checks.spec.js enforces the match),
# so a root-only bump always fails. Bump both files together, by hand.
- dependency-name: mermaid
# @astrojs/check peers typescript ^5 || ^6; a major beyond that fails
# `npm ci` with ERESOLVE. Lift once @astrojs/check accepts the next major.
- dependency-name: typescript
update-types: [version-update:semver-major]

# actions/ has its own lockfile and ships to every docs repo that calls the
# publishing actions. Its htmlparser2/postcss may differ from the root's: the
# checker self-test runs against both trees (the actions job in ci.yml, and
# tests/artifact-checks.spec.js for the root).
- package-ecosystem: npm
directory: /actions
schedule:
interval: weekly
open-pull-requests-limit: 5
groups:
actions-dependencies:
update-types: [minor, patch]

- package-ecosystem: github-actions
directory: /
schedule:
Expand Down
7 changes: 3 additions & 4 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ Orchestrator: `scripts/build-vite.js`. Flags: `--local`, `--headless`.
- `scripts/build-vite.js` — Build orchestrator (4 steps: prepare, hoist, copy assets, astro build)
- `scripts/fetch-apps.js` — GitHub Release artifact downloader. Only *obtains* an artifact; installing it is one shared path in `build-vite.js`
- `scripts/artifacts.js` — Safe tarball extraction + tree copy, shared by both fetch paths. Validates archive members (no traversal, no absolute paths, no symlinks) before anything is written, and replaces the old `cp -r`/`tar` shell-outs so the build runs on Windows
- `scripts/check-artifact.js` — Runs the publish action's contract checker (`actions/lib/check.js`) on every installed artifact, before hoisting; logs findings grouped by rule, and fails a strict build on an error. `check.js` resolves its parsers from `actions/node_modules` or the root, which pins the same versions
- `scripts/check-artifact.js` — Runs the publish action's contract checker (`actions/lib/check.js`) on every installed artifact, before hoisting; logs findings grouped by rule, and fails a strict build on an error. `check.js` resolves its parsers from `actions/node_modules` or the root; the two may pin different versions, and `tests/artifact-checks.spec.js` runs the checker self-test against whichever the build resolves
- `scripts/hoist-inline-scripts.js` — Moves inline `<script>` bodies in sub-app HTML into files before the Astro build, so the deployment can serve `script-src 'self'`. Needed because bundles published before the action stopped emitting an inline mermaid bootstrap still contain one. A sub-app's dark-mode bootstrap is deleted here rather than hoisted — light only, and hoisting would put it beyond the reach of `transform.js`
- `actions/check-docs/` — Reusable GitHub Action for docs repo pull requests: runs `checkWorkspace()` from `actions/lib/check.js` on the built headless output, one annotation per rule, every finding in the job summary; errors fail it (warnings too with `strict: true`). Never packs or uploads
- `actions/publish-single-page-docs/` — Reusable GitHub Action that turns a repo's markdown into a single-page bundle
Expand Down Expand Up @@ -147,8 +147,7 @@ Self-contained Playwright E2E — `npm test` auto-starts everything (no external
registers the vendored `tests/fixtures/docs-example.kb-docs.tar.gz` (two apps)
(slugs `user-guide` + `guide-mirror`, for cross-app nav), an iframe entry pinned
`"headless": false`, and the generated single-page bundle fixture — with the real
mermaid bundle, copied from the root `mermaid` devDependency (pinned to the version
`actions/` vendors) and gitignored. `build:headless` builds it;
mermaid bundle, copied from the root `mermaid` devDependency and gitignored. `build:headless` builds it;
`tests/fragment-server.mjs` serves `dist/` mirroring the production **nginx** rewrites
(`/__wf/knowledge-base/*` → `/knowledge-base/*`). NB: `astro preview` is NOT used — its
Vite `configurePreviewServer` rewrite hook does not run for static output, so the
Expand Down Expand Up @@ -193,7 +192,7 @@ Every embedded test runs twice, as Playwright projects `chromium` (:4201) and
route; a narrow route tears the fragment down) — and what "smooth" means: no host reload,
the reframed iframe survives, one `astro:after-swap` and one host-document view transition
per hop, one `wf-html`, no duplicated stylesheet across a → b → c → a.
- `artifact-checks.spec.js` — the build-side checker: root and `actions/` pin the same parser versions, findings are grouped by rule, a strict build refuses an error finding.
- `artifact-checks.spec.js` — the build-side checker: the checker self-test passes with the parsers the build resolves (behaviour, not a version match with `actions/`), findings are grouped by rule, a strict build refuses an error finding.
- `artifact-safety.spec.js` — tarball extraction guards (traversal, absolute paths, symlinks).
- `nginx-config.spec.js` — static assertions on `nginx.conf`/`nginx.headers.conf`, including
that the CSP the Express mirror serves is byte-identical to nginx's.
Expand Down
4 changes: 3 additions & 1 deletion actions/lib/check.selftest.js
Original file line number Diff line number Diff line change
Expand Up @@ -229,7 +229,9 @@ check('reports a broken manifest as KB-MAN-001 instead of crashing', () => {
console.log('\nCatalogue');

check('contract/RULES.md and rules.js list the same rules, titles and severities', () => {
const md = readFileSync(RULES_MD, 'utf8');
// A Windows checkout may carry CRLF, which the line-anchored patterns below
// would otherwise not match at all.
const md = readFileSync(RULES_MD, 'utf8').replace(/\r\n/g, '\n');
const documented = {};
for (const m of md.matchAll(/^### (KB-[A-Z]+-\d{3}) — (.+)\n\n\*\*Severity:\*\* (error|warning)$/gm)) {
documented[m[1]] = { severity: m[3], title: m[2].replace(/`/g, '') };
Expand Down
8 changes: 4 additions & 4 deletions scripts/check-artifact.js
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,10 @@
* repo to chase, and for what.
*
* check.js resolves its parsers from actions/node_modules when that tree is
* installed and from the root node_modules otherwise. The root package.json
* pins htmlparser2 and postcss to the versions actions/package.json pins, so
* either way the build and the action parse the same way
* (tests/artifact-checks.spec.js holds the two in step).
* installed and from the root node_modules otherwise. The two package.json
* files may pin different versions of htmlparser2 and postcss;
* tests/artifact-checks.spec.js runs the checker's self-test against the
* parsers the build resolves, so they cannot parse differently.
*/

import { summarise } from '../actions/lib/check.js';
Expand Down
13 changes: 7 additions & 6 deletions scripts/setup-test-apps.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -140,12 +140,13 @@ if (/list-style-type/.test(LEGACY_DOC_CSS) || !/contains-task-list/.test(LEGACY_
}

/**
* The mermaid bundle the action vendors — the real one, so the suites can
* assert a diagram actually renders inside the fragment rather than only that
* the script reference resolves. Pinned in the root package.json to the
* version actions/package.json pins (tests/artifact-checks.spec.js keeps them
* equal). Copied here on every run and gitignored: 2.5 MB of minified JS is
* not worth committing when node_modules already has it.
* A real mermaid bundle, standing in for the one the action vendors, so the
* suites can assert a diagram actually renders inside the fragment rather than
* only that the script reference resolves. It comes from the root
* devDependency, which Dependabot bumps independently of actions/package.json:
* the rendering tests, not a version match, are what hold it to working.
* Copied here on every run and gitignored: 2.5 MB of minified JS is not worth
* committing when node_modules already has it.
*/
const MERMAID_BUNDLE = createRequire(import.meta.url).resolve('mermaid/dist/mermaid.min.js');

Expand Down
43 changes: 19 additions & 24 deletions tests/artifact-checks.spec.js
Original file line number Diff line number Diff line change
Expand Up @@ -4,27 +4,28 @@
* The build runs the publish action's contract checker on every artifact it
* installs (scripts/check-artifact.js). Two things keep that honest:
*
* 1. The build and the action parse with the same code at the same versions.
* check.js resolves htmlparser2/postcss from actions/node_modules when that
* tree is installed and from the root otherwise — CI's E2E job installs
* only the root — so the two package.json files must pin the same versions.
* 1. The build and the action parse the same way. check.js resolves
* htmlparser2/postcss from actions/node_modules when that tree is
* installed and from the root otherwise (CI's E2E job installs only the
* root), so the checker's own self-test runs here as well, against
* whichever parsers the build resolves. The two package.json files may
* pin different versions; they may not parse differently.
* 2. The reporting contract: grouped warnings in an ordinary build, and a
* strict (production) build that refuses an artifact with an error finding.
*
* No browser and no build: the checker's rules themselves are pinned by
* actions/lib/check.selftest.js.
* No browser and no build.
*/

import { test, expect } from '@playwright/test';
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { spawnSync } from 'node:child_process';
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';

import { checkApp, reportFindings, summarise } from '../scripts/check-artifact.js';

const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
const pkg = (rel) => JSON.parse(readFileSync(join(ROOT, rel), 'utf8'));

/** A minimal app directory with the given files. */
function app(files) {
Expand All @@ -42,22 +43,16 @@ const page = (html = 'data-kb-headless="true"', body = '') =>
const ENTRY = { slug: 'demo', entryPoint: 'index.html', pages: null };

test.describe('the build and the action parse the same way', () => {
test('root package.json pins the parsers at the versions actions/package.json pins', () => {
const root = pkg('package.json').dependencies;
const actions = pkg('actions/package.json').dependencies;
for (const name of ['htmlparser2', 'postcss']) {
expect(actions[name], `actions/package.json must pin ${name}`).toMatch(/^\d+\.\d+\.\d+$/);
expect(root[name], `package.json must pin ${name} exactly as actions/ does`).toBe(actions[name]);
}
});

// scripts/setup-test-apps.mjs vendors the root copy into the single-page
// fixture, standing in for the one the action vendors into published docs.
test('the fixture mermaid bundle is the version the action vendors', () => {
const root = pkg('package.json').devDependencies.mermaid;
const actions = pkg('actions/package.json').dependencies.mermaid;
expect(actions, 'actions/package.json must pin mermaid').toMatch(/^\d+\.\d+\.\d+$/);
expect(root, 'package.json must pin mermaid exactly as actions/ does').toBe(actions);
// The self-test pins every rule's findings on clean sites, violations and
// look-alikes. Run from here it resolves the parsers the build resolves, so
// a root htmlparser2 or postcss that parses differently from the action's
// fails it, while a bump that changes nothing is free to land on its own.
test("the checker self-test passes with the build's parsers", () => {
const run = spawnSync(process.execPath, [join(ROOT, 'actions', 'lib', 'check.selftest.js')], {
cwd: ROOT,
encoding: 'utf8',
});
expect(run.status, `${run.stdout}\n${run.stderr}`).toBe(0);
});
});

Expand Down
24 changes: 22 additions & 2 deletions tests/web-fragment.spec.js
Original file line number Diff line number Diff line change
Expand Up @@ -285,11 +285,31 @@ test.describe('Mermaid diagrams', () => {
await expect(diagram).not.toContainText('-->');
}

/** Fails the test on any page or fragment-frame error thrown while it runs. */
/**
* Console errors the browser itself raises about a deprecated API that
* third-party code still uses, not a failure of ours. Newer Chromium reports
* every `unload` listener as a permissions-policy violation, and reframed
* (web-fragments) registers one on its iframe window to abort the fragment's
* pending work. The diagram renders either way, which the tests assert.
*/
const BROWSER_DEPRECATION_NOISE = [
/^Permissions policy violation: unload is not allowed in this document\.?$/,
];

/**
* Fails the test on any page or fragment-frame error thrown while it runs.
* An uncaught exception always counts; a console error counts unless it is
* known browser deprecation noise.
*/
function collectErrors(page) {
const errors = [];
page.on('pageerror', (e) => errors.push(String(e)));
page.on('console', (msg) => { if (msg.type() === 'error') errors.push(msg.text()); });
page.on('console', (msg) => {
if (msg.type() !== 'error') return;
const text = msg.text();
if (BROWSER_DEPRECATION_NOISE.some((re) => re.test(text))) return;
errors.push(text);
});
return errors;
}

Expand Down
Loading