@openpkg-ts/sdk 0.39.0 → 0.41.0

package/README.md

@@ -1,6 +1,6 @@
 # @openpkg-ts/sdk
 
-Programmatic SDK for TypeScript API extraction and documentation generation.
+Extract [OpenPkg](https://openpkg.dev) documents from TypeScript source and generate documentation. The SDK of [openpkg-ts](https://github.com/ryanwaits/openpkg-ts), the TypeScript reference implementation of the OpenPkg standard.
 
 ## Install
 

package/dist/index.d.ts

@@ -1675,6 +1675,14 @@ declare function ensureNonEmptySchema(schema: SpecSchema2, type: ts15.Type, chec
 */
 declare function buildSchema(type: ts15.Type, checker: ts15.TypeChecker, ctx?: SerializerContext): SpecSchema2;
 /**
+* Build schema for function types
+*/
+declare function buildFunctionSchema(callSignatures: readonly ts15.Signature[], checker: ts15.TypeChecker, ctx: SerializerContext | undefined): SpecSchema2;
+/**
+* Build schema for object types with properties
+*/
+declare function buildObjectSchema(properties: ts15.Symbol[], checker: ts15.TypeChecker, ctx: SerializerContext | undefined, originalType?: ts15.Type): SpecSchema2;
+/**
 * Check if a schema is a pure $ref (only has $ref property)
 */
 declare function isPureRefSchema(schema: SpecSchema2): schema is {
@@ -1767,4 +1775,4 @@ declare function normalizeMembers(members: SpecMember3[], options?: NormalizeOpt
 import ts16 from "typescript";
 declare function isExported(node: ts16.Node): boolean;
 declare function getNodeName(node: ts16.Node): string | undefined;
-export { zodAdapter, withDescription2 as withDescription, valibotAdapter, typeboxAdapter, toSearchIndexJSON, toSearchIndex2 as toSearchIndex, toPagefindRecords2 as toPagefindRecords, toNavigation2 as toNavigation, toMarkdown2 as toMarkdown, toJSONString, toJSON2 as toJSON, toHTML2 as toHTML, toFumadocsMetaJSON, toDocusaurusSidebarJS, toAlgoliaRecords2 as toAlgoliaRecords, sortByName, serializeVariable, serializeTypeAlias, serializeInterface, serializeFunctionExport, serializeEnum, serializeClass, schemasAreEqual, schemaIsAny, resolveTypeRef, resolveExportTarget, resolveCompiledPath, registerReferencedTypes, registerAdapter, recommendSemverBump, query, normalizeType, normalizeSchema, normalizeMembers, normalizeExport, mergeConfig, loadSpec, loadConfig, listExports, isTypeReference, isTypeOnlyExport, isSymbolDeprecated, isStandardJSONSchema, isSchemaType, isPureRefSchema, isProperty, isPrimitiveName, isMethod, isExported, isBuiltinGeneric, isAnonymous, hasDeprecatedTag, groupByVisibility, getTypeOrigin, getSourceLocation, getProperties, getParamDescription, getNonNullableType, getNodeName, getMethods, getMemberBadges, getJSDocComment, getExportKind, getExport2 as getExport, getDeprecationMessage, toMarkdown2 as generateDocs, formatTypeParameters, formatSchema, formatReturnType, formatParameters, formatMappedType, formatConditionalType, formatBadges, findMissingParamDocs, findDiscriminatorProperty, findAdapter, filterSpec, extractTypeParameters, extractStandardSchemasFromTs, extractStandardSchemasFromProject, extractStandardSchemas, extractSpec, extractSchemaType, extractParameters, extract, exportToMarkdown, ensureNonEmptySchema, diffSpec2 as diffSpecs, diffSpec, detectTsRuntime, deduplicateSchemas, createProgram, createDocs, categorizeBreakingChanges, calculateNextVersion, buildSignatureString, buildSchema, arktypeAdapter, analyzeSpec, TypeRegistry, TypeReference2 as TypeReference, TsRuntime, StandardSchemaExtractionResult, StandardSchemaExtractionOutput, StandardJSONSchemaV1, StandardJSONSchemaTarget, StandardJSONSchemaOptions, SpecMappedType, SpecDiff, SpecDiagnostics, SpecConditionalType, SkippedExportDetail, SimplifiedSpec, SimplifiedSignature, SimplifiedReturn, SimplifiedParameter, SimplifiedMember, SimplifiedExport, SimplifiedExample, SerializerContext, SemverRecommendation, SemverBump, SearchRecord, SearchOptions, SearchIndex, SchemaExtractionResult, SchemaAdapter, STRING_PROTOTYPE_METHODS, QueryBuilder, ProjectExtractionOutput, ProjectExtractionInfo, ProgramResult, ProgramOptions, PagefindRecord, PRIMITIVES, OpenpkgConfig, NormalizeOptions, NavOptions, NavItem, NavGroup, NavFormat, NUMBER_PROTOTYPE_METHODS, MemberChangeInfo, MarkdownOptions, LoadOptions, ListExportsResult, ListExportsOptions, JSONSchema, JSONOptions, HTMLOptions, GroupBy, GetExportResult, GetExportOptions, GenericNav, FumadocsMetaItem, FumadocsMeta, FormatSchemaOptions, ForgottenExport, FilterResult, FilterCriteria, ExtractionWarningCode, ExtractionWarning, ExtractStandardSchemasOptions, ExtractResult, ExtractOptions, ExtractFromProjectOptions, ExternalsConfig, ExportVerification, ExportTracker, ExportMarkdownOptions, ExportItem, DocusaurusSidebarItem, DocusaurusSidebar, DocsInstance, DiagnosticItem, Diagnostic, CategorizedBreaking, CacheManagerOptions, CacheManager, CONFIG_FILENAME, BreakingSeverity, BUILTIN_TYPE_SCHEMAS, AlgoliaRecord, ARRAY_PROTOTYPE_METHODS };
+export { zodAdapter, withDescription2 as withDescription, valibotAdapter, typeboxAdapter, toSearchIndexJSON, toSearchIndex2 as toSearchIndex, toPagefindRecords2 as toPagefindRecords, toNavigation2 as toNavigation, toMarkdown2 as toMarkdown, toJSONString, toJSON2 as toJSON, toHTML2 as toHTML, toFumadocsMetaJSON, toDocusaurusSidebarJS, toAlgoliaRecords2 as toAlgoliaRecords, sortByName, serializeVariable, serializeTypeAlias, serializeInterface, serializeFunctionExport, serializeEnum, serializeClass, schemasAreEqual, schemaIsAny, resolveTypeRef, resolveExportTarget, resolveCompiledPath, registerReferencedTypes, registerAdapter, recommendSemverBump, query, normalizeType, normalizeSchema, normalizeMembers, normalizeExport, mergeConfig, loadSpec, loadConfig, listExports, isTypeReference, isTypeOnlyExport, isSymbolDeprecated, isStandardJSONSchema, isSchemaType, isPureRefSchema, isProperty, isPrimitiveName, isMethod, isExported, isBuiltinGeneric, isAnonymous, hasDeprecatedTag, groupByVisibility, getTypeOrigin, getSourceLocation, getProperties, getParamDescription, getNonNullableType, getNodeName, getMethods, getMemberBadges, getJSDocComment, getExportKind, getExport2 as getExport, getDeprecationMessage, toMarkdown2 as generateDocs, formatTypeParameters, formatSchema, formatReturnType, formatParameters, formatMappedType, formatConditionalType, formatBadges, findMissingParamDocs, findDiscriminatorProperty, findAdapter, filterSpec, extractTypeParameters, extractStandardSchemasFromTs, extractStandardSchemasFromProject, extractStandardSchemas, extractSpec, extractSchemaType, extractParameters, extract, exportToMarkdown, ensureNonEmptySchema, diffSpec2 as diffSpecs, diffSpec, detectTsRuntime, deduplicateSchemas, createProgram, createDocs, categorizeBreakingChanges, calculateNextVersion, buildSignatureString, buildSchema, buildObjectSchema, buildFunctionSchema, arktypeAdapter, analyzeSpec, TypeRegistry, TypeReference2 as TypeReference, TsRuntime, StandardSchemaExtractionResult, StandardSchemaExtractionOutput, StandardJSONSchemaV1, StandardJSONSchemaTarget, StandardJSONSchemaOptions, SpecMappedType, SpecDiff, SpecDiagnostics, SpecConditionalType, SkippedExportDetail, SimplifiedSpec, SimplifiedSignature, SimplifiedReturn, SimplifiedParameter, SimplifiedMember, SimplifiedExport, SimplifiedExample, SerializerContext, SemverRecommendation, SemverBump, SearchRecord, SearchOptions, SearchIndex, SchemaExtractionResult, SchemaAdapter, STRING_PROTOTYPE_METHODS, QueryBuilder, ProjectExtractionOutput, ProjectExtractionInfo, ProgramResult, ProgramOptions, PagefindRecord, PRIMITIVES, OpenpkgConfig, NormalizeOptions, NavOptions, NavItem, NavGroup, NavFormat, NUMBER_PROTOTYPE_METHODS, MemberChangeInfo, MarkdownOptions, LoadOptions, ListExportsResult, ListExportsOptions, JSONSchema, JSONOptions, HTMLOptions, GroupBy, GetExportResult, GetExportOptions, GenericNav, FumadocsMetaItem, FumadocsMeta, FormatSchemaOptions, ForgottenExport, FilterResult, FilterCriteria, ExtractionWarningCode, ExtractionWarning, ExtractStandardSchemasOptions, ExtractResult, ExtractOptions, ExtractFromProjectOptions, ExternalsConfig, ExportVerification, ExportTracker, ExportMarkdownOptions, ExportItem, DocusaurusSidebarItem, DocusaurusSidebar, DocsInstance, DiagnosticItem, Diagnostic, CategorizedBreaking, CacheManagerOptions, CacheManager, CONFIG_FILENAME, BreakingSeverity, BUILTIN_TYPE_SCHEMAS, AlgoliaRecord, ARRAY_PROTOTYPE_METHODS };

package/dist/index.js

@@ -1636,7 +1636,8 @@ var DEFAULT_COMPILER_OPTIONS = {
   module: ts2.ModuleKind.CommonJS,
   lib: ["lib.es2021.d.ts"],
   declaration: true,
-  moduleResolution: ts2.ModuleResolutionKind.NodeJs
+  moduleResolution: ts2.ModuleResolutionKind.NodeJs,
+  strict: true
 };
 function resolveWorkspaceEntry(pkgDir) {
   const candidates = [
@@ -3816,8 +3817,14 @@ function serializeTypeAlias(node, ctx) {
   const type = ctx.typeChecker.getTypeAtLocation(node);
   registerReferencedTypes(type, ctx);
   let schema;
+  let members;
   if (ts10.isIntersectionTypeNode(node.type)) {
     schema = buildIntersectionSchemaFromNode(node.type, ctx);
+  } else if (isInlineFunctionAlias(node.type) && type.getCallSignatures().length > 0) {
+    schema = buildFunctionSchema(type.getCallSignatures(), ctx.typeChecker, ctx);
+  } else if ((ts10.isMappedTypeNode(node.type) || ts10.isConditionalTypeNode(node.type)) && type.getProperties().length > 0 && type.getCallSignatures().length === 0) {
+    schema = buildObjectSchema(type.getProperties(), ctx.typeChecker, ctx, type);
+    members = serializeResolvedMembers(type, node, ctx);
   } else {
     schema = buildSchema(type, ctx.typeChecker, ctx);
   }
@@ -3830,10 +3837,95 @@ function serializeTypeAlias(node, ctx) {
     source,
     typeParameters,
     schema,
+    ...members && members.length > 0 ? { members } : {},
     ...deprecated ? { deprecated: true, deprecationReason } : {},
     ...examples.length > 0 ? { examples } : {}
   };
 }
+function isInlineFunctionAlias(typeNode) {
+  return ts10.isFunctionTypeNode(typeNode) || ts10.isTypeLiteralNode(typeNode) && typeNode.members.some(ts10.isCallSignatureDeclaration);
+}
+function buildConditionalArmDocs(typeNode, checker) {
+  const docs = new Map;
+  if (!ts10.isMappedTypeNode(typeNode) || !typeNode.type)
+    return docs;
+  const literalKeys = (extendsType) => {
+    const keys = [];
+    const visit = (n) => {
+      if (ts10.isUnionTypeNode(n)) {
+        for (const member of n.types)
+          visit(member);
+      } else if (ts10.isLiteralTypeNode(n) && ts10.isStringLiteral(n.literal)) {
+        keys.push(n.literal.text);
+      }
+    };
+    visit(extendsType);
+    return keys;
+  };
+  const armDoc = (armType) => {
+    if (!ts10.isTypeReferenceNode(armType))
+      return;
+    const symbol = checker.getSymbolAtLocation(armType.typeName);
+    if (!symbol)
+      return;
+    const target = symbol.flags & ts10.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
+    const { deprecated, reason } = isSymbolDeprecated(target);
+    const targetDecl = target.getDeclarations()?.[0];
+    const description = targetDecl ? getJSDocComment(targetDecl, target, checker).description : undefined;
+    if (!deprecated && !description)
+      return;
+    return { deprecated, deprecationReason: reason, description };
+  };
+  let current = typeNode.type;
+  while (current && ts10.isConditionalTypeNode(current)) {
+    const doc = armDoc(current.trueType);
+    if (doc) {
+      for (const key of literalKeys(current.extendsType)) {
+        if (!docs.has(key))
+          docs.set(key, doc);
+      }
+    }
+    current = current.falseType;
+  }
+  return docs;
+}
+function serializeResolvedMembers(type, node, ctx) {
+  const { typeChecker: checker } = ctx;
+  const members = [];
+  const armDocs = buildConditionalArmDocs(node.type, checker);
+  for (const prop of type.getProperties()) {
+    const decl = prop.getDeclarations()?.[0] ?? node;
+    const propType = checker.getTypeOfSymbolAtLocation(prop, decl);
+    registerReferencedTypes(propType, ctx);
+    const callSigs = propType.getCallSignatures();
+    const kind = callSigs.length > 0 ? "method" : "property";
+    let { description, tags } = getJSDocComment(decl, prop, checker);
+    let { deprecated, reason: deprecationReason } = isSymbolDeprecated(prop);
+    const arm = armDocs.get(prop.getName());
+    if (arm) {
+      if (!deprecated && arm.deprecated) {
+        deprecated = true;
+        deprecationReason = arm.deprecationReason;
+      }
+      if (!description)
+        description = arm.description;
+    }
+    const armAlias = propType.aliasSymbol;
+    if (!deprecated && armAlias) {
+      ({ deprecated, reason: deprecationReason } = isSymbolDeprecated(armAlias));
+    }
+    members.push({
+      name: prop.getName(),
+      kind,
+      description,
+      tags: tags.length > 0 ? tags : undefined,
+      schema: kind === "property" ? buildSchema(propType, checker, ctx) : undefined,
+      signatures: kind === "method" ? buildSignatures(callSigs, checker, ctx) : undefined,
+      ...deprecated ? { deprecated: true, deprecationReason } : {}
+    });
+  }
+  return members;
+}
 
 // src/schema/registry.ts
 function isTypeReference(type) {
@@ -6556,6 +6648,8 @@ export {
   calculateNextVersion,
   buildSignatureString,
   buildSchema,
+  buildObjectSchema,
+  buildFunctionSchema,
   arktypeAdapter,
   analyzeSpec,
   TypeRegistry,

package/package.json

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