@openpkg-ts/sdk 0.48.1 → 0.50.0

package/dist/browser.d.ts

@@ -60,7 +60,7 @@ interface HTMLOptions {
 	/** Exports to render (multi-mode) - overridden by `export` if both provided */
 	exports?: string[];
 }
-import { SpecExportKind } from "@openpkg-ts/spec";
+import { SpecExportKind, SpecInlineTag } from "@openpkg-ts/spec";
 interface JSONOptions {
 	/** Include raw spec data alongside simplified data */
 	includeRaw?: boolean;
@@ -115,6 +115,7 @@ interface SimplifiedExport {
 	tags: Array<{
 		name: string;
 		text: string;
+		inlineTags?: SpecInlineTag[];
 	}>;
 	parameters?: SimplifiedParameter[];
 	returns?: SimplifiedReturn;

package/dist/index.d.ts

@@ -276,7 +276,7 @@ interface HTMLOptions {
 * ```
 */
 declare function toHTML2(spec: OpenPkg3, options?: HTMLOptions): string;
-import { OpenPkg as OpenPkg4, SpecExportKind } from "@openpkg-ts/spec";
+import { OpenPkg as OpenPkg4, SpecExportKind, SpecInlineTag } from "@openpkg-ts/spec";
 interface JSONOptions {
 	/** Include raw spec data alongside simplified data */
 	includeRaw?: boolean;
@@ -331,6 +331,7 @@ interface SimplifiedExport {
 	tags: Array<{
 		name: string;
 		text: string;
+		inlineTags?: SpecInlineTag[];
 	}>;
 	parameters?: SimplifiedParameter[];
 	returns?: SimplifiedReturn;
@@ -1271,12 +1272,13 @@ declare function resolveExportTarget(symbol: ts3.Symbol, checker: ts3.TypeChecke
 	targetSymbol: ts3.Symbol;
 	isTypeOnly: boolean;
 };
-import { SpecExample, SpecExportKind as SpecExportKind8, SpecSource, SpecTag, SpecTypeParameter as SpecTypeParameter2 } from "@openpkg-ts/spec";
+import { SpecExample, SpecExportKind as SpecExportKind8, SpecInlineTag as SpecInlineTag2, SpecSource, SpecTag, SpecTypeParameter as SpecTypeParameter2 } from "@openpkg-ts/spec";
 import ts4 from "typescript";
 declare function getJSDocComment(node: ts4.Node, symbol?: ts4.Symbol, checker?: ts4.TypeChecker): {
 	description?: string;
 	tags: SpecTag[];
 	examples: SpecExample[];
+	inlineTags?: SpecInlineTag2[];
 };
 declare function getSourceLocation(node: ts4.Node, sourceFile: ts4.SourceFile): SpecSource;
 /**
@@ -1839,6 +1841,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 +1965,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

@@ -480,7 +480,11 @@ function simplifyExport(exp) {
     signature: buildSignatureString(exp),
     description: exp.description,
     deprecated: exp.deprecated === true,
-    tags: (exp.tags || []).map((t) => ({ name: t.name, text: t.text })),
+    tags: (exp.tags || []).map((t) => ({
+      name: t.name,
+      text: t.text,
+      ...t.inlineTags ? { inlineTags: t.inlineTags } : {}
+    })),
     extends: exp.extends,
     implements: exp.implements,
     sourceFile: exp.source?.file,
@@ -1305,6 +1309,26 @@ import ts12 from "typescript";
 // src/ast/utils.ts
 import * as path2 from "node:path";
 import ts from "typescript";
+var INLINE_TAG_RE = /(^|[^\\])\{@([a-zA-Z][a-zA-Z0-9]*)((?:[^}\\]|\\.)*)\}/g;
+function parseInlineTags(...texts) {
+  const inlineTags = [];
+  for (const text of texts) {
+    if (!text || !text.includes("{@"))
+      continue;
+    INLINE_TAG_RE.lastIndex = 0;
+    let match = INLINE_TAG_RE.exec(text);
+    while (match) {
+      inlineTags.push({ name: match[2], text: match[3].trim() });
+      INLINE_TAG_RE.lastIndex -= 1;
+      match = INLINE_TAG_RE.exec(text);
+    }
+  }
+  return inlineTags.length > 0 ? inlineTags : undefined;
+}
+function withInlineTags(node, ...texts) {
+  const inlineTags = parseInlineTags(...texts);
+  return inlineTags ? { ...node, inlineTags } : node;
+}
 function parseExamplesFromTags(tags) {
   const examples = [];
   for (const tag of tags) {
@@ -1319,9 +1343,9 @@ function parseExamplesFromTags(tags) {
       if (lang && ["ts", "js", "tsx", "jsx", "shell", "json"].includes(lang)) {
         example.language = lang;
       }
-      examples.push(example);
+      examples.push(withInlineTags(example, example.code));
     } else if (text) {
-      examples.push({ code: text });
+      examples.push(withInlineTags({ code: text }, text));
     }
   }
   return examples;
@@ -1416,17 +1440,17 @@ function getJSDocComment(node, symbol, checker) {
         param.description = description2;
       if (paramTag.isBracketed)
         param.optional = true;
-      return { name: tag.tagName.text, text, param };
+      return withInlineTags({ name: tag.tagName.text, text, param }, text);
     }
     if (tag.tagName.text === "typeParam") {
       const text = stripTypeParamSeparator(rawText) ?? "";
-      return { name: tag.tagName.text, text };
+      return withInlineTags({ name: tag.tagName.text, text }, text);
     }
     if (tag.tagName.text === "see") {
       const text = extractSeeTagText(tag);
-      return { name: tag.tagName.text, text };
+      return withInlineTags({ name: tag.tagName.text, text }, text);
     }
-    return { name: tag.tagName.text, text: rawText };
+    return withInlineTags({ name: tag.tagName.text, text: rawText }, rawText);
   });
   const jsDocComments = ts.getJSDocCommentsAndTags(node).filter(ts.isJSDoc);
   let description;
@@ -1444,7 +1468,7 @@ function getJSDocComment(node, symbol, checker) {
     }
   }
   const examples = parseExamplesFromTags(tags);
-  return { description, tags, examples };
+  return { description, tags, examples, inlineTags: parseInlineTags(description) };
 }
 function getSourceLocation(node, sourceFile) {
   const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
@@ -1993,6 +2017,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 +2060,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 +2074,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",
@@ -2889,6 +2938,9 @@ function extractParameters(signature, ctx) {
       };
       if (description) {
         paramResult.description = description;
+        const inlineTags = parseInlineTags(description);
+        if (inlineTags)
+          paramResult.inlineTags = inlineTags;
       }
       if (decl.initializer) {
         applyDefault(paramResult, decl.initializer);
@@ -2923,6 +2975,9 @@ function expandBindingPattern(paramDecl, paramType, jsdocTags, ctx) {
     };
     if (description) {
       param.description = description;
+      const inlineTags = parseInlineTags(description);
+      if (inlineTags)
+        param.inlineTags = inlineTags;
     }
     if (element.initializer) {
       applyDefault(param, element.initializer);
@@ -3232,6 +3287,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;
@@ -3505,7 +3564,7 @@ function serializeInheritedMember(symbol, inheritedFrom, ctx, isStatic) {
   }
   if (visibility === "private")
     return null;
-  const { description, tags } = getJSDocComment(decl);
+  const { description, tags, inlineTags } = getJSDocComment(decl);
   let kind = "property";
   const callSigs = type.getCallSignatures();
   if (callSigs.length > 0) {
@@ -3538,6 +3597,7 @@ function serializeInheritedMember(symbol, inheritedFrom, ctx, isStatic) {
         },
         ...sigDoc.description ? { description: sigDoc.description } : {},
         ...sigDoc.tags.length > 0 ? { tags: sigDoc.tags } : {},
+        ...sigDoc.inlineTags ? { inlineTags: sigDoc.inlineTags } : {},
         ...callSigs.length > 1 ? { overloadIndex: index } : {}
       };
     });
@@ -3551,16 +3611,17 @@ function serializeInheritedMember(symbol, inheritedFrom, ctx, isStatic) {
     visibility,
     schema: kind !== "method" ? buildSchema(type, checker, ctx) : decoratePropertySchema({ "x-ts-function": true }, symbol, type, checker),
     signatures,
-    flags: Object.keys(flags).length > 0 ? flags : undefined
+    flags: Object.keys(flags).length > 0 ? flags : undefined,
+    ...inlineTags ? { inlineTags } : {}
   };
 }
 
 // src/serializers/shared.ts
 function extractExportMetadata(node, symbol, checker, jsdocNode) {
   const { deprecated, reason: deprecationReason } = isSymbolDeprecated(symbol);
-  const { description, tags, examples } = getJSDocComment(jsdocNode ?? node, symbol, checker);
+  const { description, tags, examples, inlineTags } = getJSDocComment(jsdocNode ?? node, symbol, checker);
   const source = getSourceLocation(node, node.getSourceFile());
-  return { description, tags, examples, source, deprecated, deprecationReason };
+  return { description, tags, examples, source, deprecated, deprecationReason, inlineTags };
 }
 function buildSignatures(callSignatures, checker, ctx) {
   return callSignatures.map((sig, index) => {
@@ -3575,6 +3636,7 @@ function buildSignatures(callSignatures, checker, ctx) {
       ...sigDoc.description ? { description: sigDoc.description } : {},
       ...sigDoc.tags.length > 0 ? { tags: sigDoc.tags } : {},
       ...sigDoc.examples.length > 0 ? { examples: sigDoc.examples } : {},
+      ...sigDoc.inlineTags ? { inlineTags: sigDoc.inlineTags } : {},
       ...sigTypeParams ? { typeParameters: sigTypeParams } : {},
       ...callSignatures.length > 1 ? { overloadIndex: index } : {}
     };
@@ -3588,7 +3650,7 @@ function serializeClass(node, ctx) {
   const name = symbol?.getName() ?? node.name?.getText();
   if (!name)
     return null;
-  const { description, tags, examples, source, deprecated, deprecationReason } = extractExportMetadata(node, symbol, checker);
+  const { description, tags, examples, source, deprecated, deprecationReason, inlineTags } = extractExportMetadata(node, symbol, checker);
   const typeParameters = extractTypeParameters(node, checker);
   const members = [];
   const signatures = [];
@@ -3664,6 +3726,7 @@ function serializeClass(node, ctx) {
     implements: implementsClause?.length ? implementsClause : undefined,
     ...deprecated ? { deprecated: true, deprecationReason } : {},
     ...examples.length > 0 ? { examples } : {},
+    ...inlineTags ? { inlineTags } : {},
     ...Object.keys(classFlags).length > 0 ? { flags: classFlags } : {}
   };
 }
@@ -3705,7 +3768,7 @@ function serializeProperty(node, ctx) {
   const name = getMemberName(node);
   if (!name)
     return null;
-  const { description, tags } = getJSDocComment(node);
+  const { description, tags, inlineTags } = getJSDocComment(node);
   const visibility = getVisibility(node);
   if (!ctx.includePrivate && (visibility === "private" || visibility === "protected")) {
     return null;
@@ -3734,6 +3797,7 @@ function serializeProperty(node, ctx) {
     visibility,
     schema,
     flags: Object.keys(flags).length > 0 ? flags : undefined,
+    ...inlineTags ? { inlineTags } : {},
     ...deprecated ? { deprecated: true, deprecationReason } : {}
   };
 }
@@ -3742,7 +3806,7 @@ function serializeMethod(node, ctx) {
   const name = getMemberName(node);
   if (!name)
     return null;
-  const { description, tags } = getJSDocComment(node);
+  const { description, tags, inlineTags } = getJSDocComment(node);
   const visibility = getVisibility(node);
   if (!ctx.includePrivate && (visibility === "private" || visibility === "protected")) {
     return null;
@@ -3775,6 +3839,7 @@ function serializeMethod(node, ctx) {
     schema,
     signatures: signatures.length > 0 ? signatures : undefined,
     flags: Object.keys(flags).length > 0 ? flags : undefined,
+    ...inlineTags ? { inlineTags } : {},
     ...deprecated ? { deprecated: true, deprecationReason } : {}
   };
 }
@@ -3786,13 +3851,14 @@ function serializeConstructor(node, ctx) {
   return serializeConstructorSignature(node, sig, ctx);
 }
 function serializeConstructorSignature(node, sig, ctx) {
-  const { description, tags, examples } = getJSDocComment(node);
+  const { description, tags, examples, inlineTags } = getJSDocComment(node);
   const params = extractParameters(sig, ctx);
   return {
     description,
     parameters: params.length > 0 ? params : undefined,
     ...tags.length > 0 ? { tags } : {},
-    ...examples.length > 0 ? { examples } : {}
+    ...examples.length > 0 ? { examples } : {},
+    ...inlineTags ? { inlineTags } : {}
   };
 }
 function serializeInheritedConstructors(node, ctx) {
@@ -3823,7 +3889,7 @@ function serializeAccessor(node, ctx) {
   const name = getMemberName(node);
   if (!name)
     return null;
-  const { description, tags } = getJSDocComment(node);
+  const { description, tags, inlineTags } = getJSDocComment(node);
   const visibility = getVisibility(node);
   if (!ctx.includePrivate && (visibility === "private" || visibility === "protected")) {
     return null;
@@ -3861,7 +3927,8 @@ function serializeAccessor(node, ctx) {
     visibility,
     schema,
     signatures,
-    flags: Object.keys(flags).length > 0 ? flags : undefined
+    flags: Object.keys(flags).length > 0 ? flags : undefined,
+    ...inlineTags ? { inlineTags } : {}
   };
 }
 function getExtendsClause(node, checker) {
@@ -3901,7 +3968,7 @@ function serializeEnum(node, ctx) {
   const name = symbol?.getName() ?? node.name?.getText();
   if (!name)
     return null;
-  const { description, tags, examples, source, deprecated, deprecationReason } = extractExportMetadata(node, symbol, checker);
+  const { description, tags, examples, source, deprecated, deprecationReason, inlineTags } = extractExportMetadata(node, symbol, checker);
   const members = node.members.map((member) => {
     const memberSymbol = checker.getSymbolAtLocation(member.name);
     const memberName = memberSymbol?.getName() ?? member.name.getText();
@@ -3914,13 +3981,21 @@ function serializeEnum(node, ctx) {
     } else if (member.initializer) {
       schema = { type: member.initializer.getText() };
     }
-    const { description: memberDesc } = getJSDocComment(member);
+    const {
+      description: memberDesc,
+      tags: memberTags,
+      inlineTags: memberInlineTags
+    } = 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 } : {},
+      ...memberInlineTags ? { inlineTags: memberInlineTags } : {},
+      ...deprecated2 ? { deprecated: true, deprecationReason: deprecationReason2 } : {}
     };
   });
   return {
@@ -3932,7 +4007,8 @@ function serializeEnum(node, ctx) {
     source,
     members,
     ...deprecated ? { deprecated: true, deprecationReason } : {},
-    ...examples.length > 0 ? { examples } : {}
+    ...examples.length > 0 ? { examples } : {},
+    ...inlineTags ? { inlineTags } : {}
   };
 }
 
@@ -3971,7 +4047,7 @@ function serializeFunctionExport(node, ctx, nameOverride) {
   const name = nameOverride ?? symbol?.getName() ?? node.name?.getText();
   if (!name)
     return null;
-  const { description, tags, examples, source, deprecated, deprecationReason } = extractExportMetadata(node, symbol, ctx.typeChecker);
+  const { description, tags, examples, source, deprecated, deprecationReason, inlineTags } = extractExportMetadata(node, symbol, ctx.typeChecker);
   const typeParameters = extractTypeParameters(node, ctx.typeChecker);
   const type = ctx.typeChecker.getTypeAtLocation(node);
   const callSignatures = type.getCallSignatures();
@@ -4008,7 +4084,8 @@ function serializeFunctionExport(node, ctx, nameOverride) {
     signatures,
     ...Object.keys(flags).length > 0 ? { flags } : {},
     ...deprecated ? { deprecated: true, deprecationReason } : {},
-    ...examples.length > 0 ? { examples } : {}
+    ...examples.length > 0 ? { examples } : {},
+    ...inlineTags ? { inlineTags } : {}
   };
 }
 
@@ -4020,7 +4097,7 @@ function serializeInterface(node, ctx) {
   const name = symbol?.getName() ?? node.name?.getText();
   if (!name)
     return null;
-  const { description, tags, examples, source, deprecated, deprecationReason } = extractExportMetadata(node, symbol, checker);
+  const { description, tags, examples, source, deprecated, deprecationReason, inlineTags } = extractExportMetadata(node, symbol, checker);
   const typeParameters = extractTypeParameters(node, checker);
   const members = [];
   const methodsByName = new Map;
@@ -4098,13 +4175,14 @@ function serializeInterface(node, ctx) {
     signatures: exportSignatures,
     extends: extendsClause,
     ...deprecated ? { deprecated: true, deprecationReason } : {},
-    ...examples.length > 0 ? { examples } : {}
+    ...examples.length > 0 ? { examples } : {},
+    ...inlineTags ? { inlineTags } : {}
   };
 }
 function serializePropertySignature(node, ctx) {
   const { typeChecker: checker } = ctx;
   const name = node.name.getText();
-  const { description, tags } = getJSDocComment(node);
+  const { description, tags, inlineTags } = getJSDocComment(node);
   const rawType = checker.getTypeAtLocation(node);
   const type = node.questionToken ? stripUndefinedFromType(rawType, checker) : rawType;
   let schema = buildSchema(type, checker, ctx);
@@ -4127,13 +4205,14 @@ function serializePropertySignature(node, ctx) {
     tags: tags.length > 0 ? tags : undefined,
     schema,
     flags: Object.keys(flags).length > 0 ? flags : undefined,
+    ...inlineTags ? { inlineTags } : {},
     ...deprecated ? { deprecated: true, deprecationReason } : {}
   };
 }
 function serializeMethodSignature(node, ctx) {
   const { typeChecker: checker } = ctx;
   const name = node.name.getText();
-  const { description, tags } = getJSDocComment(node);
+  const { description, tags, inlineTags } = getJSDocComment(node);
   const type = checker.getTypeAtLocation(node);
   const callSignatures = type.getCallSignatures();
   const signatures = buildSignatures(callSignatures, checker, ctx);
@@ -4152,12 +4231,13 @@ function serializeMethodSignature(node, ctx) {
     schema,
     signatures: signatures.length > 0 ? signatures : undefined,
     flags: Object.keys(flags).length > 0 ? flags : undefined,
+    ...inlineTags ? { inlineTags } : {},
     ...deprecated ? { deprecated: true, deprecationReason } : {}
   };
 }
 function serializeCallSignature(node, ctx) {
   const { typeChecker: checker } = ctx;
-  const { description, tags } = getJSDocComment(node);
+  const { description, tags, inlineTags } = getJSDocComment(node);
   const sig = checker.getSignatureFromDeclaration(node);
   if (!sig)
     return null;
@@ -4169,6 +4249,7 @@ function serializeCallSignature(node, ctx) {
     kind: "call-signature",
     description,
     tags: tags.length > 0 ? tags : undefined,
+    ...inlineTags ? { inlineTags } : {},
     signatures: [
       {
         parameters: params.length > 0 ? params : undefined,
@@ -4181,7 +4262,7 @@ function serializeCallSignature(node, ctx) {
 }
 function serializeIndexSignature(node, ctx) {
   const { typeChecker: checker } = ctx;
-  const { description, tags } = getJSDocComment(node);
+  const { description, tags, inlineTags } = getJSDocComment(node);
   const valueType = node.type ? checker.getTypeAtLocation(node.type) : checker.getAnyType();
   const valueSchema = buildSchema(valueType, checker, ctx);
   registerReferencedTypes(valueType, ctx);
@@ -4193,7 +4274,8 @@ function serializeIndexSignature(node, ctx) {
     kind: "index-signature",
     description,
     tags: tags.length > 0 ? tags : undefined,
-    schema: valueSchema
+    schema: valueSchema,
+    ...inlineTags ? { inlineTags } : {}
   };
 }
 function getInterfaceExtends(node, checker) {
@@ -4234,7 +4316,7 @@ function serializeTypeAlias(node, ctx) {
   const name = symbol?.getName() ?? node.name?.getText();
   if (!name)
     return null;
-  const { description, tags, examples, source, deprecated, deprecationReason } = extractExportMetadata(node, symbol, ctx.typeChecker);
+  const { description, tags, examples, source, deprecated, deprecationReason, inlineTags } = extractExportMetadata(node, symbol, ctx.typeChecker);
   const typeParameters = extractTypeParameters(node, ctx.typeChecker);
   const type = ctx.typeChecker.getTypeAtLocation(node);
   registerReferencedTypes(type, ctx);
@@ -4247,6 +4329,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 +4345,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 {
@@ -4273,7 +4362,8 @@ function serializeTypeAlias(node, ctx) {
     schema,
     ...members && members.length > 0 ? { members } : {},
     ...deprecated ? { deprecated: true, deprecationReason } : {},
-    ...examples.length > 0 ? { examples } : {}
+    ...examples.length > 0 ? { examples } : {},
+    ...inlineTags ? { inlineTags } : {}
   };
 }
 function isObjectShapedAlias(type, ctx) {
@@ -4372,6 +4462,7 @@ function serializeResolvedMembers(type, node, ctx) {
     if (prop.flags & ts11.SymbolFlags.Method)
       flags.methodSyntax = true;
     const schema = kind === "property" ? decoratePropertySchema(buildSchema(propType, checker, ctx), prop, propType, checker) : decoratePropertySchema({ "x-ts-function": true }, prop, propType, checker);
+    const inlineTags = parseInlineTags(description);
     members.push({
       name: prop.getName(),
       kind,
@@ -4380,6 +4471,7 @@ function serializeResolvedMembers(type, node, ctx) {
       schema,
       signatures: kind === "method" ? buildSignatures(callSigs, checker, ctx) : undefined,
       flags: Object.keys(flags).length > 0 ? flags : undefined,
+      ...inlineTags ? { inlineTags } : {},
       ...deprecated ? { deprecated: true, deprecationReason } : {}
     });
   }
@@ -4555,7 +4647,7 @@ function serializeVariable(node, statement, ctx) {
   const name = symbol?.getName() ?? node.name.getText();
   if (!name)
     return null;
-  const { description, tags, examples, source, deprecated, deprecationReason } = extractExportMetadata(node, symbol, ctx.typeChecker, statement);
+  const { description, tags, examples, source, deprecated, deprecationReason, inlineTags } = extractExportMetadata(node, symbol, ctx.typeChecker, statement);
   const type = ctx.typeChecker.getTypeAtLocation(node);
   const schemaExtraction = extractSchemaType(type, ctx.typeChecker);
   const typeToSerialize = schemaExtraction?.outputType ?? type;
@@ -4575,7 +4667,8 @@ function serializeVariable(node, statement, ctx) {
     schema,
     ...flags ? { flags } : {},
     ...deprecated ? { deprecated: true, deprecationReason } : {},
-    ...examples.length > 0 ? { examples } : {}
+    ...examples.length > 0 ? { examples } : {},
+    ...inlineTags ? { inlineTags } : {}
   };
 }
 
@@ -7138,6 +7231,7 @@ function serializeDeclaration2(declaration, exportSymbol, exportName, ctx, isTyp
 }
 function serializeNamespaceExport(symbol, exportName, ctx) {
   const { description, tags, examples } = getJSDocFromExportSymbol(symbol);
+  const inlineTags = parseInlineTags(description);
   const members = [];
   const checker = ctx.program.getTypeChecker();
   let targetSymbol = symbol;
@@ -7162,7 +7256,8 @@ function serializeNamespaceExport(symbol, exportName, ctx) {
     description,
     tags,
     ...examples.length > 0 ? { examples } : {},
-    ...members.length > 0 ? { members } : {}
+    ...members.length > 0 ? { members } : {},
+    ...inlineTags ? { inlineTags } : {}
   };
 }
 function serializeNamespaceMember(symbol, memberName, ctx) {
@@ -7209,15 +7304,22 @@ function serializeNamespaceMember(symbol, memberName, ctx) {
     registerReferencedTypes(type, ctx);
     schema = buildSchema(type, ctx.typeChecker, ctx);
   }
+  const inlineTags = parseInlineTags(description);
   return {
     name: memberName,
     kind,
     ...description ? { description } : {},
     ...signatures ? { signatures } : {},
     ...schema ? { schema } : {},
+    ...inlineTags ? { inlineTags } : {},
     ...deprecated ? { flags: { deprecated: true } } : {}
   };
 }
+function flattenJSDocComment(comment) {
+  if (comment === undefined)
+    return "";
+  return typeof comment === "string" ? comment : ts18.getTextOfJSDocComment(comment) ?? "";
+}
 function getJSDocFromExportSymbol(symbol) {
   const tags = [];
   const examples = [];
@@ -7228,7 +7330,7 @@ function getJSDocFromExportSymbol(symbol) {
       const jsDocs = ts18.getJSDocCommentsAndTags(exportDecl);
       for (const doc of jsDocs) {
         if (ts18.isJSDoc(doc) && doc.comment) {
-          const commentText = typeof doc.comment === "string" ? doc.comment : doc.comment.map((c) => ("text" in c) ? c.text : "").join("");
+          const commentText = flattenJSDocComment(doc.comment);
           if (commentText) {
             return {
               description: commentText,
@@ -7258,8 +7360,9 @@ function extractJSDocTags(doc) {
   const tags = [];
   for (const tag of doc.tags ?? []) {
     if (tag.tagName.text !== "example") {
-      const text = typeof tag.comment === "string" ? tag.comment : tag.comment?.map((c) => ("text" in c) ? c.text : "").join("") ?? "";
-      tags.push({ name: tag.tagName.text, text });
+      const text = flattenJSDocComment(tag.comment);
+      const inlineTags = parseInlineTags(text);
+      tags.push({ name: tag.tagName.text, text, ...inlineTags ? { inlineTags } : {} });
     }
   }
   return tags;
@@ -7268,7 +7371,7 @@ function extractExamples(doc) {
   const examples = [];
   for (const tag of doc.tags ?? []) {
     if (tag.tagName.text === "example") {
-      const text = typeof tag.comment === "string" ? tag.comment : tag.comment?.map((c) => ("text" in c) ? c.text : "").join("") ?? "";
+      const text = flattenJSDocComment(tag.comment);
       if (text)
         examples.push(text);
     }
@@ -7837,6 +7940,7 @@ function getNodeName(node) {
 }
 export {
   zodAdapter,
+  writtenTypeText,
   withDescription,
   withDeprecated,
   validateSpec2 as validateSpec,
@@ -7942,6 +8046,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.50.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.50.0",
     "picomatch": "4.0.3",
     "typescript": "^5.0.0"
   },