@openpkg-ts/extract 0.24.1 → 0.26.0

package/dist/bin/tspec.js

@@ -3,7 +3,7 @@ import {
   detectTsRuntime,
   extract,
   resolveCompiledPath
-} from "../shared/chunk-2fes3xf8.js";
+} from "../shared/chunk-xamjhe27.js";
 
 // src/cli/spec.ts
 import * as fs from "node:fs";
@@ -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}` : "";

package/dist/shared/{chunk-2fes3xf8.js → chunk-xamjhe27.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);
@@ -3112,6 +3120,28 @@ function clearTypeDefinitionCache() {
   typeDefinitionCache = null;
   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 };
+}
 var BUILTIN_TYPES2 = new Set([
   "Array",
   "ArrayBuffer",
@@ -3206,7 +3236,9 @@ async function extract(options) {
     resolveExternalTypes,
     includeSchema,
     only,
-    ignore
+    ignore,
+    onProgress,
+    isDtsSource
   } = options;
   const diagnostics = [];
   let exports = [];
@@ -3214,7 +3246,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" }]
     };
   }
@@ -3222,7 +3254,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" }]
     };
   }
@@ -3237,10 +3269,15 @@ async function extract(options) {
     resolveExternalTypes
   });
   ctx.exportedIds = exportedIds;
-  for (const symbol of exportedSymbols) {
+  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();
-    if (!shouldIncludeExport(exportName, only, ignore))
-      continue;
+    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)
@@ -3326,15 +3363,21 @@ 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;
   return {
     spec,
     diagnostics,
     ...internalForgotten.length > 0 ? { forgottenExports: internalForgotten } : {},
-    ...runtimeMetadata ? { runtimeSchemas: runtimeMetadata } : {}
+    ...runtimeMetadata ? { runtimeSchemas: runtimeMetadata } : {},
+    ...degradedMode ? { degradedMode } : {}
   };
 }
 function collectAllRefsWithContext(obj, refs, state) {
@@ -3592,7 +3635,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,
@@ -3686,7 +3729,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,
@@ -3694,7 +3737,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[];
@@ -237,6 +237,10 @@ interface ExtractOptions {
 	only?: string[];
 	/** Ignore these exports (supports * wildcards) */
 	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;
@@ -255,6 +259,15 @@ 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;
+		};
+	};
 }
 interface Diagnostic {
 	message: string;

package/dist/src/index.js

@@ -48,7 +48,7 @@ import {
   valibotAdapter,
   withDescription,
   zodAdapter
-} from "../shared/chunk-2fes3xf8.js";
+} from "../shared/chunk-xamjhe27.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.24.1",
+  "version": "0.26.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",