@openpkg-ts/extract 0.14.0 → 0.14.1

package/dist/bin/tspec.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   extract
-} from "../shared/chunk-v4cnenxs.js";
+} from "../shared/chunk-khwn5myc.js";
 
 // src/cli/spec.ts
 import * as fs from "node:fs";
@@ -9,7 +9,7 @@ import * as path from "node:path";
 import { normalize, validateSpec } from "@openpkg-ts/spec";
 import { Command } from "commander";
 function createProgram() {
-  const program = new Command("tspec").description("Extract TypeScript package API to OpenPkg spec").argument("[entry]", "Entry point file").option("-o, --output <file>", "Output file", "openpkg.json").option("--max-depth <n>", "Max type depth", "20").option("--skip-resolve", "Skip external type resolution").option("--runtime", "Enable Standard Schema runtime extraction").action(async (entry, options) => {
+  const program = new Command("tspec").description("Extract TypeScript package API to OpenPkg spec").argument("[entry]", "Entry point file").option("-o, --output <file>", "Output file", "openpkg.json").option("--max-depth <n>", "Max type depth (default: 4)").option("--skip-resolve", "Skip external type resolution").option("--runtime", "Enable Standard Schema runtime extraction").action(async (entry, options) => {
     const entryFile = entry || findEntryPoint(process.cwd());
     if (!entryFile) {
       console.error("No entry point found. Please specify an entry file.");
@@ -18,7 +18,7 @@ function createProgram() {
     console.log(`Extracting from: ${entryFile}`);
     const result = await extract({
       entryFile: path.resolve(entryFile),
-      maxTypeDepth: parseInt(options.maxDepth),
+      ...options.maxDepth ? { maxTypeDepth: parseInt(options.maxDepth) } : {},
       resolveExternalTypes: !options.skipResolve,
       schemaExtraction: options.runtime ? "hybrid" : "static"
     });

package/dist/shared/{chunk-v4cnenxs.js → chunk-khwn5myc.js}

@@ -1,6 +1,4 @@
 // src/ast/registry.ts
-import * as fs from "node:fs";
-import * as path from "node:path";
 import ts from "typescript";
 var PRIMITIVES = new Set([
   "string",
@@ -94,48 +92,6 @@ function isExternalType(decl) {
     return false;
   return sourceFile.fileName.includes("node_modules");
 }
-function extractPackageName(filePath) {
-  const nmIndex = filePath.lastIndexOf("node_modules");
-  if (nmIndex === -1)
-    return;
-  const afterNm = filePath.slice(nmIndex + "node_modules/".length);
-  const parts = afterNm.split("/");
-  if (parts[0].startsWith("@") && parts.length >= 2) {
-    return `${parts[0]}/${parts[1]}`;
-  }
-  return parts[0];
-}
-function getPackageVersion(filePath, packageName) {
-  const nmIndex = filePath.lastIndexOf("node_modules");
-  if (nmIndex === -1)
-    return;
-  const nmDir = filePath.slice(0, nmIndex + "node_modules".length);
-  const pkgJsonPath = path.join(nmDir, packageName, "package.json");
-  try {
-    if (fs.existsSync(pkgJsonPath)) {
-      const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
-      return pkg.version;
-    }
-  } catch {}
-  return;
-}
-function buildExternalSource(decl) {
-  const sourceFile = decl.getSourceFile();
-  if (!sourceFile)
-    return;
-  const filePath = sourceFile.fileName;
-  if (!filePath.includes("node_modules"))
-    return;
-  const packageName = extractPackageName(filePath);
-  if (!packageName)
-    return;
-  const version = getPackageVersion(filePath, packageName);
-  return {
-    file: filePath,
-    package: packageName,
-    version
-  };
-}
 
 class TypeRegistry {
   types = new Map;
@@ -167,17 +123,19 @@ class TypeRegistry {
       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 (exportedIds.has(name))
-      return name;
     if (this.processing.has(name))
       return name;
     this.processing.add(name);
     try {
-      const specType = this.buildSpecType(symbol, type, checker);
+      const specType = this.buildStubType(symbol, checker);
       if (specType) {
         this.add(specType);
         return specType.id;
@@ -187,7 +145,7 @@ class TypeRegistry {
     }
     return;
   }
-  buildSpecType(symbol, type, checker) {
+  buildStubType(symbol, checker) {
     const name = symbol.getName();
     const decl = symbol.declarations?.[0];
     let kind = "type";
@@ -203,139 +161,21 @@ class TypeRegistry {
     if (external) {
       kind = "external";
     }
-    const source = decl ? buildExternalSource(decl) : undefined;
-    const schema = this.buildShallowSchema(type, checker);
-    let members;
-    if (decl && (ts.isClassDeclaration(decl) || ts.isInterfaceDeclaration(decl))) {
-      members = this.extractShallowMembers(decl, checker);
-    }
+    const type = checker.getDeclaredTypeOfSymbol(symbol);
+    const typeString = checker.typeToString(type);
     return {
       id: name,
       name,
       kind,
-      schema,
-      members: members?.length ? members : undefined,
-      ...external ? { external: true } : {},
-      ...source ? { source } : {}
+      schema: { type: typeString },
+      ...external ? { external: true } : {}
     };
   }
-  buildShallowSchema(type, checker) {
-    if (type.isUnion()) {
-      const allEnumLiterals = type.types.every((t) => t.flags & (ts.TypeFlags.EnumLiteral | ts.TypeFlags.NumberLiteral));
-      if (allEnumLiterals) {
-        const values = type.types.map((t) => {
-          if (t.flags & ts.TypeFlags.NumberLiteral) {
-            return t.value;
-          }
-          return checker.typeToString(t);
-        }).filter((v) => v !== undefined);
-        if (values.every((v) => typeof v === "number")) {
-          return { type: "number", enum: values };
-        }
-        return { type: "string", enum: values };
-      }
-      return {
-        anyOf: type.types.map((t) => {
-          if (t.flags & ts.TypeFlags.EnumLiteral) {
-            const value = t.value;
-            if (typeof value === "number") {
-              return { type: "number", enum: [value] };
-            }
-            return { type: checker.typeToString(t) };
-          }
-          const sym = t.getSymbol() || t.aliasSymbol;
-          if (sym && sym.flags & ts.SymbolFlags.EnumMember) {
-            return { type: checker.typeToString(t) };
-          }
-          if (sym && !sym.getName().startsWith("__")) {
-            return { $ref: `#/types/${sym.getName()}` };
-          }
-          if (t.flags & ts.TypeFlags.StringLiteral) {
-            return { type: "string", enum: [t.value] };
-          }
-          if (t.flags & ts.TypeFlags.NumberLiteral) {
-            return { type: "number", enum: [t.value] };
-          }
-          return { type: checker.typeToString(t) };
-        })
-      };
-    }
-    if (type.isIntersection()) {
-      return {
-        allOf: type.types.map((t) => {
-          const sym = t.getSymbol() || t.aliasSymbol;
-          if (sym && !sym.getName().startsWith("__")) {
-            return { $ref: `#/types/${sym.getName()}` };
-          }
-          return { type: checker.typeToString(t) };
-        })
-      };
-    }
-    const props = type.getProperties();
-    if (props.length > 0) {
-      const properties = {};
-      const required = [];
-      for (const prop of props.slice(0, 30)) {
-        const propName = prop.getName();
-        if (propName.startsWith("_"))
-          continue;
-        const propType = checker.getTypeOfSymbol(prop);
-        const callSigs = propType.getCallSignatures();
-        if (callSigs.length > 0) {
-          properties[propName] = { type: "function" };
-        } else {
-          const propSym = propType.getSymbol() || propType.aliasSymbol;
-          const symName = propSym?.getName();
-          if (propSym && symName && !symName.startsWith("__") && symName !== propName) {
-            properties[propName] = { $ref: `#/types/${symName}` };
-          } else {
-            properties[propName] = { type: checker.typeToString(propType) };
-          }
-        }
-        if (!(prop.flags & ts.SymbolFlags.Optional)) {
-          required.push(propName);
-        }
-      }
-      return {
-        type: "object",
-        properties,
-        ...required.length ? { required } : {}
-      };
-    }
-    return { type: checker.typeToString(type) };
-  }
-  extractShallowMembers(decl, checker) {
-    const members = [];
-    for (const member of decl.members) {
-      if (ts.isPropertyDeclaration(member) || ts.isPropertySignature(member)) {
-        const name = member.name?.getText();
-        if (!name || name.startsWith("#") || name.startsWith("_"))
-          continue;
-        const type = checker.getTypeAtLocation(member);
-        const sym = type.getSymbol() || type.aliasSymbol;
-        members.push({
-          name,
-          kind: "property",
-          schema: sym && !sym.getName().startsWith("__") ? { $ref: `#/types/${sym.getName()}` } : { type: checker.typeToString(type) }
-        });
-      } else if (ts.isMethodDeclaration(member) || ts.isMethodSignature(member)) {
-        const name = member.name?.getText();
-        if (!name || name.startsWith("#") || name.startsWith("_"))
-          continue;
-        members.push({
-          name,
-          kind: "method"
-        });
-      }
-    }
-    return members;
-  }
   registerFromSymbol(symbol, checker) {
     const name = symbol.getName();
     if (this.has(name))
       return this.get(name);
-    const type = checker.getDeclaredTypeOfSymbol(symbol);
-    const specType = this.buildSpecType(symbol, type, checker);
+    const specType = this.buildStubType(symbol, checker);
     if (specType) {
       this.add(specType);
       return specType;
@@ -445,7 +285,7 @@ function isSymbolDeprecated(symbol) {
 }
 
 // src/compiler/program.ts
-import * as path2 from "node:path";
+import * as path from "node:path";
 import ts3 from "typescript";
 var DEFAULT_COMPILER_OPTIONS = {
   target: ts3.ScriptTarget.Latest,
@@ -456,14 +296,14 @@ var DEFAULT_COMPILER_OPTIONS = {
 };
 function createProgram({
   entryFile,
-  baseDir = path2.dirname(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, path2.dirname(configPath));
+    const parsedConfig = ts3.parseJsonConfigFileContent(configFile.config, ts3.sys, path.dirname(configPath));
     compilerOptions = { ...compilerOptions, ...parsedConfig.options };
   }
   const allowJsVal = compilerOptions.allowJs;
@@ -615,12 +455,19 @@ function buildSchema(type, checker, ctx, _depth = 0) {
     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)
@@ -734,6 +581,12 @@ function buildSchema(type, checker, ctx, _depth = 0) {
       };
     }
   }
+  if (type.flags & ts4.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();
@@ -749,10 +602,6 @@ function buildSchema(type, checker, ctx, _depth = 0) {
   }
   if (type.flags & ts4.TypeFlags.Object) {
     const objectType = type;
-    const callSignatures = type.getCallSignatures();
-    if (callSignatures.length > 0) {
-      return buildFunctionSchema(callSignatures, checker, ctx);
-    }
     const properties = type.getProperties();
     if (properties.length > 0 || objectType.objectFlags & ts4.ObjectFlags.Anonymous) {
       return buildObjectSchema(properties, checker, ctx);
@@ -1032,7 +881,9 @@ function extractDefaultValue(initializer) {
   }
   return initializer.getText();
 }
-function registerReferencedTypes(type, ctx) {
+function registerReferencedTypes(type, ctx, depth = 0) {
+  if (depth > ctx.maxTypeDepth)
+    return;
   if (ctx.visitedTypes.has(type))
     return;
   const isPrimitive = type.flags & (ts5.TypeFlags.String | ts5.TypeFlags.Number | ts5.TypeFlags.Boolean | ts5.TypeFlags.Void | ts5.TypeFlags.Undefined | ts5.TypeFlags.Null | ts5.TypeFlags.Any | ts5.TypeFlags.Unknown | ts5.TypeFlags.Never | ts5.TypeFlags.StringLiteral | ts5.TypeFlags.NumberLiteral | ts5.TypeFlags.BooleanLiteral);
@@ -1044,17 +895,24 @@ function registerReferencedTypes(type, ctx) {
   const typeArgs = type.typeArguments;
   if (typeArgs) {
     for (const arg of typeArgs) {
-      registerReferencedTypes(arg, ctx);
+      registerReferencedTypes(arg, ctx, depth + 1);
     }
   }
   if (type.isUnion()) {
     for (const t of type.types) {
-      registerReferencedTypes(t, ctx);
+      registerReferencedTypes(t, ctx, depth + 1);
     }
   }
   if (type.isIntersection()) {
     for (const t of type.types) {
-      registerReferencedTypes(t, ctx);
+      registerReferencedTypes(t, ctx, depth + 1);
+    }
+  }
+  if (type.flags & ts5.TypeFlags.Object) {
+    const props = type.getProperties();
+    for (const prop of props.slice(0, 20)) {
+      const propType = checker.getTypeOfSymbol(prop);
+      registerReferencedTypes(propType, ctx, depth + 1);
     }
   }
 }
@@ -1166,8 +1024,8 @@ function serializeProperty(node, ctx) {
   const { description, tags } = getJSDocComment(node);
   const visibility = getVisibility(node);
   const type = checker.getTypeAtLocation(node);
-  const schema = buildSchema(type, checker, ctx);
   registerReferencedTypes(type, ctx);
+  const schema = buildSchema(type, checker, ctx);
   const flags = {};
   if (isStatic(node))
     flags.static = true;
@@ -1541,8 +1399,8 @@ function serializeTypeAlias(node, ctx) {
   const source = getSourceLocation(node, declSourceFile);
   const typeParameters = extractTypeParameters(node, ctx.typeChecker);
   const type = ctx.typeChecker.getTypeAtLocation(node);
-  const schema = buildSchema(type, ctx.typeChecker, ctx);
   registerReferencedTypes(type, ctx);
+  const schema = buildSchema(type, ctx.typeChecker, ctx);
   return {
     id: name,
     name,
@@ -1566,8 +1424,8 @@ function serializeVariable(node, statement, ctx) {
   const { description, tags, examples } = getJSDocComment(statement);
   const source = getSourceLocation(node, declSourceFile);
   const type = ctx.typeChecker.getTypeAtLocation(node);
-  const schema = buildSchema(type, ctx.typeChecker, ctx);
   registerReferencedTypes(type, ctx);
+  const schema = buildSchema(type, ctx.typeChecker, ctx);
   return {
     id: name,
     name,
@@ -1581,8 +1439,8 @@ function serializeVariable(node, statement, ctx) {
 }
 
 // src/builder/spec-builder.ts
-import * as fs2 from "node:fs";
-import * as path3 from "node:path";
+import * as fs from "node:fs";
+import * as path2 from "node:path";
 import { SCHEMA_URL, SCHEMA_VERSION } from "@openpkg-ts/spec";
 import ts8 from "typescript";
 
@@ -1605,9 +1463,14 @@ function createContext(program, sourceFile, options = {}) {
 // src/builder/spec-builder.ts
 var BUILTIN_TYPES2 = new Set([
   "Array",
+  "ArrayBuffer",
+  "ArrayBufferLike",
+  "ArrayLike",
   "Promise",
   "Map",
   "Set",
+  "WeakMap",
+  "WeakSet",
   "Record",
   "Partial",
   "Required",
@@ -1621,6 +1484,15 @@ var BUILTIN_TYPES2 = new Set([
   "Readonly",
   "ReadonlyArray",
   "Awaited",
+  "PromiseLike",
+  "Iterable",
+  "Iterator",
+  "IterableIterator",
+  "Generator",
+  "AsyncGenerator",
+  "AsyncIterable",
+  "AsyncIterator",
+  "AsyncIterableIterator",
   "Date",
   "RegExp",
   "Error",
@@ -1630,8 +1502,34 @@ var BUILTIN_TYPES2 = new Set([
   "Number",
   "Boolean",
   "Symbol",
-  "BigInt"
+  "BigInt",
+  "Uint8Array",
+  "Int8Array",
+  "Uint16Array",
+  "Int16Array",
+  "Uint32Array",
+  "Int32Array",
+  "Float32Array",
+  "Float64Array",
+  "BigInt64Array",
+  "BigUint64Array",
+  "DataView",
+  "SharedArrayBuffer",
+  "ConstructorParameters",
+  "InstanceType",
+  "ThisType"
 ]);
+function shouldSkipDanglingRef(name) {
+  if (name.startsWith("__"))
+    return true;
+  if (/^[A-Z]$/.test(name))
+    return true;
+  if (/^T[A-Z]/.test(name))
+    return true;
+  if (["Key", "Value", "Item", "Element"].includes(name))
+    return true;
+  return false;
+}
 async function extract(options) {
   const {
     entryFile,
@@ -1701,10 +1599,9 @@ async function extract(options) {
   const externalTypes = types.filter((t) => t.kind === "external");
   if (externalTypes.length > 0) {
     diagnostics.push({
-      message: `${externalTypes.length} external type(s) could not be fully resolved: ${externalTypes.slice(0, 5).map((t) => t.id).join(", ")}${externalTypes.length > 5 ? "..." : ""}`,
-      severity: "warning",
-      code: "EXTERNAL_TYPE_STUBS",
-      suggestion: "Types are from external packages. Full resolution requires type declarations."
+      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"
     });
   }
   const spec = {
@@ -1744,7 +1641,7 @@ function collectDanglingRefs(exports, types) {
   const referencedTypes = new Set;
   collectAllRefs(exports, referencedTypes);
   collectAllRefs(types, referencedTypes);
-  return Array.from(referencedTypes).filter((ref) => !definedTypes.has(ref) && !BUILTIN_TYPES2.has(ref));
+  return Array.from(referencedTypes).filter((ref) => !definedTypes.has(ref) && !BUILTIN_TYPES2.has(ref) && !shouldSkipDanglingRef(ref));
 }
 function resolveExportTarget(symbol, checker) {
   let targetSymbol = symbol;
@@ -1867,7 +1764,7 @@ function createEmptySpec(entryFile, includeSchema) {
   return {
     ...includeSchema ? { $schema: SCHEMA_URL } : {},
     openpkg: SCHEMA_VERSION,
-    meta: { name: path3.basename(entryFile, path3.extname(entryFile)) },
+    meta: { name: path2.basename(entryFile, path2.extname(entryFile)) },
     exports: [],
     generation: {
       generator: "@openpkg-ts/extract",
@@ -1876,18 +1773,18 @@ function createEmptySpec(entryFile, includeSchema) {
   };
 }
 async function getPackageMeta(entryFile, baseDir) {
-  const searchDir = baseDir ?? path3.dirname(entryFile);
-  const pkgPath = path3.join(searchDir, "package.json");
+  const searchDir = baseDir ?? path2.dirname(entryFile);
+  const pkgPath = path2.join(searchDir, "package.json");
   try {
-    if (fs2.existsSync(pkgPath)) {
-      const pkg = JSON.parse(fs2.readFileSync(pkgPath, "utf-8"));
+    if (fs.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
       return {
-        name: pkg.name ?? path3.basename(searchDir),
+        name: pkg.name ?? path2.basename(searchDir),
         version: pkg.version,
         description: pkg.description
       };
     }
   } catch {}
-  return { name: path3.basename(searchDir) };
+  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 };

package/dist/src/index.d.ts

@@ -8,21 +8,14 @@ declare class TypeRegistry {
 	has(id: string): boolean;
 	getAll(): SpecType[];
 	/**
-	* Register a type from a ts.Type, extracting its structure.
+	* Register a type from a ts.Type (lightweight stub).
 	* Returns the type ID if registered, undefined if skipped.
 	*/
 	registerType(type: ts.Type, checker: ts.TypeChecker, exportedIds: Set<string>): string | undefined;
-	private buildSpecType;
 	/**
-	* Build a shallow schema for registry types (no deep recursion).
-	* Only captures top-level structure with $refs.
+	* Build a lightweight stub type (no deep schema extraction).
 	*/
-	private buildShallowSchema;
-	/**
-	* Extract shallow members for classes/interfaces.
-	* Only captures property names and simple type info.
-	*/
-	private extractShallowMembers;
+	private buildStubType;
 	registerFromSymbol(symbol: ts.Symbol, checker: ts.TypeChecker): SpecType | undefined;
 }
 import { SpecExample, SpecSource, SpecTag, SpecTypeParameter } from "@openpkg-ts/spec";
@@ -253,7 +246,7 @@ declare function extractParameters(signature: ts11.Signature, ctx: SerializerCon
 * Recursively register types referenced by a ts.Type.
 * Uses ctx.visitedTypes to prevent infinite recursion on circular types.
 */
-declare function registerReferencedTypes(type: ts11.Type, ctx: SerializerContext): void;
+declare function registerReferencedTypes(type: ts11.Type, ctx: SerializerContext, depth?: number): void;
 import { SpecSchema } from "@openpkg-ts/spec";
 import ts12 from "typescript";
 /**

package/dist/src/index.js

@@ -26,7 +26,7 @@ import {
   serializeTypeAlias,
   serializeVariable,
   withDescription
-} from "../shared/chunk-v4cnenxs.js";
+} from "../shared/chunk-khwn5myc.js";
 // src/schema/registry.ts
 function isTypeReference(type) {
   return !!(type.flags & 524288 && type.objectFlags && type.objectFlags & 4);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpkg-ts/extract",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "TypeScript export extraction to OpenPkg spec",
   "keywords": [
     "openpkg",