@clossys/writer 0.3.9 → 0.5.0

package/src/scan.ts

@@ -634,6 +634,14 @@ interface TokenizeResult {
   literals: Literal[];
   jsxTexts: JsxTextRun[];
   unchecked: RawUnchecked[];
+  /**
+   * Half-open `[start, end)` ranges of `content` that are NOT code: every
+   * comment, every string literal, every template literal's static segments
+   * (never its `${...}` interpolations, which are code), every regex literal
+   * body, and every JSX text run. Read only by `maskNonCode` below; every
+   * other caller ignores it.
+   */
+  opaque: Array<[number, number]>;
   /** Set when the scanner could not reach a consistent end-of-file state (unterminated string/template/comment, or a regex heuristic that desynced quote tracking). */
   failure?: string;
 }
@@ -687,6 +695,7 @@ function tokenize(content: string, isJsxFile: boolean): TokenizeResult {
   const literals: Literal[] = [];
   const jsxTexts: JsxTextRun[] = [];
   const unchecked: RawUnchecked[] = [];
+  const opaque: Array<[number, number]> = [];
   const n = content.length;
   let i = 0;
   let line = 1;
@@ -745,6 +754,7 @@ function tokenize(content: string, isJsxFile: boolean): TokenizeResult {
       }
       if (ck === '"' || ck === "'") {
         const q = ck;
+        const stringStart = j;
         j++;
         while (j < n && content[j] !== q) {
           if (content[j] === "\\") j++;
@@ -752,6 +762,7 @@ function tokenize(content: string, isJsxFile: boolean): TokenizeResult {
           j++;
         }
         j++; // consume closing quote, or run past EOF — caught by the outer unterminated-template check
+        opaque.push([stringStart, Math.min(j, n)]);
         continue;
       }
       if (ck === "`") {
@@ -762,6 +773,7 @@ function tokenize(content: string, isJsxFile: boolean): TokenizeResult {
       }
       if (ck === "/" && content[j + 1] === "/") {
         const nl = content.indexOf("\n", j);
+        opaque.push([j, nl === -1 ? n : nl]);
         j = nl === -1 ? n : nl;
         continue;
       }
@@ -769,6 +781,7 @@ function tokenize(content: string, isJsxFile: boolean): TokenizeResult {
         const close = content.indexOf("*/", j + 2);
         if (close === -1) return -1;
         advanceLine(j, close + 2);
+        opaque.push([j, close + 2]);
         j = close + 2;
         continue;
       }
@@ -780,22 +793,28 @@ function tokenize(content: string, isJsxFile: boolean): TokenizeResult {
   /** Skips an entire template literal starting at `pos` (`content[pos] === "\`"`), including every interpolation it contains, recursively. Returns the index one past its closing backtick, or `-1` if unterminated. */
   function skipTemplateFrom(pos: number): number {
     let j = pos + 1;
+    let segmentStart = pos;
     while (j < n) {
       const cj = content[j] as string;
       if (cj === "\\" && j + 1 < n) {
         j += 2;
         continue;
       }
-      if (cj === "`") return j + 1;
+      if (cj === "`") {
+        opaque.push([segmentStart, j + 1]);
+        return j + 1;
+      }
       if (cj === "\n") {
         line++;
         j++;
         continue;
       }
       if (cj === "$" && content[j + 1] === "{") {
+        opaque.push([segmentStart, j]);
         const next = skipInterpolation(j + 2);
         if (next === -1) return -1;
         j = next;
+        segmentStart = j;
         continue;
       }
       j++;
@@ -858,6 +877,7 @@ function tokenize(content: string, isJsxFile: boolean): TokenizeResult {
       literalFailure = `unterminated string starting at line ${startLine}`;
       return -1;
     }
+    opaque.push([start, j]);
     literals.push({
       kind: "string",
       line: startLine,
@@ -892,6 +912,7 @@ function tokenize(content: string, isJsxFile: boolean): TokenizeResult {
     let j = pos + 1;
     let current = "";
     let closed = false;
+    let segmentStart = pos;
     while (j < n) {
       const cj = content[j] as string;
       if (cj === "\\" && j + 1 < n) {
@@ -905,6 +926,7 @@ function tokenize(content: string, isJsxFile: boolean): TokenizeResult {
         break;
       }
       if (cj === "$" && content[j + 1] === "{") {
+        opaque.push([segmentStart, j]);
         staticParts.push(unescape(current));
         current = "";
         placeholderCount++;
@@ -920,6 +942,7 @@ function tokenize(content: string, isJsxFile: boolean): TokenizeResult {
           return -1;
         }
         j = next;
+        segmentStart = j;
         continue;
       }
       if (cj === "\n") line++;
@@ -931,6 +954,7 @@ function tokenize(content: string, isJsxFile: boolean): TokenizeResult {
       return -1;
     }
     staticParts.push(unescape(current));
+    opaque.push([segmentStart, j]);
     literals.push({
       kind: "template",
       line: startLine,
@@ -981,6 +1005,7 @@ function tokenize(content: string, isJsxFile: boolean): TokenizeResult {
       }
       if (cj === "/" && content[j + 1] === "/") {
         const nl = content.indexOf("\n", j);
+        opaque.push([j, nl === -1 ? n : nl]);
         j = nl === -1 ? n : nl;
         continue;
       }
@@ -988,6 +1013,7 @@ function tokenize(content: string, isJsxFile: boolean): TokenizeResult {
         const close = content.indexOf("*/", j + 2);
         if (close === -1) return -1;
         advanceLine(j, close + 2);
+        opaque.push([j, close + 2]);
         j = close + 2;
         continue;
       }
@@ -1079,6 +1105,7 @@ function tokenize(content: string, isJsxFile: boolean): TokenizeResult {
           if (found !== -1) {
             let m = found + 1;
             while (m < n && /[a-z]/i.test(content[m] as string)) m++;
+            opaque.push([j, m]);
             j = m;
             localLast = "value";
             continue;
@@ -1116,7 +1143,10 @@ function tokenize(content: string, isJsxFile: boolean): TokenizeResult {
     const flush = (): void => {
       if (j > runStart) {
         const raw = content.slice(runStart, j);
-        if (raw.trim().length > 0) jsxTexts.push({ line: runStartLine, raw });
+        if (raw.trim().length > 0) {
+          jsxTexts.push({ line: runStartLine, raw });
+          opaque.push([runStart, j]);
+        }
       }
     };
 
@@ -1268,12 +1298,14 @@ function tokenize(content: string, isJsxFile: boolean): TokenizeResult {
     const entryLiteralsCount = literals.length;
     const entryJsxTextsCount = jsxTexts.length;
     const entryUncheckedCount = unchecked.length;
+    const entryOpaqueCount = opaque.length;
 
     function backtrack(): null {
       line = entryLine;
       literals.length = entryLiteralsCount;
       jsxTexts.length = entryJsxTextsCount;
       unchecked.length = entryUncheckedCount;
+      opaque.length = entryOpaqueCount;
       return null;
     }
 
@@ -1339,6 +1371,7 @@ function tokenize(content: string, isJsxFile: boolean): TokenizeResult {
         // above.
         if (cj === "/" && content[j + 1] === "/") {
           const nl = content.indexOf("\n", j);
+          opaque.push([j, nl === -1 ? n : nl]);
           j = nl === -1 ? n : nl;
           continue;
         }
@@ -1346,6 +1379,7 @@ function tokenize(content: string, isJsxFile: boolean): TokenizeResult {
           const close = content.indexOf("*/", j + 2);
           if (close === -1) return backtrack(); // unterminated block comment — not committed, silently not-JSX
           advanceLine(j, close + 2);
+          opaque.push([j, close + 2]);
           j = close + 2;
           continue;
         }
@@ -1456,6 +1490,7 @@ function tokenize(content: string, isJsxFile: boolean): TokenizeResult {
     // line comment
     if (c === "/" && content[i + 1] === "/") {
       const nl = content.indexOf("\n", i);
+      opaque.push([i, nl === -1 ? n : nl]);
       i = nl === -1 ? n : nl;
       continue;
     }
@@ -1463,8 +1498,9 @@ function tokenize(content: string, isJsxFile: boolean): TokenizeResult {
     // block comment
     if (c === "/" && content[i + 1] === "*") {
       const close = content.indexOf("*/", i + 2);
-      if (close === -1) return { literals, jsxTexts, unchecked, failure: `unterminated block comment starting at line ${line}` };
+      if (close === -1) return { literals, jsxTexts, unchecked, opaque, failure: `unterminated block comment starting at line ${line}` };
       advanceLine(i, close + 2);
+      opaque.push([i, close + 2]);
       i = close + 2;
       continue;
     }
@@ -1472,7 +1508,7 @@ function tokenize(content: string, isJsxFile: boolean): TokenizeResult {
     // string literal
     if (c === '"' || c === "'") {
       const end = scanStringLiteral(i);
-      if (end === -1) return { literals, jsxTexts, unchecked, failure: literalFailure };
+      if (end === -1) return { literals, jsxTexts, unchecked, opaque, failure: literalFailure };
       lastTokenType = "value";
       i = end;
       continue;
@@ -1481,7 +1517,7 @@ function tokenize(content: string, isJsxFile: boolean): TokenizeResult {
     // template literal
     if (c === "`") {
       const end = scanTemplateLiteral(i);
-      if (end === -1) return { literals, jsxTexts, unchecked, failure: literalFailure };
+      if (end === -1) return { literals, jsxTexts, unchecked, opaque, failure: literalFailure };
       lastTokenType = "value";
       i = end;
       continue;
@@ -1540,6 +1576,7 @@ function tokenize(content: string, isJsxFile: boolean): TokenizeResult {
         if (found !== -1) {
           let k = found + 1;
           while (k < n && /[a-z]/i.test(content[k] as string)) k++;
+          opaque.push([i, k]);
           i = k;
           lastTokenType = "value";
           continue;
@@ -1581,7 +1618,7 @@ function tokenize(content: string, isJsxFile: boolean): TokenizeResult {
     i++;
   }
 
-  return { literals, jsxTexts, unchecked };
+  return { literals, jsxTexts, unchecked, opaque };
 }
 
 // ---------------------------------------------------------- classification
@@ -1988,3 +2025,57 @@ export function extractCopyCandidates(content: string, filePath: string): Extrac
 
   return { candidates, excluded, citations, unchecked };
 }
+
+/** One string or template literal `maskNonCode` found, with its position in the original content. */
+export interface MaskedLiteral {
+  kind: "string" | "template";
+  line: number;
+  /** Index of the opening quote/backtick. */
+  start: number;
+  /** Index one past the closing quote/backtick. */
+  end: number;
+  raw: string;
+  /** The literal's static text, unescaped; a template's interpolations are dropped. */
+  text: string;
+}
+
+/** `maskNonCode`'s result. `code` has the same length and line breaks as the input. */
+export interface CodeMask {
+  code: string;
+  literals: MaskedLiteral[];
+  failure?: string;
+}
+
+/**
+ * Pure. Runs this file's tokenizer over `content` and returns a copy of it in
+ * which every comment, string literal, template static segment, regex literal
+ * and (in a `.tsx`/`.jsx` file) JSX text run is replaced by spaces, keeping
+ * every newline and every character offset. A caller can then match code
+ * patterns against `code` without a comment or a string ever matching, and
+ * look up the literal at a given offset through `literals`. A template's
+ * `${...}` interpolations stay visible in `code`, because they are code.
+ *
+ * Exported for `approval-bypass.ts` so it delegates literal and comment
+ * boundaries to this tokenizer instead of growing a second one. Deliberately
+ * not re-exported from `index.ts`: it is an internal helper, not package API.
+ */
+export function maskNonCode(content: string, filePath: string): CodeMask {
+  const { literals, opaque, failure } = tokenize(content, JSX_FILE_RE.test(filePath));
+  const masked = content.split("");
+  if (!failure) {
+    for (const [start, end] of opaque) {
+      for (let k = start; k < end && k < masked.length; k++) {
+        if (masked[k] !== "\n") masked[k] = " ";
+      }
+    }
+  }
+  const out: MaskedLiteral[] = literals.map((lit) => ({
+    kind: lit.kind,
+    line: lit.line,
+    start: lit.start,
+    end: lit.end,
+    raw: lit.raw,
+    text: lit.staticParts.join(""),
+  }));
+  return failure ? { code: masked.join(""), literals: out, failure } : { code: masked.join(""), literals: out };
+}

package/src/schema.ts

@@ -34,6 +34,8 @@ import type {
   CopyRecord,
   CopySource,
 } from "./types.js";
+import { COPY_FINGERPRINT_ALGORITHM } from "./fingerprint.js";
+import { isDelegateScopeItem, isEntryInDelegateScope } from "./approval.js";
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -121,6 +123,8 @@ function validateCopyEntryShape(value: unknown, path: string): CopyFinding[] {
   const context = value.context;
   const placeholders = value.placeholders;
   const factRef = value.factRef;
+  const treatment = value.treatment;
+  const maxWords = value.maxWords;
 
   const findings: CopyFinding[] = [];
 
@@ -189,6 +193,26 @@ function validateCopyEntryShape(value: unknown, path: string): CopyFinding[] {
     });
   }
 
+  if (treatment !== undefined && !isNonEmptyString(treatment)) {
+    findings.push({
+      rule: "treatment-shape",
+      severity: "error",
+      message: `${path}.treatment must be a non-empty string when present, got ${JSON.stringify(treatment)}.`,
+      path: `${path}.treatment`,
+    });
+  }
+
+  if (maxWords !== undefined) {
+    if (typeof maxWords !== "number" || !Number.isFinite(maxWords) || maxWords < 1) {
+      findings.push({
+        rule: "max-words-shape",
+        severity: "error",
+        message: `${path}.maxWords must be a positive finite number when present, got ${JSON.stringify(maxWords)}.`,
+        path: `${path}.maxWords`,
+      });
+    }
+  }
+
   return findings;
 }
 
@@ -361,6 +385,207 @@ function validateTranslationShape(value: unknown, path: string): CopyFinding[] {
   return findings;
 }
 
+/**
+ * `YYYY-MM-DDTHH:MM:SS(.sss)?Z` — the one ISO 8601 UTC shape this package
+ * accepts for `approvedAt`/`expiresAt`. Also requires `Date.parse` to
+ * actually accept it, so a string that merely matches the pattern but names
+ * an impossible date (e.g. a bad month) is still rejected.
+ */
+const ISO_UTC_TIMESTAMP_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/;
+
+export function isIsoUtcTimestamp(value: unknown): value is string {
+  if (typeof value !== "string" || !ISO_UTC_TIMESTAMP_RE.test(value)) return false;
+  const year = Number(value.slice(0, 4));
+  const month = Number(value.slice(5, 7));
+  const day = Number(value.slice(8, 10));
+  const parsed = Date.parse(value);
+  if (Number.isNaN(parsed)) return false;
+  const utc = new Date(parsed);
+  return utc.getUTCFullYear() === year && utc.getUTCMonth() + 1 === month && utc.getUTCDate() === day;
+}
+
+/** `textFingerprint` shape: a `sha256` hex digest — 64 lowercase hex characters. */
+const COPY_FINGERPRINT_RE = /^[0-9a-f]{64}$/;
+
+/**
+ * Validates a `CopyRegistryEntry.approval` field, when present. `undefined`
+ * is always valid, on any entry — an entry with no approval record keeps
+ * resolving exactly as it did before this field existed. Staleness (does
+ * `textFingerprint` still match the entry's current `text`) and expiry
+ * against "now" are runtime concerns for the resolver (`resolve.ts`) and
+ * `assessCopyApprovals` (`approval.ts`), never shape findings here: a
+ * registry with a stale or expired record is still a well-formed
+ * `CopyRegistry`.
+ */
+function validateApprovalShape(value: unknown, entryStatus: unknown, entryId: unknown, path: string): CopyFinding[] {
+  if (value === undefined) return [];
+  if (!isPlainObject(value)) {
+    return [
+      {
+        rule: "approval-shape",
+        severity: "error",
+        message: `${path} must be an object when present, got ${JSON.stringify(value)}.`,
+        path,
+      },
+    ];
+  }
+
+  const approvedBy = value.approvedBy;
+  const approvedAt = value.approvedAt;
+  const textFingerprint = value.textFingerprint;
+  const fingerprintAlgorithm = value.fingerprintAlgorithm;
+  const delegate = value.delegate;
+  const pendingOwnerReview = value.pendingOwnerReview;
+  const expiresAt = value.expiresAt;
+
+  const findings: CopyFinding[] = [];
+
+  if (entryStatus !== "approved") {
+    findings.push({
+      rule: "approval-status-mismatch",
+      severity: "error",
+      message: `${path} is present but the entry's status is ${JSON.stringify(entryStatus)}, not "approved".`,
+      path,
+    });
+  }
+
+  const isDelegateRecord = approvedBy === "delegate";
+
+  if (approvedBy !== "owner" && approvedBy !== "delegate") {
+    findings.push({
+      rule: "approval-approved-by",
+      severity: "error",
+      message: `${path}.approvedBy must be "owner" or "delegate", got ${JSON.stringify(approvedBy)}.`,
+      path: `${path}.approvedBy`,
+    });
+  }
+
+  if (!isIsoUtcTimestamp(approvedAt)) {
+    findings.push({
+      rule: "approval-approved-at-shape",
+      severity: "error",
+      message: `${path}.approvedAt must be an ISO 8601 UTC timestamp, got ${JSON.stringify(approvedAt)}.`,
+      path: `${path}.approvedAt`,
+    });
+  }
+
+  if (typeof textFingerprint !== "string" || !COPY_FINGERPRINT_RE.test(textFingerprint)) {
+    findings.push({
+      rule: "approval-fingerprint-shape",
+      severity: "error",
+      message: `${path}.textFingerprint must be a 64-character lowercase hex string, got ${JSON.stringify(textFingerprint)}.`,
+      path: `${path}.textFingerprint`,
+    });
+  }
+
+  if (fingerprintAlgorithm !== COPY_FINGERPRINT_ALGORITHM) {
+    findings.push({
+      rule: "approval-fingerprint-shape",
+      severity: "error",
+      message: `${path}.fingerprintAlgorithm must be ${JSON.stringify(COPY_FINGERPRINT_ALGORITHM)}, got ${JSON.stringify(fingerprintAlgorithm)}.`,
+      path: `${path}.fingerprintAlgorithm`,
+    });
+  }
+
+  if (isDelegateRecord && delegate === undefined) {
+    findings.push({
+      rule: "approval-delegate-required",
+      severity: "error",
+      message: `${path}.delegate is required when approvedBy is "delegate".`,
+      path: `${path}.delegate`,
+    });
+  }
+
+  if (approvedBy === "owner") {
+    (["delegate", "pendingOwnerReview", "expiresAt"] as const).forEach((field) => {
+      if (value[field] !== undefined) {
+        findings.push({
+          rule: "approval-delegate-forbidden",
+          severity: "error",
+          message: `${path}.${field} is forbidden when approvedBy is "owner".`,
+          path: `${path}.${field}`,
+        });
+      }
+    });
+  }
+
+  // The remaining checks (scope shape, scope membership, pendingOwnerReview,
+  // expiresAt) only make sense on an actual delegate record — on an owner
+  // record any of these fields is already reported above as forbidden, and
+  // shape-checking a field that should not exist would only add noise.
+  if (!isDelegateRecord) return findings;
+
+  let scopeIsValid = false;
+  if (!isPlainObject(delegate)) {
+    if (delegate !== undefined) {
+      findings.push({
+        rule: "approval-delegate-scope-shape",
+        severity: "error",
+        message: `${path}.delegate must be an object, got ${JSON.stringify(delegate)}.`,
+        path: `${path}.delegate`,
+      });
+    }
+  } else {
+    const delegateId = delegate.id;
+    const scope = delegate.scope;
+    const idIsValid = isNonEmptyString(delegateId);
+    const scopeIsArrayOfItems = Array.isArray(scope) && scope.length > 0 && scope.every((item) => isDelegateScopeItem(item));
+    if (!idIsValid || !scopeIsArrayOfItems) {
+      findings.push({
+        rule: "approval-delegate-scope-shape",
+        severity: "error",
+        message: `${path}.delegate must have a non-empty string id and a non-empty array scope of well-formed namespace items, got ${JSON.stringify(delegate)}.`,
+        path: `${path}.delegate`,
+      });
+    } else {
+      scopeIsValid = true;
+    }
+
+    if (scopeIsValid && typeof entryId === "string" && !isEntryInDelegateScope(entryId, scope as string[])) {
+      findings.push({
+        rule: "approval-outside-delegate-scope",
+        severity: "error",
+        message: `${path}.delegate scope ${JSON.stringify(scope)} does not cover entry id ${JSON.stringify(entryId)}.`,
+        path: `${path}.delegate`,
+      });
+    }
+  }
+
+  if (typeof pendingOwnerReview !== "boolean") {
+    findings.push({
+      rule: "approval-pending-review-shape",
+      severity: "error",
+      message: `${path}.pendingOwnerReview must be a boolean when approvedBy is "delegate", got ${JSON.stringify(pendingOwnerReview)}.`,
+      path: `${path}.pendingOwnerReview`,
+    });
+  }
+
+  let expiresAtIsValid = false;
+  if (expiresAt !== undefined) {
+    if (!isIsoUtcTimestamp(expiresAt)) {
+      findings.push({
+        rule: "approval-expires-at-shape",
+        severity: "error",
+        message: `${path}.expiresAt must be an ISO 8601 UTC timestamp when present, got ${JSON.stringify(expiresAt)}.`,
+        path: `${path}.expiresAt`,
+      });
+    } else {
+      expiresAtIsValid = true;
+    }
+  }
+
+  if (expiresAtIsValid && isIsoUtcTimestamp(approvedAt) && Date.parse(expiresAt as string) <= Date.parse(approvedAt)) {
+    findings.push({
+      rule: "approval-expires-before-approved",
+      severity: "error",
+      message: `${path}.expiresAt ${JSON.stringify(expiresAt)} must be strictly after ${path}.approvedAt ${JSON.stringify(approvedAt)}.`,
+      path: `${path}.expiresAt`,
+    });
+  }
+
+  return findings;
+}
+
 /**
  * Validates the stronger registry shape used to resolve `CopyRef`s. A plain
  * `CopyRecord` deliberately remains valid for source scanning and voice
@@ -434,6 +659,7 @@ export function validateCopyRegistryShape(value: unknown): CopyFinding[] {
         });
       }
       findings.push(...validateTranslationShape(entry.translation, `entries.${i}.translation`));
+      findings.push(...validateApprovalShape(entry.approval, entry.status, entry.id, `entries.${i}.approval`));
     });
   }
 
@@ -461,6 +687,8 @@ function buildCopyRecord(value: Record<string, unknown>): CopyRecord {
       context: entry.context as string,
       placeholders: [...((entry.placeholders as string[] | undefined) ?? [])],
       factRef: entry.factRef as string | undefined,
+      treatment: entry.treatment as string | undefined,
+      maxWords: entry.maxWords as number | undefined,
     };
   });
 
@@ -472,11 +700,25 @@ function buildCopyRecord(value: Record<string, unknown>): CopyRecord {
 
 function buildCopyRegistry(value: Record<string, unknown>): CopyRegistry {
   const record = buildCopyRecord(value);
-  const entries = (value.entries as Array<Record<string, unknown>>).map((entry) => ({
-    ...record.entries.find((item) => item.id === entry.id)!,
-    status: entry.status as CopyEntryStatus,
-    translation: entry.translation as CopyRegistryEntry["translation"],
-  })) as CopyRegistryEntry[];
+  const entries = (value.entries as Array<Record<string, unknown>>).map((entry) => {
+    const built: CopyRegistryEntry = {
+      ...record.entries.find((item) => item.id === entry.id)!,
+      status: entry.status as CopyEntryStatus,
+      translation: entry.translation as CopyRegistryEntry["translation"],
+    };
+    // Only copy `approval` when the input entry actually has one — an
+    // `approval: undefined` key would still make `"approval" in entry` true,
+    // breaking the "no record at all" case `resolve.ts` and `approval.ts`
+    // both depend on. Copied defensively (a fresh `delegate.scope` array) so
+    // the parsed registry never aliases the caller's own input object.
+    if (entry.approval !== undefined) {
+      const approval = entry.approval as CopyRegistryEntry["approval"];
+      built.approval = approval?.delegate
+        ? { ...approval, delegate: { ...approval.delegate, scope: [...approval.delegate.scope] } }
+        : { ...approval! };
+    }
+    return built;
+  });
 
   return {
     ...record,