@doccov/sdk 0.12.0 → 0.15.0

package/dist/index.js

@@ -3501,7 +3501,6 @@ function normalizeDocCovOptions(options = {}) {
     cwd: options.cwd ?? process.cwd()
   };
 }
-var normalizeOpenPkgOptions = normalizeDocCovOptions;
 
 // src/analysis/program.ts
 import * as path7 from "node:path";
@@ -3559,7 +3558,7 @@ function createAnalysisContext({
   options
 }) {
   const baseDir = packageDir ?? path8.dirname(entryFile);
-  const normalizedOptions = normalizeOpenPkgOptions(options);
+  const normalizedOptions = normalizeDocCovOptions(options);
   const programResult = createProgram({ entryFile, baseDir, content });
   if (!programResult.sourceFile) {
     throw new Error(`Could not load ${entryFile}`);
@@ -3611,39 +3610,7 @@ function extractParameterDecorators(param) {
   return extractDecorators(param);
 }
 
-// src/utils/parameter-utils.ts
-var MAX_TYPE_DEPTH = DEFAULT_MAX_TYPE_DEPTH;
-function safeTypeToString(typeChecker, type) {
-  try {
-    return typeChecker.typeToString(type);
-  } catch {
-    return "unknown";
-  }
-}
-var BUILTIN_TYPE_SCHEMAS = {
-  Date: { type: "string", format: "date-time" },
-  RegExp: { type: "object", description: "RegExp" },
-  Error: { type: "object" },
-  Promise: { type: "object" },
-  Map: { type: "object" },
-  Set: { type: "object" },
-  WeakMap: { type: "object" },
-  WeakSet: { type: "object" },
-  Function: { type: "object" },
-  ArrayBuffer: { type: "string", format: "binary" },
-  ArrayBufferLike: { type: "string", format: "binary" },
-  DataView: { type: "string", format: "binary" },
-  Uint8Array: { type: "string", format: "byte" },
-  Uint16Array: { type: "string", format: "byte" },
-  Uint32Array: { type: "string", format: "byte" },
-  Int8Array: { type: "string", format: "byte" },
-  Int16Array: { type: "string", format: "byte" },
-  Int32Array: { type: "string", format: "byte" },
-  Float32Array: { type: "string", format: "byte" },
-  Float64Array: { type: "string", format: "byte" },
-  BigInt64Array: { type: "string", format: "byte" },
-  BigUint64Array: { type: "string", format: "byte" }
-};
+// src/utils/typebox-handler.ts
 var TYPEBOX_PRIMITIVE_MAP = {
   TString: { type: "string" },
   TNumber: { type: "number" },
@@ -3677,7 +3644,31 @@ function unwrapTypeBoxOptional(type) {
   const hadMarker = filtered.length < intersectionType.types.length;
   return { innerTypes: filtered, isOptional: hadMarker };
 }
-function formatTypeBoxSchema(type, typeChecker, typeRefs, referencedTypes, visited, depth = 0, maxDepth = MAX_TYPE_DEPTH, typeIds) {
+function getPropertyType(prop, parentType, typeChecker) {
+  if (prop.valueDeclaration) {
+    return typeChecker.getTypeOfSymbolAtLocation(prop, prop.valueDeclaration);
+  }
+  const propType = typeChecker.getTypeOfPropertyOfType(parentType, prop.getName());
+  if (propType) {
+    return propType;
+  }
+  const decl = prop.declarations?.[0];
+  if (decl) {
+    return typeChecker.getTypeOfSymbolAtLocation(prop, decl);
+  }
+  return typeChecker.getAnyType();
+}
+var _formatTypeReference = null;
+function setFormatTypeReference(fn) {
+  _formatTypeReference = fn;
+}
+function formatTypeReferenceInternal(type, typeChecker, typeRefs, referencedTypes, visited, depth, maxDepth, typeIds) {
+  if (_formatTypeReference) {
+    return _formatTypeReference(type, typeChecker, typeRefs, referencedTypes, visited, depth, maxDepth, typeIds);
+  }
+  return { type: "object" };
+}
+function formatTypeBoxSchema(type, typeChecker, typeRefs, referencedTypes, visited, depth = 0, maxDepth = DEFAULT_MAX_TYPE_DEPTH, typeIds) {
   if (depth > maxDepth) {
     return { type: "unknown" };
   }
@@ -3716,7 +3707,7 @@ function formatTypeBoxSchema(type, typeChecker, typeRefs, referencedTypes, visit
           const nested = formatTypeBoxSchema(propType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds);
           properties[propName] = nested ?? { type: "object" };
         } else {
-          properties[propName] = formatTypeReference(propType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds);
+          properties[propName] = formatTypeReferenceInternal(propType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds);
         }
         const { isOptional } = unwrapTypeBoxOptional(propType);
         if (propSymbolName !== "TOptional" && !isOptional) {
@@ -3744,7 +3735,7 @@ function formatTypeBoxSchema(type, typeChecker, typeRefs, referencedTypes, visit
           type: "object"
         };
       } else {
-        items = formatTypeReference(itemType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds);
+        items = formatTypeReferenceInternal(itemType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds);
       }
       return { type: "array", items };
     }
@@ -3765,7 +3756,7 @@ function formatTypeBoxSchema(type, typeChecker, typeRefs, referencedTypes, visit
               type: "object"
             });
           } else {
-            members.push(formatTypeReference(memberType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds));
+            members.push(formatTypeReferenceInternal(memberType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds));
           }
         }
       } else if (tupleType.typeArguments) {
@@ -3779,7 +3770,7 @@ function formatTypeBoxSchema(type, typeChecker, typeRefs, referencedTypes, visit
               type: "object"
             });
           } else {
-            members.push(formatTypeReference(memberType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds));
+            members.push(formatTypeReferenceInternal(memberType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds));
           }
         }
       }
@@ -3802,7 +3793,7 @@ function formatTypeBoxSchema(type, typeChecker, typeRefs, referencedTypes, visit
               type: "object"
             });
           } else {
-            members.push(formatTypeReference(memberType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds));
+            members.push(formatTypeReferenceInternal(memberType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds));
           }
         }
       }
@@ -3822,7 +3813,7 @@ function formatTypeBoxSchema(type, typeChecker, typeRefs, referencedTypes, visit
           type: "object"
         };
       }
-      return formatTypeReference(innerType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds);
+      return formatTypeReferenceInternal(innerType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds);
     }
     case "TLiteral": {
       if (!typeArgs || typeArgs.length === 0) {
@@ -3852,7 +3843,7 @@ function formatTypeBoxSchema(type, typeChecker, typeRefs, referencedTypes, visit
       } else if (valueSymbolName && isTypeBoxSchemaType(valueSymbolName)) {
         additionalProperties = formatTypeBoxSchema(valueType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds) ?? true;
       } else {
-        additionalProperties = formatTypeReference(valueType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds);
+        additionalProperties = formatTypeReferenceInternal(valueType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds);
       }
       return { type: "object", additionalProperties };
     }
@@ -3872,6 +3863,32 @@ function formatTypeBoxSchema(type, typeChecker, typeRefs, referencedTypes, visit
       return null;
   }
 }
+
+// src/utils/schema-builder.ts
+var BUILTIN_TYPE_SCHEMAS = {
+  Date: { type: "string", format: "date-time" },
+  RegExp: { type: "object", description: "RegExp" },
+  Error: { type: "object" },
+  Promise: { type: "object" },
+  Map: { type: "object" },
+  Set: { type: "object" },
+  WeakMap: { type: "object" },
+  WeakSet: { type: "object" },
+  Function: { type: "object" },
+  ArrayBuffer: { type: "string", format: "binary" },
+  ArrayBufferLike: { type: "string", format: "binary" },
+  DataView: { type: "string", format: "binary" },
+  Uint8Array: { type: "string", format: "byte" },
+  Uint16Array: { type: "string", format: "byte" },
+  Uint32Array: { type: "string", format: "byte" },
+  Int8Array: { type: "string", format: "byte" },
+  Int16Array: { type: "string", format: "byte" },
+  Int32Array: { type: "string", format: "byte" },
+  Float32Array: { type: "string", format: "byte" },
+  Float64Array: { type: "string", format: "byte" },
+  BigInt64Array: { type: "string", format: "byte" },
+  BigUint64Array: { type: "string", format: "byte" }
+};
 function isObjectLiteralType(type) {
   if (!(type.getFlags() & ts2.TypeFlags.Object)) {
     return false;
@@ -3894,20 +3911,6 @@ function withDescription(schema, description) {
     description
   };
 }
-function getPropertyType(prop, parentType, typeChecker) {
-  if (prop.valueDeclaration) {
-    return typeChecker.getTypeOfSymbolAtLocation(prop, prop.valueDeclaration);
-  }
-  const propType = typeChecker.getTypeOfPropertyOfType(parentType, prop.getName());
-  if (propType) {
-    return propType;
-  }
-  const decl = prop.declarations?.[0];
-  if (decl) {
-    return typeChecker.getTypeOfSymbolAtLocation(prop, decl);
-  }
-  return typeChecker.getAnyType();
-}
 function propertiesToSchema(properties, description) {
   const schema = {
     type: "object",
@@ -3944,6 +3947,10 @@ function propertiesToSchema(properties, description) {
   }
   return schema;
 }
+var _formatTypeReference2 = null;
+function setSchemaBuilderFormatTypeReference(fn) {
+  _formatTypeReference2 = fn;
+}
 function buildSchemaFromTypeNode(node, typeChecker, typeRefs, referencedTypes, functionDoc, parentParamName) {
   if (ts2.isParenthesizedTypeNode(node)) {
     return buildSchemaFromTypeNode(node.type, typeChecker, typeRefs, referencedTypes, functionDoc ?? null, parentParamName);
@@ -3973,7 +3980,7 @@ function buildSchemaFromTypeNode(node, typeChecker, typeRefs, referencedTypes, f
       let schema2 = "any";
       if (member.type) {
         const memberType = typeChecker.getTypeFromTypeNode(member.type);
-        const formatted = formatTypeReference(memberType, typeChecker, typeRefs, referencedTypes);
+        const formatted = _formatTypeReference2 ? _formatTypeReference2(memberType, typeChecker, typeRefs, referencedTypes) : { type: "any" };
         if (typeof formatted === "string") {
           if (formatted === "any") {
             schema2 = buildSchemaFromTypeNode(member.type, typeChecker, typeRefs, referencedTypes, functionDoc, parentParamName);
@@ -4154,7 +4161,16 @@ function deduplicateSchemas(schemas) {
   }
   return result;
 }
-function formatTypeReference(type, typeChecker, typeRefs, referencedTypes, visitedAliases, depth = 0, maxDepth = MAX_TYPE_DEPTH, visitedTypeIds) {
+
+// src/utils/type-formatter.ts
+function safeTypeToString(typeChecker, type) {
+  try {
+    return typeChecker.typeToString(type);
+  } catch {
+    return "unknown";
+  }
+}
+function formatTypeReference(type, typeChecker, typeRefs, referencedTypes, visitedAliases, depth = 0, maxDepth = DEFAULT_MAX_TYPE_DEPTH, visitedTypeIds) {
   if (depth > maxDepth) {
     return { type: "unknown" };
   }
@@ -4351,6 +4367,9 @@ function formatTypeReference(type, typeChecker, typeRefs, referencedTypes, visit
     }
   }
 }
+setFormatTypeReference(formatTypeReference);
+setSchemaBuilderFormatTypeReference(formatTypeReference);
+// src/utils/parameter-utils.ts
 function structureParameter(param, paramDecl, paramType, typeChecker, typeRefs, functionDoc, paramDoc, referencedTypes) {
   const paramName = param.getName();
   const isDestructured = paramName === "__0" || ts2.isObjectBindingPattern(paramDecl.name) || ts2.isArrayBindingPattern(paramDecl.name);
@@ -6147,10 +6166,30 @@ class TypeRegistry {
 }
 
 // src/analysis/spec-builder.ts
-function buildOpenPkgSpec(context, resolveExternalTypes) {
-  const { baseDir, checker: typeChecker, sourceFile, program } = context;
+function createDefaultGenerationInfo(entryFile) {
+  return {
+    timestamp: new Date().toISOString(),
+    generator: {
+      name: "@doccov/sdk",
+      version: "0.0.0"
+    },
+    analysis: {
+      entryPoint: entryFile,
+      entryPointSource: "explicit",
+      isDeclarationOnly: entryFile.endsWith(".d.ts"),
+      resolvedExternalTypes: false
+    },
+    environment: {
+      hasNodeModules: false
+    },
+    issues: []
+  };
+}
+function buildOpenPkgSpec(context, resolveExternalTypes, generation) {
+  const { baseDir, checker: typeChecker, sourceFile, program, entryFile } = context;
   const packageJsonPath = path9.join(baseDir, "package.json");
   const packageJson = fs8.existsSync(packageJsonPath) ? JSON.parse(fs8.readFileSync(packageJsonPath, "utf-8")) : {};
+  const generationInfo = generation ?? createDefaultGenerationInfo(path9.relative(baseDir, entryFile));
   const spec = {
     $schema: SCHEMA_URL,
     openpkg: SCHEMA_VERSION,
@@ -6163,7 +6202,8 @@ function buildOpenPkgSpec(context, resolveExternalTypes) {
       ecosystem: "js/ts"
     },
     exports: [],
-    types: []
+    types: [],
+    generation: generationInfo
   };
   const typeRegistry = new TypeRegistry;
   const serializerContext = {
@@ -6480,7 +6520,7 @@ function hasExternalImports(sourceFile) {
   });
   return found;
 }
-function runAnalysis(input) {
+function runAnalysis(input, generationInput) {
   const context = createAnalysisContext(input);
   const { baseDir, options, program } = context;
   const packageJsonPath = findNearestPackageJson(baseDir);
@@ -6493,30 +6533,65 @@ function runAnalysis(input) {
 `);
     return !/allowJs/i.test(msg);
   });
-  const spec = buildOpenPkgSpec(context, resolveExternalTypes);
   const specDiagnostics = [];
+  const generationIssues = [];
   if (!hasNodeModules && hasExternalImports(context.sourceFile)) {
-    specDiagnostics.push({
+    const issue = {
+      code: "NO_NODE_MODULES",
       message: "External imports detected but node_modules not found.",
       severity: "info",
       suggestion: "Run npm install or bun install for complete type resolution."
-    });
-  }
+    };
+    specDiagnostics.push(issue);
+    generationIssues.push(issue);
+  }
+  const generation = generationInput ? {
+    timestamp: new Date().toISOString(),
+    generator: {
+      name: generationInput.generatorName,
+      version: generationInput.generatorVersion
+    },
+    analysis: {
+      entryPoint: generationInput.entryPoint,
+      entryPointSource: generationInput.entryPointSource,
+      isDeclarationOnly: generationInput.isDeclarationOnly ?? false,
+      resolvedExternalTypes: resolveExternalTypes,
+      maxTypeDepth: options.maxDepth
+    },
+    environment: {
+      packageManager: generationInput.packageManager,
+      hasNodeModules,
+      isMonorepo: generationInput.isMonorepo,
+      targetPackage: generationInput.targetPackage
+    },
+    issues: generationIssues
+  } : undefined;
+  const spec = buildOpenPkgSpec(context, resolveExternalTypes, generation);
   const danglingRefs = collectDanglingRefs(spec);
   for (const ref of danglingRefs) {
-    specDiagnostics.push({
+    const issue = {
+      code: "DANGLING_REF",
       message: `Type '${ref}' is referenced but not defined in types[].`,
       severity: "warning",
       suggestion: hasNodeModules ? "The type may be from an external package. Check import paths." : "Run npm/bun install to resolve external types."
-    });
+    };
+    specDiagnostics.push(issue);
+    if (generation) {
+      generation.issues.push(issue);
+    }
   }
   const externalTypes = collectExternalTypes(spec);
   if (externalTypes.length > 0) {
-    specDiagnostics.push({
+    const issue = {
+      code: "EXTERNAL_TYPE_STUBS",
       message: `${externalTypes.length} external type(s) could not be fully resolved: ${externalTypes.slice(0, 5).join(", ")}${externalTypes.length > 5 ? "..." : ""}`,
       severity: "warning",
       suggestion: hasNodeModules ? "Types are from external packages. Full resolution requires type declarations." : "Run npm/bun install to resolve external type definitions."
-    });
+    };
+    specDiagnostics.push(issue);
+    if (generation) {
+      generation.issues.push(issue);
+    }
   }
   const sourceFiles = program.getSourceFiles().filter((sf) => !sf.isDeclarationFile && sf.fileName.startsWith(baseDir)).map((sf) => sf.fileName);
   return {
@@ -8176,7 +8251,7 @@ class DocCov {
       packageDir,
       content: code,
       options: this.options
-    });
+    }, analyzeOptions.generationInput);
     const filterOutcome = this.applySpecFilters(analysis.spec, analyzeOptions.filters);
     return {
       spec: filterOutcome.spec,
@@ -8211,7 +8286,7 @@ class DocCov {
       packageDir,
       content,
       options: this.options
-    });
+    }, analyzeOptions.generationInput);
     const filterOutcome = this.applySpecFilters(analysis.spec, analyzeOptions.filters);
     const metadata = this.normalizeMetadata(analysis.metadata);
     const result = {
@@ -8374,7 +8449,6 @@ async function analyze(code, options = {}) {
 async function analyzeFile(filePath, options = {}) {
   return new DocCov().analyzeFile(filePath, options);
 }
-var OpenPkg = DocCov;
 function resolvePackageDir(entryFile) {
   const fallbackDir = path11.dirname(entryFile);
   let currentDir = fallbackDir;
@@ -8486,130 +8560,199 @@ function extractSpecSummary(spec) {
     drift
   };
 }
-
-// src/scan/orchestrator.ts
-class ScanOrchestrator {
-  fs;
-  options;
-  constructor(fs11, options = {}) {
-    this.fs = fs11;
-    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;
+// src/scan/github-context.ts
+function parseGitHubUrl2(url) {
+  try {
+    const { owner, repo } = parseGitHubUrl(url);
+    return { owner, repo };
+  } catch {
+    return null;
   }
-  async install(workDir) {
-    if (!this.options.commandRunner) {
-      return {
-        success: false,
-        packageManager: "npm",
-        error: "No command runner provided"
-      };
+}
+async function fetchRawFile(owner, repo, ref, path13) {
+  const url = `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${path13}`;
+  try {
+    const response = await fetch(url);
+    if (response.ok) {
+      return await response.text();
     }
-    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 null;
+  } catch {
+    return null;
+  }
+}
+async function fetchRepoMetadata(owner, repo) {
+  const url = `https://api.github.com/repos/${owner}/${repo}`;
+  const response = await fetch(url, {
+    headers: {
+      Accept: "application/vnd.github.v3+json",
+      "User-Agent": "DocCov-Scanner"
     }
-    return result;
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch repository: ${response.status} ${response.statusText}`);
   }
-  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 });
+  const data = await response.json();
+  return {
+    owner,
+    repo,
+    defaultBranch: data.default_branch,
+    description: data.description,
+    language: data.language,
+    topics: data.topics ?? [],
+    isPrivate: data.private
+  };
+}
+async function detectPackageManager3(owner, repo, ref) {
+  const lockfiles = [
+    { name: "bun.lockb", manager: "bun" },
+    { name: "pnpm-lock.yaml", manager: "pnpm" },
+    { name: "yarn.lock", manager: "yarn" },
+    { name: "package-lock.json", manager: "npm" }
+  ];
+  for (const { name, manager } of lockfiles) {
+    const content = await fetchRawFile(owner, repo, ref, name);
+    if (content !== null) {
+      return { manager, lockfile: { name, content: content.slice(0, 1e4) } };
+    }
+  }
+  return { manager: "unknown" };
+}
+async function detectWorkspace(packageJson, owner, repo, ref) {
+  const pnpmWorkspace = await fetchRawFile(owner, repo, ref, "pnpm-workspace.yaml");
+  if (pnpmWorkspace) {
+    const packagesMatch = pnpmWorkspace.match(/packages:\s*\n((?:\s+-\s+['"]?[^\n]+['"]?\n?)+)/);
+    const packages = packagesMatch ? packagesMatch[1].split(`
+`).map((line) => line.replace(/^\s+-\s+['"]?/, "").replace(/['"]?\s*$/, "")).filter(Boolean) : undefined;
     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
+      isMonorepo: true,
+      tool: "pnpm",
+      packages
     };
   }
+  const lernaJson = await fetchRawFile(owner, repo, ref, "lerna.json");
+  if (lernaJson) {
+    return { isMonorepo: true, tool: "lerna" };
+  }
+  if (packageJson && typeof packageJson === "object") {
+    const pkg = packageJson;
+    if (pkg.workspaces) {
+      const workspaces = pkg.workspaces;
+      const packages = Array.isArray(workspaces) ? workspaces : workspaces.packages;
+      return {
+        isMonorepo: true,
+        tool: "npm",
+        packages: packages?.filter((p) => typeof p === "string")
+      };
+    }
+  }
+  return { isMonorepo: false };
 }
-
-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;
+function detectBuildHints(packageJson, tsconfigJson) {
+  const hints = {
+    hasTypeScript: false,
+    hasWasm: false,
+    hasNativeModules: false,
+    hasBuildScript: false,
+    frameworks: []
+  };
+  if (!packageJson || typeof packageJson !== "object") {
+    return hints;
+  }
+  const pkg = packageJson;
+  const deps = {
+    ...typeof pkg.dependencies === "object" ? pkg.dependencies : {},
+    ...typeof pkg.devDependencies === "object" ? pkg.devDependencies : {}
+  };
+  hints.hasTypeScript = "typescript" in deps || tsconfigJson !== null;
+  hints.hasWasm = "wasm-pack" in deps || "@aspect-build/rules_esbuild" in deps;
+  hints.hasNativeModules = "node-gyp" in deps || "prebuild" in deps || "napi-rs" in deps;
+  const scripts = typeof pkg.scripts === "object" ? pkg.scripts : {};
+  if (scripts.build) {
+    hints.hasBuildScript = true;
+    hints.buildScript = scripts.build;
+  }
+  const frameworkDeps = [
+    { dep: "react", name: "React" },
+    { dep: "vue", name: "Vue" },
+    { dep: "svelte", name: "Svelte" },
+    { dep: "next", name: "Next.js" },
+    { dep: "nuxt", name: "Nuxt" },
+    { dep: "astro", name: "Astro" },
+    { dep: "express", name: "Express" },
+    { dep: "fastify", name: "Fastify" },
+    { dep: "hono", name: "Hono" }
+  ];
+  for (const { dep, name } of frameworkDeps) {
+    if (dep in deps) {
+      hints.frameworks.push(name);
+    }
+  }
+  return hints;
+}
+async function fetchGitHubContext(repoUrl, ref) {
+  const parsed = parseGitHubUrl2(repoUrl);
+  if (!parsed) {
+    throw new Error(`Invalid GitHub URL: ${repoUrl}`);
+  }
+  const { owner, repo } = parsed;
+  const metadata = await fetchRepoMetadata(owner, repo);
+  const targetRef = ref ?? metadata.defaultBranch;
+  const [packageJsonRaw, tsconfigJsonRaw, pmResult] = await Promise.all([
+    fetchRawFile(owner, repo, targetRef, "package.json"),
+    fetchRawFile(owner, repo, targetRef, "tsconfig.json"),
+    detectPackageManager3(owner, repo, targetRef)
+  ]);
+  let packageJson = null;
+  let tsconfigJson = null;
+  if (packageJsonRaw) {
+    try {
+      packageJson = JSON.parse(packageJsonRaw);
+    } catch {}
+  }
+  if (tsconfigJsonRaw) {
+    try {
+      tsconfigJson = JSON.parse(tsconfigJsonRaw);
+    } catch {}
+  }
+  const workspace = await detectWorkspace(packageJson, owner, repo, targetRef);
+  const buildHints = detectBuildHints(packageJson, tsconfigJson);
+  return {
+    metadata,
+    ref: targetRef,
+    packageManager: pmResult.manager,
+    workspace,
+    buildHints,
+    files: {
+      packageJson: packageJsonRaw ?? undefined,
+      tsconfigJson: tsconfigJsonRaw ?? undefined,
+      lockfile: pmResult.lockfile
+    }
+  };
+}
+async function listWorkspacePackages(owner, repo, ref, patterns) {
+  const packages = [];
+  for (const pattern of patterns) {
+    const baseDir = pattern.replace(/\/\*.*$/, "");
+    try {
+      const url = `https://api.github.com/repos/${owner}/${repo}/contents/${baseDir}?ref=${ref}`;
+      const response = await fetch(url, {
+        headers: {
+          Accept: "application/vnd.github.v3+json",
+          "User-Agent": "DocCov-Scanner"
+        }
+      });
+      if (response.ok) {
+        const contents = await response.json();
+        for (const item of contents) {
+          if (item.type === "dir") {
+            packages.push(`${baseDir}/${item.name}`);
+          }
+        }
+      }
+    } catch {}
   }
+  return packages;
 }
 export {
   validateSpecCache,
@@ -8626,6 +8769,7 @@ export {
   runExample,
   resolveTarget,
   readPackageJson,
+  parseGitHubUrl2 as parseScanGitHubUrl,
   parseMarkdownFiles,
   parseMarkdownFile,
   parseListFlag,
@@ -8638,6 +8782,7 @@ export {
   mergeConfig,
   loadSpecCache,
   loadCachedReport,
+  listWorkspacePackages,
   isFixableDrift,
   isExecutableLang,
   isCachedReportValid,
@@ -8676,6 +8821,7 @@ export {
   findDeprecatedReferences,
   fetchSpecFromGitHub,
   fetchSpec,
+  fetchGitHubContext,
   extractSpecSummary,
   extractPackageSpec,
   extractImports,
@@ -8713,15 +8859,12 @@ export {
   analyzeDocsImpact,
   analyze,
   VALIDATION_INFO,
-  ScanOrchestrator,
   SandboxFileSystem,
   STYLE_RULES,
   SPEC_CACHE_FILE,
   REPORT_VERSION,
   REPORT_EXTENSIONS,
-  OpenPkg,
   NodeFileSystem,
-  MonorepoRequiresPackageError,
   DocCov,
   DEFAULT_REPORT_PATH,
   DEFAULT_REPORT_DIR,