@clossys/writer 0.3.9 → 0.5.0

package/src/plan-rules.ts

@@ -0,0 +1,179 @@
+// The plan contract's code rules R1-R12 (issue #1178, read here for issue
+// #1586): the checks the contract's JSON Schema keywords cannot express,
+// because each one relates one field to another. They are defined once, as
+// prose in the description of the shared contract
+// docs/contracts/advisor-plan.json -- in the public repository, not shipped
+// in this package. This is @clossys/writer's own implementation, written from
+// that text; every other reader of a plan implements the rules separately,
+// and each is tested against one corpus,
+// docs/contracts/advisor-plan-rules.fixture.json (likewise in the public
+// repository, not shipped in this package), so a plan one of them accepts,
+// they all accept, and the reverse.
+//
+// These functions assume the value already passed the plan contract's
+// schema: plan-contract.ts runs them only then. A violation names its rule and
+// the position of the field at fault, never a value, because a plan can carry
+// founder text.
+
+import { ADVISOR_PLAN_CONTRACT } from "./generated/advisor-plan-contract.generated.js";
+
+/** A code rule of the plan contract. */
+export type PlanRuleId = "R1" | "R2" | "R3" | "R4" | "R5" | "R6" | "R7" | "R8" | "R9" | "R10" | "R11" | "R12";
+
+/**
+ * The roles whose package lives in the engagement hub only, read from the
+ * packed plan contract's `definitions.hubOnlyRoles`, the one list every
+ * reader of a plan uses. Code rules R2 and R11 use it. A packed contract
+ * without a well-formed list is a build defect, so loading this module throws
+ * rather than judge plans against a guess.
+ */
+export const HUB_ONLY_ROLES: readonly string[] = (() => {
+  const definitions = ADVISOR_PLAN_CONTRACT.definitions as Record<string, { const?: unknown }> | undefined;
+  const roles = definitions?.hubOnlyRoles?.const;
+  if (!Array.isArray(roles) || roles.some((role) => typeof role !== "string")) {
+    throw new Error("the packed plan contract has no well-formed definitions.hubOnlyRoles");
+  }
+  return Object.freeze([...(roles as string[])]);
+})();
+
+/**
+ * The members of a plan these rules and the authority read, and no more. A
+ * plan that passed the contract's schema has this shape; it is a structural
+ * view, not the contract, and it validates nothing.
+ */
+export interface PlanDocument {
+  readonly mandate: { readonly roles: readonly string[] };
+  readonly staffing?: readonly { readonly repository: string; readonly roles: readonly string[] }[];
+  readonly packages?: readonly {
+    readonly planItem: string;
+    readonly repository: string;
+    readonly act: string;
+    readonly name: string;
+    readonly placement: string;
+  }[];
+  readonly kits?: readonly { readonly id: string }[];
+  readonly resolution?: unknown;
+  readonly delegatedCopyApproval?: { readonly target: "production"; readonly scopes?: readonly string[] };
+  readonly decisions: readonly { readonly at: string; readonly chosen: string; readonly subjectDigest?: string }[];
+}
+
+export interface PlanRuleViolation {
+  readonly rule: PlanRuleId;
+  /** The field at fault, such as `staffing[1].repository`. */
+  readonly path: string;
+  /** What is wrong, by position only. */
+  readonly message: string;
+}
+
+/**
+ * The position of every item whose key an earlier item already had, with the
+ * position of the first item that had it. Items keep their order.
+ */
+function repeats(keys: readonly string[]): { index: number; first: number }[] {
+  const seenAt = new Map<string, number>();
+  const found: { index: number; first: number }[] = [];
+  keys.forEach((key, index) => {
+    const first = seenAt.get(key);
+    if (first === undefined) seenAt.set(key, index);
+    else found.push({ index, first });
+  });
+  return found;
+}
+
+/**
+ * A plan's own member, or undefined. The schema checker sees only own
+ * members, so these rules read only those too: a member inherited from a
+ * prototype is ignored, never judged.
+ */
+function ownMember<T extends object, K extends keyof T>(document: T, name: K): T[K] | undefined {
+  return Object.hasOwn(document, name) ? document[name] : undefined;
+}
+
+/** Every violation of R1-R12, for a plan that already passed the plan contract's schema. */
+export function planRuleViolations(plan: PlanDocument): PlanRuleViolation[] {
+  const found: PlanRuleViolation[] = [];
+  const report = (rule: PlanRuleId, path: string, message: string): void => {
+    found.push({ rule, path, message });
+  };
+  const staffing = ownMember(plan, "staffing");
+  const acts = ownMember(plan, "packages");
+  const kits = ownMember(plan, "kits");
+  const mandateRoles = plan.mandate.roles;
+  const lower = (text: string): string => text.toLowerCase();
+
+  if (staffing !== undefined) {
+    // R1: one staffing entry per repository; ids compare case-insensitively.
+    for (const { index, first } of repeats(staffing.map((entry) => lower(entry.repository)))) {
+      report("R1", `staffing[${index}].repository`, `names the same repository as staffing[${first}].repository (repository ids compare case-insensitively)`);
+    }
+
+    // R2: staffed roles and mandate roles agree in both directions; a hub-only role is never required to be staffed.
+    const mandated = new Set(mandateRoles);
+    const staffed = new Set(staffing.flatMap((entry) => entry.roles));
+    staffing.forEach((entry, index) => {
+      entry.roles.forEach((role, position) => {
+        if (!mandated.has(role)) report("R2", `staffing[${index}].roles[${position}]`, "is not one of mandate.roles");
+      });
+    });
+    mandateRoles.forEach((role, position) => {
+      if (!staffed.has(role) && !HUB_ONLY_ROLES.includes(role)) report("R2", `mandate.roles[${position}]`, "is not staffed in any staffing entry");
+    });
+
+    staffing.forEach((entry, index) => {
+      // R8: no role twice within one staffing entry.
+      for (const { index: position, first } of repeats(entry.roles)) {
+        report("R8", `staffing[${index}].roles[${position}]`, `repeats staffing[${index}].roles[${first}]`);
+      }
+      // R11: a hub-only role is never staffed in a repository.
+      entry.roles.forEach((role, position) => {
+        if (HUB_ONLY_ROLES.includes(role)) report("R11", `staffing[${index}].roles[${position}]`, "is a hub-only role, which works from the hub and is never staffed in a repository");
+      });
+    });
+  }
+
+  if (acts !== undefined) {
+    // R3: every act names a staffed repository, spelled exactly the same.
+    const staffedRepositories = new Set((staffing ?? []).map((entry) => entry.repository));
+    acts.forEach((act, index) => {
+      if (!staffedRepositories.has(act.repository)) report("R3", `packages[${index}].repository`, "is not spelled exactly as any staffing[].repository");
+    });
+    // R4: planItem ids are unique.
+    for (const { index, first } of repeats(acts.map((act) => act.planItem))) {
+      report("R4", `packages[${index}].planItem`, `repeats packages[${first}].planItem`);
+    }
+    // R5: one act per (repository, name); repositories compare case-insensitively.
+    for (const { index, first } of repeats(acts.map((act) => JSON.stringify([lower(act.repository), act.name])))) {
+      report("R5", `packages[${index}].name`, `repeats the repository and name of packages[${first}] (repositories compare case-insensitively)`);
+    }
+    // R12: every planItem is exactly its act's repository, a colon and its name, in the same letter case.
+    acts.forEach((act, index) => {
+      if (act.planItem !== `${act.repository}:${act.name}`) report("R12", `packages[${index}].planItem`, "is not this act's repository, a colon and its name, in the same letter case");
+    });
+    // R10: at most one pin-starter act per repository (compared case-insensitively), and it is a devDependency.
+    const pinAt = acts.flatMap((act, index) => (act.act === "pin-starter" ? [index] : []));
+    for (const { index, first } of repeats(pinAt.map((position) => lower(acts[position]!.repository)))) {
+      report("R10", `packages[${pinAt[index]}].act`, `is a second act of this kind for the repository of packages[${pinAt[first]}] (repositories compare case-insensitively)`);
+    }
+    for (const position of pinAt) {
+      if (acts[position]!.placement !== "devDependencies") report("R10", `packages[${position}].placement`, "must be devDependencies for a pin-starter act");
+    }
+  }
+
+  // R6: resolution is present exactly when packages is.
+  const hasPackages = Object.hasOwn(plan, "packages");
+  const hasResolution = Object.hasOwn(plan, "resolution");
+  if (hasPackages && !hasResolution) report("R6", "resolution", "is required when packages is present");
+  if (!hasPackages && hasResolution) report("R6", "resolution", "must be absent when there are no packages");
+
+  // R7: kit ids are unique.
+  for (const { index, first } of repeats((kits ?? []).map((kit) => kit.id))) {
+    report("R7", `kits[${index}].id`, `repeats kits[${first}].id`);
+  }
+
+  // R9: no role twice in mandate.roles.
+  for (const { index, first } of repeats(mandateRoles)) {
+    report("R9", `mandate.roles[${index}]`, `repeats mandate.roles[${first}]`);
+  }
+
+  return found;
+}

package/src/render-registry-parity.ts

@@ -0,0 +1,65 @@
+/**
+ * Ensures the registry file `writer-check` reads is the same store a surface
+ * passes to `createCopyResolver` at render — never a second, request-scoped
+ * module the CLI does not scan.
+ */
+
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { validateCopyRegistryShape } from "./schema.js";
+import type { CopyRegistry } from "./types.js";
+
+export type RenderRegistryParityReason =
+  | "render-registry-path-mismatch"
+  | "record-not-copy-registry";
+
+export interface RenderRegistryParityResult {
+  ok: boolean;
+  reason?: RenderRegistryParityReason;
+  detail?: string;
+  registry?: CopyRegistry;
+}
+
+/**
+ * Confirms `recordFile` is a `CopyRegistry` and, when `renderRegistryFile`
+ * is supplied, that both paths resolve to the same file (the render store
+ * and the gate store must be one file).
+ */
+export function checkRenderRegistryParity(
+  recordFile: string,
+  recordValue: unknown,
+  renderRegistryFile?: string,
+): RenderRegistryParityResult {
+  const registryFindings = validateCopyRegistryShape(recordValue);
+  if (registryFindings.length > 0) {
+    const detail = registryFindings.map((f) => f.message).join("; ");
+    return {
+      ok: false,
+      reason: "record-not-copy-registry",
+      detail: `record-file is not a CopyRegistry (the store createCopyResolver reads): ${detail}`,
+    };
+  }
+
+  if (renderRegistryFile !== undefined) {
+    const recordReal = safeRealpath(resolve(recordFile));
+    const renderReal = safeRealpath(resolve(renderRegistryFile));
+    if (recordReal !== renderReal) {
+      return {
+        ok: false,
+        reason: "render-registry-path-mismatch",
+        detail:
+          "record-file and --render-registry must be the same file — a second approved store the CLI does not read is not an approved registry.",
+      };
+    }
+  }
+
+  return { ok: true, registry: recordValue as CopyRegistry };
+}
+
+function safeRealpath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}

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