@clossys/writer 0.3.2

package/dist/path-exclusions.js

@@ -0,0 +1,213 @@
+/**
+ * Path exclusions for `scan.ts`'s SCANNING SURFACE — `scanCopySourceTree`'s
+ * directory walk — never to be confused with `scan.ts`'s existing
+ * `ExclusionReason`/`ExcludedLiteral`, a DIFFERENT feature this file does
+ * not touch. Read `scan.ts`'s own top doc comment ("THE BOUNDARY") before
+ * this one: that mechanism decides, for a LITERAL already found inside a
+ * file that IS being scanned, whether that one literal is real copy or
+ * something structural (an import specifier, a CSS class, an aria label,
+ * ...) — a per-LITERAL classification made from the few dozen characters of
+ * context immediately around it. This file answers a completely different
+ * question, at a completely different granularity: should this FILE be
+ * looked at for copy candidates AT ALL, before a single character of it is
+ * ever tokenized? That is a per-FILE scope decision, made once, from the
+ * file's own path alone — extending `ExclusionReason` to cover it would be
+ * a coincidence of both being named "exclusion", not a shared mechanism;
+ * this is why it is a new, separate type (`PathExclusion`) and a new,
+ * separate `ScanResult` field (`excludedFiles`), not a tenth
+ * `ExclusionReason`.
+ *
+ * THE MOTIVATING CASE ("mention vs. use"): a style guide or README that
+ * documents this voice's own banned terms — "never say X, say Y instead" —
+ * necessarily CONTAINS the literal banned text, as a MENTION, not a USE.
+ * Scanned like any other file, that mention looks identical to real,
+ * unregistered product copy to `checkCopyTraceability` (`copy-gate.ts`):
+ * the traceability gate has no notion of "this file's job is to talk about
+ * copy, not ship it". A `PathExclusion` on that one file's path is the fix
+ * — the file is never tokenized at all, so it can never produce a
+ * candidate, `unregistered-copy` finding, or citation. See this file's
+ * README section, "Path exclusions vs. per-literal exclusions", for the
+ * fuller argument, including why this stays scoped to `scan.ts`'s existing
+ * scanning surface (copy TRACEABILITY) rather than inventing a new
+ * directory-scanning feature for VOICE/glossary rules, which this package
+ * does not otherwise have — a consumer building their own "walk a
+ * directory, then run each file's text through `checkCopy`" tool gets the
+ * identical mention-vs-use protection by reusing THIS mechanism (call
+ * `scanCopySourceTree` with `pathExclusions`, then feed its candidates'
+ * text through `checkCopy` themselves) rather than this package growing a
+ * second, redundant exclusion list.
+ *
+ * FAILS CLOSED, mirroring `checker.ts`'s `VoiceCheckWaiver` handling (the
+ * established precedent for "a caller-supplied list of exceptions" in this
+ * package's ecosystem) almost exactly:
+ *
+ *   - A MALFORMED entry (not an object, `path`/`reason` missing or not a
+ *     non-empty string, or a `path` this file's own small pattern language
+ *     cannot parse — see `classifyPathExclusionPattern`) is never applied:
+ *     it exempts NOTHING, and is reported as its own `"error"`-severity
+ *     `PathExclusionFinding` — the exact "a malformed exclusion entry is a
+ *     finding, never a silent exemption" requirement. This mirrors
+ *     `"waiver:invalid"`.
+ *   - An exclusion that never matched a single scanned file is dead
+ *     configuration — reported as its own `"warning"`-severity
+ *     `PathExclusionFinding`, mirroring `"waiver:unused"`, so a stale
+ *     exclusion (the file it named was renamed or deleted) cannot silently
+ *     sit in a config forever looking like it is still doing something.
+ */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+/**
+ * Classifies `pattern` into one of this file's three supported shapes, or
+ * `undefined` if it matches none of them — the entire "glob" grammar this
+ * package supports, deliberately small (no glob library, per this
+ * repository's zero-runtime-dependency rule):
+ *
+ *   1. `"exact"` — no `*` anywhere. Matches only the identical repo-relative
+ *      path, e.g. `"docs/style-guide.ts"`.
+ *   2. `"subtree"` — ends in exactly `"/**"`, with no other `*` anywhere
+ *      else in the pattern. Matches every file under that directory,
+ *      recursively, e.g. `"docs/**"` matches `"docs/style-guide.ts"` AND
+ *      `"docs/internal/glossary.ts"`.
+ *   3. `"segment-wildcard"` — exactly one `*` (not `**`), confined to the
+ *      pattern's FINAL `/`-separated segment, e.g. `"docs/*.ts"`. Every
+ *      segment before the last must match exactly; the last segment's `*`
+ *      matches any run of characters (including none) within that one
+ *      segment only — it does not cross a `/`.
+ *
+ * A `*`/`**` anywhere else (mid-path, more than one `*` in the final
+ * segment, a `**` not forming the whole-pattern `"/**"` suffix, an empty
+ * pattern) is rejected — `undefined` — by design: this is a fixed-scope
+ * exclusion mechanism for known files/directories, not a general glob
+ * engine, and a caller who needs more expressive matching should use
+ * `"subtree"` on a containing directory instead.
+ */
+function classifyPathExclusionPattern(pattern) {
+    if (pattern.length === 0)
+        return undefined;
+    if (!pattern.includes("*"))
+        return "exact";
+    if (pattern.endsWith("/**") && pattern.indexOf("*") === pattern.length - 2) {
+        // The only "*" characters are the trailing "**" pair, and nothing
+        // precedes them but a "/" — reject a bare "**" with no directory prefix
+        // (nothing meaningful to scope to) and reject any other "*" earlier in
+        // the string (already true here: `indexOf` found the FIRST "*" at the
+        // trailing pair's position, so there is no earlier one).
+        const prefix = pattern.slice(0, -3);
+        return prefix.length > 0 && !prefix.includes("*") ? "subtree" : undefined;
+    }
+    const lastSlash = pattern.lastIndexOf("/");
+    const lastSegment = lastSlash === -1 ? pattern : pattern.slice(lastSlash + 1);
+    const priorSegments = lastSlash === -1 ? "" : pattern.slice(0, lastSlash);
+    const starCount = (lastSegment.match(/\*/g) ?? []).length;
+    if (starCount === 1 && !lastSegment.includes("**") && !priorSegments.includes("*")) {
+        return "segment-wildcard";
+    }
+    return undefined;
+}
+/**
+ * Matches `relPath` (already `/`-joined, repo-relative — the same shape
+ * `scanCopySourceTree` produces for every `CopyCandidate.file`) against one
+ * already-classified exclusion. Never called with a pattern that failed
+ * `classifyPathExclusionPattern` — `validatePathExclusions` filters those
+ * out before anything reaches here, so this function does not re-validate.
+ */
+export function matchesPathExclusion(relPath, exclusion) {
+    switch (exclusion.kind) {
+        case "exact":
+            return relPath === exclusion.path;
+        case "subtree": {
+            const prefix = exclusion.path.slice(0, -2); // "docs/**" -> "docs/"
+            return relPath.startsWith(prefix);
+        }
+        case "segment-wildcard": {
+            const lastSlash = exclusion.path.lastIndexOf("/");
+            const priorSegments = lastSlash === -1 ? "" : exclusion.path.slice(0, lastSlash + 1);
+            const lastSegmentPattern = lastSlash === -1 ? exclusion.path : exclusion.path.slice(lastSlash + 1);
+            if (!relPath.startsWith(priorSegments))
+                return false;
+            const relRest = relPath.slice(priorSegments.length);
+            if (relRest.includes("/"))
+                return false; // the wildcard segment never crosses a "/"
+            const [before, after] = lastSegmentPattern.split("*");
+            return relRest.startsWith(before) && relRest.endsWith(after) && relRest.length >= before.length + after.length;
+        }
+        default: {
+            const unhandled = exclusion.kind;
+            throw new Error(`matchesPathExclusion: unknown pattern kind ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+/**
+ * Validates `value` (`ScanOptions.pathExclusions`, or any raw candidate list
+ * — this is called on a TYPED `PathExclusion[]` from a TypeScript caller,
+ * but re-validates every field anyway, the same defense-in-depth this
+ * repository's other schema functions apply to already-typed input: see
+ * `@clossys/writer/voice`'s `schema.ts` header comment for why a
+ * plain-JS caller, or a value that merely satisfies the type at compile
+ * time without conforming at runtime, is exactly the case this guards
+ * against). Never throws.
+ */
+export function validatePathExclusions(value) {
+    if (value === undefined)
+        return { valid: [], findings: [] };
+    if (!Array.isArray(value)) {
+        return {
+            valid: [],
+            findings: [
+                {
+                    rule: "path-exclusion-invalid",
+                    severity: "error",
+                    message: `pathExclusions must be an array when present, got ${JSON.stringify(value)}.`,
+                },
+            ],
+        };
+    }
+    const valid = [];
+    const findings = [];
+    value.forEach((raw, i) => {
+        if (!isPlainObject(raw)) {
+            findings.push({
+                rule: "path-exclusion-invalid",
+                severity: "error",
+                message: `pathExclusions[${i}] must be an object with "path" and "reason", got ${JSON.stringify(raw)}.`,
+            });
+            return;
+        }
+        const path = raw.path;
+        const reason = raw.reason;
+        if (!isNonEmptyString(path)) {
+            findings.push({
+                rule: "path-exclusion-invalid",
+                severity: "error",
+                message: `pathExclusions[${i}].path must be a non-empty string, got ${JSON.stringify(path)}.`,
+            });
+            return;
+        }
+        if (!isNonEmptyString(reason)) {
+            findings.push({
+                rule: "path-exclusion-invalid",
+                severity: "error",
+                message: `pathExclusions[${i}].reason must be a non-empty string, got ${JSON.stringify(reason)}. An exclusion with no stated reason is not auditable.`,
+                path,
+            });
+            return;
+        }
+        const kind = classifyPathExclusionPattern(path);
+        if (kind === undefined) {
+            findings.push({
+                rule: "path-exclusion-invalid",
+                severity: "error",
+                message: `pathExclusions[${i}].path "${path}" is not a supported pattern — supported shapes are an exact path, a "dir/**" subtree, or a single "*" confined to the final path segment. See path-exclusions.ts's classifyPathExclusionPattern doc comment.`,
+                path,
+            });
+            return;
+        }
+        valid.push({ path, reason, kind });
+    });
+    return { valid, findings };
+}
+//# sourceMappingURL=path-exclusions.js.map

package/dist/path-exclusions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-exclusions.js","sourceRoot":"","sources":["../src/path-exclusions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAuCH,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc;IACtC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,SAAS,4BAA4B,CAAC,OAAe;IACnD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3C,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC;IAE3C,IAAI,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3E,kEAAkE;QAClE,wEAAwE;QACxE,uEAAuE;QACvE,sEAAsE;QACtE,yDAAyD;QACzD,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACpC,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;IAC5E,CAAC;IAED,MAAM,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC3C,MAAM,WAAW,GAAG,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;IAC9E,MAAM,aAAa,GAAG,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IAC1E,MAAM,SAAS,GAAG,CAAC,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;IAC1D,IAAI,SAAS,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACnF,OAAO,kBAAkB,CAAC;IAC5B,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe,EAAE,SAAiC;IACrF,QAAQ,SAAS,CAAC,IAAI,EAAE,CAAC;QACvB,KAAK,OAAO;YACV,OAAO,OAAO,KAAK,SAAS,CAAC,IAAI,CAAC;QACpC,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,uBAAuB;YACnE,OAAO,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QACpC,CAAC;QACD,KAAK,kBAAkB,CAAC,CAAC,CAAC;YACxB,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;YAClD,MAAM,aAAa,GAAG,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,CAAC;YACrF,MAAM,kBAAkB,GAAG,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;YACnG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC;gBAAE,OAAO,KAAK,CAAC;YACrD,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;YACpD,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;gBAAE,OAAO,KAAK,CAAC,CAAC,2CAA2C;YACpF,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,kBAAkB,CAAC,KAAK,CAAC,GAAG,CAAqB,CAAC;YAC1E,OAAO,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QACjH,CAAC;QACD,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,SAAS,GAAU,SAAS,CAAC,IAAI,CAAC;YACxC,MAAM,IAAI,KAAK,CAAC,8CAA8C,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QAC7F,CAAC;IACH,CAAC;AACH,CAAC;AASD;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IAC5D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO;YACL,KAAK,EAAE,EAAE;YACT,QAAQ,EAAE;gBACR;oBACE,IAAI,EAAE,wBAAwB;oBAC9B,QAAQ,EAAE,OAAO;oBACjB,OAAO,EAAE,qDAAqD,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG;iBACvF;aACF;SACF,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAA6B,EAAE,CAAC;IAC3C,MAAM,QAAQ,GAA2B,EAAE,CAAC;IAE5C,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;QACvB,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,wBAAwB;gBAC9B,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,kBAAkB,CAAC,qDAAqD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG;aACxG,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QACD,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;QACtB,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;QAE1B,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5B,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,wBAAwB;gBAC9B,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,kBAAkB,CAAC,0CAA0C,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG;aAC9F,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QACD,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC;YAC9B,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,wBAAwB;gBAC9B,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,kBAAkB,CAAC,4CAA4C,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,wDAAwD;gBACtJ,IAAI;aACL,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,MAAM,IAAI,GAAG,4BAA4B,CAAC,IAAI,CAAC,CAAC;QAChD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,wBAAwB;gBAC9B,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,kBAAkB,CAAC,WAAW,IAAI,+MAA+M;gBAC1P,IAAI;aACL,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IACrC,CAAC,CAAC,CAAC;IAEH,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AAC7B,CAAC"}

package/dist/registry.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `readCopyRecord` — the one place in this package that touches a
+ * filesystem. Everything in `schema.ts` is pure shape; this function is
+ * what turns a consumer's real copy registry file into validated data, in
+ * the same gather-don't-judge spirit `@example/strategy`'s
+ * `readStrategy` uses for a `strategy/` directory: read what's there,
+ * validate it, and record — never throw on — anything that could not be
+ * turned into usable data. Judgement about what to DO with an unreadable
+ * or invalid registry (fail a build, warn, block a release) belongs to
+ * the caller, not to this function.
+ *
+ * Deliberately narrower than `readStrategy`: a `CopyRecord` is a single
+ * JSON file, not a directory of several independently-optional files, so
+ * there is exactly one thing that can go wrong and exactly one place it
+ * can go wrong at.
+ */
+import type { CopyRecord } from "./types.js";
+/**
+ * Why `path` did not become a usable `CopyRecord`. `"unreadable"` is a
+ * real I/O failure — the file does not exist, a permission was denied, or
+ * it vanished mid-read; unknown content could be hiding behind any of
+ * those, which is why they are not distinguished further here.
+ * `"unparseable"` means the bytes were read but are not valid JSON.
+ * `"invalid-schema"` means the JSON parsed but does not satisfy
+ * `CopyRecord`'s schema (a missing required field, a wrong type, a
+ * duplicate id, a declared placeholder missing from its entry's text) —
+ * see `schema.ts`'s `validateCopyRecordShape` for the full list of checks
+ * that can produce this.
+ */
+export type CopyRegistryReadIssueReason = "unreadable" | "unparseable" | "invalid-schema";
+export interface CopyRegistryReadIssue {
+    reason: CopyRegistryReadIssueReason;
+    /** Human-readable detail: the I/O error message, the JSON parse error, or `parseCopyRecord`'s full issue list. */
+    detail: string;
+}
+export interface CopyRegistryReadResult {
+    /** The path this result was read from, exactly as given — echoed back for a caller building its own error message. */
+    path: string;
+    /** The parsed, defaulted `CopyRecord`, or `undefined` if `issues` is non-empty. */
+    record?: CopyRecord;
+    /** Empty means `path` was read, parsed, and validated cleanly. Non-empty means `record` is `undefined` — see `CopyRegistryReadIssueReason`. */
+    issues: CopyRegistryReadIssue[];
+    /**
+     * `true` exactly when `issues` is empty and `record` is populated.
+     * Named to match `@example/strategy`'s `StrategyBundle.complete`
+     * and `@clossys/writer/voice`'s `VoiceCheckReport.complete` —
+     * "everything this function could have checked, it did, and it found
+     * nothing wrong" is the same one-boolean-read contract across all
+     * three, on purpose.
+     */
+    complete: boolean;
+}
+/**
+ * Reads and validates the `CopyRecord` at `path`. Never throws: every
+ * failure — an unreadable file, invalid JSON, or a schema violation — is
+ * recorded into the returned `CopyRegistryReadResult.issues` and
+ * reflected in `.complete`, the same discipline `readStrategy` holds to
+ * for a strategy directory.
+ */
+export declare function readCopyRecord(path: string): CopyRegistryReadResult;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,2BAA2B,GAAG,YAAY,GAAG,aAAa,GAAG,gBAAgB,CAAC;AAE1F,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,2BAA2B,CAAC;IACpC,kHAAkH;IAClH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,sHAAsH;IACtH,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,+IAA+I;IAC/I,MAAM,EAAE,qBAAqB,EAAE,CAAC;IAChC;;;;;;;OAOG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,sBAAsB,CAoCnE"}

package/dist/registry.js

@@ -0,0 +1,64 @@
+/**
+ * `readCopyRecord` — the one place in this package that touches a
+ * filesystem. Everything in `schema.ts` is pure shape; this function is
+ * what turns a consumer's real copy registry file into validated data, in
+ * the same gather-don't-judge spirit `@example/strategy`'s
+ * `readStrategy` uses for a `strategy/` directory: read what's there,
+ * validate it, and record — never throw on — anything that could not be
+ * turned into usable data. Judgement about what to DO with an unreadable
+ * or invalid registry (fail a build, warn, block a release) belongs to
+ * the caller, not to this function.
+ *
+ * Deliberately narrower than `readStrategy`: a `CopyRecord` is a single
+ * JSON file, not a directory of several independently-optional files, so
+ * there is exactly one thing that can go wrong and exactly one place it
+ * can go wrong at.
+ */
+import { readFileSync } from "node:fs";
+import { parseCopyRecord } from "./schema.js";
+/**
+ * Reads and validates the `CopyRecord` at `path`. Never throws: every
+ * failure — an unreadable file, invalid JSON, or a schema violation — is
+ * recorded into the returned `CopyRegistryReadResult.issues` and
+ * reflected in `.complete`, the same discipline `readStrategy` holds to
+ * for a strategy directory.
+ */
+export function readCopyRecord(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        return {
+            path,
+            issues: [{ reason: "unreadable", detail: error instanceof Error ? error.message : String(error) }],
+            complete: false,
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        return {
+            path,
+            issues: [{ reason: "unparseable", detail: error instanceof Error ? error.message : String(error) }],
+            complete: false,
+        };
+    }
+    try {
+        const record = parseCopyRecord(parsed);
+        return { path, record, issues: [], complete: true };
+    }
+    catch (error) {
+        // parseCopyRecord throws a single Error whose message already lists
+        // every validateCopyRecordShape finding, one per line — reused as-is
+        // rather than re-deriving the same detail a second way.
+        return {
+            path,
+            issues: [{ reason: "invalid-schema", detail: error instanceof Error ? error.message : String(error) }],
+            complete: false,
+        };
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAyC9C;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACnC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,IAAI;YACJ,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YAClG,QAAQ,EAAE,KAAK;SAChB,CAAC;IACJ,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO;YACL,IAAI;YACJ,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACnG,QAAQ,EAAE,KAAK;SAChB,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;QACvC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACtD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,oEAAoE;QACpE,qEAAqE;QACrE,wDAAwD;QACxD,OAAO;YACL,IAAI;YACJ,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACtG,QAAQ,EAAE,KAAK;SAChB,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/resolve.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Strict, deterministic `CopyRef` resolution for rendered surfaces.
+ *
+ * This is intentionally separate from the source scanner's `CopyRecord`
+ * support. A scanner can compare a local sentence against an unversioned
+ * record; publishing a page needs stronger evidence: a locale, revision,
+ * source provenance, and an approved entry. The result exposes every one of
+ * those inputs so `@example/surface` can place them in its output
+ * manifest without knowing how a consumer stores copy.
+ */
+import type { CopyRef, CopyRegistry, CopyResolution, CopyResolver } from "./types.js";
+export type CopyResolveIssueReason = "invalid-registry" | "invalid-ref" | "locale-mismatch" | "unknown-copy-id" | "copy-not-approved" | "missing-placeholder-value" | "unexpected-placeholder-value";
+export interface CopyResolveIssue {
+    reason: CopyResolveIssueReason;
+    message: string;
+    id?: string;
+    placeholder?: string;
+}
+export interface CopyResolveResult {
+    resolution?: CopyResolution;
+    issues: CopyResolveIssue[];
+    complete: boolean;
+}
+/**
+ * Resolves a `CopyRef` against one locale-specific registry. Any absence,
+ * lifecycle failure, locale mismatch, or placeholder mismatch produces no
+ * text and a non-complete result. Consumers may log `issues`; renderers must
+ * treat a missing `resolution` as an unresolved required input.
+ */
+export declare function resolveCopyRef(registry: CopyRegistry | unknown, ref: CopyRef | unknown): CopyResolveResult;
+/** Creates the narrow resolver callback for presentation code. */
+export declare function createCopyResolver(registry: CopyRegistry | unknown): CopyResolver;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,OAAO,EACP,YAAY,EACZ,cAAc,EACd,YAAY,EAEb,MAAM,YAAY,CAAC;AAGpB,MAAM,MAAM,sBAAsB,GAC9B,kBAAkB,GAClB,aAAa,GACb,iBAAiB,GACjB,iBAAiB,GACjB,mBAAmB,GACnB,2BAA2B,GAC3B,8BAA8B,CAAC;AAEnC,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,sBAAsB,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,QAAQ,EAAE,OAAO,CAAC;CACnB;AAkBD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,GAAG,iBAAiB,CAsG1G;AAED,kEAAkE;AAClE,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,GAAG,YAAY,CAEjF"}

package/dist/resolve.js

@@ -0,0 +1,133 @@
+/**
+ * Strict, deterministic `CopyRef` resolution for rendered surfaces.
+ *
+ * This is intentionally separate from the source scanner's `CopyRecord`
+ * support. A scanner can compare a local sentence against an unversioned
+ * record; publishing a page needs stronger evidence: a locale, revision,
+ * source provenance, and an approved entry. The result exposes every one of
+ * those inputs so `@example/surface` can place them in its output
+ * manifest without knowing how a consumer stores copy.
+ */
+import { validateCopyRegistryShape } from "./schema.js";
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isCopyValue(value) {
+    return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+function interpolate(text, values) {
+    return text.replace(/\{([^{}]+)\}/g, (_match, name) => String(values[name]));
+}
+/**
+ * Resolves a `CopyRef` against one locale-specific registry. Any absence,
+ * lifecycle failure, locale mismatch, or placeholder mismatch produces no
+ * text and a non-complete result. Consumers may log `issues`; renderers must
+ * treat a missing `resolution` as an unresolved required input.
+ */
+export function resolveCopyRef(registry, ref) {
+    const registryFindings = validateCopyRegistryShape(registry);
+    if (registryFindings.length > 0) {
+        return {
+            issues: [{ reason: "invalid-registry", message: "CopyRegistry must pass validateCopyRegistryShape before it can resolve CopyRefs." }],
+            complete: false,
+        };
+    }
+    // Safe after the validator's complete structural check. The public
+    // signature still accepts unknown because JavaScript callers can bypass
+    // TypeScript and resolution must fail closed rather than throw.
+    const validRegistry = registry;
+    if (!isPlainObject(ref) || !isNonEmptyString(ref.id) || (ref.locale !== undefined && !isNonEmptyString(ref.locale)) || (ref.values !== undefined && !isPlainObject(ref.values))) {
+        return {
+            issues: [{ reason: "invalid-ref", message: "CopyRef.id must be a non-empty string." }],
+            complete: false,
+        };
+    }
+    const validRef = ref;
+    if (validRef.locale !== undefined && validRef.locale !== validRegistry.locale) {
+        return {
+            issues: [
+                {
+                    reason: "locale-mismatch",
+                    id: validRef.id,
+                    message: `CopyRef "${validRef.id}" requests locale "${validRef.locale}", but this registry provides "${validRegistry.locale}".`,
+                },
+            ],
+            complete: false,
+        };
+    }
+    const entry = validRegistry.entries.find((candidate) => candidate.id === validRef.id);
+    if (!entry) {
+        return {
+            issues: [
+                { reason: "unknown-copy-id", id: validRef.id, message: `CopyRef "${validRef.id}" is not present in registry "${validRegistry.id}".` },
+            ],
+            complete: false,
+        };
+    }
+    if (entry.status !== "approved") {
+        return {
+            issues: [
+                {
+                    reason: "copy-not-approved",
+                    id: validRef.id,
+                    message: `CopyRef "${validRef.id}" is ${entry.status} and cannot be rendered until it is approved.`,
+                },
+            ],
+            complete: false,
+        };
+    }
+    const values = validRef.values ?? {};
+    const issues = [];
+    const declared = new Set(entry.placeholders ?? []);
+    for (const placeholder of declared) {
+        if (!Object.hasOwn(values, placeholder)) {
+            issues.push({
+                reason: "missing-placeholder-value",
+                id: validRef.id,
+                placeholder,
+                message: `CopyRef "${validRef.id}" is missing a value for required placeholder "${placeholder}".`,
+            });
+        }
+        else if (!isCopyValue(values[placeholder])) {
+            issues.push({
+                reason: "missing-placeholder-value",
+                id: validRef.id,
+                placeholder,
+                message: `CopyRef "${validRef.id}" has an invalid value for placeholder "${placeholder}".`,
+            });
+        }
+    }
+    for (const name of Object.keys(values)) {
+        if (!declared.has(name)) {
+            issues.push({
+                reason: "unexpected-placeholder-value",
+                id: validRef.id,
+                placeholder: name,
+                message: `CopyRef "${validRef.id}" supplies "${name}", which is not declared by that copy entry.`,
+            });
+        }
+    }
+    if (issues.length > 0)
+        return { issues, complete: false };
+    return {
+        resolution: {
+            ref: validRef,
+            text: interpolate(entry.text, values),
+            recordId: validRegistry.id,
+            revision: validRegistry.revision,
+            locale: validRegistry.locale,
+            source: validRegistry.source,
+            entryId: entry.id,
+        },
+        issues: [],
+        complete: true,
+    };
+}
+/** Creates the narrow resolver callback for presentation code. */
+export function createCopyResolver(registry) {
+    return (ref) => resolveCopyRef(registry, ref).resolution;
+}
+//# sourceMappingURL=resolve.js.map

package/dist/resolve.js.map

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