@kitschpatrol/shared-config 8.12.1 → 8.13.1

package/skills/ksc-update/references/verification.md

@@ -1,9 +1,44 @@
-# Consumer verification recipes
+# Verification recipes
 
 Use these recipes during Setup and step 5. Save commands, versions, raw logs,
-and results under `node_modules/.cache/ksc-update/`. Run pnpm commands as separate
-bare invocations; save their captured output in a later operation so sandbox
-command exclusions still match.
+and results in the run directory, `$KSC_UPDATE_RUN_DIR`, created once using the
+[Environment instructions](../SKILL.md#environment),
+under `baseline/` and `updated/`. Capture output without losing exit codes and
+use the runner's normal permissions.
+
+## Baselines
+
+Keep these states distinct:
+
+- **Original checkout:** the starting manifests, lockfile, and policy settings
+  copied before any Setup edit. Identify the original locked tree without
+  claiming it passed checks that only ran later.
+- **Setup baseline:** every install attempt and build, test, lint, inventory,
+  and advisory output under `baseline/`, with the actual pnpm version, policy
+  changes, commands, environment, and lockfile diff. Label results after a
+  lockfile repair as repaired. A failure here predates the dependency updates
+  but may have been introduced by Setup; call it pre-existing only when evidence
+  shows it.
+- **Updated result:** compared with the Setup baseline, with every change
+  explained.
+- **Published release:** a fresh install resolving the currently allowed
+  versions is not the historical dependency tree; that needs a known lockfile or
+  preserved installation. A registry tarball alone does not recover it, so
+  report missing historical evidence rather than relabeling a fresh install.
+
+For build-producing repositories, save the baseline artifacts such as `dist/`,
+disable nondeterministic steps such as encryption or timestamps through
+repository switches, and record the matching commands and environment for later
+comparison.
+
+For each published package, record declared `engines.node`, the effective
+consumer minimum and full supported range, and separate development
+requirements. Inspect published dependency trees and artifacts, not just the
+root or the current CI runtime. When support is undeclared, derive the existing
+requirement from published code and dependencies rather than assuming the
+developer runtime is the consumer floor. Capture the production inventory,
+advisory report, isolated consumer installs, and representative fixture results
+below before updates, and repeat them for the updated result.
 
 ## Production-tree engines
 
@@ -13,156 +48,243 @@ For each published package, run in its directory before and after updates:
 pnpm list --prod --depth Infinity --json
 ```
 
-Save stdout as `production-tree.json` in the corresponding baseline or updated
-results folder. If stdout contains lines beginning with `[WARN]`, preserve those
-warnings separately and remove only those lines before parsing. Require a
-successful command and valid JSON; do not extract an arbitrary JSON-looking
-substring from failed output. In a monorepo, include every published package,
-not only a private root with no production dependencies.
+Save stdout as `production-tree.json` in the matching results folder. If stdout
+contains lines beginning with `[WARN]`, keep those warnings separately and strip
+only those lines before parsing. Require a successful command and valid JSON;
+never extract a JSON-looking substring from failed output. In a monorepo include
+every published package, not only a private root.
 
-The list supplies installed paths; read each installed `package.json` for its
-actual engine declaration. Save this helper in the run's cache as
-`production-engines.mjs` and run it with the saved JSON path as its argument:
+The list supplies installed paths, and each installed `package.json` holds the
+actual engine declaration. The skill's `scripts/production-engines.mjs` walks
+the tree and prints one sorted row of name, version, and declared `engines.node`
+per installed package:
 
-```js
-import { readFileSync } from 'node:fs'
-import { join } from 'node:path'
+```bash
+node "<skill-directory>/scripts/production-engines.mjs" production-tree.json > production-engines.txt
+```
 
-const roots = JSON.parse(readFileSync(process.argv[2], 'utf8'))
-if (!Array.isArray(roots)) {
-  throw new TypeError('Expected pnpm list JSON array')
-}
+Save the inventory and diff it after resolution and deduplication. A row with
+`installed: false` is a dependency this host did not install, usually a
+platform-specific optional dependency; review its engines from registry
+metadata, because one host's installed tree cannot prove it. An omitted `node`
+field means undeclared support, not compatibility. Check full semver ranges
+against every supported consumer Node.js line, and check shipped or bundled code
+separately. This inventory does not replace the newest-in-range registry review.
 
-const manifests = new Map()
-const rows = new Set()
+## Security advisories
 
-function visit(pkg) {
-  if (!pkg.path) {
-    throw new Error(`Missing installed path: ${pkg.name ?? pkg.version}`)
-  }
+Before and after updates, in each workspace root:
 
-  if (!manifests.has(pkg.path)) {
-    manifests.set(pkg.path, JSON.parse(readFileSync(join(pkg.path, 'package.json'), 'utf8')))
-  }
+```bash
+pnpm audit --prod --json > audit.json
+echo $? > audit.exit
+```
 
-  const manifest = manifests.get(pkg.path)
-  rows.add(
-    JSON.stringify({
-      name: manifest.name,
-      node: manifest.engines?.node,
-      version: manifest.version,
-    }),
-  )
-  for (const group of ['dependencies', 'optionalDependencies']) {
-    const children = Object.values(pkg[group] ?? {})
-    for (const child of children) {
-      visit(child)
-    }
-  }
-}
+Diff the two reports and list advisories that are new, resolved, or still open,
+with their advisory identifiers and dependency paths. Never run `pnpm audit
+--fix`: it writes overrides and release-age exclusions outside the override and
+exemption policies. Resolve an open advisory through an accepted update or a
+reviewed override under the configuration policy, and otherwise report it as a
+gap.
 
-for (const root of roots) {
-  visit(root)
-}
+## Packed builds
 
-process.stdout.write(`${[...rows].toSorted().join('\n')}\n`)
-```
+Use this repository's tests and CLI fixtures for baseline comparisons.
 
-Save the resulting inventory and diff it after resolution and deduplication.
-Investigate missing installed paths instead of omitting them. An omitted `node`
-field means undeclared support, not proof of compatibility. Check full semver ranges
-against every supported consumer Node.js line; check platform-specific optional
-dependencies and shipped/bundled code separately because one host's installed
-tree cannot prove their compatibility. This inventory does not replace the
-newest-in-range registry review.
-
-## Known consumers and packed builds
-
-Read confirmed consumers from the repository's existing `CLAUDE.md` or
-`AGENTS.md`. A useful `Known consumers` entry contains the consumer's name and
-path, which package/imports/CLI it uses, its test command, and representative
-CLI commands and fixture inputs. Preserve existing instructions; add only facts
-confirmed by the user or repository evidence.
-
-1. Create a temporary directory under `${TMPDIR:-/tmp}`. Clone each local
-   consumer into it with `git clone --no-hardlinks <consumer-path> <temp-copy>`.
-   Record the commit. A clone excludes uncommitted changes; if those matter,
-   explicitly copy the needed working-tree files and record that baseline.
-   Do not modify the consumer's original checkout.
-2. Install and test the copied consumer with its starting lockfile. Save
-   its tests' results and representative CLI stdout, stderr, and exit codes.
-   Preserve this copy for baseline comparison.
-3. Build the updated package with its development Node.js version and run
-   `pnpm pack` as a bare command in that package. Inspect the archive's contents
-   and manifest, including exported entrypoints, engines, and dependency ranges.
-4. In a second consumer copy, replace the consumed dependency with a `file:`
-   specifier pointing to that tarball, using a direct manifest edit. Install
-   and rerun the same tests and CLI fixtures. If a workspace-local dependency
-   or alias is involved, replace the actual consuming edge and verify the
-   resolved path/version; do not assume a root-only edit reaches it. A linked
-   built package is useful for iteration, but the tarball verifies what ships
-   and avoids a link silently borrowing the producer's `node_modules`.
-5. Diff CLI output and fixture results. Inspect semantic differences, including
-   behavior JSON may hide, such as object prototypes, missing versus undefined
-   values, ordering, and error handling. Explain each change against accepted
-   migrations and consumer expectations.
+1. Build the package with its development Node.js version and run `pnpm pack` in
+   that package. Inspect the archive's contents and manifest, including exported
+   entrypoints, engines, and dependency ranges.
+2. Create an isolated fixture under the run directory with a `file:` dependency
+   on that tarball. Install it and run representative API and CLI checks with
+   the repository's fixtures. Verify the resolved path and version; the tarball
+   checks what ships without borrowing the producer's `node_modules`.
+3. Diff CLI output and fixture results against the Setup baseline. Inspect
+   semantic differences that JSON can hide, such as object prototypes, missing
+   versus undefined values, ordering, and error handling, and explain each
+   change against accepted migrations and consumer expectations.
 
 Also test a fresh isolated install of the published release with the newest
-dependencies its ranges allow. Keep this distinct from the published release
-running on its old dependencies: reproduce the latter from a known historical
-lockfile or preserved installation where possible. A registry tarball alone
-does not recover the old transitive tree. If it cannot be reconstructed, report
-that gap instead of labeling a fresh install the historical baseline.
+dependencies its ranges allow, kept distinct from the historical state as the
+Baselines section describes.
+
+`scripts/packed-fixture.mjs <state>` performs steps 1 and 2 up to the install:
+it packs every published workspace package, records each tarball's manifest and
+file list in `packed-manifests.json`, and installs a fixture under `<run
+directory>/<state>/fixture`. With `--published name@version` it installs the
+registry release instead, for the fresh-install check. Run the representative
+checks inside the printed fixture directory yourself. Pitfalls it handles, which
+a hand-built fixture must handle too:
+
+- Packing rewrites `workspace:` ranges to registry versions, so a fixture that
+  depends only on one tarball silently installs its siblings from the registry.
+  Override every packed sibling to its tarball.
+- Some consumer setup must exist before installing, for example an init command
+  that writes `publicHoistPattern` so bins and plugins resolve. Follow the
+  documented consumer installation order; `--before-install` runs such a
+  command, with `FIXTURE_TARBALLS` naming a JSON map of package to tarball for
+  `dlx` against a packed package.
+- Exported JSON or JSONC files, such as tsconfig presets, cannot be imported as
+  ES modules; check them with the consuming tool, for example `tsc
+--showConfig`.
+- Fixers mutate files in the fixture, including untracked probe scripts. Restore
+  the tree (`git checkout -- .` after committing the setup, and regenerate
+  untracked probes) before every run that should be comparable.
+- pnpm may append `minimumReleaseAgeExclude` entries to the fixture's workspace
+  file when it falls back to young versions; that is expected in a fixture and
+  shows which young versions consumers resolve.
 
 ## Exact Node.js floor
 
-Use the exact minimum supported release, not just the same major or the active
-developer runtime. For disjoint supported Node.js lines, check each relevant
-minimum. For an approved engine bump, compare the old release at its old floor
-with the updated package at its new floor and on an overlapping supported
-runtime where available.
-
-If the version manager has no suitable installed binary, download the exact
-official archive from `https://nodejs.org/dist/v<version>/` for the host's OS and
-architecture into a temporary folder, alongside `SHASUMS256.txt`. Verify the
-archive's SHA-256 against that file, then extract it there. Use the resulting
-Node binary by absolute path; do not install globally or change the user's
-default runtime. Record `<absolute-node-path> --version` with the results.
-
-Install/build with the development runtime if the tooling requires it, then
-invoke the packed package's built JavaScript entrypoint and runtime fixtures
-with the exact-floor binary. For subprocesses that use `env node`, put that
-binary's directory first in the test process's `PATH` only. Confirm which
-binary the child process uses. If the test runner itself requires newer Node,
-run a small fixture harness or the built CLI directly at the floor; running
-only the newer test runner is not floor validation. Report when installation
-or execution on the exact runtime could not be verified.
+Validate at the exact minimum supported release, not the same major or the
+active developer runtime. For disjoint supported lines check each relevant
+minimum. For an approved engine change compare the old release at its old floor
+with the updated package at its new floor, and on an overlapping supported
+runtime where one exists.
+
+Obtain the exact runtime without changing the user's default. In the isolated
+fixture declare the floor version:
+
+```json
+{
+  "devEngines": {
+    "runtime": { "name": "node", "version": "24.16.0", "onFail": "download" }
+  }
+}
+```
+
+Run `pnpm install` there and confirm `pnpm exec node --version`; pnpm downloads
+the release, verifies it, and records the checksum in the fixture's lockfile. If
+that is unavailable, download the official archive for the host from
+`https://nodejs.org/dist/v<version>/` together with `SHASUMS256.txt`, verify the
+SHA-256, extract it in the run directory, and use the binary by absolute path.
+Record the binary's path and `--version` output with the results either way.
+
+Install and build with the development runtime when the tooling requires it,
+then invoke the packed package's built entrypoint and runtime fixtures with the
+floor binary. For subprocesses that use `env node`, put the floor binary's
+directory first in the test process's `PATH` only, and confirm which binary the
+child used. If the test runner itself needs newer Node.js, run a small fixture
+harness or the built CLI directly at the floor; running only the newer runner is
+not floor validation. Report when installation or execution at the exact runtime
+could not be verified.
+
+`scripts/run-at-node.mjs <version> --cwd <fixture> -- <command>` does all of
+this: it downloads and verifies the release through `devEngines.runtime` in the
+run directory, puts a logging `node` shim first in `PATH`, runs the command, and
+reports how many `node` processes started and with which versions. A count that
+is implausibly low for the command means children bypassed `PATH`; treat that as
+unverified rather than as a pass.
 
 Record stdout, stderr, exit codes, and relevant API results for identical
 fixtures across runtimes and dependency baselines. Normalize only known
-nondeterministic fields using the same documented transformation for all runs.
-Save SHA-256 digests of normalized fixture output for quick comparison, retain
-the actual output for reviewing differences, and add targeted assertions for
-behavior that serialization omits.
+nondeterministic fields with the same documented transformation for every run.
+Save SHA-256 digests of normalized output for quick comparison, keep the actual
+output for reviewing differences, and add targeted assertions for behavior that
+serialization omits.
+
+`scripts/compare-outputs.mjs <dir-a> <dir-b>` compares two result directories
+with the standard normalization: state names only as path segments (`--token-a`,
+`--token-b`), pnpm store directory names, git blob ids, and content-hashed
+filenames. Never replace a state name as a bare word: `baseline` also occurs in
+CSS properties and rule names. Use `--sort-lines` only for output whose parallel
+tools interleave differently on each run, such as `ksc lint`.
+
+## Updated validation
+
+After resolution and deduplication, run:
+
+```bash
+pnpm build
+pnpm fix
+pnpm build # if fix changed source files or build configuration
+pnpm test
+pnpm lint
+```
+
+Skip a script the repository does not define and say so. Compare every check
+with the recorded baseline, and use these procedures where applicable; later
+cleanup steps reuse them for affected checks:
+
+- **Published consumers:** diff the production-engine inventories; inspect
+  packed manifests and artifacts; test isolated installations and representative
+  fixtures at the exact supported floors above, separately from
+  development-runtime checks. Review fixer edits to `engines.node` and
+  `devEngines.runtime`. Passing on newer Node.js does not establish consumer
+  compatibility. Validate new contracts and record changed baselines for
+  authorized breaks.
+- **Advisories:** diff the audit reports as described above.
+- **Warnings:** trace and report new warnings, deprecations, and peer issues
+  with the configuration policy's procedure, applying only its permitted
+  suppressions or explicitly authorized exceptions.
+- **Build output:** when a baseline exists, rebuild with its command and
+  environment and diff the trees with content-hashed filenames normalized
+  (`name.[hash].js`). Explain every remaining difference through an upstream
+  changelog, issue, or reviewed migration or configuration change, and
+  investigate the rest. Record effective targets before and after: unless
+  configured explicitly, tsdown derives its target from `engines.node`. Changed
+  syntax can be expected, but syntax lowering does not polyfill runtime APIs.
+- **Fixer output:** review the diff and compare a required rebuild with the
+  pre-fix build. Formatting changes must produce identical output; handle
+  behavioral or browser-compatibility changes under the configuration policy's
+  lint-fix rules and recheck the behavior after correction.
+
+On failure, make the smallest change the authorization table allows and rerun
+from the failing step, using the baseline logs to separate new failures, subject
+to the baseline qualifications above. `git stash` does not restore
+`node_modules`. To isolate an update, reset half of the accepted specifiers, run
+`pnpm update -r --no-save`, and repeat the failing check; defer the culprit
+unless an authorized migration resolves it. For a runtime release that published
+ranges already allow, follow the consumer-range decision; resetting a specifier
+or the lockfile may not exclude it.
+
+## Tool behavior notes
+
+Known behaviors that look like failures, or hide them:
+
+- `ksc fix` prints nothing when everything was fixed; only remaining problems
+  produce output. A silent exit code of 0 is success.
+- `ksc lint` and `ksc fix` use tool caches. Before trusting a pass on files a
+  fix or migration touched, rerun ESLint with `--no-cache` and `ksc-prettier
+lint --no-cache`.
+- Output from `ksc lint` interleaves its parallel tools differently on each run;
+  compare it with sorted lines.
+- mdat expands rules from the `package.json` nearest to where it runs. Never run
+  `mdat expand` on a package readme from a monorepo root; it fills the title,
+  description, and other rules from the private root manifest. Regenerate
+  through the repository's own script.
+- Use `pnpm -r ls --depth -1 --json` to enumerate workspace packages instead of
+  globbing `packages/*`, which also matches stray entries such as `.DS_Store`.
+- Recent pnpm lockfiles contain several YAML documents, the first describing the
+  package manager's own dependencies; a lockfile parser must read every
+  `packages:` section.
 
 ## Tool references
 
 Check these primary sources or the installed tool's help when behavior differs:
 
-- [GitHub Actions variables](https://docs.github.com/en/actions/reference/workflows-and-actions/variables):
-  `GITHUB_ACTIONS` and `CI` identify unattended execution in Actions.
-- [pnpm update](https://pnpm.io/cli/update): manifest/catalog writes and selectors.
-  This workflow uses a bare update for its full dependency refresh; do not
-  assume exclusion syntax works identically in every pnpm implementation.
-- [pnpm dedupe](https://pnpm.io/cli/dedupe) and
-  [pnpm list](https://pnpm.io/cli/list): deduplication checks and tree inventories.
-- [pnpm settings](https://pnpm.io/settings) and
-  [peer rules](https://pnpm.io/settings/peer-dependencies#peerdependencyrulesallowedversions):
-  current configuration locations and scoped warning allowances. Current pnpm
-  uses `.npmrc` for registry/auth settings, not all policy settings.
-- [Taze](https://github.com/antfu-collective/taze): candidate filters and maturity.
-- [Actions Up](https://github.com/azat-io/actions-up#update-style): SHA pinning.
-- [tsdown target](https://tsdown.dev/options/target): implicit engine-derived
-  targets affect emitted syntax and do not provide API polyfills.
-- [Node.js release archives](https://nodejs.org/dist/): exact runtime downloads
-  and checksum manifests.
+- [GitHub Actions
+  variables](https://docs.github.com/en/actions/reference/workflows-and-actions/variables):
+  `GITHUB_ACTIONS` and `CI` identify unattended execution.
+- [pnpm update](https://pnpm.io/cli/update): `--no-save` and what an update
+  writes. The full refresh here uses no package selectors; do not assume
+  exclusion syntax is identical in every pnpm version.
+- [pnpm dedupe](https://pnpm.io/cli/dedupe),
+  [pnpm list](https://pnpm.io/cli/list), and [pnpm audit](https://pnpm.io/cli/audit).
+- [pnpm settings](https://pnpm.io/settings), including
+  [minimumReleaseAge](https://pnpm.io/settings/dependency-resolution#minimumreleaseage),
+  [trustPolicy](https://pnpm.io/settings/dependency-resolution#trustpolicy),
+  [allowBuilds](https://pnpm.io/settings/build#allowbuilds), and
+  [peer rules](https://pnpm.io/settings/peer-dependencies#peerdependencyrulesallowedversions).
+  Current pnpm reads only registry and auth settings from `.npmrc`.
+- [devEngines.runtime](https://pnpm.io/package_json#devenginesruntime): exact
+  runtime downloads for fixtures.
+- [Taze](https://github.com/antfu-collective/taze): candidate filters, maturity,
+  and the pnpm settings it infers.
+- [Actions Up](https://github.com/azat-io/actions-up): SHA pinning, cool-down,
+  and `--min-age-exclude`.
+- [Node.js release schedule](https://github.com/nodejs/Release): LTS lines and
+  the annual all-LTS cycle from Node 27.
+- [tsdown target](https://tsdown.dev/options/target): engine-derived targets
+  affect emitted syntax and do not polyfill APIs.
+- [Node.js release archives](https://nodejs.org/dist/): fallback runtime
+  downloads and checksum manifests.

package/skills/ksc-update/scripts/compare-outputs.mjs

@@ -0,0 +1,144 @@
+/**
+ * Compares two directories of captured outputs, such as baseline and updated
+ * fixture results or build trees, after normalizing only known nondeterministic
+ * text, and reports each file as identical, different, or present on one side.
+ *
+ * Normalization:
+ *
+ * - `--token-a` and `--token-b` replace state names such as `baseline` and
+ *   `updated` with `<STATE>`, but only where they appear as a path segment
+ *   (bounded by `/`, `\`, or `+`). Bare-word replacement would also rewrite
+ *   content such as the CSS property `alignment-baseline`.
+ * - Store directory names that pnpm ends with `_` plus 32 hex characters become
+ *   `<STORE-DIR>`. pnpm truncates long names before the hash, so the whole
+ *   segment varies with the state name's length, not just the hash.
+ * - Git blob ids in captured diffs (`index abc123..def456`) become `index
+ *   <BLOBS>`.
+ * - Content-hashed filenames (`name.<8+ characters>.js`) become `name.[hash].js`.
+ * - `--sort-lines` sorts lines first, for output that parallel tools interleave
+ *   differently on each run. Never use it where order is meaningful.
+ *
+ * Usage:
+ *
+ * ```
+ * node compare-outputs.mjs <dir-a> <dir-b> [--token-a <name>] [--token-b <name>] [--sort-lines]
+ * ```
+ *
+ * Prints a short `git diff --no-index` of each differing file and exits 1 when
+ * anything differs.
+ */
+import { spawnSync } from 'node:child_process'
+import { mkdtempSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import process from 'node:process'
+import { runDirectory } from './lib.mjs'
+
+/** @type {string[]} */
+const positional = []
+/** @type {Record<string, string>} */
+const options = {}
+let sortLines = false
+const argv = process.argv.slice(2)
+for (let index = 0; index < argv.length; index++) {
+	const argument = argv[index] ?? ''
+	if (argument === '--sort-lines') {
+		sortLines = true
+	} else if (argument.startsWith('--')) {
+		options[argument.slice(2)] = argv[++index] ?? ''
+	} else {
+		positional.push(argument)
+	}
+}
+
+const [directoryA, directoryB] = positional
+if (directoryA === undefined || directoryB === undefined) {
+	throw new Error(
+		'Usage: node compare-outputs.mjs <dir-a> <dir-b> [--token-a x] [--token-b y] [--sort-lines]',
+	)
+}
+
+/**
+ * Lists files under a directory recursively, as paths relative to it.
+ *
+ * @param {string} root - Directory to walk.
+ *
+ * @returns {string[]} Relative file paths.
+ */
+function listFiles(root) {
+	return readdirSync(root, { recursive: true, withFileTypes: true })
+		.filter((entry) => entry.isFile())
+		.map((entry) => relative(root, join(entry.parentPath, entry.name)))
+		.toSorted()
+}
+
+/**
+ * Normalizes one file's text for comparison.
+ *
+ * @param {string} text - File contents.
+ * @param {string | undefined} token - State name to replace on this side.
+ *
+ * @returns {string} Normalized text.
+ */
+function normalize(text, token) {
+	let result = text
+	if (token !== undefined && token !== '') {
+		const escaped = token.replaceAll(/[$\(\)*+.?\[\\\]^\{\|\}]/gv, String.raw`\$&`)
+		result = result.replaceAll(
+			new RegExp(String.raw`(?<=[\/\\+])${escaped}(?=[\/\\+])`, 'gv'),
+			'<STATE>',
+		)
+	}
+
+	result = result
+		.replaceAll(/[^\s"'\/\\]*_[\da-f]{32}/gv, '<STORE-DIR>')
+		.replaceAll(/^index [\da-f]+\.\.[\da-f]+/gmv, 'index <BLOBS>')
+		.replaceAll(/\.[\w\-]{8,}\.(c?js|mjs|css)\b/gv, '.[hash].$1')
+	return sortLines ? result.split('\n').toSorted().join('\n') : result
+}
+
+const filesA = new Set(listFiles(directoryA))
+const filesB = new Set(listFiles(directoryB))
+const scratch = mkdtempSync(join(runDirectory(), 'compare-'))
+let differences = 0
+
+for (const file of [...filesA.union(filesB)].toSorted()) {
+	if (!filesA.has(file) || !filesB.has(file)) {
+		differences++
+		process.stdout.write(`only in ${filesA.has(file) ? 'A' : 'B'}: ${file}\n`)
+		continue
+	}
+
+	const pathA = join(directoryA, file)
+	const pathB = join(directoryB, file)
+	if (statSync(pathA).size === 0 && statSync(pathB).size === 0) {
+		continue
+	}
+
+	const textA = normalize(readFileSync(pathA, 'utf8'), options['token-a'])
+	const textB = normalize(readFileSync(pathB, 'utf8'), options['token-b'])
+	if (textA === textB) {
+		continue
+	}
+
+	differences++
+	const safeName = file.replaceAll(/[\/\\]/gv, '__')
+	writeFileSync(join(scratch, `a-${safeName}`), textA)
+	writeFileSync(join(scratch, `b-${safeName}`), textB)
+	const diff = spawnSync(
+		'git',
+		['diff', '--no-index', '--no-color', '-U1', `a-${safeName}`, `b-${safeName}`],
+		{ cwd: scratch, encoding: 'utf8' },
+	)
+	const lines = diff.stdout.split('\n')
+	process.stdout.write(`differs: ${file}\n${lines.slice(4, 44).join('\n')}\n`)
+	if (lines.length > 44) {
+		process.stdout.write(`  ... ${lines.length - 44} more diff lines\n`)
+	}
+}
+
+process.stdout.write(
+	`${differences === 0 ? 'no differences' : `${differences} file(s) differ`} (normalized copies in ${scratch})\n`,
+)
+if (differences > 0) {
+	process.exitCode = 1
+}