@codedrifters/configulator 0.0.276 → 0.0.278

package/lib/index.mjs

@@ -2867,20 +2867,26 @@ var createPackageSkill = {
     "   places the sub-project at `packages/<scope>/<name>`.",
     "",
     "6. **Tell the user how to synthesize.** Instruct them to run, from",
-    "   the repo root:",
+    "   the repo root, the safe three-step regen sequence:",
     "",
     "   ```",
+    "   pnpm i",
     "   pnpm exec projen",
-    "   pnpm install",
+    "   pnpm i",
     "   ```",
     "",
-    "   `pnpm exec projen` regenerates the sub-project tree;",
-    "   `pnpm install` updates the workspace lockfile. Do **not** run",
-    "   these commands yourself \u2014 the user runs them.",
+    "   The leading `pnpm i` syncs `node_modules` with `pnpm-lock.yaml`",
+    "   so synth runs against the right configulator/projen/plugin",
+    "   versions \u2014 without it, `pnpm exec projen` may synth against a",
+    "   stale resolved version of any pnpm-managed component and produce",
+    "   phantom drift in generated files. `pnpm exec projen` regenerates",
+    "   the sub-project tree; the trailing `pnpm i` updates the workspace",
+    "   lockfile to pick up any dependency changes projen wrote during",
+    "   synth. Do **not** run these commands yourself \u2014 the user runs them.",
     "",
     "## Guardrails",
     "",
-    "- Never run `pnpm exec projen`, `pnpm install`, `pnpm build`,",
+    "- Never run `pnpm exec projen`, `pnpm install`, `pnpm i`, `pnpm build`,",
     "  `pnpm test`, or any other package-manager, build, or test command.",
     "  Emit the projen block and instructions only.",
     "- Never scaffold outside `packages/`. Deployable apps belong under",
@@ -2990,20 +2996,26 @@ var createAppSkill = {
     "   sub-project at `apps/<scope>/<name>`.",
     "",
     "6. **Tell the user how to synthesize.** Instruct them to run, from",
-    "   the repo root:",
+    "   the repo root, the safe three-step regen sequence:",
     "",
     "   ```",
+    "   pnpm i",
     "   pnpm exec projen",
-    "   pnpm install",
+    "   pnpm i",
     "   ```",
     "",
-    "   `pnpm exec projen` regenerates the sub-project tree;",
-    "   `pnpm install` updates the workspace lockfile. Do **not** run",
-    "   these commands yourself \u2014 the user runs them.",
+    "   The leading `pnpm i` syncs `node_modules` with `pnpm-lock.yaml`",
+    "   so synth runs against the right configulator/projen/plugin",
+    "   versions \u2014 without it, `pnpm exec projen` may synth against a",
+    "   stale resolved version of any pnpm-managed component and produce",
+    "   phantom drift in generated files. `pnpm exec projen` regenerates",
+    "   the sub-project tree; the trailing `pnpm i` updates the workspace",
+    "   lockfile to pick up any dependency changes projen wrote during",
+    "   synth. Do **not** run these commands yourself \u2014 the user runs them.",
     "",
     "## Guardrails",
     "",
-    "- Never run `pnpm exec projen`, `pnpm install`, `pnpm build`,",
+    "- Never run `pnpm exec projen`, `pnpm install`, `pnpm i`, `pnpm build`,",
     "  `pnpm test`, or any other package-manager, build, or test command.",
     "  Emit the projen block and instructions only.",
     "- Never scaffold outside `apps/`. Shared libraries belong under",
@@ -3149,20 +3161,26 @@ var createSiteSkill = {
     "   `sites/<scope>/<name>`.",
     "",
     "6. **Tell the user how to synthesize.** Instruct them to run, from",
-    "   the repo root:",
+    "   the repo root, the safe three-step regen sequence:",
     "",
     "   ```",
+    "   pnpm i",
     "   pnpm exec projen",
-    "   pnpm install",
+    "   pnpm i",
     "   ```",
     "",
-    "   `pnpm exec projen` regenerates the sub-project tree;",
-    "   `pnpm install` updates the workspace lockfile. Do **not** run",
-    "   these commands yourself \u2014 the user runs them.",
+    "   The leading `pnpm i` syncs `node_modules` with `pnpm-lock.yaml`",
+    "   so synth runs against the right configulator/projen/plugin",
+    "   versions \u2014 without it, `pnpm exec projen` may synth against a",
+    "   stale resolved version of any pnpm-managed component and produce",
+    "   phantom drift in generated files. `pnpm exec projen` regenerates",
+    "   the sub-project tree; the trailing `pnpm i` updates the workspace",
+    "   lockfile to pick up any dependency changes projen wrote during",
+    "   synth. Do **not** run these commands yourself \u2014 the user runs them.",
     "",
     "## Guardrails",
     "",
-    "- Never run `pnpm exec projen`, `pnpm install`, `pnpm build`,",
+    "- Never run `pnpm exec projen`, `pnpm install`, `pnpm i`, `pnpm build`,",
     "  `pnpm test`, or any other package-manager, build, or test command.",
     "  Emit the projen block and instructions only.",
     "- Never scaffold the monorepo-wide docs site under `sites/`. The",
@@ -3266,7 +3284,7 @@ function buildBaseBundle(paths = DEFAULT_AGENT_PATHS) {
           "## Important Notes",
           "",
           "- **Never edit generated files** \u2014 they are marked with `// ~~ Generated by projen`",
-          "- **After modifying Projen configuration**, run `pnpm exec projen` to regenerate files, then `pnpm install` to update the lockfile.",
+          "- **After modifying Projen configuration**, run the three-step regen sequence: `pnpm i`, then `pnpm exec projen`, then `pnpm i` again. The leading `pnpm i` syncs `node_modules` with the lockfile so synth runs against the right configulator/projen/plugin versions; the trailing `pnpm i` refreshes the lockfile to match anything projen rewrote in `package.json`.",
           "- **Configure dependencies through Projen** \u2014 never use `npm install`, `pnpm add`, or `yarn add`. Add them to `deps` or `devDeps` in Projen config.",
           "- **Export from index.ts** to maintain clean public APIs",
           "",
@@ -3325,7 +3343,7 @@ function buildBaseBundle(paths = DEFAULT_AGENT_PATHS) {
           "",
           "After making changes that need validation, tell the user the specific commands to run:",
           "",
-          "1. **After projen config changes** \u2014 tell the user to run `pnpm exec projen && pnpm install`",
+          "1. **After projen config changes** \u2014 tell the user to run the three-step regen sequence: `pnpm i && pnpm exec projen && pnpm i`",
           "2. **After source code changes** \u2014 tell the user to run `pnpm --filter @codedrifters/<package> test`",
           "3. **After multi-package changes** \u2014 tell the user to run `pnpm build:all`"
         ].join("\n"),
@@ -9101,7 +9119,7 @@ var githubWorkflowBundle = {
         "",
         "When the user says **open a PR** (or similar), follow these steps exactly:",
         "",
-        "1. **Regenerate project files** \u2014 run `pnpm exec projen` then `pnpm install` to ensure all generated files are up to date. Check `git diff` \u2014 if there are changes, commit them before proceeding.",
+        "1. **Regenerate project files** \u2014 run the three-step regen sequence (`pnpm i`, then `pnpm exec projen`, then `pnpm i` again) to ensure all generated files are up to date. The leading `pnpm i` is required because `pnpm exec projen` synthesises against whatever version of configulator (and projen, and any projen plugins) is currently resolved in `node_modules`; if the lockfile has moved past `node_modules` (typically right after `git pull` lands a dependency upgrade, or on a fresh checkout), synth runs against stale templates and produces phantom drift in `.claude/`, `.github/labels.yml`, `CLAUDE.md`, and other generated files. The trailing `pnpm i` picks up any dependency changes projen wrote into `package.json` during synth. Check `git diff` after the third step \u2014 if there are changes, commit them before proceeding.",
         "2. **Run the full monorepo build** \u2014 run `pnpm build:all` to compile, lint, and test all packages (mirrors the CI pipeline). This command requires the user to be authenticated to AWS on the prod account used for Turborepo remote caching (`readonlyaccess-prod-525259625215-us-east-1` profile). If the command fails due to AWS credentials, ask the user to authenticate first. If the build produces changes to turbo inputs (typically snapshot files or ESLint auto-fixes), commit those changes and run `pnpm build:all` again \u2014 the build must complete cleanly with no uncommitted changes.",
         "3. **Check for uncommitted changes** \u2014 if any exist, commit them with a conventional commit message",
         "4. **Pull and rebase from the default branch** \u2014 run `git pull origin {{repository.defaultBranch}} --rebase` to incorporate the latest changes and resolve any conflicts before pushing",
@@ -13799,7 +13817,7 @@ var issueWorkerSubAgent = {
     "",
     "Run the appropriate verification commands depending on what changed:",
     "",
-    "1. If Projen config was changed: `pnpm exec projen && pnpm install`",
+    "1. If Projen config was changed: run the three-step regen sequence `pnpm i && pnpm exec projen && pnpm i` (leading `pnpm i` syncs `node_modules` with the lockfile so synth runs against the right configulator/projen/plugin versions; trailing `pnpm i` refreshes the lockfile after synth)",
     "2. Compile the affected package: `pnpm --filter @codedrifters/<package> compile`",
     "3. Test the affected package: `pnpm --filter @codedrifters/<package> test`",
     "4. If changes span multiple packages: `pnpm build:all`",
@@ -15090,7 +15108,7 @@ var pnpmBundle = {
         "- Configure dependencies in Projen configuration files (`.projenrc.ts` or `projenrc/*.ts`)",
         "- Add dependencies to `deps`, `devDeps`, or `peerDeps` arrays in project configuration",
         '- Use catalog dependencies when available (e.g., `"aws-cdk-lib@catalog:"`)',
-        "- Ask the user to run `pnpm exec projen` and `pnpm install` after updating dependency configuration",
+        "- Ask the user to run the three-step regen sequence after updating dependency configuration: `pnpm i`, then `pnpm exec projen`, then `pnpm i` again. The leading `pnpm i` syncs `node_modules` with the lockfile so synth runs against the right configulator/projen/plugin versions; the trailing `pnpm i` picks up any dependency changes projen wrote during synth.",
         "",
         "**DO NOT:**",
         "- Run `npm install some-package`",
@@ -16527,14 +16545,19 @@ var projenBundle = {
         "",
         "## Synthesizing Projen Configuration",
         "",
-        "After modifying any file in `projenrc/` or `.projenrc.ts`, regenerate project files:",
+        "After modifying any file in `projenrc/` or `.projenrc.ts`, regenerate project files using the safe three-step sequence:",
         "",
         "```sh",
+        "pnpm i",
         "pnpm exec projen",
-        "pnpm install",
+        "pnpm i",
         "```",
         "",
-        "Both steps are required \u2014 `pnpm exec projen` regenerates files, `pnpm install` updates the lockfile to match.",
+        "All three steps are required:",
+        "",
+        "1. The leading `pnpm i` guarantees `node_modules` matches `pnpm-lock.yaml` before synth. Without this step, `pnpm exec projen` may synth against a stale version of any pnpm-resolved component (configulator itself, projen, or any plugin) that the lockfile has already moved past \u2014 most commonly right after `git pull` updates the lockfile or on a fresh checkout. The result is phantom drift in `.claude/`, `.github/labels.yml`, `CLAUDE.md`, and other configulator-generated files that looks like a real bundle change but vanishes after running `pnpm i`.",
+        "2. `pnpm exec projen` regenerates files against the now-synced templates.",
+        "3. The trailing `pnpm i` picks up any dependency changes projen wrote into `package.json` during the synth pass and refreshes the lockfile.",
         "",
         "## Building",
         "",
@@ -16615,7 +16638,7 @@ var projenBundle = {
         "After finishing implementation work, validate that changes are correct by running the appropriate commands depending on what was changed:",
         "",
         "1. **Projen config changes** (`projenrc/`, `.projenrc.ts`):",
-        "   - Run `pnpm exec projen` then `pnpm install`",
+        "   - Run the three-step regen sequence: `pnpm i`, then `pnpm exec projen`, then `pnpm i` again",
         "   - Verify no unexpected generated file changes with `git diff`",
         "",
         "2. **Source code changes** (in a sub-package):",
@@ -16632,8 +16655,8 @@ var projenBundle = {
         "",
         "| Task | Command |",
         "|------|---------|",
-        "| Synthesize projen | `pnpm exec projen` |",
-        "| Install deps | `pnpm install` |",
+        "| Regenerate projen configuration | `pnpm i && pnpm exec projen && pnpm i` |",
+        "| Install deps | `pnpm i` |",
         "| Full monorepo build | `pnpm build:all` |",
         "| Root build only | `pnpm build` |",
         "| Compile one package | `pnpm --filter @codedrifters/<pkg> compile` |",
@@ -16691,7 +16714,7 @@ var projenBundle = {
         "",
         "## After Any Change",
         "",
-        "Run `pnpm exec projen` then `pnpm install` to regenerate the output files."
+        "Run the three-step regen sequence to regenerate the output files: `pnpm i`, then `pnpm exec projen`, then `pnpm i` again. The leading `pnpm i` syncs `node_modules` with the lockfile before synth so `pnpm exec projen` runs against the right configulator/projen/plugin versions; the trailing `pnpm i` refreshes the lockfile for any dependency changes projen made during synth."
       ].join("\n"),
       tags: ["workflow"]
     },
@@ -16709,7 +16732,7 @@ var projenBundle = {
         "- Edit Projen configuration in:",
         "  - `.projenrc.ts` (root)",
         "  - `projenrc/*.ts` (package-specific)",
-        "- After making Projen changes, run `pnpm exec projen` to synthesize",
+        "- After making Projen changes, run the three-step regen sequence: `pnpm i`, `pnpm exec projen`, `pnpm i`. The leading `pnpm i` ensures `node_modules` matches the lockfile so synth runs against the right configulator/projen/plugin versions; without it, synth can produce phantom drift in generated files. The trailing `pnpm i` picks up dependency changes projen wrote during synth.",
         "",
         "## Workspace Dependencies",
         "",
@@ -26554,8 +26577,8 @@ var FALLBACKS = {
   monorepoLayoutSeedBlock: ""
 };
 var TEMPLATE_RE = /\{\{(\w+(?:\.\w+)*)\}\}/g;
-function getNestedValue(obj, path7) {
-  const parts = path7.split(".");
+function getNestedValue(obj, path8) {
+  const parts = path8.split(".");
   let current = obj;
   for (const part of parts) {
     if (current == null || typeof current !== "object") {
@@ -29164,9 +29187,388 @@ function auditReportJsonSchema() {
   };
 }
 
+// src/docs-sync/scan/checks/api-diff-check.ts
+function parseApiRollup(rollup) {
+  const fenceContents = extractFirstTsFence(rollup);
+  if (fenceContents === void 0) {
+    return [];
+  }
+  const lines = fenceContents.split("\n");
+  const entries = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("export ")) {
+      i += 1;
+      continue;
+    }
+    const startIndex = i;
+    let buffer = trimmed;
+    let braceDepth = countBraceDelta(trimmed);
+    let endsWithSemicolon = trimmed.endsWith(";");
+    i += 1;
+    while (i < lines.length && !isComplete(buffer, braceDepth, endsWithSemicolon)) {
+      const next = lines[i];
+      const nextTrimmed = next.trim();
+      if (nextTrimmed.length === 0 || nextTrimmed.startsWith("//")) {
+        i += 1;
+        continue;
+      }
+      buffer = `${buffer} ${nextTrimmed}`;
+      braceDepth += countBraceDelta(nextTrimmed);
+      endsWithSemicolon = nextTrimmed.endsWith(";");
+      i += 1;
+    }
+    const normalized = normalizeWhitespace(buffer);
+    const name = extractDeclarationName(normalized);
+    if (name) {
+      entries.push({ name, signature: normalized });
+    }
+    if (name && normalized.startsWith("export {")) {
+      const names = extractExportListNames(normalized);
+      if (names.length > 1) {
+        entries.pop();
+        for (const exportName of names) {
+          entries.push({ name: exportName, signature: normalized });
+        }
+      }
+    }
+    if (i === startIndex) {
+      i += 1;
+    }
+  }
+  const dedup = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    if (!dedup.has(entry.name)) {
+      dedup.set(entry.name, entry);
+    }
+  }
+  return Array.from(dedup.values()).sort(
+    (a, b) => a.name.localeCompare(b.name)
+  );
+}
+function diffApiRollups(baselineRollup, currentRollup) {
+  const baseline = /* @__PURE__ */ new Map();
+  for (const entry of parseApiRollup(baselineRollup)) {
+    baseline.set(entry.name, entry);
+  }
+  const current = /* @__PURE__ */ new Map();
+  for (const entry of parseApiRollup(currentRollup)) {
+    current.set(entry.name, entry);
+  }
+  const added = [];
+  const removed = [];
+  const changed = [];
+  for (const [name, entry] of current.entries()) {
+    const before = baseline.get(name);
+    if (!before) {
+      added.push(entry);
+      continue;
+    }
+    if (before.signature !== entry.signature) {
+      changed.push(entry);
+    }
+  }
+  for (const [name, entry] of baseline.entries()) {
+    if (!current.has(name)) {
+      removed.push(entry);
+    }
+  }
+  added.sort((a, b) => a.name.localeCompare(b.name));
+  removed.sort((a, b) => a.name.localeCompare(b.name));
+  changed.sort((a, b) => a.name.localeCompare(b.name));
+  return { added, removed, changed };
+}
+function createApiDiffCheck(options) {
+  const baseline = options.baselineRollup;
+  const current = options.currentRollup;
+  const rollupPath = options.rollupPath ?? "";
+  return {
+    name: options.name ?? "apiDiff",
+    run(_context) {
+      const diff = diffApiRollups(baseline, current);
+      const findings = [];
+      for (const entry of diff.added) {
+        findings.push({
+          category: AuditCategory.ApiDiff,
+          severity: AuditSeverity.Mechanical,
+          location: { file: rollupPath, line: 0 },
+          subject: entry.name,
+          details: `New public export \`${entry.name}\` not present in baseline rollup.`,
+          change: "added",
+          symbol: entry.name,
+          fixHint: "stub-tsdoc"
+        });
+      }
+      for (const entry of diff.removed) {
+        findings.push({
+          category: AuditCategory.ApiDiff,
+          severity: AuditSeverity.Advisory,
+          location: { file: rollupPath, line: 0 },
+          subject: entry.name,
+          details: `Public export \`${entry.name}\` was present in baseline rollup but is gone in the current rollup.`,
+          change: "removed",
+          symbol: entry.name
+        });
+      }
+      for (const entry of diff.changed) {
+        findings.push({
+          category: AuditCategory.ApiDiff,
+          severity: AuditSeverity.Advisory,
+          location: { file: rollupPath, line: 0 },
+          subject: entry.name,
+          details: `Public export \`${entry.name}\` signature changed since baseline rollup.`,
+          change: "changed",
+          symbol: entry.name
+        });
+      }
+      return findings;
+    }
+  };
+}
+function extractFirstTsFence(rollup) {
+  const lines = rollup.split("\n");
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line === "```ts" || line === "```typescript") {
+      start = i + 1;
+      break;
+    }
+  }
+  if (start < 0) {
+    return void 0;
+  }
+  for (let j = start; j < lines.length; j++) {
+    if (lines[j].trim() === "```") {
+      return lines.slice(start, j).join("\n");
+    }
+  }
+  return lines.slice(start).join("\n");
+}
+function countBraceDelta(line) {
+  let delta = 0;
+  for (const ch of line) {
+    if (ch === "{") {
+      delta += 1;
+    } else if (ch === "}") {
+      delta -= 1;
+    }
+  }
+  return delta;
+}
+function isComplete(buffer, braceDepth, endsWithSemicolon) {
+  if (braceDepth > 0) {
+    return false;
+  }
+  if (endsWithSemicolon) {
+    return true;
+  }
+  return buffer.trimEnd().endsWith("}");
+}
+function normalizeWhitespace(s) {
+  return s.replace(/\s+/g, " ").replace(/\(\s+/g, "(").replace(/\s+\)/g, ")").replace(/\[\s+/g, "[").replace(/\s+\]/g, "]").replace(/\{\s+/g, "{").replace(/\s+\}/g, "}").replace(/\s+,/g, ",").replace(/\s+;/g, ";").replace(/\s+:/g, ":").trim();
+}
+var DECLARATION_KEYWORDS = [
+  "function",
+  "class",
+  "interface",
+  "type",
+  "enum",
+  "const",
+  "let",
+  "var",
+  "namespace",
+  "abstract",
+  "default",
+  "async"
+];
+function extractDeclarationName(declaration) {
+  const tokens = declaration.split(/\s+/);
+  if (tokens.length === 0 || tokens[0] !== "export") {
+    return void 0;
+  }
+  let cursor = 1;
+  while (cursor < tokens.length && DECLARATION_KEYWORDS.includes(tokens[cursor])) {
+    cursor += 1;
+  }
+  if (cursor >= tokens.length) {
+    return void 0;
+  }
+  const candidate = tokens[cursor];
+  if (candidate.startsWith("{")) {
+    const stripped = candidate.replace(/^\{/, "").replace(/[},].*$/, "");
+    return stripped || void 0;
+  }
+  const cleaned = candidate.replace(/[<(:;].*$/, "");
+  return cleaned || void 0;
+}
+function extractExportListNames(declaration) {
+  const open = declaration.indexOf("{");
+  const close = declaration.indexOf("}", open);
+  if (open < 0 || close < 0) {
+    return [];
+  }
+  const inside = declaration.slice(open + 1, close);
+  const names = [];
+  for (const part of inside.split(",")) {
+    const token = part.trim();
+    if (!token) {
+      continue;
+    }
+    const asMatch = token.match(/\sas\s+(\S+)$/);
+    if (asMatch) {
+      names.push(asMatch[1]);
+    } else {
+      names.push(token);
+    }
+  }
+  return names;
+}
+
+// src/docs-sync/scan/checks/reference-mismatch-check.ts
+function referenceRecordToFinding(record, signatureChangedSymbols) {
+  if (signatureChangedSymbols.has(record.symbol)) {
+    return {
+      category: AuditCategory.ReferenceMismatches,
+      severity: AuditSeverity.Advisory,
+      location: { file: record.docPath, line: record.line },
+      subject: record.symbol,
+      details: `Inline reference \`${record.symbol}\` resolves to a symbol whose signature has changed; review the surrounding prose.`,
+      mismatch: "signature-changed",
+      symbol: record.symbol
+    };
+  }
+  if (!record.isKnown) {
+    return {
+      category: AuditCategory.ReferenceMismatches,
+      severity: AuditSeverity.Advisory,
+      location: { file: record.docPath, line: record.line },
+      subject: record.symbol,
+      details: `Inline reference \`${record.symbol}\` does not match any known public export.`,
+      mismatch: "unknown-symbol",
+      symbol: record.symbol
+    };
+  }
+  return void 0;
+}
+function createReferenceMismatchCheck(options) {
+  const records = options.records;
+  const signatureChangedSymbols = new Set(
+    options.signatureChangedSymbols ?? []
+  );
+  return {
+    name: options.name ?? "referenceMismatches",
+    run(_context) {
+      const findings = [];
+      for (const record of records) {
+        const finding = referenceRecordToFinding(
+          record,
+          signatureChangedSymbols
+        );
+        if (finding !== void 0) {
+          findings.push(finding);
+        }
+      }
+      return findings;
+    }
+  };
+}
+
+// src/docs-sync/scan/checks/tsdoc-coverage-check.ts
+import * as path5 from "path";
+function tsdocRecordToFindings(record, context) {
+  const findings = [];
+  const file = relativizeFile(record.location.file, context.repoRoot);
+  const line = record.location.line;
+  const symbol = record.symbol;
+  if (!record.hasSummary) {
+    findings.push({
+      category: AuditCategory.TsdocCoverage,
+      severity: AuditSeverity.Mechanical,
+      location: { file, line },
+      subject: symbol,
+      details: `Public export \`${symbol}\` is missing a TSDoc summary.`,
+      shortfall: "missing-summary",
+      symbol,
+      fixHint: "stub-tsdoc"
+    });
+    return findings;
+  }
+  if (record.hasThinSummary) {
+    findings.push({
+      category: AuditCategory.TsdocCoverage,
+      severity: AuditSeverity.Advisory,
+      location: { file, line },
+      subject: symbol,
+      details: `Public export \`${symbol}\` carries a thin TSDoc summary; consider expanding it.`,
+      shortfall: "thin-summary",
+      symbol
+    });
+  }
+  if (!record.hasParams && isParamCarryingKind(record)) {
+    findings.push({
+      category: AuditCategory.TsdocCoverage,
+      severity: AuditSeverity.Advisory,
+      location: { file, line },
+      subject: symbol,
+      details: `Public export \`${symbol}\` has parameters with no \`@param\` block tag.`,
+      shortfall: "missing-params",
+      symbol
+    });
+  }
+  if (!record.hasReturns && isReturnCarryingKind(record)) {
+    findings.push({
+      category: AuditCategory.TsdocCoverage,
+      severity: AuditSeverity.Advisory,
+      location: { file, line },
+      subject: symbol,
+      details: `Public export \`${symbol}\` has a return value with no \`@returns\` block tag.`,
+      shortfall: "missing-returns",
+      symbol
+    });
+  }
+  return findings;
+}
+function createTsdocCoverageCheck(options) {
+  const records = options.records;
+  return {
+    name: options.name ?? "tsdocCoverage",
+    run(context) {
+      const findings = [];
+      for (const record of records) {
+        for (const finding of tsdocRecordToFindings(record, context)) {
+          findings.push(finding);
+        }
+      }
+      return findings;
+    }
+  };
+}
+function isParamCarryingKind(record) {
+  return record.kind === "Function";
+}
+function isReturnCarryingKind(record) {
+  return record.kind === "Function";
+}
+function relativizeFile(file, repoRoot) {
+  if (!file) {
+    return "";
+  }
+  if (!path5.isAbsolute(file)) {
+    return toPosix3(file);
+  }
+  const rel = path5.relative(repoRoot, file);
+  return toPosix3(rel);
+}
+function toPosix3(p) {
+  return p.split(path5.sep).join("/");
+}
+
 // src/docs-sync/scan/run-scan.ts
 import * as fs3 from "fs";
-import * as path5 from "path";
+import * as path6 from "path";
 var DEFAULT_AUDIT_REPORT_DIR = ".claude/state/docs-sync";
 var SEVERITY_RANK = {
   blocking: 0,
@@ -29181,7 +29583,7 @@ var AUDIT_CATEGORY_ORDER = [
   AuditCategory.SampleFailures
 ];
 function runScan(options) {
-  const repoRoot = path5.resolve(options.repoRoot);
+  const repoRoot = path6.resolve(options.repoRoot);
   const mode = options.mode;
   const scope = options.scope ?? "";
   const issueNumber = options.issueNumber;
@@ -29256,11 +29658,11 @@ function buildReport(args) {
   };
 }
 function persistAuditReport(args) {
-  const repoRoot = path5.resolve(args.repoRoot);
+  const repoRoot = path6.resolve(args.repoRoot);
   const reportDir = args.reportDir ?? DEFAULT_AUDIT_REPORT_DIR;
-  const targetDir = path5.resolve(repoRoot, reportDir);
+  const targetDir = path6.resolve(repoRoot, reportDir);
   fs3.mkdirSync(targetDir, { recursive: true });
-  const targetFile = path5.join(
+  const targetFile = path6.join(
     targetDir,
     `${args.report.issueNumber}-audit.json`
   );
@@ -29323,7 +29725,7 @@ function compareFindings(a, b) {
 }
 
 // src/docs-sync/tsdoc-coverage/coverage.ts
-import * as path6 from "path";
+import * as path7 from "path";
 import { TSDocParser } from "@microsoft/tsdoc";
 import * as ts2 from "typescript";
 var TsDocCoverageKind = {
@@ -29341,8 +29743,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 = path6.resolve(resolvedOptions.packageRoot);
-  const entryPoint = path6.resolve(
+  const packageRoot = path7.resolve(resolvedOptions.packageRoot);
+  const entryPoint = path7.resolve(
     packageRoot,
     resolvedOptions.entryPoint ?? DEFAULT_ENTRY_POINT
   );
@@ -29405,7 +29807,7 @@ function analyzeTsDocCoverage(options) {
 }
 function resolveCompilerOptions(packageRoot, tsconfigPath) {
   if (tsconfigPath) {
-    const absoluteTsconfig = path6.resolve(packageRoot, tsconfigPath);
+    const absoluteTsconfig = path7.resolve(packageRoot, tsconfigPath);
     const configFile = ts2.readConfigFile(absoluteTsconfig, ts2.sys.readFile);
     if (configFile.error) {
       throw new Error(
@@ -29415,7 +29817,7 @@ function resolveCompilerOptions(packageRoot, tsconfigPath) {
     const parsed = ts2.parseJsonConfigFileContent(
       configFile.config,
       ts2.sys,
-      path6.dirname(absoluteTsconfig)
+      path7.dirname(absoluteTsconfig)
     );
     return { ...parsed.options, noEmit: true };
   }
@@ -29724,14 +30126,14 @@ var LAYOUT_ROOT_BY_PROJECT_TYPE = {
 };
 function validateMonorepoLayout(root) {
   const violations = [];
-  const rootOutdir = toPosix3(root.outdir);
+  const rootOutdir = toPosix4(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, toPosix3(sub.outdir));
+    const relOutdir = relativeOutdir(rootOutdir, toPosix4(sub.outdir));
     if (!outdirMatchesRoot(relOutdir, expectedRoot)) {
       violations.push({
         projectName: sub.name,
@@ -29790,7 +30192,7 @@ function outdirMatchesRoot(relOutdir, expectedRoot) {
   }
   return segments.length >= 2;
 }
-function toPosix3(p) {
+function toPosix4(p) {
   return p.replace(/\\/g, "/");
 }
 function relativeOutdir(rootOutdir, subOutdir) {
@@ -29879,8 +30281,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((path7) => {
-      resetTask.exec(`[ -e "${path7}" ] && rm -rf ${path7} || true`);
+    this.pathsToRemove.forEach((path8) => {
+      resetTask.exec(`[ -e "${path8}" ] && rm -rf ${path8} || true`);
     });
     const rootHasTurbo = TurboRepo.of(this.project.root) !== void 0;
     const isSubproject = this.project !== this.project.root;
@@ -31801,7 +32203,7 @@ export const collections = {
 `;
 
 // src/typescript/typescript-config.ts
-import { relative as relative6 } from "path";
+import { relative as relative7 } from "path";
 import { Component as Component19 } from "projen";
 import { ensureRelativePathStartsWithDot } from "projen/lib/util/path";
 var TypeScriptConfig = class extends Component19 {
@@ -31820,7 +32222,7 @@ var TypeScriptConfig = class extends Component19 {
         ...tsPaths,
         [dep.name]: [
           ensureRelativePathStartsWithDot(
-            relative6(project.outdir, subproject.outdir)
+            relative7(project.outdir, subproject.outdir)
           )
         ]
       };
@@ -31976,7 +32378,11 @@ export {
   classifyRun,
   companyProfileBundle,
   compileFencedSamples,
+  createApiDiffCheck,
+  createReferenceMismatchCheck,
+  createTsdocCoverageCheck,
   customerProfileBundle,
+  diffApiRollups,
   docsSyncBundle,
   emptyCategoryBuckets,
   extractApiProcedure,
@@ -31991,11 +32397,13 @@ export {
   maintenanceAuditBundle,
   meetingAnalysisBundle,
   orchestratorBundle,
+  parseApiRollup,
   peopleProfileBundle,
   persistAuditReport,
   pnpmBundle,
   prReviewBundle,
   projenBundle,
+  referenceRecordToFinding,
   regulatoryResearchBundle,
   renderAgentTierCaseStatement,
   renderAgentTierSection,
@@ -32058,6 +32466,7 @@ export {
   slackBundle,
   softwareProfileBundle,
   standardsResearchBundle,
+  tsdocRecordToFindings,
   turborepoBundle,
   typescriptBundle,
   validateAgentTierConfig,