@codedrifters/configulator 0.0.274 → 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",
@@ -26943,8 +27000,8 @@ var FALLBACKS = {
   monorepoLayoutSeedBlock: ""
 };
 var TEMPLATE_RE = /\{\{(\w+(?:\.\w+)*)\}\}/g;
-function getNestedValue(obj, path6) {
-  const parts = path6.split(".");
+function getNestedValue(obj, path7) {
+  const parts = path7.split(".");
   let current = obj;
   for (const part of parts) {
     if (current == null || typeof current !== "object") {
@@ -27170,20 +27227,20 @@ var ClaudeRenderer = class _ClaudeRenderer {
       obj.excludedCommands = [...sandbox.excludedCommands];
     }
     if (sandbox.filesystem) {
-      const fs3 = {};
+      const fs4 = {};
       if (sandbox.filesystem.allowRead?.length) {
-        fs3.allowRead = [...sandbox.filesystem.allowRead];
+        fs4.allowRead = [...sandbox.filesystem.allowRead];
       }
       if (sandbox.filesystem.denyRead?.length) {
-        fs3.denyRead = [...sandbox.filesystem.denyRead];
+        fs4.denyRead = [...sandbox.filesystem.denyRead];
       }
       if (sandbox.filesystem.allowWrite?.length) {
-        fs3.allowWrite = [...sandbox.filesystem.allowWrite];
+        fs4.allowWrite = [...sandbox.filesystem.allowWrite];
       }
       if (sandbox.filesystem.denyWrite?.length) {
-        fs3.denyWrite = [...sandbox.filesystem.denyWrite];
+        fs4.denyWrite = [...sandbox.filesystem.denyWrite];
       }
-      if (Object.keys(fs3).length > 0) obj.filesystem = fs3;
+      if (Object.keys(fs4).length > 0) obj.filesystem = fs4;
     }
     if (sandbox.network) {
       const net = {};
@@ -29392,8 +29449,405 @@ function formatDiagnostic(d) {
   return `${code}${text}`.trim();
 }
 
-// src/docs-sync/tsdoc-coverage/coverage.ts
+// 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 ts2 from "typescript";
 var TsDocCoverageKind = {
@@ -29411,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 = path5.resolve(resolvedOptions.packageRoot);
-  const entryPoint = path5.resolve(
+  const packageRoot = path6.resolve(resolvedOptions.packageRoot);
+  const entryPoint = path6.resolve(
     packageRoot,
     resolvedOptions.entryPoint ?? DEFAULT_ENTRY_POINT
   );
@@ -29475,7 +29929,7 @@ function analyzeTsDocCoverage(options) {
 }
 function resolveCompilerOptions(packageRoot, tsconfigPath) {
   if (tsconfigPath) {
-    const absoluteTsconfig = path5.resolve(packageRoot, tsconfigPath);
+    const absoluteTsconfig = path6.resolve(packageRoot, tsconfigPath);
     const configFile = ts2.readConfigFile(absoluteTsconfig, ts2.sys.readFile);
     if (configFile.error) {
       throw new Error(
@@ -29485,7 +29939,7 @@ function resolveCompilerOptions(packageRoot, tsconfigPath) {
     const parsed = ts2.parseJsonConfigFileContent(
       configFile.config,
       ts2.sys,
-      path5.dirname(absoluteTsconfig)
+      path6.dirname(absoluteTsconfig)
     );
     return { ...parsed.options, noEmit: true };
   }
@@ -29949,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((path6) => {
-      resetTask.exec(`[ -e "${path6}" ] && rm -rf ${path6} || 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;
@@ -31892,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,
@@ -31912,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,
@@ -31959,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,
@@ -32000,6 +32460,7 @@ export {
   addSyncLabelsWorkflow,
   agendaBundle,
   analyzeTsDocCoverage,
+  auditReportJsonSchema,
   awsCdkBundle,
   baseBundle,
   bcmWriterBundle,
@@ -32016,6 +32477,7 @@ export {
   buildOrchestratorConventionsContent,
   buildPeopleProfileBundle,
   buildRegulatoryResearchBundle,
+  buildReport,
   buildRequirementsAnalystBundle,
   buildRequirementsReviewerBundle,
   buildRequirementsWriterBundle,
@@ -32032,6 +32494,7 @@ export {
   compileFencedSamples,
   customerProfileBundle,
   docsSyncBundle,
+  emptyCategoryBuckets,
   extractApiProcedure,
   extractDocReferences,
   extractFencedSamples,
@@ -32045,6 +32508,7 @@ export {
   meetingAnalysisBundle,
   orchestratorBundle,
   peopleProfileBundle,
+  persistAuditReport,
   pnpmBundle,
   prReviewBundle,
   projenBundle,
@@ -32111,6 +32575,7 @@ export {
   resolveTypeScriptProjectOutdir,
   resolveUnblockDependents,
   resolveWorkflowDiagrams,
+  runScan,
   slackBundle,
   softwareProfileBundle,
   standardsResearchBundle,