@doccov/sdk 0.6.0 → 0.8.0

package/dist/index.js

@@ -1,3 +1,22 @@
+import { createRequire } from "node:module";
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __require = createRequire(import.meta.url);
+
 // src/analysis/docs-coverage.ts
 import ts from "typescript";
 
@@ -2042,7 +2061,36 @@ function createAnalysisContext({
 // src/analysis/spec-builder.ts
 import * as fs2 from "node:fs";
 import * as path3 from "node:path";
-import { SCHEMA_URL } from "@openpkg-ts/spec";
+import { SCHEMA_URL, SCHEMA_VERSION } from "@openpkg-ts/spec";
+
+// src/analysis/decorator-utils.ts
+function extractDecorators(node) {
+  if (!ts2.canHaveDecorators(node)) {
+    return;
+  }
+  const decorators = ts2.getDecorators(node);
+  if (!decorators || decorators.length === 0) {
+    return;
+  }
+  return decorators.map((decorator) => {
+    const expression = decorator.expression;
+    if (ts2.isIdentifier(expression)) {
+      return { name: expression.text };
+    }
+    if (ts2.isCallExpression(expression)) {
+      const name = ts2.isIdentifier(expression.expression) ? expression.expression.text : expression.expression.getText();
+      const argumentsText = expression.arguments.map((arg) => arg.getText());
+      return { name, argumentsText };
+    }
+    if (ts2.isPropertyAccessExpression(expression)) {
+      return { name: expression.getText() };
+    }
+    return { name: expression.getText() };
+  });
+}
+function extractParameterDecorators(param) {
+  return extractDecorators(param);
+}
 
 // src/utils/parameter-utils.ts
 var BUILTIN_TYPE_SCHEMAS = {
@@ -2972,6 +3020,10 @@ function structureParameter(param, paramDecl, paramType, typeChecker, typeRefs,
   if (paramDecl.dotDotDotToken) {
     out.rest = true;
   }
+  const decorators = extractParameterDecorators(paramDecl);
+  if (decorators) {
+    out.decorators = decorators;
+  }
   return out;
 }
 
@@ -2980,6 +3032,7 @@ function parseJSDocBlock(commentText) {
   const result = {
     description: "",
     params: [],
+    throws: [],
     examples: [],
     tags: [],
     rawParamNames: []
@@ -3085,6 +3138,22 @@ function parseReturnContent(content) {
     description: processInlineLinks(remaining)
   };
 }
+function parseThrowsContent(content) {
+  const trimmed = content.trim();
+  let remaining = trimmed;
+  let type;
+  if (remaining.startsWith("{")) {
+    const typeEnd = findMatchingBrace(remaining, 0);
+    if (typeEnd > 0) {
+      type = remaining.slice(1, typeEnd).trim();
+      remaining = remaining.slice(typeEnd + 1).trim();
+    }
+  }
+  return {
+    type,
+    description: processInlineLinks(remaining)
+  };
+}
 function findMatchingBrace(text, startIndex) {
   if (text[startIndex] !== "{")
     return -1;
@@ -3141,14 +3210,35 @@ function processTagContent(result, tag, content) {
         result.rawParamNames.push(parsed.name);
         result.params.push(parsed);
       }
-      result.tags.push({ name: "param", text: trimmedContent });
+      result.tags.push({
+        name: "param",
+        text: trimmedContent,
+        paramName: parsed?.name,
+        typeAnnotation: parsed?.type
+      });
       break;
     }
     case "returns":
     case "return": {
       const parsed = parseReturnContent(trimmedContent);
       result.returns = parsed;
-      result.tags.push({ name: "returns", text: trimmedContent });
+      result.tags.push({
+        name: "returns",
+        text: trimmedContent,
+        typeAnnotation: parsed.type
+      });
+      break;
+    }
+    case "throws":
+    case "throw":
+    case "exception": {
+      const parsed = parseThrowsContent(trimmedContent);
+      result.throws.push(parsed);
+      result.tags.push({
+        name: "throws",
+        text: trimmedContent,
+        typeAnnotation: parsed.type
+      });
       break;
     }
     case "example": {
@@ -3156,26 +3246,70 @@ function processTagContent(result, tag, content) {
       if (example) {
         result.examples.push(example);
       }
+      const langMatch = trimmedContent.match(/^```(\w+)/);
+      result.tags.push({
+        name: "example",
+        text: example,
+        language: langMatch?.[1]
+      });
       break;
     }
     case "see": {
       const linkTargets = extractAllLinkTargets(trimmedContent);
       for (const target of linkTargets) {
-        result.tags.push({ name: "link", text: target });
-        result.tags.push({ name: "see", text: target });
+        result.tags.push({ name: "link", text: target, reference: target });
+        result.tags.push({ name: "see", text: target, reference: target });
       }
       if (linkTargets.length === 0) {
-        result.tags.push({ name: "see", text: trimmedContent });
+        result.tags.push({ name: "see", text: trimmedContent, reference: trimmedContent });
       }
       break;
     }
     case "link": {
       const target = extractLinkTarget(trimmedContent);
       if (target) {
-        result.tags.push({ name: "link", text: target });
+        result.tags.push({ name: "link", text: target, reference: target });
       }
       break;
     }
+    case "since": {
+      result.tags.push({ name: "since", text: trimmedContent, version: trimmedContent });
+      break;
+    }
+    case "deprecated": {
+      const versionMatch = trimmedContent.match(/^(\d+\.\d+(?:\.\d+)?)\s*(.*)?$/);
+      if (versionMatch) {
+        result.tags.push({
+          name: "deprecated",
+          text: trimmedContent,
+          version: versionMatch[1],
+          reason: versionMatch[2]?.trim() || undefined
+        });
+      } else {
+        result.tags.push({
+          name: "deprecated",
+          text: trimmedContent,
+          reason: trimmedContent || undefined
+        });
+      }
+      break;
+    }
+    case "type":
+    case "typedef": {
+      let typeAnnotation;
+      if (trimmedContent.startsWith("{")) {
+        const typeEnd = findMatchingBrace(trimmedContent, 0);
+        if (typeEnd > 0) {
+          typeAnnotation = trimmedContent.slice(1, typeEnd).trim();
+        }
+      }
+      result.tags.push({
+        name: tag,
+        text: trimmedContent,
+        typeAnnotation
+      });
+      break;
+    }
     case "inheritdoc": {
       result.tags.push({ name: "inheritDoc", text: trimmedContent });
       break;
@@ -3262,6 +3396,9 @@ function parseJSDocText(commentText) {
     result.returns = parsed.returns.description;
     result.returnsType = parsed.returns.type;
   }
+  if (parsed.throws.length > 0) {
+    result.throws = parsed.throws;
+  }
   return result;
 }
 function extractDestructuredParams(parsedDoc, paramName) {
@@ -3401,6 +3538,7 @@ function serializeClass(declaration, symbol, context) {
   const parsedDoc = parseJSDocComment(symbol, context.checker);
   const description = parsedDoc?.description ?? getJSDocComment(symbol, context.checker);
   const metadata = extractPresentationMetadata(parsedDoc);
+  const decorators = extractDecorators(declaration);
   const exportEntry = {
     id: symbol.getName(),
     name: symbol.getName(),
@@ -3414,7 +3552,8 @@ function serializeClass(declaration, symbol, context) {
     ...heritage.extends ? { extends: heritage.extends } : {},
     ...heritage.implements && heritage.implements.length > 0 ? { implements: heritage.implements } : {},
     tags: parsedDoc?.tags,
-    examples: parsedDoc?.examples
+    examples: parsedDoc?.examples,
+    decorators
   };
   const typeDefinition = {
     id: symbol.getName(),
@@ -3507,7 +3646,8 @@ function serializeClassMembers(declaration, checker, typeRefs, referencedTypes)
         schema,
         description: memberDoc?.description ?? (memberSymbol ? getJSDocComment(memberSymbol, checker) : undefined),
         flags: Object.keys(flags).length > 0 ? flags : undefined,
-        tags: memberDoc?.tags
+        tags: memberDoc?.tags,
+        decorators: extractDecorators(member)
       });
       continue;
     }
@@ -3515,10 +3655,12 @@ function serializeClassMembers(declaration, checker, typeRefs, referencedTypes)
       const memberName = member.name?.getText() ?? "method";
       const memberSymbol = member.name ? checker.getSymbolAtLocation(member.name) : undefined;
       const methodDoc = memberSymbol ? parseJSDocComment(memberSymbol, checker) : null;
-      const signature = checker.getSignatureFromDeclaration(member);
-      const signatures = signature ? [
-        serializeSignature(signature, checker, typeRefs, referencedTypes, methodDoc, memberSymbol)
-      ] : undefined;
+      const methodType = memberSymbol ? checker.getTypeOfSymbolAtLocation(memberSymbol, member) : checker.getTypeAtLocation(member);
+      const callSignatures = methodType.getCallSignatures();
+      const signatures = callSignatures.length > 0 ? callSignatures.map((sig, index) => ({
+        ...serializeSignature(sig, checker, typeRefs, referencedTypes, methodDoc, memberSymbol),
+        overloadIndex: callSignatures.length > 1 ? index : undefined
+      })) : undefined;
       members.push({
         id: memberName,
         name: memberName,
@@ -3527,15 +3669,20 @@ function serializeClassMembers(declaration, checker, typeRefs, referencedTypes)
         signatures,
         description: methodDoc?.description ?? (memberSymbol ? getJSDocComment(memberSymbol, checker) : undefined),
         flags: getMethodFlags(member),
-        tags: methodDoc?.tags
+        tags: methodDoc?.tags,
+        decorators: extractDecorators(member)
       });
       continue;
     }
     if (ts2.isConstructorDeclaration(member)) {
       const ctorSymbol = checker.getSymbolAtLocation(member);
       const ctorDoc = ctorSymbol ? parseJSDocComment(ctorSymbol, checker) : null;
-      const signature = checker.getSignatureFromDeclaration(member);
-      const signatures = signature ? [serializeSignature(signature, checker, typeRefs, referencedTypes, ctorDoc, ctorSymbol)] : undefined;
+      const classType = checker.getTypeAtLocation(declaration);
+      const constructSignatures = classType.getConstructSignatures();
+      const signatures = constructSignatures.length > 0 ? constructSignatures.map((sig, index) => ({
+        ...serializeSignature(sig, checker, typeRefs, referencedTypes, ctorDoc, ctorSymbol),
+        overloadIndex: constructSignatures.length > 1 ? index : undefined
+      })) : undefined;
       members.push({
         id: "constructor",
         name: "constructor",
@@ -3543,7 +3690,8 @@ function serializeClassMembers(declaration, checker, typeRefs, referencedTypes)
         visibility: getMemberVisibility(member.modifiers),
         signatures,
         description: ctorDoc?.description ?? (ctorSymbol ? getJSDocComment(ctorSymbol, checker) : undefined),
-        tags: ctorDoc?.tags
+        tags: ctorDoc?.tags,
+        decorators: extractDecorators(member)
       });
       continue;
     }
@@ -3576,7 +3724,8 @@ function serializeClassMembers(declaration, checker, typeRefs, referencedTypes)
         schema,
         description: memberDoc?.description ?? (memberSymbol ? getJSDocComment(memberSymbol, checker) : undefined),
         flags: Object.keys(flags).length > 0 ? flags : undefined,
-        tags: memberDoc?.tags
+        tags: memberDoc?.tags,
+        decorators: extractDecorators(primaryMember)
       });
     }
   }
@@ -3584,6 +3733,10 @@ function serializeClassMembers(declaration, checker, typeRefs, referencedTypes)
 }
 function serializeSignature(signature, checker, typeRefs, referencedTypes, doc, symbol) {
   const typeParameters = serializeTypeParameterDeclarations(signature.declaration?.typeParameters, checker, referencedTypes);
+  const throws = doc?.throws?.map((t) => ({
+    type: t.type,
+    description: t.description
+  }));
   return {
     parameters: signature.getParameters().map((param) => {
       const paramDecl = param.valueDeclaration;
@@ -3597,7 +3750,8 @@ function serializeSignature(signature, checker, typeRefs, referencedTypes, doc,
       description: doc?.returns || ""
     },
     description: doc?.description || (symbol ? getJSDocComment(symbol, checker) : undefined),
-    typeParameters
+    typeParameters,
+    throws: throws && throws.length > 0 ? throws : undefined
   };
 }
 function getMemberVisibility(modifiers) {
@@ -3677,7 +3831,7 @@ function serializeCallSignatures(signatures, symbol, context, parsedDoc) {
   const typeRefs = typeRegistry.getTypeRefs();
   const referencedTypes = typeRegistry.getReferencedTypes();
   const functionDoc = parsedDoc ?? (symbol ? parseJSDocComment(symbol, checker) : null);
-  return signatures.map((signature) => {
+  return signatures.map((signature, index) => {
     const parameters = signature.getParameters().map((param) => {
       const paramDecl = param.declarations?.find(ts2.isParameter);
       const location = symbol?.declarations?.[0] ?? signature.declaration ?? param.declarations?.[0] ?? param.valueDeclaration;
@@ -3715,6 +3869,10 @@ function serializeCallSignatures(signatures, symbol, context, parsedDoc) {
         ...isAsserts ? { asserts: true } : {}
       };
     }
+    const throws = functionDoc?.throws?.map((t) => ({
+      type: t.type,
+      description: t.description
+    }));
     return {
       parameters,
       returns: {
@@ -3724,7 +3882,9 @@ function serializeCallSignatures(signatures, symbol, context, parsedDoc) {
         ...typePredicateInfo ? { typePredicate: typePredicateInfo } : {}
       },
       description: functionDoc?.description || undefined,
-      typeParameters
+      typeParameters,
+      overloadIndex: signatures.length > 1 ? index : undefined,
+      throws: throws && throws.length > 0 ? throws : undefined
     };
   });
 }
@@ -3785,26 +3945,37 @@ function serializeInterfaceMembers(declaration, checker, typeRefs, referencedTyp
         continue;
       const memberSymbol = member.name ? checker.getSymbolAtLocation(member.name) : undefined;
       const methodDoc = memberSymbol ? parseJSDocComment(memberSymbol, checker) : null;
-      const signature = checker.getSignatureFromDeclaration(member);
-      if (signature) {
-        const parameters = signature.getParameters().map((param) => {
-          const paramDecl = param.declarations?.find(ts2.isParameter);
-          const paramType = paramDecl ? checker.getTypeAtLocation(paramDecl) : checker.getTypeOfSymbolAtLocation(param, member);
-          collectReferencedTypes(paramType, checker, referencedTypes);
-          if (paramDecl) {
-            const paramDoc = getParameterDocumentation(param, paramDecl, checker);
-            return structureParameter(param, paramDecl, paramType, checker, typeRefs, null, paramDoc, referencedTypes);
+      const methodType = memberSymbol ? checker.getTypeOfSymbolAtLocation(memberSymbol, member) : checker.getTypeAtLocation(member);
+      const callSignatures = methodType.getCallSignatures();
+      if (callSignatures.length > 0) {
+        const signatures = callSignatures.map((signature, index) => {
+          const parameters = signature.getParameters().map((param) => {
+            const paramDecl = param.declarations?.find(ts2.isParameter);
+            const paramType = paramDecl ? checker.getTypeAtLocation(paramDecl) : checker.getTypeOfSymbolAtLocation(param, member);
+            collectReferencedTypes(paramType, checker, referencedTypes);
+            if (paramDecl) {
+              const paramDoc = getParameterDocumentation(param, paramDecl, checker);
+              return structureParameter(param, paramDecl, paramType, checker, typeRefs, null, paramDoc, referencedTypes);
+            }
+            return {
+              name: param.getName(),
+              required: !(param.flags & ts2.SymbolFlags.Optional),
+              schema: formatTypeReference(paramType, checker, typeRefs, referencedTypes)
+            };
+          });
+          const returnType = signature.getReturnType();
+          if (returnType) {
+            collectReferencedTypes(returnType, checker, referencedTypes);
           }
           return {
-            name: param.getName(),
-            required: !(param.flags & ts2.SymbolFlags.Optional),
-            schema: formatTypeReference(paramType, checker, typeRefs, referencedTypes)
+            parameters,
+            returns: {
+              schema: returnType ? formatTypeReference(returnType, checker, typeRefs, referencedTypes) : { type: "void" }
+            },
+            description: methodDoc?.description,
+            overloadIndex: callSignatures.length > 1 ? index : undefined
           };
         });
-        const returnType = signature.getReturnType();
-        if (returnType) {
-          collectReferencedTypes(returnType, checker, referencedTypes);
-        }
         const flags = {};
         if (member.questionToken) {
           flags.optional = true;
@@ -3813,15 +3984,7 @@ function serializeInterfaceMembers(declaration, checker, typeRefs, referencedTyp
           id: methodName,
           name: methodName,
           kind: "method",
-          signatures: [
-            {
-              parameters,
-              returns: {
-                schema: returnType ? formatTypeReference(returnType, checker, typeRefs, referencedTypes) : { type: "void" }
-              },
-              description: methodDoc?.description
-            }
-          ],
+          signatures,
           description: methodDoc?.description ?? (memberSymbol ? getJSDocComment(memberSymbol, checker) : undefined),
           flags: Object.keys(flags).length > 0 ? flags : undefined,
           tags: methodDoc?.tags
@@ -4013,6 +4176,8 @@ function serializeNamespace(declaration, symbol, context) {
   const description = parsedDoc?.description ?? getJSDocComment(symbol, checker);
   const metadata = extractPresentationMetadata(parsedDoc);
   const members = extractNamespaceMembers(declaration, checker);
+  const isAugmentation = ts2.isStringLiteral(declaration.name);
+  const augmentedModule = isAugmentation ? declaration.name.text : undefined;
   return {
     id: symbol.getName(),
     name: symbol.getName(),
@@ -4023,7 +4188,9 @@ function serializeNamespace(declaration, symbol, context) {
     source: getSourceLocation(declaration),
     members: members.length > 0 ? members : undefined,
     tags: parsedDoc?.tags,
-    examples: parsedDoc?.examples
+    examples: parsedDoc?.examples,
+    isAugmentation: isAugmentation || undefined,
+    augmentedModule
   };
 }
 function extractNamespaceMembers(declaration, checker) {
@@ -4115,6 +4282,46 @@ function extractNamespaceMembers(declaration, checker) {
 }
 
 // src/analysis/serializers/type-aliases.ts
+function analyzeTypeAliasKind(typeNode) {
+  if (ts2.isConditionalTypeNode(typeNode)) {
+    return {
+      typeAliasKind: "conditional",
+      conditionalType: {
+        checkType: typeNode.checkType.getText(),
+        extendsType: typeNode.extendsType.getText(),
+        trueType: typeNode.trueType.getText(),
+        falseType: typeNode.falseType.getText()
+      }
+    };
+  }
+  if (ts2.isMappedTypeNode(typeNode)) {
+    const readonlyToken = typeNode.readonlyToken;
+    const questionToken = typeNode.questionToken;
+    return {
+      typeAliasKind: "mapped",
+      mappedType: {
+        typeParameter: typeNode.typeParameter.getText(),
+        nameType: typeNode.nameType?.getText(),
+        valueType: typeNode.type?.getText(),
+        readonly: readonlyToken ? readonlyToken.kind === ts2.SyntaxKind.MinusToken ? "-" : readonlyToken.kind === ts2.SyntaxKind.PlusToken ? "+" : true : undefined,
+        optional: questionToken ? questionToken.kind === ts2.SyntaxKind.MinusToken ? "-" : questionToken.kind === ts2.SyntaxKind.PlusToken ? "+" : true : undefined
+      }
+    };
+  }
+  if (ts2.isTemplateLiteralTypeNode(typeNode)) {
+    return { typeAliasKind: "template-literal" };
+  }
+  if (containsInferType(typeNode)) {
+    return { typeAliasKind: "infer" };
+  }
+  return { typeAliasKind: "alias" };
+}
+function containsInferType(node) {
+  if (ts2.isInferTypeNode(node)) {
+    return true;
+  }
+  return ts2.forEachChild(node, containsInferType) ?? false;
+}
 function serializeTypeAlias(declaration, symbol, context) {
   const { checker, typeRegistry } = context;
   const typeRefs = typeRegistry.getTypeRefs();
@@ -4123,6 +4330,7 @@ function serializeTypeAlias(declaration, symbol, context) {
   const description = parsedDoc?.description ?? getJSDocComment(symbol, checker);
   const metadata = extractPresentationMetadata(parsedDoc);
   const typeParameters = serializeTypeParameterDeclarations(declaration.typeParameters, checker, referencedTypes);
+  const typeAnalysis = analyzeTypeAliasKind(declaration.type);
   const exportEntry = {
     id: symbol.getName(),
     name: symbol.getName(),
@@ -4134,7 +4342,10 @@ function serializeTypeAlias(declaration, symbol, context) {
     source: getSourceLocation(declaration),
     typeParameters,
     tags: parsedDoc?.tags,
-    examples: parsedDoc?.examples
+    examples: parsedDoc?.examples,
+    typeAliasKind: typeAnalysis.typeAliasKind !== "alias" ? typeAnalysis.typeAliasKind : undefined,
+    conditionalType: typeAnalysis.conditionalType,
+    mappedType: typeAnalysis.mappedType
   };
   const aliasType = checker.getTypeAtLocation(declaration.type);
   const aliasName = symbol.getName();
@@ -4153,7 +4364,10 @@ function serializeTypeAlias(declaration, symbol, context) {
     kind: "type",
     description,
     source: getSourceLocation(declaration),
-    tags: parsedDoc?.tags
+    tags: parsedDoc?.tags,
+    typeAliasKind: typeAnalysis.typeAliasKind !== "alias" ? typeAnalysis.typeAliasKind : undefined,
+    conditionalType: typeAnalysis.conditionalType,
+    mappedType: typeAnalysis.mappedType
   };
   if (typeof aliasSchema === "string") {
     typeDefinition.type = aliasSchema;
@@ -4270,7 +4484,7 @@ function buildOpenPkgSpec(context, resolveExternalTypes) {
   const packageJson = fs2.existsSync(packageJsonPath) ? JSON.parse(fs2.readFileSync(packageJsonPath, "utf-8")) : {};
   const spec = {
     $schema: SCHEMA_URL,
-    openpkg: "0.2.0",
+    openpkg: SCHEMA_VERSION,
     meta: {
       name: packageJson.name || "unknown",
       version: packageJson.version || "1.0.0",
@@ -4666,6 +4880,48 @@ async function extractPackageSpec(entryFile, packageDir, content, options) {
   });
   return result.spec;
 }
+// src/filtering/merge.ts
+function unique(values) {
+  return Array.from(new Set(values));
+}
+function parseListFlag(value) {
+  if (!value) {
+    return;
+  }
+  const rawItems = Array.isArray(value) ? value : [value];
+  const normalized = rawItems.flatMap((item) => String(item).split(",")).map((item) => item.trim()).filter(Boolean);
+  return normalized.length > 0 ? unique(normalized) : undefined;
+}
+function mergeFilters(config, overrides) {
+  const configInclude = config?.include;
+  const configExclude = config?.exclude;
+  const overrideInclude = overrides.include;
+  const overrideExclude = overrides.exclude;
+  let include = configInclude;
+  let exclude = configExclude;
+  let source = include || exclude ? "config" : undefined;
+  const fromConfig = !!(configInclude || configExclude);
+  let fromOverride = false;
+  if (overrideInclude) {
+    include = include ? include.filter((item) => overrideInclude.includes(item)) : overrideInclude;
+    source = source ? "combined" : "override";
+    fromOverride = true;
+  }
+  if (overrideExclude) {
+    exclude = exclude ? unique([...exclude, ...overrideExclude]) : overrideExclude;
+    source = source ? "combined" : "override";
+    fromOverride = true;
+  }
+  include = include ? unique(include) : undefined;
+  exclude = exclude ? unique(exclude) : undefined;
+  return {
+    include,
+    exclude,
+    source,
+    fromConfig,
+    fromOverride
+  };
+}
 // src/fix/deterministic-fixes.ts
 var FIXABLE_DRIFT_TYPES = new Set([
   "param-mismatch",
@@ -7056,6 +7312,390 @@ async function runExamplesWithPackage(examples, options) {
     } catch {}
   }
 }
+// src/scan/summary.ts
+function extractSpecSummary(spec) {
+  const exports = spec.exports ?? [];
+  const undocumented = [];
+  const drift = [];
+  for (const exp of exports) {
+    const docs = exp.docs;
+    if (!docs)
+      continue;
+    const hasMissing = (docs.missing?.length ?? 0) > 0;
+    const isPartial = (docs.coverageScore ?? 0) < 100;
+    if (hasMissing || isPartial) {
+      undocumented.push(exp.name);
+    }
+    for (const d of docs.drift ?? []) {
+      drift.push({
+        export: exp.name,
+        type: d.type,
+        issue: d.issue,
+        suggestion: d.suggestion
+      });
+    }
+  }
+  return {
+    coverage: spec.docs?.coverageScore ?? 0,
+    exportCount: exports.length,
+    typeCount: spec.types?.length ?? 0,
+    driftCount: drift.length,
+    undocumented,
+    drift
+  };
+}
+// src/install/index.ts
+var DEFAULT_FALLBACK_ORDER = ["bun", "npm"];
+async function installDependencies(fs8, cwd, runCommand2, options = {}) {
+  const {
+    timeout = 180000,
+    fallbackOrder = DEFAULT_FALLBACK_ORDER,
+    onProgress
+  } = options;
+  const errors = [];
+  onProgress?.({ stage: "installing", message: "Detecting package manager..." });
+  const pmInfo = await detectPackageManager(fs8);
+  if (pmInfo.lockfile) {
+    onProgress?.({
+      stage: "installing",
+      message: `Installing with ${pmInfo.name}...`,
+      progress: 25
+    });
+    const installCmd = getInstallCommand(pmInfo);
+    const result = await runCommand2(installCmd[0], installCmd.slice(1), { cwd, timeout });
+    if (result.exitCode === 0) {
+      onProgress?.({ stage: "installing", message: "Dependencies installed", progress: 100 });
+      return {
+        success: true,
+        packageManager: pmInfo.name
+      };
+    }
+    const errorMsg = result.stderr.slice(0, 150) || `Exit code ${result.exitCode}`;
+    errors.push(`[${installCmd.join(" ")}] ${errorMsg}`);
+    if (result.stderr.includes("workspace:") || result.stderr.includes("EUNSUPPORTEDPROTOCOL")) {
+      onProgress?.({
+        stage: "installing",
+        message: "Workspace protocol detected, trying bun...",
+        progress: 35
+      });
+    }
+  }
+  for (const fallbackPm of fallbackOrder) {
+    if (pmInfo.lockfile && fallbackPm === pmInfo.name)
+      continue;
+    onProgress?.({
+      stage: "installing",
+      message: `Trying ${fallbackPm} fallback...`,
+      progress: 50
+    });
+    const fallbackCmd = getFallbackInstallCommand(fallbackPm);
+    const result = await runCommand2(fallbackCmd[0], fallbackCmd.slice(1), { cwd, timeout });
+    if (result.exitCode === 0) {
+      onProgress?.({ stage: "installing", message: "Dependencies installed", progress: 100 });
+      return {
+        success: true,
+        packageManager: fallbackPm,
+        fallbackUsed: fallbackPm
+      };
+    }
+    const errorMsg = result.stderr.slice(0, 150) || `Exit code ${result.exitCode}`;
+    errors.push(`[${fallbackCmd.join(" ")}] ${errorMsg}`);
+  }
+  onProgress?.({
+    stage: "installing",
+    message: "Could not install dependencies",
+    progress: 100
+  });
+  return {
+    success: false,
+    packageManager: pmInfo.name,
+    error: "All installation attempts failed",
+    errors
+  };
+}
+function getFallbackInstallCommand(pm) {
+  switch (pm) {
+    case "npm":
+      return ["npm", "install", "--legacy-peer-deps", "--ignore-scripts"];
+    case "bun":
+      return ["bun", "install"];
+    case "yarn":
+      return ["yarn", "install"];
+    case "pnpm":
+      return ["pnpm", "install"];
+    default:
+      return ["npm", "install"];
+  }
+}
+function createNodeCommandRunner() {
+  return async (cmd, args, options) => {
+    const { execSync } = await import("node:child_process");
+    const fullCmd = [cmd, ...args].join(" ");
+    try {
+      const stdout = execSync(fullCmd, {
+        cwd: options.cwd,
+        stdio: "pipe",
+        timeout: options.timeout ?? 180000
+      });
+      return {
+        exitCode: 0,
+        stdout: stdout?.toString() ?? "",
+        stderr: ""
+      };
+    } catch (error) {
+      const err = error;
+      return {
+        exitCode: err.status ?? 1,
+        stdout: err.stdout?.toString() ?? "",
+        stderr: err.stderr?.toString() ?? err.message ?? "Unknown error"
+      };
+    }
+  };
+}
+
+// src/github/index.ts
+function parseGitHubUrl(input, defaultRef = "main") {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    throw new Error("GitHub URL cannot be empty");
+  }
+  let normalized = trimmed.replace(/^https?:\/\//, "").replace(/^git@github\.com:/, "").replace(/\.git$/, "");
+  normalized = normalized.replace(/^github\.com\//, "");
+  const parts = normalized.split("/").filter(Boolean);
+  if (parts.length < 2) {
+    throw new Error(`Invalid GitHub URL format: "${input}". Expected owner/repo or https://github.com/owner/repo`);
+  }
+  const owner = parts[0];
+  const repo = parts[1];
+  let ref = defaultRef;
+  if (parts.length >= 4 && (parts[2] === "tree" || parts[2] === "blob")) {
+    ref = parts.slice(3).join("/");
+  }
+  if (!owner || !repo) {
+    throw new Error(`Could not parse owner/repo from: "${input}"`);
+  }
+  return { owner, repo, ref };
+}
+function buildCloneUrl(parsed) {
+  return `https://github.com/${parsed.owner}/${parsed.repo}.git`;
+}
+function buildDisplayUrl(parsed) {
+  return `github.com/${parsed.owner}/${parsed.repo}`;
+}
+function buildRawUrl(parsed, filePath) {
+  return `https://raw.githubusercontent.com/${parsed.owner}/${parsed.repo}/${parsed.ref}/${filePath}`;
+}
+async function fetchSpecFromGitHub(parsed) {
+  const urls = [
+    buildRawUrl(parsed, "openpkg.json"),
+    `https://raw.githubusercontent.com/${parsed.owner}/${parsed.repo}/master/openpkg.json`
+  ];
+  for (const url of urls) {
+    try {
+      const response = await fetch(url);
+      if (response.ok) {
+        return await response.json();
+      }
+    } catch {}
+  }
+  return null;
+}
+async function fetchSpec(owner, repo, branch = "main") {
+  return fetchSpecFromGitHub({ owner, repo, ref: branch });
+}
+
+// src/scan/orchestrator.ts
+class ScanOrchestrator {
+  fs;
+  options;
+  constructor(fs8, options = {}) {
+    this.fs = fs8;
+    this.options = options;
+  }
+  emit(event) {
+    this.options.onProgress?.(event);
+  }
+  async detectPackage(packageName) {
+    this.emit({ stage: "detecting", message: "Detecting project structure...", progress: 10 });
+    const mono = await detectMonorepo(this.fs);
+    if (mono.isMonorepo) {
+      if (!packageName) {
+        const publicPackages = mono.packages.filter((p) => !p.private);
+        throw new MonorepoRequiresPackageError(publicPackages.map((p) => p.name));
+      }
+      const pkg = findPackageByName(mono.packages, packageName);
+      if (!pkg) {
+        throw new Error(`Package "${packageName}" not found. Available: ${mono.packages.map((p) => p.name).join(", ")}`);
+      }
+      this.emit({ stage: "detecting", message: `Found package: ${pkg.name}`, progress: 15 });
+      return { targetPath: pkg.path, resolvedPackage: pkg.name };
+    }
+    return { targetPath: "." };
+  }
+  async detectEntry(targetPath) {
+    this.emit({ stage: "detecting", message: "Detecting entry point...", progress: 18 });
+    const entry = await detectEntryPoint(this.fs, targetPath);
+    const entryFile = targetPath === "." ? entry.path : `${targetPath}/${entry.path}`;
+    this.emit({
+      stage: "detecting",
+      message: `Entry point: ${entry.path} (from ${entry.source})`,
+      progress: 20
+    });
+    return entryFile;
+  }
+  async install(workDir) {
+    if (!this.options.commandRunner) {
+      return {
+        success: false,
+        packageManager: "npm",
+        error: "No command runner provided"
+      };
+    }
+    this.emit({ stage: "installing", message: "Installing dependencies...", progress: 25 });
+    const result = await installDependencies(this.fs, workDir, this.options.commandRunner, {
+      onProgress: this.options.onProgress
+    });
+    if (result.success) {
+      this.emit({ stage: "installing", message: "Dependencies installed", progress: 45 });
+    } else {
+      this.emit({
+        stage: "installing",
+        message: "Install failed (continuing with limited analysis)",
+        progress: 45
+      });
+    }
+    return result;
+  }
+  async build(workDir, targetPath) {
+    if (!this.options.commandRunner)
+      return;
+    const buildInfo = await detectBuildInfo(this.fs, targetPath);
+    const buildScript = getPrimaryBuildScript(buildInfo);
+    if (!buildScript)
+      return;
+    this.emit({ stage: "building", message: "Running build...", progress: 50 });
+    const result = await this.options.commandRunner("npm", ["run", buildScript], {
+      cwd: workDir,
+      timeout: 300000
+    });
+    const buildMessage = result.exitCode === 0 ? "Build complete" : "Build failed (continuing)";
+    this.emit({ stage: "building", message: buildMessage, progress: 60 });
+  }
+  async analyze(entryFile) {
+    this.emit({ stage: "analyzing", message: "Analyzing documentation...", progress: 65 });
+    const doccov = new DocCov({ resolveExternalTypes: !this.options.skipResolve });
+    const result = await doccov.analyzeFileWithDiagnostics(entryFile);
+    this.emit({ stage: "analyzing", message: "Analysis complete", progress: 90 });
+    return result.spec;
+  }
+  async scan(options) {
+    const parsed = parseGitHubUrl(options.url, options.ref ?? "main");
+    this.emit({
+      stage: "detecting",
+      message: `Scanning ${parsed.owner}/${parsed.repo}...`,
+      progress: 5
+    });
+    const { targetPath, resolvedPackage } = await this.detectPackage(options.package);
+    const entryFile = await this.detectEntry(targetPath);
+    if (!options.skipInstall && this.options.commandRunner) {
+      await this.install(".");
+      await this.build(".", targetPath);
+    }
+    const spec = await this.analyze(entryFile);
+    this.emit({ stage: "complete", message: "Extracting results...", progress: 95 });
+    const summary = extractSpecSummary(spec);
+    this.emit({ stage: "complete", message: "Scan complete", progress: 100 });
+    return {
+      owner: parsed.owner,
+      repo: parsed.repo,
+      ref: parsed.ref,
+      packageName: resolvedPackage ?? options.package,
+      coverage: summary.coverage,
+      exportCount: summary.exportCount,
+      typeCount: summary.typeCount,
+      driftCount: summary.driftCount,
+      undocumented: summary.undocumented,
+      drift: summary.drift
+    };
+  }
+}
+
+class MonorepoRequiresPackageError extends Error {
+  availablePackages;
+  constructor(availablePackages) {
+    super(`Monorepo detected with ${availablePackages.length} packages. ` + `Specify target with --package. Available: ${availablePackages.join(", ")}`);
+    this.name = "MonorepoRequiresPackageError";
+    this.availablePackages = availablePackages;
+  }
+}
+// src/resolve/index.ts
+import * as path9 from "node:path";
+async function resolveTarget(fs8, options) {
+  let targetDir = options.cwd;
+  let packageInfo;
+  if (options.package) {
+    const mono = await detectMonorepo(fs8);
+    if (!mono.isMonorepo) {
+      throw new Error("Not a monorepo. Remove --package flag for single-package repos.");
+    }
+    const pkg = findPackageByName(mono.packages, options.package);
+    if (!pkg) {
+      const available = mono.packages.map((p) => p.name).join(", ");
+      throw new Error(`Package "${options.package}" not found. Available: ${available}`);
+    }
+    targetDir = path9.join(options.cwd, pkg.path);
+    packageInfo = pkg;
+  }
+  let entryFile;
+  let entryPointInfo;
+  if (!options.entry) {
+    entryPointInfo = await detectEntryPoint(fs8, getRelativePath(options.cwd, targetDir));
+    entryFile = path9.join(targetDir, entryPointInfo.path);
+  } else {
+    const explicitPath = path9.resolve(targetDir, options.entry);
+    const isDirectory = await isDir(fs8, getRelativePath(options.cwd, explicitPath));
+    if (isDirectory) {
+      targetDir = explicitPath;
+      entryPointInfo = await detectEntryPoint(fs8, getRelativePath(options.cwd, explicitPath));
+      entryFile = path9.join(explicitPath, entryPointInfo.path);
+    } else {
+      entryFile = explicitPath;
+      entryPointInfo = {
+        path: options.entry,
+        source: "explicit",
+        isDeclarationOnly: options.entry.endsWith(".d.ts")
+      };
+    }
+  }
+  return {
+    targetDir,
+    entryFile,
+    packageInfo,
+    entryPointInfo
+  };
+}
+function getRelativePath(base, target) {
+  if (base === target)
+    return ".";
+  const rel = path9.relative(base, target);
+  return rel || ".";
+}
+async function isDir(fs8, relativePath) {
+  const hasPackageJson = await fs8.exists(path9.join(relativePath, "package.json"));
+  if (hasPackageJson)
+    return true;
+  const commonEntryFiles = ["index.ts", "index.tsx", "src/index.ts", "main.ts"];
+  for (const entry of commonEntryFiles) {
+    if (await fs8.exists(path9.join(relativePath, entry))) {
+      return true;
+    }
+  }
+  return !path9.extname(relativePath);
+}
+// src/config/types.ts
+function defineConfig(config) {
+  return config;
+}
 export {
   typecheckExamples,
   typecheckExample,
@@ -7064,20 +7704,25 @@ export {
   runExamplesWithPackage,
   runExamples,
   runExample,
+  resolveTarget,
   requireExample,
   requireDescription,
   readPackageJson,
   parseMarkdownFiles,
   parseMarkdownFile,
+  parseListFlag,
   parseJSDocToPatch,
+  parseGitHubUrl,
   parseAssertions,
   noEmptyReturns,
   mergeFixes,
+  mergeFilters,
   mergeConfig,
   lintExports,
   lintExport,
   isFixableDrift,
   isExecutableLang,
+  installDependencies,
   hasNonAssertionComments,
   hasDocsImpact,
   hasDocsForExport,
@@ -7097,6 +7742,9 @@ export {
   findJSDocLocation,
   findExportReferences,
   findDeprecatedReferences,
+  fetchSpecFromGitHub,
+  fetchSpec,
+  extractSpecSummary,
   extractPackageSpec,
   extractImports,
   extractFunctionCalls,
@@ -7107,9 +7755,14 @@ export {
   detectExampleAssertionFailures,
   detectEntryPoint,
   detectBuildInfo,
+  defineConfig,
   createSourceFile,
+  createNodeCommandRunner,
   consistentParamStyle,
   categorizeDrifts,
+  buildRawUrl,
+  buildDisplayUrl,
+  buildCloneUrl,
   blockReferencesExport,
   applyPatchToJSDoc,
   applyEdits,
@@ -7118,8 +7771,10 @@ export {
   analyzeDocsImpact,
   analyze,
   allRules,
+  ScanOrchestrator,
   SandboxFileSystem,
   OpenPkg,
   NodeFileSystem,
+  MonorepoRequiresPackageError,
   DocCov
 };