@clossys/writer 0.3.2

package/dist/checker.d.ts

@@ -0,0 +1,159 @@
+/**
+ * `checkCopyRecord` — runs every entry in a `CopyRecord` through
+ * `@clossys/writer/voice`'s own `checkCopy`, against a single
+ * `VoiceRecord`, and reports the result. This is the one file in this
+ * package that imports `@clossys/writer/voice`: `types.ts` and
+ * `schema.ts` are pure, dependency-free data/validation, exactly like
+ * `voice`'s own `types.ts`/`schema.ts`; this file is where the two
+ * packages' machinery actually meet.
+ *
+ * FIVE AGENTS FINISHED A REPAIR ROUND ON THIS REPOSITORY AN HOUR BEFORE
+ * THIS FILE WAS WRITTEN, AND EVERY ONE OF THEM SHIPPED A FIRST DRAFT THAT
+ * REPRODUCED THE EXACT DEFECT IT WAS FIXING. The recurring shape was "a
+ * check that passes while asserting nothing" — `checkCopyRecord` IS a
+ * check, so this file is written against that failure mode directly, not
+ * as an afterthought:
+ *
+ *   1. NO SILENT NARROWING. If an entry is not run through `checkCopy`
+ *      for any reason, it is recorded in `report.skipped`, by id — never
+ *      folded silently into a "0 findings" result that looks identical
+ *      to "everything ran and was clean". `report.checkedCount` and
+ *      `report.skippedCount` are always populated (not just inferable
+ *      from array lengths), so a caller reading only those two numbers,
+ *      without inspecting either array, still cannot mistake one for the
+ *      other.
+ *   2. FAILS CLOSED. An invalid `CopyRecord`, an invalid `VoiceRecord`,
+ *      or a `CopyRecord` with zero entries are each treated as a
+ *      FAILURE — `report.complete` is `false` and `report.findings`
+ *      names the reason — never as a clean pass with nothing to check.
+ *      `checkCopyRecord` re-validates BOTH its arguments itself
+ *      (`validateCopyRecordShape` and, imported from `voice`,
+ *      `validateVoiceRecordShape`), even though both are typed inputs a
+ *      TypeScript caller "should" have already validated — because a
+ *      plain-JS caller, or a value that merely satisfies the type at
+ *      compile time without actually conforming at runtime, is exactly
+ *      the case a check that "passes while asserting nothing" would fail
+ *      to catch. This is a deliberate difference from `voice`'s own
+ *      `checkCopy`, which does NOT self-validate its `VoiceRecord`
+ *      argument (see that function's own doc comment) — this package
+ *      chooses the stricter behavior for its own entry point because it
+ *      is the thing this whole package's design brief was written to
+ *      distrust in itself.
+ *   3. `report.complete` MEANS "did this run check everything it could
+ *      have", never "did everything pass" — the same non-negotiable
+ *      distinction `voice`'s own `VoiceCheckReport.complete` draws. A
+ *      `CopyRecord` with real voice violations in it can still be
+ *      `complete: true` (every entry got checked; some of them failed);
+ *      a `CopyRecord` this function refused to check at all is always
+ *      `complete: false`, no matter how "clean" an empty `findings`
+ *      array might otherwise look.
+ *
+ * Pure, no I/O: `checkCopyRecord` never reads a file — that is
+ * `registry.ts`'s job — and never resolves a `factRef` against anything,
+ * for the same reason `voice`'s `checkCopy` does not: see
+ * `@clossys/writer/voice`'s README, "The `factRef` seam".
+ */
+import { type VoiceCheckReport, type VoiceCheckWaiver, type VoiceFinding, type VoiceRecord } from "./voice/index.js";
+import type { CopyEntryId, CopyRecord } from "./types.js";
+/** One entry `checkCopyRecord` did NOT run through `voice`'s `checkCopy` this run, and why. */
+export interface CopyEntrySkip {
+    entryId: CopyEntryId;
+    /**
+     * Human-readable reason. In practice always because the `CopyRecord` or
+     * `VoiceRecord` given to this call failed its own shape validation —
+     * see `report.findings` for the specific violation(s). An entry that
+     * passes `validateCopyRecordShape` (id well-formed and unique, `text`
+     * and `context` non-empty, every declared placeholder present) is
+     * always run, never skipped for a reason internal to the entry itself;
+     * `voice`'s own `checkCopy` has its own, separately-reported notion of
+     * an incomplete run (see `CopyEntryCheckResult.report.skipped`) for a
+     * dimension it could not evaluate against a structurally valid entry.
+     */
+    reason: string;
+}
+/** One entry `checkCopyRecord` DID run through `voice`'s `checkCopy`, and the resulting report. */
+export interface CopyEntryCheckResult {
+    entryId: CopyEntryId;
+    /**
+     * `voice`'s own `checkCopy` report for this entry's `text`, unmodified.
+     * Its own `.complete`/`.skipped` describe whether `checkCopy` itself
+     * could evaluate every dimension against this ONE entry — a separate
+     * question from whether `checkCopyRecord` ran this entry at all.
+     */
+    report: VoiceCheckReport;
+}
+/** One `VoiceFinding` from one entry's `checkCopy` run, flattened into `report.findings` and tagged with the entry it came from. */
+export interface CopyRecordFinding extends VoiceFinding {
+    /** The entry this finding is about, or `undefined` for a record-level finding not specific to any one entry (an invalid `CopyRecord`/`VoiceRecord`, or zero entries). */
+    entryId?: CopyEntryId;
+}
+/** A `CopyRecordFinding` that was waived, with the waiver that covered it — mirrors `voice`'s `WaivedVoiceFinding`. */
+export interface CopyRecordWaivedFinding extends CopyRecordFinding {
+    waiver: VoiceCheckWaiver;
+}
+export interface CopyRecordCheckOptions {
+    /**
+     * Waivers applied uniformly to EVERY entry's `checkCopy` call — the
+     * same `VoiceCheckWaiver[]` shape `voice`'s own `checkCopy` accepts.
+     * There is no per-entry waiver targeting in this version: a waiver
+     * scoped to one entry's finding still matches the same `rule`+`path`
+     * pair in every other entry's report too. A caller that genuinely needs
+     * per-entry waiver scoping can call `voice`'s `checkCopy` directly,
+     * per entry, with its own waiver list — this package's own `checker.ts`
+     * does exactly that under the hood.
+     */
+    waivers?: VoiceCheckWaiver[];
+}
+export interface CopyRecordCheckReport {
+    recordId: string;
+    /** Every entry actually run through `checkCopy`, with its own `VoiceCheckReport`. */
+    checked: CopyEntryCheckResult[];
+    /** Every entry NOT run, by id, and why. Empty does not by itself mean "nothing was skipped for a bad reason" — see `report.complete`, which is `false` whenever this run could not be trusted enough to check every entry, including the cases where this is legitimately `[]` (zero entries; see `checkedCount`). */
+    skipped: CopyEntrySkip[];
+    /** `checked.length`, restated as its own field so a caller does not have to inspect the array to get this number — see this file's top-of-file "no silent narrowing" note. */
+    checkedCount: number;
+    /** `skipped.length`, restated as its own field for the same reason as `checkedCount`. */
+    skippedCount: number;
+    /**
+     * Every non-waived finding this run produced, flattened across every
+     * checked entry AND any record-level problem (an invalid `CopyRecord`,
+     * an invalid `VoiceRecord`, or zero entries), each entry-sourced
+     * finding tagged with the `entryId` it came from. This is the one field
+     * a caller checking "is anything wrong" should read — it is populated
+     * in every failure case this function knows about, never left empty to
+     * imply a clean run when the run in fact could not be trusted (see
+     * `.complete`).
+     */
+    findings: CopyRecordFinding[];
+    /** Every finding covered by a waiver, across every checked entry, each with the waiver that covered it — mirrors `voice`'s `VoiceCheckReport.waived`. */
+    waived: CopyRecordWaivedFinding[];
+    /**
+     * `true` exactly when: the given `CopyRecord` was structurally valid,
+     * the given `VoiceRecord` was structurally valid, the record had at
+     * least one entry, and every entry was actually run (`skipped` is
+     * empty). `false` in every other case. Independent of `findings` —
+     * see this file's top-of-file note #3. Read this field, not an empty
+     * `findings` array, to decide whether a run can be trusted as "checked
+     * everything, found nothing".
+     */
+    complete: boolean;
+}
+/**
+ * Checks every entry in `record` against `voiceRecord`, via `voice`'s own
+ * `checkCopy`. See this file's top-of-file doc comment for the fail-
+ * closed behavior on an invalid `record`, an invalid `voiceRecord`, and a
+ * `record` with zero entries.
+ *
+ * Throws a plain `Error` (not a finding) for caller-input problems that
+ * are not this function's job to interpret as data: `record` or
+ * `voiceRecord` not an object at all. This mirrors `voice`'s own
+ * `checkCopy`, which treats a malformed call the same way — a hard
+ * upfront rejection, not a soft finding that could be mistaken for
+ * something the checker discovered about the record itself. A `record`
+ * or `voiceRecord` that IS an object but fails shape validation is,
+ * unlike a non-object, a real finding (`report.findings`), not a thrown
+ * error — see note #2 above for why this function validates both itself
+ * rather than trusting its own type signature.
+ */
+export declare function checkCopyRecord(record: CopyRecord, voiceRecord: VoiceRecord, options?: CopyRecordCheckOptions): CopyRecordCheckReport;
+//# sourceMappingURL=checker.d.ts.map

package/dist/checker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checker.d.ts","sourceRoot":"","sources":["../src/checker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,WAAW,EACjB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE1D,+FAA+F;AAC/F,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,WAAW,CAAC;IACrB;;;;;;;;;;OAUG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,mGAAmG;AACnG,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,WAAW,CAAC;IACrB;;;;;OAKG;IACH,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED,oIAAoI;AACpI,MAAM,WAAW,iBAAkB,SAAQ,YAAY;IACrD,yKAAyK;IACzK,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED,uHAAuH;AACvH,MAAM,WAAW,uBAAwB,SAAQ,iBAAiB;IAChE,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,OAAO,EAAE,oBAAoB,EAAE,CAAC;IAChC,sTAAsT;IACtT,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,8KAA8K;IAC9K,YAAY,EAAE,MAAM,CAAC;IACrB,yFAAyF;IACzF,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;;;OASG;IACH,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,yJAAyJ;IACzJ,MAAM,EAAE,uBAAuB,EAAE,CAAC;IAClC;;;;;;;;OAQG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB;AAyCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,UAAU,EAClB,WAAW,EAAE,WAAW,EACxB,OAAO,GAAE,sBAA2B,GACnC,qBAAqB,CAuEvB"}

package/dist/checker.js

@@ -0,0 +1,177 @@
+/**
+ * `checkCopyRecord` — runs every entry in a `CopyRecord` through
+ * `@clossys/writer/voice`'s own `checkCopy`, against a single
+ * `VoiceRecord`, and reports the result. This is the one file in this
+ * package that imports `@clossys/writer/voice`: `types.ts` and
+ * `schema.ts` are pure, dependency-free data/validation, exactly like
+ * `voice`'s own `types.ts`/`schema.ts`; this file is where the two
+ * packages' machinery actually meet.
+ *
+ * FIVE AGENTS FINISHED A REPAIR ROUND ON THIS REPOSITORY AN HOUR BEFORE
+ * THIS FILE WAS WRITTEN, AND EVERY ONE OF THEM SHIPPED A FIRST DRAFT THAT
+ * REPRODUCED THE EXACT DEFECT IT WAS FIXING. The recurring shape was "a
+ * check that passes while asserting nothing" — `checkCopyRecord` IS a
+ * check, so this file is written against that failure mode directly, not
+ * as an afterthought:
+ *
+ *   1. NO SILENT NARROWING. If an entry is not run through `checkCopy`
+ *      for any reason, it is recorded in `report.skipped`, by id — never
+ *      folded silently into a "0 findings" result that looks identical
+ *      to "everything ran and was clean". `report.checkedCount` and
+ *      `report.skippedCount` are always populated (not just inferable
+ *      from array lengths), so a caller reading only those two numbers,
+ *      without inspecting either array, still cannot mistake one for the
+ *      other.
+ *   2. FAILS CLOSED. An invalid `CopyRecord`, an invalid `VoiceRecord`,
+ *      or a `CopyRecord` with zero entries are each treated as a
+ *      FAILURE — `report.complete` is `false` and `report.findings`
+ *      names the reason — never as a clean pass with nothing to check.
+ *      `checkCopyRecord` re-validates BOTH its arguments itself
+ *      (`validateCopyRecordShape` and, imported from `voice`,
+ *      `validateVoiceRecordShape`), even though both are typed inputs a
+ *      TypeScript caller "should" have already validated — because a
+ *      plain-JS caller, or a value that merely satisfies the type at
+ *      compile time without actually conforming at runtime, is exactly
+ *      the case a check that "passes while asserting nothing" would fail
+ *      to catch. This is a deliberate difference from `voice`'s own
+ *      `checkCopy`, which does NOT self-validate its `VoiceRecord`
+ *      argument (see that function's own doc comment) — this package
+ *      chooses the stricter behavior for its own entry point because it
+ *      is the thing this whole package's design brief was written to
+ *      distrust in itself.
+ *   3. `report.complete` MEANS "did this run check everything it could
+ *      have", never "did everything pass" — the same non-negotiable
+ *      distinction `voice`'s own `VoiceCheckReport.complete` draws. A
+ *      `CopyRecord` with real voice violations in it can still be
+ *      `complete: true` (every entry got checked; some of them failed);
+ *      a `CopyRecord` this function refused to check at all is always
+ *      `complete: false`, no matter how "clean" an empty `findings`
+ *      array might otherwise look.
+ *
+ * Pure, no I/O: `checkCopyRecord` never reads a file — that is
+ * `registry.ts`'s job — and never resolves a `factRef` against anything,
+ * for the same reason `voice`'s `checkCopy` does not: see
+ * `@clossys/writer/voice`'s README, "The `factRef` seam".
+ */
+import { checkCopy, validateVoiceRecordShape, } from "./voice/index.js";
+import { validateCopyRecordShape } from "./schema.js";
+function recordLevelFailure(recordId, findings, skipped) {
+    return {
+        recordId,
+        checked: [],
+        skipped,
+        checkedCount: 0,
+        skippedCount: skipped.length,
+        findings,
+        waived: [],
+        complete: false,
+    };
+}
+/**
+ * Best-effort per-entry skip attribution for a `CopyRecord` whose own
+ * shape is invalid. `record.entries` is typed as `CopyEntry[]`, but the
+ * whole point of the branch that calls this is that the type cannot be
+ * trusted at runtime — so this reads defensively, using whatever id it
+ * can find and falling back to a positional label (`"$3"`, meaning index
+ * 3) for an entry too malformed to have a usable id at all. Never throws.
+ */
+function bestEffortSkipList(entriesValue, reason) {
+    if (!Array.isArray(entriesValue))
+        return [];
+    return entriesValue.map((entry, i) => {
+        const hasUsableId = typeof entry === "object" &&
+            entry !== null &&
+            !Array.isArray(entry) &&
+            typeof entry.id === "string" &&
+            entry.id.length > 0;
+        const entryId = hasUsableId ? entry.id : `$${i}`;
+        return { entryId, reason };
+    });
+}
+/**
+ * Checks every entry in `record` against `voiceRecord`, via `voice`'s own
+ * `checkCopy`. See this file's top-of-file doc comment for the fail-
+ * closed behavior on an invalid `record`, an invalid `voiceRecord`, and a
+ * `record` with zero entries.
+ *
+ * Throws a plain `Error` (not a finding) for caller-input problems that
+ * are not this function's job to interpret as data: `record` or
+ * `voiceRecord` not an object at all. This mirrors `voice`'s own
+ * `checkCopy`, which treats a malformed call the same way — a hard
+ * upfront rejection, not a soft finding that could be mistaken for
+ * something the checker discovered about the record itself. A `record`
+ * or `voiceRecord` that IS an object but fails shape validation is,
+ * unlike a non-object, a real finding (`report.findings`), not a thrown
+ * error — see note #2 above for why this function validates both itself
+ * rather than trusting its own type signature.
+ */
+export function checkCopyRecord(record, voiceRecord, options = {}) {
+    if (record === null || typeof record !== "object") {
+        throw new TypeError("checkCopyRecord: record must be a CopyRecord object");
+    }
+    if (voiceRecord === null || typeof voiceRecord !== "object") {
+        throw new TypeError("checkCopyRecord: voiceRecord must be a VoiceRecord object");
+    }
+    const recordIdForReport = isNonEmptyStringField(record, "id") ? record.id : "(unknown)";
+    // --- fail closed: the CopyRecord itself must be well-formed --------------
+    const recordShapeFindings = validateCopyRecordShape(record);
+    if (recordShapeFindings.length > 0) {
+        const findings = recordShapeFindings.map((f) => ({ ...f }));
+        const entriesValue = record.entries;
+        return recordLevelFailure(recordIdForReport, findings, bestEffortSkipList(entriesValue, "record-shape-invalid"));
+    }
+    // --- fail closed: the VoiceRecord itself must be well-formed --------------
+    // Unlike voice's own checkCopy, this function does not trust its typed
+    // input — see this file's top-of-file note #2 for why.
+    const voiceShapeFindings = validateVoiceRecordShape(voiceRecord);
+    if (voiceShapeFindings.length > 0) {
+        const findings = voiceShapeFindings.map((f) => ({ ...f }));
+        // record is now known well-formed (previous branch would have returned
+        // otherwise), so every entry has a real, unique id to attribute a skip to.
+        const skipped = record.entries.map((entry) => ({
+            entryId: entry.id,
+            reason: "voice-record-invalid",
+        }));
+        return recordLevelFailure(recordIdForReport, findings, skipped);
+    }
+    // --- fail closed: zero entries is nothing to check, not a clean pass -----
+    if (record.entries.length === 0) {
+        const findings = [
+            {
+                rule: "record:no-entries",
+                severity: "error",
+                message: `CopyRecord "${recordIdForReport}" has zero entries — there is nothing for checkCopyRecord to check.`,
+            },
+        ];
+        return recordLevelFailure(recordIdForReport, findings, []);
+    }
+    // --- the real work: run every entry through voice's checkCopy ------------
+    const checked = [];
+    const findings = [];
+    const waived = [];
+    for (const entry of record.entries) {
+        const entryReport = checkCopy(voiceRecord, entry.text, { waivers: options.waivers });
+        checked.push({ entryId: entry.id, report: entryReport });
+        for (const finding of entryReport.findings) {
+            findings.push({ ...finding, entryId: entry.id });
+        }
+        for (const w of entryReport.waived) {
+            waived.push({ ...w, entryId: entry.id });
+        }
+    }
+    return {
+        recordId: recordIdForReport,
+        checked,
+        skipped: [],
+        checkedCount: checked.length,
+        skippedCount: 0,
+        findings,
+        waived,
+        complete: true,
+    };
+}
+function isNonEmptyStringField(value, key) {
+    const v = value[key];
+    return typeof v === "string" && v.length > 0;
+}
+//# sourceMappingURL=checker.js.map

package/dist/checker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checker.js","sourceRoot":"","sources":["../src/checker.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+/**
+ * `writer-check` — the CLI for `checkCopyTraceability` — AND, in this same
+ * file and under this SAME `writer-check` bin, a subcommand
+ * (`writer-check addressability`, dispatched on `argv[0] === "addressability"`
+ * before any of the existing argument parsing below runs — see the bottom
+ * of this file), `checkAddressability`: is user-facing prose resolved from
+ * the copy registry by id, rather than typed inline? A stricter, DIFFERENT
+ * question from traceability — see `addressability.ts`'s top doc comment
+ * for the full split. Deliberately NOT merged into the default command's
+ * own exit code: traceability's own fixtures/tests are built entirely
+ * around bare literal assignments (a registered string, an unregistered
+ * one, a `copy-gate:ignore` marker, a `copy:<id>` citation) — exactly the
+ * shapes addressability treats as either a violation (an attribute/
+ * text-node literal) or an unclassifiable position (a bare assignment,
+ * position 3 — see `addressability.ts`), by design and on purpose.
+ * Combining the two into one number would make the default command's own
+ * "clean pass" fixtures structurally unwritable (a literal a
+ * registered-text match needs to exist for traceability to prove anything
+ * is exactly a literal addressability cannot confirm is safe) rather than
+ * genuinely complementary. A SEPARATE `bin` entry pointing at this same
+ * compiled file was rejected for the identical reason `@example/ui`
+ * never does that: this repository's own root `package.json` invokes every
+ * gate by its COMPILED PATH (`node packages/ui/dist/tokens/contrast-cli.js`,
+ * `node packages/controller/dist/cli.js`, ...), never by installed `bin`
+ * name — a second `bin` entry pointing at the same file is invisible to
+ * that invocation style, and worse, silently falls through to the OTHER
+ * command rather than erroring. An explicit `argv[0]` subcommand is
+ * reachable however the file is invoked, by path or by name. Both
+ * commands are still presentation-only wrappers over this package's pure
+ * gates, both still print every skip/exclusion count unconditionally, and
+ * both still use the identical three-state exit-code contract described
+ * below — same shape, same file, same bin, two subcommands, two numbers,
+ * matching `@example/strategy`'s `strategy-facts-check` shape
+ * closely, deliberately: same argument order (the thing being checked
+ * FOR, then the thing being checked, where applicable), same `--help`,
+ * same `CliInputError` split between "bad arguments" and "ran, found
+ * something wrong".
+ *
+ * A second subcommand, `voice-derivation-coverage`, wires
+ * `checkVoiceDerivationCoverage` (`./voice/derivation-coverage.ts`) in with
+ * the identical shape: parse argv, load two JSON files, run the pure check,
+ * print a report, pick an exit code from the same 0/1/2 contract — see
+ * `runVoiceDerivationCoverage`'s own doc comment below. `main()` dispatches
+ * to it only when `argv[0]` is exactly `"voice-derivation-coverage"`; any
+ * other first argument (including every existing caller's real
+ * `record-file` path) falls through to the original, unchanged behavior
+ * above — this addition is purely additive to the argv contract.
+ *
+ * A third subcommand, `locale-coverage`, wires `checkLocaleCoverage`
+ * (`./locale-coverage.ts`) in with the identical shape again: parse argv,
+ * load a JSON registries file, run the pure check, print a report, pick an
+ * exit code — see `runLocaleCoverage`'s own doc comment below.
+ * `checkLocaleCoverage` already defines its own caller contract for turning
+ * a `LocaleCoverageReport` into this package's usual three-state exit code
+ * (see `LocaleCoverageReport.complete`'s own doc comment in
+ * `locale-coverage.ts`); `runLocaleCoverage` applies that mapping exactly,
+ * rather than inventing a second one. `main()` dispatches to it only when
+ * `argv[0]` is exactly `"locale-coverage"` — checked alongside
+ * `"voice-derivation-coverage"`, before either falls through to the
+ * original `record-file` handling — so this, too, is purely additive to the
+ * argv contract.
+ *
+ * A FOURTH subcommand, `passages` (`writer-check passages <registry-file>`),
+ * wires `checkPassageComposition` (`./passage.ts`) in — the passage-layer
+ * COMPOSITION gate: does every passage in a `PassageRecord` reference only
+ * registered entries and glossary terms, never an inlined literal string
+ * or another passage's own internals? Dispatched EXACTLY the way
+ * `addressability` is (see below): a fully separate top-level branch at
+ * the very bottom of this file, its own exported `mainPassagesCheck`, its
+ * own `runPassagesCheck` wrapper — never folded through `main()` at all,
+ * for the identical reason addressability is not: this gate's own ternary
+ * precedence ("a real violation wins over an incomplete picture" — see
+ * `passage.ts`'s own top doc comment, "THE TERNARY") is independent of
+ * every other subcommand's exit-code contract, and keeping it a fully
+ * separate dispatch path keeps that independence visible in this file's
+ * own structure, not just in a comment.
+ *
+ * Exit codes — a contract a consumer's CI depends on, matching this
+ * repository's `foundry-check` convention (`@example/gates`):
+ *
+ *   0 — ran cleanly: the copy record loaded, at least one file was
+ *       actually scanned (successfully tokenized — see `scan.ts`'s
+ *       `ScanResult.filesScanned`), zero findings.
+ *   1 — ran cleanly, at least one finding (an unregistered copy candidate,
+ *       or a citation to a copy id that does not exist).
+ *   2 — could not run: bad input, the copy record missing/unreadable/
+ *       invalid, the scan directory does not exist, the walk matched zero
+ *       files, ANY matched file failed to tokenize (see `scan.parseFailures`
+ *       — a file that could not be parsed was never examined for copy, and
+ *       one such file among a hundred clean ones is still incomplete
+ *       coverage, not a clean scan), an unreadable directory
+ *       during the walk, an unexpected exception, a malformed
+ *       `ScanOptions.pathExclusions` entry (see below), OR — as of the JSX
+ *       text-node scanning added for issue #37 — at least one
+ *       `ScanResult.unchecked` entry: a JSX construct the scanner
+ *       recognized but could not reliably classify. That last case lands
+ *       here, not as a `1`-severity finding, deliberately: `unchecked`
+ *       means a REGION of an otherwise-matched, otherwise-parseable file
+ *       was never actually examined for copy — the exact same shape of
+ *       problem `parseFailures`/`filesScanned === 0` already are, just at
+ *       finer grain (part of one file, rather than a whole file), so it
+ *       gets the same answer they do. Every real finding is still printed
+ *       first (see `printGateReport`) — `unchecked` does not suppress
+ *       what WAS learned, it just refuses to let that partial picture
+ *       read as "clean" the way a bare exit `0` would. Kept strictly
+ *       distinct from 1 — a gate that reports "clean" after failing to
+ *       run, OR after only partially running, is worse than no gate at
+ *       all. This is the explicit third state this gate is built around:
+ *       "could not check" must never be reported as a pass.
+ *
+ * A malformed `pathExclusions` entry (see `scan.ts`/`path-exclusions.ts`)
+ * gets the same `2` treatment as `unchecked`, for the identical reason: an
+ * exclusion list this run cannot trust means this run cannot say which
+ * files were correctly in or out of scope, which is "could not run", not "a
+ * clean scan that happened to find nothing". This CLI does not currently
+ * accept `pathExclusions` from argv — see `main()`'s own comment — so this
+ * only fires for a caller driving `scanCopySourceTree` directly with a
+ * malformed list and inspecting `ScanResult` themselves; it is handled here
+ * anyway so the accounting/exit-code contract stays correct for a future
+ * CLI flag without a second pass over this logic.
+ */
+/** Exported for `cli.test.ts` — anything wrong with the arguments themselves always maps to exit code 2, never 1. */
+export declare class CliInputError extends Error {
+}
+/**
+ * Exported (unlike a typical CLI `main`) so `cli.test.ts` can exercise the
+ * whole argv-to-exit-code contract directly, against real `mkdtemp` temp
+ * directories, without spawning a subprocess for every case. Takes `argv`
+ * as a parameter rather than reading `process.argv` itself for exactly
+ * that reason — `run()` below is the only caller that reads the real
+ * `process.argv`.
+ */
+export declare function main(argv: string[]): number;
+/**
+ * Exported (unlike a typical CLI `main`) for the identical reason `main`
+ * and `mainAddressabilityCheck` above are — `cli.test.ts` exercises the
+ * whole argv-to-exit-code contract directly against real fixture files,
+ * without spawning a subprocess.
+ */
+export declare function mainPassagesCheck(argv: string[]): number;
+/**
+ * Exported (unlike a typical CLI `main`) for the identical reason `main`
+ * above is — `cli.test.ts` exercises the whole argv-to-exit-code contract
+ * directly against real `mkdtemp` directories, without spawning a
+ * subprocess.
+ */
+export declare function mainAddressabilityCheck(argv: string[]): number;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwHG;AAuEH,qHAAqH;AACrH,qBAAa,aAAc,SAAQ,KAAK;CAAG;AA2f3C;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAyH3C;AAsGD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAqCxD;AAkFD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CA6B9D"}