@openpkg-ts/sdk 0.48.1 → 0.49.0

package/dist/index.d.ts

@@ -1839,6 +1839,21 @@ declare function scrubImportQualifiers(text: string): string;
 */
 declare function renderTypeText(type: ts15.Type, checker: ts15.TypeChecker, enclosing?: ts15.Node, extraFlags?: ts15.TypeFormatFlags): string;
 /**
+* The type exactly as the author WROTE it — the annotation node's source text.
+* `x-ts-type` carries the resolved truth (`Omit<T, K>` expanded to its mapped
+* type, `InitiatorType` expanded to its union); this recovers the declared form
+* a docs reader recognizes.
+*
+* Restricted to NAMED references and unions — the shapes where the author wrote
+* a name that resolves to something else. Object literals, mapped, and
+* conditional bodies are excluded: they differ from their resolved text only by
+* formatting (a trailing `;`, `readonly T[]` vs `ReadonlyArray<T>`) or would
+* drag source comments into the spec, both of which are noise, not signal.
+*/
+declare function writtenTypeText(typeNode: ts15.TypeNode | undefined): string | undefined;
+/** The annotation TypeNode on a declaration (property, alias, parameter), if any. */
+declare function declaredTypeNode(decl: ts15.Declaration | undefined): ts15.TypeNode | undefined;
+/**
 * Strip `undefined` from a union type when optionality is already expressed
 * elsewhere (`required: false`, `flags.optional`). Used for both schema shape
 * and x-ts-type text so neither re-encodes optionality as `| undefined`.
@@ -1948,4 +1963,4 @@ declare function findDiscriminatorProperty(unionTypes: ts15.Type[], checker: ts1
 import ts16 from "typescript";
 declare function isExported(node: ts16.Node): boolean;
 declare function getNodeName(node: ts16.Node): string | undefined;
-export { zodAdapter, withDescription2 as withDescription, withDeprecated, validateSpec, valibotAdapter, typeboxAdapter, toToolSchema, toSearchIndexJSON, toSearchIndex2 as toSearchIndex, toPagefindRecords2 as toPagefindRecords, toNavigation2 as toNavigation, toMarkdown2 as toMarkdown, toJsonSchema, toJSONString, toJSON2 as toJSON, toHTML2 as toHTML, toFumadocsMetaJSON, toDocusaurusSidebarJS, toAlgoliaRecords2 as toAlgoliaRecords, stripUndefinedFromType, stripTsExtensions, sortByName, shouldEmitAliasTypeText, serializeVariable, serializeTypeAlias, serializeInterface, serializeFunctionExport, serializeEnum, serializeClass, scrubImportQualifiers, schemasAreEqual, schemaIsAny, resolveTypeRef, resolveExportTarget, resolveCompiledPath, renderTypeText, registerReferencedTypes, registerAdapter, recommendSemverBump, query, normalizeType, normalizeSchema, normalizeMembers, normalizeExport, mergeConfig, loadSpec, loadConfig, listExports, isTypeReference, isTypeOnlyExport, isSymbolDeprecated, isStandardJSONSchema, isSchemaType, isReadonlyPropertySymbol, isPureRefSchema, isProperty, isPrimitiveName, isMethod, isExported, isBuiltinSymbol, isBuiltinGeneric, isAnonymous, hasDeprecatedTag, groupByVisibility, getValidationErrors, getTypeOrigin, getSourceLocation, getProperties, getParamDescription, getNonNullableType, getNodeName, getMethods, getMemberBadges, getJSDocComment, getExportKind, getExport2 as getExport, getDeprecationMessage, getAvailableVersions, toMarkdown2 as generateDocs, formatTypeParameters, formatSchema, formatReturnType, formatParameters, formatMappedType, formatConditionalType, formatBadges, findMissingParamDocs, findDiscriminatorProperty, findAdapter, filterSpec, extractTypeParameters, extractStandardSchemasFromTs, extractStandardSchemasFromProject, extractStandardSchemas, extractSpec, extractSchemaType, extractParameters, extract, exportToMarkdown, exportToJsonSchema, ensureNonEmptySchema, diffSpec2 as diffSpecs, diffSpec, detectTsRuntime, deduplicateSchemas, decoratePropertySchema, createProgram, createDocs, categorizeBreakingChanges, calculateNextVersion, bundleRefs, buildSignatureString, buildSchema, buildObjectSchema, buildFunctionSchema, assertSpec, asStandardSchema, arktypeAdapter, analyzeSpec, TypeRegistry, TypeReference2 as TypeReference, TsRuntime, ToolSchemaResult, ToolSchemaProvider, ToToolSchemaOptions, ToJsonSchemaOptions, StandardSchemaExtractionResult, StandardSchemaExtractionOutput, StandardJSONSchemaV1, StandardJSONSchemaTarget, StandardJSONSchemaOptions, SpecMappedType, SpecError, SpecDiff, SpecDiagnostics, SpecConditionalType, SkippedExportDetail, SimplifiedSpec, SimplifiedSignature, SimplifiedReturn, SimplifiedParameter, SimplifiedMember, SimplifiedExport, SimplifiedExample, SerializerContext, SemverRecommendation, SemverBump, SearchRecord, SearchOptions, SearchIndex, SchemaVersion, 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, LATEST_VERSION, JsonSchemaDocument, 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, BundleResult, BundleOptions, BuiltinSchema, BreakingSeverity, BUILTIN_TYPE_SCHEMAS, AsStandardSchemaOptions, AlgoliaRecord, ARRAY_PROTOTYPE_METHODS };
+export { zodAdapter, writtenTypeText, withDescription2 as withDescription, withDeprecated, validateSpec, valibotAdapter, typeboxAdapter, toToolSchema, toSearchIndexJSON, toSearchIndex2 as toSearchIndex, toPagefindRecords2 as toPagefindRecords, toNavigation2 as toNavigation, toMarkdown2 as toMarkdown, toJsonSchema, toJSONString, toJSON2 as toJSON, toHTML2 as toHTML, toFumadocsMetaJSON, toDocusaurusSidebarJS, toAlgoliaRecords2 as toAlgoliaRecords, stripUndefinedFromType, stripTsExtensions, sortByName, shouldEmitAliasTypeText, serializeVariable, serializeTypeAlias, serializeInterface, serializeFunctionExport, serializeEnum, serializeClass, scrubImportQualifiers, schemasAreEqual, schemaIsAny, resolveTypeRef, resolveExportTarget, resolveCompiledPath, renderTypeText, registerReferencedTypes, registerAdapter, recommendSemverBump, query, normalizeType, normalizeSchema, normalizeMembers, normalizeExport, mergeConfig, loadSpec, loadConfig, listExports, isTypeReference, isTypeOnlyExport, isSymbolDeprecated, isStandardJSONSchema, isSchemaType, isReadonlyPropertySymbol, isPureRefSchema, isProperty, isPrimitiveName, isMethod, isExported, isBuiltinSymbol, isBuiltinGeneric, isAnonymous, hasDeprecatedTag, groupByVisibility, getValidationErrors, getTypeOrigin, getSourceLocation, getProperties, getParamDescription, getNonNullableType, getNodeName, getMethods, getMemberBadges, getJSDocComment, getExportKind, getExport2 as getExport, getDeprecationMessage, getAvailableVersions, toMarkdown2 as generateDocs, formatTypeParameters, formatSchema, formatReturnType, formatParameters, formatMappedType, formatConditionalType, formatBadges, findMissingParamDocs, findDiscriminatorProperty, findAdapter, filterSpec, extractTypeParameters, extractStandardSchemasFromTs, extractStandardSchemasFromProject, extractStandardSchemas, extractSpec, extractSchemaType, extractParameters, extract, exportToMarkdown, exportToJsonSchema, ensureNonEmptySchema, diffSpec2 as diffSpecs, diffSpec, detectTsRuntime, deduplicateSchemas, decoratePropertySchema, declaredTypeNode, createProgram, createDocs, categorizeBreakingChanges, calculateNextVersion, bundleRefs, buildSignatureString, buildSchema, buildObjectSchema, buildFunctionSchema, assertSpec, asStandardSchema, arktypeAdapter, analyzeSpec, TypeRegistry, TypeReference2 as TypeReference, TsRuntime, ToolSchemaResult, ToolSchemaProvider, ToToolSchemaOptions, ToJsonSchemaOptions, StandardSchemaExtractionResult, StandardSchemaExtractionOutput, StandardJSONSchemaV1, StandardJSONSchemaTarget, StandardJSONSchemaOptions, SpecMappedType, SpecError, SpecDiff, SpecDiagnostics, SpecConditionalType, SkippedExportDetail, SimplifiedSpec, SimplifiedSignature, SimplifiedReturn, SimplifiedParameter, SimplifiedMember, SimplifiedExport, SimplifiedExample, SerializerContext, SemverRecommendation, SemverBump, SearchRecord, SearchOptions, SearchIndex, SchemaVersion, 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, LATEST_VERSION, JsonSchemaDocument, 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, BundleResult, BundleOptions, BuiltinSchema, BreakingSeverity, BUILTIN_TYPE_SCHEMAS, AsStandardSchemaOptions, AlgoliaRecord, ARRAY_PROTOTYPE_METHODS };

package/dist/index.js

@@ -1993,6 +1993,22 @@ function scrubImportQualifiers(text) {
 function renderTypeText(type, checker, enclosing, extraFlags = 0) {
   return scrubImportQualifiers(checker.typeToString(type, enclosing, ts4.TypeFormatFlags.NoTruncation | extraFlags));
 }
+function writtenTypeText(typeNode) {
+  if (!typeNode)
+    return;
+  if (!ts4.isTypeReferenceNode(typeNode) && !ts4.isUnionTypeNode(typeNode))
+    return;
+  try {
+    const text = scrubImportQualifiers(typeNode.getText().replace(/\s+/g, " ").replace(/^\|\s*/, "").trim());
+    return text.length > 0 ? text : undefined;
+  } catch {
+    return;
+  }
+}
+function declaredTypeNode(decl) {
+  const withType = decl;
+  return withType?.type;
+}
 function stripUndefinedFromType(type, checker) {
   if (!type.isUnion())
     return type;
@@ -2020,6 +2036,10 @@ function decoratePropertySchema(schema, prop, propType, checker) {
   let result = obj;
   if (!derivable && !("x-ts-type" in obj)) {
     result = { ...result, "x-ts-type": text };
+    const declared = writtenTypeText(declaredTypeNode(decl));
+    if (declared && declared !== text && !PRIMITIVES.has(declared) && !("x-ts-declared" in obj)) {
+      result = { ...result, "x-ts-declared": declared };
+    }
   }
   if (isReadonlyPropertySymbol(prop) && !("readOnly" in obj)) {
     result = { ...result, readOnly: true };
@@ -2030,7 +2050,12 @@ function decoratePropertySchema(schema, prop, propType, checker) {
   return result;
 }
 function shouldEmitAliasTypeText(typeNode) {
-  return !ts4.isTypeLiteralNode(typeNode) && !ts4.isMappedTypeNode(typeNode);
+  if (ts4.isMappedTypeNode(typeNode))
+    return false;
+  if (ts4.isTypeLiteralNode(typeNode)) {
+    return typeNode.members.length > 0 && typeNode.members.every((m) => ts4.isIndexSignatureDeclaration(m));
+  }
+  return true;
 }
 var PRIMITIVES = new Set([
   "string",
@@ -3232,6 +3257,10 @@ class TypeRegistry {
       const text = renderTypeText(type, checker, decl, ts6.TypeFormatFlags.InTypeAlias);
       if (!PRIMITIVES.has(text) && text !== name) {
         schema["x-ts-type"] = text;
+        const declared = writtenTypeText(declaredTypeNode(decl));
+        if (declared && declared !== text && !PRIMITIVES.has(declared)) {
+          schema["x-ts-declared"] = declared;
+        }
       }
     }
     let typeParameters;
@@ -3914,13 +3943,16 @@ function serializeEnum(node, ctx) {
     } else if (member.initializer) {
       schema = { type: member.initializer.getText() };
     }
-    const { description: memberDesc } = getJSDocComment(member);
+    const { description: memberDesc, tags: memberTags } = getJSDocComment(member);
+    const { deprecated: deprecated2, reason: deprecationReason2 } = isSymbolDeprecated(memberSymbol);
     return {
       id: memberName,
       name: memberName,
       kind: "enum-member",
       ...schema ? { schema } : {},
-      ...memberDesc ? { description: memberDesc } : {}
+      ...memberDesc ? { description: memberDesc } : {},
+      ...memberTags.length > 0 ? { tags: memberTags } : {},
+      ...deprecated2 ? { deprecated: true, deprecationReason: deprecationReason2 } : {}
     };
   });
   return {
@@ -4247,6 +4279,9 @@ function serializeTypeAlias(node, ctx) {
     }
   } else if (isInlineFunctionAlias(node.type) && type.getCallSignatures().length > 0) {
     schema = buildFunctionSchema(type.getCallSignatures(), ctx.typeChecker, ctx);
+    if (type.getProperties().length > 0) {
+      members = serializeResolvedMembers(type, node, ctx);
+    }
   } else if ((ts11.isMappedTypeNode(node.type) || ts11.isConditionalTypeNode(node.type)) && type.getProperties().length > 0 && type.getCallSignatures().length === 0 && !(type.flags & ts11.TypeFlags.Conditional) && !(type.flags & (ts11.TypeFlags.StringLike | ts11.TypeFlags.NumberLike))) {
     schema = buildObjectSchema(type.getProperties(), ctx.typeChecker, ctx, type);
     members = serializeResolvedMembers(type, node, ctx);
@@ -4260,6 +4295,10 @@ function serializeTypeAlias(node, ctx) {
     const text = renderTypeText(type, ctx.typeChecker, node, ts11.TypeFormatFlags.InTypeAlias);
     if (!PRIMITIVES.has(text) && text !== name) {
       schema["x-ts-type"] = text;
+      const declared = writtenTypeText(declaredTypeNode(node));
+      if (declared && declared !== text && !PRIMITIVES.has(declared)) {
+        schema["x-ts-declared"] = declared;
+      }
     }
   }
   return {
@@ -7837,6 +7876,7 @@ function getNodeName(node) {
 }
 export {
   zodAdapter,
+  writtenTypeText,
   withDescription,
   withDeprecated,
   validateSpec2 as validateSpec,
@@ -7942,6 +7982,7 @@ export {
   detectTsRuntime,
   deduplicateSchemas,
   decoratePropertySchema,
+  declaredTypeNode,
   createProgram,
   createDocs,
   categorizeBreakingChanges,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpkg-ts/sdk",
-  "version": "0.48.1",
+  "version": "0.49.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.48.1",
+    "@openpkg-ts/spec": "^0.49.0",
     "picomatch": "4.0.3",
     "typescript": "^5.0.0"
   },