@codedrifters/configulator 0.0.269 → 0.0.271

package/lib/index.js

@@ -270,6 +270,7 @@ __export(index_exports, {
   STARLIGHT_ROLE: () => STARLIGHT_ROLE,
   StarlightProject: () => StarlightProject,
   TestRunner: () => TestRunner,
+  TsDocCoverageKind: () => TsDocCoverageKind,
   TurboRepo: () => TurboRepo,
   TurboRepoTask: () => TurboRepoTask,
   TypeScriptConfig: () => TypeScriptConfig,
@@ -284,6 +285,7 @@ __export(index_exports, {
   addBuildCompleteJob: () => addBuildCompleteJob,
   addSyncLabelsWorkflow: () => addSyncLabelsWorkflow,
   agendaBundle: () => agendaBundle,
+  analyzeTsDocCoverage: () => analyzeTsDocCoverage,
   awsCdkBundle: () => awsCdkBundle,
   baseBundle: () => baseBundle,
   bcmWriterBundle: () => bcmWriterBundle,
@@ -314,6 +316,7 @@ __export(index_exports, {
   customerProfileBundle: () => customerProfileBundle,
   docsSyncBundle: () => docsSyncBundle,
   extractApiProcedure: () => extractApiProcedure,
+  extractDocReferences: () => extractDocReferences,
   formatLayoutViolation: () => formatLayoutViolation,
   formatStarlightSingletonViolation: () => formatStarlightSingletonViolation,
   getLatestEligibleVersion: () => getLatestEligibleVersion,
@@ -26768,8 +26771,8 @@ var FALLBACKS = {
   monorepoLayoutSeedBlock: ""
 };
 var TEMPLATE_RE = /\{\{(\w+(?:\.\w+)*)\}\}/g;
-function getNestedValue(obj, path2) {
-  const parts = path2.split(".");
+function getNestedValue(obj, path4) {
+  const parts = path4.split(".");
   let current = obj;
   for (const part of parts) {
     if (current == null || typeof current !== "object") {
@@ -26995,20 +26998,20 @@ var ClaudeRenderer = class _ClaudeRenderer {
       obj.excludedCommands = [...sandbox.excludedCommands];
     }
     if (sandbox.filesystem) {
-      const fs = {};
+      const fs2 = {};
       if (sandbox.filesystem.allowRead?.length) {
-        fs.allowRead = [...sandbox.filesystem.allowRead];
+        fs2.allowRead = [...sandbox.filesystem.allowRead];
       }
       if (sandbox.filesystem.denyRead?.length) {
-        fs.denyRead = [...sandbox.filesystem.denyRead];
+        fs2.denyRead = [...sandbox.filesystem.denyRead];
       }
       if (sandbox.filesystem.allowWrite?.length) {
-        fs.allowWrite = [...sandbox.filesystem.allowWrite];
+        fs2.allowWrite = [...sandbox.filesystem.allowWrite];
       }
       if (sandbox.filesystem.denyWrite?.length) {
-        fs.denyWrite = [...sandbox.filesystem.denyWrite];
+        fs2.denyWrite = [...sandbox.filesystem.denyWrite];
       }
-      if (Object.keys(fs).length > 0) obj.filesystem = fs;
+      if (Object.keys(fs2).length > 0) obj.filesystem = fs2;
     }
     if (sandbox.network) {
       const net = {};
@@ -28753,6 +28756,343 @@ var AwsDeploymentTarget = class _AwsDeploymentTarget extends import_projen12.Com
   }
 };
 
+// src/docs-sync/reference-extraction/extraction.ts
+var fs = __toESM(require("fs"));
+var path2 = __toESM(require("path"));
+var import_mdast_util_from_markdown = require("mdast-util-from-markdown");
+var DEFAULT_DOCS_ROOT = "docs/src/content/docs";
+var DEFAULT_SYMBOL_PATTERN = /^(?:[a-z][a-zA-Z0-9]*|[A-Z][a-zA-Z0-9]*|[A-Z][A-Z0-9_]*)$/;
+function extractDocReferences(options = {}) {
+  const docsRoot = path2.resolve(options.docsRoot ?? DEFAULT_DOCS_ROOT);
+  const symbolPattern = options.symbolPattern ?? DEFAULT_SYMBOL_PATTERN;
+  const knownSymbols = new Set(options.knownSymbols ?? []);
+  if (!fs.existsSync(docsRoot)) {
+    return [];
+  }
+  const records = [];
+  for (const absolutePath of walkMarkdownFiles(docsRoot)) {
+    const docPath = toPosix(path2.relative(docsRoot, absolutePath));
+    const source = fs.readFileSync(absolutePath, "utf-8");
+    const tree = (0, import_mdast_util_from_markdown.fromMarkdown)(stripYamlFrontmatter(source));
+    collectInlineCode(tree, (symbol, position) => {
+      if (!symbolPattern.test(symbol)) {
+        return;
+      }
+      records.push({
+        docPath,
+        line: position.line,
+        column: position.column,
+        symbol,
+        isKnown: knownSymbols.has(symbol)
+      });
+    });
+  }
+  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;
+    }
+    if (a.column !== b.column) {
+      return a.column - b.column;
+    }
+    return a.symbol.localeCompare(b.symbol);
+  });
+  return records;
+}
+function walkMarkdownFiles(root) {
+  const out = [];
+  const stack = [root];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path2.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 collectInlineCode(tree, visit) {
+  walk(tree);
+  function walk(node) {
+    if (node.type === "inlineCode") {
+      const start = node.position?.start;
+      if (!start) {
+        return;
+      }
+      visit(node.value, { line: start.line, column: start.column });
+      return;
+    }
+    if (node.type === "code" || node.type === "html") {
+      return;
+    }
+    const parent = node;
+    if (Array.isArray(parent.children)) {
+      for (const child of parent.children) {
+        walk(child);
+      }
+    }
+  }
+}
+function toPosix(p) {
+  return p.split(path2.sep).join("/");
+}
+function stripYamlFrontmatter(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/tsdoc-coverage/coverage.ts
+var path3 = __toESM(require("path"));
+var import_tsdoc = require("@microsoft/tsdoc");
+var ts = __toESM(require("typescript"));
+var TsDocCoverageKind = {
+  Class: "Class",
+  Interface: "Interface",
+  TypeAlias: "TypeAlias",
+  Enum: "Enum",
+  Function: "Function",
+  Variable: "Variable",
+  Module: "Module",
+  Default: "Default",
+  Other: "Other"
+};
+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(
+    packageRoot,
+    resolvedOptions.entryPoint ?? DEFAULT_ENTRY_POINT
+  );
+  const thinThreshold = resolvedOptions.thinSummaryWordThreshold ?? DEFAULT_THIN_SUMMARY_WORD_THRESHOLD;
+  const compilerOptions = resolveCompilerOptions(
+    packageRoot,
+    resolvedOptions.tsconfigPath
+  );
+  const program = ts.createProgram({
+    rootNames: [entryPoint],
+    options: compilerOptions
+  });
+  const checker = program.getTypeChecker();
+  const entrySource = program.getSourceFile(entryPoint);
+  if (!entrySource) {
+    throw new Error(
+      `analyzeTsDocCoverage: entry point not found in program: ${entryPoint}`
+    );
+  }
+  const moduleSymbol = checker.getSymbolAtLocation(entrySource);
+  if (!moduleSymbol) {
+    return [];
+  }
+  const tsdocParser = new import_tsdoc.TSDocParser();
+  const records = [];
+  for (const exportSymbol of checker.getExportsOfModule(moduleSymbol)) {
+    const resolved = resolveAlias(exportSymbol, checker);
+    const declaration = pickPrimaryDeclaration(resolved);
+    if (!declaration) {
+      continue;
+    }
+    const kind = classifyDeclaration(declaration);
+    const location = resolveLocation(declaration);
+    const tsdoc = parseTsDocFor(declaration, tsdocParser);
+    const summaryWordCount = tsdoc ? countSummaryWords(tsdoc) : 0;
+    const hasSummary = summaryWordCount > 0;
+    const hasThinSummary = hasSummary && summaryWordCount <= thinThreshold;
+    const hasParams = tsdoc ? hasBlockTag(tsdoc, "@param") : false;
+    const hasReturns = tsdoc ? hasBlockTag(tsdoc, "@returns") || hasBlockTag(tsdoc, "@return") : false;
+    records.push({
+      symbol: exportSymbol.getName(),
+      kind,
+      location,
+      hasSummary,
+      hasThinSummary,
+      hasParams,
+      hasReturns
+    });
+  }
+  records.sort((a, b) => {
+    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.symbol.localeCompare(b.symbol);
+  });
+  return records;
+}
+function resolveCompilerOptions(packageRoot, tsconfigPath) {
+  if (tsconfigPath) {
+    const absoluteTsconfig = path3.resolve(packageRoot, tsconfigPath);
+    const configFile = ts.readConfigFile(absoluteTsconfig, ts.sys.readFile);
+    if (configFile.error) {
+      throw new Error(
+        `analyzeTsDocCoverage: failed to read tsconfig at ${absoluteTsconfig}: ${ts.flattenDiagnosticMessageText(configFile.error.messageText, "\n")}`
+      );
+    }
+    const parsed = ts.parseJsonConfigFileContent(
+      configFile.config,
+      ts.sys,
+      path3.dirname(absoluteTsconfig)
+    );
+    return { ...parsed.options, noEmit: true };
+  }
+  return {
+    target: ts.ScriptTarget.ESNext,
+    module: ts.ModuleKind.NodeNext,
+    moduleResolution: ts.ModuleResolutionKind.NodeNext,
+    allowJs: false,
+    declaration: false,
+    noEmit: true,
+    skipLibCheck: true,
+    strict: false,
+    esModuleInterop: true,
+    resolveJsonModule: true
+  };
+}
+function resolveAlias(symbol, checker) {
+  let current = symbol;
+  for (let i = 0; i < 32; i++) {
+    if (!isAlias(current)) {
+      return current;
+    }
+    const next = checker.getAliasedSymbol(current);
+    if (!next || next === current) {
+      return current;
+    }
+    current = next;
+  }
+  return current;
+}
+function isAlias(symbol) {
+  return (symbol.flags & ts.SymbolFlags.Alias) !== 0;
+}
+function pickPrimaryDeclaration(symbol) {
+  const declarations = symbol.getDeclarations();
+  if (!declarations || declarations.length === 0) {
+    return void 0;
+  }
+  const concrete = declarations.find(
+    (d) => !ts.isExportSpecifier(d) && !ts.isExportAssignment(d) && !ts.isExportDeclaration(d)
+  );
+  return concrete ?? declarations[0];
+}
+function classifyDeclaration(declaration) {
+  if (ts.isClassDeclaration(declaration)) {
+    return TsDocCoverageKind.Class;
+  }
+  if (ts.isInterfaceDeclaration(declaration)) {
+    return TsDocCoverageKind.Interface;
+  }
+  if (ts.isTypeAliasDeclaration(declaration)) {
+    return TsDocCoverageKind.TypeAlias;
+  }
+  if (ts.isEnumDeclaration(declaration)) {
+    return TsDocCoverageKind.Enum;
+  }
+  if (ts.isFunctionDeclaration(declaration) || ts.isMethodDeclaration(declaration)) {
+    return TsDocCoverageKind.Function;
+  }
+  if (ts.isVariableDeclaration(declaration) || ts.isVariableStatement(declaration)) {
+    return TsDocCoverageKind.Variable;
+  }
+  if (ts.isModuleDeclaration(declaration)) {
+    return TsDocCoverageKind.Module;
+  }
+  if (ts.isExportAssignment(declaration)) {
+    return TsDocCoverageKind.Default;
+  }
+  return TsDocCoverageKind.Other;
+}
+function resolveLocation(declaration) {
+  const target = ts.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 sourceText = target.getSourceFile().getFullText();
+  const ranges = ts.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) {
+      continue;
+    }
+    const text = sourceText.slice(range.pos, range.end);
+    if (!text.startsWith("/**")) {
+      continue;
+    }
+    const parsed = parser.parseString(text);
+    return parsed.docComment;
+  }
+  return void 0;
+}
+function countSummaryWords(doc) {
+  let words = 0;
+  doc.summarySection.nodes.forEach((node) => {
+    words += countWordsInNode(node);
+  });
+  return words;
+}
+function countWordsInNode(node) {
+  const anyNode = node;
+  if (anyNode.kind === "PlainText" && typeof anyNode.text === "string") {
+    return anyNode.text.split(/\s+/).filter((token) => token.trim().length > 0).length;
+  }
+  let words = 0;
+  const children = anyNode.getChildNodes?.() ?? [];
+  for (const child of children) {
+    words += countWordsInNode(child);
+  }
+  return words;
+}
+function hasBlockTag(doc, tagName) {
+  if (tagName === "@param") {
+    return doc.params.count > 0;
+  }
+  if (tagName === "@returns" || tagName === "@return") {
+    return doc.returnsBlock !== void 0;
+  }
+  return doc.customBlocks.some((block) => block.blockTag.tagName === tagName);
+}
+
 // src/latest-eligible-version.ts
 var NPM_REGISTRY = "https://registry.npmjs.org";
 function isPrerelease(version) {
@@ -28934,14 +29274,14 @@ var LAYOUT_ROOT_BY_PROJECT_TYPE = {
 };
 function validateMonorepoLayout(root) {
   const violations = [];
-  const rootOutdir = toPosix(root.outdir);
+  const rootOutdir = toPosix2(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, toPosix(sub.outdir));
+    const relOutdir = relativeOutdir(rootOutdir, toPosix2(sub.outdir));
     if (!outdirMatchesRoot(relOutdir, expectedRoot)) {
       violations.push({
         projectName: sub.name,
@@ -29000,7 +29340,7 @@ function outdirMatchesRoot(relOutdir, expectedRoot) {
   }
   return segments.length >= 2;
 }
-function toPosix(p) {
+function toPosix2(p) {
   return p.replace(/\\/g, "/");
 }
 function relativeOutdir(rootOutdir, subOutdir) {
@@ -29080,8 +29420,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((path2) => {
-      resetTask.exec(`[ -e "${path2}" ] && rm -rf ${path2} || true`);
+    this.pathsToRemove.forEach((path4) => {
+      resetTask.exec(`[ -e "${path4}" ] && rm -rf ${path4} || true`);
     });
     const rootHasTurbo = TurboRepo.of(this.project.root) !== void 0;
     const isSubproject = this.project !== this.project.root;
@@ -31099,6 +31439,7 @@ var TypeScriptConfig = class extends import_projen23.Component {
   STARLIGHT_ROLE,
   StarlightProject,
   TestRunner,
+  TsDocCoverageKind,
   TurboRepo,
   TurboRepoTask,
   TypeScriptConfig,
@@ -31113,6 +31454,7 @@ var TypeScriptConfig = class extends import_projen23.Component {
   addBuildCompleteJob,
   addSyncLabelsWorkflow,
   agendaBundle,
+  analyzeTsDocCoverage,
   awsCdkBundle,
   baseBundle,
   bcmWriterBundle,
@@ -31143,6 +31485,7 @@ var TypeScriptConfig = class extends import_projen23.Component {
   customerProfileBundle,
   docsSyncBundle,
   extractApiProcedure,
+  extractDocReferences,
   formatLayoutViolation,
   formatStarlightSingletonViolation,
   getLatestEligibleVersion,