@openpkg-ts/extract 0.25.0 → 0.27.0

package/dist/bin/tspec.js

@@ -3,7 +3,7 @@ import {
   detectTsRuntime,
   extract,
   resolveCompiledPath
-} from "../shared/chunk-2zvzqxtn.js";
+} from "../shared/chunk-v9c97d62.js";
 
 // src/cli/spec.ts
 import * as fs from "node:fs";
@@ -412,7 +412,7 @@ function summary(options) {
 }
 // src/cli/spec.ts
 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 (default: 4)").option("--skip-resolve", "Skip external type resolution").option("--runtime", "Enable Standard Schema runtime extraction").option("--only <exports>", "Only extract these exports (comma-separated, supports * wildcards)").option("--ignore <exports>", "Ignore these exports (comma-separated, supports * wildcards)").option("-v, --verbose", "Show detailed output").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").option("--only <exports>", "Only extract these exports (comma-separated, supports * wildcards)").option("--ignore <exports>", "Ignore these exports (comma-separated, supports * wildcards)").option("-v, --verbose", "Show detailed output").option("--verify", "Enable export count verification mode (exit 1 on failures)").action(async (entry, options) => {
     let entryFile;
     let fromDts = false;
     if (entry) {
@@ -428,8 +428,9 @@ function createProgram() {
       fromDts = found.fromDts;
     }
     if (fromDts) {
-      console.warn("⚠ Using .d.ts file. TSDoc comments may be missing.");
-      console.warn(`  Consider: tspec src/index.ts
+      console.log("Mode: Declaration-only (.d.ts)");
+      console.log("  Types and signatures will be extracted");
+      console.log(`  JSDoc comments unavailable (stripped during compilation)
 `);
     }
     if (options.runtime) {
@@ -459,7 +460,8 @@ function createProgram() {
       resolveExternalTypes: !options.skipResolve,
       schemaExtraction: options.runtime ? "hybrid" : "static",
       ...options.only ? { only: options.only.split(",").map((s) => s.trim()) } : {},
-      ...options.ignore ? { ignore: options.ignore.split(",").map((s) => s.trim()) } : {}
+      ...options.ignore ? { ignore: options.ignore.split(",").map((s) => s.trim()) } : {},
+      isDtsSource: fromDts
     });
     const normalized = normalize(result.spec);
     const validation = validateSpec(normalized);
@@ -473,6 +475,15 @@ function createProgram() {
     }
     fs.writeFileSync(options.output, JSON.stringify(normalized, null, 2));
     spin.success(`Extracted to ${options.output}`);
+    if (result.degradedMode) {
+      const { stats } = result.degradedMode;
+      const total = normalized.exports.length;
+      console.log(`
+Extraction completed in declaration-only mode:`);
+      console.log(`  ${stats.exportsWithoutDescription}/${total} exports missing descriptions`);
+      console.log(`  ${stats.paramsWithoutDocs} parameters without documentation`);
+      console.log(`  ${stats.missingExamples} exports without examples`);
+    }
     if (result.runtimeSchemas) {
       const { extracted, merged, vendors, method } = result.runtimeSchemas;
       const via = method ? ` via ${method}` : "";
@@ -488,7 +499,34 @@ function createProgram() {
     if (result.runtimeSchemas) {
       sum.addKeyValue("Runtime Schemas", result.runtimeSchemas.merged);
     }
+    if (result.verification) {
+      const v = result.verification;
+      sum.addKeyValue("Discovered", v.discovered);
+      sum.addKeyValue("Extracted", v.extracted);
+      if (v.failed > 0) {
+        sum.addWithThreshold("Failed", v.failed, { value: 0, operator: "<=" });
+      }
+    }
     sum.print();
+    if (result.verification?.failed) {
+      console.log(`
+Failed exports:`);
+      for (const f of result.verification.details.failed) {
+        console.log(`  - ${f.name}: ${f.error}`);
+      }
+    }
+    if (options.verbose && result.verification?.details.skipped.length) {
+      console.log(`
+Skipped exports:`);
+      for (const s of result.verification.details.skipped) {
+        console.log(`  - ${s.name}: ${s.reason}`);
+      }
+    }
+    if (options.verify && result.verification?.failed) {
+      const v = result.verification;
+      spin.fail(`Expected ${v.discovered} exports, got ${v.extracted}`);
+      process.exit(1);
+    }
   });
   return program;
 }

package/dist/shared/{chunk-2zvzqxtn.js → chunk-v9c97d62.js}

@@ -831,7 +831,7 @@ function extractSeeTagText(tag) {
   }
   return typeof tag.comment === "string" ? tag.comment : ts3.getTextOfJSDocComment(tag.comment) ?? "";
 }
-function getJSDocComment(node) {
+function getJSDocComment(node, symbol, checker) {
   const jsDocTags = ts3.getJSDocTags(node);
   const tags = jsDocTags.map((tag) => {
     const rawText = typeof tag.comment === "string" ? tag.comment : ts3.getTextOfJSDocComment(tag.comment) ?? "";
@@ -869,6 +869,13 @@ function getJSDocComment(node) {
       description = typeof firstDoc.comment === "string" ? firstDoc.comment : ts3.getTextOfJSDocComment(firstDoc.comment);
     }
   }
+  if (!description && symbol && checker) {
+    const docComment = symbol.getDocumentationComment(checker);
+    if (docComment.length > 0) {
+      description = docComment.map((c) => c.text).join(`
+`);
+    }
+  }
   const examples = parseExamplesFromTags(tags);
   return { description, tags, examples };
 }
@@ -954,12 +961,13 @@ function isSymbolDeprecated(symbol) {
   }
   return false;
 }
-function getJSDocForSignature(signature) {
+function getJSDocForSignature(signature, checker) {
   const decl = signature.getDeclaration();
   if (!decl) {
     return { tags: [], examples: [] };
   }
-  return getJSDocComment(decl);
+  const symbol = checker?.getSymbolAtLocation(decl);
+  return getJSDocComment(decl, symbol, checker);
 }
 function extractTypeParametersFromSignature(signature, checker) {
   const typeParams = signature.getTypeParameters();
@@ -1819,7 +1827,7 @@ function serializeInheritedMember(symbol, inheritedFrom, ctx, isStatic) {
       const params = extractParameters(sig, ctx);
       const returnType = checker.getReturnTypeOfSignature(sig);
       registerReferencedTypes(returnType, ctx);
-      const sigDoc = getJSDocForSignature(sig);
+      const sigDoc = getJSDocForSignature(sig, checker);
       return {
         parameters: params.length > 0 ? params : undefined,
         returns: {
@@ -1853,7 +1861,7 @@ function serializeClass(node, ctx) {
     return null;
   const deprecated = isSymbolDeprecated(symbol);
   const declSourceFile = node.getSourceFile();
-  const { description, tags, examples } = getJSDocComment(node);
+  const { description, tags, examples } = getJSDocComment(node, symbol, checker);
   const source = getSourceLocation(node, declSourceFile);
   const typeParameters = extractTypeParameters(node, checker);
   const members = [];
@@ -1995,7 +2003,7 @@ function serializeMethod(node, ctx) {
     const params = extractParameters(sig, ctx);
     const returnType = checker.getReturnTypeOfSignature(sig);
     registerReferencedTypes(returnType, ctx);
-    const sigDoc = getJSDocForSignature(sig);
+    const sigDoc = getJSDocForSignature(sig, checker);
     const sigTypeParams = extractTypeParametersFromSignature(sig, checker);
     return {
       parameters: params.length > 0 ? params : undefined,
@@ -2103,7 +2111,7 @@ function serializeEnum(node, ctx) {
     return null;
   const deprecated = isSymbolDeprecated(symbol);
   const declSourceFile = node.getSourceFile();
-  const { description, tags, examples } = getJSDocComment(node);
+  const { description, tags, examples } = getJSDocComment(node, symbol, checker);
   const source = getSourceLocation(node, declSourceFile);
   const members = node.members.map((member) => {
     const memberSymbol = checker.getSymbolAtLocation(member.name);
@@ -2176,14 +2184,14 @@ function serializeFunctionExport(node, ctx) {
     return null;
   const deprecated = isSymbolDeprecated(symbol);
   const declSourceFile = node.getSourceFile();
-  const { description, tags, examples } = getJSDocComment(node);
+  const { description, tags, examples } = getJSDocComment(node, symbol, ctx.typeChecker);
   const source = getSourceLocation(node, declSourceFile);
   const typeParameters = extractTypeParameters(node, ctx.typeChecker);
   const type = ctx.typeChecker.getTypeAtLocation(node);
   const callSignatures = type.getCallSignatures();
   const signatures = callSignatures.map((sig, index) => {
     const params = extractParameters(sig, ctx);
-    const sigDoc = getJSDocForSignature(sig);
+    const sigDoc = getJSDocForSignature(sig, ctx.typeChecker);
     const sigTypeParams = extractTypeParametersFromSignature(sig, ctx.typeChecker);
     return {
       parameters: params,
@@ -2219,7 +2227,7 @@ function serializeInterface(node, ctx) {
     return null;
   const deprecated = isSymbolDeprecated(symbol);
   const declSourceFile = node.getSourceFile();
-  const { description, tags, examples } = getJSDocComment(node);
+  const { description, tags, examples } = getJSDocComment(node, symbol, checker);
   const source = getSourceLocation(node, declSourceFile);
   const typeParameters = extractTypeParameters(node, checker);
   const members = [];
@@ -2294,7 +2302,7 @@ function serializeMethodSignature(node, ctx) {
     const params = extractParameters(sig, ctx);
     const returnType = checker.getReturnTypeOfSignature(sig);
     registerReferencedTypes(returnType, ctx);
-    const sigDoc = getJSDocForSignature(sig);
+    const sigDoc = getJSDocForSignature(sig, checker);
     const sigTypeParams = extractTypeParametersFromSignature(sig, checker);
     return {
       parameters: params.length > 0 ? params : undefined,
@@ -2404,7 +2412,7 @@ function serializeTypeAlias(node, ctx) {
     return null;
   const deprecated = isSymbolDeprecated(symbol);
   const declSourceFile = node.getSourceFile();
-  const { description, tags, examples } = getJSDocComment(node);
+  const { description, tags, examples } = getJSDocComment(node, symbol, ctx.typeChecker);
   const source = getSourceLocation(node, declSourceFile);
   const typeParameters = extractTypeParameters(node, ctx.typeChecker);
   const type = ctx.typeChecker.getTypeAtLocation(node);
@@ -2600,7 +2608,7 @@ function serializeVariable(node, statement, ctx) {
     return null;
   const deprecated = isSymbolDeprecated(symbol);
   const declSourceFile = node.getSourceFile();
-  const { description, tags, examples } = getJSDocComment(statement);
+  const { description, tags, examples } = getJSDocComment(statement, symbol, ctx.typeChecker);
   const source = getSourceLocation(node, declSourceFile);
   const type = ctx.typeChecker.getTypeAtLocation(node);
   const schemaExtraction = extractSchemaType(type, ctx.typeChecker);
@@ -3113,6 +3121,52 @@ function clearTypeDefinitionCache() {
   internalTagCache = null;
 }
 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 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 });
+    }
+  }
+  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
+    }
+  };
+}
 var BUILTIN_TYPES2 = new Set([
   "Array",
   "ArrayBuffer",
@@ -3208,7 +3262,8 @@ async function extract(options) {
     includeSchema,
     only,
     ignore,
-    onProgress
+    onProgress,
+    isDtsSource
   } = options;
   const diagnostics = [];
   let exports = [];
@@ -3216,7 +3271,7 @@ async function extract(options) {
   const { program, sourceFile } = result;
   if (!sourceFile) {
     return {
-      spec: createEmptySpec(entryFile, includeSchema),
+      spec: createEmptySpec(entryFile, includeSchema, isDtsSource),
       diagnostics: [{ message: `Could not load source file: ${entryFile}`, severity: "error" }]
     };
   }
@@ -3224,7 +3279,7 @@ async function extract(options) {
   const moduleSymbol = typeChecker.getSymbolAtLocation(sourceFile);
   if (!moduleSymbol) {
     return {
-      spec: createEmptySpec(entryFile, includeSchema),
+      spec: createEmptySpec(entryFile, includeSchema, isDtsSource),
       diagnostics: [{ message: "Could not get module symbol", severity: "warning" }]
     };
   }
@@ -3233,6 +3288,17 @@ async function extract(options) {
   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,
@@ -3244,24 +3310,39 @@ async function extract(options) {
   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 } = resolveExportTarget(symbol, typeChecker);
-      if (!declaration)
+      if (!declaration) {
+        tracker.status = "skipped";
+        tracker.skipReason = "no-declaration";
         continue;
+      }
       const exp = serializeDeclaration(declaration, symbol, targetSymbol, exportName, ctx);
-      if (exp)
+      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}: ${err}`,
-        severity: "warning"
+        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 ?? path3.dirname(entryFile);
@@ -3333,15 +3414,31 @@ async function extract(options) {
     generation: {
       generator: "@openpkg-ts/extract",
       timestamp: new Date().toISOString(),
-      ...options.schemaExtraction === "hybrid" ? { schemaExtraction: "hybrid" } : {}
+      mode: isDtsSource ? "declaration-only" : "source",
+      ...options.schemaExtraction === "hybrid" ? { schemaExtraction: "hybrid" } : {},
+      ...isDtsSource && {
+        limitations: ["No JSDoc descriptions", "No @example tags", "No @param descriptions"]
+      }
     }
   };
   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 } : {}
+    ...runtimeMetadata ? { runtimeSchemas: runtimeMetadata } : {},
+    ...degradedMode ? { degradedMode } : {}
   };
 }
 function collectAllRefsWithContext(obj, refs, state) {
@@ -3599,7 +3696,7 @@ function serializeNamespaceMember(symbol, memberName, ctx) {
       const returnType = checker.getReturnTypeOfSignature(sig);
       registerReferencedTypes(returnType, ctx);
       const returnSchema = buildSchema(returnType, ctx.typeChecker, ctx);
-      const sigDoc = getJSDocForSignature(sig);
+      const sigDoc = getJSDocForSignature(sig, checker);
       const sigTypeParams = extractTypeParametersFromSignature(sig, ctx.typeChecker);
       return {
         parameters: params,
@@ -3693,7 +3790,7 @@ function withExportName(entry, exportName) {
     name: entry.name
   };
 }
-function createEmptySpec(entryFile, includeSchema) {
+function createEmptySpec(entryFile, includeSchema, isDtsSource) {
   return {
     ...includeSchema ? { $schema: SCHEMA_URL } : {},
     openpkg: SCHEMA_VERSION,
@@ -3701,7 +3798,11 @@ function createEmptySpec(entryFile, includeSchema) {
     exports: [],
     generation: {
       generator: "@openpkg-ts/extract",
-      timestamp: new Date().toISOString()
+      timestamp: new Date().toISOString(),
+      mode: isDtsSource ? "declaration-only" : "source",
+      ...isDtsSource && {
+        limitations: ["No JSDoc descriptions", "No @example tags", "No @param descriptions"]
+      }
     }
   };
 }

package/dist/src/index.d.ts

@@ -43,7 +43,7 @@ declare class TypeRegistry {
 }
 import { SpecExample, SpecSource, SpecTag, SpecTypeParameter } from "@openpkg-ts/spec";
 import ts3 from "typescript";
-declare function getJSDocComment(node: ts3.Node): {
+declare function getJSDocComment(node: ts3.Node, symbol?: ts3.Symbol, checker?: ts3.TypeChecker): {
 	description?: string;
 	tags: SpecTag[];
 	examples: SpecExample[];
@@ -239,6 +239,8 @@ interface ExtractOptions {
 	ignore?: string[];
 	/** Progress callback for tracking extraction progress */
 	onProgress?: (current: number, total: number, item: string) => void;
+	/** Whether source is a .d.ts file (degraded mode - TSDoc may be missing) */
+	isDtsSource?: boolean;
 }
 interface ExtractResult {
 	spec: OpenPkg;
@@ -257,6 +259,17 @@ interface ExtractResult {
 		/** Extraction method used: 'compiled' or 'direct-ts (runtime)' */
 		method?: string;
 	};
+	/** Degraded mode info when extracting from .d.ts files */
+	degradedMode?: {
+		reason: "dts-source";
+		stats: {
+			exportsWithoutDescription: number;
+			paramsWithoutDocs: number;
+			missingExamples: number;
+		};
+	};
+	/** Export verification comparing discovered vs extracted */
+	verification?: ExportVerification;
 }
 interface Diagnostic {
 	message: string;
@@ -284,6 +297,29 @@ interface ForgottenExport {
 	isExternal: boolean;
 	fix?: string;
 }
+/** Verification result comparing discovered vs extracted exports */
+interface ExportVerification {
+	/** Total exports discovered by TypeScript */
+	discovered: number;
+	/** Exports successfully extracted */
+	extracted: number;
+	/** Exports skipped (filtered, no-declaration, internal) */
+	skipped: number;
+	/** Exports that failed during serialization */
+	failed: number;
+	/** Delta: discovered - extracted */
+	delta: number;
+	details: {
+		skipped: Array<{
+			name: string;
+			reason: "filtered" | "no-declaration" | "internal";
+		}>;
+		failed: Array<{
+			name: string;
+			error: string;
+		}>;
+	};
+}
 declare function extract(options: ExtractOptions): Promise<ExtractResult>;
 import ts4 from "typescript";
 interface ProgramOptions {

package/dist/src/index.js

@@ -48,7 +48,7 @@ import {
   valibotAdapter,
   withDescription,
   zodAdapter
-} from "../shared/chunk-2zvzqxtn.js";
+} from "../shared/chunk-v9c97d62.js";
 // src/types/utils.ts
 function isExported(node) {
   const modifiers = node.modifiers;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpkg-ts/extract",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "TypeScript export extraction to OpenPkg spec",
   "keywords": [
     "openpkg",
@@ -40,7 +40,7 @@
     "format": "biome format --write src/"
   },
   "dependencies": {
-    "@openpkg-ts/spec": "^0.24.0",
+    "@openpkg-ts/spec": "^0.26.0",
     "chalk": "^5.4.1",
     "commander": "^12.0.0",
     "tree-sitter-wasms": "^0.1.13",