@clossys/writer 0.4.0 → 0.5.1

package/src/resolve.ts

@@ -7,16 +7,29 @@
  * 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.
+ *
+ * Target policy: an owner-approved entry resolves on both `"preview"` and
+ * `"production"` (the default target). A delegate-approved entry resolves
+ * freely on `"preview"`, but on `"production"` is refused
+ * (`delegate-approval-refused`) unless the caller opts in with
+ * `acceptDelegateInProduction: true`, or passes `approvalPlan`, the bytes of
+ * a plan whose latest approval names that plan's own digest and which
+ * declares `delegatedCopyApproval` covering the entry — a delegate's sign-off
+ * is not, by itself, sufficient evidence to publish, only to preview.
  */
 
 import type {
   CopyRef,
   CopyRegistry,
   CopyResolution,
+  CopyResolutionApproval,
   CopyResolver,
   CopyValue,
 } from "./types.js";
 import { validateCopyRegistryShape } from "./schema.js";
+import { isApprovalExpired, isApprovalStale, isEntryInDelegateScope } from "./approval.js";
+import { isPlanBytes, planDelegateCopyAuthority } from "./plan-authority.js";
+import type { PlanDelegateCopyRefusal } from "./plan-authority.js";
 
 export type CopyResolveIssueReason =
   | "invalid-registry"
@@ -25,13 +38,43 @@ export type CopyResolveIssueReason =
   | "unknown-copy-id"
   | "copy-not-approved"
   | "missing-placeholder-value"
-  | "unexpected-placeholder-value";
+  | "unexpected-placeholder-value"
+  | "invalid-options"
+  | "approval-stale"
+  | "approval-expired"
+  | "delegate-approval-refused";
+
+/** Which audience a resolution is for — see this file's top doc comment for the policy difference. */
+export type CopyResolveTarget = "preview" | "production";
+
+/** Options controlling how strictly `resolveCopyRef`/`createCopyResolver` treat an entry's approval record. */
+export interface CopyResolveOptions {
+  /** Defaults to `"production"`. */
+  target?: CopyResolveTarget;
+  /** Defaults to `false`. Only meaningful when `target` is `"production"`. */
+  acceptDelegateInProduction?: boolean;
+  /** Defaults to `new Date()`, evaluated per call. */
+  now?: Date;
+  /**
+   * The bytes of an Advisor plan record (a `Uint8Array`; Node's `Buffer` is
+   * one), read by the caller. Consulted only for a delegate-approved entry on
+   * `"production"` when `acceptDelegateInProduction` is not `true`: see
+   * `planDelegateCopyAuthority()`. Not a `Uint8Array`, or given together with
+   * `acceptDelegateInProduction: true`, is `"invalid-options"`.
+   */
+  approvalPlan?: Uint8Array;
+}
+
+/** Why an `approvalPlan` did not authorize an entry: the plan's own refusal, or that the entry is outside the scopes the plan declares. */
+export type CopyResolvePlanRefusal = PlanDelegateCopyRefusal | "entry-outside-plan-scopes";
 
 export interface CopyResolveIssue {
   reason: CopyResolveIssueReason;
   message: string;
   id?: string;
   placeholder?: string;
+  /** Only on `"delegate-approval-refused"` when an `approvalPlan` was given: why it did not authorize this entry. */
+  planRefusal?: CopyResolvePlanRefusal;
 }
 
 export interface CopyResolveResult {
@@ -56,13 +99,60 @@ function interpolate(text: string, values: Readonly<Record<string, CopyValue>>):
   return text.replace(/\{([^{}]+)\}/g, (_match, name: string) => String(values[name]!));
 }
 
+/** The options a call runs with, each read from the caller's object exactly once. */
+interface ResolveSettings {
+  target: CopyResolveTarget;
+  acceptDelegateInProduction: boolean;
+  now: Date;
+  approvalPlan: Uint8Array | undefined;
+}
+
+/**
+ * Reads a well-formed `CopyResolveOptions`, or returns null — checked before
+ * anything else so a malformed caller-supplied options object fails closed
+ * rather than silently falling back to defaults. Each property is read
+ * exactly once, into a local that is validated and then used, so a getter
+ * cannot answer differently at validation and at use.
+ */
+function readResolveOptions(value: unknown): ResolveSettings | null {
+  if (value === undefined) return { target: "production", acceptDelegateInProduction: false, now: new Date(), approvalPlan: undefined };
+  if (!isPlainObject(value)) return null;
+  const { target, acceptDelegateInProduction, now, approvalPlan } = value;
+  if (target !== undefined && target !== "preview" && target !== "production") return null;
+  if (acceptDelegateInProduction !== undefined && typeof acceptDelegateInProduction !== "boolean") return null;
+  if (now !== undefined && !(now instanceof Date && Number.isFinite(now.getTime()))) return null;
+  if (approvalPlan !== undefined && !isPlanBytes(approvalPlan)) return null;
+  // Two authorities for one decision is an ambiguity, so it is refused: no precedence needs defining.
+  if (approvalPlan !== undefined && acceptDelegateInProduction === true) return null;
+  return {
+    target: target ?? "production",
+    acceptDelegateInProduction: acceptDelegateInProduction ?? false,
+    now: now ?? new Date(),
+    approvalPlan,
+  };
+}
+
 /**
  * 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.
+ * lifecycle failure, locale mismatch, staleness/expiry, delegate-in-production
+ * refusal, 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: CopyRegistry | unknown, ref: CopyRef | unknown): CopyResolveResult {
+export function resolveCopyRef(
+  registry: CopyRegistry | unknown,
+  ref: CopyRef | unknown,
+  options?: CopyResolveOptions | unknown,
+): CopyResolveResult {
+  const settings = readResolveOptions(options);
+  if (settings === null) {
+    return {
+      issues: [{ reason: "invalid-options", message: "CopyResolveOptions is malformed." }],
+      complete: false,
+    };
+  }
+  const { target, acceptDelegateInProduction, now, approvalPlan } = settings;
+
   const registryFindings = validateCopyRegistryShape(registry);
   if (registryFindings.length > 0) {
     return {
@@ -119,6 +209,69 @@ export function resolveCopyRef(registry: CopyRegistry | unknown, ref: CopyRef |
     };
   }
 
+  const approval = entry.approval;
+  // Set only when an approvalPlan, not the flag, authorized a delegate entry on production.
+  let authorizingPlanDigest: string | undefined;
+  if (approval) {
+    if (isApprovalStale(entry)) {
+      return {
+        issues: [
+          {
+            reason: "approval-stale",
+            id: validRef.id,
+            message: `CopyRef "${validRef.id}"'s approval record no longer matches its current text.`,
+          },
+        ],
+        complete: false,
+      };
+    }
+    if (isApprovalExpired(approval, now)) {
+      return {
+        issues: [
+          {
+            reason: "approval-expired",
+            id: validRef.id,
+            message: `CopyRef "${validRef.id}"'s approval expired at ${approval.expiresAt}.`,
+          },
+        ],
+        complete: false,
+      };
+    }
+    if (approval.approvedBy === "delegate" && target === "production" && acceptDelegateInProduction !== true) {
+      // The flag did not authorize this entry, so only a plan can. The plan is
+      // read here and nowhere else: never for preview, an owner entry, a
+      // record-less entry, or once the flag is true, and never before the
+      // entry's own staleness and expiry, which outrank it.
+      if (approvalPlan === undefined) {
+        return {
+          issues: [
+            {
+              reason: "delegate-approval-refused",
+              id: validRef.id,
+              message: `CopyRef "${validRef.id}" was approved by a delegate; production resolution requires acceptDelegateInProduction: true.`,
+            },
+          ],
+          complete: false,
+        };
+      }
+      const planRefused = (code: CopyResolvePlanRefusal): CopyResolveResult => ({
+        issues: [
+          {
+            reason: "delegate-approval-refused",
+            id: validRef.id,
+            planRefusal: code,
+            message: `CopyRef "${validRef.id}" was approved by a delegate; the approvalPlan given does not authorize it on production (${code}).`,
+          },
+        ],
+        complete: false,
+      });
+      const authority = planDelegateCopyAuthority(approvalPlan);
+      if (!authority.authorized) return planRefused(authority.refusal);
+      if (authority.scopes !== undefined && !isEntryInDelegateScope(entry.id, authority.scopes)) return planRefused("entry-outside-plan-scopes");
+      authorizingPlanDigest = authority.planDigest;
+    }
+  }
+
   const values = validRef.values ?? {};
   const issues: CopyResolveIssue[] = [];
   const declared = new Set(entry.placeholders ?? []);
@@ -151,22 +304,35 @@ export function resolveCopyRef(registry: CopyRegistry | unknown, ref: CopyRef |
   }
   if (issues.length > 0) return { issues, complete: false };
 
-  return {
-    resolution: {
-      ref: validRef as unknown as CopyRef,
-      text: interpolate(entry.text, values as Readonly<Record<string, CopyValue>>),
-      recordId: validRegistry.id,
-      revision: validRegistry.revision,
-      locale: validRegistry.locale,
-      source: validRegistry.source,
-      entryId: entry.id,
-    },
-    issues: [],
-    complete: true,
+  const resolution: CopyResolution = {
+    ref: validRef as unknown as CopyRef,
+    text: interpolate(entry.text, values as Readonly<Record<string, CopyValue>>),
+    recordId: validRegistry.id,
+    revision: validRegistry.revision,
+    locale: validRegistry.locale,
+    source: validRegistry.source,
+    entryId: entry.id,
   };
+  // Only set when the entry actually carries a record — an approved entry
+  // with no record resolves exactly as it did before this field existed,
+  // with no `approval` key on the resolution at all.
+  if (approval) {
+    // Built explicitly, so the digest key exists only when a plan authorized the entry.
+    const facts: CopyResolutionApproval =
+      approval.approvedBy === "owner"
+        ? { approvedBy: "owner", pendingOwnerReview: false }
+        : {
+            approvedBy: "delegate",
+            pendingOwnerReview: approval.pendingOwnerReview === true,
+            ...(authorizingPlanDigest === undefined ? {} : { authorizingPlanDigest }),
+          };
+    resolution.approval = facts;
+  }
+
+  return { resolution, issues: [], complete: true };
 }
 
 /** Creates the narrow resolver callback for presentation code. */
-export function createCopyResolver(registry: CopyRegistry | unknown): CopyResolver {
-  return (ref) => resolveCopyRef(registry, ref).resolution;
+export function createCopyResolver(registry: CopyRegistry | unknown, options?: CopyResolveOptions | unknown): CopyResolver {
+  return (ref) => resolveCopyRef(registry, ref, options).resolution;
 }

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 };
+}