@openpkg-ts/sdk 0.34.0 → 0.35.0

package/dist/index.js

@@ -25,7 +25,7 @@ import {
   toPagefindRecords,
   toSearchIndex,
   toSearchIndexJSON
-} from "./shared/chunk-91b592v7.js";
+} from "./shared/chunk-skapcfq1.js";
 
 // src/primitives/diff.ts
 import {
@@ -45,7 +45,10 @@ function loadConfig(cwd) {
     try {
       const content = fs.readFileSync(configPath, "utf-8");
       return JSON.parse(content);
-    } catch {}
+    } catch (err) {
+      const msg = err instanceof SyntaxError ? err.message : String(err);
+      console.warn(`Warning: Invalid JSON in ${CONFIG_FILENAME}: ${msg}`);
+    }
   }
   const pkgPath = path.join(cwd, "package.json");
   if (fs.existsSync(pkgPath)) {
@@ -55,7 +58,10 @@ function loadConfig(cwd) {
       if (pkg.openpkg) {
         return pkg.openpkg;
       }
-    } catch {}
+    } catch (err) {
+      const msg = err instanceof SyntaxError ? err.message : String(err);
+      console.warn(`Warning: Invalid JSON in package.json: ${msg}`);
+    }
   }
   return null;
 }
@@ -73,6 +79,7 @@ function mergeConfig(fileConfig, cliOptions) {
 }
 // src/core/loader.ts
 import * as fs2 from "node:fs";
+import { validateSpec } from "@openpkg-ts/spec";
 
 // src/render/html.ts
 var defaultCSS = `
@@ -1098,7 +1105,21 @@ function loadSpec(spec) {
   return createDocsInstance(spec);
 }
 function createDocs(input) {
-  const spec = typeof input === "string" ? JSON.parse(fs2.readFileSync(input, "utf-8")) : input;
+  let spec;
+  if (typeof input === "string") {
+    try {
+      spec = JSON.parse(fs2.readFileSync(input, "utf-8"));
+    } catch (err) {
+      throw new Error(`Failed to parse spec file: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  } else {
+    spec = input;
+  }
+  const validation = validateSpec(spec);
+  if (!validation.ok) {
+    const errors = validation.errors.slice(0, 5).map((e) => `${e.instancePath || "/"}: ${e.message}`).join("; ");
+    throw new Error(`Invalid OpenPkg spec: ${errors}`);
+  }
   return createDocsInstance(spec);
 }
 function createDocsInstance(spec) {
@@ -2514,9 +2535,11 @@ function buildSchemaInternal(type, checker, ctx) {
 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);
+      const params = sig.getParameters().flatMap((param) => {
         const decl = param.valueDeclaration;
+        if (!decl)
+          return [];
+        const paramType = checker.getTypeOfSymbolAtLocation(param, decl);
         const isOptional = !!decl?.questionToken || !!decl?.initializer;
         return {
           name: param.getName(),
@@ -2697,7 +2720,9 @@ function extractParameters(signature, ctx) {
   const jsdocTags = signatureDecl ? ts4.getJSDocTags(signatureDecl) : [];
   for (const param of signature.getParameters()) {
     const decl = param.valueDeclaration;
-    const type = checker.getTypeOfSymbolAtLocation(param, decl ?? param.valueDeclaration);
+    if (!decl)
+      continue;
+    const type = checker.getTypeOfSymbolAtLocation(param, decl);
     if (decl && ts4.isObjectBindingPattern(decl.name)) {
       const expandedParams = expandBindingPattern(decl, type, jsdocTags, ctx);
       result.push(...expandedParams);
@@ -2842,7 +2867,12 @@ function registerReferencedTypes(type, ctx, depth = 0) {
   }
   if (type.flags & ts4.TypeFlags.Object) {
     const props = type.getProperties();
-    for (const prop of props.slice(0, 20)) {
+    const limit = ctx.maxProperties;
+    if (props.length > limit && ctx.onTruncation) {
+      const typeName = type.getSymbol()?.getName() ?? "anonymous";
+      ctx.onTruncation(typeName, props.length, limit);
+    }
+    for (const prop of props.slice(0, limit)) {
       const propType = checker.getTypeOfSymbol(prop);
       registerReferencedTypes(propType, ctx, depth + 1);
     }
@@ -3041,7 +3071,12 @@ class TypeRegistry {
     }
     const props = {};
     const required = [];
-    for (const prop of properties.slice(0, 20)) {
+    const limit = ctx.maxProperties;
+    if (properties.length > limit && ctx.onTruncation) {
+      const typeName = type.getSymbol()?.getName() ?? "anonymous";
+      ctx.onTruncation(typeName, properties.length, limit);
+    }
+    for (const prop of properties.slice(0, limit)) {
       const propName = prop.getName();
       if (propName.startsWith("_"))
         continue;
@@ -3075,7 +3110,9 @@ function createContext(program, sourceFile, options = {}) {
     typeRegistry: new TypeRegistry,
     exportedIds: new Set,
     visitedTypes: new Set,
-    includePrivate: options.includePrivate ?? false
+    includePrivate: options.includePrivate ?? false,
+    maxProperties: options.maxProperties ?? 20,
+    onTruncation: options.onTruncation
   };
 }
 function getInheritedMembers(classType, ownMemberNames, ctx, isStatic = false) {
@@ -3083,7 +3120,12 @@ function getInheritedMembers(classType, ownMemberNames, ctx, isStatic = false) {
   const inherited = [];
   const visited = new Set;
   const inheritedNames = new Set;
-  const typeToWalk = isStatic ? classType.getSymbol()?.valueDeclaration && checker.getTypeOfSymbolAtLocation(classType.getSymbol(), classType.getSymbol().valueDeclaration) : classType;
+  let typeToWalk = classType;
+  if (isStatic) {
+    const symbol = classType.getSymbol();
+    const valueDecl = symbol?.valueDeclaration;
+    typeToWalk = symbol && valueDecl ? checker.getTypeOfSymbolAtLocation(symbol, valueDecl) : undefined;
+  }
   if (!typeToWalk)
     return inherited;
   walkBaseTypes(typeToWalk, ownMemberNames, inherited, inheritedNames, visited, ctx, isStatic);
@@ -3234,6 +3276,8 @@ function serializeClass(node, ctx) {
           methodsByName.set(methodMember.name, methodMember);
         } else {
           const existing = methodsByName.get(methodMember.name);
+          if (!existing)
+            continue;
           if (!existing.description && methodMember.description) {
             existing.description = methodMember.description;
           }
@@ -4707,9 +4751,9 @@ function getDescriptionPreview(symbol, checker) {
 }
 // src/builder/spec-builder.ts
 import * as fs7 from "node:fs";
-import * as path7 from "node:path";
+import * as path8 from "node:path";
 import { SCHEMA_URL, SCHEMA_VERSION } from "@openpkg-ts/spec";
-import ts15 from "typescript";
+import ts16 from "typescript";
 
 // src/ast/resolve.ts
 import ts13 from "typescript";
@@ -4746,6 +4790,7 @@ import { spawn, spawnSync } from "node:child_process";
 import * as fs5 from "node:fs";
 import * as os from "node:os";
 import * as path5 from "node:path";
+var MAX_BUFFER_SIZE = 10 * 1024 * 1024;
 function isStandardJSONSchema(obj) {
   if (typeof obj !== "object" || obj === null)
     return false;
@@ -4845,6 +4890,7 @@ async function extract() {
     const absPath = path.resolve(modulePath);
     const mod = await import(pathToFileURL(absPath).href);
     const results = [];
+    const warnings = [];
 
     // Build exports map - handle both ESM and CJS (where exports are in mod.default)
     const exports = {};
@@ -4877,7 +4923,7 @@ async function extract() {
             inputSchema
           });
         } catch (e) {
-          // Skip schemas that fail to extract
+          warnings.push({ code: 'SCHEMA_FAILED', message: String(e), exportName: name });
         }
         continue;
       }
@@ -4891,15 +4937,15 @@ async function extract() {
             outputSchema: sanitizeTypeBoxSchema(value)
           });
         } catch (e) {
-          // Skip schemas that fail to extract
+          warnings.push({ code: 'TYPEBOX_FAILED', message: String(e), exportName: name });
         }
         continue;
       }
     }
 
-    console.log(JSON.stringify({ success: true, results }));
+    console.log(JSON.stringify({ success: true, results, warnings }));
   } catch (e) {
-    console.log(JSON.stringify({ success: false, error: e.message }));
+    console.log(JSON.stringify({ success: false, error: e.message, warnings: [] }));
   }
 }
 
@@ -4931,6 +4977,7 @@ async function extract() {
     const absPath = path.resolve(modulePath);
     const mod = await import(pathToFileURL(absPath).href);
     const results: Array<{exportName: string; vendor: string; outputSchema: unknown; inputSchema?: unknown}> = [];
+    const warnings: Array<{code: string; message: string; exportName?: string}> = [];
 
     // Build exports map
     const exports: Record<string, unknown> = {};
@@ -4959,7 +5006,9 @@ async function extract() {
             const outputSchema = (jsonSchema.output as Function)(options);
             const inputSchema = typeof jsonSchema.input === 'function' ? (jsonSchema.input as Function)(options) : undefined;
             results.push({ exportName: name, vendor: std.vendor as string, outputSchema, inputSchema });
-          } catch {}
+          } catch (e) {
+            warnings.push({ code: 'SCHEMA_FAILED', message: String(e), exportName: name });
+          }
           continue;
         }
       }
@@ -4968,13 +5017,15 @@ async function extract() {
       if (isTypeBoxSchema(value)) {
         try {
           results.push({ exportName: name, vendor: 'typebox', outputSchema: sanitizeTypeBoxSchema(value) });
-        } catch {}
+        } catch (e) {
+          warnings.push({ code: 'TYPEBOX_FAILED', message: String(e), exportName: name });
+        }
       }
     }
 
-    console.log(JSON.stringify({ success: true, results }));
+    console.log(JSON.stringify({ success: true, results, warnings }));
   } catch (e) {
-    console.log(JSON.stringify({ success: false, error: (e as Error).message }));
+    console.log(JSON.stringify({ success: false, error: (e as Error).message, warnings: [] }));
   }
 }
 
@@ -4984,7 +5035,8 @@ async function extractStandardSchemasFromTs(tsFilePath, options = {}) {
   const { timeout = 1e4, target = "draft-2020-12", libraryOptions } = options;
   const result = {
     schemas: new Map,
-    errors: []
+    errors: [],
+    warnings: []
   };
   const runtime = detectTsRuntime();
   if (!runtime) {
@@ -5009,16 +5061,32 @@ async function extractStandardSchemasFromTs(tsFilePath, options = {}) {
       });
       let stdout = "";
       let stderr = "";
+      let stdoutTruncated = false;
+      let stderrTruncated = false;
       child.stdout.on("data", (data) => {
-        stdout += data.toString();
+        if (stdout.length < MAX_BUFFER_SIZE) {
+          const chunk = data.toString();
+          stdout += chunk.slice(0, MAX_BUFFER_SIZE - stdout.length);
+          if (stdout.length >= MAX_BUFFER_SIZE)
+            stdoutTruncated = true;
+        }
       });
       child.stderr.on("data", (data) => {
-        stderr += data.toString();
+        if (stderr.length < MAX_BUFFER_SIZE) {
+          const chunk = data.toString();
+          stderr += chunk.slice(0, MAX_BUFFER_SIZE - stderr.length);
+          if (stderr.length >= MAX_BUFFER_SIZE)
+            stderrTruncated = true;
+        }
       });
       child.on("close", (code) => {
         try {
           fs5.unlinkSync(workerPath);
-        } catch {}
+        } catch (cleanupErr) {
+          if (cleanupErr?.code !== "ENOENT") {
+            result.warnings.push({ code: "CLEANUP_FAILED", message: String(cleanupErr) });
+          }
+        }
         if (code !== 0) {
           result.errors.push(`Extraction failed (${runtime.name}): ${stderr || `exit code ${code}`}`);
           resolve2(result);
@@ -5039,15 +5107,34 @@ async function extractStandardSchemasFromTs(tsFilePath, options = {}) {
               inputSchema: item.inputSchema
             });
           }
+          if (Array.isArray(parsed.warnings)) {
+            for (const w of parsed.warnings) {
+              result.warnings.push({
+                code: w.code,
+                message: w.message,
+                exportName: w.exportName
+              });
+            }
+          }
         } catch (e) {
           result.errors.push(`Failed to parse extraction output: ${e}`);
         }
+        if (stdoutTruncated) {
+          result.warnings.push({ code: "OUTPUT_TRUNCATED", message: "stdout exceeded 10MB buffer limit" });
+        }
+        if (stderrTruncated) {
+          result.warnings.push({ code: "OUTPUT_TRUNCATED", message: "stderr exceeded 10MB buffer limit" });
+        }
         resolve2(result);
       });
       child.on("error", (err) => {
         try {
           fs5.unlinkSync(workerPath);
-        } catch {}
+        } catch (cleanupErr) {
+          if (cleanupErr?.code !== "ENOENT") {
+            result.warnings.push({ code: "CLEANUP_FAILED", message: String(cleanupErr) });
+          }
+        }
         result.errors.push(`Subprocess error: ${err.message}`);
         resolve2(result);
       });
@@ -5055,7 +5142,11 @@ async function extractStandardSchemasFromTs(tsFilePath, options = {}) {
   } catch (e) {
     try {
       fs5.unlinkSync(workerPath);
-    } catch {}
+    } catch (cleanupErr) {
+      if (cleanupErr?.code !== "ENOENT") {
+        result.warnings.push({ code: "CLEANUP_FAILED", message: String(cleanupErr) });
+      }
+    }
     result.errors.push(`Failed to create worker script: ${e}`);
     return result;
   }
@@ -5072,7 +5163,7 @@ function readTsconfigOutDir(baseDir) {
     if (tsconfig.compilerOptions?.outDir) {
       return tsconfig.compilerOptions.outDir.replace(/^\.\//, "");
     }
-  } catch {}
+  } catch (_e) {}
   return null;
 }
 function resolveCompiledPath(tsPath, baseDir) {
@@ -5116,7 +5207,8 @@ async function extractStandardSchemas(compiledJsPath, options = {}) {
   const { timeout = 1e4, target = "draft-2020-12", libraryOptions } = options;
   const result = {
     schemas: new Map,
-    errors: []
+    errors: [],
+    warnings: []
   };
   if (!fs5.existsSync(compiledJsPath)) {
     result.errors.push(`Compiled JS not found: ${compiledJsPath}`);
@@ -5130,11 +5222,23 @@ async function extractStandardSchemas(compiledJsPath, options = {}) {
     });
     let stdout = "";
     let stderr = "";
+    let stdoutTruncated = false;
+    let stderrTruncated = false;
     child.stdout.on("data", (data) => {
-      stdout += data.toString();
+      if (stdout.length < MAX_BUFFER_SIZE) {
+        const chunk = data.toString();
+        stdout += chunk.slice(0, MAX_BUFFER_SIZE - stdout.length);
+        if (stdout.length >= MAX_BUFFER_SIZE)
+          stdoutTruncated = true;
+      }
     });
     child.stderr.on("data", (data) => {
-      stderr += data.toString();
+      if (stderr.length < MAX_BUFFER_SIZE) {
+        const chunk = data.toString();
+        stderr += chunk.slice(0, MAX_BUFFER_SIZE - stderr.length);
+        if (stderr.length >= MAX_BUFFER_SIZE)
+          stderrTruncated = true;
+      }
     });
     child.on("close", (code) => {
       if (code !== 0) {
@@ -5157,9 +5261,24 @@ async function extractStandardSchemas(compiledJsPath, options = {}) {
             inputSchema: item.inputSchema
           });
         }
+        if (Array.isArray(parsed.warnings)) {
+          for (const w of parsed.warnings) {
+            result.warnings.push({
+              code: w.code,
+              message: w.message,
+              exportName: w.exportName
+            });
+          }
+        }
       } catch (e) {
         result.errors.push(`Failed to parse extraction output: ${e}`);
       }
+      if (stdoutTruncated) {
+        result.warnings.push({ code: "OUTPUT_TRUNCATED", message: "stdout exceeded 10MB buffer limit" });
+      }
+      if (stderrTruncated) {
+        result.warnings.push({ code: "OUTPUT_TRUNCATED", message: "stderr exceeded 10MB buffer limit" });
+      }
       resolve2(result);
     });
     child.on("error", (err) => {
@@ -5195,7 +5314,8 @@ async function extractStandardSchemasFromProject(entryFile, baseDir, options = {
   const hint = isTypeScript && !runtime ? " Install bun, tsx, or ts-node for direct TS execution." : "";
   return {
     schemas: new Map,
-    errors: [`Could not find compiled JS for ${entryFile}.${hint}`]
+    errors: [`Could not find compiled JS for ${entryFile}.${hint}`],
+    warnings: []
   };
 }
 
@@ -5394,72 +5514,149 @@ function mergeRuntimeSchemas(staticExports, runtimeSchemas) {
   return { merged, exports };
 }
 
-// src/builder/spec-builder.ts
-var typeDefinitionCache = null;
-function getTypeDefinitionCache() {
-  if (!typeDefinitionCache) {
-    typeDefinitionCache = new Map;
+// src/builder/type-cache.ts
+import ts15 from "typescript";
+
+// src/utils/cache-manager.ts
+class CacheManager {
+  cache;
+  maxSize;
+  ttl;
+  constructor(options = {}) {
+    this.maxSize = options.maxSize ?? 1000;
+    this.ttl = options.ttl;
+    this.cache = new Map;
+  }
+  get(key) {
+    const entry = this.cache.get(key);
+    if (!entry)
+      return;
+    if (entry.expiresAt && Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      return;
+    }
+    this.cache.delete(key);
+    this.cache.set(key, entry);
+    return entry.value;
   }
-  return typeDefinitionCache;
-}
-var internalTagCache = null;
-function getInternalTagCache() {
-  if (!internalTagCache) {
-    internalTagCache = new Map;
+  has(key) {
+    const entry = this.cache.get(key);
+    if (!entry)
+      return false;
+    if (entry.expiresAt && Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      return false;
+    }
+    return true;
+  }
+  set(key, value) {
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    }
+    if (this.cache.size >= this.maxSize) {
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey !== undefined) {
+        this.cache.delete(firstKey);
+      }
+    }
+    const entry = {
+      value,
+      ...this.ttl ? { expiresAt: Date.now() + this.ttl } : {}
+    };
+    this.cache.set(key, entry);
+  }
+  delete(key) {
+    return this.cache.delete(key);
+  }
+  clear() {
+    this.cache.clear();
+  }
+  get size() {
+    return this.cache.size;
+  }
+  keys() {
+    return this.cache.keys();
+  }
+  values() {
+    const result = [];
+    const now = Date.now();
+    for (const [key, entry] of this.cache) {
+      if (entry.expiresAt && now > entry.expiresAt) {
+        this.cache.delete(key);
+        continue;
+      }
+      result.push(entry.value);
+    }
+    return result;
   }
-  return internalTagCache;
 }
+
+// src/builder/type-cache.ts
+var typeDefinitionCache = new CacheManager({ maxSize: 1000 });
+var internalTagCache = new CacheManager({ maxSize: 1000 });
+var regexCache = new CacheManager({ maxSize: 100 });
 function clearTypeDefinitionCache() {
-  typeDefinitionCache = null;
-  internalTagCache = null;
+  typeDefinitionCache.clear();
+  internalTagCache.clear();
+  regexCache.clear();
 }
-var YIELD_BATCH_SIZE = 5;
-function computeDegradedStats(exports) {
-  let exportsWithoutDescription = 0;
-  let paramsWithoutDocs = 0;
-  let missingExamples = 0;
-  for (const exp of exports) {
-    if (!exp.description)
-      exportsWithoutDescription++;
-    if (!exp.examples || exp.examples.length === 0)
-      missingExamples++;
-    const signatures = exp.signatures;
-    if (signatures) {
-      for (const sig of signatures) {
-        for (const param of sig.parameters ?? []) {
-          if (!param.description)
-            paramsWithoutDocs++;
-        }
+function getRegexCache() {
+  return regexCache;
+}
+function findTypeDefinition(typeName, program, sourceFile) {
+  if (typeDefinitionCache.has(typeName)) {
+    return typeDefinitionCache.get(typeName);
+  }
+  const checker = program.getTypeChecker();
+  const findInNode = (node) => {
+    if ((ts15.isInterfaceDeclaration(node) || ts15.isTypeAliasDeclaration(node) || ts15.isClassDeclaration(node) || ts15.isEnumDeclaration(node)) && node.name?.text === typeName) {
+      const sf = node.getSourceFile();
+      return sf.fileName;
+    }
+    return ts15.forEachChild(node, findInNode);
+  };
+  const entryResult = findInNode(sourceFile);
+  if (entryResult) {
+    typeDefinitionCache.set(typeName, entryResult);
+    return entryResult;
+  }
+  for (const sf of program.getSourceFiles()) {
+    if (sf.isDeclarationFile && !sf.fileName.includes("node_modules")) {
+      const result = findInNode(sf);
+      if (result) {
+        typeDefinitionCache.set(typeName, result);
+        return result;
       }
     }
   }
-  return { exportsWithoutDescription, paramsWithoutDocs, missingExamples };
+  const symbol = checker.resolveName(typeName, sourceFile, ts15.SymbolFlags.Type, false);
+  if (symbol?.declarations?.[0]) {
+    const result = symbol.declarations[0].getSourceFile().fileName;
+    typeDefinitionCache.set(typeName, result);
+    return result;
+  }
+  typeDefinitionCache.set(typeName, undefined);
+  return;
 }
-function buildVerificationSummary(discoveredCount, extractedCount, tracker) {
-  const skippedDetails = [];
-  const failedDetails = [];
-  for (const entry of tracker.values()) {
-    if (entry.status === "skipped" && entry.skipReason) {
-      skippedDetails.push({ name: entry.name, reason: entry.skipReason });
-    } else if (entry.status === "failed" && entry.error) {
-      failedDetails.push({ name: entry.name, error: entry.error });
-    }
+function hasInternalTag(typeName, program, sourceFile) {
+  const cached = internalTagCache.get(typeName);
+  if (cached !== undefined) {
+    return cached;
   }
-  const skipped = skippedDetails.length;
-  const failed = failedDetails.length;
-  const delta = discoveredCount - extractedCount - skipped;
-  return {
-    discovered: discoveredCount,
-    extracted: extractedCount,
-    skipped,
-    failed,
-    delta,
-    details: {
-      skipped: skippedDetails,
-      failed: failedDetails
-    }
-  };
+  const checker = program.getTypeChecker();
+  const symbol = checker.resolveName(typeName, sourceFile, ts15.SymbolFlags.Type, false);
+  if (!symbol) {
+    internalTagCache.set(typeName, false);
+    return false;
+  }
+  const jsTags = symbol.getJsDocTags();
+  const isInternal = jsTags.some((tag) => tag.name === "internal");
+  internalTagCache.set(typeName, isInternal);
+  return isInternal;
 }
+
+// src/builder/verification.ts
+import * as path7 from "node:path";
 var BUILTIN_TYPES2 = new Set([
   "Array",
   "ArrayBuffer",
@@ -5518,19 +5715,39 @@ var BUILTIN_TYPES2 = new Set([
   "InstanceType",
   "ThisType"
 ]);
-function matchesPattern(name, pattern) {
-  if (!pattern.includes("*"))
-    return name === pattern;
-  const regex = new RegExp(`^${pattern.replace(/\*/g, ".*")}$`);
-  return regex.test(name);
-}
-function shouldIncludeExport(name, only, ignore) {
-  if (ignore?.some((p) => matchesPattern(name, p)))
-    return false;
-  if (only && only.length > 0) {
-    return only.some((p) => matchesPattern(name, p));
+function buildVerificationSummary(discoveredCount, extractedCount, tracker) {
+  const skippedDetails = [];
+  const failedDetails = [];
+  for (const entry of tracker.values()) {
+    if (entry.status === "skipped" && entry.skipReason) {
+      skippedDetails.push({ name: entry.name, reason: entry.skipReason });
+    } else if (entry.status === "failed" && entry.error) {
+      failedDetails.push({ name: entry.name, error: entry.error });
+    }
   }
-  return true;
+  const skipped = skippedDetails.length;
+  const failed = failedDetails.length;
+  const delta = discoveredCount - extractedCount - skipped;
+  return {
+    discovered: discoveredCount,
+    extracted: extractedCount,
+    skipped,
+    failed,
+    delta,
+    details: {
+      skipped: skippedDetails,
+      failed: failedDetails
+    }
+  };
+}
+function isExternalType2(definedIn, baseDir) {
+  if (!definedIn)
+    return true;
+  if (definedIn.includes("node_modules"))
+    return true;
+  const normalizedDefined = path7.resolve(definedIn);
+  const normalizedBase = path7.resolve(baseDir);
+  return !normalizedDefined.startsWith(normalizedBase);
 }
 function shouldSkipDanglingRef(name) {
   if (name.startsWith("__"))
@@ -5543,255 +5760,6 @@ function shouldSkipDanglingRef(name) {
     return true;
   return false;
 }
-async function extract(options) {
-  clearTypeDefinitionCache();
-  const {
-    entryFile,
-    baseDir,
-    content,
-    maxTypeDepth,
-    maxExternalTypeDepth,
-    resolveExternalTypes,
-    includeSchema,
-    only,
-    ignore,
-    onProgress,
-    isDtsSource,
-    includePrivate
-  } = options;
-  const diagnostics = [];
-  let exports = [];
-  const result = createProgram({ entryFile, baseDir, content });
-  const { program, sourceFile } = result;
-  if (!sourceFile) {
-    return {
-      spec: createEmptySpec(entryFile, includeSchema, isDtsSource),
-      diagnostics: [{ message: `Could not load source file: ${entryFile}`, severity: "error" }]
-    };
-  }
-  const typeChecker = program.getTypeChecker();
-  const moduleSymbol = typeChecker.getSymbolAtLocation(sourceFile);
-  if (!moduleSymbol) {
-    return {
-      spec: createEmptySpec(entryFile, includeSchema, isDtsSource),
-      diagnostics: [{ message: "Could not get module symbol", severity: "warning" }]
-    };
-  }
-  const exportedSymbols = typeChecker.getExportsOfModule(moduleSymbol);
-  const exportedIds = new Set;
-  for (const symbol of exportedSymbols) {
-    exportedIds.add(symbol.getName());
-  }
-  const exportTracker = new Map;
-  for (const symbol of exportedSymbols) {
-    const name = symbol.getName();
-    const included = shouldIncludeExport(name, only, ignore);
-    exportTracker.set(name, {
-      name,
-      discovered: true,
-      status: included ? "pending" : "skipped",
-      ...included ? {} : { skipReason: "filtered" }
-    });
-  }
-  const ctx = createContext(program, sourceFile, {
-    maxTypeDepth,
-    maxExternalTypeDepth,
-    resolveExternalTypes,
-    includePrivate
-  });
-  ctx.exportedIds = exportedIds;
-  const filteredSymbols = exportedSymbols.filter((s) => shouldIncludeExport(s.getName(), only, ignore));
-  const total = filteredSymbols.length;
-  for (let i = 0;i < filteredSymbols.length; i++) {
-    const symbol = filteredSymbols[i];
-    const exportName = symbol.getName();
-    const tracker = exportTracker.get(exportName);
-    onProgress?.(i + 1, total, exportName);
-    if (i > 0 && i % YIELD_BATCH_SIZE === 0) {
-      await new Promise((r) => setImmediate(r));
-    }
-    try {
-      const { declaration, targetSymbol, isTypeOnly } = resolveExportTarget2(symbol, typeChecker);
-      if (!declaration) {
-        let externalPackage;
-        const allDecls = [
-          ...targetSymbol.declarations ?? [],
-          ...symbol.declarations ?? []
-        ];
-        for (const decl of allDecls) {
-          const sf = decl.getSourceFile();
-          if (sf?.fileName.includes("node_modules")) {
-            const match = sf.fileName.match(/node_modules\/(@[^/]+\/[^/]+|[^/]+)/);
-            if (match) {
-              externalPackage = match[1];
-              break;
-            }
-          }
-          if (ts15.isExportSpecifier(decl)) {
-            const exportDecl = decl.parent?.parent;
-            if (exportDecl && ts15.isExportDeclaration(exportDecl) && exportDecl.moduleSpecifier) {
-              const moduleText = exportDecl.moduleSpecifier.getText().slice(1, -1);
-              if (!moduleText.startsWith(".") && !moduleText.startsWith("/")) {
-                externalPackage = moduleText;
-                break;
-              }
-            }
-          }
-        }
-        if (externalPackage) {
-          const shouldResolve = matchesExternalPattern(externalPackage, options.externals?.include, options.externals?.exclude);
-          if (shouldResolve) {
-            const resolvedModule = resolveExternalModule(externalPackage, sourceFile.fileName, program.getCompilerOptions());
-            if (resolvedModule) {
-              const visitedExternals = new Set;
-              const extractedExport = extractExternalExport(exportName, resolvedModule, program, ctx, visitedExternals);
-              if (extractedExport) {
-                exports.push(extractedExport);
-                tracker.status = "success";
-                tracker.kind = extractedExport.kind;
-                continue;
-              }
-            }
-          }
-          const externalExport = {
-            id: exportName,
-            name: exportName,
-            kind: "external",
-            source: {
-              package: externalPackage
-            }
-          };
-          exports.push(externalExport);
-          tracker.status = "success";
-          tracker.kind = "external";
-        } else {
-          tracker.status = "skipped";
-          tracker.skipReason = "no-declaration";
-        }
-        continue;
-      }
-      const exp = serializeDeclaration2(declaration, symbol, targetSymbol, exportName, ctx, isTypeOnly);
-      if (exp) {
-        exports.push(exp);
-        tracker.status = "success";
-        tracker.kind = exp.kind;
-      } else {
-        tracker.status = "skipped";
-        tracker.skipReason = "internal";
-      }
-    } catch (err) {
-      const errorMsg = err instanceof Error ? err.message : String(err);
-      tracker.status = "failed";
-      tracker.error = errorMsg;
-      diagnostics.push({
-        message: `Failed to serialize '${exportName}': ${errorMsg}`,
-        severity: "warning",
-        code: "SERIALIZATION_FAILED"
-      });
-    }
-  }
-  const verification = buildVerificationSummary(exportedSymbols.length, exports.length, exportTracker);
-  const meta = await getPackageMeta(entryFile, baseDir);
-  const types = ctx.typeRegistry.getAll();
-  const projectBaseDir = baseDir ?? path7.dirname(entryFile);
-  const definedTypes = new Set(types.map((t) => t.id));
-  const forgottenExports = collectForgottenExports(exports, types, program, sourceFile, exportedIds, projectBaseDir, definedTypes);
-  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) {
-    diagnostics.push({
-      message: `${externalTypes.length} external type(s) from dependencies: ${externalTypes.slice(0, 5).map((t) => t.id).join(", ")}${externalTypes.length > 5 ? "..." : ""}`,
-      severity: "info",
-      code: "EXTERNAL_TYPES"
-    });
-  }
-  let runtimeMetadata;
-  if (options.schemaExtraction === "hybrid") {
-    const projectBaseDir2 = baseDir || path7.dirname(entryFile);
-    const runtimeResult = await extractStandardSchemasFromProject(entryFile, projectBaseDir2, {
-      target: options.schemaTarget || "draft-2020-12",
-      timeout: 15000
-    });
-    if (runtimeResult.schemas.size > 0) {
-      const mergeResult = mergeRuntimeSchemas(exports, runtimeResult.schemas);
-      exports = mergeResult.exports;
-      const method = runtimeResult.info?.method === "direct-ts" ? `direct-ts (${runtimeResult.info.runtime})` : "compiled";
-      runtimeMetadata = {
-        extracted: runtimeResult.schemas.size,
-        merged: mergeResult.merged,
-        vendors: [...new Set([...runtimeResult.schemas.values()].map((s) => s.vendor))],
-        errors: runtimeResult.errors,
-        method
-      };
-    }
-    for (const error of runtimeResult.errors) {
-      diagnostics.push({
-        message: `Runtime schema extraction: ${error}`,
-        severity: "warning",
-        code: "RUNTIME_SCHEMA_ERROR"
-      });
-    }
-  }
-  const normalizedExports = exports.map((exp) => normalizeExport(exp, { dialect: "draft-2020-12" }));
-  const normalizedTypes = types.map((t) => normalizeType(t, { dialect: "draft-2020-12" }));
-  const spec = {
-    ...includeSchema ? { $schema: SCHEMA_URL } : {},
-    openpkg: SCHEMA_VERSION,
-    meta,
-    exports: normalizedExports,
-    types: normalizedTypes,
-    generation: {
-      generator: "@openpkg-ts/sdk",
-      timestamp: new Date().toISOString(),
-      mode: isDtsSource ? "declaration-only" : "source",
-      ...options.schemaExtraction === "hybrid" ? { schemaExtraction: "hybrid" } : {},
-      ...isDtsSource && {
-        limitations: ["No JSDoc descriptions", "No @example tags", "No @param descriptions"]
-      },
-      ...verification.details.skipped.length > 0 && {
-        skipped: verification.details.skipped
-      }
-    }
-  };
-  const internalForgotten = forgottenExports.filter((f) => !f.isExternal);
-  const degradedMode = isDtsSource ? { reason: "dts-source", stats: computeDegradedStats(normalizedExports) } : undefined;
-  if (verification.failed > 0) {
-    const failedNames = verification.details.failed.map((f) => f.name).join(", ");
-    diagnostics.push({
-      message: `Export verification: ${verification.failed} export(s) failed: ${failedNames}`,
-      severity: "warning",
-      code: "EXPORT_VERIFICATION_FAILED",
-      suggestion: "Check serialization errors for these exports"
-    });
-  }
-  return {
-    spec,
-    diagnostics,
-    verification,
-    ...internalForgotten.length > 0 ? { forgottenExports: internalForgotten } : {},
-    ...runtimeMetadata ? { runtimeSchemas: runtimeMetadata } : {},
-    ...degradedMode ? { degradedMode } : {}
-  };
-}
 function collectAllRefsWithContext(obj, refs, state) {
   if (obj === null || obj === undefined)
     return;
@@ -5835,68 +5803,6 @@ function collectAllRefsWithContext(obj, refs, state) {
     }
   }
 }
-function findTypeDefinition(typeName, program, sourceFile) {
-  const cache = getTypeDefinitionCache();
-  if (cache.has(typeName)) {
-    return cache.get(typeName);
-  }
-  const checker = program.getTypeChecker();
-  const findInNode = (node) => {
-    if ((ts15.isInterfaceDeclaration(node) || ts15.isTypeAliasDeclaration(node) || ts15.isClassDeclaration(node) || ts15.isEnumDeclaration(node)) && node.name?.text === typeName) {
-      const sf = node.getSourceFile();
-      return sf.fileName;
-    }
-    return ts15.forEachChild(node, findInNode);
-  };
-  const entryResult = findInNode(sourceFile);
-  if (entryResult) {
-    cache.set(typeName, entryResult);
-    return entryResult;
-  }
-  for (const sf of program.getSourceFiles()) {
-    if (sf.isDeclarationFile && !sf.fileName.includes("node_modules")) {
-      const result = findInNode(sf);
-      if (result) {
-        cache.set(typeName, result);
-        return result;
-      }
-    }
-  }
-  const symbol = checker.resolveName(typeName, sourceFile, ts15.SymbolFlags.Type, false);
-  if (symbol?.declarations?.[0]) {
-    const result = symbol.declarations[0].getSourceFile().fileName;
-    cache.set(typeName, result);
-    return result;
-  }
-  cache.set(typeName, undefined);
-  return;
-}
-function isExternalType2(definedIn, baseDir) {
-  if (!definedIn)
-    return true;
-  if (definedIn.includes("node_modules"))
-    return true;
-  const normalizedDefined = path7.resolve(definedIn);
-  const normalizedBase = path7.resolve(baseDir);
-  return !normalizedDefined.startsWith(normalizedBase);
-}
-function hasInternalTag(typeName, program, sourceFile) {
-  const cache = getInternalTagCache();
-  const cached = cache.get(typeName);
-  if (cached !== undefined) {
-    return cached;
-  }
-  const checker = program.getTypeChecker();
-  const symbol = checker.resolveName(typeName, sourceFile, ts15.SymbolFlags.Type, false);
-  if (!symbol) {
-    cache.set(typeName, false);
-    return false;
-  }
-  const jsTags = symbol.getJsDocTags();
-  const isInternal = jsTags.some((tag) => tag.name === "internal");
-  cache.set(typeName, isInternal);
-  return isInternal;
-}
 function collectForgottenExports(exports, types, program, sourceFile, exportedIds, baseDir, definedTypes) {
   const referencedTypes = new Map;
   for (const exp of exports) {
@@ -5937,29 +5843,336 @@ function collectForgottenExports(exports, types, program, sourceFile, exportedId
   }
   return forgottenExports;
 }
+
+// src/builder/spec-builder.ts
+var YIELD_BATCH_SIZE = 5;
+function computeDegradedStats(exports) {
+  let exportsWithoutDescription = 0;
+  let paramsWithoutDocs = 0;
+  let missingExamples = 0;
+  for (const exp of exports) {
+    if (!exp.description)
+      exportsWithoutDescription++;
+    if (!exp.examples || exp.examples.length === 0)
+      missingExamples++;
+    const signatures = exp.signatures;
+    if (signatures) {
+      for (const sig of signatures) {
+        for (const param of sig.parameters ?? []) {
+          if (!param.description)
+            paramsWithoutDocs++;
+        }
+      }
+    }
+  }
+  return { exportsWithoutDescription, paramsWithoutDocs, missingExamples };
+}
+function matchesPattern(name, pattern) {
+  if (!pattern.includes("*"))
+    return name === pattern;
+  const regexCache2 = getRegexCache();
+  let regex = regexCache2.get(pattern);
+  if (!regex) {
+    regex = new RegExp(`^${pattern.replace(/\*/g, ".*")}$`);
+    regexCache2.set(pattern, regex);
+  }
+  return regex.test(name);
+}
+function shouldIncludeExport(name, only, ignore) {
+  if (ignore?.some((p) => matchesPattern(name, p)))
+    return false;
+  if (only && only.length > 0) {
+    return only.some((p) => matchesPattern(name, p));
+  }
+  return true;
+}
+async function extract(options) {
+  clearTypeDefinitionCache();
+  try {
+    const {
+      entryFile,
+      baseDir,
+      content,
+      maxTypeDepth,
+      maxExternalTypeDepth,
+      resolveExternalTypes,
+      includeSchema,
+      only,
+      ignore,
+      onProgress,
+      isDtsSource,
+      includePrivate,
+      maxProperties,
+      onTruncation
+    } = options;
+    const diagnostics = [];
+    let exports = [];
+    const result = createProgram({ entryFile, baseDir, content });
+    const { program, sourceFile } = result;
+    if (!sourceFile) {
+      return {
+        spec: createEmptySpec(entryFile, includeSchema, isDtsSource),
+        diagnostics: [{ message: `Could not load source file: ${entryFile}`, severity: "error" }]
+      };
+    }
+    const typeChecker = program.getTypeChecker();
+    const moduleSymbol = typeChecker.getSymbolAtLocation(sourceFile);
+    if (!moduleSymbol) {
+      return {
+        spec: createEmptySpec(entryFile, includeSchema, isDtsSource),
+        diagnostics: [{ message: "Could not get module symbol", severity: "warning" }]
+      };
+    }
+    const exportedSymbols = typeChecker.getExportsOfModule(moduleSymbol);
+    const exportedIds = new Set;
+    for (const symbol of exportedSymbols) {
+      exportedIds.add(symbol.getName());
+    }
+    const exportTracker = new Map;
+    for (const symbol of exportedSymbols) {
+      const name = symbol.getName();
+      const included = shouldIncludeExport(name, only, ignore);
+      exportTracker.set(name, {
+        name,
+        discovered: true,
+        status: included ? "pending" : "skipped",
+        ...included ? {} : { skipReason: "filtered" }
+      });
+    }
+    const ctx = createContext(program, sourceFile, {
+      maxTypeDepth,
+      maxExternalTypeDepth,
+      resolveExternalTypes,
+      includePrivate,
+      maxProperties,
+      onTruncation
+    });
+    ctx.exportedIds = exportedIds;
+    const filteredSymbols = exportedSymbols.filter((s) => shouldIncludeExport(s.getName(), only, ignore));
+    const total = filteredSymbols.length;
+    for (let i = 0;i < filteredSymbols.length; i++) {
+      const symbol = filteredSymbols[i];
+      const exportName = symbol.getName();
+      const tracker = exportTracker.get(exportName);
+      if (!tracker)
+        continue;
+      onProgress?.(i + 1, total, exportName);
+      if (i > 0 && i % YIELD_BATCH_SIZE === 0) {
+        await new Promise((r) => setImmediate(r));
+      }
+      try {
+        const { declaration, targetSymbol, isTypeOnly } = resolveExportTarget2(symbol, typeChecker);
+        if (!declaration) {
+          let externalPackage;
+          const allDecls = [...targetSymbol.declarations ?? [], ...symbol.declarations ?? []];
+          for (const decl of allDecls) {
+            const sf = decl.getSourceFile();
+            if (sf?.fileName.includes("node_modules")) {
+              const match = sf.fileName.match(/node_modules\/(@[^/]+\/[^/]+|[^/]+)/);
+              if (match) {
+                externalPackage = match[1];
+                break;
+              }
+            }
+            if (ts16.isExportSpecifier(decl)) {
+              const exportDecl = decl.parent?.parent;
+              if (exportDecl && ts16.isExportDeclaration(exportDecl) && exportDecl.moduleSpecifier) {
+                const moduleText = exportDecl.moduleSpecifier.getText().slice(1, -1);
+                if (!moduleText.startsWith(".") && !moduleText.startsWith("/")) {
+                  externalPackage = moduleText;
+                  break;
+                }
+              }
+            }
+          }
+          if (externalPackage) {
+            const shouldResolve = matchesExternalPattern(externalPackage, options.externals?.include, options.externals?.exclude);
+            if (shouldResolve) {
+              const resolvedModule = resolveExternalModule(externalPackage, sourceFile.fileName, program.getCompilerOptions());
+              if (resolvedModule) {
+                const visitedExternals = new Set;
+                const extractedExport = extractExternalExport(exportName, resolvedModule, program, ctx, visitedExternals);
+                if (extractedExport) {
+                  exports.push(extractedExport);
+                  tracker.status = "success";
+                  tracker.kind = extractedExport.kind;
+                  continue;
+                }
+              }
+            }
+            const externalExport = {
+              id: exportName,
+              name: exportName,
+              kind: "external",
+              source: {
+                package: externalPackage
+              }
+            };
+            exports.push(externalExport);
+            tracker.status = "success";
+            tracker.kind = "external";
+          } else {
+            tracker.status = "skipped";
+            tracker.skipReason = "no-declaration";
+          }
+          continue;
+        }
+        const exp = serializeDeclaration2(declaration, symbol, targetSymbol, exportName, ctx, isTypeOnly);
+        if (exp) {
+          exports.push(exp);
+          tracker.status = "success";
+          tracker.kind = exp.kind;
+        } else {
+          tracker.status = "skipped";
+          tracker.skipReason = "internal";
+        }
+      } catch (err) {
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        tracker.status = "failed";
+        tracker.error = errorMsg;
+        diagnostics.push({
+          message: `Failed to serialize '${exportName}': ${errorMsg}`,
+          severity: "warning",
+          code: "SERIALIZATION_FAILED"
+        });
+      }
+    }
+    const verification = buildVerificationSummary(exportedSymbols.length, exports.length, exportTracker);
+    const meta = await getPackageMeta(entryFile, baseDir);
+    const types = ctx.typeRegistry.getAll();
+    const projectBaseDir = baseDir ?? path8.dirname(entryFile);
+    const definedTypes = new Set(types.map((t) => t.id));
+    const forgottenExports = collectForgottenExports(exports, types, program, sourceFile, exportedIds, projectBaseDir, definedTypes);
+    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) {
+      diagnostics.push({
+        message: `${externalTypes.length} external type(s) from dependencies: ${externalTypes.slice(0, 5).map((t) => t.id).join(", ")}${externalTypes.length > 5 ? "..." : ""}`,
+        severity: "info",
+        code: "EXTERNAL_TYPES"
+      });
+    }
+    let runtimeMetadata;
+    if (options.schemaExtraction === "hybrid") {
+      const projectBaseDir2 = baseDir || path8.dirname(entryFile);
+      const runtimeResult = await extractStandardSchemasFromProject(entryFile, projectBaseDir2, {
+        target: options.schemaTarget || "draft-2020-12",
+        timeout: 15000
+      });
+      if (runtimeResult.schemas.size > 0) {
+        const mergeResult = mergeRuntimeSchemas(exports, runtimeResult.schemas);
+        exports = mergeResult.exports;
+        const method = runtimeResult.info?.method === "direct-ts" ? `direct-ts (${runtimeResult.info.runtime})` : "compiled";
+        runtimeMetadata = {
+          extracted: runtimeResult.schemas.size,
+          merged: mergeResult.merged,
+          vendors: [...new Set([...runtimeResult.schemas.values()].map((s) => s.vendor))],
+          errors: runtimeResult.errors,
+          warnings: runtimeResult.warnings,
+          method
+        };
+      }
+      for (const error of runtimeResult.errors) {
+        diagnostics.push({
+          message: `Runtime schema extraction: ${error}`,
+          severity: "warning",
+          code: "RUNTIME_SCHEMA_ERROR"
+        });
+      }
+      for (const warning of runtimeResult.warnings) {
+        diagnostics.push({
+          message: `Schema extraction skipped${warning.exportName ? ` (${warning.exportName})` : ""}: ${warning.message}`,
+          severity: "warning",
+          code: warning.code
+        });
+      }
+    }
+    const normalizedExports = exports.map((exp) => normalizeExport(exp, { dialect: "draft-2020-12" }));
+    const normalizedTypes = types.map((t) => normalizeType(t, { dialect: "draft-2020-12" }));
+    const spec = {
+      ...includeSchema ? { $schema: SCHEMA_URL } : {},
+      openpkg: SCHEMA_VERSION,
+      meta,
+      exports: normalizedExports,
+      types: normalizedTypes,
+      generation: {
+        generator: "@openpkg-ts/sdk",
+        timestamp: new Date().toISOString(),
+        mode: isDtsSource ? "declaration-only" : "source",
+        ...options.schemaExtraction === "hybrid" ? { schemaExtraction: "hybrid" } : {},
+        ...isDtsSource && {
+          limitations: ["No JSDoc descriptions", "No @example tags", "No @param descriptions"]
+        },
+        ...verification.details.skipped.length > 0 && {
+          skipped: verification.details.skipped
+        }
+      }
+    };
+    const internalForgotten = forgottenExports.filter((f) => !f.isExternal);
+    const degradedMode = isDtsSource ? { reason: "dts-source", stats: computeDegradedStats(normalizedExports) } : undefined;
+    if (verification.failed > 0) {
+      const failedNames = verification.details.failed.map((f) => f.name).join(", ");
+      diagnostics.push({
+        message: `Export verification: ${verification.failed} export(s) failed: ${failedNames}`,
+        severity: "warning",
+        code: "EXPORT_VERIFICATION_FAILED",
+        suggestion: "Check serialization errors for these exports"
+      });
+    }
+    return {
+      spec,
+      diagnostics,
+      verification,
+      ...internalForgotten.length > 0 ? { forgottenExports: internalForgotten } : {},
+      ...runtimeMetadata ? { runtimeSchemas: runtimeMetadata } : {},
+      ...degradedMode ? { degradedMode } : {}
+    };
+  } finally {
+    clearTypeDefinitionCache();
+  }
+}
 function serializeDeclaration2(declaration, exportSymbol, _targetSymbol, exportName, ctx, isTypeOnly = false) {
   let result = null;
-  if (ts15.isFunctionDeclaration(declaration)) {
+  if (ts16.isFunctionDeclaration(declaration)) {
     result = serializeFunctionExport(declaration, ctx);
-  } else if (ts15.isClassDeclaration(declaration)) {
+  } else if (ts16.isClassDeclaration(declaration)) {
     result = serializeClass(declaration, ctx);
-  } else if (ts15.isInterfaceDeclaration(declaration)) {
+  } else if (ts16.isInterfaceDeclaration(declaration)) {
     result = serializeInterface(declaration, ctx);
-  } else if (ts15.isTypeAliasDeclaration(declaration)) {
+  } else if (ts16.isTypeAliasDeclaration(declaration)) {
     result = serializeTypeAlias(declaration, ctx);
-  } else if (ts15.isEnumDeclaration(declaration)) {
+  } else if (ts16.isEnumDeclaration(declaration)) {
     result = serializeEnum(declaration, ctx);
-  } else if (ts15.isVariableDeclaration(declaration)) {
+  } else if (ts16.isVariableDeclaration(declaration)) {
     const varStatement = declaration.parent?.parent;
-    if (varStatement && ts15.isVariableStatement(varStatement)) {
-      if (declaration.initializer && ts15.isArrowFunction(declaration.initializer)) {
-        const varName = ts15.isIdentifier(declaration.name) ? declaration.name.text : declaration.name.getText();
+    if (varStatement && ts16.isVariableStatement(varStatement)) {
+      if (declaration.initializer && ts16.isArrowFunction(declaration.initializer)) {
+        const varName = ts16.isIdentifier(declaration.name) ? declaration.name.text : declaration.name.getText();
         result = serializeFunctionExport(declaration.initializer, ctx, varName);
       } else {
         result = serializeVariable(declaration, varStatement, ctx);
       }
     }
-  } else if (ts15.isNamespaceExport(declaration) || ts15.isModuleDeclaration(declaration)) {
+  } else if (ts16.isNamespaceExport(declaration) || ts16.isModuleDeclaration(declaration)) {
     try {
       result = serializeNamespaceExport(exportSymbol, exportName, ctx);
     } catch {
@@ -5972,7 +6185,7 @@ function serializeDeclaration2(declaration, exportSymbol, _targetSymbol, exportN
         examples: []
       };
     }
-  } else if (ts15.isNamespaceImport(declaration)) {
+  } else if (ts16.isNamespaceImport(declaration)) {
     try {
       result = serializeNamespaceExport(exportSymbol, exportName, ctx);
     } catch {
@@ -5985,7 +6198,7 @@ function serializeDeclaration2(declaration, exportSymbol, _targetSymbol, exportN
         examples: []
       };
     }
-  } else if (ts15.isSourceFile(declaration)) {
+  } else if (ts16.isSourceFile(declaration)) {
     try {
       result = serializeNamespaceExport(exportSymbol, exportName, ctx);
     } catch {
@@ -6015,7 +6228,7 @@ function serializeNamespaceExport(symbol, exportName, ctx) {
   const members = [];
   const checker = ctx.program.getTypeChecker();
   let targetSymbol = symbol;
-  if (symbol.flags & ts15.SymbolFlags.Alias) {
+  if (symbol.flags & ts16.SymbolFlags.Alias) {
     const aliased = checker.getAliasedSymbol(symbol);
     if (aliased && aliased !== symbol) {
       targetSymbol = aliased;
@@ -6042,31 +6255,31 @@ function serializeNamespaceExport(symbol, exportName, ctx) {
 function serializeNamespaceMember(symbol, memberName, ctx) {
   const checker = ctx.program.getTypeChecker();
   let targetSymbol = symbol;
-  if (symbol.flags & ts15.SymbolFlags.Alias) {
+  if (symbol.flags & ts16.SymbolFlags.Alias) {
     const aliased = checker.getAliasedSymbol(symbol);
     if (aliased && aliased !== symbol) {
       targetSymbol = aliased;
     }
   }
   const declarations = targetSymbol.declarations ?? [];
-  const declaration = targetSymbol.valueDeclaration || declarations.find((d) => d.kind !== ts15.SyntaxKind.ExportSpecifier) || declarations[0];
+  const declaration = targetSymbol.valueDeclaration || declarations.find((d) => d.kind !== ts16.SyntaxKind.ExportSpecifier) || declarations[0];
   if (!declaration)
     return null;
   const type = checker.getTypeAtLocation(declaration);
   const callSignatures = type.getCallSignatures();
   const deprecated = isSymbolDeprecated(targetSymbol);
   let kind = "variable";
-  if (ts15.isFunctionDeclaration(declaration) || ts15.isFunctionExpression(declaration)) {
+  if (ts16.isFunctionDeclaration(declaration) || ts16.isFunctionExpression(declaration)) {
     kind = "function";
-  } else if (ts15.isClassDeclaration(declaration)) {
+  } else if (ts16.isClassDeclaration(declaration)) {
     kind = "class";
-  } else if (ts15.isInterfaceDeclaration(declaration)) {
+  } else if (ts16.isInterfaceDeclaration(declaration)) {
     kind = "interface";
-  } else if (ts15.isTypeAliasDeclaration(declaration)) {
+  } else if (ts16.isTypeAliasDeclaration(declaration)) {
     kind = "type";
-  } else if (ts15.isEnumDeclaration(declaration)) {
+  } else if (ts16.isEnumDeclaration(declaration)) {
     kind = "enum";
-  } else if (ts15.isVariableDeclaration(declaration)) {
+  } else if (ts16.isVariableDeclaration(declaration)) {
     if (callSignatures.length > 0) {
       kind = "function";
     }
@@ -6113,11 +6326,11 @@ function getJSDocFromExportSymbol(symbol) {
   const examples = [];
   const decl = symbol.declarations?.[0];
   if (decl) {
-    const exportDecl = ts15.isNamespaceExport(decl) ? decl.parent : decl;
-    if (exportDecl && ts15.isExportDeclaration(exportDecl)) {
-      const jsDocs = ts15.getJSDocCommentsAndTags(exportDecl);
+    const exportDecl = ts16.isNamespaceExport(decl) ? decl.parent : decl;
+    if (exportDecl && ts16.isExportDeclaration(exportDecl)) {
+      const jsDocs = ts16.getJSDocCommentsAndTags(exportDecl);
       for (const doc of jsDocs) {
-        if (ts15.isJSDoc(doc) && doc.comment) {
+        if (ts16.isJSDoc(doc) && doc.comment) {
           const commentText = typeof doc.comment === "string" ? doc.comment : doc.comment.map((c) => ("text" in c) ? c.text : "").join("");
           if (commentText) {
             return {
@@ -6179,7 +6392,7 @@ function createEmptySpec(entryFile, includeSchema, isDtsSource) {
   return {
     ...includeSchema ? { $schema: SCHEMA_URL } : {},
     openpkg: SCHEMA_VERSION,
-    meta: { name: path7.basename(entryFile, path7.extname(entryFile)) },
+    meta: { name: path8.basename(entryFile, path8.extname(entryFile)) },
     exports: [],
     generation: {
       generator: "@openpkg-ts/sdk",
@@ -6192,19 +6405,19 @@ function createEmptySpec(entryFile, includeSchema, isDtsSource) {
   };
 }
 async function getPackageMeta(entryFile, baseDir) {
-  const searchDir = baseDir ?? path7.dirname(entryFile);
-  const pkgPath = path7.join(searchDir, "package.json");
+  const searchDir = baseDir ?? path8.dirname(entryFile);
+  const pkgPath = path8.join(searchDir, "package.json");
   try {
     if (fs7.existsSync(pkgPath)) {
       const pkg = JSON.parse(fs7.readFileSync(pkgPath, "utf-8"));
       return {
-        name: pkg.name ?? path7.basename(searchDir),
+        name: pkg.name ?? path8.basename(searchDir),
         version: pkg.version,
         description: pkg.description
       };
     }
   } catch {}
-  return { name: path7.basename(searchDir) };
+  return { name: path8.basename(searchDir) };
 }
 
 // src/primitives/spec.ts
@@ -6326,6 +6539,7 @@ export {
   analyzeSpec,
   TypeRegistry,
   QueryBuilder,
+  CacheManager,
   CONFIG_FILENAME,
   BUILTIN_TYPE_SCHEMAS,
   ARRAY_PROTOTYPE_METHODS