@wxxb789/anc 0.0.1

package/scripts/preview-site.js

@@ -0,0 +1,364 @@
+/**
+ * `anc preview` — serve a built site on loopback.
+ *
+ * A user who has run `build` has a directory of HTML and no way to look at it.
+ * Opening `dist/index.html` with `file://` does not work: every page links
+ * `/notes/x/`, a root-relative path that under `file://` resolves to the
+ * filesystem root, and Pagefind fetches its index over HTTP. A server is the
+ * only way to read one's own site before publishing it.
+ *
+ * ## Why a subcommand at all, when `astro preview` exists
+ *
+ * Because it is not there. `package.json` has an `astro preview` script and that
+ * serves *this repository's* build; a stranger has this package in their
+ * `node_modules` and their own `dist/`. Measured, with the real tarball from
+ * `scripts/compile-package.ts` installed three ways:
+ *
+ * | Install | `node_modules/.bin/` | `astro preview` |
+ * | --- | --- | --- |
+ * | `npm install <tarball>` | `astro` present, hoisted | works |
+ * | `pnpm add <tarball>` | `anc`, `esbuild`, `vite`, `yaml` | **`node_modules/astro` does not exist** |
+ * | `npx <tarball> build` | nothing installed locally | nothing to run |
+ *
+ * So "run `astro preview`" is advice that holds for one of three install paths,
+ * and the one it holds for holds by accident — npm's flat hoisting, not a
+ * promise this package makes. The user always has the binary they just typed;
+ * that is the only entry point this tool can rely on.
+ *
+ * ## Astro's `preview()` rather than a hand-written `node:http`
+ *
+ * `import('astro')` already resolves from the installed package — measured from
+ * inside `node_modules/anc` under the pnpm layout, where the
+ * *binary* is absent but the *module* resolves fine, because it is this
+ * package's own dependency. It is an existing dependency doing a job it already
+ * does, which beats forty lines of MIME table and traversal guard that would
+ * duplicate what `tests/rendered-page.test.ts` already has for its own purposes.
+ *
+ * What it gives, all executed against a `dist/` outside the package:
+ *
+ * - `outDir` is served and `root` is not. `package.json`, `astro.config.mjs`,
+ *   `tsconfig.json`, and `public/_headers` all 404 while sitting under the
+ *   `root` that was passed in. So pointing the server at the user's build cannot
+ *   serve this package's files.
+ * - Traversal is refused: `/../secret.md`, `/%2e%2e/secret.md`, `/....//secret.md`,
+ *   `/..\secret.md`, and `/../../<sibling>/secret.md` are 404 with a canary file
+ *   present at each target, and `/..%2fsecret.md` is a 500 — Node's
+ *   `fileURLToPath` throws on the encoded separator inside Astro's preview
+ *   middleware before any file is read. No path escapes in any of the six, but
+ *   the 500's body carries the throwing frame, which is a path inside this
+ *   package's `node_modules`. That reaches an HTTP client rather than a stream,
+ *   so this repository's disclosure rule does not govern it, and the server is
+ *   bound to loopback with Vite refusing a foreign `Host:` — so the audience for
+ *   it is a process already running as the user. Recorded rather than fixed:
+ *   suppressing it means owning Astro's error middleware.
+ * - `trailingSlash: 'always'` is honoured — `/notes/x` 404s, `/notes/x/` serves.
+ * - A `Host:` header of `evil.example.com` is refused with 403 while
+ *   `localhost`, `127.0.0.1`, and any `*.localhost` are served. That is Vite's
+ *   DNS-rebinding guard, and it is a real protection a hand-written server would
+ *   not have had unless someone remembered to write it.
+ * - A taken port moves to the next free one rather than throwing.
+ * - It does **not** daemonize when called as a function. The `astro preview` CLI
+ *   does — it printed `Preview server already running (pid 26248)` and outlived
+ *   its parent — but the API's `stop()` closes the port in this process, so the
+ *   subcommand runs in the foreground and ends with Ctrl-C, which is what a
+ *   preview should do.
+ *
+ * One thing it does not give, recorded so nobody reads more into a passing
+ * preview than it says: **no `_headers`.** The built site ships a CSP and five
+ * other security headers in that file, Cloudflare Pages applies them, and this
+ * server sends none of them. So a preview cannot prove the deployed site's CSP
+ * admits its own scripts — `tests/rendered-page.test.ts` covers that by serving
+ * `dist/` itself with `public/_headers` parsed and applied, which is why that
+ * file has its own server and this one does not reuse it. A preview shows the
+ * content; the gate proves the headers.
+ *
+ * ## The refusal, which is the part that is not convenience
+ *
+ * `preview()` serves whatever directory it is given, and a directory of notes is
+ * a directory. Measured, pointed at one holding `.env` and `private/salary.md`:
+ *
+ *     /.env               -> 200   SECRET=…
+ *     /private/salary.md  -> 200   the note's contents
+ *     /index.html         -> 404
+ *
+ * Note the third line, which is the sharp part: the directory is *obviously* not
+ * a build — it has no index — and every file in it is served anyway. So `--dist .`
+ * in a notes repository publishes the notes **and** the dotfiles on a port, which
+ * for a tool whose entire premise is that excluded notes never ship is the worst
+ * thing it could do.
+ *
+ * So the directory must carry exactly one regular `data/site.<sha256>.sqlite`,
+ * matching SQLite magic, application ID, the reader's exact version, and the
+ * digest in its own filename.
+ *
+ * **That file and not `index.html`, because the marker has to be something only
+ * this tool writes.** An `index.html` is the most ordinary file on earth — a
+ * user may plausibly have one lying around in a notes directory, a downloaded
+ * page, or any other static site's output, and every one of those would satisfy
+ * a guard written against it while being no build of ours. A digest-named
+ * snapshot with ANC's own `application_id` is this tool's own projection of the
+ * corpus and nothing else produces it. The guard is only as good as the marker's
+ * exclusivity.
+ *
+ * **A matching filename is not enough; the bytes are checked.** A hand-made
+ * `data/site.<64hex>.sqlite` still has to carry the SQLite header, the format
+ * constants, and a SHA-256 equal to the digest in its name. That refuses the
+ * ordinary accident (`--dist .`, a typo, a stale path, a truncated copy) without
+ * turning recognition into a full correctness proof.
+ *
+ * It is a marker of "this tool built this", not a validity check — a
+ * schema-valid snapshot with wrong content still previews. What it excludes is
+ * the *category* error of aiming the server at a directory that was never a
+ * build output.
+ *
+ * **Checked before anything binds.** `resolveArtifactDirectory` throws and
+ * `startPreview` is the only thing that opens a socket; the binary calls them in
+ * that order. A server that starts and then refuses has already opened the port.
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { DatabaseSync } from "../src/lib/sqlite.js";
+import { SNAPSHOT_APPLICATION_ID, SNAPSHOT_DIRECTORY, SNAPSHOT_FILE_PATTERN, SNAPSHOT_USER_VERSION, } from "../src/lib/snapshot.js";
+import { BuildFailure } from "./write-report.js";
+import { declaresWal, journalSidecar } from "./snapshot-rows.js";
+/** The SQLite file header every valid snapshot starts with. */
+const SQLITE_MAGIC = Buffer.from('SQLite format 3\0', 'latin1');
+/**
+ * Astro's default preview port, and deliberately the same number.
+ *
+ * A user who has previewed an Astro site knows this port; a user who has not
+ * reads it from the line the command prints. Choosing a different one would buy
+ * nothing and cost the recognition.
+ */
+export const DEFAULT_PREVIEW_PORT = 4321;
+/**
+ * Find and validate the one snapshot in a built output.
+ *
+ * @throws {BuildFailure} when the directory has no snapshot, more than one, a
+ *   member whose digest does not match its bytes, or a file that is not ANC's
+ *   SQLite format.
+ */
+function resolveSnapshot(directory) {
+    const dataDirectory = resolve(directory, SNAPSHOT_DIRECTORY);
+    let candidates = [];
+    try {
+        candidates = existsSync(dataDirectory)
+            ? readdirSync(dataDirectory).filter((name) => SNAPSHOT_FILE_PATTERN.test(name))
+            : [];
+    }
+    catch {
+        candidates = [];
+    }
+    if (candidates.length !== 1) {
+        throw new BuildFailure('preview-directory-not-an-artifact', 'not a built site: the directory named by --dist does not carry exactly one ' +
+            'data/site.<sha256>.sqlite snapshot, so it was not produced by this tool. ' +
+            'Refusing to serve it — a directory of notes served on a port publishes every ' +
+            'file in it. Name the build output directory instead; the default is `dist`.', `${dataDirectory}: ${candidates.length} snapshot candidate(s)`);
+    }
+    const name = candidates[0];
+    const path = resolve(dataDirectory, name);
+    if (!statSync(path).isFile()) {
+        throw new BuildFailure('preview-directory-not-an-artifact', 'not a built site: the snapshot candidate is not a regular file.', path);
+    }
+    const match = SNAPSHOT_FILE_PATTERN.exec(name);
+    const expected = match[1];
+    const bytes = readFileSync(path);
+    if (bytes.length < 100 || !bytes.subarray(0, SQLITE_MAGIC.length).equals(SQLITE_MAGIC)) {
+        throw new BuildFailure('preview-snapshot-invalid', 'the preview snapshot is not a SQLite database.', `${path}: missing SQLite header`);
+    }
+    if (createHash('sha256').update(bytes).digest('hex') !== expected) {
+        throw new BuildFailure('preview-snapshot-digest', 'the preview snapshot bytes do not match the digest in their filename.', path);
+    }
+    // Opening is not free of side effects when SQLite sees journal work to do:
+    // measured, a `-wal` sibling makes the read-only open recover and write a
+    // `-shm` file into the directory being served. A built output carries none of
+    // these, so a WAL header or a sidecar is a wrong candidate and is refused
+    // before the driver touches it.
+    if (declaresWal(bytes)) {
+        throw new BuildFailure('preview-snapshot-format', 'the preview snapshot is not a snapshot this reader accepts.', `${path}: WAL format`);
+    }
+    const sidecar = journalSidecar(path);
+    if (sidecar !== undefined) {
+        throw new BuildFailure('preview-snapshot-format', 'the preview snapshot is not a snapshot this reader accepts.', `${path}: journal sidecar ${sidecar}`);
+    }
+    let database;
+    try {
+        database = new DatabaseSync(path, { readOnly: true });
+    }
+    catch (error) {
+        throw new BuildFailure('preview-snapshot-unreadable', 'the preview snapshot could not be opened.', `${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    try {
+        const applicationId = database.prepare('PRAGMA application_id').get()
+            .application_id;
+        const userVersion = database.prepare('PRAGMA user_version').get()
+            .user_version;
+        if (applicationId !== SNAPSHOT_APPLICATION_ID || userVersion !== SNAPSHOT_USER_VERSION) {
+            throw new BuildFailure('preview-snapshot-format', 'the preview snapshot is not a snapshot this reader accepts.', `${path}: application_id=${applicationId}, user_version=${userVersion}`);
+        }
+    }
+    catch (error) {
+        // `node:sqlite` opens a file whose header is valid and whose pages are not
+        // lazily, so a corrupt snapshot fails here rather than at the constructor.
+        // A `BuildFailure` is the format refusal above and must pass through.
+        if (error instanceof BuildFailure)
+            throw error;
+        throw new BuildFailure('preview-snapshot-unreadable', 'the preview snapshot could not be read.', `${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        database.close();
+    }
+    return path;
+}
+/**
+ * Check a directory is one this tool built, and return its absolute path.
+ *
+ * Exported for the gates, which need to assert the refusal without standing up
+ * a server. The path is returned rather than the caller re-resolving it, so the
+ * thing checked and the thing served cannot drift apart.
+ */
+export function resolveArtifactDirectory(directory, from) {
+    const resolved = resolve(from, directory);
+    if (!existsSync(resolved)) {
+        throw new BuildFailure('preview-directory-not-found', 'preview directory not found: the directory named by --dist does not exist. ' +
+            'Run the build first — its default output directory is `dist`.', resolved);
+    }
+    resolveSnapshot(resolved);
+    if (!existsSync(resolve(resolved, 'index.html'))) {
+        // The path is not in the message. A user who typed `--dist clients/acme` is
+        // looking at the command they typed, and the stream this reaches is one a
+        // workflow log inherits — the same rule `bin/anc.mjs`
+        // applies to every argv token it declines to echo.
+        throw new BuildFailure('preview-directory-not-an-artifact', 'not a built site: the directory named by --dist has no entry page and no ' +
+            'data/site.<sha256>.sqlite snapshot, so it was not produced by this tool. ' +
+            'Refusing to serve it. Name the build output directory instead; the default is `dist`.', resolved);
+    }
+    return resolved;
+}
+/**
+ * Serve a built site until the process is interrupted.
+ *
+ * Resolves when the server is listening, and the returned handle is what a gate
+ * uses to make requests and shut down. The binary never calls `stop()` — it
+ * hands the process to the server and the user ends it with Ctrl-C.
+ *
+ * `host` is `127.0.0.1` and is not configurable. Every other choice publishes a
+ * user's unpublished-by-default site to their network, and the flag that would
+ * do it is a flag someone eventually passes. Astro's own default binds
+ * `localhost`, which on this host resolves to `::1` — measured — and a literal
+ * `127.0.0.1` is the same protection without depending on what a name resolves
+ * to.
+ */
+export async function startPreview(artifactDirectory, port, packageRoot) {
+    // Dynamically imported, matching how `bin/anc.mjs` loads
+    // every build step: a `preview` run must not pay for Astro's module graph
+    // being resolved when the user typed `build`, and vice versa.
+    //
+    // **Through `import.meta.resolve` rather than as a bare specifier**, and the
+    // reason is measured rather than stylistic. Astro's own Vite config aliases
+    // `/^astro$/` to `astro/types/public/index.js` — `create-vite.js:216-220`,
+    // read at astro 7.1.6 — so that `import { Type } from 'astro'` works in user
+    // code. `vitest.config.ts` reuses that exact config through `getViteConfig`,
+    // so under the test suite a bare `import('astro')` resolves to the *types*
+    // module: measured, `Object.keys()` is empty and `preview` is `undefined`.
+    // The shipped binary is unaffected, which is the trap — the module works in
+    // production and cannot be tested, which is how a gate ends up asserting
+    // something other than what ships.
+    //
+    // `import.meta.resolve` is Node's own resolver and no bundler rewrites its
+    // result: measured under vitest, it returns the real `astro/dist/index.js`
+    // and `preview` is a function. `tests/packaging.test.ts:549` already reaches
+    // an Astro internal the same way for the same class of reason.
+    const { preview } = await import(__rewriteRelativeImportExtension(/* @vite-ignore */ import.meta.resolve('astro'), true));
+    const server = await preview({
+        // `root` is where `astro.config.mjs` lives — this package, never the user's
+        // directory, for the reason `bin/anc.mjs` documents at
+        // length for `build`. It contributes only the config; nothing under it is
+        // served, which is measured rather than assumed.
+        root: packageRoot,
+        outDir: artifactDirectory,
+        server: { port, host: '127.0.0.1' },
+        // Astro's own listening line names a port that may not be the one it got,
+        // and prints it before this function can compare. Silenced, and the caller
+        // prints the real one from `server.port`.
+        logLevel: 'silent',
+        vite: { logLevel: 'silent' },
+        // **Both loggers, because they are two loggers.** `logLevel` reaches
+        // Astro's; the preview server is a Vite server and Vite logs through its
+        // own, which `httpServerStart` uses for the port-in-use line. Measured with
+        // only the Astro one set: `anc preview --port 47411` on a
+        // held port printed `Port 47411 is in use, trying another one...` to stdout
+        // ahead of this module's line — and that number is an argv token, which is
+        // the class `parsePreviewArguments` refuses to echo forty lines below, on
+        // the same stream a workflow log inherits. With this line the identical run
+        // prints only the two lines the binary composes.
+    });
+    return { port: server.port, stop: () => server.stop() };
+}
+/**
+ * Parse `preview`'s options.
+ *
+ * Deliberately its own parser rather than an extension of `build`'s: the two
+ * share no flags, and a combined table would accept `--content` for a preview
+ * and `--dist` for a build. Unknown flags are refused for the reason
+ * `parseArguments` gives in `bin/anc.mjs` — a mistyped flag
+ * that is silently ignored produces a plausible result the user did not ask for
+ * — and, as there, the rejected token is never echoed.
+ */
+export function parsePreviewArguments(argv) {
+    let dist = 'dist';
+    let port = DEFAULT_PREVIEW_PORT;
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        const key = argument === '--dist' ? 'dist' : argument === '--port' ? 'port' : undefined;
+        if (key === undefined) {
+            throw new BuildFailure('unknown-option', 'unrecognised option for preview', argument);
+        }
+        const value = argv[index + 1];
+        if (value === undefined || value.startsWith('--')) {
+            // `argument` is one of this file's own two literals here, so printing it
+            // is printing a string this source declares.
+            throw new BuildFailure('missing-value', `${argument} needs a value`);
+        }
+        index += 1;
+        if (key === 'dist') {
+            dist = value;
+            continue;
+        }
+        // **The decimal spelling is required before any coercion.** `parseInt` was
+        // rejected first because it reads `4321abc` as 4321 — and `Number` alone has
+        // the same defect in other spellings, measured: `''`, `'  '`, and `'\n'` all
+        // become 0, `'0x10'` becomes 16, `'1e3'` becomes 1000, and `' 4321 '` becomes
+        // 4321. The empty string is the one that is not a curiosity: `--port "$PORT"`
+        // with `PORT` unset reaches here as `''`, survives the `startsWith('--')`
+        // guard above, and would bind an ephemeral port while the user believes they
+        // named one — a silently wrong result presented as success, which is the
+        // failure class this whole parser exists to prevent.
+        //
+        // So the shape is checked as text first, and only a string of digits is
+        // coerced. `Number.isInteger` then cannot fail, and is kept because a
+        // 20-digit input is integral text and not a port.
+        if (!/^\d+$/.test(value)) {
+            // The value is not echoed. A port is not itself sensitive, but this is the
+            // same stream, and the rule that a printed token must be one of this
+            // tool's own spellings does not admit exceptions for values that look
+            // harmless — `--port` is followed by whatever the shell expanded.
+            throw new BuildFailure('invalid-port', '--port must be a whole number between 0 and 65535', value);
+        }
+        const parsed = Number(value);
+        if (!Number.isInteger(parsed) || parsed > 65535) {
+            throw new BuildFailure('invalid-port', '--port must be a whole number between 0 and 65535', value);
+        }
+        port = parsed;
+    }
+    return { dist, port };
+}

package/scripts/publish-set-review.js

@@ -0,0 +1,157 @@
+/**
+ * A committed review of the exact public note set used by release builds.
+ *
+ * The ledger contains public slugs, never source paths or withheld names. Exact
+ * equality is deliberate: a note that is published, excluded, then re-included
+ * must become an addition again instead of inheriting stale authorization.
+ */
+import { spawnSync } from 'node:child_process';
+import { lstatSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { compareSlugs, isNoteSlug } from "../src/lib/route-path.js";
+import { BuildFailure } from "./write-report.js";
+export const PUBLISH_SET_REVIEW_FILE = '.publish-set.json';
+const REVIEW_VERSION = 1;
+const MAX_REVIEW_BYTES = 1_048_576;
+function canonicalSlugs(slugs) {
+    const unique = [...new Set(slugs)];
+    for (const slug of unique) {
+        if (!isNoteSlug(slug)) {
+            throw new BuildFailure('publish-set-review-invalid', 'publish-set review is invalid; run anc review again', 'computed publish set contains an invalid slug: ' + JSON.stringify(slug));
+        }
+    }
+    // Canonical slug order (code points), the same order the snapshot uses.
+    return unique.sort(compareSlugs);
+}
+function invalidReview(detail) {
+    throw new BuildFailure('publish-set-review-invalid', 'release blocked: .publish-set.json is invalid; run anc review again', detail);
+}
+function parseReview(text) {
+    if (Buffer.byteLength(text, 'utf8') > MAX_REVIEW_BYTES)
+        invalidReview('publish-set review exceeds 1 MiB');
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (error) {
+        invalidReview('publish-set review is not JSON: ' + String(error));
+    }
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        invalidReview('publish-set review must be an object');
+    }
+    const table = value;
+    const keys = Object.keys(table).sort();
+    if (keys.length !== 2 || keys[0] !== 'slugs' || keys[1] !== 'version') {
+        invalidReview('publish-set review must contain exactly version and slugs');
+    }
+    if (table['version'] !== REVIEW_VERSION)
+        invalidReview('publish-set review has an unsupported version');
+    if (!Array.isArray(table['slugs']))
+        invalidReview('publish-set review slugs must be an array');
+    const slugs = table['slugs'];
+    if (!slugs.every((slug) => typeof slug === 'string' && isNoteSlug(slug))) {
+        invalidReview('publish-set review contains an invalid slug');
+    }
+    const canonical = canonicalSlugs(slugs);
+    if (canonical.length !== slugs.length || canonical.some((slug, index) => slug !== slugs[index])) {
+        invalidReview('publish-set review slugs must be sorted and unique');
+    }
+    return { version: REVIEW_VERSION, slugs };
+}
+function git(directory, args) {
+    return spawnSync('git', args, { cwd: directory, encoding: 'utf8', windowsHide: true });
+}
+function gitDetail(command, result) {
+    return [
+        command,
+        'status=' + String(result.status),
+        result.error?.stack ?? '',
+        result.stdout,
+        result.stderr,
+    ].filter(Boolean).join('\n');
+}
+function assertGitRepository(directory) {
+    const result = git(directory, ['rev-parse', '--is-inside-work-tree']);
+    if (result.status !== 0 || result.stdout.trim() !== 'true') {
+        throw new BuildFailure('publish-set-review-needs-git', 'publish-set review requires a git repository so approval can be committed', gitDetail('git rev-parse --is-inside-work-tree', result));
+    }
+}
+function assertReviewNotIgnored(directory) {
+    const result = git(directory, ['check-ignore', '--quiet', '--', PUBLISH_SET_REVIEW_FILE]);
+    if (result.status === 0) {
+        throw new BuildFailure('publish-set-review-ignored', 'publish-set review is ignored by git; unignore .publish-set.json before reviewing', gitDetail('git check-ignore', result));
+    }
+    if (result.status !== 1) {
+        throw new BuildFailure('publish-set-review-needs-git', 'publish-set review could not verify git ignore rules', gitDetail('git check-ignore', result));
+    }
+}
+function reviewFileIsRegular(directory) {
+    try {
+        return lstatSync(join(directory, PUBLISH_SET_REVIEW_FILE)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function assertCommitted(directory) {
+    const tracked = git(directory, ['ls-files', '--error-unmatch', '--', PUBLISH_SET_REVIEW_FILE]);
+    const unstaged = git(directory, ['diff', '--quiet', '--', PUBLISH_SET_REVIEW_FILE]);
+    const staged = git(directory, ['diff', '--cached', '--quiet', '--', PUBLISH_SET_REVIEW_FILE]);
+    if (tracked.status !== 0 || unstaged.status !== 0 || staged.status !== 0) {
+        throw new BuildFailure('publish-set-review-uncommitted', 'release blocked: .publish-set.json must be committed and unchanged', [
+            gitDetail('git ls-files', tracked),
+            gitDetail('git diff', unstaged),
+            gitDetail('git diff --cached', staged),
+        ].join('\n'));
+    }
+}
+/** Write the current candidate set. A release still refuses it until committed. */
+export function writePublishSetReview(directory, slugs) {
+    assertGitRepository(directory);
+    assertReviewNotIgnored(directory);
+    const path = join(directory, PUBLISH_SET_REVIEW_FILE);
+    try {
+        const state = lstatSync(path);
+        if (!state.isFile())
+            invalidReview('publish-set review path is not a regular file');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const review = { version: REVIEW_VERSION, slugs: canonicalSlugs(slugs) };
+    writeFileSync(join(directory, PUBLISH_SET_REVIEW_FILE), JSON.stringify(review, null, 2) + '\n', 'utf8');
+    return review.slugs.length;
+}
+/** Require one committed ledger exactly equal to the computed public note set. */
+export function assertPublishSetReviewed(directory, slugs) {
+    assertGitRepository(directory);
+    if (!reviewFileIsRegular(directory)) {
+        try {
+            lstatSync(join(directory, PUBLISH_SET_REVIEW_FILE));
+            invalidReview('publish-set review path is not a regular file');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    let reviewText;
+    try {
+        reviewText = readFileSync(join(directory, PUBLISH_SET_REVIEW_FILE), 'utf8');
+    }
+    catch (error) {
+        throw new BuildFailure('publish-set-review-missing', 'release blocked: no reviewed publish set; run anc review and commit it', 'could not read ' + PUBLISH_SET_REVIEW_FILE + ': ' + String(error));
+    }
+    const reviewed = parseReview(reviewText).slugs;
+    const current = canonicalSlugs(slugs);
+    const reviewedSet = new Set(reviewed);
+    const currentSet = new Set(current);
+    const added = current.filter((slug) => !reviewedSet.has(slug));
+    const removed = reviewed.filter((slug) => !currentSet.has(slug));
+    if (added.length > 0 || removed.length > 0) {
+        throw new BuildFailure('publish-set-review-changed', 'release blocked: publish set changed (' + added.length + ' added, ' + removed.length +
+            ' removed); run anc review, inspect the diff, and commit it', JSON.stringify({ added, removed }));
+    }
+    assertCommitted(directory);
+}