@clossys/writer 0.3.8 → 0.4.0

package/src/addressability.ts

@@ -157,8 +157,8 @@
  *     position classified, and no inline user-facing prose found.
  */
 
-import { readdirSync, readFileSync, statSync } from "node:fs";
-import { extname, join, relative, sep } from "node:path";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { extractCopyCandidates } from "./scan.js";
 import type { ParseFailure, SkippedFile } from "./scan.js";
 import {
@@ -182,6 +182,12 @@ export interface AddressabilityScanOptions {
   skipDirs?: string[];
   /** Same mechanism `scan.ts`'s `ScanOptions.pathExclusions` uses — see `path-exclusions.ts`. */
   pathExclusions?: PathExclusion[];
+  /**
+   * Consumer-declared persistent chrome (site header, footer, skip link, nav
+   * labels) — shell or layout files scanned in addition to the directory walk.
+   * Paths are relative to `root` unless absolute. Each file must exist.
+   */
+  chromeFiles?: string[];
 }
 
 const DEFAULT_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx"];
@@ -190,7 +196,7 @@ const DEFAULT_SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", "cov
 /** `.test.ts(x)`, `.spec.ts(x)`, `.check.ts(x)`, and bare `.d.ts` — the identical pattern `scan.ts` and `@example/ui`'s `style-scan.ts` both use, reused verbatim rather than reinvented (not exported by `scan.ts`, so redefined locally here — the same precedent `style-scan.ts` sets for its own copy of this constant). */
 const SKIP_FILE_RE = /\.(test|spec|check)\.(ts|tsx|js|jsx)$|\.d\.ts$/;
 
-export type AddressabilityPosition = "markup-text" | "user-facing-attribute";
+export type AddressabilityPosition = "markup-text" | "user-facing-attribute" | "object-literal-copy";
 
 export interface AddressabilityViolation {
   file: string;
@@ -198,6 +204,10 @@ export interface AddressabilityViolation {
   position: AddressabilityPosition;
   /** Set only for `"user-facing-attribute"` — which of the four this literal was the value of. */
   attribute?: "aria-label" | "placeholder" | "alt" | "title";
+  /** Set only for `"object-literal-copy"` — the property key this literal was the value of. */
+  objectKey?: string;
+  /** Set only for `"object-literal-copy"` — dotted/bracket path when nested under `items`/`nav`/`links`. */
+  keyPath?: string;
   /** The literal's own raw source text, for a human auditing the finding. */
   raw: string;
 }
@@ -316,6 +326,12 @@ export function scanAddressabilitySources(root: string, options: AddressabilityS
 
   walk(root);
 
+  if (options.chromeFiles !== undefined) {
+    for (const chromePath of options.chromeFiles) {
+      scanAddressabilityChromeFile(root, chromePath, extensions, result);
+    }
+  }
+
   for (const exclusion of pathExclusionValidation.valid) {
     if ((matchCounts.get(exclusion) ?? 0) === 0) {
       result.pathExclusionFindings.push({
@@ -330,6 +346,62 @@ export function scanAddressabilitySources(root: string, options: AddressabilityS
   return result;
 }
 
+function scanAddressabilityChromeFile(
+  root: string,
+  chromePath: string,
+  extensions: Set<string>,
+  result: AddressabilityScanResult,
+): void {
+  const full = isAbsolute(chromePath) ? resolve(chromePath) : resolve(root, chromePath);
+  if (!existsSync(full)) {
+    throw new Error(`scanAddressabilitySources: chrome file "${chromePath}" does not exist (resolved "${full}")`);
+  }
+  let stat;
+  try {
+    stat = statSync(full);
+  } catch (error) {
+    throw new Error(
+      `scanAddressabilitySources: cannot read chrome file "${chromePath}": ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  if (!stat.isFile()) {
+    throw new Error(`scanAddressabilitySources: chrome path "${chromePath}" is not a file`);
+  }
+
+  const relPath = relative(root, full).split(sep).join("/");
+  const displayPath = relPath.length > 0 && !relPath.startsWith("..") ? relPath : chromePath;
+  const entryName = full.slice(full.lastIndexOf(sep) + 1);
+
+  if (!extensions.has(extname(entryName).toLowerCase())) {
+    throw new Error(
+      `scanAddressabilitySources: chrome file "${chromePath}" has extension ${extname(entryName)} which is not in the scan extension set`,
+    );
+  }
+
+  if (SKIP_FILE_RE.test(entryName)) {
+    result.skippedByDesign.push({ file: displayPath, reason: "test-or-check-file" });
+    return;
+  }
+
+  let content: string;
+  try {
+    content = readFileSync(full, "utf8");
+  } catch (error) {
+    throw new Error(
+      `scanAddressabilitySources: cannot read chrome file "${full}": ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  const extracted = extractAddressabilityCandidates(content, displayPath);
+  if (extracted.parseFailure) {
+    result.parseFailures.push({ file: displayPath, detail: extracted.parseFailure });
+    return;
+  }
+  result.filesScanned++;
+  result.violations.push(...extracted.violations);
+  result.unchecked.push(...extracted.unchecked);
+}
+
 // ------------------------------------------------------------- extraction
 
 /** `ariaLabel` -> `arialabel`, `aria-label` -> `arialabel` — the identical case/hyphen-insensitive normalization `scan.ts`'s own `normalizeIdentifier` performs (not exported, so reimplemented locally — a one-line heuristic, not worth a cross-file dependency). */
@@ -414,6 +486,83 @@ const DESTRUCTURING_OR_PARAMETER_DEFAULT_RE =
  * `DESTRUCTURING_OR_PARAMETER_DEFAULT_RE`'s own doc comment for exactly
  * what is and is not matched.
  */
+/** Copy-bearing object-literal property keys (issue #1063) — normalized like `normalizeAttrName`. */
+const COPY_BEARING_OBJECT_KEYS = new Set([
+  "label",
+  "title",
+  "cta",
+  "caption",
+  "heading",
+  "kicker",
+  "body",
+  "description",
+  "arialabel",
+  "text",
+]);
+
+/** Non-copy object-literal keys — route targets, icons, tokens; not Writer surfaces. */
+const ALLOWLISTED_OBJECT_LITERAL_KEYS = new Set([
+  "href",
+  "to",
+  "path",
+  "pathname",
+  "icon",
+  "iconname",
+  "slug",
+  "token",
+  "variant",
+  "size",
+]);
+
+const OBJECT_LITERAL_CONTAINER_KEYS = ["items", "nav", "links"] as const;
+
+const OBJECT_LITERAL_PROP_NAME_RE =
+  /(?:"([^"]+)"|'([^']+)'|([A-Za-z_$][A-Za-z0-9_$-]*))\s*:\s*$/;
+
+function literalStartIndex(content: string, line: number, raw: string): number | undefined {
+  const lines = content.split("\n");
+  const lineText = lines[line - 1];
+  if (lineText === undefined) return undefined;
+  const col = lineText.indexOf(raw);
+  if (col === -1) return undefined;
+  let start = 0;
+  for (let i = 0; i < line - 1; i++) start += lines[i]!.length + 1;
+  return start + col;
+}
+
+function objectLiteralPropertyName(content: string, start: number): string | undefined {
+  const from = Math.max(0, start - 120);
+  const before = content.slice(from, start);
+  const match = OBJECT_LITERAL_PROP_NAME_RE.exec(before);
+  if (!match) return undefined;
+  return match[1] ?? match[2] ?? match[3];
+}
+
+function objectLiteralKeyPath(content: string, start: number, propName: string): string {
+  const from = Math.max(0, start - 500);
+  const slice = content.slice(from, start);
+  for (const container of OBJECT_LITERAL_CONTAINER_KEYS) {
+    const re = new RegExp(`\\b${container}\\s*:\\s*\\[`, "g");
+    let lastIndex = -1;
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(slice)) !== null) lastIndex = m.index;
+    if (lastIndex !== -1) return `${container}[].${propName}`;
+  }
+  return propName;
+}
+
+/** Route/icon-shaped literal values that are never copy, regardless of key. */
+function looksLikeAllowlistedConstantValue(raw: string): boolean {
+  const quote = raw[0];
+  if (quote !== '"' && quote !== "'") return false;
+  const text = raw.slice(1, -1).trim();
+  if (text.length === 0) return false;
+  if (/^\/[^\s]*$/.test(text)) return true;
+  if (/^#[\w-]+$/.test(text)) return true;
+  if (/^https?:\/\//.test(text)) return true;
+  return false;
+}
+
 function isDestructuringOrParameterDefault(lines: string[], line: number, raw: string): boolean {
   const lineText = lines[line - 1];
   if (lineText === undefined) return false;
@@ -575,13 +724,46 @@ export function extractAddressabilityCandidates(content: string, filePath: strin
     violations.push({ file: c.file, line: c.line, position: "user-facing-attribute", attribute, raw: c.raw });
   }
 
-  // ---- position 3: everything else scan.ts kept as a real candidate —
+  // ---- position 3a: copy-bearing object-literal property values (issue
+  // #1063) — chrome config bags (`{ label: "...", href: "/join" }`) are
+  // Writer surfaces; allowlisted keys and route/icon-shaped values are not.
+  const objectLiteralClaimed = new Set<string>();
+  for (const c of candidates) {
+    if (c.kind !== "string") continue;
+    if (claimed.has(`${c.line}::${c.raw}`)) continue;
+    if (looksLikeUtilityClassList(c.raw)) continue;
+    const start = literalStartIndex(content, c.line, c.raw);
+    if (start === undefined) continue;
+    const propName = objectLiteralPropertyName(content, start);
+    if (propName === undefined) continue;
+    const normalizedProp = normalizeAttrName(propName);
+    if (ALLOWLISTED_OBJECT_LITERAL_KEYS.has(normalizedProp) || looksLikeAllowlistedConstantValue(c.raw)) {
+      objectLiteralClaimed.add(`${c.line}::${c.raw}`);
+      continue;
+    }
+    if (!COPY_BEARING_OBJECT_KEYS.has(normalizedProp)) continue;
+    if (isDestructuringOrParameterDefault(lines, c.line, c.raw)) continue;
+    if (!hasProse(c.raw)) continue;
+    const keyPath = objectLiteralKeyPath(content, start, propName);
+    objectLiteralClaimed.add(`${c.line}::${c.raw}`);
+    violations.push({
+      file: c.file,
+      line: c.line,
+      position: "object-literal-copy",
+      objectKey: propName,
+      keyPath,
+      raw: c.raw,
+    });
+  }
+
+  // ---- position 3b: everything else scan.ts kept as a real candidate —
   // never silently treated as clean, never treated as a violation either
   // — except a plain string shaped like a utility class LIST, which is
   // definitively not prose (see looksLikeUtilityClassList).
   for (const c of candidates) {
     if (c.kind === "jsx-text") continue; // already position 1
     if (c.kind === "string" && claimed.has(`${c.line}::${c.raw}`)) continue; // already position 2
+    if (c.kind === "string" && objectLiteralClaimed.has(`${c.line}::${c.raw}`)) continue;
     if (c.kind === "string" && looksLikeUtilityClassList(c.raw)) continue; // a class-name list, not prose
     unchecked.push({
       file: c.file,

package/src/approved-copy-coverage-rate-cli.ts

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { assessApprovedCopyCoverageRate } from "./approved-copy-coverage-rate.js";
+
+const USAGE = `Usage: writer-rate-check <assessment.json>\n\nAssess approved copy coverage rate from consumer-supplied independent observations.\nExit codes: 0 = satisfied, 1 = violated, 2 = indeterminate or unreadable.\nwriter-check remains the multi-mode CLI and is not this assessment.`;
+
+export class WriterRateCliInputError extends Error {}
+
+/** Reads caller-owned assessment evidence without treating it as validated. */
+export function readWriterAssessmentJson(path: string): unknown {
+  const resolved = resolve(path);
+  if (!existsSync(resolved)) throw new WriterRateCliInputError(`assessment file "${path}" does not exist`);
+  try {
+    if (!statSync(resolved).isFile()) throw new WriterRateCliInputError(`assessment file "${path}" is not a file`);
+    return JSON.parse(readFileSync(resolved, "utf8"));
+  } catch (cause) {
+    if (cause instanceof WriterRateCliInputError) throw cause;
+    throw new WriterRateCliInputError(`assessment file "${path}" is unreadable JSON: ${cause instanceof Error ? cause.message : String(cause)}`);
+  }
+}
+
+/** Testable CLI dispatcher. Invalid arguments throw; the executable maps them to exit 2. */
+export function main(argv: readonly string[]): number {
+  if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h")) {
+    console.log(USAGE);
+    return 0;
+  }
+  if (argv.length !== 1) throw new WriterRateCliInputError("exactly one assessment.json file is required");
+  const report = assessApprovedCopyCoverageRate(readWriterAssessmentJson(argv[0] as string));
+  console.log(JSON.stringify(report, null, 2));
+  return report.state === "satisfied" ? 0 : report.state === "violated" ? 1 : 2;
+}
+
+function run(): void {
+  try {
+    process.exitCode = main(process.argv.slice(2));
+  } catch (cause) {
+    console.error(`writer-rate-check: ${cause instanceof Error ? cause.message : String(cause)}`);
+    process.exitCode = 2;
+  }
+}
+
+/** Resolves an npm/POSIX bin symlink before deciding whether this module is the entrypoint. */
+export function isDirectInvocation(moduleUrl: string, argvPath: string | undefined): boolean {
+  if (argvPath === undefined) return false;
+  try {
+    return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(resolve(argvPath));
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectInvocation(import.meta.url, process.argv[1])) run();

package/src/approved-copy-coverage-rate.ts

@@ -0,0 +1,201 @@
+/**
+ * Computes the Writer charter metric `approved copy coverage rate` from
+ * consumer-supplied independent observations.
+ *
+ * This module does not invent observations and does not relabel
+ * `checkCopyRecord` or `checkCopyTraceability`. An empty evaluated set is
+ * indeterminate, never a perfect rate of 1. `writer-check` remains the
+ * multi-mode CLI.
+ */
+const METRIC = "approved copy coverage rate" as const;
+const RESERVED_OBSERVERS = new Set(["writer", "@clossys/writer"]);
+const PROPOSED_POSITIONS: readonly unknown[] = [];
+
+export type ApprovedCopyCoverageRateState = "satisfied" | "violated" | "indeterminate";
+
+export interface ApprovedCopyCoverageRateFinding {
+  readonly rule: string;
+  readonly severity: "error";
+  readonly message: string;
+  readonly path?: string;
+}
+
+export interface ApprovedCopyCoverageRateAssessment {
+  readonly metric: "approved copy coverage rate";
+  readonly state: ApprovedCopyCoverageRateState;
+  readonly rate: number | null;
+  readonly evaluatedCopy: number;
+  readonly approvedCoveredCopy: number;
+  readonly findings: readonly ApprovedCopyCoverageRateFinding[];
+  readonly proposedPositions: readonly unknown[];
+}
+
+type UnknownRecord = Record<string, unknown>;
+
+function record(value: unknown): value is UnknownRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function text(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function timestamp(value: unknown): value is string {
+  return text(value) && !Number.isNaN(Date.parse(value));
+}
+
+function finding(rule: string, message: string, path?: string): ApprovedCopyCoverageRateFinding {
+  return path === undefined ? { rule, severity: "error", message } : { rule, severity: "error", message, path };
+}
+
+function evidenceCounts(value: unknown): boolean {
+  if (!Array.isArray(value) || value.length === 0) return false;
+  return value.every((item) => record(item) && text(item.id) && text(item.description));
+}
+
+function reservedObserver(value: string): boolean {
+  return RESERVED_OBSERVERS.has(value.trim().toLowerCase());
+}
+
+function report(
+  state: ApprovedCopyCoverageRateState,
+  evaluatedCopy: number,
+  approvedCoveredCopy: number,
+  rate: number | null,
+  findings: readonly ApprovedCopyCoverageRateFinding[],
+): ApprovedCopyCoverageRateAssessment {
+  return {
+    metric: METRIC,
+    state,
+    rate,
+    evaluatedCopy,
+    approvedCoveredCopy,
+    findings,
+    proposedPositions: PROPOSED_POSITIONS,
+  };
+}
+
+interface CountingObservation {
+  readonly approved: boolean;
+  readonly traceable: boolean;
+  readonly resolvedFromRegistry: boolean;
+}
+
+function isCovered(entry: CountingObservation): boolean {
+  return entry.approved && entry.traceable && entry.resolvedFromRegistry;
+}
+
+/**
+ * Computes `approved copy coverage rate`: shipped audience-facing copy
+ * resolved from approved traceable registry entries / all shipped
+ * audience-facing copy evaluated.
+ */
+export function assessApprovedCopyCoverageRate(input: unknown): ApprovedCopyCoverageRateAssessment {
+  if (!record(input)) {
+    return report("indeterminate", 0, 0, null, [finding("assessment-shape", "Assessment input must be an object.", "$")]);
+  }
+
+  const findings: ApprovedCopyCoverageRateFinding[] = [];
+  if (!timestamp(input.asOf)) {
+    findings.push(finding("assessment-as-of", "asOf must be an interpretable timestamp.", "asOf"));
+  }
+
+  const declaredCopy = input.declaredCopy;
+  if (!Array.isArray(declaredCopy)) {
+    findings.push(finding("declared-copy-required", "declaredCopy must be an array of { id } objects.", "declaredCopy"));
+    return report("indeterminate", 0, 0, null, findings);
+  }
+
+  const declaredIds: string[] = [];
+  const declaredSet = new Set<string>();
+  declaredCopy.forEach((item, index) => {
+    const path = `declaredCopy[${index}]`;
+    if (!record(item) || !text(item.id)) {
+      findings.push(finding("copy-id-required", "id must be a non-empty string.", `${path}.id`));
+      return;
+    }
+    if (declaredSet.has(item.id)) {
+      findings.push(finding("duplicate-copy-id", `Duplicate id "${item.id}".`, `${path}.id`));
+      return;
+    }
+    declaredSet.add(item.id);
+    declaredIds.push(item.id);
+  });
+
+  if (declaredIds.length === 0) {
+    findings.push(finding("declared-copy-empty", "No declared copy is available for the approved-copy-coverage metric; the rate is indeterminate, never 1.", "declaredCopy"));
+  }
+
+  const observations = input.observations;
+  if (observations !== undefined && !Array.isArray(observations)) {
+    findings.push(finding("observations-shape", "observations must be an array.", "observations"));
+  }
+
+  const counting = new Map<string, CountingObservation[]>();
+  if (Array.isArray(observations)) {
+    observations.forEach((item, index) => {
+      const path = `observations[${index}]`;
+      if (!record(item)) {
+        findings.push(finding("observation-shape", "An observation must be an object.", path));
+        return;
+      }
+      if (text(item.observerRef) && reservedObserver(item.observerRef)) {
+        findings.push(finding("self-observation", "Writer cannot observe itself; reserved observerRef values are not independent.", `${path}.observerRef`));
+        return;
+      }
+      if (text(item.copyId) && !declaredSet.has(item.copyId)) {
+        findings.push(finding("unknown-copy", `Observation copyId "${item.copyId}" is not declared copy.`, `${path}.copyId`));
+        return;
+      }
+      if (item.independent !== true) return;
+      if (
+        typeof item.approved !== "boolean" ||
+        typeof item.traceable !== "boolean" ||
+        typeof item.resolvedFromRegistry !== "boolean"
+      ) return;
+      if (!text(item.observerRef) || !evidenceCounts(item.evidence) || !text(item.copyId) || !declaredSet.has(item.copyId)) return;
+      const bucket = counting.get(item.copyId) ?? [];
+      bucket.push({
+        approved: item.approved,
+        traceable: item.traceable,
+        resolvedFromRegistry: item.resolvedFromRegistry,
+      });
+      counting.set(item.copyId, bucket);
+    });
+  }
+
+  let evaluatedCopy = 0;
+  let approvedCoveredCopy = 0;
+  for (const id of declaredIds) {
+    const observed = counting.get(id) ?? [];
+    if (observed.length === 0) {
+      findings.push(finding("copy-unevaluated", `Declared copy "${id}" has no counting independent observation.`, `declaredCopy.${id}`));
+      continue;
+    }
+    evaluatedCopy += 1;
+    const allCovered = observed.every((entry) => isCovered(entry));
+    if (allCovered) approvedCoveredCopy += 1;
+    else {
+      findings.push(finding("copy-not-covered", `Declared copy "${id}" was independently observed not resolved from an approved traceable registry entry.`, `declaredCopy.${id}`));
+    }
+    if (observed.length > 1) {
+      const first = observed[0]!;
+      const disagree = observed.some((entry) =>
+        entry.approved !== first.approved ||
+        entry.traceable !== first.traceable ||
+        entry.resolvedFromRegistry !== first.resolvedFromRegistry
+      );
+      if (disagree) {
+        findings.push(finding("observation-disagreement", `Counting observations for "${id}" disagree.`, `observations.${id}`));
+      }
+    }
+  }
+
+  const rate = evaluatedCopy === 0 ? null : approvedCoveredCopy / evaluatedCopy;
+  if (evaluatedCopy === 0) return report("indeterminate", 0, 0, null, findings);
+  const coverageComplete = evaluatedCopy === declaredIds.length;
+  const noErrorFindings = findings.length === 0;
+  const state: ApprovedCopyCoverageRateState =
+    coverageComplete && approvedCoveredCopy === evaluatedCopy && noErrorFindings ? "satisfied" : "violated";
+  return report(state, evaluatedCopy, approvedCoveredCopy, rate, findings);
+}