@doccov/sdk 0.2.1

package/dist/index.js

@@ -0,0 +1,2973 @@
+// src/analysis/run-analysis.ts
+import * as fs2 from "node:fs";
+import * as path4 from "node:path";
+
+// src/ts-module.ts
+import * as tsNamespace from "typescript";
+var resolvedTypeScriptModule = (() => {
+  const candidate = tsNamespace;
+  if (candidate.ScriptTarget === undefined && typeof candidate.default !== "undefined") {
+    return candidate.default;
+  }
+  return candidate;
+})();
+var ts = resolvedTypeScriptModule;
+
+// src/analysis/context.ts
+import * as path2 from "node:path";
+
+// src/options.ts
+var DEFAULT_OPTIONS = {
+  includePrivate: false,
+  followImports: true
+};
+function normalizeDocCovOptions(options = {}) {
+  return {
+    ...DEFAULT_OPTIONS,
+    ...options
+  };
+}
+var normalizeOpenPkgOptions = normalizeDocCovOptions;
+
+// src/analysis/program.ts
+import * as path from "node:path";
+var DEFAULT_COMPILER_OPTIONS = {
+  target: ts.ScriptTarget.Latest,
+  module: ts.ModuleKind.CommonJS,
+  lib: ["lib.es2021.d.ts"],
+  declaration: true,
+  moduleResolution: ts.ModuleResolutionKind.NodeJs
+};
+function createProgram({
+  entryFile,
+  baseDir = path.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, path.dirname(configPath));
+    compilerOptions = { ...compilerOptions, ...parsedConfig.options };
+  }
+  const allowJsVal = compilerOptions.allowJs;
+  if (typeof allowJsVal === "boolean" && allowJsVal) {
+    compilerOptions = { ...compilerOptions, allowJs: false, checkJs: false };
+  }
+  const compilerHost = ts.createCompilerHost(compilerOptions, true);
+  let inMemorySource;
+  if (content !== undefined) {
+    inMemorySource = ts.createSourceFile(entryFile, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const originalGetSourceFile = compilerHost.getSourceFile.bind(compilerHost);
+    compilerHost.getSourceFile = (fileName, languageVersion, onError, shouldCreateNewSourceFile) => {
+      if (fileName === entryFile) {
+        return inMemorySource;
+      }
+      return originalGetSourceFile(fileName, languageVersion, onError, shouldCreateNewSourceFile);
+    };
+  }
+  const program = ts.createProgram([entryFile], compilerOptions, compilerHost);
+  const sourceFile = inMemorySource ?? program.getSourceFile(entryFile);
+  return {
+    program,
+    compilerHost,
+    compilerOptions,
+    sourceFile,
+    configPath
+  };
+}
+
+// src/analysis/context.ts
+function createAnalysisContext({
+  entryFile,
+  packageDir,
+  content,
+  options
+}) {
+  const baseDir = packageDir ?? path2.dirname(entryFile);
+  const normalizedOptions = normalizeOpenPkgOptions(options);
+  const programResult = createProgram({ entryFile, baseDir, content });
+  if (!programResult.sourceFile) {
+    throw new Error(`Could not load ${entryFile}`);
+  }
+  return {
+    entryFile,
+    baseDir,
+    program: programResult.program,
+    checker: programResult.program.getTypeChecker(),
+    sourceFile: programResult.sourceFile,
+    compilerOptions: programResult.compilerOptions,
+    compilerHost: programResult.compilerHost,
+    options: normalizedOptions,
+    configPath: programResult.configPath
+  };
+}
+
+// src/analysis/spec-builder.ts
+import * as fs from "node:fs";
+import * as path3 from "node:path";
+import { SCHEMA_URL } from "@openpkg-ts/spec";
+
+// src/analysis/docs-coverage.ts
+var DOC_SECTIONS = ["description", "params", "returns", "examples"];
+var SECTION_WEIGHT = 100 / DOC_SECTIONS.length;
+function computeDocsCoverage(spec) {
+  const coverageByExport = new Map;
+  const exportRegistry = new Set;
+  for (const entry of spec.exports ?? []) {
+    exportRegistry.add(entry.name);
+    exportRegistry.add(entry.id);
+  }
+  for (const type of spec.types ?? []) {
+    exportRegistry.add(type.name);
+    exportRegistry.add(type.id);
+  }
+  let aggregateScore = 0;
+  let processed = 0;
+  for (const entry of spec.exports ?? []) {
+    const coverage = evaluateExport(entry, exportRegistry);
+    coverageByExport.set(entry.id ?? entry.name, coverage.docs);
+    aggregateScore += coverage.docs.coverageScore ?? 0;
+    processed += 1;
+  }
+  const specCoverageScore = processed === 0 ? 100 : Math.round(aggregateScore / processed);
+  return {
+    spec: { coverageScore: specCoverageScore },
+    exports: coverageByExport
+  };
+}
+function evaluateExport(entry, exportRegistry) {
+  const missing = [];
+  const drift = [
+    ...detectParamDrift(entry),
+    ...detectOptionalityDrift(entry),
+    ...detectParamTypeDrift(entry),
+    ...detectReturnTypeDrift(entry),
+    ...detectGenericConstraintDrift(entry),
+    ...detectDeprecatedDrift(entry),
+    ...detectVisibilityDrift(entry),
+    ...detectExampleDrift(entry, exportRegistry),
+    ...detectBrokenLinks(entry, exportRegistry)
+  ];
+  if (!hasDescription(entry)) {
+    missing.push("description");
+  }
+  if (!paramsDocumented(entry)) {
+    missing.push("params");
+  }
+  if (!returnsDocumented(entry)) {
+    missing.push("returns");
+  }
+  if (!hasExamples(entry)) {
+    missing.push("examples");
+  }
+  const satisfied = DOC_SECTIONS.length - missing.length;
+  const coverageScore = Math.max(0, Math.round(satisfied * SECTION_WEIGHT));
+  return {
+    id: entry.id,
+    docs: {
+      coverageScore,
+      missing: missing.length > 0 ? missing : undefined,
+      drift: drift.length > 0 ? drift : undefined
+    }
+  };
+}
+function hasDescription(entry) {
+  return Boolean(entry.description && entry.description.trim().length > 0);
+}
+function paramsDocumented(entry) {
+  const parameters = (entry.signatures ?? []).flatMap((signature) => signature.parameters ?? []);
+  if (parameters.length === 0) {
+    return true;
+  }
+  return parameters.every((param) => Boolean(param.description && param.description.trim().length > 0));
+}
+function returnsDocumented(entry) {
+  const signatures = entry.signatures ?? [];
+  if (signatures.length === 0) {
+    return true;
+  }
+  return signatures.every((signature) => {
+    const text = signature.returns?.description;
+    return Boolean(text && text.trim().length > 0);
+  });
+}
+function hasExamples(entry) {
+  return Array.isArray(entry.examples) && entry.examples.length > 0;
+}
+function detectParamDrift(entry) {
+  const drifts = [];
+  const signatures = entry.signatures ?? [];
+  if (signatures.length === 0) {
+    return drifts;
+  }
+  const actualParamNames = new Set;
+  for (const signature of signatures) {
+    for (const param of signature.parameters ?? []) {
+      if (param.name) {
+        actualParamNames.add(param.name);
+      }
+    }
+  }
+  if (actualParamNames.size === 0) {
+    return drifts;
+  }
+  const documentedParamNames = (entry.tags ?? []).filter((tag) => tag.name === "param" && Boolean(tag.text)).map((tag) => extractParamFromTag(tag.text ?? "")?.name).filter((name) => Boolean(name));
+  if (documentedParamNames.length === 0) {
+    return drifts;
+  }
+  for (const documentedName of documentedParamNames) {
+    if (actualParamNames.has(documentedName)) {
+      continue;
+    }
+    const suggestion = findClosestMatch(documentedName, Array.from(actualParamNames));
+    drifts.push({
+      type: "param-mismatch",
+      target: documentedName,
+      issue: `JSDoc documents parameter "${documentedName}" which is not present in the signature.`,
+      suggestion: suggestion?.distance !== undefined && suggestion.distance <= 3 ? suggestion.value : undefined
+    });
+  }
+  return drifts;
+}
+function detectOptionalityDrift(entry) {
+  const signatures = entry.signatures ?? [];
+  if (signatures.length === 0) {
+    return [];
+  }
+  const actualOptionality = new Map;
+  for (const signature of signatures) {
+    for (const param of signature.parameters ?? []) {
+      if (!param.name || actualOptionality.has(param.name)) {
+        continue;
+      }
+      actualOptionality.set(param.name, param.required === false);
+    }
+  }
+  if (actualOptionality.size === 0) {
+    return [];
+  }
+  const documentedParams = (entry.tags ?? []).filter((tag) => tag.name === "param" && Boolean(tag.text)).map((tag) => extractParamFromTag(tag.text ?? "")).filter((parsed) => Boolean(parsed?.name));
+  if (documentedParams.length === 0) {
+    return [];
+  }
+  const drifts = [];
+  for (const docParam of documentedParams) {
+    const actualOptional = actualOptionality.get(docParam.name);
+    if (actualOptional === undefined) {
+      continue;
+    }
+    const documentedOptional = Boolean(docParam.isOptional);
+    if (actualOptional === documentedOptional) {
+      continue;
+    }
+    const issue = documentedOptional ? `JSDoc marks parameter "${docParam.name}" optional but the signature requires it.` : `JSDoc omits optional brackets for parameter "${docParam.name}" but the signature marks it optional.`;
+    const suggestion = documentedOptional ? `Remove brackets around ${docParam.name} or mark the parameter optional in the signature.` : `Document ${docParam.name} as [${docParam.name}] or make it required in the signature.`;
+    drifts.push({
+      type: "optionality-mismatch",
+      target: docParam.name,
+      issue,
+      suggestion
+    });
+  }
+  return drifts;
+}
+function detectParamTypeDrift(entry) {
+  const signatures = entry.signatures ?? [];
+  if (signatures.length === 0) {
+    return [];
+  }
+  const documentedParams = (entry.tags ?? []).filter((tag) => tag.name === "param" && Boolean(tag.text)).map((tag) => extractParamFromTag(tag.text ?? "")).filter((parsed) => Boolean(parsed?.name) && Boolean(parsed?.type));
+  if (documentedParams.length === 0) {
+    return [];
+  }
+  const declaredParamTypes = new Map;
+  for (const signature of signatures) {
+    for (const param of signature.parameters ?? []) {
+      if (!param.name || declaredParamTypes.has(param.name)) {
+        continue;
+      }
+      const declaredType = extractTypeFromSchema(param.schema);
+      if (declaredType) {
+        declaredParamTypes.set(param.name, declaredType);
+      }
+    }
+  }
+  if (declaredParamTypes.size === 0) {
+    return [];
+  }
+  const drifts = [];
+  for (const documentedParam of documentedParams) {
+    const declaredType = declaredParamTypes.get(documentedParam.name);
+    if (!declaredType || !documentedParam.type) {
+      continue;
+    }
+    const documentedNormalized = normalizeType(documentedParam.type);
+    const declaredNormalized = normalizeType(declaredType);
+    if (!documentedNormalized || !declaredNormalized) {
+      continue;
+    }
+    if (typesEquivalent(documentedNormalized, declaredNormalized)) {
+      continue;
+    }
+    drifts.push({
+      type: "param-type-mismatch",
+      target: documentedParam.name,
+      issue: buildParamTypeMismatchIssue(documentedParam.name, documentedParam.type, declaredType),
+      suggestion: `Update @param {${declaredType}} ${documentedParam.name} to match the signature.`
+    });
+  }
+  return drifts;
+}
+function detectReturnTypeDrift(entry) {
+  const returnsTag = entry.tags?.find((tag) => tag.name === "returns" && tag.text?.length);
+  if (!returnsTag) {
+    return [];
+  }
+  const documentedType = extractReturnTypeFromTag(returnsTag.text);
+  if (!documentedType) {
+    return [];
+  }
+  const signatureWithReturns = entry.signatures?.find((signature) => signature.returns);
+  const signatureReturn = signatureWithReturns?.returns;
+  if (!signatureReturn) {
+    return [];
+  }
+  const declaredRaw = signatureReturn.tsType ?? extractTypeFromSchema(signatureReturn.schema);
+  const declaredType = normalizeType(declaredRaw) ?? undefined;
+  if (!declaredType) {
+    return [];
+  }
+  const documentedNormalized = normalizeType(documentedType);
+  if (!documentedNormalized) {
+    return [];
+  }
+  if (typesEquivalent(documentedNormalized, declaredType)) {
+    return [];
+  }
+  return [
+    {
+      type: "return-type-mismatch",
+      target: "returns",
+      issue: buildReturnTypeMismatchIssue(documentedType, documentedNormalized, declaredType),
+      suggestion: `Update @returns to ${declaredType}.`
+    }
+  ];
+}
+function detectDeprecatedDrift(entry) {
+  const codeDeprecated = Boolean(entry.deprecated);
+  const docsDeprecated = entry.tags?.some((tag) => tag.name.toLowerCase() === "deprecated") ?? false;
+  if (codeDeprecated === docsDeprecated) {
+    return [];
+  }
+  const target = entry.name ?? entry.id;
+  if (codeDeprecated && !docsDeprecated) {
+    return [
+      {
+        type: "deprecated-mismatch",
+        target,
+        issue: `Declaration for "${target}" is marked deprecated but @deprecated is missing from the docs.`,
+        suggestion: "Add an @deprecated tag explaining the replacement or removal timeline."
+      }
+    ];
+  }
+  return [
+    {
+      type: "deprecated-mismatch",
+      target,
+      issue: `JSDoc marks "${target}" as deprecated but the TypeScript declaration is not.`,
+      suggestion: "Remove the @deprecated tag or deprecate the declaration."
+    }
+  ];
+}
+function detectGenericConstraintDrift(entry) {
+  const templateTags = entry.tags?.filter((tag) => tag.name === "template" && Boolean(tag.text?.trim())) ?? [];
+  if (templateTags.length === 0) {
+    return [];
+  }
+  const documentedTemplates = templateTags.map((tag) => parseTemplateTag(tag.text)).filter((template) => Boolean(template?.name));
+  if (documentedTemplates.length === 0) {
+    return [];
+  }
+  const actualConstraints = collectActualTypeParameterConstraints(entry);
+  if (actualConstraints.size === 0) {
+    return [];
+  }
+  const drifts = [];
+  for (const doc of documentedTemplates) {
+    if (!actualConstraints.has(doc.name)) {
+      continue;
+    }
+    const actualConstraint = actualConstraints.get(doc.name);
+    const normalizedActual = normalizeType(actualConstraint);
+    const normalizedDocumented = normalizeType(doc.constraint);
+    if (!normalizedActual && !normalizedDocumented) {
+      continue;
+    }
+    if (normalizedActual === normalizedDocumented) {
+      continue;
+    }
+    drifts.push({
+      type: "generic-constraint-mismatch",
+      target: doc.name,
+      issue: buildGenericConstraintMismatchIssue(doc.name, doc.constraint, actualConstraint),
+      suggestion: buildGenericConstraintSuggestion(doc.name, actualConstraint)
+    });
+  }
+  return drifts;
+}
+var VISIBILITY_TAG_MAP = {
+  internal: "internal",
+  alpha: "internal",
+  private: "private",
+  protected: "protected",
+  public: "public"
+};
+function detectVisibilityDrift(entry) {
+  const drifts = [];
+  const exportDocVisibility = getDocVisibility(entry.tags);
+  const exportActualVisibility = "public";
+  if (exportDocVisibility && !visibilityMatches(exportDocVisibility.value, exportActualVisibility)) {
+    const target = entry.name ?? entry.id ?? "export";
+    drifts.push({
+      type: "visibility-mismatch",
+      target,
+      issue: buildVisibilityIssue(target, exportDocVisibility, exportActualVisibility),
+      suggestion: buildVisibilitySuggestion(exportDocVisibility, exportActualVisibility)
+    });
+  }
+  const members = Array.isArray(entry.members) ? entry.members : [];
+  for (const member of members) {
+    const typedMember = member;
+    const memberDocVisibility = getDocVisibility(typedMember.tags);
+    if (!memberDocVisibility) {
+      continue;
+    }
+    const memberActualVisibility = typedMember.visibility ?? "public";
+    if (visibilityMatches(memberDocVisibility.value, memberActualVisibility)) {
+      continue;
+    }
+    const memberName = typedMember.name ?? typedMember.id ?? typedMember.kind ?? "member";
+    const qualifiedTarget = `${entry.name ?? entry.id ?? "export"}#${memberName}`;
+    drifts.push({
+      type: "visibility-mismatch",
+      target: qualifiedTarget,
+      issue: buildVisibilityIssue(qualifiedTarget, memberDocVisibility, memberActualVisibility),
+      suggestion: buildVisibilitySuggestion(memberDocVisibility, memberActualVisibility)
+    });
+  }
+  return drifts;
+}
+function getDocVisibility(tags) {
+  if (!tags) {
+    return;
+  }
+  for (const tag of tags) {
+    const normalizedName = tag.name?.toLowerCase();
+    if (!normalizedName) {
+      continue;
+    }
+    const mapped = VISIBILITY_TAG_MAP[normalizedName];
+    if (mapped) {
+      return {
+        value: mapped,
+        tagName: tag.name
+      };
+    }
+  }
+  return;
+}
+function visibilityMatches(docVisibility, actualVisibility) {
+  if (docVisibility === "internal") {
+    return actualVisibility !== "public";
+  }
+  if (docVisibility === "public") {
+    return actualVisibility === "public";
+  }
+  return docVisibility === actualVisibility;
+}
+function buildVisibilityIssue(target, docVisibility, actualVisibility) {
+  const docLabel = formatDocVisibilityTag(docVisibility.tagName);
+  return `JSDoc marks "${target}" as ${docLabel} but the declaration is ${actualVisibility}.`;
+}
+function buildVisibilitySuggestion(docVisibility, actualVisibility) {
+  const docLabel = formatDocVisibilityTag(docVisibility.tagName);
+  switch (docVisibility.value) {
+    case "internal":
+      return `Remove ${docLabel} or mark the declaration protected/private.`;
+    case "public":
+      return `Remove ${docLabel} or mark the declaration public.`;
+    case "protected":
+      if (actualVisibility === "private") {
+        return `Promote the declaration to protected or replace ${docLabel} with @private.`;
+      }
+      return `Remove ${docLabel} or mark the declaration protected.`;
+    case "private":
+      if (actualVisibility === "protected") {
+        return `Downgrade the declaration to private or replace ${docLabel} with @protected/@internal.`;
+      }
+      return `Remove ${docLabel} or mark the declaration private.`;
+    default:
+      return "Align the JSDoc visibility tag with the declaration visibility.";
+  }
+}
+function formatDocVisibilityTag(tagName) {
+  const trimmed = tagName.trim();
+  if (!trimmed) {
+    return "@internal";
+  }
+  return trimmed.startsWith("@") ? trimmed : `@${trimmed}`;
+}
+function extractParamFromTag(text) {
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return;
+  }
+  const match = trimmed.match(/^(?:\{([^}]+)\}\s+)?(\S+)(?:\s+-\s+)?/);
+  if (!match) {
+    return;
+  }
+  const [, type, rawName] = match;
+  const isOptional = Boolean(rawName?.startsWith("[") && rawName?.endsWith("]"));
+  const name = normalizeParamName(rawName);
+  if (!name) {
+    return;
+  }
+  return {
+    name,
+    type: type?.trim(),
+    isOptional
+  };
+}
+function normalizeParamName(raw) {
+  if (!raw) {
+    return;
+  }
+  let name = raw.trim();
+  if (!name) {
+    return;
+  }
+  if (name.startsWith("[") && name.endsWith("]")) {
+    name = name.slice(1, -1);
+  }
+  const equalsIndex = name.indexOf("=");
+  if (equalsIndex >= 0) {
+    name = name.slice(0, equalsIndex);
+  }
+  if (name.endsWith(",")) {
+    name = name.slice(0, -1);
+  }
+  return name;
+}
+function extractReturnTypeFromTag(text) {
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return;
+  }
+  const braceMatch = trimmed.match(/^\{([^}]+)\}/);
+  if (braceMatch) {
+    return braceMatch[1]?.trim();
+  }
+  const [first] = trimmed.split(/\s+/);
+  return first?.trim();
+}
+function extractTypeFromSchema(schema) {
+  if (!schema) {
+    return;
+  }
+  if (typeof schema === "string") {
+    return schema;
+  }
+  if (typeof schema === "object") {
+    const record = schema;
+    if (typeof record.type === "string") {
+      return record.type;
+    }
+    if (typeof record.$ref === "string") {
+      const ref = record.$ref;
+      return ref.startsWith("#/types/") ? ref.slice("#/types/".length) : ref;
+    }
+  }
+  return;
+}
+function normalizeType(value) {
+  if (!value) {
+    return;
+  }
+  return value.replace(/\s+/g, " ").replace(/\s*<\s*/g, "<").replace(/\s*>\s*/g, ">").trim();
+}
+var VOID_EQUIVALENTS = new Set(["void", "undefined"]);
+function typesEquivalent(a, b) {
+  if (a === b) {
+    return true;
+  }
+  const lowerA = a.toLowerCase();
+  const lowerB = b.toLowerCase();
+  if (VOID_EQUIVALENTS.has(lowerA) && VOID_EQUIVALENTS.has(lowerB)) {
+    return true;
+  }
+  return false;
+}
+function unwrapPromise(type) {
+  const match = type.match(/^promise<(.+)>$/i);
+  return match ? match[1]?.trim() : undefined;
+}
+function buildReturnTypeMismatchIssue(documentedRaw, documentedNormalized, declaredNormalized) {
+  const docPromiseInner = unwrapPromise(documentedNormalized);
+  const declaredPromiseInner = unwrapPromise(declaredNormalized);
+  if (docPromiseInner && !declaredPromiseInner && docPromiseInner === declaredNormalized) {
+    return `JSDoc documents Promise<${docPromiseInner}> but the function returns ${declaredNormalized}.`;
+  }
+  if (!docPromiseInner && declaredPromiseInner && documentedNormalized === declaredPromiseInner) {
+    return `JSDoc documents ${documentedNormalized} but the function returns Promise<${declaredPromiseInner}>.`;
+  }
+  return `JSDoc documents ${documentedRaw} but the function returns ${declaredNormalized}.`;
+}
+function buildParamTypeMismatchIssue(paramName, documentedRaw, declaredRaw) {
+  return `JSDoc documents ${documentedRaw} for parameter "${paramName}" but the signature declares ${declaredRaw}.`;
+}
+function parseTemplateTag(text) {
+  const trimmed = text?.trim();
+  if (!trimmed) {
+    return;
+  }
+  let remaining = trimmed;
+  let constraint;
+  const braceMatch = remaining.match(/^\{([^}]+)\}\s+(.+)$/);
+  if (braceMatch) {
+    constraint = braceMatch[1]?.trim();
+    remaining = braceMatch[2]?.trim() ?? "";
+  }
+  if (!remaining) {
+    return;
+  }
+  const parts = remaining.split(/\s+/).filter(Boolean);
+  const rawName = parts.shift();
+  if (!rawName) {
+    return;
+  }
+  const name = rawName.replace(/[.,;:]+$/, "");
+  if (!constraint && parts.length > 0 && parts[0] === "extends") {
+    const constraintTokens = parts.slice(1);
+    const dashIndex = constraintTokens.findIndex((token) => token === "-" || token === "–");
+    const tokens = dashIndex >= 0 ? constraintTokens.slice(0, dashIndex) : constraintTokens;
+    constraint = tokens.join(" ").trim();
+  }
+  if (!constraint) {
+    constraint = undefined;
+  }
+  return {
+    name,
+    constraint
+  };
+}
+function collectActualTypeParameterConstraints(entry) {
+  const constraints = new Map;
+  for (const typeParam of entry.typeParameters ?? []) {
+    if (!typeParam?.name || constraints.has(typeParam.name)) {
+      continue;
+    }
+    constraints.set(typeParam.name, typeParam.constraint ?? undefined);
+  }
+  for (const signature of entry.signatures ?? []) {
+    for (const typeParam of signature.typeParameters ?? []) {
+      if (!typeParam?.name || constraints.has(typeParam.name)) {
+        continue;
+      }
+      constraints.set(typeParam.name, typeParam.constraint ?? undefined);
+    }
+  }
+  return constraints;
+}
+function buildGenericConstraintMismatchIssue(templateName, documentedConstraint, actualConstraint) {
+  if (actualConstraint && documentedConstraint) {
+    return `JSDoc constrains template "${templateName}" to ${documentedConstraint} but the declaration constrains it to ${actualConstraint}.`;
+  }
+  if (actualConstraint && !documentedConstraint) {
+    return `JSDoc omits the constraint for template "${templateName}" but the declaration constrains it to ${actualConstraint}.`;
+  }
+  if (!actualConstraint && documentedConstraint) {
+    return `JSDoc constrains template "${templateName}" to ${documentedConstraint} but the declaration has no constraint.`;
+  }
+  return `Template "${templateName}" has inconsistent constraints between JSDoc and the declaration.`;
+}
+function buildGenericConstraintSuggestion(templateName, actualConstraint) {
+  if (actualConstraint) {
+    return `Update @template to {${actualConstraint}} ${templateName} to reflect the declaration.`;
+  }
+  return `Remove the constraint from @template ${templateName} to match the declaration.`;
+}
+function findClosestMatch(source, candidates) {
+  if (candidates.length === 0) {
+    return;
+  }
+  const normalizedSource = source.toLowerCase();
+  const substringCandidate = candidates.find((candidate) => {
+    const normalizedCandidate = candidate.toLowerCase();
+    return normalizedCandidate.includes(normalizedSource) || normalizedSource.includes(normalizedCandidate);
+  });
+  if (substringCandidate && substringCandidate !== source) {
+    return { value: substringCandidate, distance: 0 };
+  }
+  let best;
+  for (const candidate of candidates) {
+    const distance = levenshtein(source, candidate);
+    if (!best || distance < best.distance) {
+      best = { value: candidate, distance };
+    }
+  }
+  return best;
+}
+function levenshtein(a, b) {
+  if (a === b) {
+    return 0;
+  }
+  if (a.length === 0) {
+    return b.length;
+  }
+  if (b.length === 0) {
+    return a.length;
+  }
+  const matrix = [];
+  for (let i = 0;i <= b.length; i++) {
+    matrix[i] = [i];
+  }
+  for (let j = 0;j <= a.length; j++) {
+    matrix[0][j] = j;
+  }
+  for (let i = 1;i <= b.length; i++) {
+    for (let j = 1;j <= a.length; j++) {
+      if (b.charAt(i - 1) === a.charAt(j - 1)) {
+        matrix[i][j] = matrix[i - 1][j - 1];
+      } else {
+        matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j] + 1);
+      }
+    }
+  }
+  return matrix[b.length][a.length];
+}
+function detectExampleDrift(entry, exportRegistry) {
+  if (!exportRegistry || !entry.examples || entry.examples.length === 0) {
+    return [];
+  }
+  const drifts = [];
+  const identifierPattern = /\b([A-Z][a-zA-Z0-9]*)\b/g;
+  for (const example of entry.examples) {
+    if (typeof example !== "string") {
+      continue;
+    }
+    const matches = example.matchAll(identifierPattern);
+    const referencedIdentifiers = new Set;
+    for (const match of matches) {
+      const identifier = match[1];
+      if (identifier && !isBuiltInIdentifier(identifier)) {
+        referencedIdentifiers.add(identifier);
+      }
+    }
+    for (const identifier of referencedIdentifiers) {
+      if (!exportRegistry.has(identifier)) {
+        const suggestion = findClosestMatch(identifier, Array.from(exportRegistry));
+        if (suggestion && suggestion.distance <= 3) {
+          drifts.push({
+            type: "example-drift",
+            target: identifier,
+            issue: `@example references "${identifier}" which does not exist in this package.`,
+            suggestion: `Did you mean "${suggestion.value}"?`
+          });
+        }
+      }
+    }
+  }
+  return drifts;
+}
+function isBuiltInIdentifier(identifier) {
+  const builtIns = new Set([
+    "Array",
+    "Object",
+    "String",
+    "Number",
+    "Boolean",
+    "Function",
+    "Symbol",
+    "BigInt",
+    "Date",
+    "RegExp",
+    "Error",
+    "TypeError",
+    "ReferenceError",
+    "SyntaxError",
+    "Map",
+    "Set",
+    "WeakMap",
+    "WeakSet",
+    "Promise",
+    "Proxy",
+    "Reflect",
+    "JSON",
+    "Math",
+    "Intl",
+    "ArrayBuffer",
+    "DataView",
+    "URL",
+    "Record",
+    "Partial",
+    "Required",
+    "Readonly",
+    "Pick",
+    "Omit",
+    "Exclude",
+    "Extract",
+    "NonNullable",
+    "ReturnType",
+    "InstanceType",
+    "Parameters",
+    "ConstructorParameters",
+    "Console",
+    "Event",
+    "Element",
+    "Document",
+    "Window",
+    "Node",
+    "React",
+    "Component",
+    "Props",
+    "State"
+  ]);
+  return builtIns.has(identifier);
+}
+function detectBrokenLinks(entry, exportRegistry) {
+  if (!exportRegistry) {
+    return [];
+  }
+  const drifts = [];
+  const linkPattern = /\{@link\s+([^}\s]+)\s*\}/g;
+  const allText = [
+    entry.description ?? "",
+    ...(entry.tags ?? []).map((tag) => tag.text),
+    ...entry.examples ?? []
+  ].join(" ");
+  const matches = allText.matchAll(linkPattern);
+  for (const match of matches) {
+    const target = match[1];
+    if (!target) {
+      continue;
+    }
+    const rootName = target.split(".")[0] ?? target;
+    if (!exportRegistry.has(rootName) && !exportRegistry.has(target)) {
+      const suggestion = findClosestMatch(rootName, Array.from(exportRegistry));
+      drifts.push({
+        type: "broken-link",
+        target,
+        issue: `{@link ${target}} references a symbol that does not exist.`,
+        suggestion: suggestion && suggestion.distance <= 3 ? `Did you mean "${suggestion.value}"?` : undefined
+      });
+    }
+  }
+  return drifts;
+}
+
+// src/utils/type-utils.ts
+function collectReferencedTypes(type, typeChecker, referencedTypes, visitedTypes = new Set) {
+  if (visitedTypes.has(type))
+    return;
+  visitedTypes.add(type);
+  const symbol = type.getSymbol();
+  if (symbol) {
+    const symbolName = symbol.getName();
+    if (!symbolName.startsWith("__") && !isBuiltInType(symbolName)) {
+      referencedTypes.add(symbolName);
+    }
+  }
+  if (type.isIntersection()) {
+    for (const intersectionType of type.types) {
+      collectReferencedTypes(intersectionType, typeChecker, referencedTypes, visitedTypes);
+    }
+  }
+  if (type.isUnion()) {
+    for (const unionType of type.types) {
+      collectReferencedTypes(unionType, typeChecker, referencedTypes, visitedTypes);
+    }
+  }
+  if (type.flags & ts.TypeFlags.Object) {
+    const objectType = type;
+    if (objectType.objectFlags & ts.ObjectFlags.Reference) {
+      const typeRef = objectType;
+      if (typeRef.typeArguments) {
+        for (const typeArg of typeRef.typeArguments) {
+          collectReferencedTypes(typeArg, typeChecker, referencedTypes, visitedTypes);
+        }
+      }
+    }
+  }
+}
+function collectReferencedTypesFromNode(node, typeChecker, referencedTypes) {
+  if (ts.isTypeReferenceNode(node)) {
+    const typeNameText = node.typeName.getText();
+    const symbol = typeChecker.getSymbolAtLocation(node.typeName);
+    const name = symbol?.getName() ?? typeNameText;
+    if (!isBuiltInType(name)) {
+      referencedTypes.add(name);
+    }
+    node.typeArguments?.forEach((arg) => collectReferencedTypesFromNode(arg, typeChecker, referencedTypes));
+    return;
+  }
+  if (ts.isExpressionWithTypeArguments(node)) {
+    const expressionText = node.expression.getText();
+    const symbol = typeChecker.getSymbolAtLocation(node.expression);
+    const name = symbol?.getName() ?? expressionText;
+    if (!isBuiltInType(name)) {
+      referencedTypes.add(name);
+    }
+    node.typeArguments?.forEach((arg) => collectReferencedTypesFromNode(arg, typeChecker, referencedTypes));
+    return;
+  }
+  if (ts.isUnionTypeNode(node) || ts.isIntersectionTypeNode(node)) {
+    node.types.forEach((typeNode) => collectReferencedTypesFromNode(typeNode, typeChecker, referencedTypes));
+    return;
+  }
+  if (ts.isArrayTypeNode(node)) {
+    collectReferencedTypesFromNode(node.elementType, typeChecker, referencedTypes);
+    return;
+  }
+  if (ts.isParenthesizedTypeNode(node)) {
+    collectReferencedTypesFromNode(node.type, typeChecker, referencedTypes);
+    return;
+  }
+  if (ts.isTypeLiteralNode(node)) {
+    node.members.forEach((member) => {
+      if (ts.isPropertySignature(member) && member.type) {
+        collectReferencedTypesFromNode(member.type, typeChecker, referencedTypes);
+      }
+      if (ts.isMethodSignature(member)) {
+        member.typeParameters?.forEach((param) => {
+          param.constraint && collectReferencedTypesFromNode(param.constraint, typeChecker, referencedTypes);
+        });
+        member.parameters.forEach((param) => {
+          if (param.type) {
+            collectReferencedTypesFromNode(param.type, typeChecker, referencedTypes);
+          }
+        });
+        if (member.type) {
+          collectReferencedTypesFromNode(member.type, typeChecker, referencedTypes);
+        }
+      }
+      if (ts.isCallSignatureDeclaration(member) && member.type) {
+        collectReferencedTypesFromNode(member.type, typeChecker, referencedTypes);
+      }
+      if (ts.isIndexSignatureDeclaration(member) && member.type) {
+        collectReferencedTypesFromNode(member.type, typeChecker, referencedTypes);
+      }
+    });
+    return;
+  }
+  if (ts.isTypeOperatorNode(node)) {
+    collectReferencedTypesFromNode(node.type, typeChecker, referencedTypes);
+    return;
+  }
+  if (ts.isIndexedAccessTypeNode(node)) {
+    collectReferencedTypesFromNode(node.objectType, typeChecker, referencedTypes);
+    collectReferencedTypesFromNode(node.indexType, typeChecker, referencedTypes);
+    return;
+  }
+  if (ts.isLiteralTypeNode(node)) {
+    return;
+  }
+  node.forEachChild((child) => {
+    if (ts.isTypeNode(child)) {
+      collectReferencedTypesFromNode(child, typeChecker, referencedTypes);
+    }
+  });
+}
+function isBuiltInType(name) {
+  const builtIns = [
+    "string",
+    "number",
+    "boolean",
+    "bigint",
+    "symbol",
+    "undefined",
+    "null",
+    "any",
+    "unknown",
+    "never",
+    "void",
+    "object",
+    "Array",
+    "Promise",
+    "Map",
+    "Set",
+    "WeakMap",
+    "WeakSet",
+    "Date",
+    "RegExp",
+    "Error",
+    "Function",
+    "Object",
+    "String",
+    "Number",
+    "Boolean",
+    "BigInt",
+    "Symbol",
+    "Uint8Array",
+    "Int8Array",
+    "Uint16Array",
+    "Int16Array",
+    "Uint32Array",
+    "Int32Array",
+    "Float32Array",
+    "Float64Array",
+    "BigInt64Array",
+    "BigUint64Array",
+    "Uint8ClampedArray",
+    "ArrayBuffer",
+    "ArrayBufferLike",
+    "DataView",
+    "Uint8ArrayConstructor",
+    "ArrayBufferConstructor",
+    "JSON",
+    "Math",
+    "Reflect",
+    "Proxy",
+    "Intl",
+    "globalThis",
+    "__type"
+  ];
+  return builtIns.includes(name);
+}
+
+// src/utils/parameter-utils.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;
+}
+function isPureRefSchema(value) {
+  return Object.keys(value).length === 1 && "$ref" in value;
+}
+function withDescription(schema, description) {
+  if (isPureRefSchema(schema)) {
+    return {
+      allOf: [schema],
+      description
+    };
+  }
+  return {
+    ...schema,
+    description
+  };
+}
+function propertiesToSchema(properties, description) {
+  const schema = {
+    type: "object",
+    properties: {}
+  };
+  const required = [];
+  for (const prop of properties) {
+    const propType = prop.type;
+    let propSchema;
+    if (typeof propType === "string") {
+      if (["string", "number", "boolean", "bigint", "null"].includes(propType)) {
+        propSchema = { type: propType === "bigint" ? "string" : propType };
+      } else {
+        propSchema = { type: propType };
+      }
+    } else if (propType && typeof propType === "object") {
+      propSchema = propType;
+    } else {
+      propSchema = { type: "any" };
+    }
+    if (prop.description && typeof propSchema === "object") {
+      propSchema = withDescription(propSchema, prop.description);
+    }
+    schema.properties[prop.name] = propSchema;
+    if (!prop.optional) {
+      required.push(prop.name);
+    }
+  }
+  if (required.length > 0) {
+    schema.required = required;
+  }
+  if (description) {
+    return withDescription(schema, description);
+  }
+  return schema;
+}
+function buildSchemaFromTypeNode(node, typeChecker, typeRefs, referencedTypes, functionDoc, parentParamName) {
+  if (ts.isParenthesizedTypeNode(node)) {
+    return buildSchemaFromTypeNode(node.type, typeChecker, typeRefs, referencedTypes, functionDoc ?? null, parentParamName);
+  }
+  if (ts.isIntersectionTypeNode(node)) {
+    const schemas = node.types.map((type) => buildSchemaFromTypeNode(type, typeChecker, typeRefs, referencedTypes, functionDoc, parentParamName));
+    return { allOf: schemas };
+  }
+  if (ts.isUnionTypeNode(node)) {
+    const schemas = node.types.map((type) => buildSchemaFromTypeNode(type, typeChecker, typeRefs, referencedTypes, functionDoc, parentParamName));
+    return { anyOf: schemas };
+  }
+  if (ts.isArrayTypeNode(node)) {
+    return {
+      type: "array",
+      items: buildSchemaFromTypeNode(node.elementType, typeChecker, typeRefs, referencedTypes, functionDoc, parentParamName)
+    };
+  }
+  if (ts.isTypeLiteralNode(node)) {
+    const properties = {};
+    const required = [];
+    for (const member of node.members) {
+      if (!ts.isPropertySignature(member) || !member.name) {
+        continue;
+      }
+      const propName = member.name.getText();
+      let schema2 = "any";
+      if (member.type) {
+        const memberType = typeChecker.getTypeFromTypeNode(member.type);
+        const formatted = formatTypeReference(memberType, typeChecker, typeRefs, referencedTypes);
+        if (typeof formatted === "string") {
+          if (formatted === "any") {
+            schema2 = buildSchemaFromTypeNode(member.type, typeChecker, typeRefs, referencedTypes, functionDoc, parentParamName);
+          } else {
+            schema2 = { type: formatted };
+          }
+        } else {
+          schema2 = formatted;
+        }
+      } else {
+        schema2 = { type: "any" };
+      }
+      const description = getDocDescriptionForProperty(functionDoc, parentParamName, propName);
+      if (typeof schema2 === "object" && description) {
+        schema2 = withDescription(schema2, description);
+      }
+      properties[propName] = schema2;
+      if (!member.questionToken) {
+        required.push(propName);
+      }
+    }
+    const schema = {
+      type: "object",
+      properties
+    };
+    if (required.length > 0) {
+      schema.required = required;
+    }
+    return schema;
+  }
+  if (ts.isTypeReferenceNode(node)) {
+    const typeName = node.typeName.getText();
+    if (typeName === "Array") {
+      return { type: "array" };
+    }
+    const builtInSchema = BUILTIN_TYPE_SCHEMAS[typeName];
+    if (builtInSchema) {
+      return { ...builtInSchema };
+    }
+    if (isBuiltInType(typeName)) {
+      return { type: "object" };
+    }
+    if (!typeRefs.has(typeName)) {
+      typeRefs.set(typeName, typeName);
+    }
+    referencedTypes?.add(typeName);
+    return { $ref: `#/types/${typeName}` };
+  }
+  if (ts.isLiteralTypeNode(node)) {
+    if (ts.isStringLiteral(node.literal)) {
+      return { enum: [node.literal.text] };
+    }
+    if (ts.isNumericLiteral(node.literal)) {
+      return { enum: [Number(node.literal.text)] };
+    }
+  }
+  if (ts.isIntersectionTypeNode(node)) {
+    const schemas = node.types.map((typeNode) => buildSchemaFromTypeNode(typeNode, typeChecker, typeRefs, referencedTypes, functionDoc, parentParamName));
+    if (schemas.some((schema) => ("$ref" in schema) && Object.keys(schema).length === 1)) {
+      const refs = schemas.filter((schema) => ("$ref" in schema) && Object.keys(schema).length === 1);
+      const nonRefs = schemas.filter((schema) => !(("$ref" in schema) && Object.keys(schema).length === 1));
+      if (refs.length === schemas.length) {
+        return refs[0];
+      }
+      if (nonRefs.length > 0) {
+        const merged = {};
+        for (const obj of nonRefs) {
+          for (const [k, v] of Object.entries(obj)) {
+            merged[k] = v;
+          }
+        }
+        return merged;
+      }
+    }
+    return {
+      allOf: schemas
+    };
+  }
+  return { type: node.getText() };
+}
+function getDocDescriptionForProperty(functionDoc, parentParamName, propName) {
+  if (!functionDoc) {
+    return;
+  }
+  let match = functionDoc.params.find((p) => p.name === `${parentParamName}.${propName}`);
+  if (!match) {
+    match = functionDoc.params.find((p) => p.name.endsWith(`.${propName}`));
+  }
+  return match?.description;
+}
+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 formatTypeReference(type, typeChecker, typeRefs, referencedTypes, visitedAliases) {
+  const visited = visitedAliases ?? new Set;
+  const aliasSymbol = type.aliasSymbol;
+  let aliasName;
+  let aliasAdded = false;
+  if (aliasSymbol) {
+    aliasName = aliasSymbol.getName();
+    if (visited.has(aliasName)) {
+      return { $ref: `#/types/${aliasName}` };
+    }
+    if (typeRefs.has(aliasName)) {
+      return { $ref: `#/types/${aliasName}` };
+    }
+    if (referencedTypes && !isBuiltInType(aliasName)) {
+      referencedTypes.add(aliasName);
+      return { $ref: `#/types/${aliasName}` };
+    }
+    visited.add(aliasName);
+    aliasAdded = true;
+  }
+  try {
+    const typeString = typeChecker.typeToString(type);
+    const primitives = [
+      "string",
+      "number",
+      "boolean",
+      "bigint",
+      "symbol",
+      "any",
+      "unknown",
+      "void",
+      "undefined",
+      "null",
+      "never"
+    ];
+    if (primitives.includes(typeString)) {
+      if (typeString === "bigint") {
+        return { type: "string", format: "bigint" };
+      }
+      if (typeString === "undefined" || typeString === "null") {
+        return { type: "null" };
+      }
+      if (typeString === "void" || typeString === "never") {
+        return { type: "null" };
+      }
+      return { type: typeString };
+    }
+    if (type.isUnion()) {
+      const unionType = type;
+      const parts = unionType.types.map((t) => formatTypeReference(t, typeChecker, typeRefs, referencedTypes, visited));
+      return {
+        anyOf: parts
+      };
+    }
+    if (type.isIntersection()) {
+      const intersectionType = type;
+      const parts = intersectionType.types.map((t) => formatTypeReference(t, typeChecker, typeRefs, referencedTypes, visited));
+      const normalized = parts.flatMap((part) => {
+        if (typeof part === "string") {
+          return [{ type: part }];
+        }
+        if (part && typeof part === "object" && "allOf" in part) {
+          return Array.isArray(part.allOf) ? part.allOf : [part];
+        }
+        return [part];
+      });
+      if (normalized.length === 1) {
+        return normalized[0];
+      }
+      return {
+        allOf: normalized
+      };
+    }
+    const symbol = type.getSymbol();
+    if (symbol) {
+      const symbolName = symbol.getName();
+      if (symbolName.startsWith("__")) {
+        if (type.getFlags() & ts.TypeFlags.Object) {
+          const properties = type.getProperties();
+          if (properties.length > 0) {
+            const objSchema = {
+              type: "object",
+              properties: {}
+            };
+            const required = [];
+            for (const prop of properties) {
+              const propType = typeChecker.getTypeOfSymbolAtLocation(prop, prop.valueDeclaration);
+              const propName = prop.getName();
+              objSchema.properties[propName] = formatTypeReference(propType, typeChecker, typeRefs, referencedTypes, visited);
+              if (!(prop.flags & ts.SymbolFlags.Optional)) {
+                required.push(propName);
+              }
+            }
+            if (required.length > 0) {
+              objSchema.required = required;
+            }
+            return objSchema;
+          }
+        }
+        return { type: "object" };
+      }
+      if (typeRefs.has(symbolName)) {
+        return { $ref: `#/types/${symbolName}` };
+      }
+      if (symbolName === "Array") {
+        return { type: "array" };
+      }
+      const builtInSchema = BUILTIN_TYPE_SCHEMAS[symbolName];
+      if (builtInSchema) {
+        return { ...builtInSchema };
+      }
+      if (referencedTypes && !isBuiltInType(symbolName)) {
+        referencedTypes.add(symbolName);
+        return { $ref: `#/types/${symbolName}` };
+      }
+      if (isBuiltInType(symbolName)) {
+        return { type: "object" };
+      }
+      return { $ref: `#/types/${symbolName}` };
+    }
+    if (type.isLiteral()) {
+      if (typeString.startsWith('"') && typeString.endsWith('"')) {
+        const literalValue = typeString.slice(1, -1);
+        return { enum: [literalValue] };
+      }
+      return { enum: [Number(typeString)] };
+    }
+    const typePattern = /^(\w+)(\s*\|\s*undefined)?$/;
+    const match = typeString.match(typePattern);
+    if (match) {
+      const [, typeName, hasUndefined] = match;
+      if (typeRefs.has(typeName) || !isBuiltInType(typeName)) {
+        if (hasUndefined) {
+          return {
+            anyOf: [{ $ref: `#/types/${typeName}` }, { type: "null" }]
+          };
+        }
+        return { $ref: `#/types/${typeName}` };
+      }
+    }
+    return { type: typeString };
+  } finally {
+    if (aliasAdded && aliasName) {
+      visited.delete(aliasName);
+    }
+  }
+}
+function structureParameter(param, paramDecl, paramType, typeChecker, typeRefs, functionDoc, paramDoc, referencedTypes) {
+  const paramName = param.getName();
+  const isDestructured = paramName === "__0" || ts.isObjectBindingPattern(paramDecl.name) || ts.isArrayBindingPattern(paramDecl.name);
+  let inferredAlias;
+  if (isDestructured && functionDoc && Array.isArray(functionDoc.params)) {
+    const prefixes = functionDoc.params.map((p) => p?.name).filter((n) => typeof n === "string" && n.includes(".")).map((n) => n.split(".", 2)[0]).filter(Boolean);
+    if (prefixes.length > 0) {
+      const counts = new Map;
+      for (const px of prefixes)
+        counts.set(px, (counts.get(px) ?? 0) + 1);
+      inferredAlias = Array.from(counts.entries()).sort((a, b) => b[1] - a[1])[0]?.[0];
+    }
+  }
+  const fallbackName = isDestructured ? inferredAlias ?? "options" : paramName;
+  const docDescription = paramDoc?.description?.trim();
+  if (paramType.isIntersection()) {
+    const properties = [];
+    const intersectionType = paramType;
+    for (const subType of intersectionType.types) {
+      const symbol2 = subType.getSymbol();
+      const _typeString = typeChecker.typeToString(subType);
+      const isAnonymousObject = isObjectLiteralType(subType) || symbol2?.getName().startsWith("__");
+      if (isAnonymousObject) {
+        for (const prop of subType.getProperties()) {
+          const propType = typeChecker.getTypeOfSymbolAtLocation(prop, prop.valueDeclaration);
+          let description = "";
+          if (functionDoc) {
+            let docParam = functionDoc.params.find((p) => p.name === `${paramName}.${prop.getName()}`);
+            if (!docParam && paramName === "__0") {
+              docParam = functionDoc.params.find((p) => p.name.endsWith(`.${prop.getName()}`));
+            }
+            if (docParam) {
+              description = docParam.description;
+            }
+          }
+          properties.push({
+            name: prop.getName(),
+            type: formatTypeReference(propType, typeChecker, typeRefs, referencedTypes),
+            description,
+            optional: !!(prop.flags & ts.SymbolFlags.Optional)
+          });
+        }
+      } else if (symbol2) {
+        const _symbolName = symbol2.getName();
+        if (!isBuiltInType(_symbolName)) {
+          for (const prop of subType.getProperties()) {
+            const propType = typeChecker.getTypeOfSymbolAtLocation(prop, prop.valueDeclaration);
+            properties.push({
+              name: prop.getName(),
+              type: formatTypeReference(propType, typeChecker, typeRefs, referencedTypes),
+              description: "",
+              optional: !!(prop.flags & ts.SymbolFlags.Optional)
+            });
+          }
+        }
+      }
+    }
+    const actualName = fallbackName;
+    const out2 = {
+      name: actualName,
+      required: !typeChecker.isOptionalParameter(paramDecl),
+      schema: propertiesToSchema(properties)
+    };
+    if (docDescription) {
+      out2.description = docDescription;
+    }
+    return out2;
+  }
+  if (paramType.isUnion()) {
+    const unionType = paramType;
+    const objectOptions = [];
+    let hasNonObjectTypes = false;
+    for (const subType of unionType.types) {
+      const symbol2 = subType.getSymbol();
+      if (isObjectLiteralType(subType) || symbol2?.getName().startsWith("__")) {
+        const properties = [];
+        for (const prop of subType.getProperties()) {
+          const propType = typeChecker.getTypeOfSymbolAtLocation(prop, prop.valueDeclaration);
+          properties.push({
+            name: prop.getName(),
+            type: formatTypeReference(propType, typeChecker, typeRefs, referencedTypes),
+            description: "",
+            optional: !!(prop.flags & ts.SymbolFlags.Optional)
+          });
+        }
+        if (properties.length > 0) {
+          objectOptions.push({ properties });
+        }
+      } else {
+        hasNonObjectTypes = true;
+      }
+    }
+    if (objectOptions.length > 0 && !hasNonObjectTypes) {
+      const readableName2 = fallbackName;
+      const out2 = {
+        name: readableName2,
+        required: !typeChecker.isOptionalParameter(paramDecl),
+        schema: {
+          oneOf: objectOptions.map((opt) => propertiesToSchema(opt.properties))
+        }
+      };
+      if (docDescription) {
+        out2.description = docDescription;
+      }
+      return out2;
+    }
+  }
+  const symbol = paramType.getSymbol();
+  if ((symbol?.getName().startsWith("__") || isObjectLiteralType(paramType)) && paramType.getProperties().length > 0) {
+    const properties = [];
+    for (const prop of paramType.getProperties()) {
+      const propType = typeChecker.getTypeOfSymbolAtLocation(prop, prop.valueDeclaration);
+      properties.push({
+        name: prop.getName(),
+        type: formatTypeReference(propType, typeChecker, typeRefs, referencedTypes),
+        description: "",
+        optional: !!(prop.flags & ts.SymbolFlags.Optional)
+      });
+    }
+    const readableName2 = fallbackName;
+    const out2 = {
+      name: readableName2,
+      required: !typeChecker.isOptionalParameter(paramDecl),
+      schema: propertiesToSchema(properties)
+    };
+    if (docDescription) {
+      out2.description = docDescription;
+    }
+    return out2;
+  }
+  if (paramType.flags & ts.TypeFlags.Any && paramDecl.type && paramDecl.name && ts.isObjectBindingPattern(paramDecl.name)) {
+    const actualName = fallbackName;
+    const schema2 = buildSchemaFromTypeNode(paramDecl.type, typeChecker, typeRefs, referencedTypes, functionDoc ?? null, param.getName());
+    const out2 = {
+      name: actualName,
+      required: !typeChecker.isOptionalParameter(paramDecl),
+      schema: schema2
+    };
+    if (docDescription) {
+      out2.description = docDescription;
+    }
+    return out2;
+  }
+  const typeRef = formatTypeReference(paramType, typeChecker, typeRefs, referencedTypes);
+  let schema;
+  if (typeof typeRef === "string") {
+    if ([
+      "string",
+      "number",
+      "boolean",
+      "null",
+      "undefined",
+      "any",
+      "unknown",
+      "never",
+      "void"
+    ].includes(typeRef)) {
+      schema = { type: typeRef };
+    } else {
+      schema = { type: typeRef };
+    }
+  } else {
+    schema = typeRef;
+  }
+  if (paramDecl.type) {
+    const astSchema = buildSchemaFromTypeNode(paramDecl.type, typeChecker, typeRefs, referencedTypes, functionDoc ?? null, param.getName());
+    if (schemaIsAny(schema)) {
+      schema = astSchema;
+    } else if (!(("type" in schema) && schema.type === "any") && !(typeof schema === "object" && isPureRefSchema(schema)) && Object.keys(astSchema).length > 0 && !schemasAreEqual(schema, astSchema)) {
+      schema = {
+        allOf: [schema, astSchema]
+      };
+    }
+  }
+  const readableName = fallbackName;
+  const out = {
+    name: readableName,
+    required: !typeChecker.isOptionalParameter(paramDecl),
+    schema
+  };
+  if (docDescription) {
+    out.description = docDescription;
+  }
+  return out;
+}
+
+// src/utils/tsdoc-utils.ts
+function parseJSDocComment(symbol, _typeChecker, sourceFileOverride) {
+  const node = symbol.valueDeclaration || symbol.declarations?.[0];
+  if (!node)
+    return null;
+  const sourceFile = sourceFileOverride || node.getSourceFile();
+  const commentRanges = ts.getLeadingCommentRanges(sourceFile.text, node.pos);
+  if (!commentRanges || commentRanges.length === 0) {
+    return null;
+  }
+  const lastComment = commentRanges[commentRanges.length - 1];
+  const commentText = sourceFile.text.substring(lastComment.pos, lastComment.end);
+  return parseJSDocText(commentText);
+}
+function parseJSDocText(commentText) {
+  const tags = [];
+  const result = {
+    description: "",
+    params: [],
+    examples: [],
+    rawParamNames: []
+  };
+  const cleanedText = commentText.replace(/^\/\*\*\s*/, "").replace(/\s*\*\/$/, "").replace(/^\s*\* ?/gm, "").replace(/\n\/\s*$/, "");
+  const lines = cleanedText.split(/\n/);
+  let currentTag = "";
+  let currentContent = [];
+  const pushDescription = (line) => {
+    const processed = replaceInlineLinks(line, tags).trimEnd();
+    if (processed.trim()) {
+      result.description = result.description ? `${result.description}
+${processed}` : processed;
+    }
+  };
+  for (const line of lines) {
+    const tagMatch = line.match(/^@(\w+)(?:\s+(.*))?$/);
+    if (tagMatch) {
+      if (currentTag) {
+        processTag(result, tags, currentTag, currentContent.join(String.fromCharCode(10)));
+      }
+      currentTag = tagMatch[1];
+      currentContent = tagMatch[2] ? [tagMatch[2]] : [];
+    } else if (currentTag) {
+      currentContent.push(line);
+    } else {
+      if (line.trim()) {
+        pushDescription(line);
+      }
+    }
+  }
+  if (currentTag) {
+    processTag(result, tags, currentTag, currentContent.join(String.fromCharCode(10)));
+  }
+  if (result.examples && result.examples.length === 0) {
+    delete result.examples;
+  }
+  if (tags.length > 0) {
+    result.tags = tags;
+  }
+  return result;
+}
+function processTag(result, tags, tag, content) {
+  switch (tag) {
+    case "param":
+    case "parameter": {
+      const paramMatch = content.match(/^(?:\{([^}]+)\}\s+)?(\S+)(?:\s+-\s+)?(.*)$/);
+      if (paramMatch) {
+        const [, type, name, description] = paramMatch;
+        const processedDescription = replaceInlineLinks(description || "", tags);
+        const normalizedName = name || "";
+        result.rawParamNames?.push(normalizedName);
+        result.params.push({
+          name: normalizedName,
+          description: processedDescription || "",
+          type
+        });
+      }
+      tags.push({ name: "param", text: content });
+      break;
+    }
+    case "returns":
+    case "return": {
+      const returnMatch = content.match(/^(?:\{([^}]+)\}\s*)?(.*)$/s);
+      const typeText = returnMatch?.[1]?.trim();
+      const descriptionText = replaceInlineLinks(returnMatch?.[2] ?? "", tags).trim();
+      if (typeText) {
+        result.returnsType = typeText;
+      }
+      if (descriptionText) {
+        result.returns = descriptionText;
+      } else if (!result.returns) {
+        result.returns = "";
+      }
+      tags.push({ name: "returns", text: content });
+      break;
+    }
+    case "example": {
+      const example = replaceInlineLinks(content.trim(), tags).trim();
+      if (example) {
+        if (!result.examples) {
+          result.examples = [];
+        }
+        result.examples.push(example);
+      }
+      break;
+    }
+    case "see": {
+      const parts = content.split(",").map((part) => part.trim()).filter(Boolean);
+      for (const part of parts) {
+        const linkTargets = extractLinkTargets(part);
+        if (linkTargets.length > 0) {
+          for (const target of linkTargets) {
+            tags.push({ name: "link", text: target });
+            tags.push({ name: "see", text: target });
+          }
+        } else {
+          tags.push({ name: "see", text: part });
+        }
+      }
+      break;
+    }
+    case "link": {
+      const { target } = parseLinkBody(content.trim());
+      if (target) {
+        tags.push({ name: "link", text: target });
+      }
+      break;
+    }
+    default: {
+      const text = replaceInlineLinks(content, tags).trim();
+      if (text) {
+        tags.push({ name: tag, text });
+      }
+    }
+  }
+}
+function replaceInlineLinks(text, tags, tagName = "link") {
+  return text.replace(/\{@link\s+([^}]+)\}/g, (_match, body) => {
+    const { target, label } = parseLinkBody(body);
+    if (target) {
+      tags.push({ name: tagName, text: target });
+    }
+    return label || target || "";
+  });
+}
+function extractLinkTargets(text) {
+  const targets = [];
+  text.replace(/\{@link\s+([^}]+)\}/g, (_match, body) => {
+    const { target } = parseLinkBody(body);
+    if (target) {
+      targets.push(target);
+    }
+    return "";
+  });
+  return targets;
+}
+function parseLinkBody(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return { target: "" };
+  }
+  const pipeIndex = trimmed.indexOf("|");
+  if (pipeIndex >= 0) {
+    const target2 = trimmed.slice(0, pipeIndex).trim();
+    const label2 = trimmed.slice(pipeIndex + 1).trim();
+    return { target: target2, label: label2 };
+  }
+  const parts = trimmed.split(/\s+/);
+  const target = parts.shift() ?? "";
+  const label = parts.join(" ").trim();
+  return { target, label: label || undefined };
+}
+function extractDestructuredParams(parsedDoc, paramName) {
+  const destructuredParams = new Map;
+  const paramPrefix = `${paramName}.`;
+  for (const param of parsedDoc.params) {
+    if (param.name.startsWith(paramPrefix)) {
+      const propertyName = param.name.substring(paramPrefix.length);
+      destructuredParams.set(propertyName, param.description);
+    } else if (param.name.includes(".") && paramName === "__0") {
+      const [_prefix, propertyName] = param.name.split(".", 2);
+      if (propertyName) {
+        destructuredParams.set(propertyName, param.description);
+      }
+    }
+  }
+  return destructuredParams;
+}
+function getParameterDocumentation(param, paramDecl, typeChecker) {
+  const result = {
+    description: ""
+  };
+  const funcNode = paramDecl.parent;
+  if (ts.isFunctionDeclaration(funcNode) || ts.isFunctionExpression(funcNode)) {
+    const funcSymbol = typeChecker.getSymbolAtLocation(funcNode.name || funcNode);
+    if (funcSymbol) {
+      const parsedDoc = parseJSDocComment(funcSymbol, typeChecker);
+      if (parsedDoc) {
+        const paramName = param.getName();
+        const paramDoc = parsedDoc.params.find((p) => p.name === paramName || p.name.split(".")[0] === paramName);
+        if (paramDoc) {
+          result.description = paramDoc.description;
+        }
+        const destructuredProps = extractDestructuredParams(parsedDoc, paramName);
+        if (destructuredProps.size > 0) {
+          result.destructuredProperties = Array.from(destructuredProps.entries()).map(([name, description]) => ({
+            name,
+            description
+          }));
+        }
+      }
+    }
+  }
+  return result;
+}
+
+// src/utils/type-parameter-utils.ts
+function serializeTypeParameterDeclarations(typeParameters, checker, referencedTypes) {
+  if (!typeParameters || typeParameters.length === 0) {
+    return;
+  }
+  const serialized = [];
+  for (const typeParam of typeParameters) {
+    const name = typeParam.name?.getText().trim();
+    if (!name) {
+      continue;
+    }
+    let constraint;
+    if (typeParam.constraint) {
+      collectReferencedTypesFromNode(typeParam.constraint, checker, referencedTypes);
+      constraint = typeParam.constraint.getText().trim();
+    }
+    let defaultType;
+    if (typeParam.default) {
+      collectReferencedTypesFromNode(typeParam.default, checker, referencedTypes);
+      defaultType = typeParam.default.getText().trim();
+    }
+    serialized.push({
+      name,
+      ...constraint ? { constraint } : {},
+      ...defaultType ? { default: defaultType } : {}
+    });
+  }
+  return serialized.length > 0 ? serialized : undefined;
+}
+
+// src/analysis/ast-utils.ts
+function getJSDocComment(symbol, typeChecker) {
+  const comments = symbol.getDocumentationComment(typeChecker);
+  return ts.displayPartsToString(comments);
+}
+function getSourceLocation(node) {
+  const sourceFile = node.getSourceFile();
+  const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+  return {
+    file: sourceFile.fileName,
+    line: line + 1
+  };
+}
+function isSymbolDeprecated(symbol) {
+  if (!symbol) {
+    return false;
+  }
+  const jsDocTags = symbol.getJsDocTags();
+  if (jsDocTags.some((tag) => tag.name.toLowerCase() === "deprecated")) {
+    return true;
+  }
+  for (const declaration of symbol.getDeclarations() ?? []) {
+    if (ts.getJSDocDeprecatedTag(declaration)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// src/analysis/serializers/presentation.ts
+function extractPresentationMetadata(doc) {
+  if (!doc?.tags || doc.tags.length === 0) {
+    return {};
+  }
+  const findTag = (...names) => {
+    for (const name of names) {
+      const match = doc.tags?.find((tag) => tag.name.toLowerCase() === name.toLowerCase());
+      const text = match?.text.trim();
+      if (text) {
+        return text;
+      }
+    }
+    return;
+  };
+  return {
+    slug: findTag("slug"),
+    displayName: findTag("displayname", "display-name", "title"),
+    category: findTag("category", "group", "module"),
+    importPath: findTag("importpath", "import-path", "import")
+  };
+}
+
+// src/analysis/serializers/classes.ts
+function serializeClass(declaration, symbol, context) {
+  const { checker, typeRegistry } = context;
+  const typeRefs = typeRegistry.getTypeRefs();
+  const referencedTypes = typeRegistry.getReferencedTypes();
+  const members = serializeClassMembers(declaration, checker, typeRefs, referencedTypes);
+  const typeParameters = serializeTypeParameterDeclarations(declaration.typeParameters, checker, referencedTypes);
+  const parsedDoc = parseJSDocComment(symbol, context.checker);
+  const description = parsedDoc?.description ?? getJSDocComment(symbol, context.checker);
+  const metadata = extractPresentationMetadata(parsedDoc);
+  const exportEntry = {
+    id: symbol.getName(),
+    name: symbol.getName(),
+    ...metadata,
+    kind: "class",
+    deprecated: isSymbolDeprecated(symbol),
+    description,
+    source: getSourceLocation(declaration),
+    members: members.length > 0 ? members : undefined,
+    typeParameters,
+    tags: parsedDoc?.tags
+  };
+  const typeDefinition = {
+    id: symbol.getName(),
+    name: symbol.getName(),
+    ...metadata,
+    kind: "class",
+    description,
+    source: getSourceLocation(declaration),
+    members: members.length > 0 ? members : undefined,
+    tags: parsedDoc?.tags
+  };
+  return {
+    exportEntry,
+    typeDefinition
+  };
+}
+function serializeClassMembers(declaration, checker, typeRefs, referencedTypes) {
+  const members = [];
+  for (const member of declaration.members) {
+    if (!member.name && !ts.isConstructorDeclaration(member)) {
+      continue;
+    }
+    if (ts.isPropertyDeclaration(member) || ts.isPropertySignature(member)) {
+      const memberName = member.name?.getText();
+      if (!memberName)
+        continue;
+      const memberSymbol = member.name ? checker.getSymbolAtLocation(member.name) : undefined;
+      const memberDoc = memberSymbol ? parseJSDocComment(memberSymbol, checker) : null;
+      const memberType = memberSymbol ? checker.getTypeOfSymbolAtLocation(memberSymbol, member) : member.type ? checker.getTypeFromTypeNode(member.type) : checker.getTypeAtLocation(member);
+      collectReferencedTypes(memberType, checker, referencedTypes);
+      const schema = formatTypeReference(memberType, checker, typeRefs, referencedTypes);
+      const flags = {};
+      const isOptionalSymbol = memberSymbol != null && (memberSymbol.flags & ts.SymbolFlags.Optional) !== 0;
+      if (member.questionToken || isOptionalSymbol) {
+        flags.optional = true;
+      }
+      if (member.modifiers?.some((mod) => mod.kind === ts.SyntaxKind.ReadonlyKeyword)) {
+        flags.readonly = true;
+      }
+      if (member.modifiers?.some((mod) => mod.kind === ts.SyntaxKind.StaticKeyword)) {
+        flags.static = true;
+      }
+      members.push({
+        id: memberName,
+        name: memberName,
+        kind: "property",
+        visibility: getMemberVisibility(member.modifiers),
+        schema,
+        description: memberDoc?.description ?? (memberSymbol ? getJSDocComment(memberSymbol, checker) : undefined),
+        flags: Object.keys(flags).length > 0 ? flags : undefined,
+        tags: memberDoc?.tags
+      });
+      continue;
+    }
+    if (ts.isMethodDeclaration(member)) {
+      const memberName = member.name?.getText() ?? "method";
+      const memberSymbol = member.name ? checker.getSymbolAtLocation(member.name) : undefined;
+      const methodDoc = memberSymbol ? parseJSDocComment(memberSymbol, checker) : null;
+      const signature = checker.getSignatureFromDeclaration(member);
+      const signatures = signature ? [
+        serializeSignature(signature, checker, typeRefs, referencedTypes, methodDoc, memberSymbol)
+      ] : undefined;
+      members.push({
+        id: memberName,
+        name: memberName,
+        kind: "method",
+        visibility: getMemberVisibility(member.modifiers),
+        signatures,
+        description: methodDoc?.description ?? (memberSymbol ? getJSDocComment(memberSymbol, checker) : undefined),
+        flags: getMethodFlags(member),
+        tags: methodDoc?.tags
+      });
+      continue;
+    }
+    if (ts.isConstructorDeclaration(member)) {
+      const ctorSymbol = checker.getSymbolAtLocation(member);
+      const ctorDoc = ctorSymbol ? parseJSDocComment(ctorSymbol, checker) : null;
+      const signature = checker.getSignatureFromDeclaration(member);
+      const signatures = signature ? [serializeSignature(signature, checker, typeRefs, referencedTypes, ctorDoc, ctorSymbol)] : undefined;
+      members.push({
+        id: "constructor",
+        name: "constructor",
+        kind: "constructor",
+        visibility: getMemberVisibility(member.modifiers),
+        signatures,
+        description: ctorDoc?.description ?? (ctorSymbol ? getJSDocComment(ctorSymbol, checker) : undefined),
+        tags: ctorDoc?.tags
+      });
+      continue;
+    }
+    if (ts.isGetAccessorDeclaration(member) || ts.isSetAccessorDeclaration(member)) {
+      const memberName = member.name?.getText();
+      if (!memberName)
+        continue;
+      const memberSymbol = checker.getSymbolAtLocation(member.name);
+      const memberDoc = memberSymbol ? parseJSDocComment(memberSymbol, checker) : null;
+      const accessorType = ts.isGetAccessorDeclaration(member) ? checker.getTypeAtLocation(member) : member.parameters.length > 0 ? checker.getTypeAtLocation(member.parameters[0]) : checker.getTypeAtLocation(member);
+      collectReferencedTypes(accessorType, checker, referencedTypes);
+      const schema = formatTypeReference(accessorType, checker, typeRefs, referencedTypes);
+      members.push({
+        id: memberName,
+        name: memberName,
+        kind: "accessor",
+        visibility: getMemberVisibility(member.modifiers),
+        schema,
+        description: memberDoc?.description ?? (memberSymbol ? getJSDocComment(memberSymbol, checker) : undefined),
+        tags: memberDoc?.tags
+      });
+    }
+  }
+  return members;
+}
+function serializeSignature(signature, checker, typeRefs, referencedTypes, doc, symbol) {
+  const typeParameters = serializeTypeParameterDeclarations(signature.declaration?.typeParameters, checker, referencedTypes);
+  return {
+    parameters: signature.getParameters().map((param) => {
+      const paramDecl = param.valueDeclaration;
+      const paramType = paramDecl?.type != null ? checker.getTypeFromTypeNode(paramDecl.type) : checker.getTypeAtLocation(paramDecl);
+      collectReferencedTypes(paramType, checker, referencedTypes);
+      const paramDoc = paramDecl ? getParameterDocumentation(param, paramDecl, checker) : undefined;
+      return structureParameter(param, paramDecl, paramType, checker, typeRefs, doc, paramDoc, referencedTypes);
+    }),
+    returns: {
+      schema: formatTypeReference(signature.getReturnType(), checker, typeRefs, referencedTypes),
+      description: doc?.returns || ""
+    },
+    description: doc?.description || (symbol ? getJSDocComment(symbol, checker) : undefined),
+    typeParameters
+  };
+}
+function getMemberVisibility(modifiers) {
+  if (!modifiers)
+    return;
+  if (modifiers.some((mod) => mod.kind === ts.SyntaxKind.PrivateKeyword)) {
+    return "private";
+  }
+  if (modifiers.some((mod) => mod.kind === ts.SyntaxKind.ProtectedKeyword)) {
+    return "protected";
+  }
+  if (modifiers.some((mod) => mod.kind === ts.SyntaxKind.PublicKeyword)) {
+    return "public";
+  }
+  return;
+}
+function getMethodFlags(member) {
+  const flags = {};
+  if (member.modifiers?.some((mod) => mod.kind === ts.SyntaxKind.StaticKeyword)) {
+    flags.static = true;
+  }
+  if (member.asteriskToken) {
+    flags.generator = true;
+  }
+  if (member.questionToken) {
+    flags.optional = true;
+  }
+  return Object.keys(flags).length > 0 ? flags : undefined;
+}
+
+// src/analysis/serializers/enums.ts
+function serializeEnum(declaration, symbol, context) {
+  const parsedDoc = parseJSDocComment(symbol, context.checker);
+  const description = parsedDoc?.description ?? getJSDocComment(symbol, context.checker);
+  const metadata = extractPresentationMetadata(parsedDoc);
+  const exportEntry = {
+    id: symbol.getName(),
+    name: symbol.getName(),
+    ...metadata,
+    kind: "enum",
+    deprecated: isSymbolDeprecated(symbol),
+    description,
+    source: getSourceLocation(declaration),
+    tags: parsedDoc?.tags
+  };
+  const typeDefinition = {
+    id: symbol.getName(),
+    name: symbol.getName(),
+    ...metadata,
+    kind: "enum",
+    members: getEnumMembers(declaration),
+    description,
+    source: getSourceLocation(declaration),
+    tags: parsedDoc?.tags
+  };
+  return {
+    exportEntry,
+    typeDefinition
+  };
+}
+function getEnumMembers(enumDecl) {
+  return enumDecl.members.map((member) => ({
+    id: member.name?.getText() || "",
+    name: member.name?.getText() || "",
+    value: member.initializer ? member.initializer.getText() : undefined,
+    description: ""
+  }));
+}
+
+// src/analysis/serializers/functions.ts
+function serializeCallSignatures(signatures, symbol, context, parsedDoc) {
+  if (signatures.length === 0) {
+    return [];
+  }
+  const { checker, typeRegistry } = context;
+  const typeRefs = typeRegistry.getTypeRefs();
+  const referencedTypes = typeRegistry.getReferencedTypes();
+  const functionDoc = parsedDoc ?? (symbol ? parseJSDocComment(symbol, checker) : null);
+  return signatures.map((signature) => {
+    const parameters = signature.getParameters().map((param) => {
+      const paramDecl = param.declarations?.find(ts.isParameter);
+      const paramType = paramDecl ? paramDecl.type != null ? checker.getTypeFromTypeNode(paramDecl.type) : checker.getTypeAtLocation(paramDecl) : checker.getTypeOfSymbolAtLocation(param, symbol?.declarations?.[0] ?? signature.declaration ?? param.declarations?.[0] ?? param.valueDeclaration);
+      collectReferencedTypes(paramType, checker, referencedTypes);
+      if (paramDecl?.type) {
+        collectReferencedTypesFromNode(paramDecl.type, checker, referencedTypes);
+      }
+      if (paramDecl && ts.isParameter(paramDecl)) {
+        const paramDoc = getParameterDocumentation(param, paramDecl, checker);
+        return structureParameter(param, paramDecl, paramType, checker, typeRefs, functionDoc, paramDoc, referencedTypes);
+      }
+      return {
+        name: param.getName(),
+        required: !(param.flags & ts.SymbolFlags.Optional),
+        description: "",
+        schema: formatTypeReference(paramType, checker, typeRefs, referencedTypes)
+      };
+    });
+    const returnType = signature.getReturnType();
+    const returnTypeText = returnType ? checker.typeToString(returnType) : undefined;
+    if (returnType) {
+      collectReferencedTypes(returnType, checker, referencedTypes);
+    }
+    const typeParameters = serializeTypeParameterDeclarations(signature.declaration?.typeParameters, checker, referencedTypes);
+    return {
+      parameters,
+      returns: {
+        schema: returnType ? formatTypeReference(returnType, checker, typeRefs, referencedTypes) : { type: "void" },
+        description: functionDoc?.returns || "",
+        tsType: returnTypeText
+      },
+      description: functionDoc?.description || undefined,
+      typeParameters
+    };
+  });
+}
+function serializeFunctionExport(declaration, symbol, context) {
+  const { checker } = context;
+  const signature = checker.getSignatureFromDeclaration(declaration);
+  const funcSymbol = checker.getSymbolAtLocation(declaration.name || declaration);
+  const parsedDoc = parseJSDocComment(symbol, checker);
+  const description = parsedDoc?.description ?? getJSDocComment(symbol, checker);
+  const metadata = extractPresentationMetadata(parsedDoc);
+  return {
+    id: symbol.getName(),
+    name: symbol.getName(),
+    ...metadata,
+    kind: "function",
+    deprecated: isSymbolDeprecated(symbol),
+    signatures: signature ? serializeCallSignatures([signature], funcSymbol ?? symbol, context, parsedDoc) : [],
+    description,
+    source: getSourceLocation(declaration),
+    examples: parsedDoc?.examples,
+    tags: parsedDoc?.tags
+  };
+}
+
+// src/analysis/serializers/interfaces.ts
+function serializeInterface(declaration, symbol, context) {
+  const { checker, typeRegistry } = context;
+  const parsedDoc = parseJSDocComment(symbol, checker);
+  const description = parsedDoc?.description ?? getJSDocComment(symbol, checker);
+  const metadata = extractPresentationMetadata(parsedDoc);
+  const referencedTypes = typeRegistry.getReferencedTypes();
+  const typeRefs = typeRegistry.getTypeRefs();
+  const typeParameters = serializeTypeParameterDeclarations(declaration.typeParameters, checker, referencedTypes);
+  const exportEntry = {
+    id: symbol.getName(),
+    name: symbol.getName(),
+    ...metadata,
+    kind: "interface",
+    deprecated: isSymbolDeprecated(symbol),
+    description,
+    source: getSourceLocation(declaration),
+    typeParameters,
+    tags: parsedDoc?.tags
+  };
+  const schema = interfaceToSchema(declaration, checker, typeRefs, referencedTypes);
+  const typeDefinition = {
+    id: symbol.getName(),
+    name: symbol.getName(),
+    ...metadata,
+    kind: "interface",
+    schema,
+    description,
+    source: getSourceLocation(declaration),
+    tags: parsedDoc?.tags
+  };
+  return {
+    exportEntry,
+    typeDefinition
+  };
+}
+function interfaceToSchema(iface, typeChecker, typeRefs, referencedTypes) {
+  const schema = {
+    type: "object",
+    properties: {}
+  };
+  const required = [];
+  for (const prop of iface.members.filter(ts.isPropertySignature)) {
+    const propName = prop.name?.getText() || "";
+    if (prop.type) {
+      const propType = typeChecker.getTypeAtLocation(prop.type);
+      collectReferencedTypes(propType, typeChecker, referencedTypes);
+    }
+    schema.properties[propName] = prop.type ? formatTypeReference(typeChecker.getTypeAtLocation(prop.type), typeChecker, typeRefs, referencedTypes) : { type: "any" };
+    if (!prop.questionToken) {
+      required.push(propName);
+    }
+  }
+  if (required.length > 0) {
+    schema.required = required;
+  }
+  return schema;
+}
+
+// src/analysis/serializers/type-aliases.ts
+function serializeTypeAlias(declaration, symbol, context) {
+  const { checker, typeRegistry } = context;
+  const typeRefs = typeRegistry.getTypeRefs();
+  const referencedTypes = typeRegistry.getReferencedTypes();
+  const parsedDoc = parseJSDocComment(symbol, checker);
+  const description = parsedDoc?.description ?? getJSDocComment(symbol, checker);
+  const metadata = extractPresentationMetadata(parsedDoc);
+  const typeParameters = serializeTypeParameterDeclarations(declaration.typeParameters, checker, referencedTypes);
+  const exportEntry = {
+    id: symbol.getName(),
+    name: symbol.getName(),
+    ...metadata,
+    kind: "type",
+    deprecated: isSymbolDeprecated(symbol),
+    type: typeToRef(declaration.type, checker, typeRefs, referencedTypes),
+    description,
+    source: getSourceLocation(declaration),
+    typeParameters,
+    tags: parsedDoc?.tags
+  };
+  const aliasType = checker.getTypeAtLocation(declaration.type);
+  const aliasName = symbol.getName();
+  const existingRef = typeRefs.get(aliasName);
+  if (existingRef) {
+    typeRefs.delete(aliasName);
+  }
+  const aliasSchema = formatTypeReference(aliasType, checker, typeRefs, undefined);
+  if (existingRef) {
+    typeRefs.set(aliasName, existingRef);
+  }
+  const typeDefinition = {
+    id: symbol.getName(),
+    name: symbol.getName(),
+    ...metadata,
+    kind: "type",
+    description,
+    source: getSourceLocation(declaration),
+    tags: parsedDoc?.tags
+  };
+  if (typeof aliasSchema === "string") {
+    typeDefinition.type = aliasSchema;
+  } else if (aliasSchema && Object.keys(aliasSchema).length > 0) {
+    typeDefinition.schema = aliasSchema;
+  } else {
+    typeDefinition.type = declaration.type.getText();
+  }
+  return {
+    exportEntry,
+    typeDefinition
+  };
+}
+function typeToRef(node, typeChecker, typeRefs, referencedTypes) {
+  const type = typeChecker.getTypeAtLocation(node);
+  collectReferencedTypes(type, typeChecker, referencedTypes);
+  return formatTypeReference(type, typeChecker, typeRefs, referencedTypes);
+}
+
+// src/analysis/serializers/variables.ts
+function serializeVariable(declaration, symbol, context) {
+  const { checker, typeRegistry } = context;
+  const variableType = checker.getTypeAtLocation(declaration.name ?? declaration);
+  const callSignatures = variableType.getCallSignatures();
+  const parsedDoc = parseJSDocComment(symbol, checker);
+  const description = parsedDoc?.description ?? getJSDocComment(symbol, checker);
+  const metadata = extractPresentationMetadata(parsedDoc);
+  if (callSignatures.length > 0) {
+    return {
+      id: symbol.getName(),
+      name: symbol.getName(),
+      ...metadata,
+      kind: "function",
+      deprecated: isSymbolDeprecated(symbol),
+      signatures: serializeCallSignatures(callSignatures, symbol, context, parsedDoc),
+      description,
+      source: getSourceLocation(declaration.initializer ?? declaration),
+      examples: parsedDoc?.examples,
+      tags: parsedDoc?.tags
+    };
+  }
+  const typeRefs = typeRegistry.getTypeRefs();
+  const referencedTypes = typeRegistry.getReferencedTypes();
+  return {
+    id: symbol.getName(),
+    name: symbol.getName(),
+    ...metadata,
+    kind: "variable",
+    deprecated: isSymbolDeprecated(symbol),
+    type: typeToRef2(declaration, checker, typeRefs, referencedTypes),
+    description,
+    source: getSourceLocation(declaration),
+    tags: parsedDoc?.tags
+  };
+}
+function typeToRef2(node, typeChecker, typeRefs, referencedTypes) {
+  const type = typeChecker.getTypeAtLocation(node);
+  collectReferencedTypes(type, typeChecker, referencedTypes);
+  return formatTypeReference(type, typeChecker, typeRefs, referencedTypes);
+}
+
+// src/analysis/type-registry.ts
+class TypeRegistry {
+  typeRefs = new Map;
+  typeDefinitions = new Map;
+  referencedTypes = new Set;
+  registerExportedType(name, id = name) {
+    if (!this.typeRefs.has(name)) {
+      this.typeRefs.set(name, id);
+    }
+  }
+  hasType(name) {
+    return this.typeDefinitions.has(name);
+  }
+  registerTypeDefinition(definition) {
+    if (this.typeDefinitions.has(definition.name)) {
+      return false;
+    }
+    this.typeDefinitions.set(definition.name, definition);
+    if (!this.typeRefs.has(definition.name)) {
+      this.typeRefs.set(definition.name, definition.id);
+    }
+    return true;
+  }
+  getTypeRefs() {
+    return this.typeRefs;
+  }
+  getTypeDefinitions() {
+    return Array.from(this.typeDefinitions.values());
+  }
+  getReferencedTypes() {
+    return this.referencedTypes;
+  }
+  isKnownType(name) {
+    if (this.typeDefinitions.has(name)) {
+      return true;
+    }
+    const ref = this.typeRefs.get(name);
+    if (ref === undefined) {
+      return false;
+    }
+    if (ref !== name) {
+      return this.typeDefinitions.has(ref);
+    }
+    return false;
+  }
+}
+
+// src/analysis/spec-builder.ts
+function buildOpenPkgSpec(context, resolveExternalTypes) {
+  const { baseDir, checker: typeChecker, sourceFile, program } = context;
+  const packageJsonPath = path3.join(baseDir, "package.json");
+  const packageJson = fs.existsSync(packageJsonPath) ? JSON.parse(fs.readFileSync(packageJsonPath, "utf-8")) : {};
+  const spec = {
+    $schema: SCHEMA_URL,
+    openpkg: "0.2.0",
+    meta: {
+      name: packageJson.name || "unknown",
+      version: packageJson.version || "1.0.0",
+      description: packageJson.description || "",
+      license: packageJson.license || "",
+      repository: packageJson.repository?.url || packageJson.repository || "",
+      ecosystem: "js/ts"
+    },
+    exports: [],
+    types: []
+  };
+  const typeRegistry = new TypeRegistry;
+  const serializerContext = {
+    checker: typeChecker,
+    typeRegistry
+  };
+  const moduleSymbol = typeChecker.getSymbolAtLocation(sourceFile);
+  if (!moduleSymbol) {
+    return spec;
+  }
+  const exportedSymbols = typeChecker.getExportsOfModule(moduleSymbol);
+  for (const symbol of exportedSymbols) {
+    const { declaration, targetSymbol } = resolveExportTarget(symbol, typeChecker);
+    if (!declaration)
+      continue;
+    const exportName = symbol.getName();
+    if (ts.isClassDeclaration(declaration) || ts.isInterfaceDeclaration(declaration) || ts.isTypeAliasDeclaration(declaration) || ts.isEnumDeclaration(declaration)) {
+      typeRegistry.registerExportedType(exportName, targetSymbol.getName());
+    }
+  }
+  for (const symbol of exportedSymbols) {
+    const { declaration, targetSymbol } = resolveExportTarget(symbol, typeChecker);
+    if (!declaration)
+      continue;
+    const exportName = symbol.getName();
+    if (ts.isFunctionDeclaration(declaration)) {
+      const exportEntry = serializeFunctionExport(declaration, targetSymbol, serializerContext);
+      addExport(spec, exportEntry, exportName, baseDir);
+    } else if (ts.isClassDeclaration(declaration)) {
+      const { exportEntry, typeDefinition } = serializeClass(declaration, targetSymbol, serializerContext);
+      addExport(spec, exportEntry, exportName, baseDir);
+      addTypeDefinition(spec, typeRegistry, typeDefinition, baseDir);
+    } else if (ts.isInterfaceDeclaration(declaration)) {
+      const { exportEntry, typeDefinition } = serializeInterface(declaration, targetSymbol, serializerContext);
+      addExport(spec, exportEntry, exportName, baseDir);
+      addTypeDefinition(spec, typeRegistry, typeDefinition, baseDir);
+    } else if (ts.isTypeAliasDeclaration(declaration)) {
+      const { exportEntry, typeDefinition } = serializeTypeAlias(declaration, targetSymbol, serializerContext);
+      addExport(spec, exportEntry, exportName, baseDir);
+      addTypeDefinition(spec, typeRegistry, typeDefinition, baseDir);
+    } else if (ts.isEnumDeclaration(declaration)) {
+      const { exportEntry, typeDefinition } = serializeEnum(declaration, targetSymbol, serializerContext);
+      addExport(spec, exportEntry, exportName, baseDir);
+      addTypeDefinition(spec, typeRegistry, typeDefinition, baseDir);
+    } else if (ts.isVariableDeclaration(declaration)) {
+      const exportEntry = serializeVariable(declaration, targetSymbol, serializerContext);
+      addExport(spec, exportEntry, exportName, baseDir);
+    }
+  }
+  for (const typeName of typeRegistry.getReferencedTypes()) {
+    if (typeRegistry.isKnownType(typeName)) {
+      continue;
+    }
+    const allSourceFiles = program.getSourceFiles();
+    for (const file of allSourceFiles) {
+      if (!resolveExternalTypes && (file.fileName.includes("node_modules") || file.fileName.endsWith(".d.ts") && !file.fileName.startsWith(baseDir))) {
+        continue;
+      }
+      const fileSymbol = typeChecker.getSymbolAtLocation(file);
+      if (!fileSymbol) {
+        continue;
+      }
+      const exports = typeChecker.getExportsOfModule(fileSymbol);
+      for (const exportSymbol of exports) {
+        if (exportSymbol.getName() !== typeName || typeRegistry.isKnownType(typeName)) {
+          continue;
+        }
+        const { declaration, targetSymbol } = resolveExportTarget(exportSymbol, typeChecker);
+        if (!declaration)
+          continue;
+        if (ts.isClassDeclaration(declaration)) {
+          const { typeDefinition } = serializeClass(declaration, targetSymbol, serializerContext);
+          addTypeDefinition(spec, typeRegistry, typeDefinition, baseDir);
+        } else if (ts.isInterfaceDeclaration(declaration)) {
+          const { typeDefinition } = serializeInterface(declaration, targetSymbol, serializerContext);
+          addTypeDefinition(spec, typeRegistry, typeDefinition, baseDir);
+        } else if (ts.isTypeAliasDeclaration(declaration)) {
+          const { typeDefinition } = serializeTypeAlias(declaration, targetSymbol, serializerContext);
+          addTypeDefinition(spec, typeRegistry, typeDefinition, baseDir);
+        } else if (ts.isEnumDeclaration(declaration)) {
+          const { typeDefinition } = serializeEnum(declaration, targetSymbol, serializerContext);
+          addTypeDefinition(spec, typeRegistry, typeDefinition, baseDir);
+        }
+      }
+    }
+  }
+  const coverage = computeDocsCoverage(spec);
+  spec.docs = coverage.spec;
+  spec.exports.forEach((entry) => {
+    const exportCoverage = coverage.exports.get(entry.id);
+    if (exportCoverage) {
+      entry.docs = exportCoverage;
+    }
+  });
+  return spec;
+}
+function addExport(spec, entry, exportName, baseDir) {
+  const named = withExportName(entry, exportName);
+  spec.exports.push(applyPresentationDefaults(named, baseDir));
+}
+function addTypeDefinition(spec, typeRegistry, definition, baseDir) {
+  if (!definition) {
+    return;
+  }
+  const enriched = applyPresentationDefaults(definition, baseDir);
+  if (typeRegistry.registerTypeDefinition(enriched)) {
+    spec.types?.push(enriched);
+  }
+}
+function applyPresentationDefaults(entry, baseDir) {
+  const slug = entry.slug ?? createSlug(entry.name);
+  const displayName = entry.displayName ?? entry.name;
+  const category = entry.category ?? entry.kind;
+  const importPath = entry.importPath ?? deriveImportPath(entry.source?.file, baseDir);
+  return {
+    ...entry,
+    ...slug ? { slug } : {},
+    ...displayName ? { displayName } : {},
+    ...category ? { category } : {},
+    ...importPath ? { importPath } : {}
+  };
+}
+function createSlug(name) {
+  const normalized = name.replace(/([a-z\d])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").replace(/[^a-zA-Z0-9-]/g, "-").replace(/--+/g, "-").toLowerCase();
+  return normalized || name.toLowerCase();
+}
+function deriveImportPath(sourceFile, baseDir) {
+  if (!sourceFile) {
+    return;
+  }
+  const relative2 = path3.relative(baseDir, sourceFile);
+  if (!relative2 || relative2.startsWith("..")) {
+    return;
+  }
+  const normalized = relative2.replace(/\\/g, "/");
+  const withoutExt = normalized.replace(/\.[^.]+$/, "");
+  if (!withoutExt) {
+    return;
+  }
+  const prefixed = withoutExt.startsWith(".") ? withoutExt : `./${withoutExt}`;
+  return prefixed.replace(/\/\/+/, "/");
+}
+function resolveExportTarget(symbol, checker) {
+  let targetSymbol = symbol;
+  if (symbol.flags & ts.SymbolFlags.Alias) {
+    const aliasTarget = checker.getImmediateAliasedSymbol(symbol);
+    if (aliasTarget) {
+      targetSymbol = aliasTarget;
+    }
+  }
+  const declarations = targetSymbol.declarations ?? [];
+  const declaration = targetSymbol.valueDeclaration || declarations.find((decl) => decl.kind !== ts.SyntaxKind.ExportSpecifier) || declarations[0];
+  return {
+    declaration,
+    targetSymbol
+  };
+}
+function withExportName(entry, exportName) {
+  if (entry.name === exportName) {
+    return entry;
+  }
+  return {
+    ...entry,
+    id: exportName,
+    name: exportName
+  };
+}
+
+// src/analysis/run-analysis.ts
+function findNearestPackageJson(startDir) {
+  let current = startDir;
+  while (true) {
+    const candidate = path4.join(current, "package.json");
+    if (fs2.existsSync(candidate)) {
+      return candidate;
+    }
+    const parent = path4.dirname(current);
+    if (parent === current) {
+      return;
+    }
+    current = parent;
+  }
+}
+function hasNodeModulesDirectory(directories) {
+  for (const dir of directories) {
+    let current = dir;
+    while (true) {
+      const candidate = path4.join(current, "node_modules");
+      if (fs2.existsSync(candidate)) {
+        return true;
+      }
+      const parent = path4.dirname(current);
+      if (parent === current) {
+        break;
+      }
+      current = parent;
+    }
+  }
+  return false;
+}
+function runAnalysis(input) {
+  const context = createAnalysisContext(input);
+  const { baseDir, options } = context;
+  const packageJsonPath = findNearestPackageJson(baseDir);
+  const searchDirs = new Set([baseDir]);
+  if (packageJsonPath) {
+    searchDirs.add(path4.dirname(packageJsonPath));
+  }
+  const hasNodeModules = hasNodeModulesDirectory(searchDirs);
+  const resolveExternalTypes = options.resolveExternalTypes !== undefined ? options.resolveExternalTypes : hasNodeModules;
+  const diagnostics = ts.getPreEmitDiagnostics(context.program).filter((d) => {
+    if (d.code === 5053)
+      return false;
+    const msg = ts.flattenDiagnosticMessageText(d.messageText, `
+`);
+    return !/allowJs/i.test(msg);
+  });
+  const spec = buildOpenPkgSpec(context, resolveExternalTypes);
+  return {
+    spec,
+    metadata: {
+      baseDir,
+      configPath: context.configPath,
+      packageJsonPath,
+      hasNodeModules,
+      resolveExternalTypes
+    },
+    diagnostics
+  };
+}
+
+// src/extractor.ts
+async function extractPackageSpec(entryFile, packageDir, content, options) {
+  const result = runAnalysis({
+    entryFile,
+    packageDir,
+    content,
+    options
+  });
+  return result.spec;
+}
+// src/openpkg.ts
+import * as fsSync from "node:fs";
+import * as fs3 from "node:fs/promises";
+import * as path5 from "node:path";
+
+// src/filtering/apply-filters.ts
+var TYPE_REF_PREFIX = "#/types/";
+var toLowerKey = (value) => value.trim().toLowerCase();
+var buildLookupMap = (values) => {
+  const map = new Map;
+  if (!values) {
+    return map;
+  }
+  for (const value of values) {
+    const key = toLowerKey(value);
+    if (!map.has(key)) {
+      map.set(key, value);
+    }
+  }
+  return map;
+};
+var matches = (candidate, lookup) => {
+  if (!candidate) {
+    return;
+  }
+  const keys = [candidate.id, candidate.name];
+  for (const key of keys) {
+    if (!key) {
+      continue;
+    }
+    const normalized = toLowerKey(key);
+    if (lookup.has(normalized)) {
+      return normalized;
+    }
+  }
+  return;
+};
+var collectTypeRefs = (value, refs, seen = new Set) => {
+  if (value === null || value === undefined) {
+    return;
+  }
+  if (typeof value !== "object") {
+    return;
+  }
+  if (seen.has(value)) {
+    return;
+  }
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      collectTypeRefs(item, refs, seen);
+    }
+    return;
+  }
+  const record = value;
+  for (const [key, nested] of Object.entries(record)) {
+    if (key === "$ref" && typeof nested === "string" && nested.startsWith(TYPE_REF_PREFIX)) {
+      const typeId = nested.slice(TYPE_REF_PREFIX.length);
+      if (typeId) {
+        refs.add(typeId);
+      }
+    }
+    collectTypeRefs(nested, refs, seen);
+  }
+};
+var applyFilters = (spec, options) => {
+  const includeLookup = buildLookupMap(options.include);
+  const excludeLookup = buildLookupMap(options.exclude);
+  if (includeLookup.size === 0 && excludeLookup.size === 0) {
+    return { spec, diagnostics: [], changed: false };
+  }
+  const includeMatches = new Set;
+  const diagnostics = [];
+  const exportsList = spec.exports ?? [];
+  const typesList = spec.types ?? [];
+  const keptExports = [];
+  for (const entry of exportsList) {
+    const includeMatch = includeLookup.size === 0 ? undefined : matches(entry, includeLookup);
+    const excludeMatch = matches(entry, excludeLookup);
+    const allowedByInclude = includeLookup.size === 0 || Boolean(includeMatch);
+    const allowedByExclude = !excludeMatch;
+    if (includeMatch) {
+      includeMatches.add(includeMatch);
+    }
+    if (allowedByInclude && allowedByExclude) {
+      keptExports.push(entry);
+    }
+  }
+  const typeMap = new Map(typesList.map((typeEntry) => [typeEntry.id, typeEntry]));
+  const requestedTypeIds = new Set;
+  const excludedTypeIds = new Set;
+  for (const typeEntry of typesList) {
+    const includeMatch = includeLookup.size === 0 ? undefined : matches(typeEntry, includeLookup);
+    if (includeMatch) {
+      includeMatches.add(includeMatch);
+      requestedTypeIds.add(typeEntry.id);
+    }
+    const excludeMatch = matches(typeEntry, excludeLookup);
+    if (excludeMatch) {
+      excludedTypeIds.add(typeEntry.id);
+    }
+  }
+  const referencedTypeIds = new Set;
+  for (const entry of keptExports) {
+    collectTypeRefs(entry, referencedTypeIds);
+  }
+  for (const requestedId of requestedTypeIds) {
+    referencedTypeIds.add(requestedId);
+  }
+  const processedTypeIds = new Set;
+  const finalTypeIds = new Set;
+  const excludedButReferenced = new Set;
+  const queue = Array.from(referencedTypeIds);
+  while (queue.length > 0) {
+    const currentId = queue.pop();
+    if (!currentId || processedTypeIds.has(currentId)) {
+      continue;
+    }
+    processedTypeIds.add(currentId);
+    if (excludedTypeIds.has(currentId)) {
+      excludedButReferenced.add(currentId);
+      continue;
+    }
+    if (!typeMap.has(currentId)) {
+      continue;
+    }
+    finalTypeIds.add(currentId);
+    const typeEntry = typeMap.get(currentId);
+    if (typeEntry) {
+      const nestedRefs = new Set;
+      collectTypeRefs(typeEntry, nestedRefs);
+      for (const ref of nestedRefs) {
+        if (!processedTypeIds.has(ref)) {
+          queue.push(ref);
+        }
+      }
+    }
+  }
+  if (includeLookup.size > 0 && keptExports.length === 0 && finalTypeIds.size === 0) {
+    diagnostics.push({
+      message: "Include filters did not match any exports or types.",
+      severity: "warning"
+    });
+  }
+  if (excludedButReferenced.size > 0) {
+    const labels = Array.from(excludedButReferenced).map((id) => {
+      const entry = typeMap.get(id);
+      return entry?.name ?? id;
+    });
+    diagnostics.push({
+      message: `Excluded types are still referenced: ${labels.join(", ")}`,
+      severity: "warning",
+      target: "type"
+    });
+  }
+  const unmatchedIncludes = Array.from(includeLookup.keys()).filter((key) => !includeMatches.has(key));
+  if (unmatchedIncludes.length > 0) {
+    const labels = unmatchedIncludes.map((key) => includeLookup.get(key) ?? key);
+    diagnostics.push({
+      message: `Include filters with no matches: ${labels.join(", ")}`,
+      severity: "warning",
+      target: "type"
+    });
+  }
+  const filteredTypes = typesList.filter((typeEntry) => finalTypeIds.has(typeEntry.id));
+  const baseSpec = {
+    ...spec,
+    exports: keptExports,
+    types: filteredTypes.length > 0 ? filteredTypes : spec.types ? [] : undefined
+  };
+  const filteredSpec = spec.docs ? { ...baseSpec, docs: computeDocsCoverage(baseSpec).spec } : baseSpec;
+  const changed = keptExports.length !== exportsList.length || filteredTypes.length !== typesList.length;
+  return {
+    spec: filteredSpec,
+    diagnostics,
+    changed
+  };
+};
+
+// src/openpkg.ts
+class DocCov {
+  options;
+  constructor(options = {}) {
+    this.options = normalizeDocCovOptions(options);
+  }
+  async analyze(code, fileName = "temp.ts", analyzeOptions = {}) {
+    const resolvedFileName = path5.resolve(fileName);
+    const tempDir = path5.dirname(resolvedFileName);
+    const spec = await extractPackageSpec(resolvedFileName, tempDir, code, this.options);
+    return this.applySpecFilters(spec, analyzeOptions.filters).spec;
+  }
+  async analyzeFile(filePath, analyzeOptions = {}) {
+    const resolvedPath = path5.resolve(filePath);
+    const content = await fs3.readFile(resolvedPath, "utf-8");
+    const packageDir = resolvePackageDir(resolvedPath);
+    const spec = await extractPackageSpec(resolvedPath, packageDir, content, this.options);
+    return this.applySpecFilters(spec, analyzeOptions.filters).spec;
+  }
+  async analyzeProject(entryPath, analyzeOptions = {}) {
+    return this.analyzeFile(entryPath, analyzeOptions);
+  }
+  async analyzeWithDiagnostics(code, fileName, analyzeOptions = {}) {
+    const resolvedFileName = path5.resolve(fileName ?? "temp.ts");
+    const packageDir = resolvePackageDir(resolvedFileName);
+    const analysis = runAnalysis({
+      entryFile: resolvedFileName,
+      packageDir,
+      content: code,
+      options: this.options
+    });
+    const filterOutcome = this.applySpecFilters(analysis.spec, analyzeOptions.filters);
+    return {
+      spec: filterOutcome.spec,
+      diagnostics: [
+        ...analysis.diagnostics.map((diagnostic) => this.normalizeDiagnostic(diagnostic)),
+        ...filterOutcome.diagnostics
+      ],
+      metadata: this.normalizeMetadata(analysis.metadata)
+    };
+  }
+  async analyzeFileWithDiagnostics(filePath, analyzeOptions = {}) {
+    const resolvedPath = path5.resolve(filePath);
+    const content = await fs3.readFile(resolvedPath, "utf-8");
+    const packageDir = resolvePackageDir(resolvedPath);
+    const analysis = runAnalysis({
+      entryFile: resolvedPath,
+      packageDir,
+      content,
+      options: this.options
+    });
+    const filterOutcome = this.applySpecFilters(analysis.spec, analyzeOptions.filters);
+    return {
+      spec: filterOutcome.spec,
+      diagnostics: [
+        ...analysis.diagnostics.map((diagnostic) => this.normalizeDiagnostic(diagnostic)),
+        ...filterOutcome.diagnostics
+      ],
+      metadata: this.normalizeMetadata(analysis.metadata)
+    };
+  }
+  normalizeDiagnostic(tsDiagnostic) {
+    const message = ts.flattenDiagnosticMessageText(tsDiagnostic.messageText, `
+`);
+    let location;
+    if (tsDiagnostic.file && typeof tsDiagnostic.start === "number") {
+      const { line, character } = tsDiagnostic.file.getLineAndCharacterOfPosition(tsDiagnostic.start);
+      location = {
+        file: tsDiagnostic.file.fileName,
+        line: line + 1,
+        column: character + 1
+      };
+    }
+    const severity = this.mapSeverity(tsDiagnostic.category);
+    return {
+      message,
+      severity,
+      location
+    };
+  }
+  mapSeverity(category) {
+    switch (category) {
+      case ts.DiagnosticCategory.Message:
+      case ts.DiagnosticCategory.Suggestion:
+        return "info";
+      case ts.DiagnosticCategory.Warning:
+        return "warning";
+      default:
+        return "error";
+    }
+  }
+  normalizeMetadata(metadata) {
+    return {
+      baseDir: metadata.baseDir,
+      configPath: metadata.configPath,
+      packageJsonPath: metadata.packageJsonPath,
+      hasNodeModules: metadata.hasNodeModules,
+      resolveExternalTypes: metadata.resolveExternalTypes
+    };
+  }
+  applySpecFilters(spec, filters) {
+    if (!filters || !filters.include?.length && !filters.exclude?.length) {
+      return { spec, diagnostics: [] };
+    }
+    const result = applyFilters(spec, filters);
+    return {
+      spec: result.spec,
+      diagnostics: result.diagnostics.map((diagnostic) => ({
+        message: diagnostic.message,
+        severity: diagnostic.severity
+      }))
+    };
+  }
+}
+async function analyze(code, options = {}) {
+  return new DocCov().analyze(code, "temp.ts", options);
+}
+async function analyzeFile(filePath, options = {}) {
+  return new DocCov().analyzeFile(filePath, options);
+}
+var OpenPkg = DocCov;
+function resolvePackageDir(entryFile) {
+  const fallbackDir = path5.dirname(entryFile);
+  let currentDir = fallbackDir;
+  while (true) {
+    const candidate = path5.join(currentDir, "package.json");
+    if (fsSync.existsSync(candidate)) {
+      return currentDir;
+    }
+    const parentDir = path5.dirname(currentDir);
+    if (parentDir === currentDir) {
+      return fallbackDir;
+    }
+    currentDir = parentDir;
+  }
+}
+export {
+  extractPackageSpec,
+  analyzeFile,
+  analyze,
+  OpenPkg,
+  DocCov
+};