@openpkg-ts/extract 0.14.5 → 0.16.0

package/dist/shared/{chunk-mhaxcbzq.js → chunk-2v40ecks.js}

@@ -1,54 +1,63 @@
-// src/ast/registry.ts
+// src/types/schema-builder.ts
 import ts from "typescript";
+var BUILTIN_TYPE_SCHEMAS = {
+  Date: { type: "string", format: "date-time" },
+  RegExp: { type: "object", description: "RegExp" },
+  Error: { type: "object" },
+  Promise: { type: "object" },
+  Map: { type: "object" },
+  Set: { type: "object" },
+  WeakMap: { type: "object" },
+  WeakSet: { type: "object" },
+  Function: { type: "object" },
+  ArrayBuffer: { type: "string", format: "binary" },
+  ArrayBufferLike: { type: "string", format: "binary" },
+  DataView: { type: "string", format: "binary" },
+  Uint8Array: { type: "string", format: "byte" },
+  Uint16Array: { type: "string", format: "byte" },
+  Uint32Array: { type: "string", format: "byte" },
+  Int8Array: { type: "string", format: "byte" },
+  Int16Array: { type: "string", format: "byte" },
+  Int32Array: { type: "string", format: "byte" },
+  Float32Array: { type: "string", format: "byte" },
+  Float64Array: { type: "string", format: "byte" },
+  BigInt64Array: { type: "string", format: "byte" },
+  BigUint64Array: { type: "string", format: "byte" }
+};
 var PRIMITIVES = new Set([
   "string",
   "number",
   "boolean",
   "void",
-  "any",
   "undefined",
   "null",
-  "never",
+  "any",
   "unknown",
+  "never",
   "object",
   "symbol",
   "bigint"
 ]);
-var BUILTINS = new Set([
+var BUILTIN_GENERICS = new Set([
   "Array",
-  "ArrayBuffer",
-  "ArrayBufferLike",
-  "ArrayLike",
+  "ReadonlyArray",
   "Promise",
+  "PromiseLike",
   "Map",
   "Set",
   "WeakMap",
   "WeakSet",
-  "Date",
-  "RegExp",
-  "Error",
-  "Function",
-  "Object",
-  "String",
-  "Number",
-  "Boolean",
-  "Symbol",
-  "BigInt",
-  "Uint8Array",
-  "Int8Array",
-  "Uint16Array",
-  "Int16Array",
-  "Uint32Array",
-  "Int32Array",
-  "Float32Array",
-  "Float64Array",
-  "BigInt64Array",
-  "BigUint64Array",
-  "DataView",
-  "ReadonlyArray",
-  "Readonly",
+  "Iterable",
+  "Iterator",
+  "IterableIterator",
+  "AsyncIterable",
+  "AsyncIterator",
+  "AsyncIterableIterator",
+  "Generator",
+  "AsyncGenerator",
   "Partial",
   "Required",
+  "Readonly",
   "Pick",
   "Omit",
   "Record",
@@ -59,360 +68,404 @@ var BUILTINS = new Set([
   "ReturnType",
   "ConstructorParameters",
   "InstanceType",
-  "ThisType",
-  "Awaited",
-  "PromiseLike",
-  "Iterable",
-  "Iterator",
-  "IterableIterator",
-  "Generator",
-  "AsyncGenerator",
-  "AsyncIterable",
-  "AsyncIterator",
-  "AsyncIterableIterator",
+  "Awaited"
+]);
+var BUILTIN_TYPES = new Set([
+  "Date",
+  "RegExp",
+  "Error",
+  "Function",
+  "ArrayBuffer",
   "SharedArrayBuffer",
-  "Atomics",
-  "JSON",
-  "Math",
-  "console",
-  "globalThis"
+  "DataView",
+  "Uint8Array",
+  "Int8Array",
+  "Uint16Array",
+  "Int16Array",
+  "Uint32Array",
+  "Int32Array",
+  "Float32Array",
+  "Float64Array",
+  "BigInt64Array",
+  "BigUint64Array"
 ]);
-function isGenericTypeParameter(name) {
-  if (/^[A-Z]$/.test(name))
-    return true;
-  if (/^T[A-Z]/.test(name))
-    return true;
-  if (["Key", "Value", "Item", "Element"].includes(name))
+function isPrimitiveName(name) {
+  return PRIMITIVES.has(name);
+}
+function isBuiltinGeneric(name) {
+  return BUILTIN_GENERICS.has(name);
+}
+function isAnonymous(type) {
+  const symbol = type.getSymbol() || type.aliasSymbol;
+  if (!symbol)
     return true;
-  return false;
+  const name = symbol.getName();
+  return name.startsWith("__") || name === "";
 }
-function isExternalType(decl) {
-  const sourceFile = decl.getSourceFile();
-  if (!sourceFile)
+function withDepth(ctx, fn) {
+  ctx.currentDepth++;
+  try {
+    return fn();
+  } finally {
+    ctx.currentDepth--;
+  }
+}
+function isAtMaxDepth(ctx) {
+  if (!ctx)
     return false;
-  return sourceFile.fileName.includes("node_modules");
+  return ctx.currentDepth >= ctx.maxTypeDepth;
 }
-
-class TypeRegistry {
-  types = new Map;
-  processing = new Set;
-  add(type) {
-    this.types.set(type.id, type);
+function buildSchema(type, checker, ctx, _depth = 0) {
+  if (isAtMaxDepth(ctx)) {
+    return { type: checker.typeToString(type) };
   }
-  get(id) {
-    return this.types.get(id);
+  if (ctx?.visitedTypes.has(type)) {
+    const callSignatures = type.getCallSignatures();
+    if (callSignatures.length > 0) {
+      return buildFunctionSchema(callSignatures, checker, ctx);
+    }
+    const symbol2 = type.getSymbol() || type.aliasSymbol;
+    if (symbol2) {
+      return { $ref: `#/types/${symbol2.getName()}` };
+    }
+    return { type: checker.typeToString(type) };
   }
-  has(id) {
-    return this.types.has(id);
+  if (ctx && type.flags & ts.TypeFlags.Object) {
+    ctx.visitedTypes.add(type);
   }
-  getAll() {
-    return Array.from(this.types.values());
+  if (type.flags & ts.TypeFlags.String)
+    return { type: "string" };
+  if (type.flags & ts.TypeFlags.Number)
+    return { type: "number" };
+  if (type.flags & ts.TypeFlags.Boolean)
+    return { type: "boolean" };
+  if (type.flags & ts.TypeFlags.Undefined)
+    return { type: "undefined" };
+  if (type.flags & ts.TypeFlags.Null)
+    return { type: "null" };
+  if (type.flags & ts.TypeFlags.Void)
+    return { type: "void" };
+  if (type.flags & ts.TypeFlags.Any)
+    return { type: "any" };
+  if (type.flags & ts.TypeFlags.Unknown)
+    return { type: "unknown" };
+  if (type.flags & ts.TypeFlags.Never)
+    return { type: "never" };
+  if (type.flags & ts.TypeFlags.BigInt)
+    return { type: "bigint" };
+  if (type.flags & ts.TypeFlags.ESSymbol)
+    return { type: "symbol" };
+  if (type.flags & ts.TypeFlags.StringLiteral) {
+    const literal = type.value;
+    return { type: "string", enum: [literal] };
   }
-  registerType(type, checker, exportedIds) {
-    const symbol = type.getSymbol() || type.aliasSymbol;
-    if (!symbol)
-      return;
-    const name = symbol.getName();
-    if (PRIMITIVES.has(name))
-      return;
-    if (BUILTINS.has(name))
-      return;
-    if (name.startsWith("__"))
-      return;
-    if (symbol.flags & ts.SymbolFlags.EnumMember)
-      return;
-    if (symbol.flags & ts.SymbolFlags.TypeParameter)
-      return;
-    if (symbol.flags & ts.SymbolFlags.Method)
-      return;
-    if (symbol.flags & ts.SymbolFlags.Function)
-      return;
-    if (isGenericTypeParameter(name))
-      return;
-    if (this.has(name))
-      return name;
-    if (this.processing.has(name))
-      return name;
-    this.processing.add(name);
-    try {
-      const specType = this.buildStubType(symbol, checker);
-      if (specType) {
-        this.add(specType);
-        return specType.id;
-      }
-    } finally {
-      this.processing.delete(name);
-    }
-    return;
+  if (type.flags & ts.TypeFlags.NumberLiteral) {
+    const literal = type.value;
+    return { type: "number", enum: [literal] };
   }
-  buildStubType(symbol, checker) {
-    const name = symbol.getName();
-    const decl = symbol.declarations?.[0];
-    let kind = "type";
-    const external = decl ? isExternalType(decl) : false;
-    if (decl) {
-      if (ts.isClassDeclaration(decl))
-        kind = "class";
-      else if (ts.isInterfaceDeclaration(decl))
-        kind = "interface";
-      else if (ts.isEnumDeclaration(decl))
-        kind = "enum";
+  if (type.flags & ts.TypeFlags.BooleanLiteral) {
+    const intrinsicName = type.intrinsicName;
+    return { type: "boolean", enum: [intrinsicName === "true"] };
+  }
+  if (type.isUnion()) {
+    const types = type.types;
+    const allStringLiterals = types.every((t) => t.flags & ts.TypeFlags.StringLiteral);
+    if (allStringLiterals) {
+      const enumValues = types.map((t) => t.value);
+      return { type: "string", enum: enumValues };
     }
-    if (external) {
-      kind = "external";
+    const allNumberLiterals = types.every((t) => t.flags & ts.TypeFlags.NumberLiteral);
+    if (allNumberLiterals) {
+      const enumValues = types.map((t) => t.value);
+      return { type: "number", enum: enumValues };
     }
-    const type = checker.getDeclaredTypeOfSymbol(symbol);
-    const typeString = checker.typeToString(type);
-    return {
-      id: name,
-      name,
-      kind,
-      schema: { type: typeString },
-      ...external ? { external: true } : {}
-    };
+    if (ctx) {
+      return withDepth(ctx, () => ({
+        anyOf: types.map((t) => buildSchema(t, checker, ctx))
+      }));
+    }
+    return { anyOf: types.map((t) => buildSchema(t, checker, ctx)) };
   }
-  registerFromSymbol(symbol, checker) {
-    const name = symbol.getName();
-    if (this.has(name))
-      return this.get(name);
-    const specType = this.buildStubType(symbol, checker);
-    if (specType) {
-      this.add(specType);
-      return specType;
+  if (type.isIntersection()) {
+    if (ctx) {
+      return withDepth(ctx, () => ({
+        allOf: type.types.map((t) => buildSchema(t, checker, ctx))
+      }));
     }
-    return;
+    return { allOf: type.types.map((t) => buildSchema(t, checker, ctx)) };
   }
-}
-
-// src/ast/utils.ts
-import ts2 from "typescript";
-function parseExamplesFromTags(tags) {
-  const examples = [];
-  for (const tag of tags) {
-    if (tag.name !== "example")
-      continue;
-    const text = tag.text.trim();
-    const fenceMatch = text.match(/^```(\w*)\n([\s\S]*?)\n?```$/);
-    if (fenceMatch) {
-      const lang = fenceMatch[1] || undefined;
-      const code = fenceMatch[2].trim();
-      const example = { code };
-      if (lang && ["ts", "js", "tsx", "jsx", "shell", "json"].includes(lang)) {
-        example.language = lang;
+  if (checker.isArrayType(type)) {
+    const typeRef2 = type;
+    const elementType = typeRef2.typeArguments?.[0];
+    if (elementType) {
+      if (ctx) {
+        return withDepth(ctx, () => ({
+          type: "array",
+          items: buildSchema(elementType, checker, ctx)
+        }));
       }
-      examples.push(example);
-    } else if (text) {
-      examples.push({ code: text });
+      return { type: "array", items: buildSchema(elementType, checker, ctx) };
     }
+    return { type: "array" };
   }
-  return examples;
-}
-function getJSDocComment(node) {
-  const jsDocTags = ts2.getJSDocTags(node);
-  const tags = jsDocTags.map((tag) => ({
-    name: tag.tagName.text,
-    text: typeof tag.comment === "string" ? tag.comment : ts2.getTextOfJSDocComment(tag.comment) ?? ""
-  }));
-  const jsDocComments = node.jsDoc;
-  let description;
-  if (jsDocComments && jsDocComments.length > 0) {
-    const firstDoc = jsDocComments[0];
-    if (firstDoc.comment) {
-      description = typeof firstDoc.comment === "string" ? firstDoc.comment : ts2.getTextOfJSDocComment(firstDoc.comment);
+  if (checker.isTupleType(type)) {
+    const typeRef2 = type;
+    const elementTypes = typeRef2.typeArguments ?? [];
+    if (ctx) {
+      return withDepth(ctx, () => ({
+        type: "array",
+        prefixedItems: elementTypes.map((t) => buildSchema(t, checker, ctx)),
+        minItems: elementTypes.length,
+        maxItems: elementTypes.length
+      }));
     }
+    return {
+      type: "array",
+      prefixedItems: elementTypes.map((t) => buildSchema(t, checker, ctx)),
+      minItems: elementTypes.length,
+      maxItems: elementTypes.length
+    };
   }
-  const examples = parseExamplesFromTags(tags);
-  return { description, tags, examples };
+  const typeRef = type;
+  if (typeRef.target && typeRef.typeArguments && typeRef.typeArguments.length > 0) {
+    const symbol2 = typeRef.target.getSymbol();
+    const name = symbol2?.getName();
+    if (name && BUILTIN_TYPES.has(name)) {
+      return { $ref: `#/types/${name}` };
+    }
+    if (name && (isBuiltinGeneric(name) || !isAnonymous(typeRef.target))) {
+      if (ctx) {
+        return withDepth(ctx, () => ({
+          $ref: `#/types/${name}`,
+          typeArguments: typeRef.typeArguments.map((t) => buildSchema(t, checker, ctx))
+        }));
+      }
+      return {
+        $ref: `#/types/${name}`,
+        typeArguments: typeRef.typeArguments.map((t) => buildSchema(t, checker, ctx))
+      };
+    }
+  }
+  if (type.flags & ts.TypeFlags.Object) {
+    const callSignatures = type.getCallSignatures();
+    if (callSignatures.length > 0) {
+      return buildFunctionSchema(callSignatures, checker, ctx);
+    }
+  }
+  const symbol = type.getSymbol() || type.aliasSymbol;
+  if (symbol && !isAnonymous(type)) {
+    const name = symbol.getName();
+    if (isPrimitiveName(name)) {
+      return { type: name };
+    }
+    if (BUILTIN_TYPES.has(name)) {
+      return { $ref: `#/types/${name}` };
+    }
+    if (!name.startsWith("__")) {
+      return { $ref: `#/types/${name}` };
+    }
+  }
+  if (type.flags & ts.TypeFlags.Object) {
+    const objectType = type;
+    const properties = type.getProperties();
+    if (properties.length > 0 || objectType.objectFlags & ts.ObjectFlags.Anonymous) {
+      return buildObjectSchema(properties, checker, ctx);
+    }
+  }
+  return { type: checker.typeToString(type) };
 }
-function getSourceLocation(node, sourceFile) {
-  const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
-  return {
-    file: sourceFile.fileName,
-    line: line + 1
+function buildFunctionSchema(callSignatures, checker, ctx) {
+  const buildSignatures = () => {
+    const signatures = callSignatures.map((sig) => {
+      const params = sig.getParameters().map((param) => {
+        const paramType = checker.getTypeOfSymbolAtLocation(param, param.valueDeclaration);
+        return {
+          name: param.getName(),
+          schema: buildSchema(paramType, checker, ctx),
+          required: !(param.flags & ts.SymbolFlags.Optional)
+        };
+      });
+      const returnType = checker.getReturnTypeOfSignature(sig);
+      return {
+        parameters: params,
+        returns: {
+          schema: buildSchema(returnType, checker, ctx)
+        }
+      };
+    });
+    return signatures;
   };
+  if (ctx) {
+    return withDepth(ctx, () => ({ type: "function", signatures: buildSignatures() }));
+  }
+  return { type: "function", signatures: buildSignatures() };
 }
-function getParamDescription(propertyName, jsdocTags, inferredAlias) {
-  for (const tag of jsdocTags) {
-    if (tag.tagName.text !== "param")
-      continue;
-    const paramTag = tag;
-    const tagParamName = paramTag.name?.getText() ?? "";
-    const isMatch = tagParamName === propertyName || inferredAlias && tagParamName === `${inferredAlias}.${propertyName}` || tagParamName.endsWith(`.${propertyName}`);
-    if (isMatch) {
-      const comment = typeof tag.comment === "string" ? tag.comment : ts2.getTextOfJSDocComment(tag.comment);
-      return comment?.trim() || undefined;
+function buildObjectSchema(properties, checker, ctx) {
+  const buildProps = () => {
+    const props = {};
+    const required = [];
+    for (const prop of properties) {
+      const propName = prop.getName();
+      if (propName.startsWith("_"))
+        continue;
+      const propType = checker.getTypeOfSymbol(prop);
+      props[propName] = buildSchema(propType, checker, ctx);
+      if (!(prop.flags & ts.SymbolFlags.Optional)) {
+        required.push(propName);
+      }
     }
+    return {
+      type: "object",
+      properties: props,
+      ...required.length > 0 ? { required } : {}
+    };
+  };
+  if (ctx) {
+    return withDepth(ctx, buildProps);
   }
-  return;
+  return buildProps();
 }
-function extractTypeParameters(node, checker) {
-  if (!node.typeParameters || node.typeParameters.length === 0) {
-    return;
-  }
-  return node.typeParameters.map((tp) => {
-    const name = tp.name.text;
-    let constraint;
-    if (tp.constraint) {
-      const constraintType = checker.getTypeAtLocation(tp.constraint);
-      constraint = checker.typeToString(constraintType);
-    }
-    let defaultType;
-    if (tp.default) {
-      const defType = checker.getTypeAtLocation(tp.default);
-      defaultType = checker.typeToString(defType);
-    }
+function isPureRefSchema(schema) {
+  return typeof schema === "object" && Object.keys(schema).length === 1 && "$ref" in schema;
+}
+function withDescription(schema, description) {
+  if (isPureRefSchema(schema)) {
     return {
-      name,
-      ...constraint ? { constraint } : {},
-      ...defaultType ? { default: defaultType } : {}
+      allOf: [schema],
+      description
     };
-  });
+  }
+  return { ...schema, description };
 }
-function isSymbolDeprecated(symbol) {
-  if (!symbol) {
-    return false;
+function schemaIsAny(schema) {
+  if (typeof schema === "string") {
+    return schema === "any";
   }
-  const jsDocTags = symbol.getJsDocTags();
-  if (jsDocTags.some((tag) => tag.name.toLowerCase() === "deprecated")) {
+  if ("type" in schema && schema.type === "any" && Object.keys(schema).length === 1) {
     return true;
   }
-  for (const declaration of symbol.getDeclarations() ?? []) {
-    if (ts2.getJSDocDeprecatedTag(declaration)) {
-      return true;
-    }
-  }
   return false;
 }
-
-// src/compiler/program.ts
-import * as path from "node:path";
-import ts3 from "typescript";
-var DEFAULT_COMPILER_OPTIONS = {
-  target: ts3.ScriptTarget.Latest,
-  module: ts3.ModuleKind.CommonJS,
-  lib: ["lib.es2021.d.ts"],
-  declaration: true,
-  moduleResolution: ts3.ModuleResolutionKind.NodeJs
-};
-function createProgram({
-  entryFile,
-  baseDir = path.dirname(entryFile),
-  content
-}) {
-  const configPath = ts3.findConfigFile(baseDir, ts3.sys.fileExists, "tsconfig.json");
-  let compilerOptions = { ...DEFAULT_COMPILER_OPTIONS };
-  if (configPath) {
-    const configFile = ts3.readConfigFile(configPath, ts3.sys.readFile);
-    const parsedConfig = ts3.parseJsonConfigFileContent(configFile.config, ts3.sys, path.dirname(configPath));
-    compilerOptions = { ...compilerOptions, ...parsedConfig.options };
+function schemasAreEqual(left, right) {
+  if (typeof left !== typeof right) {
+    return false;
   }
-  const allowJsVal = compilerOptions.allowJs;
-  if (typeof allowJsVal === "boolean" && allowJsVal) {
-    compilerOptions = { ...compilerOptions, allowJs: false, checkJs: false };
+  if (typeof left === "string" && typeof right === "string") {
+    return left === right;
   }
-  const compilerHost = ts3.createCompilerHost(compilerOptions, true);
-  let inMemorySource;
-  if (content !== undefined) {
-    inMemorySource = ts3.createSourceFile(entryFile, content, ts3.ScriptTarget.Latest, true, ts3.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);
-    };
+  if (left == null || right == null) {
+    return left === right;
   }
-  const program = ts3.createProgram([entryFile], compilerOptions, compilerHost);
-  const sourceFile = inMemorySource ?? program.getSourceFile(entryFile);
-  return {
-    program,
-    compilerHost,
-    compilerOptions,
-    sourceFile,
-    configPath
+  const normalize = (value) => {
+    if (Array.isArray(value)) {
+      return value.map((item) => normalize(item));
+    }
+    if (value && typeof value === "object") {
+      const sortedEntries = Object.entries(value).map(([key, val]) => [key, normalize(val)]).sort(([keyA], [keyB]) => keyA.localeCompare(keyB));
+      return Object.fromEntries(sortedEntries);
+    }
+    return value;
   };
+  return JSON.stringify(normalize(left)) === JSON.stringify(normalize(right));
 }
-
-// src/types/schema-builder.ts
-import ts4 from "typescript";
-var BUILTIN_TYPE_SCHEMAS = {
-  Date: { type: "string", format: "date-time" },
-  RegExp: { type: "object", description: "RegExp" },
-  Error: { type: "object" },
-  Promise: { type: "object" },
-  Map: { type: "object" },
-  Set: { type: "object" },
-  WeakMap: { type: "object" },
-  WeakSet: { type: "object" },
-  Function: { type: "object" },
-  ArrayBuffer: { type: "string", format: "binary" },
-  ArrayBufferLike: { type: "string", format: "binary" },
-  DataView: { type: "string", format: "binary" },
-  Uint8Array: { type: "string", format: "byte" },
-  Uint16Array: { type: "string", format: "byte" },
-  Uint32Array: { type: "string", format: "byte" },
-  Int8Array: { type: "string", format: "byte" },
-  Int16Array: { type: "string", format: "byte" },
-  Int32Array: { type: "string", format: "byte" },
-  Float32Array: { type: "string", format: "byte" },
-  Float64Array: { type: "string", format: "byte" },
-  BigInt64Array: { type: "string", format: "byte" },
-  BigUint64Array: { type: "string", format: "byte" }
-};
+function deduplicateSchemas(schemas) {
+  const result = [];
+  for (const schema of schemas) {
+    const isDuplicate = result.some((existing) => schemasAreEqual(existing, schema));
+    if (!isDuplicate) {
+      result.push(schema);
+    }
+  }
+  return result;
+}
+function findDiscriminatorProperty(unionTypes, checker) {
+  const memberProps = [];
+  for (const t of unionTypes) {
+    if (t.flags & (ts.TypeFlags.Null | ts.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 = checker.getTypeOfSymbolAtLocation(prop, declaration);
+        if (propType.isStringLiteral()) {
+          propValues.set(prop.getName(), propType.value);
+        } else if (propType.isNumberLiteral()) {
+          propValues.set(prop.getName(), propType.value);
+        }
+      } catch {}
+    }
+    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;
+}
+
+// src/ast/registry.ts
+import ts2 from "typescript";
 var PRIMITIVES2 = new Set([
   "string",
   "number",
   "boolean",
   "void",
+  "any",
   "undefined",
   "null",
-  "any",
-  "unknown",
   "never",
+  "unknown",
   "object",
   "symbol",
   "bigint"
 ]);
-var BUILTIN_GENERICS = new Set([
+var BUILTINS = new Set([
   "Array",
-  "ReadonlyArray",
+  "ArrayBuffer",
+  "ArrayBufferLike",
+  "ArrayLike",
   "Promise",
-  "PromiseLike",
   "Map",
   "Set",
   "WeakMap",
   "WeakSet",
-  "Iterable",
-  "Iterator",
-  "IterableIterator",
-  "AsyncIterable",
-  "AsyncIterator",
-  "AsyncIterableIterator",
-  "Generator",
-  "AsyncGenerator",
-  "Partial",
-  "Required",
-  "Readonly",
-  "Pick",
-  "Omit",
-  "Record",
-  "Exclude",
-  "Extract",
-  "NonNullable",
-  "Parameters",
-  "ReturnType",
-  "ConstructorParameters",
-  "InstanceType",
-  "Awaited"
-]);
-var BUILTIN_TYPES = new Set([
   "Date",
   "RegExp",
   "Error",
   "Function",
-  "ArrayBuffer",
-  "SharedArrayBuffer",
-  "DataView",
+  "Object",
+  "String",
+  "Number",
+  "Boolean",
+  "Symbol",
+  "BigInt",
   "Uint8Array",
   "Int8Array",
   "Uint16Array",
@@ -422,230 +475,158 @@ var BUILTIN_TYPES = new Set([
   "Float32Array",
   "Float64Array",
   "BigInt64Array",
-  "BigUint64Array"
+  "BigUint64Array",
+  "DataView",
+  "ReadonlyArray",
+  "Readonly",
+  "Partial",
+  "Required",
+  "Pick",
+  "Omit",
+  "Record",
+  "Exclude",
+  "Extract",
+  "NonNullable",
+  "Parameters",
+  "ReturnType",
+  "ConstructorParameters",
+  "InstanceType",
+  "ThisType",
+  "Awaited",
+  "PromiseLike",
+  "Iterable",
+  "Iterator",
+  "IterableIterator",
+  "Generator",
+  "AsyncGenerator",
+  "AsyncIterable",
+  "AsyncIterator",
+  "AsyncIterableIterator",
+  "SharedArrayBuffer",
+  "Atomics",
+  "JSON",
+  "Math",
+  "console",
+  "globalThis"
 ]);
-function isPrimitiveName(name) {
-  return PRIMITIVES2.has(name);
-}
-function isBuiltinGeneric(name) {
-  return BUILTIN_GENERICS.has(name);
-}
-function isAnonymous(type) {
-  const symbol = type.getSymbol() || type.aliasSymbol;
-  if (!symbol)
+function isGenericTypeParameter(name) {
+  if (/^[A-Z]$/.test(name))
     return true;
-  const name = symbol.getName();
-  return name.startsWith("__") || name === "";
-}
-function withDepth(ctx, fn) {
-  ctx.currentDepth++;
-  try {
-    return fn();
-  } finally {
-    ctx.currentDepth--;
-  }
+  if (/^T[A-Z]/.test(name))
+    return true;
+  if (["Key", "Value", "Item", "Element"].includes(name))
+    return true;
+  return false;
 }
-function isAtMaxDepth(ctx) {
-  if (!ctx)
+function isExternalType(decl) {
+  const sourceFile = decl.getSourceFile();
+  if (!sourceFile)
     return false;
-  return ctx.currentDepth >= ctx.maxTypeDepth;
+  return sourceFile.fileName.includes("node_modules");
 }
-function buildSchema(type, checker, ctx, _depth = 0) {
-  if (isAtMaxDepth(ctx)) {
-    return { type: checker.typeToString(type) };
-  }
-  if (ctx?.visitedTypes.has(type)) {
-    const callSignatures = type.getCallSignatures();
-    if (callSignatures.length > 0) {
-      return buildFunctionSchema(callSignatures, checker, ctx);
-    }
-    const symbol2 = type.getSymbol() || type.aliasSymbol;
-    if (symbol2) {
-      return { $ref: `#/types/${symbol2.getName()}` };
-    }
-    return { type: checker.typeToString(type) };
-  }
-  if (ctx && type.flags & ts4.TypeFlags.Object) {
-    ctx.visitedTypes.add(type);
-  }
-  if (type.flags & ts4.TypeFlags.String)
-    return { type: "string" };
-  if (type.flags & ts4.TypeFlags.Number)
-    return { type: "number" };
-  if (type.flags & ts4.TypeFlags.Boolean)
-    return { type: "boolean" };
-  if (type.flags & ts4.TypeFlags.Undefined)
-    return { type: "undefined" };
-  if (type.flags & ts4.TypeFlags.Null)
-    return { type: "null" };
-  if (type.flags & ts4.TypeFlags.Void)
-    return { type: "void" };
-  if (type.flags & ts4.TypeFlags.Any)
-    return { type: "any" };
-  if (type.flags & ts4.TypeFlags.Unknown)
-    return { type: "unknown" };
-  if (type.flags & ts4.TypeFlags.Never)
-    return { type: "never" };
-  if (type.flags & ts4.TypeFlags.BigInt)
-    return { type: "bigint" };
-  if (type.flags & ts4.TypeFlags.ESSymbol)
-    return { type: "symbol" };
-  if (type.flags & ts4.TypeFlags.StringLiteral) {
-    const literal = type.value;
-    return { type: "string", enum: [literal] };
-  }
-  if (type.flags & ts4.TypeFlags.NumberLiteral) {
-    const literal = type.value;
-    return { type: "number", enum: [literal] };
-  }
-  if (type.flags & ts4.TypeFlags.BooleanLiteral) {
-    const intrinsicName = type.intrinsicName;
-    return { type: "boolean", enum: [intrinsicName === "true"] };
-  }
-  if (type.isUnion()) {
-    const types = type.types;
-    const allStringLiterals = types.every((t) => t.flags & ts4.TypeFlags.StringLiteral);
-    if (allStringLiterals) {
-      const enumValues = types.map((t) => t.value);
-      return { type: "string", enum: enumValues };
-    }
-    const allNumberLiterals = types.every((t) => t.flags & ts4.TypeFlags.NumberLiteral);
-    if (allNumberLiterals) {
-      const enumValues = types.map((t) => t.value);
-      return { type: "number", enum: enumValues };
-    }
-    if (ctx) {
-      return withDepth(ctx, () => ({
-        anyOf: types.map((t) => buildSchema(t, checker, ctx))
-      }));
-    }
-    return { anyOf: types.map((t) => buildSchema(t, checker, ctx)) };
+
+class TypeRegistry {
+  types = new Map;
+  processing = new Set;
+  add(type) {
+    this.types.set(type.id, type);
   }
-  if (type.isIntersection()) {
-    if (ctx) {
-      return withDepth(ctx, () => ({
-        allOf: type.types.map((t) => buildSchema(t, checker, ctx))
-      }));
-    }
-    return { allOf: type.types.map((t) => buildSchema(t, checker, ctx)) };
+  get(id) {
+    return this.types.get(id);
   }
-  if (checker.isArrayType(type)) {
-    const typeRef2 = type;
-    const elementType = typeRef2.typeArguments?.[0];
-    if (elementType) {
-      if (ctx) {
-        return withDepth(ctx, () => ({
-          type: "array",
-          items: buildSchema(elementType, checker, ctx)
-        }));
-      }
-      return { type: "array", items: buildSchema(elementType, checker, ctx) };
-    }
-    return { type: "array" };
+  has(id) {
+    return this.types.has(id);
   }
-  if (checker.isTupleType(type)) {
-    const typeRef2 = type;
-    const elementTypes = typeRef2.typeArguments ?? [];
-    if (ctx) {
-      return withDepth(ctx, () => ({
-        type: "array",
-        prefixedItems: elementTypes.map((t) => buildSchema(t, checker, ctx)),
-        minItems: elementTypes.length,
-        maxItems: elementTypes.length
-      }));
-    }
-    return {
-      type: "array",
-      prefixedItems: elementTypes.map((t) => buildSchema(t, checker, ctx)),
-      minItems: elementTypes.length,
-      maxItems: elementTypes.length
-    };
+  getAll() {
+    return Array.from(this.types.values());
   }
-  const typeRef = type;
-  if (typeRef.target && typeRef.typeArguments && typeRef.typeArguments.length > 0) {
-    const symbol2 = typeRef.target.getSymbol();
-    const name = symbol2?.getName();
-    if (name && BUILTIN_TYPES.has(name)) {
-      return { $ref: `#/types/${name}` };
-    }
-    if (name && (isBuiltinGeneric(name) || !isAnonymous(typeRef.target))) {
-      if (ctx) {
-        return withDepth(ctx, () => ({
-          $ref: `#/types/${name}`,
-          typeArguments: typeRef.typeArguments.map((t) => buildSchema(t, checker, ctx))
-        }));
+  registerType(type, ctx) {
+    const symbol = type.getSymbol() || type.aliasSymbol;
+    if (!symbol)
+      return;
+    const name = symbol.getName();
+    if (PRIMITIVES2.has(name))
+      return;
+    if (BUILTINS.has(name))
+      return;
+    if (name.startsWith("__"))
+      return;
+    if (symbol.flags & ts2.SymbolFlags.EnumMember)
+      return;
+    if (symbol.flags & ts2.SymbolFlags.TypeParameter)
+      return;
+    if (symbol.flags & ts2.SymbolFlags.Method)
+      return;
+    if (symbol.flags & ts2.SymbolFlags.Function)
+      return;
+    if (isGenericTypeParameter(name))
+      return;
+    if (this.has(name))
+      return name;
+    if (this.processing.has(name))
+      return name;
+    this.processing.add(name);
+    try {
+      const specType = this.buildSpecType(type, symbol, ctx);
+      if (specType) {
+        this.add(specType);
+        return specType.id;
       }
-      return {
-        $ref: `#/types/${name}`,
-        typeArguments: typeRef.typeArguments.map((t) => buildSchema(t, checker, ctx))
-      };
-    }
-  }
-  if (type.flags & ts4.TypeFlags.Object) {
-    const callSignatures = type.getCallSignatures();
-    if (callSignatures.length > 0) {
-      return buildFunctionSchema(callSignatures, checker, ctx);
+    } finally {
+      this.processing.delete(name);
     }
+    return;
   }
-  const symbol = type.getSymbol() || type.aliasSymbol;
-  if (symbol && !isAnonymous(type)) {
+  buildSpecType(type, symbol, ctx) {
     const name = symbol.getName();
-    if (isPrimitiveName(name)) {
-      return { type: name };
-    }
-    if (BUILTIN_TYPES.has(name)) {
-      return { $ref: `#/types/${name}` };
+    const decl = symbol.declarations?.[0];
+    const checker = ctx.typeChecker;
+    let kind = "type";
+    const external = decl ? isExternalType(decl) : false;
+    if (decl) {
+      if (ts2.isClassDeclaration(decl))
+        kind = "class";
+      else if (ts2.isInterfaceDeclaration(decl))
+        kind = "interface";
+      else if (ts2.isEnumDeclaration(decl))
+        kind = "enum";
     }
-    if (!name.startsWith("__")) {
-      return { $ref: `#/types/${name}` };
+    if (external) {
+      kind = "external";
     }
-  }
-  if (type.flags & ts4.TypeFlags.Object) {
-    const objectType = type;
-    const properties = type.getProperties();
-    if (properties.length > 0 || objectType.objectFlags & ts4.ObjectFlags.Anonymous) {
-      return buildObjectSchema(properties, checker, ctx);
+    let schema = buildSchema(type, checker, ctx);
+    if (this.isSelfRef(schema, name)) {
+      schema = this.buildObjectSchemaFromType(type, checker, ctx);
     }
+    return {
+      id: name,
+      name,
+      kind,
+      schema,
+      ...external ? { external: true } : {}
+    };
   }
-  return { type: checker.typeToString(type) };
-}
-function buildFunctionSchema(callSignatures, checker, ctx) {
-  const buildSignatures = () => {
-    const signatures = callSignatures.map((sig) => {
-      const params = sig.getParameters().map((param) => {
-        const paramType = checker.getTypeOfSymbolAtLocation(param, param.valueDeclaration);
-        return {
-          name: param.getName(),
-          schema: buildSchema(paramType, checker, ctx),
-          required: !(param.flags & ts4.SymbolFlags.Optional)
-        };
-      });
-      const returnType = checker.getReturnTypeOfSignature(sig);
-      return {
-        parameters: params,
-        returns: {
-          schema: buildSchema(returnType, checker, ctx)
-        }
-      };
-    });
-    return signatures;
-  };
-  if (ctx) {
-    return withDepth(ctx, () => ({ type: "function", signatures: buildSignatures() }));
-  }
-  return { type: "function", signatures: buildSignatures() };
-}
-function buildObjectSchema(properties, checker, ctx) {
-  const buildProps = () => {
+  isSelfRef(schema, typeName) {
+    if (typeof schema !== "object" || schema === null)
+      return false;
+    const obj = schema;
+    return obj.$ref === `#/types/${typeName}`;
+  }
+  buildObjectSchemaFromType(type, checker, ctx) {
+    const properties = type.getProperties();
+    if (properties.length === 0) {
+      return { type: checker.typeToString(type) };
+    }
     const props = {};
     const required = [];
-    for (const prop of properties) {
+    for (const prop of properties.slice(0, 20)) {
       const propName = prop.getName();
       if (propName.startsWith("_"))
         continue;
       const propType = checker.getTypeOfSymbol(prop);
+      this.registerType(propType, ctx);
       props[propName] = buildSchema(propType, checker, ctx);
-      if (!(prop.flags & ts4.SymbolFlags.Optional)) {
+      if (!(prop.flags & ts2.SymbolFlags.Optional)) {
         required.push(propName);
       }
     }
@@ -654,115 +635,156 @@ function buildObjectSchema(properties, checker, ctx) {
       properties: props,
       ...required.length > 0 ? { required } : {}
     };
-  };
-  if (ctx) {
-    return withDepth(ctx, buildProps);
   }
-  return buildProps();
-}
-function isPureRefSchema(schema) {
-  return typeof schema === "object" && Object.keys(schema).length === 1 && "$ref" in schema;
 }
-function withDescription(schema, description) {
-  if (isPureRefSchema(schema)) {
-    return {
-      allOf: [schema],
-      description
-    };
+
+// src/ast/utils.ts
+import ts3 from "typescript";
+function parseExamplesFromTags(tags) {
+  const examples = [];
+  for (const tag of tags) {
+    if (tag.name !== "example")
+      continue;
+    const text = tag.text.trim();
+    const fenceMatch = text.match(/^```(\w*)\n([\s\S]*?)\n?```$/);
+    if (fenceMatch) {
+      const lang = fenceMatch[1] || undefined;
+      const code = fenceMatch[2].trim();
+      const example = { code };
+      if (lang && ["ts", "js", "tsx", "jsx", "shell", "json"].includes(lang)) {
+        example.language = lang;
+      }
+      examples.push(example);
+    } else if (text) {
+      examples.push({ code: text });
+    }
   }
-  return { ...schema, description };
+  return examples;
 }
-function schemaIsAny(schema) {
-  if (typeof schema === "string") {
-    return schema === "any";
-  }
-  if ("type" in schema && schema.type === "any" && Object.keys(schema).length === 1) {
-    return true;
+function getJSDocComment(node) {
+  const jsDocTags = ts3.getJSDocTags(node);
+  const tags = jsDocTags.map((tag) => ({
+    name: tag.tagName.text,
+    text: typeof tag.comment === "string" ? tag.comment : ts3.getTextOfJSDocComment(tag.comment) ?? ""
+  }));
+  const jsDocComments = node.jsDoc;
+  let description;
+  if (jsDocComments && jsDocComments.length > 0) {
+    const firstDoc = jsDocComments[0];
+    if (firstDoc.comment) {
+      description = typeof firstDoc.comment === "string" ? firstDoc.comment : ts3.getTextOfJSDocComment(firstDoc.comment);
+    }
   }
-  return false;
+  const examples = parseExamplesFromTags(tags);
+  return { description, tags, examples };
 }
-function schemasAreEqual(left, right) {
-  if (typeof left !== typeof right) {
-    return false;
-  }
-  if (typeof left === "string" && typeof right === "string") {
-    return left === right;
-  }
-  if (left == null || right == null) {
-    return left === right;
-  }
-  const normalize = (value) => {
-    if (Array.isArray(value)) {
-      return value.map((item) => normalize(item));
-    }
-    if (value && typeof value === "object") {
-      const sortedEntries = Object.entries(value).map(([key, val]) => [key, normalize(val)]).sort(([keyA], [keyB]) => keyA.localeCompare(keyB));
-      return Object.fromEntries(sortedEntries);
-    }
-    return value;
+function getSourceLocation(node, sourceFile) {
+  const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+  return {
+    file: sourceFile.fileName,
+    line: line + 1
   };
-  return JSON.stringify(normalize(left)) === JSON.stringify(normalize(right));
 }
-function deduplicateSchemas(schemas) {
-  const result = [];
-  for (const schema of schemas) {
-    const isDuplicate = result.some((existing) => schemasAreEqual(existing, schema));
-    if (!isDuplicate) {
-      result.push(schema);
+function getParamDescription(propertyName, jsdocTags, inferredAlias) {
+  for (const tag of jsdocTags) {
+    if (tag.tagName.text !== "param")
+      continue;
+    const paramTag = tag;
+    const tagParamName = paramTag.name?.getText() ?? "";
+    const isMatch = tagParamName === propertyName || inferredAlias && tagParamName === `${inferredAlias}.${propertyName}` || tagParamName.endsWith(`.${propertyName}`);
+    if (isMatch) {
+      const comment = typeof tag.comment === "string" ? tag.comment : ts3.getTextOfJSDocComment(tag.comment);
+      return comment?.trim() || undefined;
     }
   }
-  return result;
+  return;
 }
-function findDiscriminatorProperty(unionTypes, checker) {
-  const memberProps = [];
-  for (const t of unionTypes) {
-    if (t.flags & (ts4.TypeFlags.Null | ts4.TypeFlags.Undefined)) {
-      continue;
+function extractTypeParameters(node, checker) {
+  if (!node.typeParameters || node.typeParameters.length === 0) {
+    return;
+  }
+  return node.typeParameters.map((tp) => {
+    const name = tp.name.text;
+    let constraint;
+    if (tp.constraint) {
+      const constraintType = checker.getTypeAtLocation(tp.constraint);
+      constraint = checker.typeToString(constraintType);
     }
-    const props = t.getProperties();
-    if (!props || props.length === 0) {
-      return;
+    let defaultType;
+    if (tp.default) {
+      const defType = checker.getTypeAtLocation(tp.default);
+      defaultType = checker.typeToString(defType);
     }
-    const propValues = new Map;
-    for (const prop of props) {
-      const declaration = prop.valueDeclaration ?? prop.declarations?.[0];
-      if (!declaration)
-        continue;
-      try {
-        const propType = checker.getTypeOfSymbolAtLocation(prop, declaration);
-        if (propType.isStringLiteral()) {
-          propValues.set(prop.getName(), propType.value);
-        } else if (propType.isNumberLiteral()) {
-          propValues.set(prop.getName(), propType.value);
-        }
-      } catch {}
+    return {
+      name,
+      ...constraint ? { constraint } : {},
+      ...defaultType ? { default: defaultType } : {}
+    };
+  });
+}
+function isSymbolDeprecated(symbol) {
+  if (!symbol) {
+    return false;
+  }
+  const jsDocTags = symbol.getJsDocTags();
+  if (jsDocTags.some((tag) => tag.name.toLowerCase() === "deprecated")) {
+    return true;
+  }
+  for (const declaration of symbol.getDeclarations() ?? []) {
+    if (ts3.getJSDocDeprecatedTag(declaration)) {
+      return true;
     }
-    memberProps.push(propValues);
   }
-  if (memberProps.length < 2) {
-    return;
+  return false;
+}
+
+// src/compiler/program.ts
+import * as path from "node:path";
+import ts4 from "typescript";
+var DEFAULT_COMPILER_OPTIONS = {
+  target: ts4.ScriptTarget.Latest,
+  module: ts4.ModuleKind.CommonJS,
+  lib: ["lib.es2021.d.ts"],
+  declaration: true,
+  moduleResolution: ts4.ModuleResolutionKind.NodeJs
+};
+function createProgram({
+  entryFile,
+  baseDir = path.dirname(entryFile),
+  content
+}) {
+  const configPath = ts4.findConfigFile(baseDir, ts4.sys.fileExists, "tsconfig.json");
+  let compilerOptions = { ...DEFAULT_COMPILER_OPTIONS };
+  if (configPath) {
+    const configFile = ts4.readConfigFile(configPath, ts4.sys.readFile);
+    const parsedConfig = ts4.parseJsonConfigFileContent(configFile.config, ts4.sys, path.dirname(configPath));
+    compilerOptions = { ...compilerOptions, ...parsedConfig.options };
   }
-  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;
+  const allowJsVal = compilerOptions.allowJs;
+  if (typeof allowJsVal === "boolean" && allowJsVal) {
+    compilerOptions = { ...compilerOptions, allowJs: false, checkJs: false };
+  }
+  const compilerHost = ts4.createCompilerHost(compilerOptions, true);
+  let inMemorySource;
+  if (content !== undefined) {
+    inMemorySource = ts4.createSourceFile(entryFile, content, ts4.ScriptTarget.Latest, true, ts4.ScriptKind.TS);
+    const originalGetSourceFile = compilerHost.getSourceFile.bind(compilerHost);
+    compilerHost.getSourceFile = (fileName, languageVersion, onError, shouldCreateNewSourceFile) => {
+      if (fileName === entryFile) {
+        return inMemorySource;
       }
-      values.add(value);
-    }
-    if (isDiscriminator) {
-      return propName;
-    }
+      return originalGetSourceFile(fileName, languageVersion, onError, shouldCreateNewSourceFile);
+    };
   }
-  return;
+  const program = ts4.createProgram([entryFile], compilerOptions, compilerHost);
+  const sourceFile = inMemorySource ?? program.getSourceFile(entryFile);
+  return {
+    program,
+    compilerHost,
+    compilerOptions,
+    sourceFile,
+    configPath
+  };
 }
 
 // src/types/parameters.ts
@@ -890,8 +912,8 @@ function registerReferencedTypes(type, ctx, depth = 0) {
   if (!isPrimitive) {
     ctx.visitedTypes.add(type);
   }
-  const { typeChecker: checker, typeRegistry, exportedIds } = ctx;
-  typeRegistry.registerType(type, checker, exportedIds);
+  const { typeChecker: checker, typeRegistry } = ctx;
+  typeRegistry.registerType(type, ctx);
   const typeArgs = type.typeArguments;
   if (typeArgs) {
     for (const arg of typeArgs) {
@@ -1587,14 +1609,26 @@ async function extract(options) {
   }
   const meta = await getPackageMeta(entryFile, baseDir);
   const types = ctx.typeRegistry.getAll();
-  const danglingRefs = collectDanglingRefs(exports, types);
-  for (const ref of danglingRefs) {
-    diagnostics.push({
-      message: `Type '${ref}' is referenced but not defined in types[].`,
-      severity: "warning",
-      code: "DANGLING_REF",
-      suggestion: "The type may be from an external package. Check import paths."
-    });
+  const forgottenExports = collectForgottenExports(exports, types, program, sourceFile);
+  for (const forgotten of forgottenExports) {
+    const refSummary = forgotten.referencedBy.slice(0, 3).map((r) => `${r.exportName} (${r.location})`).join(", ");
+    const moreRefs = forgotten.referencedBy.length > 3 ? ` +${forgotten.referencedBy.length - 3} more` : "";
+    if (forgotten.isExternal) {
+      diagnostics.push({
+        message: `External type '${forgotten.name}' referenced by: ${refSummary}${moreRefs}`,
+        severity: "info",
+        code: "EXTERNAL_TYPE_REF",
+        suggestion: forgotten.definedIn ? `Type is from: ${forgotten.definedIn}` : "Type is from an external package"
+      });
+    } else {
+      diagnostics.push({
+        message: `Forgotten export: '${forgotten.name}' referenced by: ${refSummary}${moreRefs}`,
+        severity: "warning",
+        code: "FORGOTTEN_EXPORT",
+        suggestion: forgotten.fix ?? `Export this type from your public API`,
+        location: forgotten.definedIn ? { file: forgotten.definedIn } : undefined
+      });
+    }
   }
   const externalTypes = types.filter((t) => t.kind === "external");
   if (externalTypes.length > 0) {
@@ -1615,33 +1649,134 @@ async function extract(options) {
       timestamp: new Date().toISOString()
     }
   };
-  return { spec, diagnostics };
+  const internalForgotten = forgottenExports.filter((f) => !f.isExternal);
+  return {
+    spec,
+    diagnostics,
+    ...internalForgotten.length > 0 ? { forgottenExports: internalForgotten } : {}
+  };
 }
-function collectAllRefs(obj, refs) {
+function collectAllRefsWithContext(obj, refs, state) {
   if (obj === null || obj === undefined)
     return;
   if (Array.isArray(obj)) {
-    for (const item of obj) {
-      collectAllRefs(item, refs);
+    for (let i = 0;i < obj.length; i++) {
+      collectAllRefsWithContext(obj[i], refs, {
+        ...state,
+        path: [...state.path, `[${i}]`]
+      });
     }
     return;
   }
   if (typeof obj === "object") {
     const record = obj;
     if (typeof record.$ref === "string" && record.$ref.startsWith("#/types/")) {
-      refs.add(record.$ref.slice("#/types/".length));
+      const typeName = record.$ref.slice("#/types/".length);
+      const existing = refs.get(typeName) ?? [];
+      existing.push({
+        typeName,
+        exportName: state.exportName,
+        location: state.location,
+        path: state.path.join(".") || undefined
+      });
+      refs.set(typeName, existing);
+    }
+    for (const [key, value] of Object.entries(record)) {
+      let newLocation = state.location;
+      if (key === "returnType" || key === "returns")
+        newLocation = "return";
+      else if (key === "parameters" || key === "params")
+        newLocation = "parameter";
+      else if (key === "properties" || key === "members")
+        newLocation = "property";
+      else if (key === "extends" || key === "implements")
+        newLocation = "extends";
+      else if (key === "typeParameters" || key === "typeParams")
+        newLocation = "type-parameter";
+      collectAllRefsWithContext(value, refs, {
+        ...state,
+        location: newLocation,
+        path: [...state.path, key]
+      });
+    }
+  }
+}
+function findTypeDefinition(typeName, program, sourceFile) {
+  const checker = program.getTypeChecker();
+  const findInNode = (node) => {
+    if ((ts8.isInterfaceDeclaration(node) || ts8.isTypeAliasDeclaration(node) || ts8.isClassDeclaration(node) || ts8.isEnumDeclaration(node)) && node.name?.text === typeName) {
+      const sf = node.getSourceFile();
+      return sf.fileName;
     }
-    for (const value of Object.values(record)) {
-      collectAllRefs(value, refs);
+    return ts8.forEachChild(node, findInNode);
+  };
+  const entryResult = findInNode(sourceFile);
+  if (entryResult)
+    return entryResult;
+  for (const sf of program.getSourceFiles()) {
+    if (sf.isDeclarationFile && !sf.fileName.includes("node_modules")) {
+      const result = findInNode(sf);
+      if (result)
+        return result;
     }
   }
+  const symbol = checker.resolveName(typeName, sourceFile, ts8.SymbolFlags.Type, false);
+  if (symbol?.declarations?.[0]) {
+    return symbol.declarations[0].getSourceFile().fileName;
+  }
+  return;
 }
-function collectDanglingRefs(exports, types) {
+function isExternalType2(definedIn) {
+  if (!definedIn)
+    return true;
+  return definedIn.includes("node_modules");
+}
+function hasInternalTag(typeName, program, sourceFile) {
+  const checker = program.getTypeChecker();
+  const symbol = checker.resolveName(typeName, sourceFile, ts8.SymbolFlags.Type, false);
+  if (!symbol)
+    return false;
+  const jsTags = symbol.getJsDocTags();
+  return jsTags.some((tag) => tag.name === "internal");
+}
+function collectForgottenExports(exports, types, program, sourceFile) {
   const definedTypes = new Set(types.map((t) => t.id));
-  const referencedTypes = new Set;
-  collectAllRefs(exports, referencedTypes);
-  collectAllRefs(types, referencedTypes);
-  return Array.from(referencedTypes).filter((ref) => !definedTypes.has(ref) && !BUILTIN_TYPES2.has(ref) && !shouldSkipDanglingRef(ref));
+  const referencedTypes = new Map;
+  for (const exp of exports) {
+    collectAllRefsWithContext(exp, referencedTypes, {
+      exportName: exp.id || exp.name,
+      location: "property",
+      path: []
+    });
+  }
+  for (const type of types) {
+    collectAllRefsWithContext(type, referencedTypes, {
+      exportName: type.id,
+      location: "property",
+      path: []
+    });
+  }
+  const forgottenExports = [];
+  for (const [typeName, references] of referencedTypes) {
+    if (definedTypes.has(typeName))
+      continue;
+    if (BUILTIN_TYPES2.has(typeName))
+      continue;
+    if (shouldSkipDanglingRef(typeName))
+      continue;
+    if (hasInternalTag(typeName, program, sourceFile))
+      continue;
+    const definedIn = findTypeDefinition(typeName, program, sourceFile);
+    const isExternal = isExternalType2(definedIn);
+    forgottenExports.push({
+      name: typeName,
+      definedIn,
+      referencedBy: references,
+      isExternal,
+      fix: isExternal ? undefined : `export { ${typeName} } from '${definedIn ?? "./types"}'`
+    });
+  }
+  return forgottenExports;
 }
 function resolveExportTarget(symbol, checker) {
   let targetSymbol = symbol;
@@ -1845,4 +1980,4 @@ async function getPackageMeta(entryFile, baseDir) {
   } catch {}
   return { name: path2.basename(searchDir) };
 }
-export { TypeRegistry, getJSDocComment, getSourceLocation, getParamDescription, extractTypeParameters, isSymbolDeprecated, createProgram, BUILTIN_TYPE_SCHEMAS, isPrimitiveName, isBuiltinGeneric, isAnonymous, buildSchema, isPureRefSchema, withDescription, schemaIsAny, schemasAreEqual, deduplicateSchemas, findDiscriminatorProperty, extractParameters, registerReferencedTypes, serializeClass, serializeEnum, serializeFunctionExport, serializeInterface, serializeTypeAlias, serializeVariable, extract };
+export { BUILTIN_TYPE_SCHEMAS, isPrimitiveName, isBuiltinGeneric, isAnonymous, buildSchema, isPureRefSchema, withDescription, schemaIsAny, schemasAreEqual, deduplicateSchemas, findDiscriminatorProperty, TypeRegistry, getJSDocComment, getSourceLocation, getParamDescription, extractTypeParameters, isSymbolDeprecated, createProgram, extractParameters, registerReferencedTypes, serializeClass, serializeEnum, serializeFunctionExport, serializeInterface, serializeTypeAlias, serializeVariable, extract };