@clossys/writer 0.3.2

package/src/copy-gate.ts

@@ -0,0 +1,197 @@
+/**
+ * `checkCopyTraceability` — the gate that makes `scan.ts`'s extraction
+ * worth having. Pure: takes already-extracted `CopyCandidate[]`/
+ * `Citation[]` (see `scan.ts`) and an already-loaded `CopyRecord` (see
+ * `./types.js`), does no I/O of its own, and never throws on any input
+ * shape — the same discipline `@example/strategy`'s
+ * `checkFactsTraceability` holds to in `facts-gate.ts`. `scanCopySourceTree`
+ * (see `scan.ts`) is the half that gathers candidates/citations from a
+ * real directory; `cli.ts` is what loads a real `CopyRecord` from disk
+ * (via the sibling `registry.ts`) and turns this function's result into an
+ * exit code.
+ *
+ * THE RULE, in one sentence: every user-facing string or template literal
+ * `scan.ts` extracts from a source tree must either match a registered
+ * `CopyEntry.text` (compared by STATIC SHAPE — interpolations collapsed to
+ * `PLACEHOLDER_SENTINEL` on both sides, so a source literal's actual
+ * expression content and a registered entry's placeholder NAMES never
+ * need to agree) or be annotated with a `copy:<id>` comment citing a real
+ * entry in the record on the same line — anything else is reported as
+ * untraced. This is `@example/strategy`'s `fact:<key>` citation
+ * pattern, applied to copy instead of facts.
+ *
+ * WHAT THIS DELIBERATELY DOES NOT DO, and why:
+ *
+ *   - It does not decide what counts as a "user-facing string" at all —
+ *     that classification (and every excluded category: import
+ *     specifiers, object keys, `aria-*`/`data-*` values, class-name
+ *     builder arguments, developer diagnostics, decorative glyphs, enum
+ *     tokens, ...) already happened in `scan.ts`, which is the file with
+ *     the actual judgment calls and the comment explaining each one. This
+ *     file only ever sees candidates `scan.ts` already decided are
+ *     in-scope; it has no opinion of its own about scope.
+ *   - It does not scan raw source text for `copy:<id>` citations or
+ *     `copy-gate:ignore` markers itself — `scan.ts` already did that (see
+ *     its `scanLineMarkers`) while it had the file's content in hand, and
+ *     attached the result to each `CopyCandidate`/the scan's flat
+ *     `Citation[]`. This file only ever looks those up against a
+ *     `CopyRecord`'s real ids.
+ *   - It does not validate the `CopyRecord` itself (a placeholder declared
+ *     but missing from its own entry's `text`, a malformed id, a
+ *     duplicate id) — that is `schema.ts`'s job, upstream of this
+ *     function ever being called. A `CopyRecord` that reaches this
+ *     function is assumed already well-formed; `cli.ts` is responsible for
+ *     refusing to call this function at all on one that isn't (see its own
+ *     exit-code discipline).
+ *   - It does not resolve a `CopyEntry.factRef` against a real facts
+ *     registry — the exact same deliberately-left-open seam
+ *     `@clossys/writer/voice`'s `Claim.factRef` and this package's own
+ *     `CopyEntry.factRef` both describe in their doc comments. A gate with
+ *     visibility into both a `CopyRecord` and a real facts registry is a
+ *     different, later gate.
+ */
+
+import { PLACEHOLDER_SENTINEL, type Citation, type CopyCandidate, type UncheckedItem } from "./scan.js";
+import type { CopyRecord } from "./types.js";
+
+export type CopyGateRule = "unregistered-copy" | "unknown-copy-citation";
+
+export interface CopyGateFinding {
+  rule: CopyGateRule;
+  /** Always `"error"` — the same single-severity design `@example/strategy`'s `FactsGateFinding` uses: a piece of copy is either traced to a registered entry or it isn't. */
+  severity: "error";
+  file: string;
+  line: number;
+  message: string;
+  /** The literal's raw source text (quotes included), trimmed/length-capped, for a human scanning a report. */
+  snippet: string;
+}
+
+export interface CopyGateIgnored {
+  file: string;
+  line: number;
+  snippet: string;
+}
+
+export interface CopyGateResult {
+  findings: CopyGateFinding[];
+  /** Every candidate explicitly suppressed via a `copy-gate:ignore` marker on its own source line — recorded, never silent. */
+  ignored: CopyGateIgnored[];
+  /** Echoed straight from `ScanResult.filesScanned` (see `scan.ts`) so a caller/report has one number to check for "at least one file scanned" without re-deriving it from `candidates`, which could legitimately be empty even for a real, successful scan. */
+  filesScanned: number;
+  /** Total candidates evaluated — a sanity total, the same role `FactsGateResult.claimsScanned` plays: lets a caller tell "zero findings because nothing looked like copy" apart from "zero findings because every candidate traced cleanly". */
+  candidatesScanned: number;
+  /** Candidates that matched a registered entry's text shape or a valid `copy:<id>` citation. */
+  matched: number;
+  /**
+   * Echoed straight from `ScanResult.unchecked` (see `scan.ts`) —
+   * constructs the scanner recognized as JSX-shaped but could not
+   * classify. This is passed through UNCHANGED, never filtered or
+   * summarized away: a caller that reads `findings` and ignores this
+   * field can end up exactly where issue #37 started — reporting a clean
+   * result over a file part of which was never actually examined.
+   * `cli.ts` is the one that turns a non-empty list here into something
+   * an operator cannot miss; see its own doc comment for exactly where
+   * that lands in the exit-code contract.
+   */
+  unchecked: UncheckedItem[];
+}
+
+/** The same `{name}` brace-delimited placeholder convention `schema.ts` checks `CopyEntry.text` against — collapsed here to the identical sentinel `scan.ts` uses for a source literal's `${...}` interpolations, so the two sides compare as the same shape regardless of what name either side chose. */
+const ENTRY_PLACEHOLDER_RE = /\{[^{}]+\}/g;
+
+function normalizeEntryText(text: string): string {
+  return text.replace(ENTRY_PLACEHOLDER_RE, PLACEHOLDER_SENTINEL);
+}
+
+function snippetOf(text: string, max = 120): string {
+  const trimmed = text.trim();
+  return trimmed.length > max ? `${trimmed.slice(0, max)}…` : trimmed;
+}
+
+interface CopyIndex {
+  byId: Set<string>;
+  byNormalizedText: Set<string>;
+}
+
+function buildCopyIndex(record: CopyRecord): CopyIndex {
+  const byId = new Set<string>();
+  const byNormalizedText = new Set<string>();
+  for (const entry of record.entries) {
+    byId.add(entry.id);
+    byNormalizedText.add(normalizeEntryText(entry.text));
+  }
+  return { byId, byNormalizedText };
+}
+
+/**
+ * Evaluates every `candidate` against `record`, using `citations` for the
+ * "cites an id that does not exist" check. Never throws: an `entries`
+ * array that is empty is valid input (every candidate will simply be
+ * untraced), and a `CopyCandidate[]`/`Citation[]` produced from any file
+ * content — however unusual — is evaluated with no assumption about its
+ * shape beyond what `scan.ts`'s own types already guarantee. `unchecked`
+ * is required, not optional, and passed straight through onto
+ * `CopyGateResult.unchecked` unmodified — a caller cannot construct a
+ * `CopyGateResult` from this function while accidentally forgetting that
+ * field exists.
+ */
+export function checkCopyTraceability(
+  candidates: CopyCandidate[],
+  citations: Citation[],
+  record: CopyRecord,
+  filesScanned: number,
+  unchecked: UncheckedItem[],
+): CopyGateResult {
+  const index = buildCopyIndex(record);
+  const findings: CopyGateFinding[] = [];
+  const ignored: CopyGateIgnored[] = [];
+  let matched = 0;
+
+  // Pass 1: citations to a copy id that does not exist — checked over
+  // EVERY citation found anywhere in the scanned tree, independent of
+  // whether a candidate happens to share its line, mirroring
+  // `@example/strategy`'s `facts-gate.ts` Pass 1 (see `scan.ts`'s
+  // `Citation` doc comment for why).
+  for (const citation of citations) {
+    if (!index.byId.has(citation.id)) {
+      findings.push({
+        rule: "unknown-copy-citation",
+        severity: "error",
+        file: citation.file,
+        line: citation.line,
+        message: `cites copy id "${citation.id}", which does not exist in the copy record — a citation to a rotted or misspelled id silently defeats this gate`,
+        snippet: `copy:${citation.id}`,
+      });
+    }
+  }
+
+  // Pass 2: every candidate, traced or not.
+  for (const candidate of candidates) {
+    if (candidate.hasIgnoreMarker) {
+      ignored.push({ file: candidate.file, line: candidate.line, snippet: candidate.raw });
+      continue;
+    }
+    const hasValidCitation = candidate.citedIds.some((id) => index.byId.has(id));
+    if (hasValidCitation || index.byNormalizedText.has(candidate.normalized)) {
+      matched++;
+      continue;
+    }
+
+    findings.push({
+      rule: "unregistered-copy",
+      severity: "error",
+      file: candidate.file,
+      line: candidate.line,
+      message:
+        candidate.kind === "template"
+          ? `template literal ${candidate.raw} does not match any registered copy entry's text (shape-compared, interpolations ignored), and carries no valid "copy:<id>" citation`
+          : candidate.kind === "jsx-text"
+            ? `JSX text "${candidate.raw}" does not match any registered copy entry's text, and carries no valid "copy:<id>" citation`
+            : `string ${candidate.raw} does not match any registered copy entry's text, and carries no valid "copy:<id>" citation`,
+      snippet: snippetOf(candidate.raw),
+    });
+  }
+
+  return { findings, ignored, filesScanned, candidatesScanned: candidates.length, matched, unchecked };
+}

package/src/fingerprint.ts

@@ -0,0 +1,66 @@
+/**
+ * `computeCopyFingerprint` — a deterministic, content-derived digest of a
+ * copy entry's `text`, and nothing else (no locale, no timestamp, no id
+ * folded in). This is the one piece of machinery that makes real
+ * stale-translation detection possible: `locale-coverage.ts`'s
+ * `checkLocaleCoverage` compares a target entry's recorded
+ * `translation.sourceFingerprint` (`types.ts`'s `CopyTranslationProvenance`)
+ * against a fresh `computeCopyFingerprint(sourceEntry.text)` to decide
+ * whether a translation is still current.
+ *
+ * WHY CONTENT-DERIVED, NEVER A HUMAN-MAINTAINED REVISION NUMBER
+ * ---------------------------------------------------------------------------
+ * A translation is stale exactly when the source text it was translated
+ * from no longer matches the current source text — that is the whole
+ * definition. A hand-bumped revision counter answers a related but weaker
+ * question ("did someone remember to bump the number"), and nothing in this
+ * package's schema, or any schema, can enforce that a human touches the
+ * counter in lockstep with every edit to `text`. A bumped counter next to
+ * an untouched sentence looks identical, at the type level, to a genuinely
+ * re-reviewed one — the discipline can drift silently, the same
+ * "check that passes because it checked nothing" failure mode
+ * `locale-coverage.ts`'s own top-of-file doc comment (and
+ * `scripts/check-release-readiness.mjs`'s header, which it cites) already
+ * warns about elsewhere in this package.
+ *
+ * A content hash cannot drift the same way. If the source `text` changed by
+ * one character, `computeCopyFingerprint` returns a different value with
+ * certainty; if it did not change, it returns the same value with equal
+ * certainty. It requires no human bookkeeping to stay correct — the
+ * fingerprint IS the source text, deterministically restated, rather than
+ * someone's claim about the source text.
+ *
+ * Uses `node:crypto`, a Node.js built-in — not a runtime dependency. This
+ * follows the exact precedent `registry.ts` already set for `node:fs`: see
+ * this package's README, "The single most important constraint", and
+ * `types.ts`'s own doc comment on this package's zero-runtime-dependency
+ * discipline.
+ */
+
+import { createHash } from "node:crypto";
+
+/**
+ * The digest algorithm `computeCopyFingerprint` uses, and the value every
+ * `CopyTranslationProvenance.fingerprintAlgorithm` produced by this function
+ * should record. Exported as a named constant, not hardcoded at each call
+ * site, so a future algorithm change is one edit instead of several
+ * independently-drifting string literals.
+ */
+export const COPY_FINGERPRINT_ALGORITHM = "sha256";
+
+/**
+ * Computes a deterministic, content-derived fingerprint of `text` — a
+ * `sha256` hex digest, nothing else folded in (no locale, no id, no
+ * timestamp). Pure: the same `text` always produces the same fingerprint,
+ * on any machine, in any process.
+ *
+ * A consumer's own translation tooling should call this at the moment a
+ * translation is actually produced, recording the result as
+ * `translation.sourceFingerprint` alongside `COPY_FINGERPRINT_ALGORITHM` as
+ * `translation.fingerprintAlgorithm` — the same function
+ * `checkLocaleCoverage` will later call again, on the then-current source
+ * `text`, to decide whether that recorded fingerprint still matches.
+ */
+export function computeCopyFingerprint(text: string): string {
+  return createHash(COPY_FINGERPRINT_ALGORITHM).update(text, "utf8").digest("hex");
+}

package/src/index.ts

@@ -0,0 +1,163 @@
+/**
+ * @clossys/writer — public entry point. See README.md for the full
+ * picture: the machinery-vs-values split this package mirrors from
+ * the package's voice contract (itself mirroring @example/ui/tokens), the
+ * frozen CopyEntry/CopyRecord contract, and exactly what checkCopyRecord
+ * does and does not attempt.
+ *
+ * Two halves ship from here, mirroring the split @example/strategy
+ * draws between its own entity/reader half and its facts gate:
+ *
+ *   1. THE REGISTRY. CopyEntry/CopyRecord (`types.ts`), their validation
+ *      (`schema.ts`), and `readCopyRecord` (`registry.ts`) — a consumer
+ *      registers its own copy and this package can load and validate it.
+ *   2. THE SCANNER GATE. `scanCopySourceTree` (`scan.ts`) walks a real
+ *      source tree and extracts every user-facing string/template literal
+ *      as a `CopyCandidate`; `checkCopyTraceability` (`copy-gate.ts`) is
+ *      the pure gate that checks each one against a `CopyRecord`. `cli.ts`
+ *      wires both, plus `readCopyRecord`, into `writer-check`, an installable
+ *      CLI with the same three-state exit-code contract
+ *      `strategy-facts-check` uses: 0 clean, 1 findings, 2 could not run.
+ *      `cli.ts` itself is intentionally NOT re-exported here — matching
+ *      `@example/strategy`'s own index.ts, a CLI's `main`/argv
+ *      handling is not library surface, only its `bin` entry is.
+ */
+
+export type {
+  CopyEntry,
+  CopyEntryId,
+  CopyEntryStatus,
+  CopyFinding,
+  CopyLocale,
+  CopyRef,
+  CopyRegistry,
+  CopyRegistryEntry,
+  CopyResolution,
+  CopyResolver,
+  CopySource,
+  CopyTranslationProvenance,
+  CopyValue,
+  CopyRecord,
+} from "./types.js";
+
+// Content-derived fingerprinting for translation provenance — see
+// fingerprint.ts's and locale-coverage.ts's doc comments for why a source
+// text is fingerprinted rather than tracked by a human-maintained revision.
+export { computeCopyFingerprint, COPY_FINGERPRINT_ALGORITHM } from "./fingerprint.js";
+
+export { parseCopyRecord, parseCopyRegistry, validateCopyRecordShape, validateCopyRegistryShape } from "./schema.js";
+
+export { createCopyResolver, resolveCopyRef } from "./resolve.js";
+export type { CopyResolveIssue, CopyResolveIssueReason, CopyResolveResult } from "./resolve.js";
+
+export { readCopyRecord } from "./registry.js";
+export type { CopyRegistryReadIssue, CopyRegistryReadIssueReason, CopyRegistryReadResult } from "./registry.js";
+
+export { checkCopyRecord } from "./checker.js";
+export type {
+  CopyEntryCheckResult,
+  CopyEntrySkip,
+  CopyRecordCheckOptions,
+  CopyRecordCheckReport,
+  CopyRecordFinding,
+  CopyRecordWaivedFinding,
+} from "./checker.js";
+
+// Voice is a first-class part of copy. It is available from this root entry
+// point for a single-package experience and from the focused `copy/voice`
+// subpath for consumers that only need the verbal contract.
+export * from "./voice/index.js";
+
+export { extractCopyCandidates, PLACEHOLDER_SENTINEL, scanCopySourceTree } from "./scan.js";
+export type {
+  Citation,
+  CopyCandidate,
+  ExcludedLiteral,
+  ExclusionReason,
+  ParseFailure,
+  ScanOptions,
+  ScanResult,
+  SkippedFile,
+  UncheckedItem,
+} from "./scan.js";
+
+// Path exclusions for scanCopySourceTree's scanning surface — see
+// path-exclusions.ts's top doc comment for the "mention vs. use" case this
+// exists for, and why it is a DIFFERENT feature from scan.ts's own
+// ExclusionReason (a per-literal classification, not a per-file scope
+// decision).
+export { validatePathExclusions } from "./path-exclusions.js";
+export type {
+  ExcludedPath,
+  PathExclusion,
+  PathExclusionFinding,
+  PathExclusionFindingRule,
+  PathExclusionValidation,
+} from "./path-exclusions.js";
+
+export { checkCopyTraceability } from "./copy-gate.js";
+export type { CopyGateFinding, CopyGateIgnored, CopyGateResult, CopyGateRule } from "./copy-gate.js";
+
+// Copy ADDRESSABILITY: is user-facing prose resolved from the copy
+// registry by id, or typed inline in a component? A different, stricter
+// question than traceability above — see addressability.ts's top doc
+// comment for the full split.
+export {
+  checkAddressability,
+  extractAddressabilityCandidates,
+  scanAddressabilitySources,
+} from "./addressability.js";
+export type {
+  AddressabilityGateResult,
+  AddressabilityPosition,
+  AddressabilityScanOptions,
+  AddressabilityScanResult,
+  AddressabilityUncheckedItem,
+  AddressabilityVerdict,
+  AddressabilityViolation,
+} from "./addressability.js";
+
+// Locale-coverage governance: is every declared locale covered by a source
+// locale's registry, where has a target locale drifted, has a translation
+// gone stale against an edited source (via content fingerprint), and does
+// every entry's interpolation stay in parity across locales? See
+// locale-coverage.ts's top-of-file doc comment for the full design.
+export { checkLocaleCoverage } from "./locale-coverage.js";
+export type {
+  LocaleCoverageFinding,
+  LocaleCoverageReport,
+  LocaleCoverageSkip,
+  LocaleCoverageSkipReason,
+} from "./locale-coverage.js";
+
+// The PASSAGE LAYER (issue #373) — the missing middle between a single
+// CopyEntry and a whole document: a Passage composes entry/term
+// REFERENCES the way a UI block composes atoms. See passage.ts's top doc
+// comment for the full design, the ternary, and what this gate
+// deliberately does not attempt (referential integrity against a real
+// CopyRecord/glossary — a different, later gate).
+export {
+  checkPassageComposition,
+  classifyPassageField,
+  parsePassageRecord,
+  readPassageRecord,
+  validatePassageRecordShape,
+} from "./passage.js";
+export type {
+  Passage,
+  PassageEntryReference,
+  PassageFieldClassification,
+  PassageFinding,
+  PassageGateResult,
+  PassageId,
+  PassageRecord,
+  PassageReference,
+  PassageRegistryReadIssue,
+  PassageRegistryReadIssueReason,
+  PassageRegistryReadResult,
+  PassageTermReference,
+  PassageUnclassifiedItem,
+  PassageVerdict,
+  PassageViolation,
+  PassageViolationRule,
+} from "./passage.js";