@openpkg-ts/extract 0.15.0 → 0.16.1

package/dist/bin/tspec.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   extract
-} from "../shared/chunk-0bt6mcnx.js";
+} from "../shared/chunk-bgnmsw8f.js";
 
 // src/cli/spec.ts
 import * as fs from "node:fs";

package/dist/shared/{chunk-0bt6mcnx.js → chunk-bgnmsw8f.js}

@@ -661,12 +661,33 @@ function parseExamplesFromTags(tags) {
   }
   return examples;
 }
+function stripParamSeparator(text) {
+  if (!text)
+    return;
+  const stripped = text.replace(/^-\s*/, "").trim();
+  return stripped || undefined;
+}
+function stripTypeParamSeparator(text) {
+  if (!text)
+    return;
+  const match = text.match(/^\w+\s+-\s*(.*)$/s);
+  if (match) {
+    return match[1].trim() || undefined;
+  }
+  return text.trim() || undefined;
+}
 function getJSDocComment(node) {
   const jsDocTags = ts3.getJSDocTags(node);
-  const tags = jsDocTags.map((tag) => ({
-    name: tag.tagName.text,
-    text: typeof tag.comment === "string" ? tag.comment : ts3.getTextOfJSDocComment(tag.comment) ?? ""
-  }));
+  const tags = jsDocTags.map((tag) => {
+    const rawText = typeof tag.comment === "string" ? tag.comment : ts3.getTextOfJSDocComment(tag.comment) ?? "";
+    let text = rawText;
+    if (tag.tagName.text === "param") {
+      text = stripParamSeparator(rawText) ?? "";
+    } else if (tag.tagName.text === "typeParam") {
+      text = stripTypeParamSeparator(rawText) ?? "";
+    }
+    return { name: tag.tagName.text, text };
+  });
   const jsDocComments = node.jsDoc;
   let description;
   if (jsDocComments && jsDocComments.length > 0) {
@@ -694,7 +715,7 @@ function getParamDescription(propertyName, jsdocTags, inferredAlias) {
     const isMatch = tagParamName === propertyName || inferredAlias && tagParamName === `${inferredAlias}.${propertyName}` || tagParamName.endsWith(`.${propertyName}`);
     if (isMatch) {
       const comment = typeof tag.comment === "string" ? tag.comment : ts3.getTextOfJSDocComment(tag.comment);
-      return comment?.trim() || undefined;
+      return stripParamSeparator(comment);
     }
   }
   return;
@@ -1609,14 +1630,26 @@ async function extract(options) {
   }
   const meta = await getPackageMeta(entryFile, baseDir);
   const types = ctx.typeRegistry.getAll();
-  const danglingRefs = collectDanglingRefs(exports, types);
-  for (const ref of danglingRefs) {
-    diagnostics.push({
-      message: `Type '${ref}' is referenced but not defined in types[].`,
-      severity: "warning",
-      code: "DANGLING_REF",
-      suggestion: "The type may be from an external package. Check import paths."
-    });
+  const forgottenExports = collectForgottenExports(exports, types, program, sourceFile);
+  for (const forgotten of forgottenExports) {
+    const refSummary = forgotten.referencedBy.slice(0, 3).map((r) => `${r.exportName} (${r.location})`).join(", ");
+    const moreRefs = forgotten.referencedBy.length > 3 ? ` +${forgotten.referencedBy.length - 3} more` : "";
+    if (forgotten.isExternal) {
+      diagnostics.push({
+        message: `External type '${forgotten.name}' referenced by: ${refSummary}${moreRefs}`,
+        severity: "info",
+        code: "EXTERNAL_TYPE_REF",
+        suggestion: forgotten.definedIn ? `Type is from: ${forgotten.definedIn}` : "Type is from an external package"
+      });
+    } else {
+      diagnostics.push({
+        message: `Forgotten export: '${forgotten.name}' referenced by: ${refSummary}${moreRefs}`,
+        severity: "warning",
+        code: "FORGOTTEN_EXPORT",
+        suggestion: forgotten.fix ?? `Export this type from your public API`,
+        location: forgotten.definedIn ? { file: forgotten.definedIn } : undefined
+      });
+    }
   }
   const externalTypes = types.filter((t) => t.kind === "external");
   if (externalTypes.length > 0) {
@@ -1637,33 +1670,134 @@ async function extract(options) {
       timestamp: new Date().toISOString()
     }
   };
-  return { spec, diagnostics };
+  const internalForgotten = forgottenExports.filter((f) => !f.isExternal);
+  return {
+    spec,
+    diagnostics,
+    ...internalForgotten.length > 0 ? { forgottenExports: internalForgotten } : {}
+  };
 }
-function collectAllRefs(obj, refs) {
+function collectAllRefsWithContext(obj, refs, state) {
   if (obj === null || obj === undefined)
     return;
   if (Array.isArray(obj)) {
-    for (const item of obj) {
-      collectAllRefs(item, refs);
+    for (let i = 0;i < obj.length; i++) {
+      collectAllRefsWithContext(obj[i], refs, {
+        ...state,
+        path: [...state.path, `[${i}]`]
+      });
     }
     return;
   }
   if (typeof obj === "object") {
     const record = obj;
     if (typeof record.$ref === "string" && record.$ref.startsWith("#/types/")) {
-      refs.add(record.$ref.slice("#/types/".length));
+      const typeName = record.$ref.slice("#/types/".length);
+      const existing = refs.get(typeName) ?? [];
+      existing.push({
+        typeName,
+        exportName: state.exportName,
+        location: state.location,
+        path: state.path.join(".") || undefined
+      });
+      refs.set(typeName, existing);
+    }
+    for (const [key, value] of Object.entries(record)) {
+      let newLocation = state.location;
+      if (key === "returnType" || key === "returns")
+        newLocation = "return";
+      else if (key === "parameters" || key === "params")
+        newLocation = "parameter";
+      else if (key === "properties" || key === "members")
+        newLocation = "property";
+      else if (key === "extends" || key === "implements")
+        newLocation = "extends";
+      else if (key === "typeParameters" || key === "typeParams")
+        newLocation = "type-parameter";
+      collectAllRefsWithContext(value, refs, {
+        ...state,
+        location: newLocation,
+        path: [...state.path, key]
+      });
     }
-    for (const value of Object.values(record)) {
-      collectAllRefs(value, refs);
+  }
+}
+function findTypeDefinition(typeName, program, sourceFile) {
+  const checker = program.getTypeChecker();
+  const findInNode = (node) => {
+    if ((ts8.isInterfaceDeclaration(node) || ts8.isTypeAliasDeclaration(node) || ts8.isClassDeclaration(node) || ts8.isEnumDeclaration(node)) && node.name?.text === typeName) {
+      const sf = node.getSourceFile();
+      return sf.fileName;
     }
+    return ts8.forEachChild(node, findInNode);
+  };
+  const entryResult = findInNode(sourceFile);
+  if (entryResult)
+    return entryResult;
+  for (const sf of program.getSourceFiles()) {
+    if (sf.isDeclarationFile && !sf.fileName.includes("node_modules")) {
+      const result = findInNode(sf);
+      if (result)
+        return result;
+    }
+  }
+  const symbol = checker.resolveName(typeName, sourceFile, ts8.SymbolFlags.Type, false);
+  if (symbol?.declarations?.[0]) {
+    return symbol.declarations[0].getSourceFile().fileName;
   }
+  return;
+}
+function isExternalType2(definedIn) {
+  if (!definedIn)
+    return true;
+  return definedIn.includes("node_modules");
+}
+function hasInternalTag(typeName, program, sourceFile) {
+  const checker = program.getTypeChecker();
+  const symbol = checker.resolveName(typeName, sourceFile, ts8.SymbolFlags.Type, false);
+  if (!symbol)
+    return false;
+  const jsTags = symbol.getJsDocTags();
+  return jsTags.some((tag) => tag.name === "internal");
 }
-function collectDanglingRefs(exports, types) {
+function collectForgottenExports(exports, types, program, sourceFile) {
   const definedTypes = new Set(types.map((t) => t.id));
-  const referencedTypes = new Set;
-  collectAllRefs(exports, referencedTypes);
-  collectAllRefs(types, referencedTypes);
-  return Array.from(referencedTypes).filter((ref) => !definedTypes.has(ref) && !BUILTIN_TYPES2.has(ref) && !shouldSkipDanglingRef(ref));
+  const referencedTypes = new Map;
+  for (const exp of exports) {
+    collectAllRefsWithContext(exp, referencedTypes, {
+      exportName: exp.id || exp.name,
+      location: "property",
+      path: []
+    });
+  }
+  for (const type of types) {
+    collectAllRefsWithContext(type, referencedTypes, {
+      exportName: type.id,
+      location: "property",
+      path: []
+    });
+  }
+  const forgottenExports = [];
+  for (const [typeName, references] of referencedTypes) {
+    if (definedTypes.has(typeName))
+      continue;
+    if (BUILTIN_TYPES2.has(typeName))
+      continue;
+    if (shouldSkipDanglingRef(typeName))
+      continue;
+    if (hasInternalTag(typeName, program, sourceFile))
+      continue;
+    const definedIn = findTypeDefinition(typeName, program, sourceFile);
+    const isExternal = isExternalType2(definedIn);
+    forgottenExports.push({
+      name: typeName,
+      definedIn,
+      referencedBy: references,
+      isExternal,
+      fix: isExternal ? undefined : `export { ${typeName} } from '${definedIn ?? "./types"}'`
+    });
+  }
+  return forgottenExports;
 }
 function resolveExportTarget(symbol, checker) {
   let targetSymbol = symbol;

package/dist/src/index.d.ts

@@ -79,6 +79,7 @@ interface ExtractOptions {
 interface ExtractResult {
 	spec: OpenPkg;
 	diagnostics: Diagnostic[];
+	forgottenExports?: ForgottenExport[];
 }
 interface Diagnostic {
 	message: string;
@@ -91,6 +92,21 @@ interface Diagnostic {
 		column?: number;
 	};
 }
+/** Context tracking for type references in public API */
+interface TypeReference2 {
+	typeName: string;
+	exportName: string;
+	location: "return" | "parameter" | "property" | "extends" | "type-parameter";
+	path?: string;
+}
+/** Structured data for forgotten exports */
+interface ForgottenExport {
+	name: string;
+	definedIn?: string;
+	referencedBy: TypeReference2[];
+	isExternal: boolean;
+	fix?: string;
+}
 declare function extract(options: ExtractOptions): Promise<ExtractResult>;
 import ts4 from "typescript";
 interface ProgramOptions {
@@ -309,4 +325,4 @@ declare function findDiscriminatorProperty(unionTypes: ts12.Type[], checker: ts1
 import ts13 from "typescript";
 declare function isExported(node: ts13.Node): boolean;
 declare function getNodeName(node: ts13.Node): string | undefined;
-export { zodAdapter, withDescription, valibotAdapter, typeboxAdapter, serializeVariable, serializeTypeAlias, serializeInterface, serializeFunctionExport, serializeEnum, serializeClass, schemasAreEqual, schemaIsAny, resolveCompiledPath, registerReferencedTypes, registerAdapter, isTypeReference, isSymbolDeprecated, isStandardJSONSchema, isSchemaType, isPureRefSchema, isPrimitiveName, isExported, isBuiltinGeneric, isAnonymous, getSourceLocation, getParamDescription, getNonNullableType, getNodeName, getJSDocComment, findDiscriminatorProperty, findAdapter, extractTypeParameters, extractStandardSchemasFromProject, extractStandardSchemas, extractSchemaType, extractParameters, extract, deduplicateSchemas, createProgram, buildSchema, arktypeAdapter, TypeRegistry, StandardSchemaExtractionResult, StandardSchemaExtractionOutput, StandardJSONSchemaV1, SerializerContext, SchemaExtractionResult, SchemaAdapter, ProgramResult, ProgramOptions, ExtractStandardSchemasOptions, ExtractResult, ExtractOptions, Diagnostic, BUILTIN_TYPE_SCHEMAS };
+export { zodAdapter, withDescription, valibotAdapter, typeboxAdapter, serializeVariable, serializeTypeAlias, serializeInterface, serializeFunctionExport, serializeEnum, serializeClass, schemasAreEqual, schemaIsAny, resolveCompiledPath, registerReferencedTypes, registerAdapter, isTypeReference, isSymbolDeprecated, isStandardJSONSchema, isSchemaType, isPureRefSchema, isPrimitiveName, isExported, isBuiltinGeneric, isAnonymous, getSourceLocation, getParamDescription, getNonNullableType, getNodeName, getJSDocComment, findDiscriminatorProperty, findAdapter, extractTypeParameters, extractStandardSchemasFromProject, extractStandardSchemas, extractSchemaType, extractParameters, extract, deduplicateSchemas, createProgram, buildSchema, arktypeAdapter, TypeRegistry, TypeReference2 as TypeReference, StandardSchemaExtractionResult, StandardSchemaExtractionOutput, StandardJSONSchemaV1, SerializerContext, SchemaExtractionResult, SchemaAdapter, ProgramResult, ProgramOptions, ForgottenExport, ExtractStandardSchemasOptions, ExtractResult, ExtractOptions, Diagnostic, BUILTIN_TYPE_SCHEMAS };

package/dist/src/index.js

@@ -26,7 +26,7 @@ import {
   serializeTypeAlias,
   serializeVariable,
   withDescription
-} from "../shared/chunk-0bt6mcnx.js";
+} from "../shared/chunk-bgnmsw8f.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.15.0",
+  "version": "0.16.1",
   "description": "TypeScript export extraction to OpenPkg spec",
   "keywords": [
     "openpkg",