@doccov/sdk 0.2.2 → 0.3.1

package/dist/index.js

@@ -1,114 +1,5 @@
-// 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
+import ts from "typescript";
 var DOC_SECTIONS = ["description", "params", "returns", "examples"];
 var SECTION_WEIGHT = 100 / DOC_SECTIONS.length;
 function computeDocsCoverage(spec) {
@@ -147,7 +38,10 @@ function evaluateExport(entry, exportRegistry) {
     ...detectDeprecatedDrift(entry),
     ...detectVisibilityDrift(entry),
     ...detectExampleDrift(entry, exportRegistry),
-    ...detectBrokenLinks(entry, exportRegistry)
+    ...detectBrokenLinks(entry, exportRegistry),
+    ...detectExampleSyntaxErrors(entry),
+    ...detectAsyncMismatch(entry),
+    ...detectPropertyTypeDrift(entry)
   ];
   if (!hasDescription(entry)) {
     missing.push("description");
@@ -202,10 +96,16 @@ function detectParamDrift(entry) {
     return drifts;
   }
   const actualParamNames = new Set;
+  const paramProperties = new Map;
   for (const signature of signatures) {
     for (const param of signature.parameters ?? []) {
       if (param.name) {
         actualParamNames.add(param.name);
+        const schema = param.schema;
+        if (schema?.properties && typeof schema.properties === "object") {
+          const propNames = new Set(Object.keys(schema.properties));
+          paramProperties.set(param.name, propNames);
+        }
       }
     }
   }
@@ -220,6 +120,28 @@ function detectParamDrift(entry) {
     if (actualParamNames.has(documentedName)) {
       continue;
     }
+    if (documentedName.includes(".")) {
+      const [prefix, ...rest] = documentedName.split(".");
+      const propertyPath = rest.join(".");
+      if (actualParamNames.has(prefix)) {
+        const properties = paramProperties.get(prefix);
+        if (properties) {
+          const firstProperty = rest[0];
+          if (properties.has(firstProperty)) {
+            continue;
+          }
+          const suggestion2 = findClosestMatch(firstProperty, Array.from(properties));
+          drifts.push({
+            type: "param-mismatch",
+            target: documentedName,
+            issue: `JSDoc documents property "${propertyPath}" on parameter "${prefix}" which does not exist.`,
+            suggestion: suggestion2?.distance !== undefined && suggestion2.distance <= 3 ? `${prefix}.${suggestion2.value}` : undefined
+          });
+          continue;
+        }
+        continue;
+      }
+    }
     const suggestion = findClosestMatch(documentedName, Array.from(actualParamNames));
     drifts.push({
       type: "param-mismatch",
@@ -865,131 +787,444 @@ function detectBrokenLinks(entry, exportRegistry) {
   }
   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);
-    }
+function detectExampleSyntaxErrors(entry) {
+  if (!entry.examples || entry.examples.length === 0) {
+    return [];
   }
-  if (type.isIntersection()) {
-    for (const intersectionType of type.types) {
-      collectReferencedTypes(intersectionType, typeChecker, referencedTypes, visitedTypes);
+  const drifts = [];
+  for (let i = 0;i < entry.examples.length; i++) {
+    const example = entry.examples[i];
+    if (typeof example !== "string")
+      continue;
+    const codeContent = example.replace(/^```(?:ts|typescript|js|javascript)?\n?/i, "").replace(/\n?```$/i, "").trim();
+    if (!codeContent)
+      continue;
+    const sourceFile = ts.createSourceFile(`example-${i}.ts`, codeContent, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const parseDiagnostics = sourceFile.parseDiagnostics;
+    if (parseDiagnostics && parseDiagnostics.length > 0) {
+      const firstError = parseDiagnostics[0];
+      const message = ts.flattenDiagnosticMessageText(firstError.messageText, `
+`);
+      drifts.push({
+        type: "example-syntax-error",
+        target: `example[${i}]`,
+        issue: `@example contains invalid syntax: ${message}`,
+        suggestion: "Check for missing brackets, semicolons, or typos."
+      });
     }
   }
-  if (type.isUnion()) {
-    for (const unionType of type.types) {
-      collectReferencedTypes(unionType, typeChecker, referencedTypes, visitedTypes);
-    }
+  return drifts;
+}
+function detectExampleRuntimeErrors(entry, runtimeResults) {
+  if (!entry.examples || entry.examples.length === 0 || runtimeResults.size === 0) {
+    return [];
   }
-  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);
-        }
-      }
+  const drifts = [];
+  for (let i = 0;i < entry.examples.length; i++) {
+    const result = runtimeResults.get(i);
+    if (!result || result.success) {
+      continue;
     }
+    const errorMessage = extractErrorMessage(result.stderr);
+    const isTimeout = result.stderr.includes("timed out");
+    drifts.push({
+      type: "example-runtime-error",
+      target: `example[${i}]`,
+      issue: isTimeout ? `@example timed out after ${result.duration}ms.` : `@example throws at runtime: ${errorMessage}`,
+      suggestion: isTimeout ? "Check for infinite loops or long-running operations." : "Fix the example code or update it to match the current API."
+    });
   }
+  return drifts;
 }
-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;
+function extractErrorMessage(stderr) {
+  const lines = stderr.split(`
+`).filter((line) => line.trim());
+  if (lines.length === 0) {
+    return "Unknown error";
   }
-  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);
+  for (const line of lines) {
+    const errorMatch = line.match(/^(?:Error|TypeError|ReferenceError|SyntaxError):\s*(.+)/);
+    if (errorMatch) {
+      return errorMatch[0];
     }
-    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;
+  const firstLine = lines[0] ?? "Unknown error";
+  return firstLine.length > 100 ? `${firstLine.slice(0, 100)}...` : firstLine;
+}
+function detectAsyncMismatch(entry) {
+  const signatures = entry.signatures ?? [];
+  if (signatures.length === 0) {
+    return [];
   }
-  if (ts.isParenthesizedTypeNode(node)) {
-    collectReferencedTypesFromNode(node.type, typeChecker, referencedTypes);
-    return;
+  const drifts = [];
+  const returnsPromise = signatures.some((sig) => {
+    const returnType = sig.returns?.tsType ?? extractTypeFromSchema(sig.returns?.schema) ?? "";
+    return returnType.startsWith("Promise<") || returnType === "Promise";
+  });
+  const returnsTag = entry.tags?.find((tag) => tag.name === "returns" || tag.name === "return");
+  const documentedAsPromise = returnsTag?.text?.includes("Promise") ?? false;
+  const hasAsyncTag = entry.tags?.some((tag) => tag.name === "async");
+  const isAsyncFunction = entry.flags?.async === true;
+  if (returnsPromise && !documentedAsPromise && !hasAsyncTag) {
+    drifts.push({
+      type: "async-mismatch",
+      target: "returns",
+      issue: "Function returns Promise but documentation does not indicate async behavior.",
+      suggestion: "Add @async tag or document @returns {Promise<...>}."
+    });
   }
-  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);
-      }
+  if (!returnsPromise && (documentedAsPromise || hasAsyncTag) && !isAsyncFunction) {
+    drifts.push({
+      type: "async-mismatch",
+      target: "returns",
+      issue: "Documentation indicates async but function does not return Promise.",
+      suggestion: "Remove @async tag or update @returns type."
     });
-    return;
   }
-  if (ts.isTypeOperatorNode(node)) {
-    collectReferencedTypesFromNode(node.type, typeChecker, referencedTypes);
-    return;
+  return drifts;
+}
+function detectPropertyTypeDrift(entry) {
+  const members = entry.members ?? [];
+  if (members.length === 0) {
+    return [];
   }
-  if (ts.isIndexedAccessTypeNode(node)) {
-    collectReferencedTypesFromNode(node.objectType, typeChecker, referencedTypes);
-    collectReferencedTypesFromNode(node.indexType, typeChecker, referencedTypes);
-    return;
+  const drifts = [];
+  for (const member of members) {
+    const typedMember = member;
+    if (typedMember.kind !== "property")
+      continue;
+    const typeTag = typedMember.tags?.find((tag) => tag.name === "type");
+    if (!typeTag?.text)
+      continue;
+    const documentedType = extractTypeFromBraces(typeTag.text);
+    if (!documentedType)
+      continue;
+    const actualType = extractTypeFromSchema(typedMember.schema);
+    if (!actualType)
+      continue;
+    const normalizedDoc = normalizeType(documentedType);
+    const normalizedActual = normalizeType(actualType);
+    if (!normalizedDoc || !normalizedActual)
+      continue;
+    if (!typesEquivalent(normalizedDoc, normalizedActual)) {
+      const memberName = typedMember.name ?? typedMember.id ?? "property";
+      drifts.push({
+        type: "property-type-drift",
+        target: memberName,
+        issue: `Property "${memberName}" documented as {${documentedType}} but actual type is ${actualType}.`,
+        suggestion: `Update @type {${actualType}} to match the declaration.`
+      });
+    }
   }
-  if (ts.isLiteralTypeNode(node)) {
-    return;
+  return drifts;
+}
+function extractTypeFromBraces(text) {
+  const match = text.match(/^\{([^}]+)\}/);
+  return match?.[1]?.trim();
+}
+function parseAssertions(code) {
+  const assertions = [];
+  const cleanCode = code.replace(/^```(?:ts|typescript|js|javascript)?\n?/i, "").replace(/\n?```$/i, "").trim();
+  const lines = cleanCode.split(`
+`);
+  const assertionPattern = /\/\/\s*=>\s*(.+?)\s*$/;
+  for (let i = 0;i < lines.length; i++) {
+    const match = lines[i].match(assertionPattern);
+    if (match?.[1]) {
+      assertions.push({
+        lineNumber: i + 1,
+        expected: match[1].trim()
+      });
+    }
   }
-  node.forEachChild((child) => {
-    if (ts.isTypeNode(child)) {
-      collectReferencedTypesFromNode(child, typeChecker, referencedTypes);
+  return assertions;
+}
+function hasNonAssertionComments(code) {
+  return /\/\/(?!\s*=>)/.test(code);
+}
+function detectExampleAssertionFailures(entry, runtimeResults) {
+  if (!entry.examples || entry.examples.length === 0 || runtimeResults.size === 0) {
+    return [];
+  }
+  const drifts = [];
+  for (let i = 0;i < entry.examples.length; i++) {
+    const example = entry.examples[i];
+    const result = runtimeResults.get(i);
+    if (!result || !result.success || typeof example !== "string") {
+      continue;
     }
-  });
+    const assertions = parseAssertions(example);
+    if (assertions.length === 0) {
+      continue;
+    }
+    const stdoutLines = result.stdout.split(`
+`).map((line) => line.trim()).filter((line) => line.length > 0);
+    for (let j = 0;j < assertions.length; j++) {
+      const assertion = assertions[j];
+      const actual = stdoutLines[j];
+      if (actual === undefined) {
+        drifts.push({
+          type: "example-assertion-failed",
+          target: `example[${i}]:line${assertion.lineNumber}`,
+          issue: `Assertion expected "${assertion.expected}" but no output was produced`,
+          suggestion: "Ensure the example produces output for each assertion"
+        });
+        continue;
+      }
+      if (assertion.expected.trim() !== actual.trim()) {
+        drifts.push({
+          type: "example-assertion-failed",
+          target: `example[${i}]:line${assertion.lineNumber}`,
+          issue: `Assertion failed: expected "${assertion.expected}" but got "${actual}"`,
+          suggestion: `Update assertion to: // => ${actual}`
+        });
+      }
+    }
+  }
+  return drifts;
 }
-function isBuiltInType(name) {
-  const builtIns = [
-    "string",
-    "number",
-    "boolean",
-    "bigint",
-    "symbol",
-    "undefined",
-    "null",
-    "any",
-    "unknown",
-    "never",
+// 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 ts2 = 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: ts2.ScriptTarget.Latest,
+  module: ts2.ModuleKind.CommonJS,
+  lib: ["lib.es2021.d.ts"],
+  declaration: true,
+  moduleResolution: ts2.ModuleResolutionKind.NodeJs
+};
+function createProgram({
+  entryFile,
+  baseDir = path.dirname(entryFile),
+  content
+}) {
+  const configPath = ts2.findConfigFile(baseDir, ts2.sys.fileExists, "tsconfig.json");
+  let compilerOptions = { ...DEFAULT_COMPILER_OPTIONS };
+  if (configPath) {
+    const configFile = ts2.readConfigFile(configPath, ts2.sys.readFile);
+    const parsedConfig = ts2.parseJsonConfigFileContent(configFile.config, ts2.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 = ts2.createCompilerHost(compilerOptions, true);
+  let inMemorySource;
+  if (content !== undefined) {
+    inMemorySource = ts2.createSourceFile(entryFile, content, ts2.ScriptTarget.Latest, true, ts2.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 = ts2.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/utils/type-utils.ts
+function getTypeId(type, typeChecker) {
+  const internalId = type.id;
+  if (internalId !== undefined) {
+    return `id:${internalId}`;
+  }
+  return `str:${typeChecker.typeToString(type)}`;
+}
+function collectReferencedTypes(type, typeChecker, referencedTypes, visitedTypeIds = new Set) {
+  const typeId = getTypeId(type, typeChecker);
+  if (visitedTypeIds.has(typeId))
+    return;
+  visitedTypeIds.add(typeId);
+  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, visitedTypeIds);
+    }
+  }
+  if (type.isUnion()) {
+    for (const unionType of type.types) {
+      collectReferencedTypes(unionType, typeChecker, referencedTypes, visitedTypeIds);
+    }
+  }
+  if (type.flags & ts2.TypeFlags.Object) {
+    const objectType = type;
+    if (objectType.objectFlags & ts2.ObjectFlags.Reference) {
+      const typeRef = objectType;
+      if (typeRef.typeArguments) {
+        for (const typeArg of typeRef.typeArguments) {
+          collectReferencedTypes(typeArg, typeChecker, referencedTypes, visitedTypeIds);
+        }
+      }
+    }
+  }
+}
+function collectReferencedTypesFromNode(node, typeChecker, referencedTypes) {
+  if (ts2.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 (ts2.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 (ts2.isUnionTypeNode(node) || ts2.isIntersectionTypeNode(node)) {
+    node.types.forEach((typeNode) => collectReferencedTypesFromNode(typeNode, typeChecker, referencedTypes));
+    return;
+  }
+  if (ts2.isArrayTypeNode(node)) {
+    collectReferencedTypesFromNode(node.elementType, typeChecker, referencedTypes);
+    return;
+  }
+  if (ts2.isParenthesizedTypeNode(node)) {
+    collectReferencedTypesFromNode(node.type, typeChecker, referencedTypes);
+    return;
+  }
+  if (ts2.isTypeLiteralNode(node)) {
+    node.members.forEach((member) => {
+      if (ts2.isPropertySignature(member) && member.type) {
+        collectReferencedTypesFromNode(member.type, typeChecker, referencedTypes);
+      }
+      if (ts2.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 (ts2.isCallSignatureDeclaration(member) && member.type) {
+        collectReferencedTypesFromNode(member.type, typeChecker, referencedTypes);
+      }
+      if (ts2.isIndexSignatureDeclaration(member) && member.type) {
+        collectReferencedTypesFromNode(member.type, typeChecker, referencedTypes);
+      }
+    });
+    return;
+  }
+  if (ts2.isTypeOperatorNode(node)) {
+    collectReferencedTypesFromNode(node.type, typeChecker, referencedTypes);
+    return;
+  }
+  if (ts2.isIndexedAccessTypeNode(node)) {
+    collectReferencedTypesFromNode(node.objectType, typeChecker, referencedTypes);
+    collectReferencedTypesFromNode(node.indexType, typeChecker, referencedTypes);
+    return;
+  }
+  if (ts2.isLiteralTypeNode(node)) {
+    return;
+  }
+  node.forEachChild((child) => {
+    if (ts2.isTypeNode(child)) {
+      collectReferencedTypesFromNode(child, typeChecker, referencedTypes);
+    }
+  });
+}
+function isBuiltInType(name) {
+  const builtIns = [
+    "string",
+    "number",
+    "boolean",
+    "bigint",
+    "symbol",
+    "undefined",
+    "null",
+    "any",
+    "unknown",
+    "never",
     "void",
     "object",
     "Array",
@@ -1061,11 +1296,11 @@ var BUILTIN_TYPE_SCHEMAS = {
   BigUint64Array: { type: "string", format: "byte" }
 };
 function isObjectLiteralType(type) {
-  if (!(type.getFlags() & ts.TypeFlags.Object)) {
+  if (!(type.getFlags() & ts2.TypeFlags.Object)) {
     return false;
   }
   const objectFlags = type.objectFlags;
-  return (objectFlags & ts.ObjectFlags.ObjectLiteral) !== 0;
+  return (objectFlags & ts2.ObjectFlags.ObjectLiteral) !== 0;
 }
 function isPureRefSchema(value) {
   return Object.keys(value).length === 1 && "$ref" in value;
@@ -1119,28 +1354,28 @@ function propertiesToSchema(properties, description) {
   return schema;
 }
 function buildSchemaFromTypeNode(node, typeChecker, typeRefs, referencedTypes, functionDoc, parentParamName) {
-  if (ts.isParenthesizedTypeNode(node)) {
+  if (ts2.isParenthesizedTypeNode(node)) {
     return buildSchemaFromTypeNode(node.type, typeChecker, typeRefs, referencedTypes, functionDoc ?? null, parentParamName);
   }
-  if (ts.isIntersectionTypeNode(node)) {
+  if (ts2.isIntersectionTypeNode(node)) {
     const schemas = node.types.map((type) => buildSchemaFromTypeNode(type, typeChecker, typeRefs, referencedTypes, functionDoc, parentParamName));
     return { allOf: schemas };
   }
-  if (ts.isUnionTypeNode(node)) {
+  if (ts2.isUnionTypeNode(node)) {
     const schemas = node.types.map((type) => buildSchemaFromTypeNode(type, typeChecker, typeRefs, referencedTypes, functionDoc, parentParamName));
     return { anyOf: schemas };
   }
-  if (ts.isArrayTypeNode(node)) {
+  if (ts2.isArrayTypeNode(node)) {
     return {
       type: "array",
       items: buildSchemaFromTypeNode(node.elementType, typeChecker, typeRefs, referencedTypes, functionDoc, parentParamName)
     };
   }
-  if (ts.isTypeLiteralNode(node)) {
+  if (ts2.isTypeLiteralNode(node)) {
     const properties = {};
     const required = [];
     for (const member of node.members) {
-      if (!ts.isPropertySignature(member) || !member.name) {
+      if (!ts2.isPropertySignature(member) || !member.name) {
         continue;
       }
       const propName = member.name.getText();
@@ -1178,7 +1413,7 @@ function buildSchemaFromTypeNode(node, typeChecker, typeRefs, referencedTypes, f
     }
     return schema;
   }
-  if (ts.isTypeReferenceNode(node)) {
+  if (ts2.isTypeReferenceNode(node)) {
     const typeName = node.typeName.getText();
     if (typeName === "Array") {
       return { type: "array" };
@@ -1196,15 +1431,15 @@ function buildSchemaFromTypeNode(node, typeChecker, typeRefs, referencedTypes, f
     referencedTypes?.add(typeName);
     return { $ref: `#/types/${typeName}` };
   }
-  if (ts.isLiteralTypeNode(node)) {
-    if (ts.isStringLiteral(node.literal)) {
+  if (ts2.isLiteralTypeNode(node)) {
+    if (ts2.isStringLiteral(node.literal)) {
       return { enum: [node.literal.text] };
     }
-    if (ts.isNumericLiteral(node.literal)) {
+    if (ts2.isNumericLiteral(node.literal)) {
       return { enum: [Number(node.literal.text)] };
     }
   }
-  if (ts.isIntersectionTypeNode(node)) {
+  if (ts2.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);
@@ -1228,16 +1463,67 @@ function buildSchemaFromTypeNode(node, typeChecker, typeRefs, referencedTypes, f
   }
   return { type: node.getText() };
 }
-function getDocDescriptionForProperty(functionDoc, parentParamName, propName) {
+function getDocDescriptionForProperty(functionDoc, parentParamName, propName, inferredAlias) {
   if (!functionDoc) {
     return;
   }
-  let match = functionDoc.params.find((p) => p.name === `${parentParamName}.${propName}`);
-  if (!match) {
-    match = functionDoc.params.find((p) => p.name.endsWith(`.${propName}`));
-  }
+  let match = functionDoc.params.find((p) => p.name === `${parentParamName}.${propName}` || inferredAlias && p.name === `${inferredAlias}.${propName}` || parentParamName.match(/^__\d+$/) && p.name.endsWith(`.${propName}`));
   return match?.description;
 }
+function findDiscriminatorProperty(unionTypes, typeChecker) {
+  const memberProps = [];
+  for (const t of unionTypes) {
+    if (t.flags & (ts2.TypeFlags.Null | ts2.TypeFlags.Undefined)) {
+      continue;
+    }
+    const props = t.getProperties();
+    if (!props || props.length === 0) {
+      return;
+    }
+    const propValues = new Map;
+    for (const prop of props) {
+      const declaration = prop.valueDeclaration ?? prop.declarations?.[0];
+      if (!declaration) {
+        continue;
+      }
+      try {
+        const propType = typeChecker.getTypeOfSymbolAtLocation(prop, declaration);
+        if (propType.isStringLiteral()) {
+          propValues.set(prop.getName(), propType.value);
+        } else if (propType.isNumberLiteral()) {
+          propValues.set(prop.getName(), propType.value);
+        }
+      } catch {
+        continue;
+      }
+    }
+    memberProps.push(propValues);
+  }
+  if (memberProps.length < 2) {
+    return;
+  }
+  const firstMember = memberProps[0];
+  for (const [propName, firstValue] of firstMember) {
+    const values = new Set([firstValue]);
+    let isDiscriminator = true;
+    for (let i = 1;i < memberProps.length; i++) {
+      const value = memberProps[i].get(propName);
+      if (value === undefined) {
+        isDiscriminator = false;
+        break;
+      }
+      if (values.has(value)) {
+        isDiscriminator = false;
+        break;
+      }
+      values.add(value);
+    }
+    if (isDiscriminator) {
+      return propName;
+    }
+  }
+  return;
+}
 function schemaIsAny(schema) {
   if (typeof schema === "string") {
     return schema === "any";
@@ -1316,9 +1602,25 @@ function formatTypeReference(type, typeChecker, typeRefs, referencedTypes, visit
       }
       return { type: typeString };
     }
+    if (type.getFlags() & ts2.TypeFlags.Object) {
+      const objectType = type;
+      if (objectType.objectFlags & ts2.ObjectFlags.Mapped) {
+        return { type: "object", tsType: typeString };
+      }
+    }
+    if (type.flags & ts2.TypeFlags.Conditional) {
+      return { type: "object", tsType: typeString };
+    }
     if (type.isUnion()) {
       const unionType = type;
       const parts = unionType.types.map((t) => formatTypeReference(t, typeChecker, typeRefs, referencedTypes, visited));
+      const discriminatorProp = findDiscriminatorProperty(unionType.types, typeChecker);
+      if (discriminatorProp) {
+        return {
+          anyOf: parts,
+          discriminator: { propertyName: discriminatorProp }
+        };
+      }
       return {
         anyOf: parts
       };
@@ -1346,7 +1648,7 @@ function formatTypeReference(type, typeChecker, typeRefs, referencedTypes, visit
     if (symbol) {
       const symbolName = symbol.getName();
       if (symbolName.startsWith("__")) {
-        if (type.getFlags() & ts.TypeFlags.Object) {
+        if (type.getFlags() & ts2.TypeFlags.Object) {
           const properties = type.getProperties();
           if (properties.length > 0) {
             const objSchema = {
@@ -1358,7 +1660,7 @@ function formatTypeReference(type, typeChecker, typeRefs, referencedTypes, visit
               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)) {
+              if (!(prop.flags & ts2.SymbolFlags.Optional)) {
                 required.push(propName);
               }
             }
@@ -1418,7 +1720,7 @@ function formatTypeReference(type, typeChecker, typeRefs, referencedTypes, visit
 }
 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);
+  const isDestructured = paramName === "__0" || ts2.isObjectBindingPattern(paramDecl.name) || ts2.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);
@@ -1443,10 +1745,8 @@ function structureParameter(param, paramDecl, paramType, typeChecker, typeRefs,
           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()}`));
-            }
+            const propName = prop.getName();
+            let docParam = functionDoc.params.find((p) => p.name === `${paramName}.${propName}` || inferredAlias && p.name === `${inferredAlias}.${propName}` || paramName.match(/^__\d+$/) && p.name.endsWith(`.${propName}`));
             if (docParam) {
               description = docParam.description;
             }
@@ -1455,7 +1755,7 @@ function structureParameter(param, paramDecl, paramType, typeChecker, typeRefs,
             name: prop.getName(),
             type: formatTypeReference(propType, typeChecker, typeRefs, referencedTypes),
             description,
-            optional: !!(prop.flags & ts.SymbolFlags.Optional)
+            optional: !!(prop.flags & ts2.SymbolFlags.Optional)
           });
         }
       } else if (symbol2) {
@@ -1467,7 +1767,7 @@ function structureParameter(param, paramDecl, paramType, typeChecker, typeRefs,
               name: prop.getName(),
               type: formatTypeReference(propType, typeChecker, typeRefs, referencedTypes),
               description: "",
-              optional: !!(prop.flags & ts.SymbolFlags.Optional)
+              optional: !!(prop.flags & ts2.SymbolFlags.Optional)
             });
           }
         }
@@ -1498,7 +1798,7 @@ function structureParameter(param, paramDecl, paramType, typeChecker, typeRefs,
             name: prop.getName(),
             type: formatTypeReference(propType, typeChecker, typeRefs, referencedTypes),
             description: "",
-            optional: !!(prop.flags & ts.SymbolFlags.Optional)
+            optional: !!(prop.flags & ts2.SymbolFlags.Optional)
           });
         }
         if (properties.length > 0) {
@@ -1532,7 +1832,7 @@ function structureParameter(param, paramDecl, paramType, typeChecker, typeRefs,
         name: prop.getName(),
         type: formatTypeReference(propType, typeChecker, typeRefs, referencedTypes),
         description: "",
-        optional: !!(prop.flags & ts.SymbolFlags.Optional)
+        optional: !!(prop.flags & ts2.SymbolFlags.Optional)
       });
     }
     const readableName2 = fallbackName;
@@ -1546,7 +1846,7 @@ function structureParameter(param, paramDecl, paramType, typeChecker, typeRefs,
     }
     return out2;
   }
-  if (paramType.flags & ts.TypeFlags.Any && paramDecl.type && paramDecl.name && ts.isObjectBindingPattern(paramDecl.name)) {
+  if (paramType.flags & ts2.TypeFlags.Any && paramDecl.type && paramDecl.name && ts2.isObjectBindingPattern(paramDecl.name)) {
     const actualName = fallbackName;
     const schema2 = buildSchemaFromTypeNode(paramDecl.type, typeChecker, typeRefs, referencedTypes, functionDoc ?? null, param.getName());
     const out2 = {
@@ -1599,21 +1899,56 @@ function structureParameter(param, paramDecl, paramType, typeChecker, typeRefs,
   if (docDescription) {
     out.description = docDescription;
   }
+  if (paramDecl.initializer) {
+    const defaultText = paramDecl.initializer.getText();
+    if (ts2.isStringLiteral(paramDecl.initializer)) {
+      out.default = paramDecl.initializer.text;
+    } else if (ts2.isNumericLiteral(paramDecl.initializer)) {
+      out.default = Number(paramDecl.initializer.text);
+    } else if (paramDecl.initializer.kind === ts2.SyntaxKind.TrueKeyword || paramDecl.initializer.kind === ts2.SyntaxKind.FalseKeyword) {
+      out.default = paramDecl.initializer.kind === ts2.SyntaxKind.TrueKeyword;
+    } else if (paramDecl.initializer.kind === ts2.SyntaxKind.NullKeyword) {
+      out.default = null;
+    } else {
+      out.default = defaultText;
+    }
+  }
+  if (paramDecl.dotDotDotToken) {
+    out.rest = true;
+  }
   return out;
 }
 
 // src/utils/tsdoc-utils.ts
+function findJSDocComment(commentRanges, sourceText) {
+  if (!commentRanges || commentRanges.length === 0) {
+    return;
+  }
+  for (let i = commentRanges.length - 1;i >= 0; i--) {
+    const range = commentRanges[i];
+    const text = sourceText.substring(range.pos, range.end);
+    if (text.startsWith("/**")) {
+      return range;
+    }
+  }
+  return;
+}
 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) {
+  let jsdocComment = findJSDocComment(ts2.getLeadingCommentRanges(sourceFile.text, node.pos), sourceFile.text);
+  if (!jsdocComment && ts2.isVariableDeclaration(node) && node.parent?.parent) {
+    const statement = node.parent.parent;
+    if (ts2.isVariableStatement(statement)) {
+      jsdocComment = findJSDocComment(ts2.getLeadingCommentRanges(sourceFile.text, statement.pos), sourceFile.text);
+    }
+  }
+  if (!jsdocComment) {
     return null;
   }
-  const lastComment = commentRanges[commentRanges.length - 1];
-  const commentText = sourceFile.text.substring(lastComment.pos, lastComment.end);
+  const commentText = sourceFile.text.substring(jsdocComment.pos, jsdocComment.end);
   return parseJSDocText(commentText);
 }
 function parseJSDocText(commentText) {
@@ -1794,7 +2129,7 @@ function getParameterDocumentation(param, paramDecl, typeChecker) {
     description: ""
   };
   const funcNode = paramDecl.parent;
-  if (ts.isFunctionDeclaration(funcNode) || ts.isFunctionExpression(funcNode)) {
+  if (ts2.isFunctionDeclaration(funcNode) || ts2.isFunctionExpression(funcNode)) {
     const funcSymbol = typeChecker.getSymbolAtLocation(funcNode.name || funcNode);
     if (funcSymbol) {
       const parsedDoc = parseJSDocComment(funcSymbol, typeChecker);
@@ -1850,7 +2185,7 @@ function serializeTypeParameterDeclarations(typeParameters, checker, referencedT
 // src/analysis/ast-utils.ts
 function getJSDocComment(symbol, typeChecker) {
   const comments = symbol.getDocumentationComment(typeChecker);
-  return ts.displayPartsToString(comments);
+  return ts2.displayPartsToString(comments);
 }
 function getSourceLocation(node) {
   const sourceFile = node.getSourceFile();
@@ -1869,7 +2204,7 @@ function isSymbolDeprecated(symbol) {
     return true;
   }
   for (const declaration of symbol.getDeclarations() ?? []) {
-    if (ts.getJSDocDeprecatedTag(declaration)) {
+    if (ts2.getJSDocDeprecatedTag(declaration)) {
       return true;
     }
   }
@@ -1906,6 +2241,7 @@ function serializeClass(declaration, symbol, context) {
   const referencedTypes = typeRegistry.getReferencedTypes();
   const members = serializeClassMembers(declaration, checker, typeRefs, referencedTypes);
   const typeParameters = serializeTypeParameterDeclarations(declaration.typeParameters, checker, referencedTypes);
+  const heritage = extractHeritageInfo(declaration, checker, referencedTypes);
   const parsedDoc = parseJSDocComment(symbol, context.checker);
   const description = parsedDoc?.description ?? getJSDocComment(symbol, context.checker);
   const metadata = extractPresentationMetadata(parsedDoc);
@@ -1919,7 +2255,10 @@ function serializeClass(declaration, symbol, context) {
     source: getSourceLocation(declaration),
     members: members.length > 0 ? members : undefined,
     typeParameters,
-    tags: parsedDoc?.tags
+    ...heritage.extends ? { extends: heritage.extends } : {},
+    ...heritage.implements && heritage.implements.length > 0 ? { implements: heritage.implements } : {},
+    tags: parsedDoc?.tags,
+    examples: parsedDoc?.examples
   };
   const typeDefinition = {
     id: symbol.getName(),
@@ -1929,6 +2268,8 @@ function serializeClass(declaration, symbol, context) {
     description,
     source: getSourceLocation(declaration),
     members: members.length > 0 ? members : undefined,
+    ...heritage.extends ? { extends: heritage.extends } : {},
+    ...heritage.implements && heritage.implements.length > 0 ? { implements: heritage.implements } : {},
     tags: parsedDoc?.tags
   };
   return {
@@ -1936,13 +2277,53 @@ function serializeClass(declaration, symbol, context) {
     typeDefinition
   };
 }
+function extractHeritageInfo(declaration, checker, referencedTypes) {
+  const result = {};
+  if (!declaration.heritageClauses) {
+    return result;
+  }
+  for (const clause of declaration.heritageClauses) {
+    if (clause.token === ts2.SyntaxKind.ExtendsKeyword) {
+      const baseType = clause.types[0];
+      if (baseType) {
+        result.extends = baseType.expression.getText();
+        collectReferencedTypesFromNode(baseType, checker, referencedTypes);
+      }
+    } else if (clause.token === ts2.SyntaxKind.ImplementsKeyword) {
+      result.implements = clause.types.map((type) => {
+        collectReferencedTypesFromNode(type, checker, referencedTypes);
+        return type.expression.getText();
+      });
+    }
+  }
+  return result;
+}
 function serializeClassMembers(declaration, checker, typeRefs, referencedTypes) {
   const members = [];
+  const accessorMap = new Map;
   for (const member of declaration.members) {
-    if (!member.name && !ts.isConstructorDeclaration(member)) {
-      continue;
-    }
-    if (ts.isPropertyDeclaration(member) || ts.isPropertySignature(member)) {
+    if (ts2.isGetAccessorDeclaration(member)) {
+      const name = member.name?.getText();
+      if (name) {
+        const existing = accessorMap.get(name) || {};
+        existing.get = member;
+        accessorMap.set(name, existing);
+      }
+    } else if (ts2.isSetAccessorDeclaration(member)) {
+      const name = member.name?.getText();
+      if (name) {
+        const existing = accessorMap.get(name) || {};
+        existing.set = member;
+        accessorMap.set(name, existing);
+      }
+    }
+  }
+  const processedAccessors = new Set;
+  for (const member of declaration.members) {
+    if (!member.name && !ts2.isConstructorDeclaration(member)) {
+      continue;
+    }
+    if (ts2.isPropertyDeclaration(member) || ts2.isPropertySignature(member)) {
       const memberName = member.name?.getText();
       if (!memberName)
         continue;
@@ -1952,14 +2333,14 @@ function serializeClassMembers(declaration, checker, typeRefs, referencedTypes)
       collectReferencedTypes(memberType, checker, referencedTypes);
       const schema = formatTypeReference(memberType, checker, typeRefs, referencedTypes);
       const flags = {};
-      const isOptionalSymbol = memberSymbol != null && (memberSymbol.flags & ts.SymbolFlags.Optional) !== 0;
+      const isOptionalSymbol = memberSymbol != null && (memberSymbol.flags & ts2.SymbolFlags.Optional) !== 0;
       if (member.questionToken || isOptionalSymbol) {
         flags.optional = true;
       }
-      if (member.modifiers?.some((mod) => mod.kind === ts.SyntaxKind.ReadonlyKeyword)) {
+      if (member.modifiers?.some((mod) => mod.kind === ts2.SyntaxKind.ReadonlyKeyword)) {
         flags.readonly = true;
       }
-      if (member.modifiers?.some((mod) => mod.kind === ts.SyntaxKind.StaticKeyword)) {
+      if (member.modifiers?.some((mod) => mod.kind === ts2.SyntaxKind.StaticKeyword)) {
         flags.static = true;
       }
       members.push({
@@ -1974,7 +2355,7 @@ function serializeClassMembers(declaration, checker, typeRefs, referencedTypes)
       });
       continue;
     }
-    if (ts.isMethodDeclaration(member)) {
+    if (ts2.isMethodDeclaration(member)) {
       const memberName = member.name?.getText() ?? "method";
       const memberSymbol = member.name ? checker.getSymbolAtLocation(member.name) : undefined;
       const methodDoc = memberSymbol ? parseJSDocComment(memberSymbol, checker) : null;
@@ -1994,7 +2375,7 @@ function serializeClassMembers(declaration, checker, typeRefs, referencedTypes)
       });
       continue;
     }
-    if (ts.isConstructorDeclaration(member)) {
+    if (ts2.isConstructorDeclaration(member)) {
       const ctorSymbol = checker.getSymbolAtLocation(member);
       const ctorDoc = ctorSymbol ? parseJSDocComment(ctorSymbol, checker) : null;
       const signature = checker.getSignatureFromDeclaration(member);
@@ -2010,22 +2391,35 @@ function serializeClassMembers(declaration, checker, typeRefs, referencedTypes)
       });
       continue;
     }
-    if (ts.isGetAccessorDeclaration(member) || ts.isSetAccessorDeclaration(member)) {
+    if (ts2.isGetAccessorDeclaration(member) || ts2.isSetAccessorDeclaration(member)) {
       const memberName = member.name?.getText();
-      if (!memberName)
+      if (!memberName || processedAccessors.has(memberName))
+        continue;
+      processedAccessors.add(memberName);
+      const accessorPair = accessorMap.get(memberName);
+      const hasGetter = !!accessorPair?.get;
+      const hasSetter = !!accessorPair?.set;
+      const primaryMember = accessorPair?.get || accessorPair?.set;
+      if (!primaryMember)
         continue;
-      const memberSymbol = checker.getSymbolAtLocation(member.name);
+      const memberSymbol = checker.getSymbolAtLocation(primaryMember.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);
+      const accessorType = accessorPair?.get ? checker.getTypeAtLocation(accessorPair.get) : accessorPair?.set && accessorPair.set.parameters.length > 0 ? checker.getTypeAtLocation(accessorPair.set.parameters[0]) : checker.getTypeAtLocation(primaryMember);
       collectReferencedTypes(accessorType, checker, referencedTypes);
       const schema = formatTypeReference(accessorType, checker, typeRefs, referencedTypes);
+      const flags = {};
+      if (hasGetter)
+        flags.readable = true;
+      if (hasSetter)
+        flags.writable = true;
       members.push({
         id: memberName,
         name: memberName,
         kind: "accessor",
-        visibility: getMemberVisibility(member.modifiers),
+        visibility: getMemberVisibility(primaryMember.modifiers),
         schema,
         description: memberDoc?.description ?? (memberSymbol ? getJSDocComment(memberSymbol, checker) : undefined),
+        flags: Object.keys(flags).length > 0 ? flags : undefined,
         tags: memberDoc?.tags
       });
     }
@@ -2053,20 +2447,20 @@ function serializeSignature(signature, checker, typeRefs, referencedTypes, doc,
 function getMemberVisibility(modifiers) {
   if (!modifiers)
     return;
-  if (modifiers.some((mod) => mod.kind === ts.SyntaxKind.PrivateKeyword)) {
+  if (modifiers.some((mod) => mod.kind === ts2.SyntaxKind.PrivateKeyword)) {
     return "private";
   }
-  if (modifiers.some((mod) => mod.kind === ts.SyntaxKind.ProtectedKeyword)) {
+  if (modifiers.some((mod) => mod.kind === ts2.SyntaxKind.ProtectedKeyword)) {
     return "protected";
   }
-  if (modifiers.some((mod) => mod.kind === ts.SyntaxKind.PublicKeyword)) {
+  if (modifiers.some((mod) => mod.kind === ts2.SyntaxKind.PublicKeyword)) {
     return "public";
   }
   return;
 }
 function getMethodFlags(member) {
   const flags = {};
-  if (member.modifiers?.some((mod) => mod.kind === ts.SyntaxKind.StaticKeyword)) {
+  if (member.modifiers?.some((mod) => mod.kind === ts2.SyntaxKind.StaticKeyword)) {
     flags.static = true;
   }
   if (member.asteriskToken) {
@@ -2091,7 +2485,8 @@ function serializeEnum(declaration, symbol, context) {
     deprecated: isSymbolDeprecated(symbol),
     description,
     source: getSourceLocation(declaration),
-    tags: parsedDoc?.tags
+    tags: parsedDoc?.tags,
+    examples: parsedDoc?.examples
   };
   const typeDefinition = {
     id: symbol.getName(),
@@ -2128,19 +2523,19 @@ function serializeCallSignatures(signatures, symbol, context, parsedDoc) {
   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 paramDecl = param.declarations?.find(ts2.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)) {
+      if (paramDecl && ts2.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),
+        required: !(param.flags & ts2.SymbolFlags.Optional),
         description: "",
         schema: formatTypeReference(paramType, checker, typeRefs, referencedTypes)
       };
@@ -2151,12 +2546,25 @@ function serializeCallSignatures(signatures, symbol, context, parsedDoc) {
       collectReferencedTypes(returnType, checker, referencedTypes);
     }
     const typeParameters = serializeTypeParameterDeclarations(signature.declaration?.typeParameters, checker, referencedTypes);
+    const typePredicate = checker.getTypePredicateOfSignature(signature);
+    let typePredicateInfo;
+    if (typePredicate) {
+      const paramName = typePredicate.kind === ts2.TypePredicateKind.This || typePredicate.kind === ts2.TypePredicateKind.AssertsThis ? "this" : typePredicate.parameterName ?? "";
+      const predicateType = typePredicate.type ? checker.typeToString(typePredicate.type) : undefined;
+      const isAsserts = typePredicate.kind === ts2.TypePredicateKind.AssertsThis || typePredicate.kind === ts2.TypePredicateKind.AssertsIdentifier;
+      typePredicateInfo = {
+        parameterName: paramName,
+        type: predicateType ?? "unknown",
+        ...isAsserts ? { asserts: true } : {}
+      };
+    }
     return {
       parameters,
       returns: {
         schema: returnType ? formatTypeReference(returnType, checker, typeRefs, referencedTypes) : { type: "void" },
         description: functionDoc?.returns || "",
-        tsType: returnTypeText
+        tsType: returnTypeText,
+        ...typePredicateInfo ? { typePredicate: typePredicateInfo } : {}
       },
       description: functionDoc?.description || undefined,
       typeParameters
@@ -2165,18 +2573,19 @@ function serializeCallSignatures(signatures, symbol, context, parsedDoc) {
 }
 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);
+  const type = checker.getTypeAtLocation(declaration.name || declaration);
+  const callSignatures = type.getCallSignatures();
   return {
     id: symbol.getName(),
     name: symbol.getName(),
     ...metadata,
     kind: "function",
     deprecated: isSymbolDeprecated(symbol),
-    signatures: signature ? serializeCallSignatures([signature], funcSymbol ?? symbol, context, parsedDoc) : [],
+    signatures: callSignatures.length > 0 ? serializeCallSignatures(callSignatures, funcSymbol ?? symbol, context, parsedDoc) : [],
     description,
     source: getSourceLocation(declaration),
     examples: parsedDoc?.examples,
@@ -2202,7 +2611,8 @@ function serializeInterface(declaration, symbol, context) {
     description,
     source: getSourceLocation(declaration),
     typeParameters,
-    tags: parsedDoc?.tags
+    tags: parsedDoc?.tags,
+    examples: parsedDoc?.examples
   };
   const schema = interfaceToSchema(declaration, checker, typeRefs, referencedTypes);
   const typeDefinition = {
@@ -2226,23 +2636,244 @@ function interfaceToSchema(iface, typeChecker, typeRefs, referencedTypes) {
     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);
+  const callSignatures = [];
+  const constructSignatures = [];
+  for (const member of iface.members) {
+    if (ts2.isIndexSignatureDeclaration(member)) {
+      const indexParam = member.parameters[0];
+      if (indexParam && member.type) {
+        const indexType = typeChecker.getTypeAtLocation(indexParam);
+        const valueType = typeChecker.getTypeAtLocation(member.type);
+        collectReferencedTypes(valueType, typeChecker, referencedTypes);
+        const valueSchema = formatTypeReference(valueType, typeChecker, typeRefs, referencedTypes);
+        const indexTypeString = typeChecker.typeToString(indexType);
+        if (indexTypeString === "string") {
+          schema.additionalProperties = valueSchema;
+        } else if (indexTypeString === "number") {
+          schema.items = valueSchema;
+        }
+      }
+    } else if (ts2.isPropertySignature(member)) {
+      const propName = member.name?.getText() || "";
+      if (member.type) {
+        const propType = typeChecker.getTypeAtLocation(member.type);
+        collectReferencedTypes(propType, typeChecker, referencedTypes);
+      }
+      schema.properties[propName] = member.type ? formatTypeReference(typeChecker.getTypeAtLocation(member.type), typeChecker, typeRefs, referencedTypes) : { type: "any" };
+      if (!member.questionToken) {
+        required.push(propName);
+      }
+    } else if (ts2.isMethodSignature(member)) {
+      const methodName = member.name?.getText() || "";
+      const signature = typeChecker.getSignatureFromDeclaration(member);
+      if (signature) {
+        const parameters = signature.getParameters().map((param) => {
+          const paramDecl = param.declarations?.find(ts2.isParameter);
+          const paramType = paramDecl ? typeChecker.getTypeAtLocation(paramDecl) : typeChecker.getTypeOfSymbolAtLocation(param, member);
+          collectReferencedTypes(paramType, typeChecker, referencedTypes);
+          if (paramDecl) {
+            const paramDoc = getParameterDocumentation(param, paramDecl, typeChecker);
+            return structureParameter(param, paramDecl, paramType, typeChecker, typeRefs, null, paramDoc, referencedTypes);
+          }
+          return {
+            name: param.getName(),
+            required: !(param.flags & ts2.SymbolFlags.Optional),
+            schema: formatTypeReference(paramType, typeChecker, typeRefs, referencedTypes)
+          };
+        });
+        const returnType = signature.getReturnType();
+        if (returnType) {
+          collectReferencedTypes(returnType, typeChecker, referencedTypes);
+        }
+        schema.properties[methodName] = {
+          type: "function",
+          parameters,
+          returns: {
+            schema: returnType ? formatTypeReference(returnType, typeChecker, typeRefs, referencedTypes) : { type: "void" }
+          }
+        };
+        if (!member.questionToken) {
+          required.push(methodName);
+        }
+      }
+    } else if (ts2.isCallSignatureDeclaration(member)) {
+      const signature = typeChecker.getSignatureFromDeclaration(member);
+      if (signature) {
+        const parameters = signature.getParameters().map((param) => {
+          const paramDecl = param.declarations?.find(ts2.isParameter);
+          const paramType = paramDecl ? typeChecker.getTypeAtLocation(paramDecl) : typeChecker.getTypeOfSymbolAtLocation(param, member);
+          collectReferencedTypes(paramType, typeChecker, referencedTypes);
+          if (paramDecl) {
+            const paramDoc = getParameterDocumentation(param, paramDecl, typeChecker);
+            return structureParameter(param, paramDecl, paramType, typeChecker, typeRefs, null, paramDoc, referencedTypes);
+          }
+          return {
+            name: param.getName(),
+            required: !(param.flags & ts2.SymbolFlags.Optional),
+            schema: formatTypeReference(paramType, typeChecker, typeRefs, referencedTypes)
+          };
+        });
+        const returnType = signature.getReturnType();
+        if (returnType) {
+          collectReferencedTypes(returnType, typeChecker, referencedTypes);
+        }
+        callSignatures.push({
+          parameters,
+          returns: {
+            schema: returnType ? formatTypeReference(returnType, typeChecker, typeRefs, referencedTypes) : { type: "void" }
+          }
+        });
+      }
+    } else if (ts2.isConstructSignatureDeclaration(member)) {
+      const signature = typeChecker.getSignatureFromDeclaration(member);
+      if (signature) {
+        const parameters = signature.getParameters().map((param) => {
+          const paramDecl = param.declarations?.find(ts2.isParameter);
+          const paramType = paramDecl ? typeChecker.getTypeAtLocation(paramDecl) : typeChecker.getTypeOfSymbolAtLocation(param, member);
+          collectReferencedTypes(paramType, typeChecker, referencedTypes);
+          if (paramDecl) {
+            const paramDoc = getParameterDocumentation(param, paramDecl, typeChecker);
+            return structureParameter(param, paramDecl, paramType, typeChecker, typeRefs, null, paramDoc, referencedTypes);
+          }
+          return {
+            name: param.getName(),
+            required: !(param.flags & ts2.SymbolFlags.Optional),
+            schema: formatTypeReference(paramType, typeChecker, typeRefs, referencedTypes)
+          };
+        });
+        const returnType = signature.getReturnType();
+        if (returnType) {
+          collectReferencedTypes(returnType, typeChecker, referencedTypes);
+        }
+        constructSignatures.push({
+          parameters,
+          returns: {
+            schema: returnType ? formatTypeReference(returnType, typeChecker, typeRefs, referencedTypes) : { type: "object" }
+          }
+        });
+      }
     }
   }
   if (required.length > 0) {
     schema.required = required;
   }
+  if (callSignatures.length > 0) {
+    schema.callSignatures = callSignatures;
+  }
+  if (constructSignatures.length > 0) {
+    schema.constructSignatures = constructSignatures;
+  }
   return schema;
 }
 
+// src/analysis/serializers/namespaces.ts
+function serializeNamespace(declaration, symbol, context) {
+  const { checker } = context;
+  const parsedDoc = parseJSDocComment(symbol, checker);
+  const description = parsedDoc?.description ?? getJSDocComment(symbol, checker);
+  const metadata = extractPresentationMetadata(parsedDoc);
+  const members = extractNamespaceMembers(declaration, checker);
+  return {
+    id: symbol.getName(),
+    name: symbol.getName(),
+    ...metadata,
+    kind: "namespace",
+    deprecated: isSymbolDeprecated(symbol),
+    description,
+    source: getSourceLocation(declaration),
+    members: members.length > 0 ? members : undefined,
+    tags: parsedDoc?.tags,
+    examples: parsedDoc?.examples
+  };
+}
+function extractNamespaceMembers(declaration, checker) {
+  const members = [];
+  let body = declaration.body;
+  while (body && ts2.isModuleDeclaration(body)) {
+    body = body.body;
+  }
+  if (!body || !ts2.isModuleBlock(body)) {
+    return members;
+  }
+  for (const statement of body.statements) {
+    const hasExportModifier = ts2.canHaveModifiers(statement) && ts2.getModifiers(statement)?.some((mod) => mod.kind === ts2.SyntaxKind.ExportKeyword);
+    if (!hasExportModifier) {
+      continue;
+    }
+    if (ts2.isFunctionDeclaration(statement) && statement.name) {
+      const memberSymbol = checker.getSymbolAtLocation(statement.name);
+      const memberDoc = memberSymbol ? parseJSDocComment(memberSymbol, checker) : null;
+      members.push({
+        id: statement.name.getText(),
+        name: statement.name.getText(),
+        kind: "function",
+        description: memberDoc?.description ?? (memberSymbol ? getJSDocComment(memberSymbol, checker) : undefined)
+      });
+    } else if (ts2.isVariableStatement(statement)) {
+      for (const decl of statement.declarationList.declarations) {
+        if (ts2.isIdentifier(decl.name)) {
+          const memberSymbol = checker.getSymbolAtLocation(decl.name);
+          const memberDoc = memberSymbol ? parseJSDocComment(memberSymbol, checker) : null;
+          members.push({
+            id: decl.name.getText(),
+            name: decl.name.getText(),
+            kind: "variable",
+            description: memberDoc?.description ?? (memberSymbol ? getJSDocComment(memberSymbol, checker) : undefined)
+          });
+        }
+      }
+    } else if (ts2.isInterfaceDeclaration(statement) && statement.name) {
+      const memberSymbol = checker.getSymbolAtLocation(statement.name);
+      const memberDoc = memberSymbol ? parseJSDocComment(memberSymbol, checker) : null;
+      members.push({
+        id: statement.name.getText(),
+        name: statement.name.getText(),
+        kind: "interface",
+        description: memberDoc?.description ?? (memberSymbol ? getJSDocComment(memberSymbol, checker) : undefined)
+      });
+    } else if (ts2.isTypeAliasDeclaration(statement) && statement.name) {
+      const memberSymbol = checker.getSymbolAtLocation(statement.name);
+      const memberDoc = memberSymbol ? parseJSDocComment(memberSymbol, checker) : null;
+      members.push({
+        id: statement.name.getText(),
+        name: statement.name.getText(),
+        kind: "type",
+        description: memberDoc?.description ?? (memberSymbol ? getJSDocComment(memberSymbol, checker) : undefined)
+      });
+    } else if (ts2.isEnumDeclaration(statement) && statement.name) {
+      const memberSymbol = checker.getSymbolAtLocation(statement.name);
+      const memberDoc = memberSymbol ? parseJSDocComment(memberSymbol, checker) : null;
+      members.push({
+        id: statement.name.getText(),
+        name: statement.name.getText(),
+        kind: "enum",
+        description: memberDoc?.description ?? (memberSymbol ? getJSDocComment(memberSymbol, checker) : undefined)
+      });
+    } else if (ts2.isClassDeclaration(statement) && statement.name) {
+      const memberSymbol = checker.getSymbolAtLocation(statement.name);
+      const memberDoc = memberSymbol ? parseJSDocComment(memberSymbol, checker) : null;
+      members.push({
+        id: statement.name.getText(),
+        name: statement.name.getText(),
+        kind: "class",
+        description: memberDoc?.description ?? (memberSymbol ? getJSDocComment(memberSymbol, checker) : undefined)
+      });
+    } else if (ts2.isModuleDeclaration(statement) && statement.name) {
+      const memberSymbol = checker.getSymbolAtLocation(statement.name);
+      const memberDoc = memberSymbol ? parseJSDocComment(memberSymbol, checker) : null;
+      const nestedMembers = extractNamespaceMembers(statement, checker);
+      members.push({
+        id: ts2.isIdentifier(statement.name) ? statement.name.getText() : statement.name.text,
+        name: ts2.isIdentifier(statement.name) ? statement.name.getText() : statement.name.text,
+        kind: "namespace",
+        description: memberDoc?.description ?? (memberSymbol ? getJSDocComment(memberSymbol, checker) : undefined),
+        members: nestedMembers.length > 0 ? nestedMembers : undefined
+      });
+    }
+  }
+  return members;
+}
+
 // src/analysis/serializers/type-aliases.ts
 function serializeTypeAlias(declaration, symbol, context) {
   const { checker, typeRegistry } = context;
@@ -2262,7 +2893,8 @@ function serializeTypeAlias(declaration, symbol, context) {
     description,
     source: getSourceLocation(declaration),
     typeParameters,
-    tags: parsedDoc?.tags
+    tags: parsedDoc?.tags,
+    examples: parsedDoc?.examples
   };
   const aliasType = checker.getTypeAtLocation(declaration.type);
   const aliasName = symbol.getName();
@@ -2334,7 +2966,8 @@ function serializeVariable(declaration, symbol, context) {
     type: typeToRef2(declaration, checker, typeRefs, referencedTypes),
     description,
     source: getSourceLocation(declaration),
-    tags: parsedDoc?.tags
+    tags: parsedDoc?.tags,
+    examples: parsedDoc?.examples
   };
 }
 function typeToRef2(node, typeChecker, typeRefs, referencedTypes) {
@@ -2424,7 +3057,7 @@ function buildOpenPkgSpec(context, resolveExternalTypes) {
     if (!declaration)
       continue;
     const exportName = symbol.getName();
-    if (ts.isClassDeclaration(declaration) || ts.isInterfaceDeclaration(declaration) || ts.isTypeAliasDeclaration(declaration) || ts.isEnumDeclaration(declaration)) {
+    if (ts2.isClassDeclaration(declaration) || ts2.isInterfaceDeclaration(declaration) || ts2.isTypeAliasDeclaration(declaration) || ts2.isEnumDeclaration(declaration)) {
       typeRegistry.registerExportedType(exportName, targetSymbol.getName());
     }
   }
@@ -2433,28 +3066,31 @@ function buildOpenPkgSpec(context, resolveExternalTypes) {
     if (!declaration)
       continue;
     const exportName = symbol.getName();
-    if (ts.isFunctionDeclaration(declaration)) {
+    if (ts2.isFunctionDeclaration(declaration)) {
       const exportEntry = serializeFunctionExport(declaration, targetSymbol, serializerContext);
       addExport(spec, exportEntry, exportName, baseDir);
-    } else if (ts.isClassDeclaration(declaration)) {
+    } else if (ts2.isClassDeclaration(declaration)) {
       const { exportEntry, typeDefinition } = serializeClass(declaration, targetSymbol, serializerContext);
       addExport(spec, exportEntry, exportName, baseDir);
-      addTypeDefinition(spec, typeRegistry, typeDefinition, baseDir);
-    } else if (ts.isInterfaceDeclaration(declaration)) {
+      addTypeDefinition(spec, typeRegistry, typeDefinition, baseDir, exportName);
+    } else if (ts2.isInterfaceDeclaration(declaration)) {
       const { exportEntry, typeDefinition } = serializeInterface(declaration, targetSymbol, serializerContext);
       addExport(spec, exportEntry, exportName, baseDir);
-      addTypeDefinition(spec, typeRegistry, typeDefinition, baseDir);
-    } else if (ts.isTypeAliasDeclaration(declaration)) {
+      addTypeDefinition(spec, typeRegistry, typeDefinition, baseDir, exportName);
+    } else if (ts2.isTypeAliasDeclaration(declaration)) {
       const { exportEntry, typeDefinition } = serializeTypeAlias(declaration, targetSymbol, serializerContext);
       addExport(spec, exportEntry, exportName, baseDir);
-      addTypeDefinition(spec, typeRegistry, typeDefinition, baseDir);
-    } else if (ts.isEnumDeclaration(declaration)) {
+      addTypeDefinition(spec, typeRegistry, typeDefinition, baseDir, exportName);
+    } else if (ts2.isEnumDeclaration(declaration)) {
       const { exportEntry, typeDefinition } = serializeEnum(declaration, targetSymbol, serializerContext);
       addExport(spec, exportEntry, exportName, baseDir);
-      addTypeDefinition(spec, typeRegistry, typeDefinition, baseDir);
-    } else if (ts.isVariableDeclaration(declaration)) {
+      addTypeDefinition(spec, typeRegistry, typeDefinition, baseDir, exportName);
+    } else if (ts2.isVariableDeclaration(declaration)) {
       const exportEntry = serializeVariable(declaration, targetSymbol, serializerContext);
       addExport(spec, exportEntry, exportName, baseDir);
+    } else if (ts2.isModuleDeclaration(declaration)) {
+      const exportEntry = serializeNamespace(declaration, targetSymbol, serializerContext);
+      addExport(spec, exportEntry, exportName, baseDir);
     }
   }
   for (const typeName of typeRegistry.getReferencedTypes()) {
@@ -2478,22 +3114,36 @@ function buildOpenPkgSpec(context, resolveExternalTypes) {
         const { declaration, targetSymbol } = resolveExportTarget(exportSymbol, typeChecker);
         if (!declaration)
           continue;
-        if (ts.isClassDeclaration(declaration)) {
+        if (ts2.isClassDeclaration(declaration)) {
           const { typeDefinition } = serializeClass(declaration, targetSymbol, serializerContext);
           addTypeDefinition(spec, typeRegistry, typeDefinition, baseDir);
-        } else if (ts.isInterfaceDeclaration(declaration)) {
+        } else if (ts2.isInterfaceDeclaration(declaration)) {
           const { typeDefinition } = serializeInterface(declaration, targetSymbol, serializerContext);
           addTypeDefinition(spec, typeRegistry, typeDefinition, baseDir);
-        } else if (ts.isTypeAliasDeclaration(declaration)) {
+        } else if (ts2.isTypeAliasDeclaration(declaration)) {
           const { typeDefinition } = serializeTypeAlias(declaration, targetSymbol, serializerContext);
           addTypeDefinition(spec, typeRegistry, typeDefinition, baseDir);
-        } else if (ts.isEnumDeclaration(declaration)) {
+        } else if (ts2.isEnumDeclaration(declaration)) {
           const { typeDefinition } = serializeEnum(declaration, targetSymbol, serializerContext);
           addTypeDefinition(spec, typeRegistry, typeDefinition, baseDir);
         }
       }
     }
   }
+  for (const typeName of typeRegistry.getReferencedTypes()) {
+    if (typeRegistry.isKnownType(typeName)) {
+      continue;
+    }
+    const stubDefinition = {
+      id: typeName,
+      name: typeName,
+      kind: "external",
+      description: `External type (not resolved)`
+    };
+    if (typeRegistry.registerTypeDefinition(stubDefinition)) {
+      spec.types?.push(stubDefinition);
+    }
+  }
   const coverage = computeDocsCoverage(spec);
   spec.docs = coverage.spec;
   spec.exports.forEach((entry) => {
@@ -2508,11 +3158,20 @@ function addExport(spec, entry, exportName, baseDir) {
   const named = withExportName(entry, exportName);
   spec.exports.push(applyPresentationDefaults(named, baseDir));
 }
-function addTypeDefinition(spec, typeRegistry, definition, baseDir) {
+function addTypeDefinition(spec, typeRegistry, definition, baseDir, exportAlias) {
   if (!definition) {
     return;
   }
-  const enriched = applyPresentationDefaults(definition, baseDir);
+  let finalDefinition = definition;
+  if (exportAlias && exportAlias !== definition.name) {
+    finalDefinition = {
+      ...definition,
+      id: exportAlias,
+      name: definition.name,
+      alias: exportAlias
+    };
+  }
+  const enriched = applyPresentationDefaults(finalDefinition, baseDir);
   if (typeRegistry.registerTypeDefinition(enriched)) {
     spec.types?.push(enriched);
   }
@@ -2552,14 +3211,14 @@ function deriveImportPath(sourceFile, baseDir) {
 }
 function resolveExportTarget(symbol, checker) {
   let targetSymbol = symbol;
-  if (symbol.flags & ts.SymbolFlags.Alias) {
+  if (symbol.flags & ts2.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];
+  const declaration = targetSymbol.valueDeclaration || declarations.find((decl) => decl.kind !== ts2.SyntaxKind.ExportSpecifier) || declarations[0];
   return {
     declaration,
     targetSymbol
@@ -2572,7 +3231,8 @@ function withExportName(entry, exportName) {
   return {
     ...entry,
     id: exportName,
-    name: exportName
+    name: entry.name,
+    alias: exportName
   };
 }
 
@@ -2608,6 +3268,52 @@ function hasNodeModulesDirectory(directories) {
   }
   return false;
 }
+function collectAllRefs(obj, refs) {
+  if (obj === null || obj === undefined)
+    return;
+  if (Array.isArray(obj)) {
+    for (const item of obj) {
+      collectAllRefs(item, refs);
+    }
+    return;
+  }
+  if (typeof obj === "object") {
+    const record = obj;
+    if (typeof record.$ref === "string" && record.$ref.startsWith("#/types/")) {
+      refs.add(record.$ref.slice("#/types/".length));
+    }
+    for (const value of Object.values(record)) {
+      collectAllRefs(value, refs);
+    }
+  }
+}
+function collectDanglingRefs(spec) {
+  const definedTypes = new Set(spec.types?.map((t) => t.id) ?? []);
+  const referencedTypes = new Set;
+  collectAllRefs(spec.exports, referencedTypes);
+  collectAllRefs(spec.types, referencedTypes);
+  return Array.from(referencedTypes).filter((ref) => !definedTypes.has(ref));
+}
+function collectExternalTypes(spec) {
+  return (spec.types ?? []).filter((t) => t.kind === "external").map((t) => t.id);
+}
+function hasExternalImports(sourceFile) {
+  let found = false;
+  ts2.forEachChild(sourceFile, (node) => {
+    if (found)
+      return;
+    if (ts2.isImportDeclaration(node) && node.moduleSpecifier) {
+      const specifier = node.moduleSpecifier;
+      if (ts2.isStringLiteral(specifier)) {
+        const modulePath = specifier.text;
+        if (!modulePath.startsWith(".") && !modulePath.startsWith("/")) {
+          found = true;
+        }
+      }
+    }
+  });
+  return found;
+}
 function runAnalysis(input) {
   const context = createAnalysisContext(input);
   const { baseDir, options } = context;
@@ -2618,14 +3324,38 @@ function runAnalysis(input) {
   }
   const hasNodeModules = hasNodeModulesDirectory(searchDirs);
   const resolveExternalTypes = options.resolveExternalTypes !== undefined ? options.resolveExternalTypes : hasNodeModules;
-  const diagnostics = ts.getPreEmitDiagnostics(context.program).filter((d) => {
+  const diagnostics = ts2.getPreEmitDiagnostics(context.program).filter((d) => {
     if (d.code === 5053)
       return false;
-    const msg = ts.flattenDiagnosticMessageText(d.messageText, `
+    const msg = ts2.flattenDiagnosticMessageText(d.messageText, `
 `);
     return !/allowJs/i.test(msg);
   });
   const spec = buildOpenPkgSpec(context, resolveExternalTypes);
+  const specDiagnostics = [];
+  if (!hasNodeModules && hasExternalImports(context.sourceFile)) {
+    specDiagnostics.push({
+      message: "External imports detected but node_modules not found.",
+      severity: "info",
+      suggestion: "Run npm install or bun install for complete type resolution."
+    });
+  }
+  const danglingRefs = collectDanglingRefs(spec);
+  for (const ref of danglingRefs) {
+    specDiagnostics.push({
+      message: `Type '${ref}' is referenced but not defined in types[].`,
+      severity: "warning",
+      suggestion: hasNodeModules ? "The type may be from an external package. Check import paths." : "Run npm/bun install to resolve external types."
+    });
+  }
+  const externalTypes = collectExternalTypes(spec);
+  if (externalTypes.length > 0) {
+    specDiagnostics.push({
+      message: `${externalTypes.length} external type(s) could not be fully resolved: ${externalTypes.slice(0, 5).join(", ")}${externalTypes.length > 5 ? "..." : ""}`,
+      severity: "warning",
+      suggestion: hasNodeModules ? "Types are from external packages. Full resolution requires type declarations." : "Run npm/bun install to resolve external type definitions."
+    });
+  }
   return {
     spec,
     metadata: {
@@ -2635,7 +3365,8 @@ function runAnalysis(input) {
       hasNodeModules,
       resolveExternalTypes
     },
-    diagnostics
+    diagnostics,
+    specDiagnostics
   };
 }
 
@@ -2649,10 +3380,785 @@ async function extractPackageSpec(entryFile, packageDir, content, options) {
   });
   return result.spec;
 }
+// src/fix/deterministic-fixes.ts
+var FIXABLE_DRIFT_TYPES = new Set([
+  "param-mismatch",
+  "param-type-mismatch",
+  "optionality-mismatch",
+  "return-type-mismatch",
+  "generic-constraint-mismatch",
+  "example-assertion-failed",
+  "deprecated-mismatch",
+  "async-mismatch",
+  "property-type-drift"
+]);
+function isFixableDrift(drift) {
+  return FIXABLE_DRIFT_TYPES.has(drift.type);
+}
+function generateFix(drift, exportEntry, existingPatch) {
+  switch (drift.type) {
+    case "param-mismatch":
+      return generateParamMismatchFix(drift, exportEntry, existingPatch);
+    case "param-type-mismatch":
+      return generateParamTypeFix(drift, exportEntry, existingPatch);
+    case "optionality-mismatch":
+      return generateOptionalityFix(drift, exportEntry, existingPatch);
+    case "return-type-mismatch":
+      return generateReturnTypeFix(drift, exportEntry, existingPatch);
+    case "generic-constraint-mismatch":
+      return generateGenericConstraintFix(drift, exportEntry, existingPatch);
+    case "example-assertion-failed":
+      return generateAssertionFix(drift, exportEntry);
+    case "deprecated-mismatch":
+      return generateDeprecatedFix(drift, exportEntry, existingPatch);
+    case "async-mismatch":
+      return generateAsyncFix(drift, exportEntry, existingPatch);
+    case "property-type-drift":
+      return generatePropertyTypeFix(drift, exportEntry, existingPatch);
+    default:
+      return null;
+  }
+}
+function generateFixesForExport(exportEntry, existingPatch) {
+  const fixes = [];
+  const driftList = exportEntry.docs?.drift ?? [];
+  for (const drift of driftList) {
+    const fix = generateFix(drift, exportEntry, existingPatch);
+    if (fix) {
+      fixes.push(fix);
+    }
+  }
+  return fixes;
+}
+function mergeFixes(fixes, basePatch) {
+  let result = basePatch ? { ...basePatch } : {};
+  for (const fix of fixes) {
+    result = mergePatches(result, fix.patch);
+  }
+  return result;
+}
+function mergePatches(base, update) {
+  const result = { ...base };
+  if (update.description !== undefined) {
+    result.description = update.description;
+  }
+  if (update.params !== undefined) {
+    const isRemoval = result.params && update.params.length < result.params.length;
+    if (isRemoval) {
+      const existingByName = new Map(result.params?.map((p) => [p.name, p]) ?? []);
+      result.params = update.params.map((updatedParam) => {
+        const existing = existingByName.get(updatedParam.name);
+        return {
+          ...existing,
+          ...updatedParam,
+          description: updatedParam.description ?? existing?.description
+        };
+      });
+    } else {
+      if (!result.params) {
+        result.params = [];
+      }
+      const resultByName = new Map(result.params.map((p) => [p.name, p]));
+      for (const updatedParam of update.params) {
+        const existing = resultByName.get(updatedParam.name);
+        if (existing) {
+          Object.assign(existing, updatedParam);
+        } else {
+          result.params.push(updatedParam);
+        }
+      }
+    }
+  }
+  if (update.returns !== undefined) {
+    result.returns = { ...result.returns, ...update.returns };
+  }
+  if (update.typeParams !== undefined) {
+    result.typeParams = update.typeParams;
+  }
+  if (update.examples !== undefined) {
+    result.examples = update.examples;
+  }
+  if (update.deprecated !== undefined) {
+    result.deprecated = update.deprecated;
+  }
+  if (update.async !== undefined) {
+    result.async = update.async;
+  }
+  if (update.type !== undefined) {
+    result.type = update.type;
+  }
+  return result;
+}
+function generateParamMismatchFix(drift, exportEntry, existingPatch) {
+  const issue = drift.issue.toLowerCase();
+  const target = drift.target ?? "";
+  const signature = exportEntry.signatures?.[0];
+  if (!signature)
+    return null;
+  const actualParams = signature.parameters ?? [];
+  const existingParams = existingPatch?.params ?? [];
+  if (issue.includes("missing") || issue.includes("undocumented")) {
+    const paramName = extractParamName(target, drift.issue);
+    if (!paramName)
+      return null;
+    const actualParam = actualParams.find((p) => p.name === paramName);
+    const paramType = actualParam?.schema ? stringifySchema(actualParam.schema) : undefined;
+    const newParam = {
+      name: paramName,
+      type: paramType,
+      optional: actualParam?.required === false
+    };
+    const updatedParams = [...existingParams];
+    const existingIndex = updatedParams.findIndex((p) => p.name === paramName);
+    if (existingIndex >= 0) {
+      updatedParams[existingIndex] = { ...updatedParams[existingIndex], ...newParam };
+    } else {
+      updatedParams.push(newParam);
+    }
+    return {
+      type: "add-param",
+      driftType: drift.type,
+      target: paramName,
+      description: `Add missing @param ${paramName}`,
+      patch: { params: updatedParams }
+    };
+  }
+  if (issue.includes("extra") || issue.includes("removed") || issue.includes("no longer") || issue.includes("not present") || issue.includes("does not exist")) {
+    const paramName = target || extractParamName(target, drift.issue);
+    if (!paramName)
+      return null;
+    const updatedParams = existingParams.filter((p) => p.name !== paramName);
+    return {
+      type: "remove-param",
+      driftType: drift.type,
+      target: paramName,
+      description: `Remove stale @param ${paramName}`,
+      patch: { params: updatedParams }
+    };
+  }
+  if (drift.suggestion && issue.includes("rename")) {
+    const oldName = extractParamName(target, drift.issue);
+    const newNameMatch = drift.suggestion.match(/`(\w+)`/);
+    const newName = newNameMatch?.[1];
+    if (oldName && newName) {
+      const updatedParams = existingParams.map((p) => p.name === oldName ? { ...p, name: newName } : p);
+      return {
+        type: "add-param",
+        driftType: drift.type,
+        target: newName,
+        description: `Rename @param ${oldName} to ${newName}`,
+        patch: { params: updatedParams }
+      };
+    }
+  }
+  return null;
+}
+function generateParamTypeFix(drift, exportEntry, existingPatch) {
+  const target = drift.target ?? "";
+  const paramName = extractParamName(target, drift.issue);
+  if (!paramName)
+    return null;
+  const signature = exportEntry.signatures?.[0];
+  const actualParam = signature?.parameters?.find((p) => p.name === paramName);
+  if (!actualParam)
+    return null;
+  const correctType = stringifySchema(actualParam.schema);
+  const existingParams = existingPatch?.params ?? [];
+  const updatedParams = existingParams.map((p) => p.name === paramName ? { ...p, type: correctType } : p);
+  if (!existingParams.some((p) => p.name === paramName)) {
+    updatedParams.push({
+      name: paramName,
+      type: correctType,
+      optional: actualParam.required === false
+    });
+  }
+  return {
+    type: "update-param-type",
+    driftType: drift.type,
+    target: paramName,
+    description: `Update @param ${paramName} type to {${correctType}}`,
+    patch: { params: updatedParams }
+  };
+}
+function generateOptionalityFix(drift, exportEntry, existingPatch) {
+  const target = drift.target ?? "";
+  const paramName = extractParamName(target, drift.issue);
+  if (!paramName)
+    return null;
+  const signature = exportEntry.signatures?.[0];
+  const actualParam = signature?.parameters?.find((p) => p.name === paramName);
+  if (!actualParam)
+    return null;
+  const isOptional = actualParam.required === false;
+  const existingParams = existingPatch?.params ?? [];
+  const updatedParams = existingParams.map((p) => p.name === paramName ? { ...p, optional: isOptional } : p);
+  if (!existingParams.some((p) => p.name === paramName)) {
+    updatedParams.push({
+      name: paramName,
+      optional: isOptional
+    });
+  }
+  const optionalityText = isOptional ? "optional" : "required";
+  return {
+    type: "update-param-optionality",
+    driftType: drift.type,
+    target: paramName,
+    description: `Mark @param ${paramName} as ${optionalityText}`,
+    patch: { params: updatedParams }
+  };
+}
+function generateReturnTypeFix(drift, exportEntry, existingPatch) {
+  const signature = exportEntry.signatures?.[0];
+  const actualReturn = signature?.returns;
+  if (!actualReturn)
+    return null;
+  const correctType = actualReturn.tsType ?? stringifySchema(actualReturn.schema);
+  const updatedReturn = {
+    ...existingPatch?.returns,
+    type: correctType
+  };
+  return {
+    type: "update-return-type",
+    driftType: drift.type,
+    target: "returns",
+    description: `Update @returns type to {${correctType}}`,
+    patch: { returns: updatedReturn }
+  };
+}
+function generateGenericConstraintFix(drift, exportEntry, _existingPatch) {
+  const target = drift.target ?? "";
+  const typeParamName = target || extractTypeParamName(drift.issue);
+  if (!typeParamName)
+    return null;
+  const typeParam = exportEntry.typeParameters?.find((tp) => tp.name === typeParamName);
+  if (!typeParam)
+    return null;
+  const typeParams = exportEntry.typeParameters?.map((tp) => ({
+    name: tp.name,
+    constraint: tp.constraint
+  })) ?? [];
+  return {
+    type: "update-template-constraint",
+    driftType: drift.type,
+    target: typeParamName,
+    description: `Update @template ${typeParamName} constraint to ${typeParam.constraint ?? "none"}`,
+    patch: { typeParams }
+  };
+}
+function generateAssertionFix(drift, exportEntry) {
+  if (!drift.suggestion)
+    return null;
+  const targetMatch = drift.target?.match(/example\[(\d+)\](?::line(\d+))?/);
+  if (!targetMatch)
+    return null;
+  const exampleIndex = parseInt(targetMatch[1], 10);
+  const examples = exportEntry.examples ?? [];
+  if (exampleIndex >= examples.length)
+    return null;
+  const newValueMatch = drift.suggestion.match(/\/\/\s*=>\s*(.+)$/);
+  if (!newValueMatch)
+    return null;
+  const newValue = newValueMatch[1].trim();
+  const oldExample = examples[exampleIndex];
+  const oldValueMatch = drift.issue.match(/expected\s+"([^"]+)"/i);
+  const oldValue = oldValueMatch?.[1];
+  if (!oldValue)
+    return null;
+  const updatedExample = oldExample.replace(new RegExp(`//\\s*=>\\s*${escapeRegex(oldValue)}`, "g"), `// => ${newValue}`);
+  const updatedExamples = [...examples];
+  updatedExamples[exampleIndex] = updatedExample;
+  return {
+    type: "update-assertion",
+    driftType: drift.type,
+    target: `example[${exampleIndex}]`,
+    description: `Update assertion from "${oldValue}" to "${newValue}"`,
+    patch: { examples: updatedExamples }
+  };
+}
+function generateDeprecatedFix(drift, exportEntry, _existingPatch) {
+  const issue = drift.issue.toLowerCase();
+  const target = drift.target ?? exportEntry.name ?? "";
+  if (issue.includes("missing") || issue.includes("@deprecated is missing")) {
+    const deprecationReason = exportEntry.deprecated ? typeof exportEntry.deprecated === "string" ? exportEntry.deprecated : "This API is deprecated." : "This API is deprecated.";
+    return {
+      type: "add-deprecated",
+      driftType: drift.type,
+      target,
+      description: `Add @deprecated tag`,
+      patch: { deprecated: deprecationReason }
+    };
+  }
+  if (issue.includes("not") && issue.includes("deprecated")) {
+    return {
+      type: "remove-deprecated",
+      driftType: drift.type,
+      target,
+      description: `Remove @deprecated tag`,
+      patch: { deprecated: false }
+    };
+  }
+  return null;
+}
+function generateAsyncFix(drift, _exportEntry, _existingPatch) {
+  const issue = drift.issue.toLowerCase();
+  if (issue.includes("returns promise") && issue.includes("does not indicate")) {
+    return {
+      type: "add-async",
+      driftType: drift.type,
+      target: "returns",
+      description: `Add @async tag`,
+      patch: { async: true }
+    };
+  }
+  if (issue.includes("does not return promise") || issue.includes("doesn't return promise")) {
+    return {
+      type: "remove-async",
+      driftType: drift.type,
+      target: "returns",
+      description: `Remove @async tag`,
+      patch: { async: false }
+    };
+  }
+  return null;
+}
+function generatePropertyTypeFix(drift, _exportEntry, _existingPatch) {
+  const target = drift.target ?? "";
+  let actualType = null;
+  if (drift.suggestion) {
+    const suggestionMatch = drift.suggestion.match(/\{([^}]+)\}/);
+    if (suggestionMatch) {
+      actualType = suggestionMatch[1];
+    }
+  }
+  if (!actualType && drift.issue) {
+    const issueMatch = drift.issue.match(/actual type is\s+(\S+)/i);
+    if (issueMatch) {
+      actualType = issueMatch[1].replace(/\.$/, "");
+    }
+  }
+  if (!actualType)
+    return null;
+  return {
+    type: "update-property-type",
+    driftType: drift.type,
+    target,
+    description: `Update @type to {${actualType}}`,
+    patch: { type: actualType }
+  };
+}
+function extractParamName(target, issue) {
+  if (target && !target.includes("[") && !target.includes(":")) {
+    return target;
+  }
+  const patterns = [
+    /[Pp]arameter\s+[`'"]?(\w+)[`'"]?/,
+    /@param\s+(?:\{[^}]+\}\s+)?[`'"]?(\w+)[`'"]?/,
+    /[`'"](\w+)[`'"]\s+(?:is|was|has)/
+  ];
+  for (const pattern of patterns) {
+    const match = issue.match(pattern);
+    if (match?.[1]) {
+      return match[1];
+    }
+  }
+  return null;
+}
+function extractTypeParamName(issue) {
+  const match = issue.match(/[Tt]ype\s+parameter\s+[`'"]?(\w+)[`'"]?/);
+  return match?.[1] ?? null;
+}
+function stringifySchema(schema) {
+  if (typeof schema === "string") {
+    return schema;
+  }
+  if (schema && typeof schema === "object") {
+    if ("type" in schema && typeof schema.type === "string") {
+      return schema.type;
+    }
+    if ("$ref" in schema && typeof schema.$ref === "string") {
+      const ref = schema.$ref;
+      return ref.split("/").pop() ?? ref;
+    }
+  }
+  return "unknown";
+}
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function categorizeDrifts(drifts) {
+  const fixable = [];
+  const nonFixable = [];
+  for (const drift of drifts) {
+    if (isFixableDrift(drift)) {
+      fixable.push(drift);
+    } else {
+      nonFixable.push(drift);
+    }
+  }
+  return { fixable, nonFixable };
+}
+// src/fix/jsdoc-writer.ts
+import * as fs3 from "node:fs";
+import * as path5 from "node:path";
+function parseJSDocToPatch(jsDocText) {
+  const patch = {};
+  const cleanedText = jsDocText.replace(/^\/\*\*\s*/, "").replace(/\s*\*\/$/, "").replace(/^\s*\* ?/gm, "").trim();
+  const lines = cleanedText.split(`
+`);
+  let currentTag = "";
+  let currentContent = [];
+  const descriptionLines = [];
+  const processCurrentTag = () => {
+    if (!currentTag)
+      return;
+    const content = currentContent.join(`
+`).trim();
+    switch (currentTag) {
+      case "param":
+      case "parameter": {
+        const paramMatch = content.match(/^(?:\{([^}]+)\}\s+)?(\[?\w+(?:\.\w+)*\]?)(?:\s+-\s+|\s+)?(.*)$/s);
+        if (paramMatch) {
+          const [, type, rawName, description] = paramMatch;
+          const optional = rawName.startsWith("[") && rawName.endsWith("]");
+          const name = optional ? rawName.slice(1, -1) : rawName;
+          if (!patch.params)
+            patch.params = [];
+          patch.params.push({
+            name,
+            type: type?.trim(),
+            description: description?.trim(),
+            optional
+          });
+        }
+        break;
+      }
+      case "returns":
+      case "return": {
+        const returnMatch = content.match(/^(?:\{([^}]+)\}\s*)?(.*)$/s);
+        if (returnMatch) {
+          patch.returns = {
+            type: returnMatch[1]?.trim(),
+            description: returnMatch[2]?.trim()
+          };
+        }
+        break;
+      }
+      case "example": {
+        if (!patch.examples)
+          patch.examples = [];
+        patch.examples.push(content);
+        break;
+      }
+      case "deprecated": {
+        patch.deprecated = content || "Deprecated";
+        break;
+      }
+      case "async": {
+        patch.async = true;
+        break;
+      }
+      case "type": {
+        const typeMatch = content.match(/^\{([^}]+)\}$/);
+        if (typeMatch) {
+          patch.type = typeMatch[1].trim();
+        } else if (content.trim()) {
+          patch.type = content.trim();
+        }
+        break;
+      }
+      case "template": {
+        const templateMatch = content.match(/^(\w+)(?:\s+extends\s+(\S+))?(?:\s+-?\s*(.*))?$/);
+        if (templateMatch) {
+          if (!patch.typeParams)
+            patch.typeParams = [];
+          patch.typeParams.push({
+            name: templateMatch[1],
+            constraint: templateMatch[2],
+            description: templateMatch[3]?.trim()
+          });
+        }
+        break;
+      }
+      default: {
+        if (!patch.otherTags)
+          patch.otherTags = [];
+        patch.otherTags.push({ name: currentTag, text: content });
+      }
+    }
+  };
+  for (const line of lines) {
+    const tagMatch = line.match(/^@(\w+)(?:\s+(.*))?$/);
+    if (tagMatch) {
+      processCurrentTag();
+      currentTag = tagMatch[1];
+      currentContent = tagMatch[2] ? [tagMatch[2]] : [];
+    } else if (currentTag) {
+      currentContent.push(line);
+    } else if (line.trim()) {
+      descriptionLines.push(line);
+    }
+  }
+  processCurrentTag();
+  if (descriptionLines.length > 0) {
+    patch.description = descriptionLines.join(`
+`).trim();
+  }
+  return patch;
+}
+function applyPatchToJSDoc(existing, updates) {
+  const result = { ...existing };
+  if (updates.description !== undefined) {
+    result.description = updates.description;
+  }
+  if (updates.params !== undefined) {
+    const existingByName = new Map(existing.params?.map((p) => [p.name, p]) ?? []);
+    result.params = updates.params.map((updatedParam) => {
+      const existingParam = existingByName.get(updatedParam.name);
+      return {
+        ...existingParam,
+        ...updatedParam,
+        description: updatedParam.description ?? existingParam?.description
+      };
+    });
+  }
+  if (updates.returns !== undefined) {
+    result.returns = {
+      ...existing.returns,
+      ...updates.returns
+    };
+  }
+  if (updates.examples !== undefined) {
+    result.examples = updates.examples;
+  }
+  if (updates.deprecated !== undefined) {
+    result.deprecated = updates.deprecated;
+  }
+  if (updates.typeParams !== undefined) {
+    result.typeParams = updates.typeParams;
+  }
+  if (updates.otherTags !== undefined) {
+    result.otherTags = updates.otherTags;
+  }
+  return result;
+}
+function serializeJSDoc(patch, indent = "") {
+  const lines = [];
+  if (patch.description) {
+    const descLines = patch.description.split(`
+`);
+    for (const line of descLines) {
+      lines.push(line);
+    }
+  }
+  const hasTags = patch.params?.length || patch.returns || patch.examples?.length || patch.deprecated || patch.async || patch.type || patch.typeParams?.length || patch.otherTags?.length;
+  if (patch.description && hasTags) {
+    lines.push("");
+  }
+  if (patch.async) {
+    lines.push("@async");
+  }
+  if (patch.type) {
+    lines.push(`@type {${patch.type}}`);
+  }
+  if (patch.typeParams) {
+    for (const tp of patch.typeParams) {
+      let tagLine = `@template ${tp.name}`;
+      if (tp.constraint) {
+        tagLine += ` extends ${tp.constraint}`;
+      }
+      if (tp.description) {
+        tagLine += ` - ${tp.description}`;
+      }
+      lines.push(tagLine);
+    }
+  }
+  if (patch.params) {
+    for (const param of patch.params) {
+      let tagLine = "@param";
+      if (param.type) {
+        tagLine += ` {${param.type}}`;
+      }
+      const paramName = param.optional ? `[${param.name}]` : param.name;
+      tagLine += ` ${paramName}`;
+      if (param.description) {
+        tagLine += ` - ${param.description}`;
+      }
+      lines.push(tagLine);
+    }
+  }
+  if (patch.returns && (patch.returns.type || patch.returns.description)) {
+    let tagLine = "@returns";
+    if (patch.returns.type) {
+      tagLine += ` {${patch.returns.type}}`;
+    }
+    if (patch.returns.description) {
+      tagLine += ` ${patch.returns.description}`;
+    }
+    lines.push(tagLine);
+  }
+  if (patch.deprecated && patch.deprecated !== false) {
+    lines.push(`@deprecated ${patch.deprecated}`);
+  }
+  if (patch.examples) {
+    for (const example of patch.examples) {
+      lines.push("@example");
+      const exampleLines = example.split(`
+`);
+      for (const line of exampleLines) {
+        lines.push(line);
+      }
+    }
+  }
+  if (patch.otherTags) {
+    for (const tag of patch.otherTags) {
+      if (tag.text) {
+        lines.push(`@${tag.name} ${tag.text}`);
+      } else {
+        lines.push(`@${tag.name}`);
+      }
+    }
+  }
+  if (lines.length === 0) {
+    return `${indent}/** */`;
+  }
+  if (lines.length === 1 && lines[0].length < 60) {
+    return `${indent}/** ${lines[0]} */`;
+  }
+  const formattedLines = lines.map((line) => `${indent} * ${line}`);
+  return `${indent}/**
+${formattedLines.join(`
+`)}
+${indent} */`;
+}
+function findJSDocLocation(sourceFile, symbolName, approximateLine) {
+  let result = null;
+  let closestDistance = Number.POSITIVE_INFINITY;
+  function getIndent(node) {
+    const pos = node.getStart(sourceFile);
+    const { character } = sourceFile.getLineAndCharacterOfPosition(pos);
+    return " ".repeat(character);
+  }
+  function processNode(node, name) {
+    if (name !== symbolName)
+      return;
+    const { line: nodeLine } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+    if (approximateLine !== undefined) {
+      const distance = Math.abs(nodeLine - approximateLine);
+      if (distance >= closestDistance)
+        return;
+      closestDistance = distance;
+    }
+    const indent = getIndent(node);
+    const commentRanges = ts2.getLeadingCommentRanges(sourceFile.text, node.pos);
+    let jsDocRange;
+    if (commentRanges) {
+      for (let i = commentRanges.length - 1;i >= 0; i--) {
+        const range = commentRanges[i];
+        const text = sourceFile.text.substring(range.pos, range.end);
+        if (text.startsWith("/**")) {
+          jsDocRange = range;
+          break;
+        }
+      }
+    }
+    if (jsDocRange) {
+      const { line: startLine } = sourceFile.getLineAndCharacterOfPosition(jsDocRange.pos);
+      const { line: endLine } = sourceFile.getLineAndCharacterOfPosition(jsDocRange.end);
+      const existingJSDoc = sourceFile.text.substring(jsDocRange.pos, jsDocRange.end);
+      result = {
+        startLine,
+        endLine,
+        declarationLine: nodeLine,
+        hasExisting: true,
+        existingJSDoc,
+        indent
+      };
+    } else {
+      result = {
+        startLine: nodeLine,
+        endLine: nodeLine,
+        declarationLine: nodeLine,
+        hasExisting: false,
+        indent
+      };
+    }
+  }
+  function visit(node) {
+    if (ts2.isFunctionDeclaration(node) && node.name) {
+      processNode(node, node.name.getText(sourceFile));
+    }
+    if (ts2.isVariableStatement(node)) {
+      for (const decl of node.declarationList.declarations) {
+        if (ts2.isIdentifier(decl.name)) {
+          processNode(node, decl.name.getText(sourceFile));
+        }
+      }
+    }
+    if (ts2.isClassDeclaration(node) && node.name) {
+      processNode(node, node.name.getText(sourceFile));
+    }
+    if (ts2.isInterfaceDeclaration(node)) {
+      processNode(node, node.name.getText(sourceFile));
+    }
+    if (ts2.isTypeAliasDeclaration(node)) {
+      processNode(node, node.name.getText(sourceFile));
+    }
+    if (ts2.isMethodDeclaration(node) && node.name) {
+      processNode(node, node.name.getText(sourceFile));
+    }
+    ts2.forEachChild(node, visit);
+  }
+  visit(sourceFile);
+  return result;
+}
+async function applyEdits(edits) {
+  const result = {
+    filesModified: 0,
+    editsApplied: 0,
+    errors: []
+  };
+  const editsByFile = new Map;
+  for (const edit of edits) {
+    const existing = editsByFile.get(edit.filePath) ?? [];
+    existing.push(edit);
+    editsByFile.set(edit.filePath, existing);
+  }
+  for (const [filePath, fileEdits] of editsByFile) {
+    try {
+      const content = fs3.readFileSync(filePath, "utf-8");
+      const lines = content.split(`
+`);
+      const sortedEdits = [...fileEdits].sort((a, b) => b.startLine - a.startLine);
+      for (const edit of sortedEdits) {
+        const newJSDocLines = edit.newJSDoc.split(`
+`);
+        if (edit.hasExisting) {
+          lines.splice(edit.startLine, edit.endLine - edit.startLine + 1, ...newJSDocLines);
+        } else {
+          lines.splice(edit.startLine, 0, ...newJSDocLines);
+        }
+        result.editsApplied++;
+      }
+      fs3.writeFileSync(filePath, lines.join(`
+`));
+      result.filesModified++;
+    } catch (error) {
+      result.errors.push({
+        file: filePath,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  return result;
+}
+function createSourceFile(filePath) {
+  const content = fs3.readFileSync(filePath, "utf-8");
+  return ts2.createSourceFile(path5.basename(filePath), content, ts2.ScriptTarget.Latest, true, filePath.endsWith(".tsx") ? ts2.ScriptKind.TSX : ts2.ScriptKind.TS);
+}
 // src/openpkg.ts
 import * as fsSync from "node:fs";
-import * as fs3 from "node:fs/promises";
-import * as path5 from "node:path";
+import * as fs4 from "node:fs/promises";
+import * as path6 from "node:path";
 
 // src/filtering/apply-filters.ts
 var TYPE_REF_PREFIX = "#/types/";
@@ -2835,14 +4341,14 @@ class DocCov {
     this.options = normalizeDocCovOptions(options);
   }
   async analyze(code, fileName = "temp.ts", analyzeOptions = {}) {
-    const resolvedFileName = path5.resolve(fileName);
-    const tempDir = path5.dirname(resolvedFileName);
+    const resolvedFileName = path6.resolve(fileName);
+    const tempDir = path6.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 resolvedPath = path6.resolve(filePath);
+    const content = await fs4.readFile(resolvedPath, "utf-8");
     const packageDir = resolvePackageDir(resolvedPath);
     const spec = await extractPackageSpec(resolvedPath, packageDir, content, this.options);
     return this.applySpecFilters(spec, analyzeOptions.filters).spec;
@@ -2851,7 +4357,7 @@ class DocCov {
     return this.analyzeFile(entryPath, analyzeOptions);
   }
   async analyzeWithDiagnostics(code, fileName, analyzeOptions = {}) {
-    const resolvedFileName = path5.resolve(fileName ?? "temp.ts");
+    const resolvedFileName = path6.resolve(fileName ?? "temp.ts");
     const packageDir = resolvePackageDir(resolvedFileName);
     const analysis = runAnalysis({
       entryFile: resolvedFileName,
@@ -2864,14 +4370,15 @@ class DocCov {
       spec: filterOutcome.spec,
       diagnostics: [
         ...analysis.diagnostics.map((diagnostic) => this.normalizeDiagnostic(diagnostic)),
+        ...analysis.specDiagnostics,
         ...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 resolvedPath = path6.resolve(filePath);
+    const content = await fs4.readFile(resolvedPath, "utf-8");
     const packageDir = resolvePackageDir(resolvedPath);
     const analysis = runAnalysis({
       entryFile: resolvedPath,
@@ -2884,13 +4391,14 @@ class DocCov {
       spec: filterOutcome.spec,
       diagnostics: [
         ...analysis.diagnostics.map((diagnostic) => this.normalizeDiagnostic(diagnostic)),
+        ...analysis.specDiagnostics,
         ...filterOutcome.diagnostics
       ],
       metadata: this.normalizeMetadata(analysis.metadata)
     };
   }
   normalizeDiagnostic(tsDiagnostic) {
-    const message = ts.flattenDiagnosticMessageText(tsDiagnostic.messageText, `
+    const message = ts2.flattenDiagnosticMessageText(tsDiagnostic.messageText, `
 `);
     let location;
     if (tsDiagnostic.file && typeof tsDiagnostic.start === "number") {
@@ -2910,10 +4418,10 @@ class DocCov {
   }
   mapSeverity(category) {
     switch (category) {
-      case ts.DiagnosticCategory.Message:
-      case ts.DiagnosticCategory.Suggestion:
+      case ts2.DiagnosticCategory.Message:
+      case ts2.DiagnosticCategory.Suggestion:
         return "info";
-      case ts.DiagnosticCategory.Warning:
+      case ts2.DiagnosticCategory.Warning:
         return "warning";
       default:
         return "error";
@@ -2950,22 +4458,228 @@ async function analyzeFile(filePath, options = {}) {
 }
 var OpenPkg = DocCov;
 function resolvePackageDir(entryFile) {
-  const fallbackDir = path5.dirname(entryFile);
+  const fallbackDir = path6.dirname(entryFile);
   let currentDir = fallbackDir;
   while (true) {
-    const candidate = path5.join(currentDir, "package.json");
+    const candidate = path6.join(currentDir, "package.json");
     if (fsSync.existsSync(candidate)) {
       return currentDir;
     }
-    const parentDir = path5.dirname(currentDir);
+    const parentDir = path6.dirname(currentDir);
     if (parentDir === currentDir) {
       return fallbackDir;
     }
     currentDir = parentDir;
   }
 }
+// src/utils/example-runner.ts
+import { spawn } from "node:child_process";
+import * as fs5 from "node:fs";
+import * as os from "node:os";
+import * as path7 from "node:path";
+function stripCodeBlockMarkers(code) {
+  return code.replace(/^```(?:ts|typescript|js|javascript)?\n?/i, "").replace(/\n?```$/i, "").trim();
+}
+async function runExample(code, options = {}) {
+  const { timeout = 5000, cwd = process.cwd() } = options;
+  const cleanCode = stripCodeBlockMarkers(code);
+  const tmpFile = path7.join(cwd, `doccov-example-${Date.now()}-${Math.random().toString(36).slice(2)}.ts`);
+  try {
+    fs5.writeFileSync(tmpFile, cleanCode, "utf-8");
+    const startTime = Date.now();
+    return await new Promise((resolve3) => {
+      let stdout = "";
+      let stderr = "";
+      let killed = false;
+      const proc = spawn("node", ["--experimental-strip-types", tmpFile], {
+        cwd,
+        timeout,
+        stdio: ["ignore", "pipe", "pipe"]
+      });
+      proc.stdout?.on("data", (data) => {
+        stdout += data.toString();
+      });
+      proc.stderr?.on("data", (data) => {
+        stderr += data.toString();
+      });
+      const timeoutId = setTimeout(() => {
+        killed = true;
+        proc.kill("SIGKILL");
+      }, timeout);
+      proc.on("close", (exitCode) => {
+        clearTimeout(timeoutId);
+        const duration = Date.now() - startTime;
+        if (killed) {
+          resolve3({
+            success: false,
+            stdout,
+            stderr: stderr || `Example timed out after ${timeout}ms`,
+            exitCode: exitCode ?? 1,
+            duration
+          });
+        } else {
+          resolve3({
+            success: exitCode === 0,
+            stdout,
+            stderr,
+            exitCode: exitCode ?? 1,
+            duration
+          });
+        }
+      });
+      proc.on("error", (error) => {
+        clearTimeout(timeoutId);
+        resolve3({
+          success: false,
+          stdout,
+          stderr: error.message,
+          exitCode: 1,
+          duration: Date.now() - startTime
+        });
+      });
+    });
+  } finally {
+    try {
+      fs5.unlinkSync(tmpFile);
+    } catch {}
+  }
+}
+async function runExamples(examples, options = {}) {
+  const results = new Map;
+  for (let i = 0;i < examples.length; i++) {
+    const example = examples[i];
+    if (typeof example === "string" && example.trim()) {
+      results.set(i, await runExample(example, options));
+    }
+  }
+  return results;
+}
+function detectPackageManager(cwd) {
+  if (fs5.existsSync(path7.join(cwd, "bun.lockb")))
+    return "bun";
+  if (fs5.existsSync(path7.join(cwd, "pnpm-lock.yaml")))
+    return "pnpm";
+  return "npm";
+}
+function getInstallCommand(pm, packagePath) {
+  switch (pm) {
+    case "bun":
+      return { cmd: "bun", args: ["add", packagePath] };
+    case "pnpm":
+      return { cmd: "pnpm", args: ["add", packagePath] };
+    default:
+      return { cmd: "npm", args: ["install", packagePath, "--legacy-peer-deps"] };
+  }
+}
+async function runCommand(cmd, args, options) {
+  return new Promise((resolve3) => {
+    let stdout = "";
+    let stderr = "";
+    let killed = false;
+    const proc = spawn(cmd, args, {
+      cwd: options.cwd,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    proc.stdout?.on("data", (data) => {
+      stdout += data.toString();
+    });
+    proc.stderr?.on("data", (data) => {
+      stderr += data.toString();
+    });
+    const timeoutId = setTimeout(() => {
+      killed = true;
+      proc.kill("SIGKILL");
+    }, options.timeout);
+    proc.on("close", (exitCode) => {
+      clearTimeout(timeoutId);
+      if (killed) {
+        resolve3({
+          success: false,
+          stdout,
+          stderr: stderr || `Command timed out after ${options.timeout}ms`,
+          exitCode: exitCode ?? 1
+        });
+      } else {
+        resolve3({
+          success: exitCode === 0,
+          stdout,
+          stderr,
+          exitCode: exitCode ?? 1
+        });
+      }
+    });
+    proc.on("error", (error) => {
+      clearTimeout(timeoutId);
+      resolve3({
+        success: false,
+        stdout,
+        stderr: error.message,
+        exitCode: 1
+      });
+    });
+  });
+}
+async function runExamplesWithPackage(examples, options) {
+  const { packagePath, packageManager, installTimeout = 60000, timeout = 5000 } = options;
+  const startTime = Date.now();
+  const results = new Map;
+  const absolutePackagePath = path7.resolve(packagePath);
+  const workDir = path7.join(os.tmpdir(), `doccov-examples-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  try {
+    fs5.mkdirSync(workDir, { recursive: true });
+    const pkgJson = { name: "doccov-example-runner", type: "module" };
+    fs5.writeFileSync(path7.join(workDir, "package.json"), JSON.stringify(pkgJson, null, 2));
+    const pm = packageManager ?? detectPackageManager(options.cwd ?? process.cwd());
+    const { cmd, args } = getInstallCommand(pm, absolutePackagePath);
+    const installResult = await runCommand(cmd, args, {
+      cwd: workDir,
+      timeout: installTimeout
+    });
+    if (!installResult.success) {
+      return {
+        results,
+        installSuccess: false,
+        installError: installResult.stderr || `${pm} install failed with exit code ${installResult.exitCode}`,
+        totalDuration: Date.now() - startTime
+      };
+    }
+    for (let i = 0;i < examples.length; i++) {
+      const example = examples[i];
+      if (typeof example === "string" && example.trim()) {
+        results.set(i, await runExample(example, { timeout, cwd: workDir }));
+      }
+    }
+    return {
+      results,
+      installSuccess: true,
+      totalDuration: Date.now() - startTime
+    };
+  } finally {
+    try {
+      fs5.rmSync(workDir, { recursive: true, force: true });
+    } catch {}
+  }
+}
 export {
+  serializeJSDoc,
+  runExamplesWithPackage,
+  runExamples,
+  runExample,
+  parseJSDocToPatch,
+  parseAssertions,
+  mergeFixes,
+  isFixableDrift,
+  hasNonAssertionComments,
+  generateFixesForExport,
+  generateFix,
+  findJSDocLocation,
   extractPackageSpec,
+  detectExampleRuntimeErrors,
+  detectExampleAssertionFailures,
+  createSourceFile,
+  categorizeDrifts,
+  applyPatchToJSDoc,
+  applyEdits,
   analyzeFile,
   analyze,
   OpenPkg,