@codedrifters/configulator 0.0.273 → 0.0.275

package/lib/index.mjs

@@ -8487,6 +8487,63 @@ function buildDocsSyncSubAgent(_paths) {
       "",
       "---",
       "",
+      "## Phase 1: Scan",
+      "",
+      "Phase 1 walks the repo, runs every registered drift check, and",
+      "writes a single combined **audit report** to disk. Phase 1 never",
+      "edits documentation \u2014 only the persisted report changes between",
+      "scan and fix.",
+      "",
+      "### Audit report",
+      "",
+      "The report shape is exported from `@codedrifters/configulator`",
+      "as `AuditReport` (under `src/docs-sync/scan/`) so Phase 2 and",
+      "any downstream consumers share one definition. Reports are",
+      "persisted at:",
+      "",
+      "```",
+      ".claude/state/docs-sync/<issue-number>-audit.json",
+      "```",
+      "",
+      "Every report carries a `schemaVersion`, the `issueNumber`, the",
+      "invocation `mode` (`pr` or `audit`), the `generatedAt` UTC",
+      "timestamp, the `repoRoot`, and an optional `scope` label, plus",
+      "two parallel views of the findings:",
+      "",
+      "- **`categories`** \u2014 findings grouped by drift-check category.",
+      "  Every category key is always present; empty arrays are",
+      "  persisted explicitly. The five categories are `apiDiff`,",
+      "  `tsdocCoverage`, `referenceMismatches`, `linkFailures`, and",
+      "  `sampleFailures`.",
+      "- **`findings`** \u2014 the same records re-aggregated as a single",
+      "  flat array, sorted by severity (`blocking` first), then",
+      "  category, file, line, and subject. Provided so consumers",
+      "  that don't need the category grouping can iterate one array",
+      "  and see the merge-blocking findings at the top.",
+      "",
+      "Every finding carries a `category`, `severity`",
+      "(`mechanical` / `advisory` / `blocking`), `location`, `subject`,",
+      "`details`, and an optional `fixHint` for the Phase 2 fix agent.",
+      "",
+      "### Orchestrator",
+      "",
+      "The scan is driven by `runScan(...)` (also exported under",
+      "`src/docs-sync/scan/`). The orchestrator accepts a list of",
+      "`AuditCheckRunner` instances, invokes each one in registration",
+      "order, merges the findings into the report, and (optionally)",
+      "persists the report to disk. The default check list is empty \u2014",
+      "this skeleton release runs cleanly with no checks registered",
+      "and produces a schema-compliant report whose category arrays",
+      "are all empty.",
+      "",
+      "Children of the parent docs-sync epic plug runners into the",
+      "orchestrator: API/TSDoc/reference checks land first, link",
+      "and fenced-sample checks land second, the fix phase reads the",
+      "persisted report, and the audit-mode walker reuses the same",
+      "report shape.",
+      "",
+      "---",
+      "",
       "## Write Boundaries",
       "",
       "Even once the pipeline is wired, the following boundaries are",
@@ -9026,6 +9083,126 @@ var checkLinksProcedure = {
   description: "Link integrity checker that wraps `astro check` (internal links) and `lychee` (external URLs) and normalizes their output into a single JSON-array stream of { url, docPath, line, kind, reason } records. Detection is data: the helper exits 0 when a tool ran successfully regardless of how many broken links it reported. Non-zero exits are reserved for tool-level failures.",
   content: renderCheckLinksProcedure()
 };
+function renderCheckDocSamplesProcedure() {
+  const nodeScript = [
+    "(async () => {",
+    "  const { compileFencedSamples } = await import('@codedrifters/configulator');",
+    "  const docsRoot = process.argv[1];",
+    "  const failures = compileFencedSamples({ docsRoot });",
+    "  process.stdout.write(JSON.stringify(failures));",
+    "})().catch((err) => {",
+    "  console.error('check-doc-samples.sh: ' + (err && err.stack ? err.stack : err));",
+    "  process.exit(3);",
+    "});"
+  ].join("\n");
+  return [
+    "#!/usr/bin/env bash",
+    "# check-doc-samples.sh \u2014 Compile fenced TS/TSX samples in the Starlight docs.",
+    "#",
+    "# Usage:",
+    "#   .claude/procedures/check-doc-samples.sh <docs-root>",
+    "#",
+    "# Where:",
+    "#   <docs-root> \u2014 path to the markdown content tree",
+    "#                 (e.g. `docs/src/content/docs`). Walked recursively",
+    "#                 for `*.md` files.",
+    "#",
+    "# Wraps the `compileFencedSamples` API exported from",
+    "# `@codedrifters/configulator`. For every fenced ` ```ts `,",
+    "# ` ```typescript `, ` ```tsx `, or ` ```typescriptreact ` block in",
+    "# the docs, the helper writes the sample to an in-memory file,",
+    "# runs the TypeScript compiler against it (in-process, via the TS",
+    "# compiler API), and reports any compilation diagnostics.",
+    "#",
+    "# Skipped samples (fence meta `skip` / `no-check`, or first line",
+    "# `// @no-check`) are passed through unchecked.",
+    "#",
+    "# Output (stdout, single JSON array):",
+    "#",
+    "#   [",
+    "#     {",
+    '#       "docPath":     "<path relative to <docs-root>>",',
+    '#       "line":        <1-indexed line number of the opening fence>,',
+    '#       "fenceIndex":  <0-indexed fenced-block position within the doc>,',
+    '#       "lang":        "ts" | "typescript" | "tsx" | "typescriptreact",',
+    '#       "diagnostics": [ "<TS<code>: <message>>", ... ]',
+    "#     },",
+    "#     ...",
+    "#   ]",
+    "#",
+    "# An empty array (`[]`) is emitted when every sample compiled.",
+    "# Detection is **data**, not failure: this helper exits 0 when the",
+    "# compilation phase ran successfully, regardless of how many",
+    "# samples failed to compile. The downstream docs-sync scan phase",
+    "# (#520) is responsible for treating failures as one of the two",
+    "# hard-block cases per the parent epic.",
+    "#",
+    "# Exit codes:",
+    "#   0  \u2014 compilation phase ran; failures (zero or more) are on",
+    "#        stdout as a JSON array.",
+    "#   1  \u2014 usage error (missing args, unreadable docs root).",
+    "#   2  \u2014 a required binary is not on PATH (`node` / `pnpm`).",
+    "#   3  \u2014 the compilation phase threw an unhandled exception.",
+    "#        Stderr carries the diagnostic.",
+    "#",
+    "# Dependencies: expects `node` and `pnpm` on PATH and the workspace",
+    "# `@codedrifters/configulator` package to be installed (the helper",
+    "# resolves the API through `pnpm exec node` from the repo root).",
+    "",
+    "set -uo pipefail",
+    "",
+    "err() {",
+    '  printf "check-doc-samples.sh: %s\\n" "$*" >&2',
+    "}",
+    "",
+    'if [ "$#" -lt 1 ]; then',
+    '  err "usage: check-doc-samples.sh <docs-root>"',
+    "  exit 1",
+    "fi",
+    "",
+    'docs_root="$1"',
+    "",
+    'if [ ! -d "$docs_root" ]; then',
+    '  err "docs root not found: $docs_root"',
+    "  exit 1",
+    "fi",
+    "",
+    "if ! command -v node >/dev/null 2>&1; then",
+    '  err "node is required but not on PATH"',
+    "  exit 2",
+    "fi",
+    "",
+    "if ! command -v pnpm >/dev/null 2>&1; then",
+    '  err "pnpm is required but not on PATH"',
+    "  exit 2",
+    "fi",
+    "",
+    "# Resolve docs_root to an absolute path so the inline node script",
+    "# is independent of the cwd `pnpm exec` chooses.",
+    'docs_root_abs="$(cd "$docs_root" && pwd)"',
+    "",
+    "# Run the inline node script through `pnpm exec` so module",
+    "# resolution finds `@codedrifters/configulator` via the workspace",
+    "# even when the helper is invoked from a sub-package directory.",
+    "# The `--input-type=module` flag lets us use top-level `await` and",
+    "# `import()` cleanly. Diagnostics from the script flow to stderr;",
+    "# stdout carries only the JSON array.",
+    'pnpm exec node --input-type=module -e "' + nodeScript.replace(/"/g, '\\"') + '" "$docs_root_abs"',
+    "status=$?",
+    "",
+    'if [ "$status" -ne 0 ]; then',
+    '  err "compileFencedSamples exited with status $status"',
+    "  exit 3",
+    "fi",
+    "",
+    "exit 0"
+  ].join("\n");
+}
+var checkDocSamplesProcedure = {
+  name: "check-doc-samples.sh",
+  description: "Fenced-sample compilation checker that wraps the `compileFencedSamples` API and emits a JSON-array stream of { docPath, line, fenceIndex, lang, diagnostics } failure records. Skipped samples (meta `skip`/`no-check`, or first-line `// @no-check`) are passed through unchecked. Detection is data: the helper exits 0 whenever compilation ran successfully regardless of failure count.",
+  content: renderCheckDocSamplesProcedure()
+};
 function buildDocsSyncBundle(paths = DEFAULT_AGENT_PATHS) {
   return {
     name: "docs-sync",
@@ -9075,7 +9252,11 @@ function buildDocsSyncBundle(paths = DEFAULT_AGENT_PATHS) {
     ],
     skills: [buildDocsSyncPrSkill(), buildDocsSyncAuditSkill()],
     subAgents: [buildDocsSyncSubAgent(paths)],
-    procedures: [extractApiProcedure, checkLinksProcedure],
+    procedures: [
+      extractApiProcedure,
+      checkLinksProcedure,
+      checkDocSamplesProcedure
+    ],
     labels: [
       {
         name: "type:docs-sync",
@@ -26819,8 +27000,8 @@ var FALLBACKS = {
   monorepoLayoutSeedBlock: ""
 };
 var TEMPLATE_RE = /\{\{(\w+(?:\.\w+)*)\}\}/g;
-function getNestedValue(obj, path4) {
-  const parts = path4.split(".");
+function getNestedValue(obj, path7) {
+  const parts = path7.split(".");
   let current = obj;
   for (const part of parts) {
     if (current == null || typeof current !== "object") {
@@ -27046,20 +27227,20 @@ var ClaudeRenderer = class _ClaudeRenderer {
       obj.excludedCommands = [...sandbox.excludedCommands];
     }
     if (sandbox.filesystem) {
-      const fs2 = {};
+      const fs4 = {};
       if (sandbox.filesystem.allowRead?.length) {
-        fs2.allowRead = [...sandbox.filesystem.allowRead];
+        fs4.allowRead = [...sandbox.filesystem.allowRead];
       }
       if (sandbox.filesystem.denyRead?.length) {
-        fs2.denyRead = [...sandbox.filesystem.denyRead];
+        fs4.denyRead = [...sandbox.filesystem.denyRead];
       }
       if (sandbox.filesystem.allowWrite?.length) {
-        fs2.allowWrite = [...sandbox.filesystem.allowWrite];
+        fs4.allowWrite = [...sandbox.filesystem.allowWrite];
       }
       if (sandbox.filesystem.denyWrite?.length) {
-        fs2.denyWrite = [...sandbox.filesystem.denyWrite];
+        fs4.denyWrite = [...sandbox.filesystem.denyWrite];
       }
-      if (Object.keys(fs2).length > 0) obj.filesystem = fs2;
+      if (Object.keys(fs4).length > 0) obj.filesystem = fs4;
     }
     if (sandbox.network) {
       const net = {};
@@ -28921,10 +29102,754 @@ function stripYamlFrontmatter(source) {
   return lines.join("\n");
 }
 
-// src/docs-sync/tsdoc-coverage/coverage.ts
+// src/docs-sync/sample-compilation/compilation.ts
+import * as path4 from "path";
+import * as ts from "typescript";
+
+// src/docs-sync/sample-compilation/extraction.ts
+import * as fs2 from "fs";
 import * as path3 from "path";
+import { fromMarkdown as fromMarkdown2 } from "mdast-util-from-markdown";
+var SampleLang = {
+  Ts: "ts",
+  Typescript: "typescript",
+  Tsx: "tsx",
+  Typescriptreact: "typescriptreact"
+};
+var DEFAULT_DOCS_ROOT2 = "docs/src/content/docs";
+var PLAIN_LANGS = /* @__PURE__ */ new Set([SampleLang.Ts, SampleLang.Typescript]);
+var JSX_LANGS = /* @__PURE__ */ new Set([
+  SampleLang.Tsx,
+  SampleLang.Typescriptreact
+]);
+function extractFencedSamples(options = {}) {
+  const docsRoot = path3.resolve(options.docsRoot ?? DEFAULT_DOCS_ROOT2);
+  const includeTsx = options.includeTsx ?? true;
+  if (!fs2.existsSync(docsRoot)) {
+    return [];
+  }
+  const records = [];
+  for (const absolutePath of walkMarkdownFiles2(docsRoot)) {
+    const docPath = toPosix2(path3.relative(docsRoot, absolutePath));
+    const source = fs2.readFileSync(absolutePath, "utf-8");
+    const tree = fromMarkdown2(stripYamlFrontmatter2(source));
+    let fenceIndex = 0;
+    collectFencedCode(tree, (node) => {
+      const lang = normalizeLang(node.lang);
+      if (lang === void 0) {
+        return;
+      }
+      if (!includeTsx && JSX_LANGS.has(lang)) {
+        return;
+      }
+      if (!PLAIN_LANGS.has(lang) && !JSX_LANGS.has(lang)) {
+        return;
+      }
+      const start = node.position?.start;
+      if (!start) {
+        return;
+      }
+      const skip = detectSkip(node);
+      records.push({
+        docPath,
+        line: start.line,
+        fenceIndex,
+        lang,
+        code: node.value ?? "",
+        skipped: skip.skipped,
+        skipReason: skip.reason
+      });
+      fenceIndex += 1;
+    });
+  }
+  records.sort((a, b) => {
+    if (a.docPath !== b.docPath) {
+      return a.docPath.localeCompare(b.docPath);
+    }
+    if (a.line !== b.line) {
+      return a.line - b.line;
+    }
+    return a.fenceIndex - b.fenceIndex;
+  });
+  return records;
+}
+function walkMarkdownFiles2(root) {
+  const out = [];
+  const stack = [root];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = fs2.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path3.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+      } else if (entry.isFile() && full.toLowerCase().endsWith(".md")) {
+        out.push(full);
+      }
+    }
+  }
+  out.sort();
+  return out;
+}
+function collectFencedCode(tree, visit) {
+  walk(tree);
+  function walk(node) {
+    if (node.type === "code") {
+      visit(node);
+      return;
+    }
+    if (node.type === "html") {
+      return;
+    }
+    const parent = node;
+    if (Array.isArray(parent.children)) {
+      for (const child of parent.children) {
+        walk(child);
+      }
+    }
+  }
+}
+function normalizeLang(raw) {
+  if (!raw) {
+    return void 0;
+  }
+  const lower = raw.toLowerCase();
+  switch (lower) {
+    case "ts":
+      return SampleLang.Ts;
+    case "typescript":
+      return SampleLang.Typescript;
+    case "tsx":
+      return SampleLang.Tsx;
+    case "typescriptreact":
+      return SampleLang.Typescriptreact;
+    default:
+      return void 0;
+  }
+}
+var META_SKIP_PATTERN = /\b(skip|no-check)\b/i;
+var PRAGMA_NO_CHECK_PATTERN = /^\s*\/\/\s*@no-check\b/i;
+function detectSkip(node) {
+  const meta = node.meta ?? "";
+  const metaMatch = META_SKIP_PATTERN.exec(meta);
+  if (metaMatch) {
+    return { skipped: true, reason: `meta:${metaMatch[1].toLowerCase()}` };
+  }
+  const code = node.value ?? "";
+  const firstLine = firstNonBlankLine(code);
+  if (firstLine !== void 0 && PRAGMA_NO_CHECK_PATTERN.test(firstLine)) {
+    return { skipped: true, reason: "pragma:@no-check" };
+  }
+  return { skipped: false, reason: "" };
+}
+function firstNonBlankLine(source) {
+  for (const line of source.split("\n")) {
+    if (line.trim().length > 0) {
+      return line;
+    }
+  }
+  return void 0;
+}
+function toPosix2(p) {
+  return p.split(path3.sep).join("/");
+}
+function stripYamlFrontmatter2(source) {
+  if (!source.startsWith("---")) {
+    return source;
+  }
+  const lines = source.split("\n");
+  if (lines[0] !== "---") {
+    return source;
+  }
+  let endIndex = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === "---") {
+      endIndex = i;
+      break;
+    }
+  }
+  if (endIndex < 0) {
+    return source;
+  }
+  for (let i = 0; i <= endIndex; i++) {
+    lines[i] = "";
+  }
+  return lines.join("\n");
+}
+
+// src/docs-sync/sample-compilation/compilation.ts
+var DEFAULT_SAMPLE_COMPILER_OPTIONS = {
+  target: ts.ScriptTarget.ES2022,
+  module: ts.ModuleKind.ESNext,
+  moduleResolution: ts.ModuleResolutionKind.Bundler,
+  lib: ["lib.es2022.d.ts", "lib.dom.d.ts"],
+  strict: true,
+  noUnusedLocals: false,
+  noUnusedParameters: false,
+  skipLibCheck: true,
+  esModuleInterop: true,
+  resolveJsonModule: true,
+  isolatedModules: true,
+  jsx: ts.JsxEmit.Preserve,
+  noEmit: true,
+  allowSyntheticDefaultImports: true
+};
+var REPO_RELATIVE_MODULE_PATTERN = /^['"](?:\.\.?\/|\/)/;
+function compileFencedSamples(options = {}) {
+  const samples = extractFencedSamples(options);
+  const tolerateRepoRelative = options.tolerateRepoRelativeMissingModule ?? true;
+  const failures = [];
+  for (const sample of samples) {
+    if (sample.skipped) {
+      continue;
+    }
+    const diagnostics = compileSingleSample(
+      sample,
+      options.compilerOptions,
+      tolerateRepoRelative
+    );
+    if (diagnostics.length > 0) {
+      failures.push({
+        docPath: sample.docPath,
+        line: sample.line,
+        fenceIndex: sample.fenceIndex,
+        lang: sample.lang,
+        diagnostics
+      });
+    }
+  }
+  return failures;
+}
+function compileSingleSample(sample, overrides, tolerateRepoRelative) {
+  const filename = sampleFilename(sample);
+  const compilerOptions = mergeCompilerOptions(overrides);
+  const host = createSingleFileHost(filename, sample.code, compilerOptions);
+  const program = ts.createProgram({
+    rootNames: [filename],
+    options: compilerOptions,
+    host
+  });
+  const sourceFile = program.getSourceFile(filename);
+  const collected = [];
+  if (sourceFile) {
+    collected.push(...program.getSyntacticDiagnostics(sourceFile));
+    collected.push(...program.getSemanticDiagnostics(sourceFile));
+  } else {
+    collected.push(...program.getSyntacticDiagnostics());
+    collected.push(...program.getSemanticDiagnostics());
+  }
+  const diagnostics = [];
+  for (const d of collected) {
+    if (tolerateRepoRelative && isRepoRelativeMissingModule(d, sample.code)) {
+      continue;
+    }
+    diagnostics.push(formatDiagnostic(d));
+  }
+  return diagnostics;
+}
+function sampleFilename(sample) {
+  const safeDoc = sample.docPath.replace(/[^a-zA-Z0-9]+/g, "_");
+  const ext = sample.lang === SampleLang.Tsx || sample.lang === SampleLang.Typescriptreact ? "tsx" : "ts";
+  return path4.posix.join("/", `${safeDoc}__${sample.fenceIndex}.${ext}`);
+}
+function mergeCompilerOptions(overrides) {
+  if (!overrides) {
+    return { ...DEFAULT_SAMPLE_COMPILER_OPTIONS };
+  }
+  const merged = { ...DEFAULT_SAMPLE_COMPILER_OPTIONS };
+  for (const key of Object.keys(overrides)) {
+    const value = overrides[key];
+    if (value === void 0) {
+      delete merged[key];
+    } else {
+      merged[key] = value;
+    }
+  }
+  return merged;
+}
+function createSingleFileHost(filename, source, compilerOptions) {
+  const baseHost = ts.createCompilerHost(compilerOptions, true);
+  return {
+    ...baseHost,
+    getSourceFile(name, languageVersionOrOptions, onError, shouldCreate) {
+      if (name === filename) {
+        return ts.createSourceFile(
+          name,
+          source,
+          languageVersionOrOptions,
+          true
+        );
+      }
+      return baseHost.getSourceFile(
+        name,
+        languageVersionOrOptions,
+        onError,
+        shouldCreate
+      );
+    },
+    fileExists(name) {
+      if (name === filename) {
+        return true;
+      }
+      return baseHost.fileExists(name);
+    },
+    readFile(name) {
+      if (name === filename) {
+        return source;
+      }
+      return baseHost.readFile(name);
+    },
+    writeFile() {
+    },
+    getCanonicalFileName(name) {
+      return baseHost.getCanonicalFileName(name);
+    },
+    useCaseSensitiveFileNames() {
+      return baseHost.useCaseSensitiveFileNames();
+    },
+    getNewLine() {
+      return baseHost.getNewLine();
+    },
+    getDefaultLibFileName(o) {
+      return baseHost.getDefaultLibFileName(o);
+    },
+    getCurrentDirectory() {
+      return baseHost.getCurrentDirectory();
+    }
+  };
+}
+function isRepoRelativeMissingModule(d, code) {
+  if (d.code !== 2307) {
+    return false;
+  }
+  const text = ts.flattenDiagnosticMessageText(d.messageText, "\n");
+  const match = /'([^']+)'/.exec(text);
+  if (!match) {
+    return false;
+  }
+  const specifier = match[1];
+  if (!specifier) {
+    return false;
+  }
+  const inSourceSingle = `'${specifier}'`;
+  const inSourceDouble = `"${specifier}"`;
+  if (!code.includes(inSourceSingle) && !code.includes(inSourceDouble)) {
+    return false;
+  }
+  return REPO_RELATIVE_MODULE_PATTERN.test(`'${specifier}'`);
+}
+function formatDiagnostic(d) {
+  const text = ts.flattenDiagnosticMessageText(d.messageText, " ");
+  const code = d.code === void 0 ? "" : `TS${d.code}: `;
+  return `${code}${text}`.trim();
+}
+
+// src/docs-sync/scan/audit-report.ts
+var AuditCategory = {
+  /**
+   * Findings produced by the public-API diff check that surfaces
+   * added, renamed, or removed exports between the current branch
+   * and the recorded baseline. Wired in by child issue #519.
+   */
+  ApiDiff: "apiDiff",
+  /**
+   * Findings produced by the TSDoc-coverage check that flags public
+   * exports without a one-sentence summary. Wired in by child issue
+   * #519.
+   */
+  TsdocCoverage: "tsdocCoverage",
+  /**
+   * Findings produced by the doc-reference cross-index check that
+   * flags inline-code symbol mentions whose target is missing or
+   * has changed. Wired in by child issue #519.
+   */
+  ReferenceMismatches: "referenceMismatches",
+  /**
+   * Findings produced by the link-integrity check (internal via
+   * `astro check`, external via `lychee`). Wired in by child issue
+   * #520.
+   */
+  LinkFailures: "linkFailures",
+  /**
+   * Findings produced by the fenced-sample compilation check that
+   * flags ` ```ts ` / ` ```typescript ` / ` ```tsx ` blocks in the
+   * docs that fail `tsc`. Wired in by child issue #520.
+   */
+  SampleFailures: "sampleFailures"
+};
+var AuditSeverity = {
+  /**
+   * The finding has a deterministic mechanical fix that the Phase 2
+   * (Fix) agent will auto-apply (TSDoc stubs, dead-link updates,
+   * registry sync, etc.).
+   */
+  Mechanical: "mechanical",
+  /**
+   * The finding deserves human attention but does not block the PR.
+   * Surfaced as a non-blocking note on the sticky `## Docs sync`
+   * comment.
+   */
+  Advisory: "advisory",
+  /**
+   * The finding blocks the PR. Per the parent epic this is reserved
+   * for the two narrow cases of confirmed broken external links and
+   * fenced TS samples that fail to compile.
+   */
+  Blocking: "blocking"
+};
+var AuditMode = {
+  Pr: "pr",
+  Audit: "audit"
+};
+var DOCS_SYNC_AUDIT_SCHEMA_VERSION = 1;
+function auditReportJsonSchema() {
+  const locationSchema = {
+    type: "object",
+    additionalProperties: false,
+    required: ["file", "line"],
+    properties: {
+      file: { type: "string" },
+      line: { type: "integer", minimum: 0 }
+    }
+  };
+  const findingBaseProperties = {
+    severity: { type: "string", enum: ["mechanical", "advisory", "blocking"] },
+    location: locationSchema,
+    subject: { type: "string" },
+    details: { type: "string" },
+    fixHint: { type: "string" }
+  };
+  const apiDiffFindingSchema = {
+    type: "object",
+    required: [
+      "category",
+      "severity",
+      "location",
+      "subject",
+      "details",
+      "change",
+      "symbol"
+    ],
+    properties: {
+      ...findingBaseProperties,
+      category: { type: "string", const: "apiDiff" },
+      change: { type: "string", enum: ["added", "removed", "changed"] },
+      symbol: { type: "string" }
+    }
+  };
+  const tsdocCoverageFindingSchema = {
+    type: "object",
+    required: [
+      "category",
+      "severity",
+      "location",
+      "subject",
+      "details",
+      "shortfall",
+      "symbol"
+    ],
+    properties: {
+      ...findingBaseProperties,
+      category: { type: "string", const: "tsdocCoverage" },
+      shortfall: {
+        type: "string",
+        enum: [
+          "missing-summary",
+          "thin-summary",
+          "missing-params",
+          "missing-returns"
+        ]
+      },
+      symbol: { type: "string" }
+    }
+  };
+  const referenceMismatchFindingSchema = {
+    type: "object",
+    required: [
+      "category",
+      "severity",
+      "location",
+      "subject",
+      "details",
+      "mismatch",
+      "symbol"
+    ],
+    properties: {
+      ...findingBaseProperties,
+      category: { type: "string", const: "referenceMismatches" },
+      mismatch: {
+        type: "string",
+        enum: ["unknown-symbol", "signature-changed"]
+      },
+      symbol: { type: "string" }
+    }
+  };
+  const linkFailureFindingSchema = {
+    type: "object",
+    required: [
+      "category",
+      "severity",
+      "location",
+      "subject",
+      "details",
+      "url",
+      "kind",
+      "reason"
+    ],
+    properties: {
+      ...findingBaseProperties,
+      category: { type: "string", const: "linkFailures" },
+      url: { type: "string" },
+      kind: { type: "string", enum: ["internal", "external"] },
+      reason: { type: "string" }
+    }
+  };
+  const sampleFailureFindingSchema = {
+    type: "object",
+    required: [
+      "category",
+      "severity",
+      "location",
+      "subject",
+      "details",
+      "fenceIndex",
+      "lang",
+      "diagnostics"
+    ],
+    properties: {
+      ...findingBaseProperties,
+      category: { type: "string", const: "sampleFailures" },
+      fenceIndex: { type: "integer", minimum: 0 },
+      lang: { type: "string" },
+      diagnostics: { type: "array", items: { type: "string" } }
+    }
+  };
+  return {
+    $schema: "http://json-schema.org/draft-07/schema#",
+    title: "DocsSyncAuditReport",
+    type: "object",
+    additionalProperties: false,
+    required: [
+      "schemaVersion",
+      "issueNumber",
+      "mode",
+      "generatedAt",
+      "repoRoot",
+      "scope",
+      "categories",
+      "findings"
+    ],
+    properties: {
+      schemaVersion: { type: "integer", const: DOCS_SYNC_AUDIT_SCHEMA_VERSION },
+      issueNumber: { type: "integer", minimum: 0 },
+      mode: { type: "string", enum: ["pr", "audit"] },
+      generatedAt: { type: "string", format: "date-time" },
+      repoRoot: { type: "string" },
+      scope: { type: "string" },
+      categories: {
+        type: "object",
+        additionalProperties: false,
+        required: [
+          "apiDiff",
+          "tsdocCoverage",
+          "referenceMismatches",
+          "linkFailures",
+          "sampleFailures"
+        ],
+        properties: {
+          apiDiff: { type: "array", items: apiDiffFindingSchema },
+          tsdocCoverage: { type: "array", items: tsdocCoverageFindingSchema },
+          referenceMismatches: {
+            type: "array",
+            items: referenceMismatchFindingSchema
+          },
+          linkFailures: { type: "array", items: linkFailureFindingSchema },
+          sampleFailures: { type: "array", items: sampleFailureFindingSchema }
+        }
+      },
+      findings: {
+        type: "array",
+        items: {
+          oneOf: [
+            apiDiffFindingSchema,
+            tsdocCoverageFindingSchema,
+            referenceMismatchFindingSchema,
+            linkFailureFindingSchema,
+            sampleFailureFindingSchema
+          ]
+        }
+      }
+    }
+  };
+}
+
+// src/docs-sync/scan/run-scan.ts
+import * as fs3 from "fs";
+import * as path5 from "path";
+var DEFAULT_AUDIT_REPORT_DIR = ".claude/state/docs-sync";
+var SEVERITY_RANK = {
+  blocking: 0,
+  advisory: 1,
+  mechanical: 2
+};
+var AUDIT_CATEGORY_ORDER = [
+  AuditCategory.ApiDiff,
+  AuditCategory.TsdocCoverage,
+  AuditCategory.ReferenceMismatches,
+  AuditCategory.LinkFailures,
+  AuditCategory.SampleFailures
+];
+function runScan(options) {
+  const repoRoot = path5.resolve(options.repoRoot);
+  const mode = options.mode;
+  const scope = options.scope ?? "";
+  const issueNumber = options.issueNumber;
+  const checks = options.checks ?? [];
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const persist = options.persist ?? false;
+  const reportDir = options.reportDir ?? DEFAULT_AUDIT_REPORT_DIR;
+  const context = {
+    repoRoot,
+    mode,
+    scope,
+    issueNumber
+  };
+  const collected = [];
+  for (const check of checks) {
+    const result = check.run(context);
+    for (const finding of result) {
+      collected.push(finding);
+    }
+  }
+  const report = buildReport({
+    issueNumber,
+    mode,
+    scope,
+    repoRoot,
+    generatedAt: now,
+    findings: collected
+  });
+  let reportPath = "";
+  if (persist) {
+    reportPath = persistAuditReport({
+      report,
+      repoRoot,
+      reportDir
+    });
+  }
+  return { report, reportPath };
+}
+function buildReport(args) {
+  const buckets = emptyCategoryBuckets();
+  for (const finding of args.findings) {
+    pushIntoBucket(buckets, finding);
+  }
+  buckets.apiDiff.sort(compareFindings);
+  buckets.tsdocCoverage.sort(compareFindings);
+  buckets.referenceMismatches.sort(compareFindings);
+  buckets.linkFailures.sort(compareFindings);
+  buckets.sampleFailures.sort(compareFindings);
+  const flat = [];
+  for (const key of AUDIT_CATEGORY_ORDER) {
+    const bucket = buckets[key];
+    for (const finding of bucket) {
+      flat.push(finding);
+    }
+  }
+  flat.sort(compareFindings);
+  return {
+    schemaVersion: DOCS_SYNC_AUDIT_SCHEMA_VERSION,
+    issueNumber: args.issueNumber,
+    mode: args.mode,
+    generatedAt: args.generatedAt.toISOString(),
+    repoRoot: args.repoRoot,
+    scope: args.scope,
+    categories: {
+      apiDiff: buckets.apiDiff,
+      tsdocCoverage: buckets.tsdocCoverage,
+      referenceMismatches: buckets.referenceMismatches,
+      linkFailures: buckets.linkFailures,
+      sampleFailures: buckets.sampleFailures
+    },
+    findings: flat
+  };
+}
+function persistAuditReport(args) {
+  const repoRoot = path5.resolve(args.repoRoot);
+  const reportDir = args.reportDir ?? DEFAULT_AUDIT_REPORT_DIR;
+  const targetDir = path5.resolve(repoRoot, reportDir);
+  fs3.mkdirSync(targetDir, { recursive: true });
+  const targetFile = path5.join(
+    targetDir,
+    `${args.report.issueNumber}-audit.json`
+  );
+  const tempFile = `${targetFile}.tmp-${process.pid}-${Date.now()}`;
+  const serialized = `${JSON.stringify(args.report, null, 2)}
+`;
+  fs3.writeFileSync(tempFile, serialized, "utf-8");
+  fs3.renameSync(tempFile, targetFile);
+  return targetFile;
+}
+function emptyCategoryBuckets() {
+  return {
+    apiDiff: [],
+    tsdocCoverage: [],
+    referenceMismatches: [],
+    linkFailures: [],
+    sampleFailures: []
+  };
+}
+function pushIntoBucket(buckets, finding) {
+  switch (finding.category) {
+    case AuditCategory.ApiDiff:
+      buckets.apiDiff.push(finding);
+      return;
+    case AuditCategory.TsdocCoverage:
+      buckets.tsdocCoverage.push(finding);
+      return;
+    case AuditCategory.ReferenceMismatches:
+      buckets.referenceMismatches.push(finding);
+      return;
+    case AuditCategory.LinkFailures:
+      buckets.linkFailures.push(finding);
+      return;
+    case AuditCategory.SampleFailures:
+      buckets.sampleFailures.push(finding);
+      return;
+    default: {
+      const exhaustive = finding;
+      throw new Error(
+        `runScan: unrecognized finding category: ${JSON.stringify(exhaustive)}`
+      );
+    }
+  }
+}
+function compareFindings(a, b) {
+  const sevDelta = SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity];
+  if (sevDelta !== 0) {
+    return sevDelta;
+  }
+  if (a.category !== b.category) {
+    return a.category.localeCompare(b.category);
+  }
+  if (a.location.file !== b.location.file) {
+    return a.location.file.localeCompare(b.location.file);
+  }
+  if (a.location.line !== b.location.line) {
+    return a.location.line - b.location.line;
+  }
+  return a.subject.localeCompare(b.subject);
+}
+
+// src/docs-sync/tsdoc-coverage/coverage.ts
+import * as path6 from "path";
 import { TSDocParser } from "@microsoft/tsdoc";
-import * as ts from "typescript";
+import * as ts2 from "typescript";
 var TsDocCoverageKind = {
   Class: "Class",
   Interface: "Interface",
@@ -28940,8 +29865,8 @@ var DEFAULT_THIN_SUMMARY_WORD_THRESHOLD = 4;
 var DEFAULT_ENTRY_POINT = "src/index.ts";
 function analyzeTsDocCoverage(options) {
   const resolvedOptions = typeof options === "string" ? { packageRoot: options } : options;
-  const packageRoot = path3.resolve(resolvedOptions.packageRoot);
-  const entryPoint = path3.resolve(
+  const packageRoot = path6.resolve(resolvedOptions.packageRoot);
+  const entryPoint = path6.resolve(
     packageRoot,
     resolvedOptions.entryPoint ?? DEFAULT_ENTRY_POINT
   );
@@ -28950,7 +29875,7 @@ function analyzeTsDocCoverage(options) {
     packageRoot,
     resolvedOptions.tsconfigPath
   );
-  const program = ts.createProgram({
+  const program = ts2.createProgram({
     rootNames: [entryPoint],
     options: compilerOptions
   });
@@ -29004,24 +29929,24 @@ function analyzeTsDocCoverage(options) {
 }
 function resolveCompilerOptions(packageRoot, tsconfigPath) {
   if (tsconfigPath) {
-    const absoluteTsconfig = path3.resolve(packageRoot, tsconfigPath);
-    const configFile = ts.readConfigFile(absoluteTsconfig, ts.sys.readFile);
+    const absoluteTsconfig = path6.resolve(packageRoot, tsconfigPath);
+    const configFile = ts2.readConfigFile(absoluteTsconfig, ts2.sys.readFile);
     if (configFile.error) {
       throw new Error(
-        `analyzeTsDocCoverage: failed to read tsconfig at ${absoluteTsconfig}: ${ts.flattenDiagnosticMessageText(configFile.error.messageText, "\n")}`
+        `analyzeTsDocCoverage: failed to read tsconfig at ${absoluteTsconfig}: ${ts2.flattenDiagnosticMessageText(configFile.error.messageText, "\n")}`
       );
     }
-    const parsed = ts.parseJsonConfigFileContent(
+    const parsed = ts2.parseJsonConfigFileContent(
       configFile.config,
-      ts.sys,
-      path3.dirname(absoluteTsconfig)
+      ts2.sys,
+      path6.dirname(absoluteTsconfig)
     );
     return { ...parsed.options, noEmit: true };
   }
   return {
-    target: ts.ScriptTarget.ESNext,
-    module: ts.ModuleKind.NodeNext,
-    moduleResolution: ts.ModuleResolutionKind.NodeNext,
+    target: ts2.ScriptTarget.ESNext,
+    module: ts2.ModuleKind.NodeNext,
+    moduleResolution: ts2.ModuleResolutionKind.NodeNext,
     allowJs: false,
     declaration: false,
     noEmit: true,
@@ -29046,7 +29971,7 @@ function resolveAlias(symbol, checker) {
   return current;
 }
 function isAlias(symbol) {
-  return (symbol.flags & ts.SymbolFlags.Alias) !== 0;
+  return (symbol.flags & ts2.SymbolFlags.Alias) !== 0;
 }
 function pickPrimaryDeclaration(symbol) {
   const declarations = symbol.getDeclarations();
@@ -29054,53 +29979,53 @@ function pickPrimaryDeclaration(symbol) {
     return void 0;
   }
   const concrete = declarations.find(
-    (d) => !ts.isExportSpecifier(d) && !ts.isExportAssignment(d) && !ts.isExportDeclaration(d)
+    (d) => !ts2.isExportSpecifier(d) && !ts2.isExportAssignment(d) && !ts2.isExportDeclaration(d)
   );
   return concrete ?? declarations[0];
 }
 function classifyDeclaration(declaration) {
-  if (ts.isClassDeclaration(declaration)) {
+  if (ts2.isClassDeclaration(declaration)) {
     return TsDocCoverageKind.Class;
   }
-  if (ts.isInterfaceDeclaration(declaration)) {
+  if (ts2.isInterfaceDeclaration(declaration)) {
     return TsDocCoverageKind.Interface;
   }
-  if (ts.isTypeAliasDeclaration(declaration)) {
+  if (ts2.isTypeAliasDeclaration(declaration)) {
     return TsDocCoverageKind.TypeAlias;
   }
-  if (ts.isEnumDeclaration(declaration)) {
+  if (ts2.isEnumDeclaration(declaration)) {
     return TsDocCoverageKind.Enum;
   }
-  if (ts.isFunctionDeclaration(declaration) || ts.isMethodDeclaration(declaration)) {
+  if (ts2.isFunctionDeclaration(declaration) || ts2.isMethodDeclaration(declaration)) {
     return TsDocCoverageKind.Function;
   }
-  if (ts.isVariableDeclaration(declaration) || ts.isVariableStatement(declaration)) {
+  if (ts2.isVariableDeclaration(declaration) || ts2.isVariableStatement(declaration)) {
     return TsDocCoverageKind.Variable;
   }
-  if (ts.isModuleDeclaration(declaration)) {
+  if (ts2.isModuleDeclaration(declaration)) {
     return TsDocCoverageKind.Module;
   }
-  if (ts.isExportAssignment(declaration)) {
+  if (ts2.isExportAssignment(declaration)) {
     return TsDocCoverageKind.Default;
   }
   return TsDocCoverageKind.Other;
 }
 function resolveLocation(declaration) {
-  const target = ts.isVariableDeclaration(declaration) ? declaration.parent.parent ?? declaration : declaration;
+  const target = ts2.isVariableDeclaration(declaration) ? declaration.parent.parent ?? declaration : declaration;
   const source = target.getSourceFile();
   const { line } = source.getLineAndCharacterOfPosition(target.getStart());
   return { file: source.fileName, line: line + 1 };
 }
 function parseTsDocFor(declaration, parser) {
-  const target = ts.isVariableDeclaration(declaration) ? declaration.parent.parent ?? declaration : declaration;
+  const target = ts2.isVariableDeclaration(declaration) ? declaration.parent.parent ?? declaration : declaration;
   const sourceText = target.getSourceFile().getFullText();
-  const ranges = ts.getLeadingCommentRanges(sourceText, target.getFullStart());
+  const ranges = ts2.getLeadingCommentRanges(sourceText, target.getFullStart());
   if (!ranges || ranges.length === 0) {
     return void 0;
   }
   for (let i = ranges.length - 1; i >= 0; i--) {
     const range = ranges[i];
-    if (range.kind !== ts.SyntaxKind.MultiLineCommentTrivia) {
+    if (range.kind !== ts2.SyntaxKind.MultiLineCommentTrivia) {
       continue;
     }
     const text = sourceText.slice(range.pos, range.end);
@@ -29323,14 +30248,14 @@ var LAYOUT_ROOT_BY_PROJECT_TYPE = {
 };
 function validateMonorepoLayout(root) {
   const violations = [];
-  const rootOutdir = toPosix2(root.outdir);
+  const rootOutdir = toPosix3(root.outdir);
   for (const sub of root.subprojects) {
     const className = sub.constructor.name;
     const expectedRoot = expectedRootFor(sub, className);
     if (expectedRoot === void 0) {
       continue;
     }
-    const relOutdir = relativeOutdir(rootOutdir, toPosix2(sub.outdir));
+    const relOutdir = relativeOutdir(rootOutdir, toPosix3(sub.outdir));
     if (!outdirMatchesRoot(relOutdir, expectedRoot)) {
       violations.push({
         projectName: sub.name,
@@ -29389,7 +30314,7 @@ function outdirMatchesRoot(relOutdir, expectedRoot) {
   }
   return segments.length >= 2;
 }
-function toPosix2(p) {
+function toPosix3(p) {
   return p.replace(/\\/g, "/");
 }
 function relativeOutdir(rootOutdir, subOutdir) {
@@ -29478,8 +30403,8 @@ var ResetTask = class _ResetTask extends Component14 {
     const resetTask = this.project.tasks.addTask(this.taskName, {
       description: "Delete build artifacts specified by pathsToRemove option, or artifactsDirectory if pathsToRemove is empty"
     });
-    this.pathsToRemove.forEach((path4) => {
-      resetTask.exec(`[ -e "${path4}" ] && rm -rf ${path4} || true`);
+    this.pathsToRemove.forEach((path7) => {
+      resetTask.exec(`[ -e "${path7}" ] && rm -rf ${path7} || true`);
     });
     const rootHasTurbo = TurboRepo.of(this.project.root) !== void 0;
     const isSubproject = this.project !== this.project.root;
@@ -31387,7 +32312,7 @@ export const collections = {
 `;
 
 // src/typescript/typescript-config.ts
-import { relative as relative5 } from "path";
+import { relative as relative6 } from "path";
 import { Component as Component19 } from "projen";
 import { ensureRelativePathStartsWithDot } from "projen/lib/util/path";
 var TypeScriptConfig = class extends Component19 {
@@ -31406,7 +32331,7 @@ var TypeScriptConfig = class extends Component19 {
         ...tsPaths,
         [dep.name]: [
           ensureRelativePathStartsWithDot(
-            relative5(project.outdir, subproject.outdir)
+            relative6(project.outdir, subproject.outdir)
           )
         ]
       };
@@ -31421,11 +32346,15 @@ export {
   AGENT_RULE_SCOPE,
   AGENT_TIER_ROLES,
   AGENT_TIER_VALUES,
+  AUDIT_CATEGORY_ORDER,
   AgentConfig,
   ApiExtractor,
   AstroConfig,
   AstroOutput,
   AstroProject,
+  AuditCategory,
+  AuditMode,
+  AuditSeverity,
   AwsCdkProject,
   AwsDeployWorkflow,
   AwsDeploymentConfig,
@@ -31441,6 +32370,7 @@ export {
   DEFAULT_API_EXTRACTOR_ENTRY_POINT,
   DEFAULT_API_EXTRACTOR_REPORT_FILENAME,
   DEFAULT_API_EXTRACTOR_REPORT_FOLDER,
+  DEFAULT_AUDIT_REPORT_DIR,
   DEFAULT_DECOMPOSITION_TEMPLATE,
   DEFAULT_DELEGATE_TO_PR_REVIEWER,
   DEFAULT_DISPATCH_MODEL,
@@ -31464,6 +32394,7 @@ export {
   DEFAULT_PROGRESS_FILES_STATE_DIR,
   DEFAULT_REQUIRE_LINKED_ISSUE,
   DEFAULT_REQUIRE_PRODUCT_CONTEXT,
+  DEFAULT_SAMPLE_COMPILER_OPTIONS,
   DEFAULT_SCHEDULED_TASKS_ROOT,
   DEFAULT_SCHEDULED_TASK_ENTRIES,
   DEFAULT_SHARED_EDITING_CONFLICT_STRATEGY,
@@ -31487,6 +32418,7 @@ export {
   DEFAULT_WORKFLOW_DIAGRAMS_ENABLED,
   DEFAULT_WORKFLOW_DIAGRAMS_PATH,
   DEFAULT_WORKFLOW_DIAGRAMS_REQUIRE_UPDATE,
+  DOCS_SYNC_AUDIT_SCHEMA_VERSION,
   JsiiFaker,
   LAYOUT_ENFORCEMENT,
   LAYOUT_ROOT_BY_PROJECT_TYPE,
@@ -31509,6 +32441,7 @@ export {
   SCOPE_CLASS_VALUES,
   SHARED_EDITING_CONFLICT_STRATEGY_VALUES,
   STARLIGHT_ROLE,
+  SampleLang,
   StarlightProject,
   TestRunner,
   TsDocCoverageKind,
@@ -31527,6 +32460,7 @@ export {
   addSyncLabelsWorkflow,
   agendaBundle,
   analyzeTsDocCoverage,
+  auditReportJsonSchema,
   awsCdkBundle,
   baseBundle,
   bcmWriterBundle,
@@ -31543,6 +32477,7 @@ export {
   buildOrchestratorConventionsContent,
   buildPeopleProfileBundle,
   buildRegulatoryResearchBundle,
+  buildReport,
   buildRequirementsAnalystBundle,
   buildRequirementsReviewerBundle,
   buildRequirementsWriterBundle,
@@ -31551,14 +32486,18 @@ export {
   buildStandardsResearchBundle,
   buildUnblockDependentsProcedure,
   businessModelsBundle,
+  checkDocSamplesProcedure,
   checkLinksProcedure,
   classifyIssueScope,
   classifyRun,
   companyProfileBundle,
+  compileFencedSamples,
   customerProfileBundle,
   docsSyncBundle,
+  emptyCategoryBuckets,
   extractApiProcedure,
   extractDocReferences,
+  extractFencedSamples,
   formatLayoutViolation,
   formatStarlightSingletonViolation,
   getLatestEligibleVersion,
@@ -31569,12 +32508,14 @@ export {
   meetingAnalysisBundle,
   orchestratorBundle,
   peopleProfileBundle,
+  persistAuditReport,
   pnpmBundle,
   prReviewBundle,
   projenBundle,
   regulatoryResearchBundle,
   renderAgentTierCaseStatement,
   renderAgentTierSection,
+  renderCheckDocSamplesProcedure,
   renderCheckLinksProcedure,
   renderCustomDocSectionBlock,
   renderCustomDocSections,
@@ -31634,6 +32575,7 @@ export {
   resolveTypeScriptProjectOutdir,
   resolveUnblockDependents,
   resolveWorkflowDiagrams,
+  runScan,
   slackBundle,
   softwareProfileBundle,
   standardsResearchBundle,