@openpkg-ts/sdk 0.54.8 → 0.54.9

package/dist/index.d.ts

@@ -1845,8 +1845,9 @@ import { SpecExport as SpecExport14 } from "@openpkg-ts/spec";
 import ts11 from "typescript";
 /**
 * @param declaredType - Written annotation of the variable holding `node`; when callable it supplies the signatures.
+* @param jsdocNode - Statement carrying the docs when that is not `node` (`() => {}`).
 */
-declare function serializeFunctionExport(node: ts11.FunctionDeclaration | ts11.ArrowFunction | ts11.FunctionExpression, ctx: SerializerContext, nameOverride?: string, declaredType?: ts11.TypeNode): SpecExport14 | null;
+declare function serializeFunctionExport(node: ts11.FunctionDeclaration | ts11.ArrowFunction | ts11.FunctionExpression, ctx: SerializerContext, nameOverride?: string, declaredType?: ts11.TypeNode, jsdocNode?: ts11.Node): SpecExport14 | null;
 import { SpecExport as SpecExport15 } from "@openpkg-ts/spec";
 import ts12 from "typescript";
 declare function serializeInterface(node: ts12.InterfaceDeclaration, ctx: SerializerContext): SpecExport15 | null;

package/dist/index.js

@@ -1830,6 +1830,18 @@ function declKey(symbol, checker) {
     return;
   return `${decl.getSourceFile().fileName}#${decl.getStart()}`;
 }
+function fileLabel(fileName) {
+  const base = path3.basename(fileName).replace(/(\.d)?\.[cm]?[tj]sx?$/, "");
+  return base === "index" ? path3.basename(path3.dirname(fileName)) || base : base;
+}
+function namespaceLabel(decl) {
+  const names = [];
+  for (let node = decl?.parent;node; node = node.parent) {
+    if (ts.isModuleDeclaration(node) && ts.isIdentifier(node.name))
+      names.unshift(node.name.text);
+  }
+  return names.length > 0 ? names.join(".") : undefined;
+}
 function resolveTypeId(symbol, ctx) {
   const cached = ctx.typeIds.get(symbol);
   if (cached)
@@ -1853,16 +1865,49 @@ function resolveTypeId(symbol, ctx) {
   const owner = ctx.idOwner.get(name);
   if (!owner || owner === key)
     return claim(name);
-  const file = symbol.declarations?.[0]?.getSourceFile().fileName ?? "";
-  const scoped = `${packageLabel(file, ctx.workspacePackages)}.${name}`;
-  const scopedOwner = ctx.idOwner.get(scoped);
-  if (!scopedOwner || scopedOwner === key)
-    return claim(scoped);
+  const decl = symbol.declarations?.[0];
+  const file = decl?.getSourceFile().fileName ?? "";
+  const pkg = packageLabel(file, ctx.workspacePackages);
+  const ownerFile = owner.includes("#") ? owner.slice(0, owner.lastIndexOf("#")) : "";
+  const scopes = pkg === packageLabel(ownerFile, ctx.workspacePackages) ? [] : [pkg];
+  const namespace = namespaceLabel(decl);
+  if (namespace)
+    scopes.push(namespace);
+  if (file)
+    scopes.push(fileLabel(file));
+  for (const scope of scopes) {
+    const scoped = `${scope}.${name}`;
+    const scopedOwner = ctx.idOwner.get(scoped);
+    if (!scopedOwner || scopedOwner === key)
+      return claim(scoped);
+  }
   let n = 2;
   while (ctx.idOwner.has(`${name}_${n}`))
     n++;
   return claim(`${name}_${n}`);
 }
+var EXPORTABLE_TYPE_FLAGS = ts.SymbolFlags.Interface | ts.SymbolFlags.TypeAlias | ts.SymbolFlags.Class | ts.SymbolFlags.RegularEnum | ts.SymbolFlags.ConstEnum;
+function claimExportedTypeIds(exportedSymbols, ctx) {
+  const renamed = [];
+  for (const exported of exportedSymbols) {
+    let target = exported;
+    if (exported.flags & ts.SymbolFlags.Alias) {
+      try {
+        target = ctx.typeChecker.getAliasedSymbol(exported);
+      } catch {
+        continue;
+      }
+    }
+    if (!(target.flags & EXPORTABLE_TYPE_FLAGS))
+      continue;
+    if (target.getName() === exported.getName())
+      resolveTypeId(target, ctx);
+    else
+      renamed.push(target);
+  }
+  for (const target of renamed)
+    resolveTypeId(target, ctx);
+}
 function typeRefId(type, ctx) {
   const symbol = type.aliasSymbol ?? type.getSymbol();
   if (!symbol)
@@ -2850,20 +2895,22 @@ function buildSchemaFromTypeNode(node, checker, ctx) {
       let refId = name;
       if (symbol && ctx) {
         try {
-          refId = namedRefId(checker.getDeclaredTypeOfSymbol(symbol), name, ctx);
+          refId = typeRefId(checker.getDeclaredTypeOfSymbol(symbol), ctx) || (symbol.flags & ts5.SymbolFlags.TypeAlias ? resolveTypeId(symbol, ctx) : name);
         } catch {
           refId = name;
         }
       }
       return withArgs({ $ref: `#/types/${refId}` });
     }
-    return { "x-ts-type": scrubImportQualifiers(node.getText()) };
+    return {
+      "x-ts-type": scrubImportQualifiers(node.getText().replace(/\s+/g, " "))
+    };
   }
   const t = checker.getTypeFromTypeNode(node);
   if (!(t.flags & ts5.TypeFlags.Any)) {
     return buildSchema(t, checker, ctx);
   }
-  return { "x-ts-type": scrubImportQualifiers(node.getText()) };
+  return { "x-ts-type": scrubImportQualifiers(node.getText().replace(/\s+/g, " ")) };
 }
 function stripUndefinedFromType(type, checker) {
   if (!type.isUnion())
@@ -3047,7 +3094,20 @@ function typeNodeDefersExpansion(node, checker, program) {
   const symbol = resolveAliasSymbol(raw, checker, undefined, program);
   return shouldDeferAlias(symbol);
 }
-function cheapTypeText(type, _checker, typeNode) {
+function isStaleTypeParameterNode(type, checker, typeNode) {
+  if (type.flags & ts5.TypeFlags.TypeParameter)
+    return false;
+  if (!ts5.isTypeReferenceNode(typeNode) || !ts5.isIdentifier(typeNode.typeName))
+    return false;
+  const symbol = checker.getSymbolAtLocation(typeNode.typeName);
+  return !!symbol && (symbol.flags & ts5.SymbolFlags.TypeParameter) !== 0;
+}
+function cheapTypeText(type, checker, typeNode) {
+  if (typeNode && isStaleTypeParameterNode(type, checker, typeNode)) {
+    const argument = type.aliasSymbol?.getName() ?? type.getSymbol()?.getName();
+    if (argument && !argument.startsWith("__") && !isBuiltinGeneric(argument))
+      return argument;
+  }
   if (typeNode) {
     try {
       const text = scrubImportQualifiers(typeNode.getText().replace(/\s+/g, " ").trim());
@@ -3338,10 +3398,10 @@ function buildSchema(type, checker, ctx, typeNode) {
   const schema = buildSchemaInternal(type, checker, ctx, typeNode);
   return ensureNonEmptySchema(schema, type, checker);
 }
-function buildMaxDepthSchema(type, checker, typeNode) {
+function buildMaxDepthSchema(type, checker, typeNode, ctx) {
   if (type.flags & ts5.TypeFlags.Any) {
     if (typeNode)
-      return buildSchemaFromTypeNode(typeNode, checker);
+      return buildSchemaFromTypeNode(typeNode, checker, ctx);
     return { "x-ts-type": checker.typeToString(type) };
   }
   if (type.flags & ts5.TypeFlags.TypeParameter && !isFluentThisType(type)) {
@@ -3354,7 +3414,7 @@ function buildMaxDepthSchema(type, checker, typeNode) {
       return builtinSchema(name);
     }
     if (!name.startsWith("__") && !isPrimitiveName(name)) {
-      return { $ref: `#/types/${name}` };
+      return { $ref: `#/types/${ctx ? resolveTypeId(symbol, ctx) : name}` };
     }
   }
   if (type.flags & ts5.TypeFlags.String)
@@ -3377,18 +3437,18 @@ function buildMaxDepthSchema(type, checker, typeNode) {
     };
   }
   if (type.isUnion()) {
-    const schemas = type.types.map((t) => buildMaxDepthSchema(t, checker));
+    const schemas = type.types.map((t) => buildMaxDepthSchema(t, checker, undefined, ctx));
     return { anyOf: schemas };
   }
   if (type.isIntersection()) {
-    const schemas = type.types.map((t) => buildMaxDepthSchema(t, checker));
+    const schemas = type.types.map((t) => buildMaxDepthSchema(t, checker, undefined, ctx));
     return { allOf: schemas };
   }
   return { type: checker.typeToString(type) };
 }
 function buildSchemaInternal(type, checker, ctx, typeNode) {
   if (isAtMaxDepth(ctx)) {
-    return buildMaxDepthSchema(type, checker, typeNode);
+    return buildMaxDepthSchema(type, checker, typeNode, ctx);
   }
   if (ctx) {
     ctx.schemaOps += 1;
@@ -4934,8 +4994,18 @@ function serializeConstructor(node, ctx) {
     return null;
   return serializeConstructorSignature(node, sig, ctx);
 }
+function serializeConstructSignatures(sigs, ctx) {
+  return sigs.map((sig, index) => {
+    const typeParameters = extractTypeParametersFromSignature(sig, ctx.typeChecker);
+    return {
+      ...serializeConstructorSignature(sig.getDeclaration(), sig, ctx),
+      ...typeParameters ? { typeParameters } : {},
+      ...sigs.length > 1 ? { overloadIndex: index } : {}
+    };
+  });
+}
 function serializeConstructorSignature(node, sig, ctx) {
-  const { description, tags, examples, inlineTags } = getJSDocComment(node);
+  const { description, tags, examples, inlineTags } = node ? getJSDocComment(node) : { description: undefined, tags: [], examples: [], inlineTags: undefined };
   const params = extractParameters(sig, ctx);
   return {
     description,
@@ -5222,12 +5292,12 @@ function signaturesFromDeclaredType(typeNode, ctx) {
   const callSignatures = ctx.typeChecker.getTypeFromTypeNode(inner).getCallSignatures();
   return callSignatures.length > 0 ? signaturesFromChecker(callSignatures, ctx) : undefined;
 }
-function serializeFunctionExport(node, ctx, nameOverride, declaredType) {
+function serializeFunctionExport(node, ctx, nameOverride, declaredType, jsdocNode) {
   const symbol = ctx.typeChecker.getSymbolAtLocation(node.name ?? node);
   const name = nameOverride ?? symbol?.getName() ?? node.name?.getText() ?? anonymousDefaultName(node);
   if (!name)
     return null;
-  const { description, tags, examples, source, deprecated, deprecationReason, inlineTags } = extractExportMetadata(node, symbol, ctx.typeChecker);
+  const { description, tags, examples, source, deprecated, deprecationReason, inlineTags } = extractExportMetadata(node, symbol, ctx.typeChecker, jsdocNode);
   const declaredFn = declaredType && unwrapParens(declaredType);
   const typeParameters = extractTypeParameters(declaredFn && ts11.isFunctionTypeNode(declaredFn) ? declaredFn : node, ctx.typeChecker);
   const signatures = (declaredType && signaturesFromDeclaredType(declaredType, ctx)) ?? (anySignatureDefers(node, ctx) ? signaturesFromAst(functionSignatureDecls(node, ctx), ctx) : signaturesFromChecker(ctx.typeChecker.getTypeAtLocation(node).getCallSignatures(), ctx));
@@ -5847,12 +5917,17 @@ function serializeVariable(node, statement, ctx) {
   const name = symbol?.getName() ?? node.name.getText();
   if (!name)
     return null;
-  const { description, tags, examples, source, deprecated, deprecationReason, inlineTags } = extractExportMetadata(node, symbol, ctx.typeChecker, statement);
-  const type = ctx.typeChecker.getTypeAtLocation(node);
+  return serializeValue(name, node, symbol, statement, ctx.typeChecker.getTypeAtLocation(node), ts15.isVariableDeclaration(node) ? node.type : undefined, ctx);
+}
+function serializeDefaultExpression(node, symbol, type, ctx) {
+  return serializeValue(symbol.getName(), node.expression, symbol, node, type, undefined, ctx);
+}
+function serializeValue(name, node, symbol, jsdocNode, type, typeNode, ctx) {
+  const { description, tags, examples, source, deprecated, deprecationReason, inlineTags } = extractExportMetadata(node, symbol, ctx.typeChecker, jsdocNode);
   const schemaExtraction = extractSchemaType(type, ctx.typeChecker);
   const typeToSerialize = schemaExtraction?.outputType ?? type;
   registerReferencedTypes(typeToSerialize, ctx);
-  const schema = buildSchema(typeToSerialize, ctx.typeChecker, ctx, ts15.isVariableDeclaration(node) ? node.type : undefined);
+  const schema = buildSchema(typeToSerialize, ctx.typeChecker, ctx, typeNode);
   const flags = schemaExtraction ? {
     schemaLibrary: schemaExtraction.adapter.id,
     ...schemaExtraction.inputType && schemaExtraction.inputType !== schemaExtraction.outputType ? { hasTransform: true } : {}
@@ -6438,6 +6513,7 @@ async function getExport(options) {
   }
   const ctx = createContext(program, sourceFile, { maxTypeDepth });
   ctx.exportedIds = exportedIds;
+  claimExportedTypeIds(exportedSymbols, ctx);
   try {
     const originalDecls = targetSymbol.declarations ?? [];
     const isNamespaceExportDecl = originalDecls.some((d) => ts16.isNamespaceExport(d) || ts16.isNamespaceImport(d));
@@ -7611,7 +7687,7 @@ function expandReachableTypes(exportedSymbols, ctx, opts) {
     const symbol = type.aliasSymbol ?? type.getSymbol();
     const named = !!symbol && !symbol.getName().startsWith("__");
     const allowed = !named || !symbol || symbolAllowed(symbol);
-    if (named && allowed && symbol && !ctx.exportedIds.has(symbol.getName())) {
+    if (named && allowed && symbol && !isExportedType(symbol)) {
       ctx.typeRegistry.registerType(type, ctx);
       const name = symbol.getName();
       if (!symbolByName.has(name)) {
@@ -7659,6 +7735,12 @@ function expandReachableTypes(exportedSymbols, ctx, opts) {
     }
   };
   const TYPE_SYMBOL_FLAGS = ts20.SymbolFlags.Interface | ts20.SymbolFlags.TypeAlias | ts20.SymbolFlags.Class | ts20.SymbolFlags.RegularEnum | ts20.SymbolFlags.ConstEnum;
+  const isExportedType = (symbol) => {
+    const name = symbol.getName();
+    if (!ctx.exportedIds.has(name))
+      return false;
+    return !(symbol.flags & TYPE_SYMBOL_FLAGS) || resolveTypeId(symbol, ctx) === name;
+  };
   const visitedSymbols = new Set;
   const symbolKind = (symbol) => {
     if (symbol.flags & ts20.SymbolFlags.Interface)
@@ -7673,6 +7755,7 @@ function expandReachableTypes(exportedSymbols, ctx, opts) {
     const resolved = resolveAliasSymbol(symbol, checker, undefined, ctx.program);
     return resolved;
   };
+  const writtenWhenAny = (symbol, declared) => declared.flags & ts20.TypeFlags.Any ? symbol.declarations?.find(ts20.isTypeAliasDeclaration)?.type : undefined;
   const symbolByName = new Map;
   const registerTypeSymbol = (symbol) => {
     const name = symbol.getName();
@@ -7682,7 +7765,7 @@ function expandReachableTypes(exportedSymbols, ctx, opts) {
       return;
     if (!symbolAllowed(symbol))
       return;
-    if (ctx.exportedIds.has(name)) {
+    if (isExportedType(symbol)) {
       walkDeclarations(symbol);
       return;
     }
@@ -7698,7 +7781,7 @@ function expandReachableTypes(exportedSymbols, ctx, opts) {
         id,
         name,
         kind: symbolKind(symbol),
-        schema: ensureNonEmptySchema(buildSchema(declared, checker, ctx), declared, checker)
+        schema: ensureNonEmptySchema(buildSchema(declared, checker, ctx, writtenWhenAny(symbol, declared)), declared, checker)
       });
     }
     symbolByName.set(name, symbol);
@@ -8080,6 +8163,7 @@ async function extract(options) {
       workspacePackages: result.workspacePackages ?? new Map
     });
     ctx.exportedIds = exportedIds;
+    claimExportedTypeIds(exportedSymbols, ctx);
     const filteredSymbols = exportedSymbols.filter((s) => shouldIncludeExport(s.getName(), only, ignore));
     const total = filteredSymbols.length;
     for (let i = 0;i < filteredSymbols.length; i++) {
@@ -8149,8 +8233,13 @@ async function extract(options) {
         }
         const exp = serializeDeclaration2(declaration, symbol, exportName, ctx, isTypeOnly);
         if (exp) {
-          if (!exp.members && isValueDeclaration(declaration) && hasTypeSide(targetSymbol)) {
-            mergedTypeSides.push({ index: exports.length, symbol: targetSymbol });
+          const typeSide = mergedTypeSideOf(exp, declaration, targetSymbol, ctx);
+          if (typeSide) {
+            mergedTypeSides.push({
+              index: exports.length,
+              symbol: typeSide,
+              ontoClass: ts21.isClassDeclaration(declaration)
+            });
           }
           exports.push(exp);
           tracker.status = "success";
@@ -8170,8 +8259,8 @@ async function extract(options) {
         });
       }
     }
-    for (const { index, symbol } of mergedTypeSides) {
-      exports[index] = withMergedTypeSide(exports[index], symbol, ctx);
+    for (const { index, symbol, ontoClass } of mergedTypeSides) {
+      exports[index] = withMergedTypeSide(exports[index], symbol, ctx, ontoClass);
     }
     const verification = buildVerificationSummary(exportedSymbols.length, exports.length, exportTracker);
     const meta = await getPackageMeta(entryFile, baseDir);
@@ -8354,21 +8443,18 @@ function serializeDeclaration2(declaration, exportSymbol, exportName, ctx, isTyp
         result = serializeVariable(declaration, varStatement, ctx);
         if (result?.kind === "variable") {
           const type = ctx.typeChecker.getTypeAtLocation(declaration);
-          if (type.getConstructSignatures().length > 0) {
-            result = { ...result, kind: "class" };
-          } else {
-            const callSigs = callSignaturesForVariable(declaration, ctx);
-            if (callSigs.length > 0) {
-              result = {
-                ...result,
-                kind: "function",
-                signatures: buildSignatures(callSigs, ctx.typeChecker, ctx)
-              };
-            }
-          }
+          result = withCallableKind(result, type, callSignaturesForVariable(declaration, ctx), ctx);
         }
       }
     }
+  } else if (ts21.isExportAssignment(declaration) && !declaration.isExportEquals) {
+    const expression = skipOuterExpressions(declaration.expression);
+    if (ts21.isArrowFunction(expression) || ts21.isFunctionExpression(expression)) {
+      result = serializeFunctionExport(expression, ctx, exportName, undefined, declaration);
+    } else {
+      const type = ctx.typeChecker.getTypeOfSymbol(exportSymbol);
+      result = withCallableKind(serializeDefaultExpression(declaration, exportSymbol, type, ctx), type, type.getCallSignatures(), ctx);
+    }
   } else if (ts21.isNamespaceExport(declaration) || ts21.isModuleDeclaration(declaration) || ts21.isNamespaceImport(declaration) || ts21.isSourceFile(declaration)) {
     try {
       result = serializeNamespaceExport(exportSymbol, exportName, ctx);
@@ -8559,6 +8645,30 @@ function variableStatementOf(declaration) {
   const statement = node.parent?.parent;
   return statement && ts21.isVariableStatement(statement) ? statement : undefined;
 }
+function skipOuterExpressions(expression) {
+  let node = expression;
+  while (ts21.isParenthesizedExpression(node) || ts21.isAsExpression(node) || ts21.isSatisfiesExpression(node) || ts21.isTypeAssertionExpression(node) || ts21.isNonNullExpression(node)) {
+    node = node.expression;
+  }
+  return node;
+}
+function withCallableKind(entry, type, callSigs, ctx) {
+  const constructSigs = type.getConstructSignatures();
+  if (constructSigs.length > 0) {
+    return {
+      ...entry,
+      kind: "class",
+      signatures: serializeConstructSignatures(constructSigs, ctx)
+    };
+  }
+  if (callSigs.length === 0)
+    return entry;
+  return {
+    ...entry,
+    kind: "function",
+    signatures: buildSignatures(callSigs, ctx.typeChecker, ctx)
+  };
+}
 function callSignaturesForVariable(declaration, ctx) {
   const checker = ctx.typeChecker;
   if (ts21.isVariableDeclaration(declaration) && declaration.type && ts21.isTypeReferenceNode(declaration.type)) {
@@ -8609,15 +8719,35 @@ function isValueDeclaration(declaration) {
 function hasTypeSide(symbol) {
   return (symbol.flags & (ts21.SymbolFlags.Interface | ts21.SymbolFlags.TypeAlias)) !== 0;
 }
-function withMergedTypeSide(entry, symbol, ctx) {
+function mergedTypeSideOf(exp, declaration, symbol, ctx) {
+  if (ts21.isClassDeclaration(declaration)) {
+    return symbol.flags & ts21.SymbolFlags.Interface ? symbol : undefined;
+  }
+  if (exp.members || !isValueDeclaration(declaration))
+    return;
+  if (hasTypeSide(symbol))
+    return symbol;
+  if (exp.kind !== "class")
+    return;
+  const [construct] = ctx.typeChecker.getTypeAtLocation(declaration).getConstructSignatures();
+  const instance = construct?.getReturnType();
+  const constructed = instance && (instance.aliasSymbol ?? instance.getSymbol());
+  if (!constructed || !hasTypeSide(constructed))
+    return;
+  if (ctx.shouldExpandExternal && !ctx.shouldExpandExternal(constructed))
+    return;
+  return constructed;
+}
+function withMergedTypeSide(entry, symbol, ctx, ontoClass) {
   const typeSide = serializeMergedTypeSide(symbol, ctx);
   if (!typeSide)
     return entry;
   const { members, description, tags, ...instanceType } = typeSide;
+  const own = new Set(entry.members?.map((m) => m.name));
   return {
     ...entry,
-    members,
-    ...entry.kind === "class" ? instanceType : {},
+    members: [...entry.members ?? [], ...(members ?? []).filter((m) => !own.has(m.name))],
+    ...entry.kind === "class" && !ontoClass ? instanceType : {},
     ...entry.description ? {} : { description, tags: [...entry.tags ?? [], ...tags ?? []] }
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpkg-ts/sdk",
-  "version": "0.54.8",
+  "version": "0.54.9",
   "description": "TypeScript API extraction SDK - programmatic primitives for OpenPkg specs",
   "keywords": [
     "openpkg",
@@ -43,7 +43,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@openpkg-ts/spec": "^0.54.8",
+    "@openpkg-ts/spec": "^0.54.9",
     "picomatch": "4.0.3",
     "typescript": "^5.0.0 || ^6.0.0"
   },