@codedrifters/configulator 0.0.269 → 0.0.270

package/lib/index.mjs

@@ -26530,8 +26530,8 @@ var FALLBACKS = {
   monorepoLayoutSeedBlock: ""
 };
 var TEMPLATE_RE = /\{\{(\w+(?:\.\w+)*)\}\}/g;
-function getNestedValue(obj, path2) {
-  const parts = path2.split(".");
+function getNestedValue(obj, path3) {
+  const parts = path3.split(".");
   let current = obj;
   for (const part of parts) {
     if (current == null || typeof current !== "object") {
@@ -28515,6 +28515,226 @@ var AwsDeploymentTarget = class _AwsDeploymentTarget extends Component12 {
   }
 };
 
+// src/docs-sync/tsdoc-coverage/coverage.ts
+import * as path2 from "path";
+import { TSDocParser } from "@microsoft/tsdoc";
+import * as ts from "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 = path2.resolve(resolvedOptions.packageRoot);
+  const entryPoint = path2.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 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 = path2.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,
+      path2.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) {
@@ -28851,8 +29071,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((path2) => {
-      resetTask.exec(`[ -e "${path2}" ] && rm -rf ${path2} || true`);
+    this.pathsToRemove.forEach((path3) => {
+      resetTask.exec(`[ -e "${path3}" ] && rm -rf ${path3} || true`);
     });
     const rootHasTurbo = TurboRepo.of(this.project.root) !== void 0;
     const isSubproject = this.project !== this.project.root;
@@ -30873,6 +31093,7 @@ export {
   STARLIGHT_ROLE,
   StarlightProject,
   TestRunner,
+  TsDocCoverageKind,
   TurboRepo,
   TurboRepoTask,
   TypeScriptConfig,
@@ -30887,6 +31108,7 @@ export {
   addBuildCompleteJob,
   addSyncLabelsWorkflow,
   agendaBundle,
+  analyzeTsDocCoverage,
   awsCdkBundle,
   baseBundle,
   bcmWriterBundle,