@openpkg-ts/sdk 0.36.0 → 0.37.0

package/dist/browser.d.ts

@@ -381,19 +381,19 @@ interface DocsInstance {
 	getDeprecated(): SpecExport3[];
 	/** Get exports grouped by kind */
 	groupByKind(): Record<SpecExportKind4, SpecExport3[]>;
-	/** Render spec or single to MDX */
+	/** Render spec or single to an MDX string */
 	toMarkdown(options?: ExportMarkdownOptions): string;
-	/** Render spec or single to HTML */
+	/** Render spec or single to an HTML string */
 	toHTML(options?: HTMLOptions): string;
-	/** Render spec or single to JSON structure */
+	/** Render spec or single to a simplified JSON structure */
 	toJSON(options?: JSONOptions): SimplifiedSpec | SimplifiedExport;
-	/** Generate navigation structure */
+	/** Generate navigation data structure (JSON object, not a component) */
 	toNavigation(options?: NavOptions): GenericNav | FumadocsMeta | DocusaurusSidebar;
-	/** Generate search index */
+	/** Generate search index data */
 	toSearchIndex(options?: SearchOptions): SearchIndex;
-	/** Generate Pagefind-compatible records */
+	/** Generate Pagefind-compatible record objects */
 	toPagefindRecords(options?: SearchOptions): PagefindRecord[];
-	/** Generate Algolia-compatible records */
+	/** Generate Algolia-compatible record objects */
 	toAlgoliaRecords(options?: SearchOptions): AlgoliaRecord[];
 }
 import { OpenPkg as OpenPkg8, SpecExport as SpecExport4, SpecMember as SpecMember2, SpecSchema, SpecSignature, SpecType as SpecType2, SpecTypeParameter } from "@openpkg-ts/spec";

package/dist/index.d.ts

@@ -229,9 +229,12 @@ interface HTMLOptions {
 /**
 * Render spec to standalone HTML page.
 *
+* Returns an HTML string — not a React component. Write the result to an
+* `.html` file or embed it in a template.
+*
 * @param spec - The OpenPkg spec to render
 * @param options - HTML rendering options
-* @returns Complete HTML document or fragment
+* @returns Complete HTML document string or HTML fragment string
 *
 * @example
 * ```ts
@@ -403,6 +406,9 @@ declare function exportToMarkdown(exp: SpecExport2, options?: MarkdownOptions):
 /**
 * Render entire spec to MDX.
 *
+* Returns an MDX-formatted string — not a React component. Write the result to
+* a `.mdx` file or pass it to your docs framework's content pipeline.
+*
 * @param spec - The OpenPkg spec to render
 * @param options - Markdown options, optionally with name for single mode
 * @returns MDX string
@@ -499,6 +505,8 @@ declare function toNavigation2(spec: OpenPkg6, options?: NavOptions): GenericNav
 /**
 * Generate Fumadocs meta.json file content.
 *
+* Returns a JSON string suitable for writing to a meta.json file — not a React component.
+*
 * @param spec - The OpenPkg spec
 * @param options - Navigation options (format is forced to fumadocs)
 * @returns JSON string for meta.json file
@@ -513,6 +521,8 @@ declare function toFumadocsMetaJSON(spec: OpenPkg6, options?: Omit<NavOptions, "
 /**
 * Generate Docusaurus sidebar config.
 *
+* Returns a JavaScript module.exports string suitable for writing to a sidebars.js file — not a React component.
+*
 * @param spec - The OpenPkg spec
 * @param options - Navigation options (format is forced to docusaurus)
 * @returns JavaScript module.exports string for sidebars.js
@@ -691,19 +701,19 @@ interface DocsInstance {
 	getDeprecated(): SpecExport3[];
 	/** Get exports grouped by kind */
 	groupByKind(): Record<SpecExportKind4, SpecExport3[]>;
-	/** Render spec or single to MDX */
+	/** Render spec or single to an MDX string */
 	toMarkdown(options?: ExportMarkdownOptions): string;
-	/** Render spec or single to HTML */
+	/** Render spec or single to an HTML string */
 	toHTML(options?: HTMLOptions): string;
-	/** Render spec or single to JSON structure */
+	/** Render spec or single to a simplified JSON structure */
 	toJSON(options?: JSONOptions): SimplifiedSpec | SimplifiedExport;
-	/** Generate navigation structure */
+	/** Generate navigation data structure (JSON object, not a component) */
 	toNavigation(options?: NavOptions): GenericNav | FumadocsMeta | DocusaurusSidebar;
-	/** Generate search index */
+	/** Generate search index data */
 	toSearchIndex(options?: SearchOptions): SearchIndex;
-	/** Generate Pagefind-compatible records */
+	/** Generate Pagefind-compatible record objects */
 	toPagefindRecords(options?: SearchOptions): PagefindRecord[];
-	/** Generate Algolia-compatible records */
+	/** Generate Algolia-compatible record objects */
 	toAlgoliaRecords(options?: SearchOptions): AlgoliaRecord[];
 }
 /**
@@ -722,6 +732,10 @@ declare function loadSpec(spec: OpenPkg8): DocsInstance;
 /**
 * Creates a docs instance for querying and rendering API documentation.
 *
+* Render methods (toMarkdown, toHTML, toJSON, toNavigation) return strings or
+* plain data objects — not React components. For React UI components, see the
+* `@openpkg-ts/registry` package.
+*
 * @example
 * ```ts
 * import { createDocs } from '@openpkg-ts/sdk'
@@ -1125,7 +1139,7 @@ interface ExportItem {
 	/** Export name */
 	name: string;
 	/** Export kind */
-	kind: "function" | "class" | "interface" | "type" | "enum" | "variable" | "namespace";
+	kind: "function" | "class" | "interface" | "type" | "enum" | "variable" | "namespace" | "external";
 	/** Source file path */
 	file: string;
 	/** Line number (1-indexed) */
@@ -1207,9 +1221,14 @@ declare class TypeRegistry {
 	*/
 	private isSelfRef;
 	/**
+	* Resolve a self-referential $ref to the actual type structure.
+	* Handles unions (string literal → enum), enums (numeric → enum), and objects.
+	*/
+	private resolveSelRefSchema;
+	/**
 	* Build object schema from type properties (for interfaces/classes)
 	*/
-	private buildObjectSchemaFromType;
+	private buildObjectSchemaFromProperties;
 }
 import ts3 from "typescript";
 /**
@@ -1618,7 +1637,7 @@ import ts9 from "typescript";
 declare function serializeEnum(node: ts9.EnumDeclaration, ctx: SerializerContext): SpecExport10 | null;
 import { SpecExport as SpecExport11 } from "@openpkg-ts/spec";
 import ts10 from "typescript";
-declare function serializeFunctionExport(node: ts10.FunctionDeclaration | ts10.ArrowFunction, ctx: SerializerContext, nameOverride?: string): SpecExport11 | null;
+declare function serializeFunctionExport(node: ts10.FunctionDeclaration | ts10.ArrowFunction | ts10.FunctionExpression, ctx: SerializerContext, nameOverride?: string): SpecExport11 | null;
 import { SpecExport as SpecExport12 } from "@openpkg-ts/spec";
 import ts11 from "typescript";
 declare function serializeInterface(node: ts11.InterfaceDeclaration, ctx: SerializerContext): SpecExport12 | null;
@@ -1645,6 +1664,8 @@ import ts15 from "typescript";
 declare const BUILTIN_TYPE_SCHEMAS: Record<string, SpecSchema2>;
 declare const PRIMITIVES: Set<string>;
 declare const ARRAY_PROTOTYPE_METHODS: Set<string>;
+declare const STRING_PROTOTYPE_METHODS: Set<string>;
+declare const NUMBER_PROTOTYPE_METHODS: Set<string>;
 /**
 * Check if a name is a primitive type
 */
@@ -1770,4 +1791,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, toReactString, toReact, 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, ReactLayoutOptions, QueryBuilder, ProjectExtractionOutput, ProjectExtractionInfo, ProgramResult, ProgramOptions, PagefindRecord, PRIMITIVES, OpenpkgConfig, NormalizeOptions, NavOptions, NavItem, NavGroup, NavFormat, 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, toReactString, toReact, 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, ReactLayoutOptions, 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

@@ -1953,6 +1953,21 @@ function isSymbolDeprecated(symbol) {
       }
       return { deprecated: true, reason };
     }
+    if (ts2.isExportSpecifier(declaration)) {
+      const exportDecl = declaration.parent?.parent;
+      if (exportDecl && ts2.isExportDeclaration(exportDecl)) {
+        const parentTag = ts2.getJSDocDeprecatedTag(exportDecl);
+        if (parentTag) {
+          let reason;
+          if (typeof parentTag.comment === "string") {
+            reason = parentTag.comment;
+          } else if (Array.isArray(parentTag.comment)) {
+            reason = parentTag.comment.map((c) => typeof c === "string" ? c : c.text).join("");
+          }
+          return { deprecated: true, reason };
+        }
+      }
+    }
   }
   return { deprecated: false };
 }
@@ -2013,6 +2028,8 @@ function getExportKind(declaration, type) {
     return "enum";
   if (ts2.isModuleDeclaration(declaration) || ts2.isNamespaceExport(declaration))
     return "namespace";
+  if (ts2.isVariableDeclaration(declaration) && type.getConstructSignatures().length > 0)
+    return "class";
   if (ts2.isVariableDeclaration(declaration) && type.getCallSignatures().length > 0)
     return "function";
   return "variable";
@@ -2157,6 +2174,63 @@ var ARRAY_PROTOTYPE_METHODS = new Set([
   "toString",
   "toLocaleString"
 ]);
+var STRING_PROTOTYPE_METHODS = new Set([
+  "charAt",
+  "charCodeAt",
+  "codePointAt",
+  "concat",
+  "endsWith",
+  "includes",
+  "indexOf",
+  "lastIndexOf",
+  "localeCompare",
+  "match",
+  "matchAll",
+  "normalize",
+  "padEnd",
+  "padStart",
+  "repeat",
+  "replace",
+  "replaceAll",
+  "search",
+  "slice",
+  "split",
+  "startsWith",
+  "substring",
+  "toLocaleLowerCase",
+  "toLocaleUpperCase",
+  "toLowerCase",
+  "toUpperCase",
+  "trim",
+  "trimEnd",
+  "trimStart",
+  "at",
+  "bold",
+  "fixed",
+  "italics",
+  "link",
+  "small",
+  "strike",
+  "sub",
+  "sup",
+  "anchor",
+  "big",
+  "blink",
+  "fontcolor",
+  "fontsize",
+  "substr",
+  "toString",
+  "valueOf",
+  "length"
+]);
+var NUMBER_PROTOTYPE_METHODS = new Set([
+  "toFixed",
+  "toExponential",
+  "toPrecision",
+  "toString",
+  "valueOf",
+  "toLocaleString"
+]);
 function isPrimitiveName(name) {
   return PRIMITIVES.has(name);
 }
@@ -2301,7 +2375,7 @@ function buildSchemaInternal(type, checker, ctx) {
       return { type: "bigint" };
     if (type.flags & ts3.TypeFlags.ESSymbol)
       return { type: "symbol" };
-    if (type.isThisType?.()) {
+    if (type.isThisType === true) {
       const constraint = type.getConstraint?.();
       const symbol2 = constraint?.getSymbol() ?? type.getSymbol();
       if (symbol2 && !isAnonymous(type)) {
@@ -2556,6 +2630,7 @@ function buildFunctionSchema(callSignatures, checker, ctx) {
   return { type: "function", signatures: buildSignatures() };
 }
 function buildObjectSchema(properties, checker, ctx, originalType) {
+  const isArrayLikeType = originalType ? checker.isArrayType(originalType) || checker.isTupleType(originalType) || originalType.symbol?.getName() === "Array" && isBuiltinSymbol(originalType.symbol) : false;
   const buildProps = () => {
     const props = {};
     const required = [];
@@ -2563,7 +2638,7 @@ function buildObjectSchema(properties, checker, ctx, originalType) {
       const propName = prop.getName();
       if (propName.startsWith("_"))
         continue;
-      if (ARRAY_PROTOTYPE_METHODS.has(propName)) {
+      if (isArrayLikeType && ARRAY_PROTOTYPE_METHODS.has(propName)) {
         continue;
       }
       const propType = checker.getTypeOfSymbol(prop);
@@ -2945,8 +3020,6 @@ function isGenericTypeParameter(name) {
     return true;
   if (/^T[A-Z]/.test(name))
     return true;
-  if (["Key", "Value", "Item", "Element"].includes(name))
-    return true;
   return false;
 }
 function isExternalType(decl) {
@@ -2972,7 +3045,7 @@ class TypeRegistry {
     return Array.from(this.types.values());
   }
   registerType(type, ctx) {
-    const symbol = type.getSymbol() || type.aliasSymbol;
+    const symbol = type.aliasSymbol || type.getSymbol();
     if (!symbol)
       return;
     const name = symbol.getName();
@@ -3027,7 +3100,7 @@ class TypeRegistry {
     }
     let schema = buildSchema(type, checker, ctx);
     if (this.isSelfRef(schema, name)) {
-      schema = this.buildObjectSchemaFromType(type, checker, ctx);
+      schema = this.resolveSelRefSchema(type, checker, ctx);
     }
     return {
       id: name,
@@ -3043,7 +3116,56 @@ class TypeRegistry {
     const obj = schema;
     return obj.$ref === `#/types/${typeName}`;
   }
-  buildObjectSchemaFromType(type, checker, ctx) {
+  resolveSelRefSchema(type, checker, ctx) {
+    if (type.isUnion()) {
+      const types = type.types;
+      const allStringLiterals = types.every((t) => t.flags & ts5.TypeFlags.StringLiteral);
+      if (allStringLiterals) {
+        return {
+          type: "string",
+          enum: types.map((t) => t.value)
+        };
+      }
+      const allNumberLiterals = types.every((t) => t.flags & ts5.TypeFlags.NumberLiteral);
+      if (allNumberLiterals) {
+        return {
+          type: "number",
+          enum: types.map((t) => t.value)
+        };
+      }
+      return {
+        anyOf: types.map((t) => buildSchema(t, checker, ctx))
+      };
+    }
+    const symbol = type.getSymbol() ?? type.aliasSymbol;
+    if (symbol) {
+      const decl = symbol.declarations?.find(ts5.isEnumDeclaration);
+      if (decl) {
+        const members = [];
+        for (const member of decl.members) {
+          const memberSymbol = checker.getSymbolAtLocation(member.name);
+          if (memberSymbol) {
+            const constantValue = checker.getConstantValue(member);
+            if (constantValue !== undefined) {
+              members.push({
+                name: memberSymbol.getName(),
+                value: constantValue
+              });
+            }
+          }
+        }
+        if (members.length > 0) {
+          return {
+            type: typeof members[0].value === "string" ? "string" : "number",
+            enum: members.map((m) => m.value),
+            "x-enum-members": members
+          };
+        }
+      }
+    }
+    return this.buildObjectSchemaFromProperties(type, checker, ctx);
+  }
+  buildObjectSchemaFromProperties(type, checker, ctx) {
     const properties = type.getProperties();
     if (properties.length === 0) {
       return { type: checker.typeToString(type) };
@@ -3055,11 +3177,18 @@ class TypeRegistry {
       const typeName = type.getSymbol()?.getName() ?? "anonymous";
       ctx.onTruncation(typeName, properties.length, limit);
     }
+    const isArrayLike = checker.isArrayType(type) || checker.isTupleType(type) || type.symbol?.getName() === "Array" && type.symbol?.getDeclarations()?.[0]?.getSourceFile()?.fileName?.includes("/typescript/lib/lib.");
+    const isStringLike = type.flags & ts5.TypeFlags.StringLike;
+    const isNumberLike = type.flags & ts5.TypeFlags.NumberLike;
     for (const prop of properties.slice(0, limit)) {
       const propName = prop.getName();
       if (propName.startsWith("_"))
         continue;
-      if (ARRAY_PROTOTYPE_METHODS.has(propName))
+      if (isArrayLike && ARRAY_PROTOTYPE_METHODS.has(propName))
+        continue;
+      if (isStringLike && STRING_PROTOTYPE_METHODS.has(propName))
+        continue;
+      if (isNumberLike && NUMBER_PROTOTYPE_METHODS.has(propName))
         continue;
       const propType = checker.getTypeOfSymbol(prop);
       this.registerType(propType, ctx);
@@ -3091,7 +3220,7 @@ function createContext(program, sourceFile, options = {}) {
     visitedTypes: new Set,
     registeredTypes: new Set,
     includePrivate: options.includePrivate ?? false,
-    maxProperties: options.maxProperties ?? 20,
+    maxProperties: options.maxProperties ?? 100,
     onTruncation: options.onTruncation
   };
 }
@@ -3388,6 +3517,8 @@ function serializeProperty(node, ctx) {
     flags.readonly = true;
   if (node.questionToken)
     flags.optional = true;
+  const symbol = checker.getSymbolAtLocation(node.name ?? node);
+  const { deprecated, reason: deprecationReason } = isSymbolDeprecated(symbol);
   return {
     name,
     kind: "property",
@@ -3395,7 +3526,8 @@ function serializeProperty(node, ctx) {
     tags: tags.length > 0 ? tags : undefined,
     visibility,
     schema,
-    flags: Object.keys(flags).length > 0 ? flags : undefined
+    flags: Object.keys(flags).length > 0 ? flags : undefined,
+    ...deprecated ? { deprecated: true, deprecationReason } : {}
   };
 }
 function serializeMethod(node, ctx) {
@@ -3423,6 +3555,8 @@ function serializeMethod(node, ctx) {
   if (modifiers?.some((m) => m.kind === ts7.SyntaxKind.AbstractKeyword)) {
     flags.abstract = true;
   }
+  const symbol = checker.getSymbolAtLocation(node.name ?? node);
+  const { deprecated, reason: deprecationReason } = isSymbolDeprecated(symbol);
   return {
     name,
     kind: "method",
@@ -3430,7 +3564,8 @@ function serializeMethod(node, ctx) {
     tags: tags.length > 0 ? tags : undefined,
     visibility,
     signatures: signatures.length > 0 ? signatures : undefined,
-    flags: Object.keys(flags).length > 0 ? flags : undefined
+    flags: Object.keys(flags).length > 0 ? flags : undefined,
+    ...deprecated ? { deprecated: true, deprecationReason } : {}
   };
 }
 function serializeConstructor(node, ctx) {
@@ -3616,6 +3751,14 @@ function serializeFunctionExport(node, ctx, nameOverride) {
       ...callSignatures.length > 1 ? { overloadIndex: index } : {}
     };
   });
+  const flags = {};
+  const modifiers = ts8.getModifiers(node);
+  if (modifiers?.some((m) => m.kind === ts8.SyntaxKind.AsyncKeyword)) {
+    flags.async = true;
+  }
+  if (node.asteriskToken) {
+    flags.generator = true;
+  }
   return {
     id: name,
     name,
@@ -3625,6 +3768,7 @@ function serializeFunctionExport(node, ctx, nameOverride) {
     source,
     typeParameters,
     signatures,
+    ...Object.keys(flags).length > 0 ? { flags } : {},
     ...deprecated ? { deprecated: true, deprecationReason } : {},
     ...examples.length > 0 ? { examples } : {}
   };
@@ -3732,13 +3876,16 @@ function serializePropertySignature(node, ctx) {
   if (node.modifiers?.some((m) => m.kind === ts9.SyntaxKind.ReadonlyKeyword)) {
     flags.readonly = true;
   }
+  const symbol = checker.getSymbolAtLocation(node.name);
+  const { deprecated, reason: deprecationReason } = isSymbolDeprecated(symbol);
   return {
     name,
     kind: "property",
     description,
     tags: tags.length > 0 ? tags : undefined,
     schema,
-    flags: Object.keys(flags).length > 0 ? flags : undefined
+    flags: Object.keys(flags).length > 0 ? flags : undefined,
+    ...deprecated ? { deprecated: true, deprecationReason } : {}
   };
 }
 function serializeMethodSignature(node, ctx) {
@@ -3751,13 +3898,16 @@ function serializeMethodSignature(node, ctx) {
   const flags = {};
   if (node.questionToken)
     flags.optional = true;
+  const symbol = checker.getSymbolAtLocation(node.name);
+  const { deprecated, reason: deprecationReason } = isSymbolDeprecated(symbol);
   return {
     name,
     kind: "method",
     description,
     tags: tags.length > 0 ? tags : undefined,
     signatures: signatures.length > 0 ? signatures : undefined,
-    flags: Object.keys(flags).length > 0 ? flags : undefined
+    flags: Object.keys(flags).length > 0 ? flags : undefined,
+    ...deprecated ? { deprecated: true, deprecationReason } : {}
   };
 }
 function serializeCallSignature(node, ctx) {
@@ -4497,12 +4647,12 @@ async function getExport(options) {
   const result = createProgram({ entryFile, baseDir, content });
   const { program, sourceFile } = result;
   if (!sourceFile) {
-    return { export: null, types: [], errors: [`Could not load source file: ${entryFile}`] };
+    return { export: null, types: [], errors: [`Entry file not found: ${entryFile}. Specify with: drift get src/index.ts <name>`] };
   }
   const checker = program.getTypeChecker();
   const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
   if (!moduleSymbol) {
-    return { export: null, types: [], errors: ["Could not get module symbol"] };
+    return { export: null, types: [], errors: [`No exports found in ${entryFile}. Is this the right entry point?`] };
   }
   const exportedSymbols = checker.getExportsOfModule(moduleSymbol);
   const targetSymbol = exportedSymbols.find((s) => s.getName() === exportName);
@@ -4516,12 +4666,39 @@ async function getExport(options) {
   const ctx = createContext(program, sourceFile, { maxTypeDepth });
   ctx.exportedIds = exportedIds;
   try {
+    const originalDecls = targetSymbol.declarations ?? [];
+    const isNamespaceExportDecl = originalDecls.some((d) => ts11.isNamespaceExport(d) || ts11.isNamespaceImport(d));
+    if (isNamespaceExportDecl) {
+      const spec2 = serializeNamespaceForGet(targetSymbol, exportName, ctx);
+      const types2 = ctx.typeRegistry.getAll().map((t) => normalizeType(t, { dialect: "draft-2020-12" }));
+      return { export: normalizeExport(spec2, { dialect: "draft-2020-12" }), types: types2, errors };
+    }
     const { declaration, resolvedSymbol, isTypeOnly } = resolveExportTarget(targetSymbol, checker);
     if (!declaration) {
+      const externalPackage = detectExternalPackage(targetSymbol, checker);
+      if (externalPackage) {
+        const stub = {
+          id: exportName,
+          name: exportName,
+          kind: "external",
+          source: { package: externalPackage }
+        };
+        return { export: stub, types: [], errors };
+      }
       return { export: null, types: [], errors: [`No declaration found for '${exportName}'`] };
     }
     let spec = serializeDeclaration(declaration, targetSymbol, resolvedSymbol, exportName, ctx, isTypeOnly);
     if (!spec) {
+      const externalPackage = detectExternalPackage(targetSymbol, checker);
+      if (externalPackage) {
+        const stub = {
+          id: exportName,
+          name: exportName,
+          kind: "external",
+          source: { package: externalPackage }
+        };
+        return { export: stub, types: [], errors };
+      }
       return { export: null, types: [], errors: [`Could not serialize '${exportName}'`] };
     }
     spec = normalizeExport(spec, { dialect: "draft-2020-12" });
@@ -4571,17 +4748,27 @@ function serializeDeclaration(declaration, _exportSymbol, _targetSymbol, exportN
   } else if (ts11.isVariableDeclaration(declaration)) {
     const varStatement = declaration.parent?.parent;
     if (varStatement && ts11.isVariableStatement(varStatement)) {
-      if (declaration.initializer && ts11.isArrowFunction(declaration.initializer)) {
+      if (declaration.initializer && (ts11.isArrowFunction(declaration.initializer) || ts11.isFunctionExpression(declaration.initializer))) {
         const varName = ts11.isIdentifier(declaration.name) ? declaration.name.text : declaration.name.getText();
         result = serializeFunctionExport(declaration.initializer, ctx, varName);
       } else {
-        result = serializeVariable(declaration, varStatement, ctx);
+        const checker = ctx.program.getTypeChecker();
+        const varType = checker.getTypeAtLocation(declaration);
+        if (varType.getCallSignatures().length > 0) {
+          result = serializeVariable(declaration, varStatement, ctx);
+          if (result)
+            result = { ...result, kind: "function" };
+        } else {
+          result = serializeVariable(declaration, varStatement, ctx);
+        }
       }
     }
+  } else if (ts11.isNamespaceExport(declaration) || ts11.isModuleDeclaration(declaration) || ts11.isNamespaceImport(declaration) || ts11.isSourceFile(declaration)) {
+    result = serializeNamespaceForGet(_exportSymbol, exportName, ctx);
   }
   if (result) {
     if (result.name !== exportName) {
-      result = { ...result, id: exportName, name: result.name };
+      result = { ...result, id: exportName, name: exportName };
     }
     if (isTypeOnly) {
       result = { ...result, flags: { ...result.flags ?? {}, typeOnly: true } };
@@ -4589,6 +4776,65 @@ function serializeDeclaration(declaration, _exportSymbol, _targetSymbol, exportN
   }
   return result;
 }
+function serializeNamespaceForGet(symbol, exportName, ctx) {
+  const checker = ctx.program.getTypeChecker();
+  let targetSymbol = symbol;
+  if (symbol.flags & ts11.SymbolFlags.Alias) {
+    const aliased = checker.getAliasedSymbol(symbol);
+    if (aliased && aliased !== symbol) {
+      targetSymbol = aliased;
+    }
+  }
+  const members = [];
+  try {
+    const nsExports = checker.getExportsOfModule(targetSymbol);
+    for (const memberSymbol of nsExports) {
+      const memberName = memberSymbol.getName();
+      const memberDecls = memberSymbol.declarations ?? [];
+      const memberDecl = memberSymbol.valueDeclaration || memberDecls[0];
+      if (memberDecl) {
+        const type = checker.getTypeAtLocation(memberDecl);
+        const kind = getExportKind(memberDecl, type);
+        members.push({ name: memberName, kind });
+      }
+    }
+  } catch {}
+  return {
+    id: exportName,
+    name: exportName,
+    kind: "namespace",
+    tags: [],
+    ...members.length > 0 ? { members } : {}
+  };
+}
+function detectExternalPackage(symbol, checker) {
+  let targetSymbol = symbol;
+  if (symbol.flags & ts11.SymbolFlags.Alias) {
+    const aliased = checker.getAliasedSymbol(symbol);
+    if (aliased && aliased !== symbol) {
+      targetSymbol = aliased;
+    }
+  }
+  const allDecls = [...targetSymbol.declarations ?? [], ...symbol.declarations ?? []];
+  for (const decl of allDecls) {
+    const sf = decl.getSourceFile();
+    if (sf?.fileName.includes("node_modules")) {
+      const match = sf.fileName.match(/node_modules\/(@[^/]+\/[^/]+|[^/]+)/);
+      if (match)
+        return match[1];
+    }
+    if (ts11.isExportSpecifier(decl)) {
+      const exportDecl = decl.parent?.parent;
+      if (exportDecl && ts11.isExportDeclaration(exportDecl) && exportDecl.moduleSpecifier) {
+        const moduleText = exportDecl.moduleSpecifier.text;
+        if (!moduleText.startsWith(".") && !moduleText.startsWith("/")) {
+          return moduleText;
+        }
+      }
+    }
+  }
+  return;
+}
 // src/primitives/list.ts
 import * as path4 from "node:path";
 import ts12 from "typescript";
@@ -4599,12 +4845,12 @@ async function listExports(options) {
   const result = createProgram({ entryFile, baseDir, content });
   const { program, sourceFile } = result;
   if (!sourceFile) {
-    return { exports: [], errors: [`Could not load source file: ${entryFile}`] };
+    return { exports: [], errors: [`Entry file not found: ${entryFile}. Specify with: drift list src/index.ts`] };
   }
   const checker = program.getTypeChecker();
   const moduleSymbol = checker.getSymbolAtLocation(sourceFile);
   if (!moduleSymbol) {
-    return { exports: [], errors: ["Could not get module symbol"] };
+    return { exports: [], errors: [`No exports found in ${entryFile}. Is this the right entry point?`] };
   }
   const exportedSymbols = checker.getExportsOfModule(moduleSymbol);
   for (const symbol of exportedSymbols) {
@@ -4632,8 +4878,15 @@ function extractExportItem(symbol, checker, entryFile, entrySourceFile) {
   }
   const declarations = targetSymbol.declarations ?? [];
   const declaration = targetSymbol.valueDeclaration || declarations.find((d) => d.kind !== ts12.SyntaxKind.ExportSpecifier) || declarations[0];
-  if (!declaration)
-    return null;
+  if (!declaration) {
+    return {
+      name,
+      kind: "external",
+      file: "<external>",
+      line: 0,
+      reexport: true
+    };
+  }
   if (ts12.isSourceFile(declaration)) {
     return {
       name,
@@ -5803,7 +6056,7 @@ async function extract(options) {
     if (!sourceFile) {
       return {
         spec: createEmptySpec(entryFile, includeSchema, isDtsSource),
-        diagnostics: [{ message: `Could not load source file: ${entryFile}`, severity: "error" }]
+        diagnostics: [{ message: `Entry file not found: ${entryFile}. Specify with: drift list src/index.ts`, severity: "error" }]
       };
     }
     const typeChecker = program.getTypeChecker();
@@ -5811,7 +6064,7 @@ async function extract(options) {
     if (!moduleSymbol) {
       return {
         spec: createEmptySpec(entryFile, includeSchema, isDtsSource),
-        diagnostics: [{ message: "Could not get module symbol", severity: "warning" }]
+        diagnostics: [{ message: `No exports found in ${entryFile}. Is this the right entry point?`, severity: "warning" }]
       };
     }
     const exportedSymbols = typeChecker.getExportsOfModule(moduleSymbol);
@@ -6091,11 +6344,17 @@ function serializeDeclaration2(declaration, exportSymbol, exportName, ctx, isTyp
   } else if (ts16.isVariableDeclaration(declaration)) {
     const varStatement = declaration.parent?.parent;
     if (varStatement && ts16.isVariableStatement(varStatement)) {
-      if (declaration.initializer && ts16.isArrowFunction(declaration.initializer)) {
+      if (declaration.initializer && (ts16.isArrowFunction(declaration.initializer) || ts16.isFunctionExpression(declaration.initializer))) {
         const varName = ts16.isIdentifier(declaration.name) ? declaration.name.text : declaration.name.getText();
         result = serializeFunctionExport(declaration.initializer, ctx, varName);
       } else {
         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 if (ts16.isNamespaceExport(declaration) || ts16.isModuleDeclaration(declaration) || ts16.isNamespaceImport(declaration) || ts16.isSourceFile(declaration)) {
@@ -6120,6 +6379,12 @@ function serializeDeclaration2(declaration, exportSymbol, exportName, ctx, isTyp
         flags: { ...result.flags ?? {}, typeOnly: true }
       };
     }
+    if (!result.deprecated) {
+      const { deprecated, reason: deprecationReason } = isSymbolDeprecated(exportSymbol);
+      if (deprecated) {
+        result = { ...result, deprecated: true, deprecationReason };
+      }
+    }
   }
   return result;
 }
@@ -6167,7 +6432,7 @@ function serializeNamespaceMember(symbol, memberName, ctx) {
     return null;
   const type = checker.getTypeAtLocation(declaration);
   const callSignatures = type.getCallSignatures();
-  const deprecated = isSymbolDeprecated(targetSymbol);
+  const { deprecated } = isSymbolDeprecated(targetSymbol);
   let kind = "variable";
   if (ts16.isFunctionDeclaration(declaration) || ts16.isFunctionExpression(declaration)) {
     kind = "function";
@@ -6446,8 +6711,10 @@ export {
   arktypeAdapter,
   analyzeSpec,
   TypeRegistry,
+  STRING_PROTOTYPE_METHODS,
   QueryBuilder,
   PRIMITIVES,
+  NUMBER_PROTOTYPE_METHODS,
   CacheManager,
   CONFIG_FILENAME,
   BUILTIN_TYPE_SCHEMAS,

package/package.json

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