@wxxb789/anc 0.0.1

package/scripts/verify-output-inventory.js

@@ -0,0 +1,307 @@
+/**
+ * Exact route inventory plus tightly-owned build namespaces for the final site.
+ *
+ * Notes publish as HTML routes only. Static package assets are byte-compared to
+ * public/, Astro owns only flat hashed JS/CSS under _astro/, and Pagefind's
+ * content-addressed members must be referenced by its own metadata. Everything
+ * else is an unexpected publication surface and fails before copy-out.
+ */
+import { gunzipSync } from 'node:zlib';
+import { createHash } from 'node:crypto';
+import { lstatSync, readFileSync, readdirSync, statSync, } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DatabaseSync } from "../src/lib/sqlite.js";
+import { loadArtifact } from "../src/lib/artifact-source.js";
+import { noteRoute, WITHHELD_ROUTE } from "../src/lib/route-path.js";
+import { COLLECTIONS_SEGMENT, FIXED_ROUTES, TAGS_SEGMENT, collectionFacets, tagFacets, } from "../src/lib/routes.js";
+import { snapshotFileName } from "../src/lib/snapshot.js";
+import { readBuildBinding } from "../src/lib/snapshot-reader.js";
+import { BuildFailure } from "./write-report.js";
+import { assertSnapshotRows } from "../src/lib/snapshot-contract.js";
+import { isGzip, declaresWal, journalSidecar } from "./snapshot-rows.js";
+import { readStagedWasm } from "./copy-wasm.js";
+const DIST = fileURLToPath(new URL('../dist', import.meta.url));
+const PUBLIC = fileURLToPath(new URL('../public', import.meta.url));
+const GENERATED_FILES = ['_redirects', 'robots.txt', 'rss.xml', 'sitemap.xml'];
+const PAGEFIND_RUNTIME = [
+    'pagefind/pagefind-entry.json',
+    'pagefind/pagefind-highlight.js',
+    'pagefind/pagefind-worker.js',
+    'pagefind/pagefind.js',
+    'pagefind/pagefind-ui.css',
+    'pagefind/pagefind-ui.js',
+    'pagefind/pagefind-modular-ui.css',
+    'pagefind/pagefind-modular-ui.js',
+    'pagefind/pagefind-component-ui.css',
+    'pagefind/pagefind-component-ui.js',
+    'pagefind/wasm.unknown.pagefind',
+];
+function posix(path) {
+    return path.split(sep).join('/');
+}
+function filesUnder(root) {
+    const files = [];
+    const pending = [root];
+    while (pending.length > 0) {
+        const directory = pending.pop();
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            const path = join(directory, entry.name);
+            if (entry.isDirectory())
+                pending.push(path);
+            else
+                files.push(path);
+        }
+    }
+    return files.map((path) => posix(relative(root, path))).sort();
+}
+function htmlFile(route) {
+    if (route === '/')
+        return 'index.html';
+    if (route.startsWith('/') && route.endsWith('.html'))
+        return route.slice(1);
+    if (!route.startsWith('/') || !route.endsWith('/')) {
+        throw new BuildFailure('output-inventory-route-invalid', 'output inventory could not derive one static route', 'route has no static output shape: ' + JSON.stringify(route));
+    }
+    return route.slice(1) + 'index.html';
+}
+function expectedHtml(artifact) {
+    const routes = new Set([...FIXED_ROUTES, WITHHELD_ROUTE, '/404.html']);
+    for (const entry of artifact.entries)
+        routes.add(noteRoute(entry.slug));
+    for (const facet of tagFacets(artifact.entries))
+        routes.add('/' + TAGS_SEGMENT + '/' + facet.key + '/');
+    for (const facet of collectionFacets(artifact.entries)) {
+        routes.add('/' + COLLECTIONS_SEGMENT + '/' + facet.key + '/');
+    }
+    return new Set([...routes].map(htmlFile));
+}
+function inflateIfGzip(bytes) {
+    return isGzip(bytes) ? gunzipSync(bytes) : bytes;
+}
+/**
+ * The bound snapshot member, validated against its own filename and schema.
+ *
+ * An empty set when this build has no binding — a synthetic inventory fixture,
+ * or a checkout that has not run the snapshot step. When a binding exists, the
+ * exact digest-named file must be present: a misnamed or second `site.*.sqlite`
+ * is an unexpected member, and a wrong digest or schema fails here rather than
+ * after copy-out.
+ */
+function snapshotOutput(root, workspace) {
+    const binding = readBuildBinding(workspace);
+    if (binding === undefined)
+        return new Set();
+    const file = snapshotFileName(binding.digest);
+    const path = join(root, ...file.split('/'));
+    let bytes;
+    try {
+        bytes = readFileSync(path);
+    }
+    catch {
+        throw new BuildFailure('output-inventory-snapshot-missing', 'output inventory is missing its bound snapshot', file);
+    }
+    const digest = createHash('sha256').update(bytes).digest('hex');
+    if (digest !== binding.digest) {
+        throw new BuildFailure('output-inventory-snapshot-digest', 'output inventory snapshot digest does not match its bound URL', file + ': expected ' + binding.digest + ', got ' + digest);
+    }
+    // The accepted artifact is one rollback-journal file, and opening is not a
+    // read-only operation when SQLite believes it has journal work to do: a
+    // `-wal` sibling makes the driver recover, which fails on the read-only
+    // connection and — measured — creates a `-shm` file inside the directory
+    // being inspected. Refusing before the open is what keeps "scan the
+    // immutable artifact" a statement about bytes rather than about the driver's
+    // side effects. The enumerator's own WAL refusal covers the scanners; this
+    // covers inventory, which reads the same bytes directly.
+    if (declaresWal(bytes)) {
+        throw new BuildFailure('output-inventory-snapshot-format', 'output inventory snapshot is not in the accepted rollback-journal format', file + ': WAL header');
+    }
+    const sidecar = journalSidecar(path);
+    if (sidecar !== undefined) {
+        throw new BuildFailure('output-inventory-snapshot-format', 'output inventory snapshot carries a journal sidecar, which the accepted artifact does not', file + ': found ' + file.split('/').at(-1) + sidecar);
+    }
+    let database;
+    try {
+        database = new DatabaseSync(path, { readOnly: true });
+    }
+    catch (error) {
+        throw new BuildFailure('output-inventory-snapshot-unreadable', 'output inventory could not open its snapshot', file + ': ' + (error instanceof Error ? error.message : String(error)));
+    }
+    try {
+        assertSnapshotRows((sql) => database.prepare(sql).all());
+    }
+    catch (error) {
+        throw new BuildFailure('output-inventory-snapshot-schema', 'output inventory snapshot does not carry the accepted schema', file + ': ' + (error instanceof Error ? error.message : String(error)));
+    }
+    finally {
+        database.close();
+    }
+    return new Set([file]);
+}
+/**
+ * The bound SQLite WASM member, validated against its own filename.
+ *
+ * An empty set when this build staged no WASM (synthetic inventories without a
+ * browser runtime). When a binding exists, exactly the digest-named member must
+ * be present; a second `sqlite3*.wasm` is unexpected.
+ */
+function wasmOutput(root, workspace) {
+    const binding = readStagedWasm(workspace);
+    if (binding === undefined)
+        return new Set();
+    for (const member of binding.members) {
+        const path = join(root, ...member.split('/'));
+        if (member.endsWith('.wasm')) {
+            let bytes;
+            try {
+                bytes = readFileSync(path);
+            }
+            catch {
+                throw new BuildFailure('output-inventory-wasm-missing', 'output inventory is missing a bound wasm member', member);
+            }
+            const digest = createHash('sha256').update(bytes).digest('hex');
+            if (digest !== binding.digest) {
+                throw new BuildFailure('output-inventory-wasm-digest', 'output inventory wasm digest does not match its bound URL', member + ': expected ' + binding.digest + ', got ' + digest);
+            }
+        }
+        else if (!statSync(path).isFile()) {
+            throw new BuildFailure('output-inventory-wasm-missing', 'output inventory is missing a bound wasm member', member);
+        }
+    }
+    return new Set(binding.members);
+}
+function pagefindFiles(root, actual) {
+    // These are Pagefind's fixed runtime distribution. Content-addressed members
+    // are added only from pagefind-entry.json and the gzip metadata it names.
+    const allowed = new Set(PAGEFIND_RUNTIME);
+    const entryPath = join(root, 'pagefind', 'pagefind-entry.json');
+    let value;
+    try {
+        value = JSON.parse(readFileSync(entryPath, 'utf8'));
+    }
+    catch (error) {
+        throw new BuildFailure('output-inventory-pagefind-unreadable', 'output inventory could not read the Pagefind manifest', error instanceof Error ? error.stack ?? error.message : String(error));
+    }
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new BuildFailure('output-inventory-pagefind-invalid', 'output inventory found an invalid Pagefind manifest', 'pagefind-entry.json is not an object');
+    }
+    const languagesValue = value['languages'];
+    if (languagesValue === null || typeof languagesValue !== 'object' || Array.isArray(languagesValue) ||
+        Object.keys(languagesValue).length === 0) {
+        throw new BuildFailure('output-inventory-pagefind-invalid', 'output inventory found an invalid Pagefind manifest', 'pagefind-entry.json languages must be a non-empty object');
+    }
+    const metadata = [];
+    for (const [name, member] of Object.entries(languagesValue)) {
+        if (member === null || typeof member !== 'object' || Array.isArray(member)) {
+            throw new BuildFailure('output-inventory-pagefind-invalid', 'output inventory found an invalid Pagefind manifest', 'invalid Pagefind language member: ' + JSON.stringify(name));
+        }
+        const language = member;
+        const wasm = language['wasm'];
+        if (typeof language['hash'] !== 'string' || !/^[A-Za-z0-9_-]+$/.test(language['hash']) ||
+            (wasm !== null && (typeof wasm !== 'string' || !/^[A-Za-z0-9_-]+$/.test(wasm)))) {
+            throw new BuildFailure('output-inventory-pagefind-invalid', 'output inventory found an invalid Pagefind manifest', 'invalid Pagefind language references: ' + JSON.stringify(name));
+        }
+        const meta = 'pagefind/pagefind.' + language['hash'] + '.pf_meta';
+        allowed.add(meta);
+        // null is Pagefind's declaration that this language uses the fixed
+        // wasm.unknown.pagefind runtime already in PAGEFIND_RUNTIME.
+        if (typeof wasm === 'string')
+            allowed.add('pagefind/wasm.' + wasm + '.pagefind');
+        try {
+            metadata.push(inflateIfGzip(readFileSync(join(root, ...meta.split('/')))));
+        }
+        catch (error) {
+            throw new BuildFailure('output-inventory-pagefind-unreadable', 'output inventory could not read Pagefind metadata', meta + ': ' + (error instanceof Error ? error.stack ?? error.message : String(error)));
+        }
+    }
+    for (const file of actual) {
+        const match = /^pagefind\/(?:fragment|index)\/([A-Za-z0-9_-]+)\.(?:pf_fragment|pf_index)$/.exec(file);
+        if (match === null)
+            continue;
+        const reference = Buffer.from(match[1]);
+        if (metadata.some((bytes) => bytes.includes(reference)))
+            allowed.add(file);
+    }
+    return allowed;
+}
+/** Assert every final file belongs to one public route or one generated namespace. */
+export function assertOutputInventory(root, artifact, workspace) {
+    let actual;
+    try {
+        actual = filesUnder(root);
+    }
+    catch (error) {
+        throw new BuildFailure('output-inventory-unreadable', 'output inventory could not be read', error instanceof Error ? error.stack ?? error.message : String(error));
+    }
+    let staticPublic;
+    try {
+        const generatedFiles = new Set(GENERATED_FILES);
+        staticPublic = filesUnder(PUBLIC).filter((file) => !generatedFiles.has(file));
+        if (staticPublic.length === 0)
+            throw new Error('package public assets are empty');
+        for (const file of staticPublic) {
+            if (!lstatSync(join(PUBLIC, ...file.split('/'))).isFile()) {
+                throw new Error('package public member is not a regular file: ' + file);
+            }
+        }
+    }
+    catch (error) {
+        throw new BuildFailure('output-inventory-source-unreadable', 'output inventory could not read package public assets', error instanceof Error ? error.stack ?? error.message : String(error));
+    }
+    const html = expectedHtml(artifact);
+    const exact = new Set([
+        ...html,
+        ...staticPublic,
+        ...GENERATED_FILES,
+        ...PAGEFIND_RUNTIME,
+        ...snapshotOutput(root, workspace),
+        ...wasmOutput(root, workspace),
+    ]);
+    const pagefind = pagefindFiles(root, actual);
+    const unexpected = [];
+    const altered = [];
+    for (const file of actual) {
+        const path = join(root, ...file.split('/'));
+        if (!lstatSync(path).isFile()) {
+            unexpected.push(file);
+            continue;
+        }
+        if (exact.has(file) || pagefind.has(file) || /^_astro\/[A-Za-z0-9._-]*[.-][A-Za-z0-9_-]{8,}\.(?:css|js)$/.test(file))
+            continue;
+        unexpected.push(file);
+    }
+    for (const file of staticPublic) {
+        if (!actual.includes(file))
+            continue;
+        const built = readFileSync(join(root, ...file.split('/')));
+        const source = readFileSync(join(PUBLIC, ...file.split('/')));
+        if (!built.equals(source))
+            altered.push(file);
+    }
+    const expected = new Set([...exact, ...pagefind]);
+    const actualSet = new Set(actual);
+    const missing = [...expected].filter((file) => !actualSet.has(file));
+    const uniqueMissing = [...new Set(missing)].sort();
+    if (unexpected.length > 0 || uniqueMissing.length > 0 || altered.length > 0) {
+        throw new BuildFailure('output-inventory-mismatch', 'output inventory mismatch: ' + unexpected.length + ' unexpected, ' + uniqueMissing.length +
+            ' missing, ' + altered.length + ' altered', JSON.stringify({ unexpected: unexpected.sort(), missing: uniqueMissing, altered: altered.sort() }));
+    }
+    return actual.length;
+}
+/**
+ * This repository's own build may print private detail. The packaged binary
+ * imports only assertOutputInventory and routes its BuildFailure message to the
+ * public stream while the detail goes to the private build report.
+ */
+function main() {
+    try {
+        console.log('output inventory ok: ' + assertOutputInventory(DIST, loadArtifact()) + ' files');
+        return 0;
+    }
+    catch (error) {
+        console.error(error instanceof BuildFailure ? error.detail : error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+}
+if (process.argv[1] === fileURLToPath(import.meta.url))
+    process.exit(main());

package/scripts/write-report.js

@@ -0,0 +1,351 @@
+/**
+ * The build's own diagnostic, written where `git` cannot commit it.
+ *
+ * A build drops files silently today — a slug collision, a filename that
+ * slugifies to nothing, an extension that is not `.md` — and the only surface
+ * that could say so is a stream this tool now forbids from carrying a filename.
+ * So the names go to a file, the counts go to the stream, and this module owns
+ * the split.
+ *
+ * ## The destination, and the one question that decides it
+ *
+ * `<git-dir>/publish-report/content-report.json`, resolved as
+ * `git rev-parse --git-path publish-report/content-report.json` against the
+ * directory the command was invoked in.
+ *
+ * Nothing under the git directory can enter the index by any command, so the
+ * "the report got committed" vector is closed structurally rather than by a
+ * rule anyone has to remember. Measured on git 2.55.0.windows.3, in a throwaway
+ * repository with no `.gitignore` at all: `git add -A` staged the note alone,
+ * `git add -f <the report>` exited 0 as a silent no-op with `git ls-files`
+ * unchanged, `git check-ignore -v` exited 1 reporting **no rule** — there is no
+ * pattern to credit — and `git clean -xfd` left the file in place. That last one
+ * is not incidental: `git clean -xfd` is what a user runs after a failed build,
+ * which is the moment the diagnostic is worth most, and a self-ignoring
+ * directory in the worktree does not survive it.
+ *
+ * The tool asks exactly one question, and every host can answer it definitively:
+ * **is there a git directory here?** There is deliberately no second question,
+ * and in particular no question about who can read the repository — a rule with
+ * no input about the reader cannot be wrong about the reader. A private
+ * repository gets the identical path and the identical contents, which trades a
+ * convenience a private-repository user could safely have for one code path
+ * exercised on every run instead of two of which one never is.
+ *
+ * The directory segment is `publish-report/`, and the neutrality is deliberate:
+ * this tool runs on a stranger's notes repository, and a directory carrying this
+ * project's name inside a user's own `.git/` is single-owner residue. The
+ * segment describes what is in the directory and is legible to someone who finds
+ * it without knowing what wrote it.
+ *
+ * ## Resolved before the chdir, and not with `--path-format=absolute`
+ *
+ * `bin/anc.mjs` changes the working directory to the package
+ * root partway through a build, so the destination is computed from the
+ * invocation cwd beside the other two directories and never after. Measured,
+ * `git rev-parse --git-path` returns a **cwd-relative** path in the ordinary
+ * case — `.git/publish-report/…` at a repository root, `../../.git/…` two levels
+ * down — so a path resolved after the chdir lands inside the installed package
+ * under `node_modules`.
+ *
+ * `path.resolve` on plain `--git-path` rather than `--path-format=absolute`:
+ * both work, the resolve form has no git version floor, and `rev-parse`
+ * **echoes unknown flags instead of failing** — measured, `git rev-parse
+ * --bogus-flag --git-path x` exits 0 and prints `--bogus-flag` first with
+ * `.git/x` second — so a version sniff on a flag silently returns garbage as a
+ * path. The last line is the answer.
+ *
+ * Measured correct at a repository root, two directories down, in a linked
+ * worktree, under `--separate-git-dir`, in a bare repository, in a repository
+ * with no commits, in a nested repository, and in a submodule.
+ */
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+export const REPORT_SCHEMA_VERSION = 1;
+/**
+ * Where a reader would look for a finding: by file, then down the file.
+ *
+ * Exported because the producer sorts its own findings before handing them over
+ * and this module sorts them again on the way to disk — and two copies of one
+ * comparator is one edit away from two different orders. `line` is compared
+ * numerically: as a string, 10 sorts before 9.
+ */
+export function bySourceThenLine(a, b) {
+    if (a.source !== b.source)
+        return a.source < b.source ? -1 : 1;
+    return a.line - b.line;
+}
+/**
+ * An error whose message was composed under the disclosure rule, so the caller
+ * may print it.
+ *
+ * The boundary in `bin/anc.mjs` prints `error.message` for
+ * every throw in the process, which is how a `readdir` `ENOTDIR` — a string
+ * nobody here composed, with an absolute path already inside it — would reach a
+ * world-readable workflow log. Only errors this module vouches for are printed;
+ * everything else prints a fixed literal and puts its real message in the
+ * report's `failure.detail`.
+ *
+ * @param code A stable identifier from a closed set, safe on any stream.
+ * @param message The public half: literals, integers, and published slugs only.
+ * @param detail The private half, which goes to the report and nowhere else.
+ */
+export class BuildFailure extends Error {
+    code;
+    detail;
+    constructor(code, message, detail = message) {
+        super(message);
+        this.name = 'BuildFailure';
+        this.code = code;
+        this.detail = detail;
+    }
+}
+/**
+ * Error names whose messages are composed under the disclosure rule.
+ *
+ * `ContentValidationError` earns its place rather than being grandfathered in:
+ * its message is a source literal for the artifact, `entries[N]` coordinates,
+ * a rule name from `schema.ts`'s own table, and the slug of an entry — which is
+ * a *published* route the build was about to serve, not the name of a file the
+ * build withheld. Its `source` argument used to be the resolved content
+ * directory, and that is the one part of it that changed.
+ *
+ * Matched by name rather than by `instanceof` so this module imports nothing
+ * from `src/`: `bin/` loads every build step through `await import()`, and a
+ * static import here would pull the schema into the report writer's own module
+ * graph for a type test.
+ */
+const DISCLOSURE_CHECKED = new Set(['BuildFailure', 'ContentValidationError']);
+/** Whether this error's own message is safe to print on a stream. */
+export function isDisclosureChecked(error) {
+    return error instanceof Error && DISCLOSURE_CHECKED.has(error.name);
+}
+/**
+ * The report's `failure` for a thrown error: a stable code for the stream's
+ * sake, and everything else for the file's.
+ */
+export function failureFor(error) {
+    if (error instanceof BuildFailure)
+        return { code: error.code, detail: error.detail };
+    if (error instanceof Error) {
+        return {
+            code: error.name === 'ContentValidationError' ? 'content-contract-violation' : 'unexpected-error',
+            detail: error.stack ?? error.message,
+        };
+    }
+    return { code: 'unexpected-error', detail: String(error) };
+}
+const GENERATOR = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+/**
+ * The line a build prints instead of the report's path.
+ *
+ * A path, printed, would carry the user's own directory onto a public log. This
+ * is a command instead: one literal, byte-identical on every machine, that the
+ * user runs to get their own path — and it is correct from any subdirectory, in
+ * a linked worktree, in a submodule, and under `--separate-git-dir` alike,
+ * because it asks the same question of git that this module asked.
+ */
+const POINTER = 'report: cat "$(git rev-parse --git-path publish-report/content-report.json)"';
+/** The same line where there is no git directory to ask. Also a fixed literal. */
+const POINTER_NO_GIT = 'report: no git directory here; written under the user state directory, publish-report/<key>/';
+/**
+ * Where a user's own state lives, for the case where there is no repository.
+ *
+ * Never `os.tmpdir()`: on Linux that is world-readable `/tmp`. Outside the
+ * worktree either way, so a later `git init` followed by `git add -A` cannot
+ * reach a report an earlier run wrote — the hazard any in-worktree fallback
+ * carries and cannot close, since the earlier run had no repository to consult.
+ *
+ * `||` rather than `??`, which is not a style choice and has a measured failure
+ * behind it: `??` treats an **empty** environment variable as a value, so
+ * `XDG_STATE_HOME=` — the ordinary way a shell unsets one for a single command —
+ * yields `''`, and `join('', 'publish-report', …)` is a *relative* path that
+ * `mkdirSync` then creates inside the invocation directory. That is the report
+ * landing in the user's worktree, one `git init && git add -A` from being
+ * committed, which is precisely the hazard this destination exists to close.
+ * `src/lib/artifact-source.ts` documents `||` for the identical reason.
+ */
+function stateDirectory() {
+    if (process.platform === 'win32') {
+        return process.env['LOCALAPPDATA'] || join(homedir(), 'AppData', 'Local');
+    }
+    return process.env['XDG_STATE_HOME'] || join(homedir(), '.local', 'state');
+}
+/** Soft cap and age bound for reports that have no git directory to own them. */
+export const STATE_REPORT_MAX_PROJECTS = 128;
+export const STATE_REPORT_MAX_AGE_MS = 90 * 24 * 60 * 60 * 1000;
+const STATE_KEY = /^[a-f0-9]{16}$/;
+/**
+ * Remove old no-git reports without following or touching unfamiliar names.
+ *
+ * Only this tool's 16-hex project directories are candidates. The current key
+ * is retained even when its previous report is old; one slot is reserved for it
+ * before the next write, so an ordinary run leaves at most 128 projects. Races
+ * between several new projects may exceed the soft cap briefly and converge on
+ * the next run. Cleanup is best-effort: inability to delete history must never
+ * replace the report for the build in progress.
+ */
+export function pruneStateReports(root, currentKey, now = Date.now()) {
+    let entries;
+    try {
+        entries = readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    const candidates = [];
+    for (const entry of entries) {
+        if (entry.name === currentKey || !STATE_KEY.test(entry.name) || !entry.isDirectory())
+            continue;
+        const directory = join(root, entry.name);
+        let modified;
+        try {
+            modified = statSync(join(directory, 'content-report.json')).mtimeMs;
+        }
+        catch {
+            try {
+                modified = statSync(directory).mtimeMs;
+            }
+            catch {
+                continue;
+            }
+        }
+        candidates.push({ directory, modified });
+    }
+    const remove = (directory) => {
+        try {
+            rmSync(directory, { recursive: true, force: true });
+        }
+        catch {
+            // Best-effort retention only; the current report still has to be written.
+        }
+    };
+    const retained = candidates.filter(({ directory, modified }) => {
+        if (now - modified <= STATE_REPORT_MAX_AGE_MS)
+            return true;
+        remove(directory);
+        return false;
+    });
+    retained
+        .sort((left, right) => right.modified - left.modified)
+        .slice(Math.max(0, STATE_REPORT_MAX_PROJECTS - 1))
+        .forEach(({ directory }) => remove(directory));
+}
+/**
+ * The report's path for this invocation, and whether git answered.
+ *
+ * `spawnSync` surfaces a missing binary as `error.code === 'ENOENT'` with
+ * `status === null`, and `git rev-parse` outside a repository exits 128. Both
+ * take the same branch, because the conclusion is the same: there is no index,
+ * so no path in the worktree can be staged.
+ */
+function destinationFor(userDirectory) {
+    const probe = spawnSync('git', ['rev-parse', '--git-path', 'publish-report/content-report.json'], {
+        cwd: userDirectory,
+        encoding: 'utf8',
+    });
+    const answer = probe.status === 0 ? probe.stdout.trim().split('\n').at(-1) : undefined;
+    if (answer !== undefined && answer !== '') {
+        return { path: resolve(userDirectory, answer), hasGitDirectory: true };
+    }
+    // A filesystem key, not a disclosure: it exists so two projects do not
+    // overwrite each other's report. It names the user's own directory on the
+    // user's own machine and is never interpolated into a stream.
+    const key = createHash('sha256').update(realpath(userDirectory)).digest('hex').slice(0, 16);
+    const root = join(stateDirectory(), 'publish-report');
+    pruneStateReports(root, key);
+    return {
+        path: join(root, key, 'content-report.json'),
+        hasGitDirectory: false,
+    };
+}
+function realpath(directory) {
+    try {
+        return realpathSync(directory);
+    }
+    catch {
+        return directory;
+    }
+}
+/**
+ * Open the report **before discovery starts**, and write the stub immediately.
+ *
+ * The ordering is the whole point, and it is why this is opened rather than
+ * written at the end: the diagnostic is most needed on the run that failed, and
+ * a report written only after validation cannot exist on the run that failed
+ * validation — which is the likeliest throw in the whole binary. Measured
+ * before this existed: a note whose body carried an absolute path exited 1 with
+ * **nothing** written anywhere.
+ *
+ * `status: "aborted"` is the only value that is true at that moment, and
+ * writing it first is what makes "I stopped before I could look" a state a
+ * reader can observe rather than an absence they must interpret.
+ *
+ * A successful run needs no third write: the stub is superseded by
+ * {@link OpenReport.discovered}, which already leaves `failure: null`.
+ */
+export function openReport(userDirectory) {
+    const { path, hasGitDirectory } = destinationFor(userDirectory);
+    const report = {
+        version: REPORT_SCHEMA_VERSION,
+        generator: GENERATOR,
+        status: 'aborted',
+        counts: { discovered: 0, published: 0, dropped: 0 },
+        dropped: [],
+        links: [],
+        failure: null,
+    };
+    const flush = () => {
+        // 0700 where the tool chose the directory. On Windows Node's mode argument
+        // is inert and the directory reports the default — accepted, because that
+        // path is inside the user's own profile directory and the vector this
+        // destination closes is git, not local ACLs.
+        mkdirSync(dirname(path), hasGitDirectory ? { recursive: true } : { recursive: true, mode: 0o700 });
+        writeFileSync(path, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+    };
+    flush();
+    return {
+        destination: path,
+        pointer: hasGitDirectory ? POINTER : POINTER_NO_GIT,
+        get summary() {
+            // Three integers and a source literal on the ordinary path. On a run that
+            // stopped before discovery finished the same three integers are all zero,
+            // and printing them unqualified would say "your directory held nothing" —
+            // indistinguishable from an empty content directory, and the opposite of
+            // what `status: "aborted"` exists to record. So the aborted run gets its
+            // own literal instead, and the counts are simply not claimed.
+            if (report.status === 'aborted')
+                return 'content: discovery did not finish';
+            const { discovered, published, dropped } = report.counts;
+            // Per-reason counts after the total: still integers and literals of the
+            // closed {@link DropReason} set, so the line stays rename-invariant, and a
+            // collision or an exclusion is visible on the stream without a name.
+            const byReason = new Map();
+            for (const row of report.dropped)
+                byReason.set(row.reason, (byReason.get(row.reason) ?? 0) + 1);
+            const reasons = [...byReason]
+                .sort(([a], [b]) => (a < b ? -1 : 1))
+                .map(([reason, count]) => `${count} ${reason}`);
+            return (`content: ${discovered} discovered, ${published} published, ${dropped} dropped` +
+                (reasons.length === 0 ? '' : ` (${reasons.join(', ')})`));
+        },
+        discovered(counts, dropped, links) {
+            report.status = 'complete';
+            report.counts = counts;
+            report.dropped = [...dropped].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+            // Sorted where a reader would look, and left alone when the caller has
+            // nothing yet — link resolution is a second step, and a caller recording
+            // discovery first must not have that read as "no findings".
+            if (links !== undefined)
+                report.links = [...links].sort(bySourceThenLine);
+            flush();
+        },
+        failed(failure) {
+            report.failure = failure;
+            flush();
+        },
+    };
+}