@codedrifters/configulator 0.0.276 → 0.0.277

package/lib/index.js

@@ -321,7 +321,11 @@ __export(index_exports, {
   classifyRun: () => classifyRun,
   companyProfileBundle: () => companyProfileBundle,
   compileFencedSamples: () => compileFencedSamples,
+  createApiDiffCheck: () => createApiDiffCheck,
+  createReferenceMismatchCheck: () => createReferenceMismatchCheck,
+  createTsdocCoverageCheck: () => createTsdocCoverageCheck,
   customerProfileBundle: () => customerProfileBundle,
+  diffApiRollups: () => diffApiRollups,
   docsSyncBundle: () => docsSyncBundle,
   emptyCategoryBuckets: () => emptyCategoryBuckets,
   extractApiProcedure: () => extractApiProcedure,
@@ -336,11 +340,13 @@ __export(index_exports, {
   maintenanceAuditBundle: () => maintenanceAuditBundle,
   meetingAnalysisBundle: () => meetingAnalysisBundle,
   orchestratorBundle: () => orchestratorBundle,
+  parseApiRollup: () => parseApiRollup,
   peopleProfileBundle: () => peopleProfileBundle,
   persistAuditReport: () => persistAuditReport,
   pnpmBundle: () => pnpmBundle,
   prReviewBundle: () => prReviewBundle,
   projenBundle: () => projenBundle,
+  referenceRecordToFinding: () => referenceRecordToFinding,
   regulatoryResearchBundle: () => regulatoryResearchBundle,
   renderAgentTierCaseStatement: () => renderAgentTierCaseStatement,
   renderAgentTierSection: () => renderAgentTierSection,
@@ -403,6 +409,7 @@ __export(index_exports, {
   slackBundle: () => slackBundle,
   softwareProfileBundle: () => softwareProfileBundle,
   standardsResearchBundle: () => standardsResearchBundle,
+  tsdocRecordToFindings: () => tsdocRecordToFindings,
   turborepoBundle: () => turborepoBundle,
   typescriptBundle: () => typescriptBundle,
   validateAgentTierConfig: () => validateAgentTierConfig,
@@ -26803,8 +26810,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") {
@@ -29413,9 +29420,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
+var path5 = __toESM(require("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
 var fs3 = __toESM(require("fs"));
-var path5 = __toESM(require("path"));
+var path6 = __toESM(require("path"));
 var DEFAULT_AUDIT_REPORT_DIR = ".claude/state/docs-sync";
 var SEVERITY_RANK = {
   blocking: 0,
@@ -29430,7 +29816,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;
@@ -29505,11 +29891,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`
   );
@@ -29572,7 +29958,7 @@ function compareFindings(a, b) {
 }
 
 // src/docs-sync/tsdoc-coverage/coverage.ts
-var path6 = __toESM(require("path"));
+var path7 = __toESM(require("path"));
 var import_tsdoc = require("@microsoft/tsdoc");
 var ts2 = __toESM(require("typescript"));
 var TsDocCoverageKind = {
@@ -29590,8 +29976,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
   );
@@ -29654,7 +30040,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(
@@ -29664,7 +30050,7 @@ function resolveCompilerOptions(packageRoot, tsconfigPath) {
     const parsed = ts2.parseJsonConfigFileContent(
       configFile.config,
       ts2.sys,
-      path6.dirname(absoluteTsconfig)
+      path7.dirname(absoluteTsconfig)
     );
     return { ...parsed.options, noEmit: true };
   }
@@ -29973,14 +30359,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,
@@ -30039,7 +30425,7 @@ function outdirMatchesRoot(relOutdir, expectedRoot) {
   }
   return segments.length >= 2;
 }
-function toPosix3(p) {
+function toPosix4(p) {
   return p.replace(/\\/g, "/");
 }
 function relativeOutdir(rootOutdir, subOutdir) {
@@ -30119,8 +30505,8 @@ var ResetTask = class _ResetTask extends import_projen14.Component {
     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;
@@ -32213,7 +32599,11 @@ var TypeScriptConfig = class extends import_projen23.Component {
   classifyRun,
   companyProfileBundle,
   compileFencedSamples,
+  createApiDiffCheck,
+  createReferenceMismatchCheck,
+  createTsdocCoverageCheck,
   customerProfileBundle,
+  diffApiRollups,
   docsSyncBundle,
   emptyCategoryBuckets,
   extractApiProcedure,
@@ -32228,11 +32618,13 @@ var TypeScriptConfig = class extends import_projen23.Component {
   maintenanceAuditBundle,
   meetingAnalysisBundle,
   orchestratorBundle,
+  parseApiRollup,
   peopleProfileBundle,
   persistAuditReport,
   pnpmBundle,
   prReviewBundle,
   projenBundle,
+  referenceRecordToFinding,
   regulatoryResearchBundle,
   renderAgentTierCaseStatement,
   renderAgentTierSection,
@@ -32295,6 +32687,7 @@ var TypeScriptConfig = class extends import_projen23.Component {
   slackBundle,
   softwareProfileBundle,
   standardsResearchBundle,
+  tsdocRecordToFindings,
   turborepoBundle,
   typescriptBundle,
   validateAgentTierConfig,