@doccov/sdk 0.15.1 → 0.18.0

package/dist/index.js

@@ -4,19 +4,169 @@ 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))
+var __toESM = (mod2, isNodeMode, target) => {
+  target = mod2 != null ? __create(__getProtoOf(mod2)) : {};
+  const to = isNodeMode || !mod2 || !mod2.__esModule ? __defProp(target, "default", { value: mod2, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod2))
     if (!__hasOwnProp.call(to, key))
       __defProp(to, key, {
-        get: () => mod[key],
+        get: () => mod2[key],
         enumerable: true
       });
   return to;
 };
-var __require = createRequire(import.meta.url);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
+// src/analysis/schema-detection.ts
+import * as fs from "node:fs";
+
+// src/extraction/standard-schema.ts
+function isStandardJSONSchema(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const obj = value;
+  const standard = obj["~standard"];
+  if (typeof standard !== "object" || standard === null) {
+    return false;
+  }
+  const stdObj = standard;
+  if (typeof stdObj.version !== "number") {
+    return false;
+  }
+  const jsonSchema = stdObj.jsonSchema;
+  if (typeof jsonSchema !== "object" || jsonSchema === null) {
+    return false;
+  }
+  const jsonSchemaObj = jsonSchema;
+  return typeof jsonSchemaObj.output === "function";
+}
+function extractViaStandardSchema(schema, options = {}) {
+  const standard = schema["~standard"];
+  const target = options.target ?? "draft-2020-12";
+  const extractedSchema = standard.jsonSchema.output({ target });
+  return {
+    schema: extractedSchema,
+    vendor: standard.vendor,
+    version: standard.version
+  };
+}
+function tryExtractStandardSchema(value, options = {}) {
+  if (!isStandardJSONSchema(value)) {
+    return null;
+  }
+  try {
+    return extractViaStandardSchema(value, options);
+  } catch {
+    return null;
+  }
+}
+var KNOWN_VENDORS = {
+  zod: { minVersion: "4.2.0", homepage: "https://zod.dev" },
+  arktype: { minVersion: "2.0.0", homepage: "https://arktype.io" },
+  valibot: { minVersion: "1.0.0", homepage: "https://valibot.dev" }
+};
+// src/analysis/schema-detection.ts
+var moduleCache = new Map;
+function getFileMtime(filePath) {
+  try {
+    return fs.statSync(filePath).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+async function loadModule(modulePath) {
+  const currentMtime = getFileMtime(modulePath);
+  const cached = moduleCache.get(modulePath);
+  if (cached && cached.mtime === currentMtime && currentMtime > 0) {
+    return cached.module;
+  }
+  try {
+    const requireCache = eval("require").cache;
+    if (requireCache && requireCache[modulePath]) {
+      delete requireCache[modulePath];
+    }
+  } catch {}
+  let mod;
+  try {
+    mod = eval("require")(modulePath);
+  } catch (err) {
+    const nodeErr = err;
+    if (nodeErr.code === "ERR_REQUIRE_ESM") {
+      const cacheBuster = currentMtime > 0 ? `?t=${currentMtime}` : "";
+      mod = await import(`${modulePath}${cacheBuster}`);
+    } else {
+      throw err;
+    }
+  }
+  moduleCache.set(modulePath, { module: mod, mtime: currentMtime });
+  return mod;
+}
+async function detectRuntimeSchemas(context) {
+  const result = {
+    schemas: new Map,
+    errors: []
+  };
+  try {
+    const modulePath2 = resolveModulePath(context.entryFile, context.baseDir);
+    if (!modulePath2) {
+      result.errors.push("Could not resolve compiled module path");
+      return result;
+    }
+    const mod2 = await loadModule(modulePath2);
+    if (!mod2 || typeof mod2 !== "object") {
+      result.errors.push("Module did not export an object");
+      return result;
+    }
+    const exports = mod2;
+    for (const [name, value] of Object.entries(exports)) {
+      if (name.startsWith("_") || name === "default") {
+        continue;
+      }
+      const schemaResult = tryExtractStandardSchema(value);
+      if (schemaResult) {
+        result.schemas.set(name, schemaResult);
+      }
+    }
+    if ("default" in exports && exports.default && typeof exports.default === "object") {
+      const defaultExports = exports.default;
+      for (const [name, value] of Object.entries(defaultExports)) {
+        if (name.startsWith("_"))
+          continue;
+        const schemaResult = tryExtractStandardSchema(value);
+        if (schemaResult && !result.schemas.has(name)) {
+          result.schemas.set(name, schemaResult);
+        }
+      }
+    }
+  } catch (err) {
+    result.errors.push(`Runtime detection failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  return result;
+}
+function resolveModulePath(entryFile, baseDir) {
+  if (entryFile.endsWith(".js") || entryFile.endsWith(".mjs") || entryFile.endsWith(".cjs")) {
+    return entryFile;
+  }
+  const tsFile = entryFile;
+  const possiblePaths = [
+    tsFile.replace(/\.tsx?$/, ".js"),
+    tsFile.replace(/\.tsx?$/, ".mjs"),
+    tsFile.replace(/\/src\//, "/dist/").replace(/\.tsx?$/, ".js"),
+    tsFile.replace(/\/src\//, "/build/").replace(/\.tsx?$/, ".js"),
+    tsFile.replace(/\/src\//, "/lib/").replace(/\.tsx?$/, ".js")
+  ];
+  for (const testPath of possiblePaths) {
+    try {
+      __require.resolve(testPath, { paths: [baseDir] });
+      return testPath;
+    } catch {}
+  }
+  return null;
+}
+function clearSchemaCache() {
+  moduleCache.clear();
+}
 // src/analysis/docs-coverage.ts
 import {
   DRIFT_CATEGORIES
@@ -446,7 +596,7 @@ function categorizeDrifts(drifts) {
   return { fixable, nonFixable };
 }
 // src/fix/jsdoc-writer.ts
-import * as fs from "node:fs";
+import * as fs2 from "node:fs";
 import * as path from "node:path";
 
 // src/ts-module.ts
@@ -786,7 +936,7 @@ async function applyEdits(edits) {
   }
   for (const [filePath, fileEdits] of editsByFile) {
     try {
-      const content = fs.readFileSync(filePath, "utf-8");
+      const content = fs2.readFileSync(filePath, "utf-8");
       const lines = content.split(`
 `);
       const sortedEdits = [...fileEdits].sort((a, b) => b.startLine - a.startLine);
@@ -800,7 +950,7 @@ async function applyEdits(edits) {
         }
         result.editsApplied++;
       }
-      fs.writeFileSync(filePath, lines.join(`
+      fs2.writeFileSync(filePath, lines.join(`
 `));
       result.filesModified++;
     } catch (error) {
@@ -813,7 +963,7 @@ async function applyEdits(edits) {
   return result;
 }
 function createSourceFile(filePath) {
-  const content = fs.readFileSync(filePath, "utf-8");
+  const content = fs2.readFileSync(filePath, "utf-8");
   return ts.createSourceFile(path.basename(filePath), content, ts.ScriptTarget.Latest, true, filePath.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
 }
 // src/utils/builtin-detection.ts
@@ -2013,6 +2163,122 @@ function ensureSpecCoverage(spec) {
   };
 }
 // src/quality/rules.ts
+var BUILTIN_TYPES = new Set([
+  "string",
+  "number",
+  "boolean",
+  "object",
+  "any",
+  "unknown",
+  "void",
+  "never",
+  "null",
+  "undefined",
+  "symbol",
+  "bigint",
+  "Array",
+  "Promise",
+  "Map",
+  "Set",
+  "Record",
+  "Partial",
+  "Required",
+  "Readonly",
+  "Pick",
+  "Omit",
+  "Exclude",
+  "Extract",
+  "NonNullable",
+  "ReturnType",
+  "Parameters",
+  "InstanceType",
+  "ConstructorParameters",
+  "Awaited"
+]);
+function extractTypeReferences(exp) {
+  const refs = new Set;
+  function collectFromSchema(schema) {
+    if (!schema)
+      return;
+    if (typeof schema === "string") {
+      if (!BUILTIN_TYPES.has(schema)) {
+        refs.add(schema);
+      }
+      return;
+    }
+    if (typeof schema === "object") {
+      const obj = schema;
+      if (typeof obj.$ref === "string") {
+        const ref = obj.$ref;
+        const name = ref.startsWith("#/types/") ? ref.slice("#/types/".length) : ref;
+        if (!BUILTIN_TYPES.has(name)) {
+          refs.add(name);
+        }
+      }
+      if (typeof obj.type === "string" && !BUILTIN_TYPES.has(obj.type)) {
+        refs.add(obj.type);
+      }
+      if (obj.items) {
+        collectFromSchema(obj.items);
+      }
+      if (obj.properties && typeof obj.properties === "object") {
+        for (const prop of Object.values(obj.properties)) {
+          collectFromSchema(prop);
+        }
+      }
+      if (Array.isArray(obj.anyOf)) {
+        for (const item of obj.anyOf) {
+          collectFromSchema(item);
+        }
+      }
+      if (Array.isArray(obj.oneOf)) {
+        for (const item of obj.oneOf) {
+          collectFromSchema(item);
+        }
+      }
+      if (Array.isArray(obj.allOf)) {
+        for (const item of obj.allOf) {
+          collectFromSchema(item);
+        }
+      }
+      if (obj.additionalProperties && typeof obj.additionalProperties === "object") {
+        collectFromSchema(obj.additionalProperties);
+      }
+    }
+  }
+  for (const sig of exp.signatures ?? []) {
+    for (const param of sig.parameters ?? []) {
+      collectFromSchema(param.schema);
+    }
+    if (sig.returns?.schema) {
+      collectFromSchema(sig.returns.schema);
+    }
+  }
+  for (const member of exp.members ?? []) {
+    collectFromSchema(member.schema);
+    for (const sig of member.signatures ?? []) {
+      for (const param of sig.parameters ?? []) {
+        collectFromSchema(param.schema);
+      }
+      if (sig.returns?.schema) {
+        collectFromSchema(sig.returns.schema);
+      }
+    }
+  }
+  collectFromSchema(exp.schema);
+  if (typeof exp.type === "string" && !BUILTIN_TYPES.has(exp.type)) {
+    refs.add(exp.type);
+  }
+  if (exp.extends && !BUILTIN_TYPES.has(exp.extends)) {
+    refs.add(exp.extends);
+  }
+  for (const impl of exp.implements ?? []) {
+    if (!BUILTIN_TYPES.has(impl)) {
+      refs.add(impl);
+    }
+  }
+  return refs;
+}
 var CORE_RULES = [
   {
     id: "has-description",
@@ -2099,6 +2365,99 @@ var CORE_RULES = [
     }
   }
 ];
+var TSDOC_RULES = [
+  {
+    id: "require-release-tag",
+    name: "Require Release Tag",
+    description: "All exports must have @public, @beta, @alpha, or @internal",
+    affectsCoverage: false,
+    defaultSeverity: "off",
+    check(ctx) {
+      const tags = ctx.export.tags ?? [];
+      return tags.some((t) => ["public", "beta", "alpha", "internal"].includes(t.name.toLowerCase()));
+    },
+    getViolation(ctx) {
+      return {
+        ruleId: "require-release-tag",
+        severity: "warn",
+        message: `Export '${ctx.export.name}' is missing a release tag (@public, @beta, @alpha, or @internal)`,
+        fixable: true
+      };
+    }
+  },
+  {
+    id: "internal-underscore",
+    name: "Internal Underscore Prefix",
+    description: "@internal exports should have underscore prefix",
+    affectsCoverage: false,
+    defaultSeverity: "off",
+    check(ctx) {
+      const tags = ctx.export.tags ?? [];
+      const isInternal = tags.some((t) => t.name.toLowerCase() === "internal");
+      if (!isInternal)
+        return true;
+      return ctx.export.name.startsWith("_");
+    },
+    getViolation(ctx) {
+      return {
+        ruleId: "internal-underscore",
+        severity: "warn",
+        message: `Internal export '${ctx.export.name}' should have underscore prefix (_${ctx.export.name})`,
+        fixable: false
+      };
+    }
+  },
+  {
+    id: "no-conflicting-tags",
+    name: "No Conflicting Tags",
+    description: "Cannot have both @internal and @public/@beta/@alpha",
+    affectsCoverage: false,
+    defaultSeverity: "warn",
+    check(ctx) {
+      const tags = ctx.export.tags ?? [];
+      const tagNames = tags.map((t) => t.name.toLowerCase());
+      const hasInternal = tagNames.includes("internal");
+      const hasPublicish = tagNames.some((n) => ["public", "beta", "alpha"].includes(n));
+      return !(hasInternal && hasPublicish);
+    },
+    getViolation(ctx) {
+      return {
+        ruleId: "no-conflicting-tags",
+        severity: "error",
+        message: `Export '${ctx.export.name}' has conflicting release tags (@internal with @public/@beta/@alpha)`,
+        fixable: false
+      };
+    }
+  },
+  {
+    id: "no-forgotten-export",
+    name: "No Forgotten Export",
+    description: "All referenced types must be exported",
+    affectsCoverage: false,
+    defaultSeverity: "off",
+    check(ctx) {
+      if (!ctx.exportRegistry)
+        return true;
+      const refs = extractTypeReferences(ctx.export);
+      for (const ref of refs) {
+        if (!ctx.exportRegistry.has(ref)) {
+          return false;
+        }
+      }
+      return true;
+    },
+    getViolation(ctx) {
+      const refs = extractTypeReferences(ctx.export);
+      const missing = ctx.exportRegistry ? [...refs].filter((r) => !ctx.exportRegistry.has(r)) : [];
+      return {
+        ruleId: "no-forgotten-export",
+        severity: "warn",
+        message: missing.length > 0 ? `Export '${ctx.export.name}' references unexported types: ${missing.join(", ")}` : `Export '${ctx.export.name}' references types that are not exported`,
+        fixable: false
+      };
+    }
+  }
+];
 var STYLE_RULES = [
   {
     id: "no-empty-returns",
@@ -2165,7 +2524,7 @@ var STYLE_RULES = [
     }
   }
 ];
-var BUILTIN_RULES = [...CORE_RULES, ...STYLE_RULES];
+var BUILTIN_RULES = [...CORE_RULES, ...TSDOC_RULES, ...STYLE_RULES];
 function getCoverageRules() {
   return BUILTIN_RULES.filter((r) => r.affectsCoverage);
 }
@@ -2188,7 +2547,7 @@ function getDefaultConfig() {
 }
 
 // src/quality/engine.ts
-function evaluateExportQuality(exp, rawJSDoc, config = { rules: {} }) {
+function evaluateExportQuality(exp, rawJSDoc, config = { rules: {} }, exportRegistry) {
   const kind = exp.kind ?? "variable";
   const applicableRules = getRulesForKind(kind);
   const defaults = getDefaultConfig();
@@ -2213,7 +2572,7 @@ function evaluateExportQuality(exp, rawJSDoc, config = { rules: {} }) {
       fixableCount: 0
     }
   };
-  const context = { export: exp, rawJSDoc };
+  const context = { export: exp, rawJSDoc, exportRegistry };
   for (const rule of applicableRules) {
     const passed = rule.check(context);
     const severity = getSeverity(rule.id, rule.defaultSeverity);
@@ -2313,7 +2672,7 @@ function enrichSpec(spec, options = {}) {
   let totalCoverage = 0;
   const enrichedExports = spec.exports.map((exp) => {
     const rawJSDoc = rawJSDocByExport?.get(exp.id);
-    const quality = evaluateExportQuality(exp, rawJSDoc, qualityConfig);
+    const quality = evaluateExportQuality(exp, rawJSDoc, qualityConfig, exportRegistry);
     const drift = computeExportDrift(exp, exportRegistry);
     const additionalDrift = driftByExport?.get(exp.id);
     const allDrift2 = additionalDrift ? [...drift, ...additionalDrift] : drift;
@@ -2360,7 +2719,7 @@ function enrichSpec(spec, options = {}) {
   };
 }
 // src/analysis/report.ts
-import * as fs2 from "node:fs";
+import * as fs3 from "node:fs";
 import * as path2 from "node:path";
 
 // src/types/report.ts
@@ -2424,7 +2783,7 @@ function generateReportFromEnriched(enriched) {
     driftSummary
   };
   return {
-    $schema: "https://doccov.dev/schemas/v1.0.0/report.schema.json",
+    $schema: "https://doccov.com/schemas/v1.0.0/report.schema.json",
     version: REPORT_VERSION,
     generatedAt: new Date().toISOString(),
     spec: {
@@ -2438,10 +2797,10 @@ function generateReportFromEnriched(enriched) {
 function loadCachedReport(reportPath = DEFAULT_REPORT_PATH) {
   try {
     const fullPath = path2.resolve(reportPath);
-    if (!fs2.existsSync(fullPath)) {
+    if (!fs3.existsSync(fullPath)) {
       return null;
     }
-    const content = fs2.readFileSync(fullPath, "utf-8");
+    const content = fs3.readFileSync(fullPath, "utf-8");
     return JSON.parse(content);
   } catch {
     return null;
@@ -2450,10 +2809,10 @@ function loadCachedReport(reportPath = DEFAULT_REPORT_PATH) {
 function saveReport(report, reportPath = DEFAULT_REPORT_PATH) {
   const fullPath = path2.resolve(reportPath);
   const dir = path2.dirname(fullPath);
-  if (!fs2.existsSync(dir)) {
-    fs2.mkdirSync(dir, { recursive: true });
+  if (!fs3.existsSync(dir)) {
+    fs3.mkdirSync(dir, { recursive: true });
   }
-  fs2.writeFileSync(fullPath, JSON.stringify(report, null, 2));
+  fs3.writeFileSync(fullPath, JSON.stringify(report, null, 2));
 }
 function isCachedReportValid(reportPath = DEFAULT_REPORT_PATH, sourceFiles = []) {
   const report = loadCachedReport(reportPath);
@@ -2463,7 +2822,7 @@ function isCachedReportValid(reportPath = DEFAULT_REPORT_PATH, sourceFiles = [])
   const reportTime = new Date(report.generatedAt).getTime();
   for (const file of sourceFiles) {
     try {
-      const stat = fs2.statSync(file);
+      const stat = fs3.statSync(file);
       if (stat.mtimeMs > reportTime) {
         return false;
       }
@@ -2473,58 +2832,460 @@ function isCachedReportValid(reportPath = DEFAULT_REPORT_PATH, sourceFiles = [])
   }
   return true;
 }
-// src/cache/hash.ts
-import * as crypto from "node:crypto";
-import * as fs3 from "node:fs";
-import * as path3 from "node:path";
-function hashFile(filePath) {
-  try {
-    const content = fs3.readFileSync(filePath);
-    return crypto.createHash("sha256").update(content).digest("hex").slice(0, 16);
-  } catch {
-    return null;
+function formatSignature(name, signature) {
+  const params = (signature.parameters ?? []).map((p) => {
+    const optional = p.required === false ? "?" : "";
+    const rest = p.rest ? "..." : "";
+    const typeStr = typeof p.schema === "string" ? p.schema : p.schema?.type ?? "unknown";
+    return `${rest}${p.name}${optional}: ${typeStr}`;
+  }).join(", ");
+  const returnType = signature.returns ? typeof signature.returns.schema === "string" ? signature.returns.schema : signature.returns.schema?.type ?? "unknown" : "void";
+  const typeParams = signature.typeParameters?.length ? `<${signature.typeParameters.map((tp) => tp.name).join(", ")}>` : "";
+  return `${name}${typeParams}(${params}): ${returnType}`;
+}
+function formatExportToApiSurface(exp) {
+  const lines = [];
+  lines.push(`### ${exp.name}`);
+  switch (exp.kind) {
+    case "function": {
+      const signatures = exp.signatures ?? [];
+      if (signatures.length === 0) {
+        lines.push(`\`\`\`typescript
+function ${exp.name}(): unknown
+\`\`\``);
+      } else {
+        for (const sig of signatures) {
+          lines.push(`\`\`\`typescript
+function ${formatSignature(exp.name, sig)}
+\`\`\``);
+        }
+      }
+      break;
+    }
+    case "class": {
+      const extendsClause = exp.extends ? ` extends ${exp.extends}` : "";
+      const implementsClause = exp.implements?.length ? ` implements ${exp.implements.join(", ")}` : "";
+      lines.push(`\`\`\`typescript
+class ${exp.name}${extendsClause}${implementsClause}
+\`\`\``);
+      break;
+    }
+    case "interface":
+    case "type": {
+      const typeStr = typeof exp.type === "string" ? exp.type : exp.type?.type ?? "{ ... }";
+      lines.push(`\`\`\`typescript
+type ${exp.name} = ${typeStr}
+\`\`\``);
+      break;
+    }
+    case "variable": {
+      const typeStr = typeof exp.type === "string" ? exp.type : exp.type?.type ?? "unknown";
+      lines.push(`\`\`\`typescript
+const ${exp.name}: ${typeStr}
+\`\`\``);
+      break;
+    }
+    case "enum": {
+      lines.push(`\`\`\`typescript
+enum ${exp.name} { ... }
+\`\`\``);
+      break;
+    }
+    default: {
+      lines.push(`\`\`\`typescript
+${exp.kind} ${exp.name}
+\`\`\``);
+    }
   }
+  return lines.join(`
+`);
 }
-function hashString(content) {
-  return crypto.createHash("sha256").update(content).digest("hex").slice(0, 16);
-}
-function hashFiles(filePaths, cwd) {
-  const hashes = {};
-  for (const filePath of filePaths) {
-    const hash = hashFile(filePath);
-    if (hash) {
-      const relativePath = path3.relative(cwd, filePath);
-      hashes[relativePath] = hash;
+function formatTypeToApiSurface(type) {
+  const lines = [];
+  lines.push(`### ${type.name}`);
+  switch (type.kind) {
+    case "interface": {
+      const extendsClause = type.extends ? ` extends ${type.extends}` : "";
+      lines.push(`\`\`\`typescript
+interface ${type.name}${extendsClause} { ... }
+\`\`\``);
+      break;
+    }
+    case "type": {
+      const typeStr = typeof type.type === "string" ? type.type : type.type?.type ?? "{ ... }";
+      lines.push(`\`\`\`typescript
+type ${type.name} = ${typeStr}
+\`\`\``);
+      break;
+    }
+    case "class": {
+      const extendsClause = type.extends ? ` extends ${type.extends}` : "";
+      lines.push(`\`\`\`typescript
+class ${type.name}${extendsClause}
+\`\`\``);
+      break;
+    }
+    case "enum": {
+      lines.push(`\`\`\`typescript
+enum ${type.name} { ... }
+\`\`\``);
+      break;
+    }
+    default: {
+      lines.push(`\`\`\`typescript
+${type.kind} ${type.name}
+\`\`\``);
     }
   }
-  return hashes;
+  return lines.join(`
+`);
 }
-function diffHashes(cached, current) {
-  const changed = [];
-  for (const [file, hash] of Object.entries(cached)) {
-    if (current[file] !== hash) {
-      changed.push(file);
+function renderApiSurface(spec) {
+  const lines = [];
+  const version = spec.meta.version ? ` v${spec.meta.version}` : "";
+  lines.push(`# API Surface: ${spec.meta.name}${version}`);
+  lines.push("");
+  lines.push("> This file is auto-generated. Do not edit manually.");
+  lines.push("> Run `doccov spec --format api-surface` to regenerate.");
+  lines.push("");
+  const exportsByKind = {};
+  for (const exp of spec.exports) {
+    const kind = exp.kind;
+    if (!exportsByKind[kind]) {
+      exportsByKind[kind] = [];
+    }
+    exportsByKind[kind].push(exp);
+  }
+  for (const kind of Object.keys(exportsByKind)) {
+    exportsByKind[kind].sort((a, b) => a.name.localeCompare(b.name));
+  }
+  const kindOrder = [
+    "function",
+    "class",
+    "interface",
+    "type",
+    "variable",
+    "enum",
+    "namespace",
+    "module"
+  ];
+  for (const kind of kindOrder) {
+    const exports = exportsByKind[kind];
+    if (!exports || exports.length === 0)
+      continue;
+    const kindTitle = kind.charAt(0).toUpperCase() + kind.slice(1) + "s";
+    lines.push(`## ${kindTitle}`);
+    lines.push("");
+    for (const exp of exports) {
+      lines.push(formatExportToApiSurface(exp));
+      lines.push("");
     }
   }
-  for (const file of Object.keys(current)) {
-    if (!(file in cached)) {
-      changed.push(file);
+  for (const kind of Object.keys(exportsByKind).sort()) {
+    if (kindOrder.includes(kind))
+      continue;
+    const exports = exportsByKind[kind];
+    if (!exports || exports.length === 0)
+      continue;
+    const kindTitle = kind.charAt(0).toUpperCase() + kind.slice(1) + "s";
+    lines.push(`## ${kindTitle}`);
+    lines.push("");
+    for (const exp of exports) {
+      lines.push(formatExportToApiSurface(exp));
+      lines.push("");
     }
   }
-  return changed;
+  const types = spec.types ?? [];
+  if (types.length > 0) {
+    const sortedTypes = [...types].sort((a, b) => a.name.localeCompare(b.name));
+    lines.push("## Internal Types");
+    lines.push("");
+    for (const type of sortedTypes) {
+      lines.push(formatTypeToApiSurface(type));
+      lines.push("");
+    }
+  }
+  return lines.join(`
+`);
 }
-// src/cache/spec-cache.ts
+// src/analysis/history.ts
 import * as fs4 from "node:fs";
-import * as path4 from "node:path";
-var CACHE_VERSION = "1.0.0";
+import * as path3 from "node:path";
+var HISTORY_DIR = ".doccov/history";
+var RETENTION_DAYS = {
+  free: 7,
+  team: 30,
+  pro: 90
+};
+function getSnapshotFilename(timestamp) {
+  const pad = (n) => n.toString().padStart(2, "0");
+  const year = timestamp.getFullYear();
+  const month = pad(timestamp.getMonth() + 1);
+  const day = pad(timestamp.getDate());
+  const hours = pad(timestamp.getHours());
+  const minutes = pad(timestamp.getMinutes());
+  const seconds = pad(timestamp.getSeconds());
+  return `${year}-${month}-${day}-${hours}${minutes}${seconds}.json`;
+}
+function computeSnapshot(spec, options) {
+  const exports = spec.exports ?? [];
+  const documented = exports.filter((e) => e.description && e.description.trim().length > 0);
+  const driftCount = exports.reduce((sum, e) => {
+    const docs = e.docs;
+    return sum + (docs?.drift?.length ?? 0);
+  }, 0);
+  const coverageScore = exports.length > 0 ? Math.round(documented.length / exports.length * 100) : 100;
+  return {
+    timestamp: new Date().toISOString(),
+    package: spec.meta.name,
+    version: spec.meta.version,
+    coverageScore,
+    totalExports: exports.length,
+    documentedExports: documented.length,
+    driftCount,
+    commit: options?.commit,
+    branch: options?.branch
+  };
+}
+function saveSnapshot(snapshot, cwd) {
+  const historyDir = path3.resolve(cwd, HISTORY_DIR);
+  if (!fs4.existsSync(historyDir)) {
+    fs4.mkdirSync(historyDir, { recursive: true });
+  }
+  const filename = getSnapshotFilename(new Date(snapshot.timestamp));
+  const filepath = path3.join(historyDir, filename);
+  fs4.writeFileSync(filepath, JSON.stringify(snapshot, null, 2));
+}
+function loadSnapshots(cwd) {
+  const historyDir = path3.resolve(cwd, HISTORY_DIR);
+  if (!fs4.existsSync(historyDir)) {
+    return [];
+  }
+  const files = fs4.readdirSync(historyDir).filter((f) => f.endsWith(".json")).sort().reverse();
+  const snapshots = [];
+  for (const file of files) {
+    try {
+      const content = fs4.readFileSync(path3.join(historyDir, file), "utf-8");
+      snapshots.push(JSON.parse(content));
+    } catch {}
+  }
+  return snapshots;
+}
+function getTrend(spec, cwd, options) {
+  const current = computeSnapshot(spec, options);
+  const history = loadSnapshots(cwd);
+  const delta = history.length > 0 ? current.coverageScore - history[0].coverageScore : undefined;
+  const sparklineHistory = history.slice(0, 9).map((s) => s.coverageScore);
+  const sparkline = [current.coverageScore, ...sparklineHistory].reverse();
+  return {
+    current,
+    history,
+    delta,
+    sparkline
+  };
+}
+function renderSparkline(values) {
+  if (values.length === 0)
+    return "";
+  const chars = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"];
+  const min = Math.min(...values);
+  const max = Math.max(...values);
+  const range = max - min || 1;
+  return values.map((v) => {
+    const normalized = (v - min) / range;
+    const index = Math.min(Math.floor(normalized * chars.length), chars.length - 1);
+    return chars[index];
+  }).join("");
+}
+function formatDelta(delta) {
+  if (delta > 0)
+    return `↑${delta}%`;
+  if (delta < 0)
+    return `↓${Math.abs(delta)}%`;
+  return "→0%";
+}
+function pruneHistory(cwd, keepCount = 100) {
+  const historyDir = path3.resolve(cwd, HISTORY_DIR);
+  if (!fs4.existsSync(historyDir)) {
+    return 0;
+  }
+  const files = fs4.readdirSync(historyDir).filter((f) => f.endsWith(".json")).sort().reverse();
+  const toDelete = files.slice(keepCount);
+  for (const file of toDelete) {
+    try {
+      fs4.unlinkSync(path3.join(historyDir, file));
+    } catch {}
+  }
+  return toDelete.length;
+}
+function pruneByTier(cwd, tier) {
+  const retentionDays = RETENTION_DAYS[tier];
+  const cutoffDate = new Date;
+  cutoffDate.setDate(cutoffDate.getDate() - retentionDays);
+  const historyDir = path3.resolve(cwd, HISTORY_DIR);
+  if (!fs4.existsSync(historyDir)) {
+    return 0;
+  }
+  const files = fs4.readdirSync(historyDir).filter((f) => f.endsWith(".json"));
+  let deleted = 0;
+  for (const file of files) {
+    try {
+      const filepath = path3.join(historyDir, file);
+      const content = fs4.readFileSync(filepath, "utf-8");
+      const snapshot = JSON.parse(content);
+      const snapshotDate = new Date(snapshot.timestamp);
+      if (snapshotDate < cutoffDate) {
+        fs4.unlinkSync(filepath);
+        deleted++;
+      }
+    } catch {}
+  }
+  return deleted;
+}
+function loadSnapshotsForDays(cwd, days) {
+  const cutoffDate = new Date;
+  cutoffDate.setDate(cutoffDate.getDate() - days);
+  const allSnapshots = loadSnapshots(cwd);
+  return allSnapshots.filter((s) => new Date(s.timestamp) >= cutoffDate);
+}
+function calculateVelocity(snapshots) {
+  if (snapshots.length < 2)
+    return 0;
+  const newest = snapshots[0];
+  const oldest = snapshots[snapshots.length - 1];
+  const newestDate = new Date(newest.timestamp);
+  const oldestDate = new Date(oldest.timestamp);
+  const daysDiff = (newestDate.getTime() - oldestDate.getTime()) / (1000 * 60 * 60 * 24);
+  if (daysDiff < 1)
+    return 0;
+  const coverageDiff = newest.coverageScore - oldest.coverageScore;
+  return Math.round(coverageDiff / daysDiff * 100) / 100;
+}
+function getWeekStart(date) {
+  const result = new Date(date);
+  result.setDate(result.getDate() - result.getDay());
+  result.setHours(0, 0, 0, 0);
+  return result;
+}
+function generateWeeklySummaries(snapshots) {
+  if (snapshots.length === 0)
+    return [];
+  const weeklyGroups = new Map;
+  for (const snapshot of snapshots) {
+    const weekStart = getWeekStart(new Date(snapshot.timestamp));
+    const weekKey = weekStart.toISOString().split("T")[0];
+    const group = weeklyGroups.get(weekKey) ?? [];
+    group.push(snapshot);
+    weeklyGroups.set(weekKey, group);
+  }
+  const summaries = [];
+  for (const [weekKey, weekSnapshots] of weeklyGroups) {
+    const sorted = [...weekSnapshots].sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+    const weekStart = new Date(weekKey);
+    const weekEnd = new Date(weekStart);
+    weekEnd.setDate(weekEnd.getDate() + 6);
+    const scores = sorted.map((s) => s.coverageScore);
+    const avgCoverage = Math.round(scores.reduce((a, b) => a + b, 0) / scores.length);
+    const startCoverage = sorted[0].coverageScore;
+    const endCoverage = sorted[sorted.length - 1].coverageScore;
+    summaries.push({
+      weekStart: weekStart.toISOString(),
+      weekEnd: weekEnd.toISOString(),
+      avgCoverage,
+      startCoverage,
+      endCoverage,
+      delta: endCoverage - startCoverage,
+      snapshotCount: sorted.length
+    });
+  }
+  return summaries.sort((a, b) => new Date(b.weekStart).getTime() - new Date(a.weekStart).getTime());
+}
+function getExtendedTrend(spec, cwd, options) {
+  const tier = options?.tier ?? "pro";
+  const retentionDays = RETENTION_DAYS[tier];
+  const trend = getTrend(spec, cwd, options);
+  const periodSnapshots = loadSnapshotsForDays(cwd, retentionDays);
+  const snapshots7d = loadSnapshotsForDays(cwd, 7);
+  const snapshots30d = loadSnapshotsForDays(cwd, 30);
+  const snapshots90d = tier === "pro" ? loadSnapshotsForDays(cwd, 90) : [];
+  const velocity7d = calculateVelocity(snapshots7d);
+  const velocity30d = calculateVelocity(snapshots30d);
+  const velocity90d = tier === "pro" ? calculateVelocity(snapshots90d) : undefined;
+  const currentScore = trend.current.coverageScore;
+  const projected30d = Math.min(100, Math.max(0, Math.round(currentScore + velocity30d * 30)));
+  const allScores = [trend.current.coverageScore, ...trend.history.map((s) => s.coverageScore)];
+  const allTimeHigh = Math.max(...allScores);
+  const allTimeLow = Math.min(...allScores);
+  const dataRange = trend.history.length > 0 ? {
+    start: trend.history[trend.history.length - 1].timestamp,
+    end: trend.current.timestamp
+  } : null;
+  const allSnapshots = [trend.current, ...periodSnapshots];
+  const weeklySummaries = generateWeeklySummaries(allSnapshots);
+  return {
+    trend,
+    weeklySummaries,
+    velocity7d,
+    velocity30d,
+    velocity90d,
+    projected30d,
+    allTimeHigh,
+    allTimeLow,
+    dataRange
+  };
+}
+// src/cache/hash.ts
+import * as crypto from "node:crypto";
+import * as fs5 from "node:fs";
+import * as path4 from "node:path";
+function hashFile(filePath) {
+  try {
+    const content = fs5.readFileSync(filePath);
+    return crypto.createHash("sha256").update(content).digest("hex").slice(0, 16);
+  } catch {
+    return null;
+  }
+}
+function hashString(content) {
+  return crypto.createHash("sha256").update(content).digest("hex").slice(0, 16);
+}
+function hashFiles(filePaths, cwd) {
+  const hashes = {};
+  for (const filePath of filePaths) {
+    const hash = hashFile(filePath);
+    if (hash) {
+      const relativePath = path4.relative(cwd, filePath);
+      hashes[relativePath] = hash;
+    }
+  }
+  return hashes;
+}
+function diffHashes(cached2, current) {
+  const changed = [];
+  for (const [file, hash] of Object.entries(cached2)) {
+    if (current[file] !== hash) {
+      changed.push(file);
+    }
+  }
+  for (const file of Object.keys(current)) {
+    if (!(file in cached2)) {
+      changed.push(file);
+    }
+  }
+  return changed;
+}
+// src/cache/spec-cache.ts
+import * as fs6 from "node:fs";
+import * as path5 from "node:path";
+var CACHE_VERSION = "1.0.0";
 var SPEC_CACHE_FILE = ".doccov/spec.cache.json";
 function loadSpecCache(cwd) {
   try {
-    const cachePath = path4.resolve(cwd, SPEC_CACHE_FILE);
-    if (!fs4.existsSync(cachePath)) {
+    const cachePath = path5.resolve(cwd, SPEC_CACHE_FILE);
+    if (!fs6.existsSync(cachePath)) {
       return null;
     }
-    const content = fs4.readFileSync(cachePath, "utf-8");
+    const content = fs6.readFileSync(cachePath, "utf-8");
     return JSON.parse(content);
   } catch {
     return null;
@@ -2536,7 +3297,7 @@ function saveSpecCache(spec, context) {
     cacheVersion: CACHE_VERSION,
     generatedAt: new Date().toISOString(),
     specVersion: spec.openpkg,
-    entryFile: path4.relative(cwd, entryFile),
+    entryFile: path5.relative(cwd, entryFile),
     hashes: {
       tsconfig: tsconfigPath ? hashFile(tsconfigPath) : null,
       packageJson: hashFile(packageJsonPath) ?? "",
@@ -2545,19 +3306,19 @@ function saveSpecCache(spec, context) {
     config,
     spec
   };
-  const cachePath = path4.resolve(cwd, SPEC_CACHE_FILE);
-  const dir = path4.dirname(cachePath);
-  if (!fs4.existsSync(dir)) {
-    fs4.mkdirSync(dir, { recursive: true });
+  const cachePath = path5.resolve(cwd, SPEC_CACHE_FILE);
+  const dir = path5.dirname(cachePath);
+  if (!fs6.existsSync(dir)) {
+    fs6.mkdirSync(dir, { recursive: true });
   }
-  fs4.writeFileSync(cachePath, JSON.stringify(cache, null, 2));
+  fs6.writeFileSync(cachePath, JSON.stringify(cache, null, 2));
 }
 function validateSpecCache(cache, context) {
   const { entryFile, sourceFiles, tsconfigPath, packageJsonPath, config, cwd } = context;
   if (cache.cacheVersion !== CACHE_VERSION) {
     return { valid: false, reason: "cache-version-mismatch" };
   }
-  const relativeEntry = path4.relative(cwd, entryFile);
+  const relativeEntry = path5.relative(cwd, entryFile);
   if (cache.entryFile !== relativeEntry) {
     return { valid: false, reason: "entry-file-changed" };
   }
@@ -2580,34 +3341,333 @@ function validateSpecCache(cache, context) {
   return { valid: true };
 }
 function clearSpecCache(cwd) {
-  const cachePath = path4.resolve(cwd, SPEC_CACHE_FILE);
-  if (fs4.existsSync(cachePath)) {
-    fs4.unlinkSync(cachePath);
+  const cachePath = path5.resolve(cwd, SPEC_CACHE_FILE);
+  if (fs6.existsSync(cachePath)) {
+    fs6.unlinkSync(cachePath);
     return true;
   }
   return false;
 }
 function getSpecCachePath(cwd) {
-  return path4.resolve(cwd, SPEC_CACHE_FILE);
+  return path5.resolve(cwd, SPEC_CACHE_FILE);
+}
+// src/codeowners/index.ts
+import * as fs7 from "node:fs";
+import * as path6 from "node:path";
+import { minimatch } from "minimatch";
+var CODEOWNERS_LOCATIONS = [
+  "CODEOWNERS",
+  ".github/CODEOWNERS",
+  "docs/CODEOWNERS"
+];
+function parseCodeOwners(content) {
+  const rules = [];
+  const lines = content.split(`
+`);
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line || line.startsWith("#"))
+      continue;
+    const parts = line.split(/\s+/);
+    if (parts.length < 2)
+      continue;
+    const pattern = parts[0];
+    const owners = parts.slice(1).filter((o) => o.startsWith("@") || o.includes("@"));
+    if (owners.length > 0) {
+      rules.push({
+        line: i + 1,
+        pattern,
+        owners
+      });
+    }
+  }
+  return rules;
+}
+function loadCodeOwners(baseDir) {
+  for (const location of CODEOWNERS_LOCATIONS) {
+    const filePath = path6.join(baseDir, location);
+    if (fs7.existsSync(filePath)) {
+      const content = fs7.readFileSync(filePath, "utf-8");
+      return {
+        filePath,
+        rules: parseCodeOwners(content)
+      };
+    }
+  }
+  return null;
+}
+function findOwners(filePath, rules) {
+  const normalizedPath = filePath.replace(/^\.\//, "");
+  let matchingOwners = [];
+  for (const rule of rules) {
+    let pattern = rule.pattern;
+    if (pattern.endsWith("/")) {
+      pattern = pattern + "**";
+    }
+    if (pattern.startsWith("/")) {
+      pattern = pattern.slice(1);
+    } else if (!pattern.startsWith("*")) {
+      pattern = "**/" + pattern;
+    }
+    if (minimatch(normalizedPath, pattern, { matchBase: true, dot: true })) {
+      matchingOwners = rule.owners;
+    }
+  }
+  return matchingOwners;
+}
+function attributeOwners(exports, rules, baseDir) {
+  const ownershipMap = new Map;
+  for (const exp of exports) {
+    const filePath = exp.source?.file;
+    if (!filePath) {
+      ownershipMap.set(exp, []);
+      continue;
+    }
+    let relativePath = filePath;
+    if (path6.isAbsolute(filePath)) {
+      relativePath = path6.relative(baseDir, filePath);
+    }
+    const owners = findOwners(relativePath, rules);
+    ownershipMap.set(exp, owners);
+  }
+  return ownershipMap;
+}
+function analyzeOwnership(spec, codeowners, baseDir) {
+  const exports = spec.exports ?? [];
+  const ownershipMap = attributeOwners(exports, codeowners.rules, baseDir);
+  const byOwnerExports = new Map;
+  const unowned = [];
+  for (const [exp, owners] of ownershipMap) {
+    if (owners.length === 0) {
+      unowned.push(exp);
+    } else {
+      for (const owner of owners) {
+        const existing = byOwnerExports.get(owner) ?? [];
+        existing.push(exp);
+        byOwnerExports.set(owner, existing);
+      }
+    }
+  }
+  const byOwner = new Map;
+  for (const [owner, ownerExports] of byOwnerExports) {
+    const documented = ownerExports.filter((e) => e.description);
+    const withDrift = ownerExports.filter((e) => e.docs?.drift && e.docs.drift.length > 0);
+    const withExamples = ownerExports.filter((e) => e.examples && e.examples.length > 0);
+    const undocumented = ownerExports.filter((e) => !e.description);
+    const coverageScore = ownerExports.length === 0 ? 100 : Math.round(documented.length / ownerExports.length * 100);
+    const driftScore = ownerExports.length === 0 ? 0 : Math.round(withDrift.length / ownerExports.length * 100);
+    byOwner.set(owner, {
+      owner,
+      totalExports: ownerExports.length,
+      documentedExports: documented.length,
+      coverageScore,
+      exportsWithDrift: withDrift.length,
+      driftScore,
+      missingExamples: ownerExports.length - withExamples.length,
+      undocumentedExports: undocumented.map((e) => e.name)
+    });
+  }
+  return {
+    codeownersPath: codeowners.filePath,
+    byOwner,
+    unowned,
+    totalExports: exports.length
+  };
+}
+function analyzeSpecOwnership(spec, options) {
+  const codeowners = loadCodeOwners(options.baseDir);
+  if (!codeowners)
+    return null;
+  return analyzeOwnership(spec, codeowners, options.baseDir);
+}
+// src/contributors/index.ts
+import { execSync } from "node:child_process";
+import * as path7 from "node:path";
+function parseBlameOutput(output) {
+  const results = [];
+  const lines = output.split(`
+`);
+  let currentCommit = "";
+  let currentAuthor = "";
+  let currentEmail = "";
+  let currentTime = 0;
+  let lineNumber = 0;
+  for (const line of lines) {
+    if (line.match(/^[0-9a-f]{40}/)) {
+      const parts = line.split(" ");
+      currentCommit = parts[0];
+      lineNumber = parseInt(parts[2], 10);
+    } else if (line.startsWith("author ")) {
+      currentAuthor = line.slice(7);
+    } else if (line.startsWith("author-mail ")) {
+      currentEmail = line.slice(12).replace(/[<>]/g, "");
+    } else if (line.startsWith("author-time ")) {
+      currentTime = parseInt(line.slice(12), 10);
+    } else if (line.startsWith("\t")) {
+      results.push({
+        commit: currentCommit,
+        author: currentAuthor,
+        email: currentEmail,
+        line: lineNumber,
+        timestamp: currentTime
+      });
+    }
+  }
+  return results;
+}
+function getFileBlame(filePath, cwd) {
+  try {
+    const relativePath = path7.isAbsolute(filePath) ? path7.relative(cwd, filePath) : filePath;
+    const output = execSync(`git blame --porcelain "${relativePath}"`, {
+      cwd,
+      encoding: "utf-8",
+      maxBuffer: 10 * 1024 * 1024,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    return parseBlameOutput(output);
+  } catch {
+    return null;
+  }
+}
+function getBlameForLines(filePath, startLine, endLine, cwd) {
+  try {
+    const relativePath = path7.isAbsolute(filePath) ? path7.relative(cwd, filePath) : filePath;
+    const output = execSync(`git blame --porcelain -L ${startLine},${endLine} "${relativePath}"`, {
+      cwd,
+      encoding: "utf-8",
+      maxBuffer: 10 * 1024 * 1024,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    return parseBlameOutput(output);
+  } catch {
+    return null;
+  }
+}
+function findPrimaryAuthor(blameLines) {
+  if (blameLines.length === 0)
+    return null;
+  const authorCounts = new Map;
+  for (const line of blameLines) {
+    const key = line.email;
+    const existing = authorCounts.get(key);
+    if (existing) {
+      existing.count++;
+      if (line.timestamp > existing.info.timestamp) {
+        existing.info = line;
+      }
+    } else {
+      authorCounts.set(key, { count: 1, info: line });
+    }
+  }
+  let maxCount = 0;
+  let primaryAuthor = null;
+  for (const { count, info } of authorCounts.values()) {
+    if (count > maxCount) {
+      maxCount = count;
+      primaryAuthor = info;
+    }
+  }
+  return primaryAuthor;
+}
+function analyzeContributors(spec, baseDir) {
+  const exports = spec.exports ?? [];
+  const byContributor = new Map;
+  const unattributed = [];
+  let totalDocumented = 0;
+  const fileBlameCache = new Map;
+  for (const exp of exports) {
+    if (!exp.description)
+      continue;
+    const filePath = exp.source?.file;
+    const line = exp.source?.line;
+    if (!filePath || !line) {
+      unattributed.push(exp.name);
+      continue;
+    }
+    let fileBlame = fileBlameCache.get(filePath);
+    if (fileBlame === undefined) {
+      fileBlame = getFileBlame(filePath, baseDir);
+      fileBlameCache.set(filePath, fileBlame);
+    }
+    if (!fileBlame) {
+      unattributed.push(exp.name);
+      continue;
+    }
+    const jsDocStartLine = Math.max(1, line - 20);
+    const declarationLine = line;
+    const jsDocBlame = fileBlame.filter((b) => b.line >= jsDocStartLine && b.line < declarationLine);
+    const primaryAuthor = findPrimaryAuthor(jsDocBlame);
+    if (!primaryAuthor) {
+      const declBlame = fileBlame.find((b) => b.line === declarationLine);
+      if (declBlame) {
+        attributeToContributor(byContributor, declBlame, exp.name, 1);
+        totalDocumented++;
+      } else {
+        unattributed.push(exp.name);
+      }
+      continue;
+    }
+    const linesAuthored = jsDocBlame.filter((b) => b.email === primaryAuthor.email).length;
+    attributeToContributor(byContributor, primaryAuthor, exp.name, linesAuthored);
+    totalDocumented++;
+  }
+  return {
+    byContributor,
+    totalDocumented,
+    unattributed
+  };
+}
+function attributeToContributor(byContributor, blame, exportName, lines) {
+  const key = blame.email;
+  const existing = byContributor.get(key);
+  if (existing) {
+    existing.documentedExports++;
+    existing.exports.push(exportName);
+    existing.linesAuthored += lines;
+    const blameDate = new Date(blame.timestamp * 1000);
+    if (!existing.lastContribution || blameDate > existing.lastContribution) {
+      existing.lastContribution = blameDate;
+    }
+  } else {
+    byContributor.set(key, {
+      name: blame.author,
+      email: blame.email,
+      documentedExports: 1,
+      exports: [exportName],
+      linesAuthored: lines,
+      lastContribution: new Date(blame.timestamp * 1000)
+    });
+  }
+}
+function analyzeSpecContributors(spec, options) {
+  try {
+    execSync("git rev-parse --git-dir", {
+      cwd: options.baseDir,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+  } catch {
+    return null;
+  }
+  return analyzeContributors(spec, options.baseDir);
 }
 // src/config/types.ts
 function defineConfig(config) {
   return config;
 }
 // src/detect/utils.ts
-async function safeParseJson(fs5, path5) {
+async function safeParseJson(fs8, path8) {
   try {
-    if (!await fs5.exists(path5))
+    if (!await fs8.exists(path8))
       return null;
-    const content = await fs5.readFile(path5);
+    const content = await fs8.readFile(path8);
     return JSON.parse(content);
   } catch {
     return null;
   }
 }
-async function readPackageJson(fs5, dir) {
-  const path5 = dir === "." ? "package.json" : `${dir}/package.json`;
-  return safeParseJson(fs5, path5);
+async function readPackageJson(fs8, dir) {
+  const path8 = dir === "." ? "package.json" : `${dir}/package.json`;
+  return safeParseJson(fs8, path8);
 }
 
 // src/detect/build.ts
@@ -2637,8 +3697,8 @@ var BUILD_TOOL_PATTERNS = [
   "babel",
   "ncc build"
 ];
-async function detectBuildInfo(fs5, packagePath = ".") {
-  const pkgJson = await readPackageJson(fs5, packagePath);
+async function detectBuildInfo(fs8, packagePath = ".") {
+  const pkgJson = await readPackageJson(fs8, packagePath);
   const scripts = pkgJson?.scripts ?? {};
   const scriptNames = Object.keys(scripts);
   const buildScriptsByName = scriptNames.filter((name) => BUILD_SCRIPT_NAMES.has(name) || BUILD_SCRIPT_PREFIXES.some((prefix) => name.startsWith(prefix)));
@@ -2650,10 +3710,10 @@ async function detectBuildInfo(fs5, packagePath = ".") {
   });
   const buildScripts = [...new Set([...buildScriptsByName, ...buildScriptsByContent])];
   const tsconfigPath = packagePath === "." ? "tsconfig.json" : `${packagePath}/tsconfig.json`;
-  const hasTsConfig = await fs5.exists(tsconfigPath);
+  const hasTsConfig = await fs8.exists(tsconfigPath);
   const hasTsDep = pkgJson?.devDependencies?.typescript !== undefined || pkgJson?.dependencies?.typescript !== undefined;
   const hasTypeScript = hasTsConfig || hasTsDep;
-  const wasm = await detectWasmProject(fs5, packagePath, pkgJson);
+  const wasm = await detectWasmProject(fs8, packagePath, pkgJson);
   const napi = detectNapiProject(pkgJson);
   return {
     scripts: buildScripts,
@@ -2670,11 +3730,11 @@ var WASM_PACKAGES = new Set([
   "wasm-bindgen",
   "@aspect/aspect-cli"
 ]);
-async function detectWasmProject(fs5, packagePath, pkgJson) {
+async function detectWasmProject(fs8, packagePath, pkgJson) {
   const pkgCargoPath = packagePath === "." ? "Cargo.toml" : `${packagePath}/Cargo.toml`;
-  if (await fs5.exists(pkgCargoPath))
+  if (await fs8.exists(pkgCargoPath))
     return true;
-  if (packagePath !== "." && await fs5.exists("Cargo.toml"))
+  if (packagePath !== "." && await fs8.exists("Cargo.toml"))
     return true;
   if (pkgJson) {
     const deps = Object.keys({
@@ -2715,15 +3775,15 @@ function getPrimaryBuildScript(buildInfo) {
   return buildInfo.scripts[0] ?? null;
 }
 // src/detect/entry-point.ts
-async function detectEntryPoint(fs5, packagePath = ".") {
-  const pkgJson = await readPackageJson(fs5, packagePath);
+async function detectEntryPoint(fs8, packagePath = ".") {
+  const pkgJson = await readPackageJson(fs8, packagePath);
   if (!pkgJson) {
     throw new Error("No package.json found - not a valid npm package");
   }
-  const tsConfig = await parseTsConfig(fs5, packagePath);
+  const tsConfig = await parseTsConfig(fs8, packagePath);
   const typesField = pkgJson.types || pkgJson.typings;
   if (typesField && typeof typesField === "string") {
-    const resolved = await resolveToSource(fs5, packagePath, typesField, tsConfig);
+    const resolved = await resolveToSource(fs8, packagePath, typesField, tsConfig);
     if (resolved) {
       return { ...resolved, source: "types" };
     }
@@ -2733,7 +3793,7 @@ async function detectEntryPoint(fs5, packagePath = ".") {
     if (dotExport && typeof dotExport === "object" && "types" in dotExport) {
       const typesPath = dotExport.types;
       if (typesPath && typeof typesPath === "string") {
-        const resolved = await resolveToSource(fs5, packagePath, typesPath, tsConfig);
+        const resolved = await resolveToSource(fs8, packagePath, typesPath, tsConfig);
         if (resolved) {
           return { ...resolved, source: "exports" };
         }
@@ -2741,13 +3801,13 @@ async function detectEntryPoint(fs5, packagePath = ".") {
     }
   }
   if (pkgJson.main && typeof pkgJson.main === "string") {
-    const resolved = await resolveToSource(fs5, packagePath, pkgJson.main, tsConfig);
+    const resolved = await resolveToSource(fs8, packagePath, pkgJson.main, tsConfig);
     if (resolved) {
       return { ...resolved, source: "main" };
     }
   }
   if (pkgJson.module && typeof pkgJson.module === "string") {
-    const resolved = await resolveToSource(fs5, packagePath, pkgJson.module, tsConfig);
+    const resolved = await resolveToSource(fs8, packagePath, pkgJson.module, tsConfig);
     if (resolved) {
       return { ...resolved, source: "module" };
     }
@@ -2765,27 +3825,27 @@ async function detectEntryPoint(fs5, packagePath = ".") {
   ];
   for (const fallback of fallbacks) {
     const checkPath = packagePath === "." ? fallback : `${packagePath}/${fallback}`;
-    if (await fs5.exists(checkPath)) {
+    if (await fs8.exists(checkPath)) {
       return { path: fallback, source: "fallback", isDeclarationOnly: false };
     }
   }
   throw new Error("Could not detect TypeScript entry point. No types field in package.json and no common entry paths found.");
 }
-async function parseTsConfig(fs5, packagePath) {
+async function parseTsConfig(fs8, packagePath) {
   const tsconfigPath = packagePath === "." ? "tsconfig.json" : `${packagePath}/tsconfig.json`;
-  const tsconfig = await safeParseJson(fs5, tsconfigPath);
+  const tsconfig = await safeParseJson(fs8, tsconfigPath);
   if (!tsconfig?.compilerOptions) {
     return null;
   }
   const { outDir, rootDir, baseUrl, paths } = tsconfig.compilerOptions;
   return { outDir, rootDir, baseUrl, paths };
 }
-async function resolveToSource(fs5, basePath, filePath, tsConfig) {
+async function resolveToSource(fs8, basePath, filePath, tsConfig) {
   const normalized = filePath.replace(/^\.\//, "");
   const checkPath = (p) => basePath === "." ? p : `${basePath}/${p}`;
   const isSourceTs = normalized.endsWith(".ts") && !normalized.endsWith(".d.ts") || normalized.endsWith(".tsx");
   if (isSourceTs) {
-    if (await fs5.exists(checkPath(normalized))) {
+    if (await fs8.exists(checkPath(normalized))) {
       return { path: normalized, isDeclarationOnly: false };
     }
   }
@@ -2827,19 +3887,19 @@ async function resolveToSource(fs5, basePath, filePath, tsConfig) {
   for (const candidate of candidates) {
     if (candidate.endsWith(".d.ts"))
       continue;
-    if (await fs5.exists(checkPath(candidate))) {
+    if (await fs8.exists(checkPath(candidate))) {
       return { path: candidate, isDeclarationOnly: false };
     }
   }
   if (normalized.endsWith(".d.ts")) {
-    if (await fs5.exists(checkPath(normalized))) {
+    if (await fs8.exists(checkPath(normalized))) {
       return { path: normalized, isDeclarationOnly: true };
     }
   }
   return null;
 }
 // src/detect/filesystem.ts
-import * as fs5 from "node:fs";
+import * as fs8 from "node:fs";
 import * as nodePath from "node:path";
 import { Writable } from "node:stream";
 
@@ -2852,19 +3912,19 @@ class NodeFileSystem {
     return nodePath.join(this.basePath, relativePath);
   }
   async exists(relativePath) {
-    return fs5.existsSync(this.resolve(relativePath));
+    return fs8.existsSync(this.resolve(relativePath));
   }
   async readFile(relativePath) {
-    return fs5.readFileSync(this.resolve(relativePath), "utf-8");
+    return fs8.readFileSync(this.resolve(relativePath), "utf-8");
   }
   async readDir(relativePath) {
-    return fs5.readdirSync(this.resolve(relativePath));
+    return fs8.readdirSync(this.resolve(relativePath));
   }
   async isDirectory(relativePath) {
     const fullPath = this.resolve(relativePath);
-    if (!fs5.existsSync(fullPath))
+    if (!fs8.existsSync(fullPath))
       return false;
-    return fs5.statSync(fullPath).isDirectory();
+    return fs8.statSync(fullPath).isDirectory();
   }
 }
 function createCaptureStream() {
@@ -2880,9 +3940,9 @@ function createCaptureStream() {
 
 class FileNotFoundError extends Error {
   path;
-  constructor(path5, message) {
-    super(message ?? `File not found: ${path5}`);
-    this.path = path5;
+  constructor(path8, message) {
+    super(message ?? `File not found: ${path8}`);
+    this.path = path8;
     this.name = "FileNotFoundError";
   }
 }
@@ -2892,34 +3952,34 @@ class SandboxFileSystem {
   constructor(sandbox) {
     this.sandbox = sandbox;
   }
-  async exists(path5) {
+  async exists(path8) {
     const result = await this.sandbox.runCommand({
       cmd: "test",
-      args: ["-e", path5]
+      args: ["-e", path8]
     });
     return result.exitCode === 0;
   }
-  async readFile(path5) {
-    const exists = await this.exists(path5);
+  async readFile(path8) {
+    const exists = await this.exists(path8);
     if (!exists) {
-      throw new FileNotFoundError(path5);
+      throw new FileNotFoundError(path8);
     }
     const capture = createCaptureStream();
     const result = await this.sandbox.runCommand({
       cmd: "cat",
-      args: [path5],
+      args: [path8],
       stdout: capture.stream
     });
     if (result.exitCode !== 0) {
-      throw new FileNotFoundError(path5, `Failed to read file: ${path5}`);
+      throw new FileNotFoundError(path8, `Failed to read file: ${path8}`);
     }
     return capture.getOutput();
   }
-  async readDir(path5) {
+  async readDir(path8) {
     const capture = createCaptureStream();
     const result = await this.sandbox.runCommand({
       cmd: "ls",
-      args: ["-1", path5],
+      args: ["-1", path8],
       stdout: capture.stream
     });
     if (result.exitCode !== 0) {
@@ -2928,20 +3988,20 @@ class SandboxFileSystem {
     return capture.getOutput().split(`
 `).filter(Boolean);
   }
-  async isDirectory(path5) {
+  async isDirectory(path8) {
     const result = await this.sandbox.runCommand({
       cmd: "test",
-      args: ["-d", path5]
+      args: ["-d", path8]
     });
     return result.exitCode === 0;
   }
 }
 // src/detect/monorepo.ts
-async function detectMonorepo(fs6) {
-  const pkgJson = await readPackageJson(fs6, ".");
+async function detectMonorepo(fs9) {
+  const pkgJson = await readPackageJson(fs9, ".");
   if (pkgJson?.workspaces) {
     const patterns = extractWorkspacePatterns(pkgJson.workspaces);
-    const packages = await resolveWorkspacePackages(fs6, patterns, pkgJson.name, pkgJson.private);
+    const packages = await resolveWorkspacePackages(fs9, patterns, pkgJson.name, pkgJson.private);
     return {
       isMonorepo: packages.length > 0,
       type: "npm-workspaces",
@@ -2949,10 +4009,10 @@ async function detectMonorepo(fs6) {
       packages
     };
   }
-  if (await fs6.exists("pnpm-workspace.yaml")) {
-    const content = await fs6.readFile("pnpm-workspace.yaml");
+  if (await fs9.exists("pnpm-workspace.yaml")) {
+    const content = await fs9.readFile("pnpm-workspace.yaml");
     const patterns = parsePnpmWorkspace(content);
-    const packages = await resolveWorkspacePackages(fs6, patterns, pkgJson?.name, pkgJson?.private);
+    const packages = await resolveWorkspacePackages(fs9, patterns, pkgJson?.name, pkgJson?.private);
     return {
       isMonorepo: packages.length > 0,
       type: "pnpm-workspaces",
@@ -2960,10 +4020,10 @@ async function detectMonorepo(fs6) {
       packages
     };
   }
-  if (await fs6.exists("lerna.json")) {
-    const lerna = await safeParseJson(fs6, "lerna.json");
+  if (await fs9.exists("lerna.json")) {
+    const lerna = await safeParseJson(fs9, "lerna.json");
     const patterns = lerna?.packages ?? ["packages/*"];
-    const packages = await resolveWorkspacePackages(fs6, patterns, pkgJson?.name, pkgJson?.private);
+    const packages = await resolveWorkspacePackages(fs9, patterns, pkgJson?.name, pkgJson?.private);
     return {
       isMonorepo: packages.length > 0,
       type: "lerna",
@@ -3037,7 +4097,7 @@ function parsePnpmWorkspace(content) {
   }
   return patterns.length > 0 ? patterns : ["packages/*"];
 }
-async function resolveWorkspacePackages(fs6, patterns, rootPackageName, rootIsPrivate) {
+async function resolveWorkspacePackages(fs9, patterns, rootPackageName, rootIsPrivate) {
   const packages = [];
   const seen = new Set;
   if (rootPackageName && !rootIsPrivate && rootPackageName !== "root") {
@@ -3059,18 +4119,18 @@ async function resolveWorkspacePackages(fs6, patterns, rootPackageName, rootIsPr
   }
   dirsToScan.add("packages");
   for (const dir of dirsToScan) {
-    if (!await fs6.exists(dir))
+    if (!await fs9.exists(dir))
       continue;
-    if (!await fs6.isDirectory(dir))
+    if (!await fs9.isDirectory(dir))
       continue;
-    const subdirs = await fs6.readDir(dir);
+    const subdirs = await fs9.readDir(dir);
     for (const subdir of subdirs) {
       const pkgPath = `${dir}/${subdir}`;
       const pkgJsonPath = `${pkgPath}/package.json`;
-      if (!await fs6.exists(pkgJsonPath))
+      if (!await fs9.exists(pkgJsonPath))
         continue;
       try {
-        const content = await fs6.readFile(pkgJsonPath);
+        const content = await fs9.readFile(pkgJsonPath);
         const pkg = JSON.parse(content);
         if (pkg.name && !seen.has(pkg.name)) {
           seen.add(pkg.name);
@@ -3142,14 +4202,14 @@ var DEFAULT_PM = {
   installArgs: ["install", "--legacy-peer-deps"],
   runPrefix: ["npm", "run"]
 };
-async function detectPackageManager(fs6) {
-  const pkgJson = await safeParseJson(fs6, "package.json");
+async function detectPackageManager(fs9) {
+  const pkgJson = await safeParseJson(fs9, "package.json");
   if (pkgJson?.packageManager) {
     const pmName = parsePackageManagerField(pkgJson.packageManager);
     if (pmName && PM_CONFIGS[pmName]) {
       const config = PM_CONFIGS[pmName];
       for (const lockfile of config.lockfiles) {
-        if (await fs6.exists(lockfile)) {
+        if (await fs9.exists(lockfile)) {
           return { ...config.info, lockfile };
         }
       }
@@ -3159,7 +4219,7 @@ async function detectPackageManager(fs6) {
   const foundLockfiles = [];
   for (const [pmName, config] of Object.entries(PM_CONFIGS)) {
     for (const lockfile of config.lockfiles) {
-      if (await fs6.exists(lockfile)) {
+      if (await fs9.exists(lockfile)) {
         foundLockfiles.push({ lockfile, pm: pmName });
       }
     }
@@ -3191,10 +4251,10 @@ function getRunCommand(pm, script) {
   return [...pm.runPrefix, script];
 }
 // src/detect/index.ts
-async function analyzeProject(fs6, options = {}) {
+async function analyzeProject(fs9, options = {}) {
   const [packageManager, monorepo] = await Promise.all([
-    detectPackageManager(fs6),
-    detectMonorepo(fs6)
+    detectPackageManager(fs9),
+    detectMonorepo(fs9)
   ]);
   let targetPath = ".";
   if (monorepo.isMonorepo) {
@@ -3211,8 +4271,8 @@ async function analyzeProject(fs6, options = {}) {
     targetPath = pkg.path;
   }
   const [entryPoint, build] = await Promise.all([
-    detectEntryPoint(fs6, targetPath),
-    detectBuildInfo(fs6, targetPath)
+    detectEntryPoint(fs9, targetPath),
+    detectBuildInfo(fs9, targetPath)
   ]);
   return { packageManager, monorepo, entryPoint, build };
 }
@@ -3256,17 +4316,17 @@ function shouldValidate(validations, check) {
   return validations.includes(check);
 }
 // src/typecheck/example-typechecker.ts
-import * as fs6 from "node:fs";
-import * as path5 from "node:path";
+import * as fs9 from "node:fs";
+import * as path8 from "node:path";
 import ts3 from "typescript";
 function stripCodeBlockMarkers(code) {
   return code.replace(/^```(?:ts|typescript|js|javascript)?\n?/i, "").replace(/\n?```$/i, "").trim();
 }
 function getPackageName(packagePath) {
-  const pkgJsonPath = path5.join(packagePath, "package.json");
-  if (fs6.existsSync(pkgJsonPath)) {
+  const pkgJsonPath = path8.join(packagePath, "package.json");
+  if (fs9.existsSync(pkgJsonPath)) {
     try {
-      const pkgJson = JSON.parse(fs6.readFileSync(pkgJsonPath, "utf-8"));
+      const pkgJson = JSON.parse(fs9.readFileSync(pkgJsonPath, "utf-8"));
       return pkgJson.name;
     } catch {
       return;
@@ -3276,12 +4336,12 @@ function getPackageName(packagePath) {
 }
 function findTsConfig(packagePath) {
   let dir = packagePath;
-  while (dir !== path5.dirname(dir)) {
-    const tsConfigPath = path5.join(dir, "tsconfig.json");
-    if (fs6.existsSync(tsConfigPath)) {
+  while (dir !== path8.dirname(dir)) {
+    const tsConfigPath = path8.join(dir, "tsconfig.json");
+    if (fs9.existsSync(tsConfigPath)) {
       return tsConfigPath;
     }
-    dir = path5.dirname(dir);
+    dir = path8.dirname(dir);
   }
   return;
 }
@@ -3297,10 +4357,10 @@ function createVirtualSource(example, packageName, exportNames) {
 `);
 }
 function getCompilerOptions(tsconfigPath) {
-  if (tsconfigPath && fs6.existsSync(tsconfigPath)) {
+  if (tsconfigPath && fs9.existsSync(tsconfigPath)) {
     const configFile = ts3.readConfigFile(tsconfigPath, ts3.sys.readFile);
     if (!configFile.error) {
-      const parsed = ts3.parseJsonConfigFileContent(configFile.config, ts3.sys, path5.dirname(tsconfigPath));
+      const parsed = ts3.parseJsonConfigFileContent(configFile.config, ts3.sys, path8.dirname(tsconfigPath));
       return {
         ...parsed.options,
         noEmit: true,
@@ -3326,7 +4386,7 @@ function typecheckExample(example, packagePath, options = {}) {
   const tsconfigPath = options.tsconfig ?? findTsConfig(packagePath);
   const compilerOptions = getCompilerOptions(tsconfigPath);
   const virtualSource = createVirtualSource(cleanCode, packageName, exportNames);
-  const virtualFileName = path5.join(packagePath, "__doccov_example__.ts");
+  const virtualFileName = path8.join(packagePath, "__doccov_example__.ts");
   const hasImport = packageName !== undefined && exportNames && exportNames.length > 0;
   const lineOffset = hasImport ? 2 : 0;
   const sourceFile = ts3.createSourceFile(virtualFileName, virtualSource, ts3.ScriptTarget.ES2022, true);
@@ -3398,20 +4458,20 @@ function typecheckExamples(examples, packagePath, options = {}) {
 
 // src/utils/example-runner.ts
 import { spawn } from "node:child_process";
-import * as fs7 from "node:fs";
+import * as fs10 from "node:fs";
 import * as os from "node:os";
-import * as path6 from "node:path";
+import * as path9 from "node:path";
 function stripCodeBlockMarkers2(code) {
   return code.replace(/^```(?:ts|typescript|js|javascript)?\n?/i, "").replace(/\n?```$/i, "").trim();
 }
 async function runExample(code, options = {}) {
   const { timeout = 5000, cwd = process.cwd() } = options;
   const cleanCode = stripCodeBlockMarkers2(code);
-  const tmpFile = path6.join(cwd, `doccov-example-${Date.now()}-${Math.random().toString(36).slice(2)}.ts`);
+  const tmpFile = path9.join(cwd, `doccov-example-${Date.now()}-${Math.random().toString(36).slice(2)}.ts`);
   try {
-    fs7.writeFileSync(tmpFile, cleanCode, "utf-8");
+    fs10.writeFileSync(tmpFile, cleanCode, "utf-8");
     const startTime = Date.now();
-    return await new Promise((resolve4) => {
+    return await new Promise((resolve5) => {
       let stdout = "";
       let stderr = "";
       let killed = false;
@@ -3434,7 +4494,7 @@ async function runExample(code, options = {}) {
         clearTimeout(timeoutId);
         const duration = Date.now() - startTime;
         if (killed) {
-          resolve4({
+          resolve5({
             success: false,
             stdout,
             stderr: stderr || `Example timed out after ${timeout}ms`,
@@ -3442,7 +4502,7 @@ async function runExample(code, options = {}) {
             duration
           });
         } else {
-          resolve4({
+          resolve5({
             success: exitCode === 0,
             stdout,
             stderr,
@@ -3453,7 +4513,7 @@ async function runExample(code, options = {}) {
       });
       proc.on("error", (error) => {
         clearTimeout(timeoutId);
-        resolve4({
+        resolve5({
           success: false,
           stdout,
           stderr: error.message,
@@ -3464,7 +4524,7 @@ async function runExample(code, options = {}) {
     });
   } finally {
     try {
-      fs7.unlinkSync(tmpFile);
+      fs10.unlinkSync(tmpFile);
     } catch {}
   }
 }
@@ -3479,15 +4539,15 @@ async function runExamples(examples, options = {}) {
   return results;
 }
 function detectPackageManager2(cwd) {
-  if (fs7.existsSync(path6.join(cwd, "bun.lockb")))
+  if (fs10.existsSync(path9.join(cwd, "bun.lockb")))
     return "bun";
-  if (fs7.existsSync(path6.join(cwd, "bun.lock")))
+  if (fs10.existsSync(path9.join(cwd, "bun.lock")))
     return "bun";
-  if (fs7.existsSync(path6.join(cwd, "pnpm-lock.yaml")))
+  if (fs10.existsSync(path9.join(cwd, "pnpm-lock.yaml")))
     return "pnpm";
-  if (fs7.existsSync(path6.join(cwd, "yarn.lock")))
+  if (fs10.existsSync(path9.join(cwd, "yarn.lock")))
     return "yarn";
-  if (fs7.existsSync(path6.join(cwd, "package-lock.json")))
+  if (fs10.existsSync(path9.join(cwd, "package-lock.json")))
     return "npm";
   return "npm";
 }
@@ -3504,7 +4564,7 @@ function getInstallCommand2(pm, packagePath) {
   }
 }
 async function runCommand(cmd, args, options) {
-  return new Promise((resolve4) => {
+  return new Promise((resolve5) => {
     let stdout = "";
     let stderr = "";
     let killed = false;
@@ -3525,14 +4585,14 @@ async function runCommand(cmd, args, options) {
     proc.on("close", (exitCode) => {
       clearTimeout(timeoutId);
       if (killed) {
-        resolve4({
+        resolve5({
           success: false,
           stdout,
           stderr: stderr || `Command timed out after ${options.timeout}ms`,
           exitCode: exitCode ?? 1
         });
       } else {
-        resolve4({
+        resolve5({
           success: exitCode === 0,
           stdout,
           stderr,
@@ -3542,7 +4602,7 @@ async function runCommand(cmd, args, options) {
     });
     proc.on("error", (error) => {
       clearTimeout(timeoutId);
-      resolve4({
+      resolve5({
         success: false,
         stdout,
         stderr: error.message,
@@ -3555,12 +4615,12 @@ async function runExamplesWithPackage(examples, options) {
   const { packagePath, packageManager, installTimeout = 60000, timeout = 5000 } = options;
   const startTime = Date.now();
   const results = new Map;
-  const absolutePackagePath = path6.resolve(packagePath);
-  const workDir = path6.join(os.tmpdir(), `doccov-examples-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  const absolutePackagePath = path9.resolve(packagePath);
+  const workDir = path9.join(os.tmpdir(), `doccov-examples-${Date.now()}-${Math.random().toString(36).slice(2)}`);
   try {
-    fs7.mkdirSync(workDir, { recursive: true });
+    fs10.mkdirSync(workDir, { recursive: true });
     const pkgJson = { name: "doccov-example-runner", type: "module" };
-    fs7.writeFileSync(path6.join(workDir, "package.json"), JSON.stringify(pkgJson, null, 2));
+    fs10.writeFileSync(path9.join(workDir, "package.json"), JSON.stringify(pkgJson, null, 2));
     const pm = packageManager ?? detectPackageManager2(options.cwd ?? process.cwd());
     const { cmd, args } = getInstallCommand2(pm, absolutePackagePath);
     const installResult = await runCommand(cmd, args, {
@@ -3588,7 +4648,7 @@ async function runExamplesWithPackage(examples, options) {
     };
   } finally {
     try {
-      fs7.rmSync(workDir, { recursive: true, force: true });
+      fs10.rmSync(workDir, { recursive: true, force: true });
     } catch {}
   }
 }
@@ -3768,8 +4828,8 @@ async function validateExamples(exports, options) {
   return result;
 }
 // src/analysis/run-analysis.ts
-import * as fs9 from "node:fs";
-import * as path10 from "node:path";
+import * as fs12 from "node:fs";
+import * as path13 from "node:path";
 // src/utils/type-utils.ts
 function getTypeId(type, typeChecker) {
   const internalId = type.id;
@@ -3892,7 +4952,7 @@ function collectReferencedTypesFromNode(node, typeChecker, referencedTypes) {
 }
 
 // src/analysis/context.ts
-import * as path8 from "node:path";
+import * as path11 from "node:path";
 
 // src/options.ts
 var DEFAULT_MAX_TYPE_DEPTH = 20;
@@ -3913,7 +4973,7 @@ function normalizeDocCovOptions(options = {}) {
 }
 
 // src/analysis/program.ts
-import * as path7 from "node:path";
+import * as path10 from "node:path";
 var DEFAULT_COMPILER_OPTIONS = {
   target: ts.ScriptTarget.Latest,
   module: ts.ModuleKind.CommonJS,
@@ -3923,14 +4983,14 @@ var DEFAULT_COMPILER_OPTIONS = {
 };
 function createProgram({
   entryFile,
-  baseDir = path7.dirname(entryFile),
+  baseDir = path10.dirname(entryFile),
   content
 }) {
   const configPath = ts.findConfigFile(baseDir, ts.sys.fileExists, "tsconfig.json");
   let compilerOptions = { ...DEFAULT_COMPILER_OPTIONS };
   if (configPath) {
     const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
-    const parsedConfig = ts.parseJsonConfigFileContent(configFile.config, ts.sys, path7.dirname(configPath));
+    const parsedConfig = ts.parseJsonConfigFileContent(configFile.config, ts.sys, path10.dirname(configPath));
     compilerOptions = { ...compilerOptions, ...parsedConfig.options };
   }
   const allowJsVal = compilerOptions.allowJs;
@@ -3965,9 +5025,10 @@ function createAnalysisContext({
   entryFile,
   packageDir,
   content,
-  options
+  options,
+  detectedSchemas
 }) {
-  const baseDir = packageDir ?? path8.dirname(entryFile);
+  const baseDir = packageDir ?? path11.dirname(entryFile);
   const normalizedOptions = normalizeDocCovOptions(options);
   const programResult = createProgram({ entryFile, baseDir, content });
   if (!programResult.sourceFile) {
@@ -3982,13 +5043,14 @@ function createAnalysisContext({
     compilerOptions: programResult.compilerOptions,
     compilerHost: programResult.compilerHost,
     options: normalizedOptions,
-    configPath: programResult.configPath
+    configPath: programResult.configPath,
+    detectedSchemas
   };
 }
 
 // src/analysis/spec-builder.ts
-import * as fs8 from "node:fs";
-import * as path9 from "node:path";
+import * as fs11 from "node:fs";
+import * as path12 from "node:path";
 import { SCHEMA_URL, SCHEMA_VERSION } from "@openpkg-ts/spec";
 
 // src/analysis/decorator-utils.ts
@@ -4020,291 +5082,37 @@ function extractParameterDecorators(param) {
   return extractDecorators(param);
 }
 
-// src/utils/typebox-handler.ts
-var TYPEBOX_PRIMITIVE_MAP = {
-  TString: { type: "string" },
-  TNumber: { type: "number" },
-  TBoolean: { type: "boolean" },
-  TInteger: { type: "integer" },
-  TNull: { type: "null" },
-  TAny: {},
-  TUnknown: {},
-  TNever: { not: {} },
-  TVoid: { type: "null" },
-  TUndefined: { type: "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 isTypeBoxSchemaType(symbolName) {
-  return /^T[A-Z][a-zA-Z]*$/.test(symbolName);
-}
-function isInternalProperty(name) {
-  return name.startsWith("__@");
-}
-function isTypeBoxOptionalMarker(type) {
-  const props = type.getProperties();
-  if (props.length !== 1)
+function isObjectLiteralType(type) {
+  if (!(type.getFlags() & ts.TypeFlags.Object)) {
     return false;
-  return isInternalProperty(props[0].getName());
-}
-function unwrapTypeBoxOptional(type) {
-  if (!type.isIntersection()) {
-    return { innerTypes: [type], isOptional: false };
   }
-  const intersectionType = type;
-  const filtered = intersectionType.types.filter((t) => !isTypeBoxOptionalMarker(t));
-  const hadMarker = filtered.length < intersectionType.types.length;
-  return { innerTypes: filtered, isOptional: hadMarker };
-}
-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" };
-  }
-  const symbol = type.getSymbol();
-  if (!symbol)
-    return null;
-  const symbolName = symbol.getName();
-  if (TYPEBOX_PRIMITIVE_MAP[symbolName]) {
-    return { ...TYPEBOX_PRIMITIVE_MAP[symbolName] };
-  }
-  const objectType = type;
-  if (!(objectType.objectFlags & ts.ObjectFlags.Reference)) {
-    return null;
-  }
-  const typeRef = type;
-  const typeArgs = typeRef.typeArguments;
-  switch (symbolName) {
-    case "TObject": {
-      if (!typeArgs || typeArgs.length === 0) {
-        return { type: "object" };
-      }
-      const propsType = typeArgs[0];
-      const properties = {};
-      const required = [];
-      for (const prop of propsType.getProperties()) {
-        const propName = prop.getName();
-        if (isInternalProperty(propName)) {
-          continue;
-        }
-        const propType = getPropertyType(prop, propsType, typeChecker);
-        const propSymbol = propType.getSymbol();
-        const propSymbolName = propSymbol?.getName();
-        if (propSymbolName && typeRefs.has(propSymbolName)) {
-          properties[propName] = { $ref: `#/types/${propSymbolName}` };
-        } else if (propSymbolName && isTypeBoxSchemaType(propSymbolName)) {
-          const nested = formatTypeBoxSchema(propType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds);
-          properties[propName] = nested ?? { type: "object" };
-        } else {
-          properties[propName] = formatTypeReferenceInternal(propType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds);
-        }
-        const { isOptional } = unwrapTypeBoxOptional(propType);
-        if (propSymbolName !== "TOptional" && !isOptional) {
-          required.push(propName);
-        }
-      }
-      const schema = { type: "object", properties };
-      if (required.length > 0) {
-        schema.required = required;
-      }
-      return schema;
-    }
-    case "TArray": {
-      if (!typeArgs || typeArgs.length === 0) {
-        return { type: "array" };
-      }
-      const itemType = typeArgs[0];
-      const itemSymbol = itemType.getSymbol();
-      const itemSymbolName = itemSymbol?.getName();
-      let items;
-      if (itemSymbolName && typeRefs.has(itemSymbolName)) {
-        items = { $ref: `#/types/${itemSymbolName}` };
-      } else if (itemSymbolName && isTypeBoxSchemaType(itemSymbolName)) {
-        items = formatTypeBoxSchema(itemType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds) ?? {
-          type: "object"
-        };
-      } else {
-        items = formatTypeReferenceInternal(itemType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds);
-      }
-      return { type: "array", items };
-    }
-    case "TUnion": {
-      if (!typeArgs || typeArgs.length === 0) {
-        return { anyOf: [] };
-      }
-      const tupleType = typeArgs[0];
-      const members = [];
-      if (tupleType.isUnion()) {
-        for (const memberType of tupleType.types) {
-          const memberSymbol = memberType.getSymbol();
-          const memberSymbolName = memberSymbol?.getName();
-          if (memberSymbolName && typeRefs.has(memberSymbolName)) {
-            members.push({ $ref: `#/types/${memberSymbolName}` });
-          } else if (memberSymbolName && isTypeBoxSchemaType(memberSymbolName)) {
-            members.push(formatTypeBoxSchema(memberType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds) ?? {
-              type: "object"
-            });
-          } else {
-            members.push(formatTypeReferenceInternal(memberType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds));
-          }
-        }
-      } else if (tupleType.typeArguments) {
-        for (const memberType of tupleType.typeArguments) {
-          const memberSymbol = memberType.getSymbol();
-          const memberSymbolName = memberSymbol?.getName();
-          if (memberSymbolName && typeRefs.has(memberSymbolName)) {
-            members.push({ $ref: `#/types/${memberSymbolName}` });
-          } else if (memberSymbolName && isTypeBoxSchemaType(memberSymbolName)) {
-            members.push(formatTypeBoxSchema(memberType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds) ?? {
-              type: "object"
-            });
-          } else {
-            members.push(formatTypeReferenceInternal(memberType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds));
-          }
-        }
-      }
-      return { anyOf: members };
-    }
-    case "TIntersect": {
-      if (!typeArgs || typeArgs.length === 0) {
-        return { allOf: [] };
-      }
-      const tupleType = typeArgs[0];
-      const members = [];
-      if (tupleType.typeArguments) {
-        for (const memberType of tupleType.typeArguments) {
-          const memberSymbol = memberType.getSymbol();
-          const memberSymbolName = memberSymbol?.getName();
-          if (memberSymbolName && typeRefs.has(memberSymbolName)) {
-            members.push({ $ref: `#/types/${memberSymbolName}` });
-          } else if (memberSymbolName && isTypeBoxSchemaType(memberSymbolName)) {
-            members.push(formatTypeBoxSchema(memberType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds) ?? {
-              type: "object"
-            });
-          } else {
-            members.push(formatTypeReferenceInternal(memberType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds));
-          }
-        }
-      }
-      return { allOf: members };
-    }
-    case "TOptional": {
-      if (!typeArgs || typeArgs.length === 0) {
-        return {};
-      }
-      const innerType = typeArgs[0];
-      const innerSymbol = innerType.getSymbol();
-      const innerSymbolName = innerSymbol?.getName();
-      if (innerSymbolName && typeRefs.has(innerSymbolName)) {
-        return { $ref: `#/types/${innerSymbolName}` };
-      } else if (innerSymbolName && isTypeBoxSchemaType(innerSymbolName)) {
-        return formatTypeBoxSchema(innerType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds) ?? {
-          type: "object"
-        };
-      }
-      return formatTypeReferenceInternal(innerType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds);
-    }
-    case "TLiteral": {
-      if (!typeArgs || typeArgs.length === 0) {
-        return { enum: [] };
-      }
-      const literalType = typeArgs[0];
-      if (literalType.isLiteral()) {
-        const value = literalType.value;
-        return { enum: [value] };
-      }
-      const literalStr = typeChecker.typeToString(literalType);
-      if (literalStr.startsWith('"') && literalStr.endsWith('"')) {
-        return { enum: [literalStr.slice(1, -1)] };
-      }
-      return { enum: [literalStr] };
-    }
-    case "TRecord": {
-      if (!typeArgs || typeArgs.length < 2) {
-        return { type: "object", additionalProperties: true };
-      }
-      const valueType = typeArgs[1];
-      const valueSymbol = valueType.getSymbol();
-      const valueSymbolName = valueSymbol?.getName();
-      let additionalProperties;
-      if (valueSymbolName && typeRefs.has(valueSymbolName)) {
-        additionalProperties = { $ref: `#/types/${valueSymbolName}` };
-      } else if (valueSymbolName && isTypeBoxSchemaType(valueSymbolName)) {
-        additionalProperties = formatTypeBoxSchema(valueType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds) ?? true;
-      } else {
-        additionalProperties = formatTypeReferenceInternal(valueType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds);
-      }
-      return { type: "object", additionalProperties };
-    }
-    case "TRef": {
-      if (!typeArgs || typeArgs.length === 0) {
-        return { $ref: "#/types/unknown" };
-      }
-      const refType = typeArgs[0];
-      const refSymbol = refType.getSymbol();
-      const refSymbolName = refSymbol?.getName();
-      if (refSymbolName) {
-        return { $ref: `#/types/${refSymbolName}` };
-      }
-      return { type: "object" };
-    }
-    default:
-      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() & ts.TypeFlags.Object)) {
-    return false;
-  }
-  const objectFlags = type.objectFlags;
-  return (objectFlags & ts.ObjectFlags.ObjectLiteral) !== 0;
+  const objectFlags = type.objectFlags;
+  return (objectFlags & ts.ObjectFlags.ObjectLiteral) !== 0;
 }
 function isPureRefSchema(value) {
   return Object.keys(value).length === 1 && "$ref" in value;
@@ -4357,9 +5165,9 @@ function propertiesToSchema(properties, description) {
   }
   return schema;
 }
-var _formatTypeReference2 = null;
+var _formatTypeReference = null;
 function setSchemaBuilderFormatTypeReference(fn) {
-  _formatTypeReference2 = fn;
+  _formatTypeReference = fn;
 }
 function buildSchemaFromTypeNode(node, typeChecker, typeRefs, referencedTypes, functionDoc, parentParamName) {
   if (ts.isParenthesizedTypeNode(node)) {
@@ -4390,7 +5198,7 @@ function buildSchemaFromTypeNode(node, typeChecker, typeRefs, referencedTypes, f
       let schema2 = "any";
       if (member.type) {
         const memberType = typeChecker.getTypeFromTypeNode(member.type);
-        const formatted = _formatTypeReference2 ? _formatTypeReference2(memberType, typeChecker, typeRefs, referencedTypes) : { type: "any" };
+        const formatted = _formatTypeReference ? _formatTypeReference(memberType, typeChecker, typeRefs, referencedTypes) : { type: "any" };
         if (typeof formatted === "string") {
           if (formatted === "any") {
             schema2 = buildSchemaFromTypeNode(member.type, typeChecker, typeRefs, referencedTypes, functionDoc, parentParamName);
@@ -4522,54 +5330,307 @@ function findDiscriminatorProperty(unionTypes, typeChecker) {
         isDiscriminator = false;
         break;
       }
-      values.add(value);
+      values.add(value);
+    }
+    if (isDiscriminator) {
+      return propName;
+    }
+  }
+  return;
+}
+function schemaIsAny(schema) {
+  if (typeof schema === "string") {
+    return schema === "any";
+  }
+  if ("type" in schema && schema.type === "any" && Object.keys(schema).length === 1) {
+    return true;
+  }
+  return false;
+}
+function schemasAreEqual(left, right) {
+  if (typeof left !== typeof right) {
+    return false;
+  }
+  if (typeof left === "string" && typeof right === "string") {
+    return left === right;
+  }
+  if (left == null || right == null) {
+    return left === right;
+  }
+  const normalize = (value) => {
+    if (Array.isArray(value)) {
+      return value.map((item) => normalize(item));
+    }
+    if (value && typeof value === "object") {
+      const sortedEntries = Object.entries(value).map(([key, val]) => [key, normalize(val)]).sort(([keyA], [keyB]) => keyA.localeCompare(keyB));
+      return Object.fromEntries(sortedEntries);
+    }
+    return value;
+  };
+  return JSON.stringify(normalize(left)) === JSON.stringify(normalize(right));
+}
+function deduplicateSchemas(schemas) {
+  const result = [];
+  for (const schema of schemas) {
+    const isDuplicate = result.some((existing) => schemasAreEqual(existing, schema));
+    if (!isDuplicate) {
+      result.push(schema);
+    }
+  }
+  return result;
+}
+// src/utils/typebox-handler.ts
+var TYPEBOX_PRIMITIVE_MAP = {
+  TString: { type: "string" },
+  TNumber: { type: "number" },
+  TBoolean: { type: "boolean" },
+  TInteger: { type: "integer" },
+  TNull: { type: "null" },
+  TAny: {},
+  TUnknown: {},
+  TNever: { not: {} },
+  TVoid: { type: "null" },
+  TUndefined: { type: "null" }
+};
+function isTypeBoxSchemaType(symbolName) {
+  return /^T[A-Z][a-zA-Z]*$/.test(symbolName);
+}
+function isInternalProperty(name) {
+  return name.startsWith("__@");
+}
+function isTypeBoxOptionalMarker(type) {
+  const props = type.getProperties();
+  if (props.length !== 1)
+    return false;
+  return isInternalProperty(props[0].getName());
+}
+function unwrapTypeBoxOptional(type) {
+  if (!type.isIntersection()) {
+    return { innerTypes: [type], isOptional: false };
+  }
+  const intersectionType = type;
+  const filtered = intersectionType.types.filter((t) => !isTypeBoxOptionalMarker(t));
+  const hadMarker = filtered.length < intersectionType.types.length;
+  return { innerTypes: filtered, isOptional: hadMarker };
+}
+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 _formatTypeReference2 = null;
+function setFormatTypeReference(fn) {
+  _formatTypeReference2 = fn;
+}
+function formatTypeReferenceInternal(type, typeChecker, typeRefs, referencedTypes, visited, depth, maxDepth, typeIds) {
+  if (_formatTypeReference2) {
+    return _formatTypeReference2(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" };
+  }
+  const symbol = type.getSymbol();
+  if (!symbol)
+    return null;
+  const symbolName = symbol.getName();
+  if (TYPEBOX_PRIMITIVE_MAP[symbolName]) {
+    return { ...TYPEBOX_PRIMITIVE_MAP[symbolName] };
+  }
+  const objectType = type;
+  if (!(objectType.objectFlags & ts.ObjectFlags.Reference)) {
+    return null;
+  }
+  const typeRef = type;
+  const typeArgs = typeRef.typeArguments;
+  switch (symbolName) {
+    case "TObject": {
+      if (!typeArgs || typeArgs.length === 0) {
+        return { type: "object" };
+      }
+      const propsType = typeArgs[0];
+      const properties = {};
+      const required = [];
+      for (const prop of propsType.getProperties()) {
+        const propName = prop.getName();
+        if (isInternalProperty(propName)) {
+          continue;
+        }
+        const propType = getPropertyType(prop, propsType, typeChecker);
+        const propSymbol = propType.getSymbol();
+        const propSymbolName = propSymbol?.getName();
+        if (propSymbolName && typeRefs.has(propSymbolName)) {
+          properties[propName] = { $ref: `#/types/${propSymbolName}` };
+        } else if (propSymbolName && isTypeBoxSchemaType(propSymbolName)) {
+          const nested = formatTypeBoxSchema(propType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds);
+          properties[propName] = nested ?? { type: "object" };
+        } else {
+          properties[propName] = formatTypeReferenceInternal(propType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds);
+        }
+        const { isOptional } = unwrapTypeBoxOptional(propType);
+        if (propSymbolName !== "TOptional" && !isOptional) {
+          required.push(propName);
+        }
+      }
+      const schema = { type: "object", properties };
+      if (required.length > 0) {
+        schema.required = required;
+      }
+      return schema;
+    }
+    case "TArray": {
+      if (!typeArgs || typeArgs.length === 0) {
+        return { type: "array" };
+      }
+      const itemType = typeArgs[0];
+      const itemSymbol = itemType.getSymbol();
+      const itemSymbolName = itemSymbol?.getName();
+      let items;
+      if (itemSymbolName && typeRefs.has(itemSymbolName)) {
+        items = { $ref: `#/types/${itemSymbolName}` };
+      } else if (itemSymbolName && isTypeBoxSchemaType(itemSymbolName)) {
+        items = formatTypeBoxSchema(itemType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds) ?? {
+          type: "object"
+        };
+      } else {
+        items = formatTypeReferenceInternal(itemType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds);
+      }
+      return { type: "array", items };
+    }
+    case "TUnion": {
+      if (!typeArgs || typeArgs.length === 0) {
+        return { anyOf: [] };
+      }
+      const tupleType = typeArgs[0];
+      const members = [];
+      if (tupleType.isUnion()) {
+        for (const memberType of tupleType.types) {
+          const memberSymbol = memberType.getSymbol();
+          const memberSymbolName = memberSymbol?.getName();
+          if (memberSymbolName && typeRefs.has(memberSymbolName)) {
+            members.push({ $ref: `#/types/${memberSymbolName}` });
+          } else if (memberSymbolName && isTypeBoxSchemaType(memberSymbolName)) {
+            members.push(formatTypeBoxSchema(memberType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds) ?? {
+              type: "object"
+            });
+          } else {
+            members.push(formatTypeReferenceInternal(memberType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds));
+          }
+        }
+      } else if (tupleType.typeArguments) {
+        for (const memberType of tupleType.typeArguments) {
+          const memberSymbol = memberType.getSymbol();
+          const memberSymbolName = memberSymbol?.getName();
+          if (memberSymbolName && typeRefs.has(memberSymbolName)) {
+            members.push({ $ref: `#/types/${memberSymbolName}` });
+          } else if (memberSymbolName && isTypeBoxSchemaType(memberSymbolName)) {
+            members.push(formatTypeBoxSchema(memberType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds) ?? {
+              type: "object"
+            });
+          } else {
+            members.push(formatTypeReferenceInternal(memberType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds));
+          }
+        }
+      }
+      return { anyOf: members };
+    }
+    case "TIntersect": {
+      if (!typeArgs || typeArgs.length === 0) {
+        return { allOf: [] };
+      }
+      const tupleType = typeArgs[0];
+      const members = [];
+      if (tupleType.typeArguments) {
+        for (const memberType of tupleType.typeArguments) {
+          const memberSymbol = memberType.getSymbol();
+          const memberSymbolName = memberSymbol?.getName();
+          if (memberSymbolName && typeRefs.has(memberSymbolName)) {
+            members.push({ $ref: `#/types/${memberSymbolName}` });
+          } else if (memberSymbolName && isTypeBoxSchemaType(memberSymbolName)) {
+            members.push(formatTypeBoxSchema(memberType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds) ?? {
+              type: "object"
+            });
+          } else {
+            members.push(formatTypeReferenceInternal(memberType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds));
+          }
+        }
+      }
+      return { allOf: members };
     }
-    if (isDiscriminator) {
-      return propName;
+    case "TOptional": {
+      if (!typeArgs || typeArgs.length === 0) {
+        return {};
+      }
+      const innerType = typeArgs[0];
+      const innerSymbol = innerType.getSymbol();
+      const innerSymbolName = innerSymbol?.getName();
+      if (innerSymbolName && typeRefs.has(innerSymbolName)) {
+        return { $ref: `#/types/${innerSymbolName}` };
+      } else if (innerSymbolName && isTypeBoxSchemaType(innerSymbolName)) {
+        return formatTypeBoxSchema(innerType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds) ?? {
+          type: "object"
+        };
+      }
+      return formatTypeReferenceInternal(innerType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds);
     }
-  }
-  return;
-}
-function schemaIsAny(schema) {
-  if (typeof schema === "string") {
-    return schema === "any";
-  }
-  if ("type" in schema && schema.type === "any" && Object.keys(schema).length === 1) {
-    return true;
-  }
-  return false;
-}
-function schemasAreEqual(left, right) {
-  if (typeof left !== typeof right) {
-    return false;
-  }
-  if (typeof left === "string" && typeof right === "string") {
-    return left === right;
-  }
-  if (left == null || right == null) {
-    return left === right;
-  }
-  const normalize = (value) => {
-    if (Array.isArray(value)) {
-      return value.map((item) => normalize(item));
+    case "TLiteral": {
+      if (!typeArgs || typeArgs.length === 0) {
+        return { enum: [] };
+      }
+      const literalType = typeArgs[0];
+      if (literalType.isLiteral()) {
+        const value = literalType.value;
+        return { enum: [value] };
+      }
+      const literalStr = typeChecker.typeToString(literalType);
+      if (literalStr.startsWith('"') && literalStr.endsWith('"')) {
+        return { enum: [literalStr.slice(1, -1)] };
+      }
+      return { enum: [literalStr] };
     }
-    if (value && typeof value === "object") {
-      const sortedEntries = Object.entries(value).map(([key, val]) => [key, normalize(val)]).sort(([keyA], [keyB]) => keyA.localeCompare(keyB));
-      return Object.fromEntries(sortedEntries);
+    case "TRecord": {
+      if (!typeArgs || typeArgs.length < 2) {
+        return { type: "object", additionalProperties: true };
+      }
+      const valueType = typeArgs[1];
+      const valueSymbol = valueType.getSymbol();
+      const valueSymbolName = valueSymbol?.getName();
+      let additionalProperties;
+      if (valueSymbolName && typeRefs.has(valueSymbolName)) {
+        additionalProperties = { $ref: `#/types/${valueSymbolName}` };
+      } else if (valueSymbolName && isTypeBoxSchemaType(valueSymbolName)) {
+        additionalProperties = formatTypeBoxSchema(valueType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds) ?? true;
+      } else {
+        additionalProperties = formatTypeReferenceInternal(valueType, typeChecker, typeRefs, referencedTypes, visited, depth + 1, maxDepth, typeIds);
+      }
+      return { type: "object", additionalProperties };
     }
-    return value;
-  };
-  return JSON.stringify(normalize(left)) === JSON.stringify(normalize(right));
-}
-function deduplicateSchemas(schemas) {
-  const result = [];
-  for (const schema of schemas) {
-    const isDuplicate = result.some((existing) => schemasAreEqual(existing, schema));
-    if (!isDuplicate) {
-      result.push(schema);
+    case "TRef": {
+      if (!typeArgs || typeArgs.length === 0) {
+        return { $ref: "#/types/unknown" };
+      }
+      const refType = typeArgs[0];
+      const refSymbol = refType.getSymbol();
+      const refSymbolName = refSymbol?.getName();
+      if (refSymbolName) {
+        return { $ref: `#/types/${refSymbolName}` };
+      }
+      return { type: "object" };
     }
+    default:
+      return null;
   }
-  return result;
 }
 
 // src/utils/type-formatter.ts
@@ -5679,10 +6740,10 @@ function serializeClassMembers(declaration, checker, typeRefs, referencedTypes)
       if (member.questionToken || isOptionalSymbol) {
         flags.optional = true;
       }
-      if (member.modifiers?.some((mod) => mod.kind === ts.SyntaxKind.ReadonlyKeyword)) {
+      if (member.modifiers?.some((mod2) => mod2.kind === ts.SyntaxKind.ReadonlyKeyword)) {
         flags.readonly = true;
       }
-      if (member.modifiers?.some((mod) => mod.kind === ts.SyntaxKind.StaticKeyword)) {
+      if (member.modifiers?.some((mod2) => mod2.kind === ts.SyntaxKind.StaticKeyword)) {
         flags.static = true;
       }
       members.push({
@@ -5804,20 +6865,20 @@ function serializeSignature(signature, checker, typeRefs, referencedTypes, doc,
 function getMemberVisibility(modifiers) {
   if (!modifiers)
     return;
-  if (modifiers.some((mod) => mod.kind === ts.SyntaxKind.PrivateKeyword)) {
+  if (modifiers.some((mod2) => mod2.kind === ts.SyntaxKind.PrivateKeyword)) {
     return "private";
   }
-  if (modifiers.some((mod) => mod.kind === ts.SyntaxKind.ProtectedKeyword)) {
+  if (modifiers.some((mod2) => mod2.kind === ts.SyntaxKind.ProtectedKeyword)) {
     return "protected";
   }
-  if (modifiers.some((mod) => mod.kind === ts.SyntaxKind.PublicKeyword)) {
+  if (modifiers.some((mod2) => mod2.kind === ts.SyntaxKind.PublicKeyword)) {
     return "public";
   }
   return;
 }
 function getMethodFlags(member) {
   const flags = {};
-  if (member.modifiers?.some((mod) => mod.kind === ts.SyntaxKind.StaticKeyword)) {
+  if (member.modifiers?.some((mod2) => mod2.kind === ts.SyntaxKind.StaticKeyword)) {
     flags.static = true;
   }
   if (member.asteriskToken) {
@@ -6002,7 +7063,7 @@ function serializeInterfaceMembers(declaration, checker, typeRefs, referencedTyp
       if (member.questionToken) {
         flags.optional = true;
       }
-      if (member.modifiers?.some((mod) => mod.kind === ts.SyntaxKind.ReadonlyKeyword)) {
+      if (member.modifiers?.some((mod2) => mod2.kind === ts.SyntaxKind.ReadonlyKeyword)) {
         flags.readonly = true;
       }
       members.push({
@@ -6300,7 +7361,7 @@ function extractNamespaceMembers(declaration, checker) {
     return members;
   }
   for (const statement of body.statements) {
-    const hasExportModifier = ts.canHaveModifiers(statement) && ts.getModifiers(statement)?.some((mod) => mod.kind === ts.SyntaxKind.ExportKeyword);
+    const hasExportModifier = ts.canHaveModifiers(statement) && ts.getModifiers(statement)?.some((mod2) => mod2.kind === ts.SyntaxKind.ExportKeyword);
     if (!hasExportModifier) {
       continue;
     }
@@ -6509,6 +7570,25 @@ function serializeVariable(declaration, symbol, context) {
   }
   const typeRefs = typeRegistry.getTypeRefs();
   const referencedTypes = typeRegistry.getReferencedTypes();
+  const symbolName = symbol.getName();
+  const detectedSchema = context.detectedSchemas?.get(symbolName);
+  if (detectedSchema) {
+    return {
+      id: symbolName,
+      name: symbolName,
+      ...metadata,
+      kind: "variable",
+      deprecated: isSymbolDeprecated(symbol),
+      schema: detectedSchema.schema,
+      description,
+      source: getSourceLocation(declaration),
+      tags: [
+        ...parsedDoc?.tags ?? [],
+        { name: "standardSchema", text: detectedSchema.vendor }
+      ],
+      examples: parsedDoc?.examples
+    };
+  }
   return {
     id: symbol.getName(),
     name: symbol.getName(),
@@ -6597,9 +7677,9 @@ function createDefaultGenerationInfo(entryFile) {
 }
 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 packageJsonPath = path12.join(baseDir, "package.json");
+  const packageJson = fs11.existsSync(packageJsonPath) ? JSON.parse(fs11.readFileSync(packageJsonPath, "utf-8")) : {};
+  const generationInfo = generation ?? createDefaultGenerationInfo(path12.relative(baseDir, entryFile));
   const spec = {
     $schema: SCHEMA_URL,
     openpkg: SCHEMA_VERSION,
@@ -6619,7 +7699,8 @@ function buildOpenPkgSpec(context, resolveExternalTypes, generation) {
   const serializerContext = {
     checker: typeChecker,
     typeRegistry,
-    maxTypeDepth: context.options.maxDepth
+    maxTypeDepth: context.options.maxDepth,
+    detectedSchemas: context.detectedSchemas
   };
   const moduleSymbol = typeChecker.getSymbolAtLocation(sourceFile);
   if (!moduleSymbol) {
@@ -6797,11 +7878,11 @@ function deriveImportPath(sourceFile, baseDir) {
   if (!sourceFile) {
     return;
   }
-  const relative4 = path9.relative(baseDir, sourceFile);
-  if (!relative4 || relative4.startsWith("..")) {
+  const relative6 = path12.relative(baseDir, sourceFile);
+  if (!relative6 || relative6.startsWith("..")) {
     return;
   }
-  const normalized = relative4.replace(/\\/g, "/");
+  const normalized = relative6.replace(/\\/g, "/");
   const withoutExt = stripExtensions(normalized);
   if (!withoutExt) {
     return;
@@ -6840,11 +7921,11 @@ function withExportName(entry, exportName) {
 function findNearestPackageJson(startDir) {
   let current = startDir;
   while (true) {
-    const candidate = path10.join(current, "package.json");
-    if (fs9.existsSync(candidate)) {
+    const candidate = path13.join(current, "package.json");
+    if (fs12.existsSync(candidate)) {
       return candidate;
     }
-    const parent = path10.dirname(current);
+    const parent = path13.dirname(current);
     if (parent === current) {
       return;
     }
@@ -6872,11 +7953,11 @@ function canResolveExternalModules(program, baseDir) {
 function hasNodeModulesDirectoryFallback(startDir) {
   let current = startDir;
   while (true) {
-    const candidate = path10.join(current, "node_modules");
-    if (fs9.existsSync(candidate)) {
+    const candidate = path13.join(current, "node_modules");
+    if (fs12.existsSync(candidate)) {
       return true;
     }
-    const parent = path10.dirname(current);
+    const parent = path13.dirname(current);
     if (parent === current) {
       break;
     }
@@ -6921,8 +8002,8 @@ function hasExternalImports(sourceFile) {
     if (ts.isImportDeclaration(node) && node.moduleSpecifier) {
       const specifier = node.moduleSpecifier;
       if (ts.isStringLiteral(specifier)) {
-        const modulePath = specifier.text;
-        if (!modulePath.startsWith(".") && !modulePath.startsWith("/")) {
+        const modulePath2 = specifier.text;
+        if (!modulePath2.startsWith(".") && !modulePath2.startsWith("/")) {
           found = true;
         }
       }
@@ -6977,6 +8058,17 @@ function runAnalysis(input, generationInput) {
     issues: generationIssues
   } : undefined;
   const spec = buildOpenPkgSpec(context, resolveExternalTypes, generation);
+  if (input.detectedSchemas && input.detectedSchemas.size > 0 && generation) {
+    const vendors = new Set;
+    for (const entry of input.detectedSchemas.values()) {
+      vendors.add(entry.vendor);
+    }
+    generation.analysis.schemaExtraction = {
+      method: "hybrid",
+      runtimeCount: input.detectedSchemas.size,
+      vendors: Array.from(vendors)
+    };
+  }
   const danglingRefs = collectDanglingRefs(spec);
   for (const ref of danglingRefs) {
     const issue = {
@@ -7118,16 +8210,33 @@ async function fetchSpecFromGitHub(parsed) {
   }
   return null;
 }
-async function fetchSpec(owner, repo, branch = "main") {
-  return fetchSpecFromGitHub({ owner, repo, ref: branch });
+async function fetchSpec(owner, repo, branchOrOptions = "main") {
+  const options = typeof branchOrOptions === "string" ? { ref: branchOrOptions, path: "openpkg.json" } : { ref: branchOrOptions.ref ?? "main", path: branchOrOptions.path ?? "openpkg.json" };
+  const parsed = { owner, repo, ref: options.ref };
+  return fetchSpecFromGitHubWithPath(parsed, options.path);
+}
+async function fetchSpecFromGitHubWithPath(parsed, specPath = "openpkg.json") {
+  const urls = [
+    buildRawUrl(parsed, specPath),
+    `https://raw.githubusercontent.com/${parsed.owner}/${parsed.repo}/master/${specPath}`
+  ];
+  for (const url of urls) {
+    try {
+      const response = await fetch(url);
+      if (response.ok) {
+        return await response.json();
+      }
+    } catch {}
+  }
+  return null;
 }
 // src/install/index.ts
 var DEFAULT_FALLBACK_ORDER = ["bun", "npm"];
-async function installDependencies(fs10, cwd, runCommand2, options = {}) {
+async function installDependencies(fs13, 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(fs10);
+  const pmInfo = await detectPackageManager(fs13);
   if (pmInfo.lockfile) {
     onProgress?.({
       stage: "installing",
@@ -7202,10 +8311,10 @@ function getFallbackInstallCommand(pm) {
 }
 function createNodeCommandRunner() {
   return async (cmd, args, options) => {
-    const { execSync } = await import("node:child_process");
+    const { execSync: execSync2 } = await import("node:child_process");
     const fullCmd = [cmd, ...args].join(" ");
     try {
-      const stdout = execSync(fullCmd, {
+      const stdout = execSync2(fullCmd, {
         cwd: options.cwd,
         stdio: "pipe",
         timeout: options.timeout ?? 180000
@@ -7782,7 +8891,7 @@ function diffMemberChanges(oldSpec, newSpec, changedClassNames) {
           memberName,
           memberKind: getMemberKind(newMember),
           changeType: "added",
-          newSignature: formatSignature(newMember)
+          newSignature: formatSignature2(newMember)
         });
       }
     }
@@ -7794,7 +8903,7 @@ function diffMemberChanges(oldSpec, newSpec, changedClassNames) {
           memberName,
           memberKind: getMemberKind(oldMember),
           changeType: "removed",
-          oldSignature: formatSignature(oldMember),
+          oldSignature: formatSignature2(oldMember),
           suggestion
         });
       }
@@ -7807,8 +8916,8 @@ function diffMemberChanges(oldSpec, newSpec, changedClassNames) {
           memberName,
           memberKind: getMemberKind(newMember),
           changeType: "signature-changed",
-          oldSignature: formatSignature(oldMember),
-          newSignature: formatSignature(newMember)
+          oldSignature: formatSignature2(oldMember),
+          newSignature: formatSignature2(newMember)
         });
       }
     }
@@ -7857,7 +8966,7 @@ function getMemberKind(member) {
       return "method";
   }
 }
-function formatSignature(member) {
+function formatSignature2(member) {
   if (!member.signatures?.length) {
     return member.name ?? "";
   }
@@ -8032,11 +9141,34 @@ function getDocsImpactSummary(diff) {
 }
 // src/openpkg.ts
 import * as fsSync from "node:fs";
-import * as fs10 from "node:fs/promises";
-import * as path11 from "node:path";
+import * as fs13 from "node:fs/promises";
+import * as path14 from "node:path";
 
 // src/filtering/apply-filters.ts
 var TYPE_REF_PREFIX = "#/types/";
+var getExportReleaseTag = (exp) => {
+  const tags = exp.tags ?? [];
+  for (const tag of tags) {
+    const tagName = tag.name?.toLowerCase();
+    if (tagName === "public")
+      return "public";
+    if (tagName === "beta")
+      return "beta";
+    if (tagName === "alpha")
+      return "alpha";
+    if (tagName === "internal")
+      return "internal";
+  }
+  return;
+};
+var matchesVisibility = (exp, visibility) => {
+  if (!visibility || visibility.length === 0) {
+    return true;
+  }
+  const tag = getExportReleaseTag(exp);
+  const effectiveTag = tag ?? "public";
+  return visibility.includes(effectiveTag);
+};
 var toLowerKey = (value) => value.trim().toLowerCase();
 var buildLookupMap = (values) => {
   const map = new Map;
@@ -8098,7 +9230,8 @@ var collectTypeRefs = (value, refs, seen = new Set) => {
 var applyFilters = (spec, options) => {
   const includeLookup = buildLookupMap(options.include);
   const excludeLookup = buildLookupMap(options.exclude);
-  if (includeLookup.size === 0 && excludeLookup.size === 0) {
+  const visibility = options.visibility;
+  if (includeLookup.size === 0 && excludeLookup.size === 0 && (!visibility || visibility.length === 0)) {
     return { spec, diagnostics: [], changed: false };
   }
   const includeMatches = new Set;
@@ -8111,10 +9244,11 @@ var applyFilters = (spec, options) => {
     const excludeMatch = matches(entry, excludeLookup);
     const allowedByInclude = includeLookup.size === 0 || Boolean(includeMatch);
     const allowedByExclude = !excludeMatch;
+    const allowedByVisibility = matchesVisibility(entry, visibility);
     if (includeMatch) {
       includeMatches.add(includeMatch);
     }
-    if (allowedByInclude && allowedByExclude) {
+    if (allowedByInclude && allowedByExclude && allowedByVisibility) {
       keptExports.push(entry);
     }
   }
@@ -8216,14 +9350,14 @@ class DocCov {
     this.options = normalizeDocCovOptions(options);
   }
   async analyze(code, fileName = "temp.ts", analyzeOptions = {}) {
-    const resolvedFileName = path11.resolve(fileName);
-    const tempDir = path11.dirname(resolvedFileName);
+    const resolvedFileName = path14.resolve(fileName);
+    const tempDir = path14.dirname(resolvedFileName);
     const spec = await extractPackageSpec(resolvedFileName, tempDir, code, this.options);
     return this.applySpecFilters(spec, analyzeOptions.filters).spec;
   }
   async analyzeFile(filePath, analyzeOptions = {}) {
-    const resolvedPath = path11.resolve(filePath);
-    const content = await fs10.readFile(resolvedPath, "utf-8");
+    const resolvedPath = path14.resolve(filePath);
+    const content = await fs13.readFile(resolvedPath, "utf-8");
     const packageDir = resolvePackageDir(resolvedPath);
     const spec = await extractPackageSpec(resolvedPath, packageDir, content, this.options);
     return this.applySpecFilters(spec, analyzeOptions.filters).spec;
@@ -8232,13 +9366,16 @@ class DocCov {
     return this.analyzeFile(entryPath, analyzeOptions);
   }
   async analyzeWithDiagnostics(code, fileName, analyzeOptions = {}) {
-    const resolvedFileName = path11.resolve(fileName ?? "temp.ts");
+    const resolvedFileName = path14.resolve(fileName ?? "temp.ts");
     const packageDir = resolvePackageDir(resolvedFileName);
+    const isRealFile = fileName && !fileName.includes("temp.ts");
+    const detectedSchemas = isRealFile ? await this.detectSchemas(resolvedFileName, packageDir) : undefined;
     const analysis = runAnalysis({
       entryFile: resolvedFileName,
       packageDir,
       content: code,
-      options: this.options
+      options: this.options,
+      detectedSchemas
     }, analyzeOptions.generationInput);
     const filterOutcome = this.applySpecFilters(analysis.spec, analyzeOptions.filters);
     return {
@@ -8252,7 +9389,7 @@ class DocCov {
     };
   }
   async analyzeFileWithDiagnostics(filePath, analyzeOptions = {}) {
-    const resolvedPath = path11.resolve(filePath);
+    const resolvedPath = path14.resolve(filePath);
     const packageDir = resolvePackageDir(resolvedPath);
     const { useCache, resolveExternalTypes } = this.options;
     if (useCache) {
@@ -8268,12 +9405,14 @@ class DocCov {
         };
       }
     }
-    const content = await fs10.readFile(resolvedPath, "utf-8");
+    const content = await fs13.readFile(resolvedPath, "utf-8");
+    const detectedSchemas = await this.detectSchemas(resolvedPath, packageDir);
     const analysis = runAnalysis({
       entryFile: resolvedPath,
       packageDir,
       content,
-      options: this.options
+      options: this.options,
+      detectedSchemas
     }, analyzeOptions.generationInput);
     const filterOutcome = this.applySpecFilters(analysis.spec, analyzeOptions.filters);
     const metadata = this.normalizeMetadata(analysis.metadata);
@@ -8303,10 +9442,10 @@ class DocCov {
     if (!packageJsonPath) {
       return null;
     }
-    const sourceFiles = Object.keys(cache.hashes.sourceFiles).map((relativePath) => path11.resolve(cwd, relativePath));
+    const currentSourceFiles = this.getCurrentSourceFiles(entryFile, packageDir);
     const cacheContext = {
       entryFile,
-      sourceFiles,
+      sourceFiles: currentSourceFiles,
       tsconfigPath,
       packageJsonPath,
       config: {
@@ -8318,6 +9457,7 @@ class DocCov {
     if (!validation.valid) {
       return null;
     }
+    const cachedSourceFiles = Object.keys(cache.hashes.sourceFiles).map((relativePath) => path14.resolve(cwd, relativePath));
     return {
       spec: cache.spec,
       metadata: {
@@ -8326,10 +9466,18 @@ class DocCov {
         packageJsonPath,
         hasNodeModules: true,
         resolveExternalTypes: cache.config.resolveExternalTypes,
-        sourceFiles
+        sourceFiles: cachedSourceFiles
       }
     };
   }
+  getCurrentSourceFiles(entryFile, baseDir) {
+    try {
+      const { program } = createProgram({ entryFile, baseDir });
+      return program.getSourceFiles().filter((sf) => !sf.isDeclarationFile && sf.fileName.startsWith(baseDir)).map((sf) => sf.fileName);
+    } catch {
+      return [];
+    }
+  }
   saveToCache(result, entryFile, metadata) {
     const { cwd } = this.options;
     if (!metadata.packageJsonPath) {
@@ -8352,11 +9500,11 @@ class DocCov {
   findTsConfig(startDir) {
     let current = startDir;
     while (true) {
-      const candidate = path11.join(current, "tsconfig.json");
+      const candidate = path14.join(current, "tsconfig.json");
       if (fsSync.existsSync(candidate)) {
         return candidate;
       }
-      const parent = path11.dirname(current);
+      const parent = path14.dirname(current);
       if (parent === current) {
         return null;
       }
@@ -8366,17 +9514,38 @@ class DocCov {
   findPackageJson(startDir) {
     let current = startDir;
     while (true) {
-      const candidate = path11.join(current, "package.json");
+      const candidate = path14.join(current, "package.json");
       if (fsSync.existsSync(candidate)) {
         return candidate;
       }
-      const parent = path11.dirname(current);
+      const parent = path14.dirname(current);
       if (parent === current) {
         return null;
       }
       current = parent;
     }
   }
+  async detectSchemas(entryFile, packageDir) {
+    try {
+      const result = await detectRuntimeSchemas({
+        baseDir: packageDir,
+        entryFile
+      });
+      if (result.schemas.size === 0) {
+        return;
+      }
+      const detected = new Map;
+      for (const [name, schema] of result.schemas) {
+        detected.set(name, {
+          schema: schema.schema,
+          vendor: schema.vendor
+        });
+      }
+      return detected;
+    } catch {
+      return;
+    }
+  }
   normalizeDiagnostic(tsDiagnostic) {
     const message = ts.flattenDiagnosticMessageText(tsDiagnostic.messageText, `
 `);
@@ -8438,27 +9607,127 @@ async function analyzeFile(filePath, options = {}) {
   return new DocCov().analyzeFile(filePath, options);
 }
 function resolvePackageDir(entryFile) {
-  const fallbackDir = path11.dirname(entryFile);
+  const fallbackDir = path14.dirname(entryFile);
   let currentDir = fallbackDir;
   while (true) {
-    const candidate = path11.join(currentDir, "package.json");
+    const candidate = path14.join(currentDir, "package.json");
     if (fsSync.existsSync(candidate)) {
       return currentDir;
     }
-    const parentDir = path11.dirname(currentDir);
+    const parentDir = path14.dirname(currentDir);
     if (parentDir === currentDir) {
       return fallbackDir;
     }
     currentDir = parentDir;
   }
 }
+// src/policies/index.ts
+import * as path15 from "node:path";
+import { minimatch as minimatch2 } from "minimatch";
+function matchesPolicy(exp, policy, baseDir) {
+  const filePath = exp.source?.file;
+  if (!filePath)
+    return false;
+  let normalizedPath = filePath;
+  if (baseDir && path15.isAbsolute(filePath)) {
+    normalizedPath = path15.relative(baseDir, filePath);
+  }
+  normalizedPath = normalizedPath.replace(/^\.\//, "");
+  return minimatch2(normalizedPath, policy.path, { matchBase: true });
+}
+function calculateCoverage(exports) {
+  if (exports.length === 0)
+    return 100;
+  let documented = 0;
+  for (const exp of exports) {
+    if (exp.description) {
+      documented++;
+    }
+  }
+  return Math.round(documented / exports.length * 100);
+}
+function calculateDrift(exports) {
+  if (exports.length === 0)
+    return 0;
+  let withDrift = 0;
+  for (const exp of exports) {
+    if (exp.docs?.drift && exp.docs.drift.length > 0) {
+      withDrift++;
+    }
+  }
+  return Math.round(withDrift / exports.length * 100);
+}
+function countMissingExamples(exports) {
+  let missing = 0;
+  for (const exp of exports) {
+    const hasExample = exp.examples && exp.examples.length > 0;
+    if (!hasExample) {
+      missing++;
+    }
+  }
+  return missing;
+}
+function evaluatePolicy(policy, allExports, baseDir) {
+  const matchedExports = allExports.filter((exp) => matchesPolicy(exp, policy, baseDir));
+  const coverageScore = calculateCoverage(matchedExports);
+  const driftScore = calculateDrift(matchedExports);
+  const missingExamples = countMissingExamples(matchedExports);
+  const failures = [];
+  if (policy.minCoverage !== undefined && coverageScore < policy.minCoverage) {
+    failures.push({
+      type: "coverage",
+      message: `Coverage ${coverageScore}% below minimum ${policy.minCoverage}%`,
+      actual: coverageScore,
+      threshold: policy.minCoverage
+    });
+  }
+  if (policy.maxDrift !== undefined && driftScore > policy.maxDrift) {
+    failures.push({
+      type: "drift",
+      message: `Drift ${driftScore}% exceeds maximum ${policy.maxDrift}%`,
+      actual: driftScore,
+      threshold: policy.maxDrift
+    });
+  }
+  if (policy.requireExamples && missingExamples > 0) {
+    failures.push({
+      type: "examples",
+      message: `${missingExamples} exports missing @example`,
+      actual: missingExamples,
+      threshold: 0
+    });
+  }
+  return {
+    policy,
+    matchedExports,
+    coverageScore,
+    driftScore,
+    missingExamples,
+    passed: failures.length === 0,
+    failures
+  };
+}
+function evaluatePolicies(policies, spec, options = {}) {
+  const { baseDir } = options;
+  const exports = spec.exports ?? [];
+  const results = policies.map((policy) => evaluatePolicy(policy, exports, baseDir));
+  const passedCount = results.filter((r) => r.passed).length;
+  const failedCount = results.length - passedCount;
+  return {
+    results,
+    allPassed: failedCount === 0,
+    totalPolicies: policies.length,
+    passedCount,
+    failedCount
+  };
+}
 // src/resolve/index.ts
-import * as path12 from "node:path";
-async function resolveTarget(fs11, options) {
+import * as path16 from "node:path";
+async function resolveTarget(fs14, options) {
   let targetDir = options.cwd;
   let packageInfo;
   if (options.package) {
-    const mono = await detectMonorepo(fs11);
+    const mono = await detectMonorepo(fs14);
     if (!mono.isMonorepo) {
       throw new Error("Not a monorepo. Remove --package flag for single-package repos.");
     }
@@ -8467,21 +9736,21 @@ async function resolveTarget(fs11, options) {
       const available = mono.packages.map((p) => p.name).join(", ");
       throw new Error(`Package "${options.package}" not found. Available: ${available}`);
     }
-    targetDir = path12.join(options.cwd, pkg.path);
+    targetDir = path16.join(options.cwd, pkg.path);
     packageInfo = pkg;
   }
   let entryFile;
   let entryPointInfo;
   if (!options.entry) {
-    entryPointInfo = await detectEntryPoint(fs11, getRelativePath(options.cwd, targetDir));
-    entryFile = path12.join(targetDir, entryPointInfo.path);
+    entryPointInfo = await detectEntryPoint(fs14, getRelativePath(options.cwd, targetDir));
+    entryFile = path16.join(targetDir, entryPointInfo.path);
   } else {
-    const explicitPath = path12.resolve(targetDir, options.entry);
-    const isDirectory = await isDir(fs11, getRelativePath(options.cwd, explicitPath));
+    const explicitPath = path16.resolve(targetDir, options.entry);
+    const isDirectory = await isDir(fs14, getRelativePath(options.cwd, explicitPath));
     if (isDirectory) {
       targetDir = explicitPath;
-      entryPointInfo = await detectEntryPoint(fs11, getRelativePath(options.cwd, explicitPath));
-      entryFile = path12.join(explicitPath, entryPointInfo.path);
+      entryPointInfo = await detectEntryPoint(fs14, getRelativePath(options.cwd, explicitPath));
+      entryFile = path16.join(explicitPath, entryPointInfo.path);
     } else {
       entryFile = explicitPath;
       entryPointInfo = {
@@ -8501,52 +9770,20 @@ async function resolveTarget(fs11, options) {
 function getRelativePath(base, target) {
   if (base === target)
     return ".";
-  const rel = path12.relative(base, target);
+  const rel = path16.relative(base, target);
   return rel || ".";
 }
-async function isDir(fs11, relativePath) {
-  const hasPackageJson = await fs11.exists(path12.join(relativePath, "package.json"));
+async function isDir(fs14, relativePath) {
+  const hasPackageJson = await fs14.exists(path16.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 fs11.exists(path12.join(relativePath, entry))) {
+    if (await fs14.exists(path16.join(relativePath, entry))) {
       return true;
     }
   }
-  return !path12.extname(relativePath);
-}
-// 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
-  };
+  return !path16.extname(relativePath);
 }
 // src/scan/github-context.ts
 function parseGitHubUrl2(url) {
@@ -8557,10 +9794,14 @@ function parseGitHubUrl2(url) {
     return null;
   }
 }
-async function fetchRawFile(owner, repo, ref, path13) {
-  const url = `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${path13}`;
+async function fetchRawFile(owner, repo, ref, path17, authToken) {
+  const url = `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${path17}`;
   try {
-    const response = await fetch(url);
+    const headers = {};
+    if (authToken) {
+      headers.Authorization = `Bearer ${authToken}`;
+    }
+    const response = await fetch(url, { headers });
     if (response.ok) {
       return await response.text();
     }
@@ -8569,14 +9810,16 @@ async function fetchRawFile(owner, repo, ref, path13) {
     return null;
   }
 }
-async function fetchRepoMetadata(owner, repo) {
+async function fetchRepoMetadata(owner, repo, authToken) {
   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"
-    }
-  });
+  const headers = {
+    Accept: "application/vnd.github.v3+json",
+    "User-Agent": "DocCov-Scanner"
+  };
+  if (authToken) {
+    headers.Authorization = `Bearer ${authToken}`;
+  }
+  const response = await fetch(url, { headers });
   if (!response.ok) {
     throw new Error(`Failed to fetch repository: ${response.status} ${response.statusText}`);
   }
@@ -8591,7 +9834,7 @@ async function fetchRepoMetadata(owner, repo) {
     isPrivate: data.private
   };
 }
-async function detectPackageManager3(owner, repo, ref) {
+async function detectPackageManager3(owner, repo, ref, authToken) {
   const lockfiles = [
     { name: "bun.lockb", manager: "bun" },
     { name: "pnpm-lock.yaml", manager: "pnpm" },
@@ -8599,15 +9842,15 @@ async function detectPackageManager3(owner, repo, ref) {
     { name: "package-lock.json", manager: "npm" }
   ];
   for (const { name, manager } of lockfiles) {
-    const content = await fetchRawFile(owner, repo, ref, name);
+    const content = await fetchRawFile(owner, repo, ref, name, authToken);
     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");
+async function detectWorkspace(packageJson, owner, repo, ref, authToken) {
+  const pnpmWorkspace = await fetchRawFile(owner, repo, ref, "pnpm-workspace.yaml", authToken);
   if (pnpmWorkspace) {
     const packagesMatch = pnpmWorkspace.match(/packages:\s*\n((?:\s+-\s+['"]?[^\n]+['"]?\n?)+)/);
     const packages = packagesMatch ? packagesMatch[1].split(`
@@ -8618,7 +9861,7 @@ async function detectWorkspace(packageJson, owner, repo, ref) {
       packages
     };
   }
-  const lernaJson = await fetchRawFile(owner, repo, ref, "lerna.json");
+  const lernaJson = await fetchRawFile(owner, repo, ref, "lerna.json", authToken);
   if (lernaJson) {
     return { isMonorepo: true, tool: "lerna" };
   }
@@ -8678,18 +9921,20 @@ function detectBuildHints(packageJson, tsconfigJson) {
   }
   return hints;
 }
-async function fetchGitHubContext(repoUrl, ref) {
+async function fetchGitHubContext(repoUrl, refOrOptions) {
   const parsed = parseGitHubUrl2(repoUrl);
   if (!parsed) {
     throw new Error(`Invalid GitHub URL: ${repoUrl}`);
   }
+  const options = typeof refOrOptions === "string" ? { ref: refOrOptions } : refOrOptions ?? {};
+  const { authToken } = options;
   const { owner, repo } = parsed;
-  const metadata = await fetchRepoMetadata(owner, repo);
-  const targetRef = ref ?? metadata.defaultBranch;
+  const metadata = await fetchRepoMetadata(owner, repo, authToken);
+  const targetRef = options.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)
+    fetchRawFile(owner, repo, targetRef, "package.json", authToken),
+    fetchRawFile(owner, repo, targetRef, "tsconfig.json", authToken),
+    detectPackageManager3(owner, repo, targetRef, authToken)
   ]);
   let packageJson = null;
   let tsconfigJson = null;
@@ -8703,7 +9948,7 @@ async function fetchGitHubContext(repoUrl, ref) {
       tsconfigJson = JSON.parse(tsconfigJsonRaw);
     } catch {}
   }
-  const workspace = await detectWorkspace(packageJson, owner, repo, targetRef);
+  const workspace = await detectWorkspace(packageJson, owner, repo, targetRef, authToken);
   const buildHints = detectBuildHints(packageJson, tsconfigJson);
   return {
     metadata,
@@ -8718,18 +9963,20 @@ async function fetchGitHubContext(repoUrl, ref) {
     }
   };
 }
-async function listWorkspacePackages(owner, repo, ref, patterns) {
+async function listWorkspacePackages(owner, repo, ref, patterns, authToken) {
   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"
-        }
-      });
+      const headers = {
+        Accept: "application/vnd.github.v3+json",
+        "User-Agent": "DocCov-Scanner"
+      };
+      if (authToken) {
+        headers.Authorization = `Bearer ${authToken}`;
+      }
+      const response = await fetch(url, { headers });
       if (response.ok) {
         const contents = await response.json();
         for (const item of contents) {
@@ -8742,21 +9989,59 @@ async function listWorkspacePackages(owner, repo, ref, patterns) {
   }
   return packages;
 }
+// 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
+  };
+}
 export {
   validateSpecCache,
   validateExamples,
   typecheckExamples,
   typecheckExample,
+  tryExtractStandardSchema,
   shouldValidate,
   serializeJSDoc,
   saveSpecCache,
+  saveSnapshot,
   saveReport,
   safeParseJson,
   runExamplesWithPackage,
   runExamples,
   runExample,
   resolveTarget,
+  renderSparkline,
+  renderApiSurface,
   readPackageJson,
+  pruneHistory,
+  pruneByTier,
   parseGitHubUrl2 as parseScanGitHubUrl,
   parseMarkdownFiles,
   parseMarkdownFile,
@@ -8764,13 +10049,18 @@ export {
   parseJSDocToPatch,
   parseGitHubUrl,
   parseExamplesFlag,
+  parseCodeOwners,
   parseAssertions,
   mergeFixes,
   mergeFilters,
   mergeConfig,
   loadSpecCache,
+  loadSnapshotsForDays,
+  loadSnapshots,
+  loadCodeOwners,
   loadCachedReport,
   listWorkspacePackages,
+  isStandardJSONSchema,
   isFixableDrift,
   isExecutableLang,
   isCachedReportValid,
@@ -8783,6 +10073,7 @@ export {
   hasDocsForExport,
   groupDriftsByCategory,
   getUndocumentedExports,
+  getTrend,
   getSpecCachePath,
   getRunCommand,
   getRulesForKind,
@@ -8790,36 +10081,46 @@ export {
   getReportPath,
   getPrimaryBuildScript,
   getInstallCommand,
+  getFileBlame,
+  getExtendedTrend,
   getDriftSummary,
   getDocumentedExports,
   getDocsImpactSummary,
   getDiffReportPath,
   getDefaultConfig,
   getCoverageRules,
+  getBlameForLines,
+  generateWeeklySummaries,
   generateReportFromEnriched,
   generateReport,
   generateFixesForExport,
   generateFix,
   formatPackageList,
   formatDriftSummaryLine,
+  formatDelta,
   findRemovedReferences,
   findPackageByName,
+  findOwners,
   findJSDocLocation,
   findExportReferences,
   findDeprecatedReferences,
   fetchSpecFromGitHub,
   fetchSpec,
   fetchGitHubContext,
+  extractViaStandardSchema,
   extractSpecSummary,
   extractPackageSpec,
   extractImports,
   extractFunctionCalls,
   evaluateQuality,
+  evaluatePolicy,
+  evaluatePolicies,
   evaluateExportQuality,
   ensureSpecCoverage,
   enrichSpec,
   diffSpecWithDocs,
   diffHashes,
+  detectRuntimeSchemas,
   detectPackageManager,
   detectMonorepo,
   detectExampleRuntimeErrors,
@@ -8829,9 +10130,11 @@ export {
   defineConfig,
   createSourceFile,
   createNodeCommandRunner,
+  computeSnapshot,
   computeExportDrift,
   computeDrift,
   clearSpecCache,
+  clearSchemaCache,
   categorizeDrifts,
   categorizeDrift,
   calculateAggregateCoverage,
@@ -8840,19 +10143,28 @@ export {
   buildDisplayUrl,
   buildCloneUrl,
   blockReferencesExport,
+  attributeOwners,
   applyPatchToJSDoc,
   applyEdits,
+  analyzeSpecOwnership,
+  analyzeSpecContributors,
   analyzeProject,
+  analyzeOwnership,
   analyzeFile,
   analyzeDocsImpact,
+  analyzeContributors,
   analyze,
   VALIDATION_INFO,
+  TSDOC_RULES,
   SandboxFileSystem,
   STYLE_RULES,
   SPEC_CACHE_FILE,
+  RETENTION_DAYS,
   REPORT_VERSION,
   REPORT_EXTENSIONS,
   NodeFileSystem,
+  KNOWN_VENDORS,
+  HISTORY_DIR,
   DocCov,
   DEFAULT_REPORT_PATH,
   DEFAULT_REPORT_DIR,