@openpkg-ts/extract 0.22.1 → 0.23.1

package/README.md

@@ -1,6 +1,6 @@
 # @openpkg-ts/extract
 
-TypeScript API extraction library. Generates OpenPkg specs from TypeScript source code.
+TypeScript API extraction library. Generates OpenPkg specs from TypeScript source code with **JSON Schema 2020-12** output.
 
 ## Install
 
@@ -14,6 +14,9 @@ npm install @openpkg-ts/extract
 # Extract API spec from entry point
 tspec src/index.ts -o openpkg.json
 
+# With runtime schema extraction (Zod, Valibot, etc.)
+tspec src/index.ts --runtime
+
 # With options
 tspec src/index.ts --max-depth 4 --verbose
 ```
@@ -46,7 +49,107 @@ for (const diag of result.diagnostics) {
 | `baseDir` | `string` | cwd | Base directory for resolution |
 | `maxTypeDepth` | `number` | 4 | Max depth for type traversal |
 | `resolveExternalTypes` | `boolean` | true | Resolve types from node_modules |
-| `schemaExtraction` | `'static' \| 'hybrid'` | 'static' | Schema extraction mode |
+| `schemaExtraction` | `'static' \| 'hybrid'` | `'static'` | Schema extraction mode |
+| `schemaTarget` | `'draft-2020-12' \| 'draft-07' \| 'openapi-3.0'` | `'draft-2020-12'` | Target JSON Schema dialect |
+| `only` | `string[]` | - | Only extract these exports (supports `*` wildcards) |
+| `ignore` | `string[]` | - | Ignore these exports (supports `*` wildcards) |
+
+## JSON Schema 2020-12 Output
+
+All schema output is normalized to valid **JSON Schema 2020-12**. This ensures consistency between static TypeScript analysis and runtime schema extraction from libraries like Zod and Valibot.
+
+### Interface/Class Output Format
+
+Interfaces and classes include a `schema` property containing a JSON Schema object representation:
+
+```json
+{
+  "kind": "interface",
+  "name": "User",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "id": { "type": "string" },
+      "age": { "type": "number" },
+      "email": { "type": "string" }
+    },
+    "required": ["id", "email"]
+  },
+  "members": [...]
+}
+```
+
+### TypeScript Extension Fields (`x-ts-*`)
+
+TypeScript constructs that don't map directly to JSON Schema are preserved using extension fields:
+
+| Extension | Purpose | Example |
+|-----------|---------|---------|
+| `x-ts-type` | Preserves original TypeScript type | `{ "type": "integer", "x-ts-type": "bigint" }` |
+| `x-ts-function` | Marks function types | `{ "x-ts-function": true, "x-ts-signatures": [...] }` |
+| `x-ts-signatures` | Function/method signatures | Array of signature objects with parameters and returns |
+| `x-ts-type-arguments` | Generic type arguments | `{ "$ref": "#/types/Promise", "x-ts-type-arguments": [{ "type": "string" }] }` |
+| `x-ts-accessor` | Getter/setter markers | `{ "type": "string", "x-ts-accessor": "getter" }` |
+
+### Type Mappings
+
+| TypeScript Type | JSON Schema Output |
+|-----------------|-------------------|
+| `void` | `{ "type": "null" }` |
+| `never` | `{ "not": {} }` |
+| `any` | `{}` |
+| `unknown` | `{}` |
+| `undefined` | `{ "type": "null" }` |
+| `bigint` | `{ "type": "integer", "x-ts-type": "bigint" }` |
+| `symbol` | `{ "type": "string", "x-ts-type": "symbol" }` |
+| `[T, U]` (tuple) | `{ "type": "array", "prefixedItems": [...], "minItems": 2, "maxItems": 2 }` |
+| `() => T` (function) | `{ "x-ts-function": true, "x-ts-signatures": [...] }` |
+| `Promise<T>` | `{ "$ref": "#/types/Promise", "x-ts-type-arguments": [<T schema>] }` |
+
+### Example: Function Schema
+
+```json
+{
+  "kind": "function",
+  "name": "fetchUser",
+  "signatures": [{
+    "parameters": [{
+      "name": "id",
+      "schema": { "type": "string" },
+      "required": true
+    }],
+    "returns": {
+      "schema": {
+        "$ref": "#/types/Promise",
+        "x-ts-type-arguments": [{ "$ref": "#/types/User" }]
+      }
+    }
+  }]
+}
+```
+
+### Example: Interface with Methods
+
+```json
+{
+  "kind": "interface",
+  "name": "Repository",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "id": { "type": "string" },
+      "find": {
+        "x-ts-function": true,
+        "x-ts-signatures": [{
+          "parameters": [{ "name": "query", "schema": { "type": "string" } }],
+          "returns": { "schema": { "type": "array", "items": { "$ref": "#/types/Item" } } }
+        }]
+      }
+    },
+    "required": ["id", "find"]
+  }
+}
+```
 
 ## Exports
 
@@ -61,6 +164,12 @@ for (const diag of result.diagnostics) {
 - `TypeRegistry` - Track and dedupe extracted types
 - `serializeType` - Convert TS types to schema
 
+### Schema Normalizer
+- `normalizeSchema(schema, options)` - Convert SpecSchema to JSON Schema 2020-12
+- `normalizeExport(exp, options)` - Normalize a SpecExport including nested schemas
+- `normalizeType(type, options)` - Normalize a SpecType including nested schemas
+- `normalizeMembers(members, options)` - Convert members array to JSON Schema properties
+
 ### Schema Adapters
 - `ZodAdapter`, `ValibotAdapter` - Runtime schema extraction
 
@@ -70,7 +179,8 @@ for (const diag of result.diagnostics) {
 2. Extracts all exported symbols
 3. Serializes each export (functions, classes, types, variables)
 4. Resolves type references and builds a type registry
-5. Outputs an OpenPkg-compliant JSON spec
+5. **Normalizes all schemas to JSON Schema 2020-12**
+6. Outputs an OpenPkg-compliant JSON spec
 
 ## License
 

package/dist/bin/tspec.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   extract
-} from "../shared/chunk-7fp2zqf8.js";
+} from "../shared/chunk-qwkv7jxy.js";
 
 // src/cli/spec.ts
 import * as fs from "node:fs";

package/dist/shared/{chunk-7fp2zqf8.js → chunk-qwkv7jxy.js}

@@ -2156,6 +2156,423 @@ async function extractStandardSchemasFromProject(entryFile, baseDir, options = {
   };
 }
 
+// src/types/schema-normalizer.ts
+var SCHEMA_DIALECT_URLS = {
+  "draft-2020-12": "https://json-schema.org/draft/2020-12/schema",
+  "draft-07": "http://json-schema.org/draft-07/schema#"
+};
+var TS_PRIMITIVE_NORMALIZATIONS = {
+  void: () => ({ type: "null" }),
+  never: () => ({ not: {} }),
+  any: () => ({}),
+  unknown: () => ({}),
+  undefined: () => ({ type: "null" }),
+  bigint: () => ({ type: "integer", "x-ts-type": "bigint" }),
+  symbol: () => ({ type: "string", "x-ts-type": "symbol" })
+};
+function normalizeSchema(schema, options = {}) {
+  const { includeSchemaField = false, dialect = "draft-2020-12" } = options;
+  const normalized = normalizeSchemaInternal(schema, options);
+  if (includeSchemaField && typeof normalized === "object") {
+    return {
+      $schema: SCHEMA_DIALECT_URLS[dialect],
+      ...normalized
+    };
+  }
+  return normalized;
+}
+function normalizeSchemaInternal(schema, options) {
+  if (typeof schema === "string") {
+    return normalizeStringType(schema);
+  }
+  if (schema == null) {
+    return {};
+  }
+  if (typeof schema !== "object") {
+    return {};
+  }
+  if ("anyOf" in schema && Array.isArray(schema.anyOf)) {
+    return normalizeCombinator("anyOf", schema.anyOf, schema, options);
+  }
+  if ("allOf" in schema && Array.isArray(schema.allOf)) {
+    return normalizeCombinator("allOf", schema.allOf, schema, options);
+  }
+  if ("oneOf" in schema && Array.isArray(schema.oneOf)) {
+    return normalizeCombinator("oneOf", schema.oneOf, schema, options);
+  }
+  if ("$ref" in schema && typeof schema.$ref === "string") {
+    return normalizeRef(schema, options);
+  }
+  if ("type" in schema && typeof schema.type === "string") {
+    return normalizeTypedSchema(schema, options);
+  }
+  return normalizeGenericObject(schema, options);
+}
+function normalizeStringType(type) {
+  const specialNormalization = TS_PRIMITIVE_NORMALIZATIONS[type];
+  if (specialNormalization) {
+    return specialNormalization();
+  }
+  if (["string", "number", "boolean", "integer", "null", "object", "array"].includes(type)) {
+    return { type };
+  }
+  return { "x-ts-type": type };
+}
+function normalizeTypedSchema(schema, options) {
+  const { type } = schema;
+  const specialNormalization = TS_PRIMITIVE_NORMALIZATIONS[type];
+  if (specialNormalization) {
+    const normalized = specialNormalization();
+    return mergeSchemaFields(normalized, schema, ["type"]);
+  }
+  if (type === "function") {
+    return normalizeFunctionType(schema, options);
+  }
+  if (type === "tuple") {
+    return normalizeTupleType(schema, options);
+  }
+  if (type === "array") {
+    return normalizeArrayType(schema, options);
+  }
+  if (type === "object") {
+    return normalizeObjectType(schema, options);
+  }
+  if (["string", "number", "boolean", "integer", "null"].includes(type)) {
+    return normalizeStandardType(schema, options);
+  }
+  const result = { "x-ts-type": type };
+  return mergeSchemaFields(result, schema, ["type"]);
+}
+function normalizeFunctionType(schema, options) {
+  const result = {
+    "x-ts-function": true
+  };
+  if ("signatures" in schema && Array.isArray(schema.signatures)) {
+    result["x-ts-signatures"] = schema.signatures.map((sig) => normalizeSignature(sig, options));
+  }
+  if ("description" in schema && schema.description) {
+    result.description = schema.description;
+  }
+  return result;
+}
+function normalizeSignature(signature, options) {
+  const result = {};
+  if (signature.parameters) {
+    result.parameters = signature.parameters.map((param) => ({
+      name: param.name,
+      schema: normalizeSchemaInternal(param.schema, options),
+      ...param.required !== undefined ? { required: param.required } : {},
+      ...param.description ? { description: param.description } : {},
+      ...param.default !== undefined ? { default: param.default } : {},
+      ...param.rest ? { rest: param.rest } : {}
+    }));
+  }
+  if (signature.returns) {
+    result.returns = {
+      schema: normalizeSchemaInternal(signature.returns.schema, options),
+      ...signature.returns.description ? { description: signature.returns.description } : {}
+    };
+  }
+  if (signature.description) {
+    result.description = signature.description;
+  }
+  if (signature.typeParameters) {
+    result.typeParameters = signature.typeParameters;
+  }
+  return result;
+}
+function normalizeTupleType(schema, options) {
+  const result = { type: "array" };
+  if ("items" in schema && Array.isArray(schema.items)) {
+    result.prefixedItems = schema.items.map((item) => normalizeSchemaInternal(item, options));
+    result.minItems = schema.items.length;
+    result.maxItems = schema.items.length;
+  }
+  if ("prefixedItems" in schema && Array.isArray(schema.prefixedItems)) {
+    result.prefixedItems = schema.prefixedItems.map((item) => normalizeSchemaInternal(item, options));
+  }
+  if ("minItems" in schema && typeof schema.minItems === "number") {
+    result.minItems = schema.minItems;
+  }
+  if ("maxItems" in schema && typeof schema.maxItems === "number") {
+    result.maxItems = schema.maxItems;
+  }
+  if ("description" in schema && schema.description) {
+    result.description = schema.description;
+  }
+  return result;
+}
+function normalizeArrayType(schema, options) {
+  const result = { type: "array" };
+  if ("items" in schema && schema.items && !Array.isArray(schema.items)) {
+    result.items = normalizeSchemaInternal(schema.items, options);
+  }
+  if ("prefixedItems" in schema && Array.isArray(schema.prefixedItems)) {
+    result.prefixedItems = schema.prefixedItems.map((item) => normalizeSchemaInternal(item, options));
+  }
+  if ("minItems" in schema && typeof schema.minItems === "number") {
+    result.minItems = schema.minItems;
+  }
+  if ("maxItems" in schema && typeof schema.maxItems === "number") {
+    result.maxItems = schema.maxItems;
+  }
+  if ("description" in schema && schema.description) {
+    result.description = schema.description;
+  }
+  return result;
+}
+function normalizeObjectType(schema, options) {
+  const result = { type: "object" };
+  if ("properties" in schema && schema.properties) {
+    const properties = schema.properties;
+    result.properties = Object.fromEntries(Object.entries(properties).map(([key, value]) => [
+      key,
+      normalizeSchemaInternal(value, options)
+    ]));
+  }
+  if ("required" in schema && Array.isArray(schema.required)) {
+    result.required = schema.required;
+  }
+  if ("additionalProperties" in schema) {
+    if (typeof schema.additionalProperties === "boolean") {
+      result.additionalProperties = schema.additionalProperties;
+    } else if (schema.additionalProperties) {
+      result.additionalProperties = normalizeSchemaInternal(schema.additionalProperties, options);
+    }
+  }
+  if ("description" in schema && schema.description) {
+    result.description = schema.description;
+  }
+  return result;
+}
+function normalizeStandardType(schema, options) {
+  const result = { type: schema.type };
+  const validationKeywords = [
+    "enum",
+    "const",
+    "format",
+    "pattern",
+    "minimum",
+    "maximum",
+    "exclusiveMinimum",
+    "exclusiveMaximum",
+    "multipleOf",
+    "minLength",
+    "maxLength",
+    "description",
+    "default",
+    "examples",
+    "title"
+  ];
+  for (const keyword of validationKeywords) {
+    if (keyword in schema && schema[keyword] !== undefined) {
+      result[keyword] = schema[keyword];
+    }
+  }
+  return result;
+}
+function normalizeRef(schema, options) {
+  const result = { $ref: schema.$ref };
+  if (schema.typeArguments && schema.typeArguments.length > 0) {
+    result["x-ts-type-arguments"] = schema.typeArguments.map((arg) => normalizeSchemaInternal(arg, options));
+  }
+  return result;
+}
+function normalizeCombinator(keyword, schemas, originalSchema, options) {
+  const result = {
+    [keyword]: schemas.map((s) => normalizeSchemaInternal(s, options))
+  };
+  if ((keyword === "anyOf" || keyword === "oneOf") && "discriminator" in originalSchema && originalSchema.discriminator) {
+    result.discriminator = originalSchema.discriminator;
+  }
+  if ("description" in originalSchema && originalSchema.description) {
+    result.description = originalSchema.description;
+  }
+  return result;
+}
+function normalizeGenericObject(schema, options) {
+  const result = {};
+  for (const [key, value] of Object.entries(schema)) {
+    if (value == null)
+      continue;
+    if (isSchemaLike(value)) {
+      result[key] = normalizeSchemaInternal(value, options);
+    } else if (Array.isArray(value)) {
+      result[key] = value.map((item) => isSchemaLike(item) ? normalizeSchemaInternal(item, options) : item);
+    } else if (typeof value === "object") {
+      result[key] = normalizeGenericObject(value, options);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+function isSchemaLike(value) {
+  if (typeof value !== "object" || value == null)
+    return false;
+  if (typeof value === "string")
+    return true;
+  const obj = value;
+  return "type" in obj || "$ref" in obj || "anyOf" in obj || "allOf" in obj || "oneOf" in obj || "properties" in obj || "items" in obj || "prefixedItems" in obj;
+}
+function mergeSchemaFields(target, source, excludeKeys) {
+  if (typeof source !== "object" || source == null) {
+    return target;
+  }
+  const excludeSet = new Set(excludeKeys);
+  const result = { ...target };
+  for (const [key, value] of Object.entries(source)) {
+    if (!excludeSet.has(key) && value !== undefined) {
+      if (!(key in result)) {
+        result[key] = value;
+      }
+    }
+  }
+  return result;
+}
+function normalizeExport(exp, options = {}) {
+  const result = { ...exp };
+  if (exp.schema) {
+    result.schema = normalizeSchema(exp.schema, options);
+  }
+  if (exp.signatures) {
+    result.signatures = exp.signatures.map((sig) => normalizeSignatureSpec(sig, options));
+  }
+  if (exp.members) {
+    result.members = exp.members.map((member) => normalizeMember(member, options));
+  }
+  if (shouldGenerateMembersSchema(exp.kind) && exp.members && exp.members.length > 0) {
+    result.schema = normalizeMembers(exp.members, options);
+  }
+  return result;
+}
+function normalizeType(type, options = {}) {
+  const result = { ...type };
+  if (type.schema) {
+    result.schema = normalizeSchema(type.schema, options);
+  }
+  if (type.members) {
+    result.members = type.members.map((member) => normalizeMember(member, options));
+  }
+  if (shouldGenerateMembersSchema(type.kind) && type.members && type.members.length > 0) {
+    result.schema = normalizeMembers(type.members, options);
+  }
+  return result;
+}
+function shouldGenerateMembersSchema(kind) {
+  return kind === "interface" || kind === "class";
+}
+function normalizeSignatureSpec(signature, options) {
+  const result = { ...signature };
+  if (signature.parameters) {
+    result.parameters = signature.parameters.map((param) => ({
+      ...param,
+      schema: normalizeSchema(param.schema, options)
+    }));
+  }
+  if (signature.returns) {
+    result.returns = {
+      ...signature.returns,
+      schema: normalizeSchema(signature.returns.schema, options)
+    };
+  }
+  return result;
+}
+function normalizeMember(member, options) {
+  const result = { ...member };
+  if (member.schema) {
+    result.schema = normalizeSchema(member.schema, options);
+  }
+  if (member.signatures) {
+    result.signatures = member.signatures.map((sig) => normalizeSignatureSpec(sig, options));
+  }
+  return result;
+}
+function normalizeMembers(members, options = {}) {
+  const properties = {};
+  const required = [];
+  let additionalProperties;
+  for (const member of members) {
+    const { name, kind } = member;
+    if (kind === "index" || kind === "index-signature") {
+      additionalProperties = normalizeMemberToSchema(member, options);
+      continue;
+    }
+    if (!name)
+      continue;
+    const memberSchema = normalizeMemberToSchema(member, options);
+    properties[name] = memberSchema;
+    if (!isOptionalMember(member)) {
+      required.push(name);
+    }
+  }
+  const result = {
+    type: "object",
+    properties
+  };
+  if (required.length > 0) {
+    result.required = required;
+  }
+  if (additionalProperties !== undefined) {
+    result.additionalProperties = additionalProperties;
+  }
+  return result;
+}
+function normalizeMemberToSchema(member, options) {
+  const { kind, schema, signatures, description } = member;
+  if (kind === "method" || kind === "call-signature") {
+    return normalizeMethodMember(member, options);
+  }
+  if (kind === "getter") {
+    const baseSchema2 = schema ? normalizeSchemaInternal(schema, options) : {};
+    return {
+      ...baseSchema2,
+      "x-ts-accessor": "getter",
+      ...description ? { description } : {}
+    };
+  }
+  if (kind === "setter") {
+    const baseSchema2 = schema ? normalizeSchemaInternal(schema, options) : {};
+    return {
+      ...baseSchema2,
+      "x-ts-accessor": "setter",
+      ...description ? { description } : {}
+    };
+  }
+  if (kind === "index" || kind === "index-signature") {
+    if (schema && typeof schema === "object" && "additionalProperties" in schema) {
+      return normalizeSchemaInternal(schema.additionalProperties, options);
+    }
+    return schema ? normalizeSchemaInternal(schema, options) : {};
+  }
+  if (signatures && signatures.length > 0) {
+    return normalizeMethodMember(member, options);
+  }
+  const baseSchema = schema ? normalizeSchemaInternal(schema, options) : {};
+  return description ? { ...baseSchema, description } : baseSchema;
+}
+function normalizeMethodMember(member, options) {
+  const result = {
+    "x-ts-function": true
+  };
+  if (member.signatures && member.signatures.length > 0) {
+    result["x-ts-signatures"] = member.signatures.map((sig) => normalizeSignature(sig, options));
+  }
+  if (member.description) {
+    result.description = member.description;
+  }
+  return result;
+}
+function isOptionalMember(member) {
+  if (member.flags?.optional === true) {
+    return true;
+  }
+  if (member.name?.endsWith("?")) {
+    return true;
+  }
+  return false;
+}
+
 // src/builder/spec-builder.ts
 import * as fs2 from "node:fs";
 import * as path3 from "node:path";
@@ -2351,7 +2768,8 @@ async function extract(options) {
   }
   const meta = await getPackageMeta(entryFile, baseDir);
   const types = ctx.typeRegistry.getAll();
-  const forgottenExports = collectForgottenExports(exports, types, program, sourceFile, exportedIds);
+  const projectBaseDir = baseDir ?? path3.dirname(entryFile);
+  const forgottenExports = collectForgottenExports(exports, types, program, sourceFile, exportedIds, projectBaseDir);
   for (const forgotten of forgottenExports) {
     const refSummary = forgotten.referencedBy.slice(0, 3).map((r) => `${r.exportName} (${r.location})`).join(", ");
     const moreRefs = forgotten.referencedBy.length > 3 ? ` +${forgotten.referencedBy.length - 3} more` : "";
@@ -2382,8 +2800,8 @@ async function extract(options) {
   }
   let runtimeMetadata;
   if (options.schemaExtraction === "hybrid") {
-    const projectBaseDir = baseDir || path3.dirname(entryFile);
-    const runtimeResult = await extractStandardSchemasFromProject(entryFile, projectBaseDir, {
+    const projectBaseDir2 = baseDir || path3.dirname(entryFile);
+    const runtimeResult = await extractStandardSchemasFromProject(entryFile, projectBaseDir2, {
       target: options.schemaTarget || "draft-2020-12",
       timeout: 15000
     });
@@ -2407,12 +2825,14 @@ async function extract(options) {
       });
     }
   }
+  const normalizedExports = exports.map((exp) => normalizeExport(exp, { dialect: "draft-2020-12" }));
+  const normalizedTypes = types.map((t) => normalizeType(t, { dialect: "draft-2020-12" }));
   const spec = {
     ...includeSchema ? { $schema: SCHEMA_URL } : {},
     openpkg: SCHEMA_VERSION,
     meta,
-    exports,
-    types,
+    exports: normalizedExports,
+    types: normalizedTypes,
     generation: {
       generator: "@openpkg-ts/extract",
       timestamp: new Date().toISOString(),
@@ -2497,10 +2917,14 @@ function findTypeDefinition(typeName, program, sourceFile) {
   }
   return;
 }
-function isExternalType2(definedIn) {
+function isExternalType2(definedIn, baseDir) {
   if (!definedIn)
     return true;
-  return definedIn.includes("node_modules");
+  if (definedIn.includes("node_modules"))
+    return true;
+  const normalizedDefined = path3.resolve(definedIn);
+  const normalizedBase = path3.resolve(baseDir);
+  return !normalizedDefined.startsWith(normalizedBase);
 }
 function hasInternalTag(typeName, program, sourceFile) {
   const checker = program.getTypeChecker();
@@ -2510,7 +2934,7 @@ function hasInternalTag(typeName, program, sourceFile) {
   const jsTags = symbol.getJsDocTags();
   return jsTags.some((tag) => tag.name === "internal");
 }
-function collectForgottenExports(exports, types, program, sourceFile, exportedIds) {
+function collectForgottenExports(exports, types, program, sourceFile, exportedIds, baseDir) {
   const definedTypes = new Set(types.map((t) => t.id));
   const referencedTypes = new Map;
   for (const exp of exports) {
@@ -2540,7 +2964,7 @@ function collectForgottenExports(exports, types, program, sourceFile, exportedId
     if (exportedIds.has(typeName))
       continue;
     const definedIn = findTypeDefinition(typeName, program, sourceFile);
-    const isExternal = isExternalType2(definedIn);
+    const isExternal = isExternalType2(definedIn, baseDir);
     forgottenExports.push({
       name: typeName,
       definedIn,
@@ -2753,4 +3177,4 @@ async function getPackageMeta(entryFile, baseDir) {
   } catch {}
   return { name: path3.basename(searchDir) };
 }
-export { BUILTIN_TYPE_SCHEMAS, isPrimitiveName, isBuiltinGeneric, isAnonymous, buildSchema, isPureRefSchema, withDescription, schemaIsAny, schemasAreEqual, deduplicateSchemas, findDiscriminatorProperty, TypeRegistry, getJSDocComment, getSourceLocation, getParamDescription, extractTypeParameters, isSymbolDeprecated, createProgram, extractParameters, registerReferencedTypes, serializeClass, serializeEnum, serializeFunctionExport, serializeInterface, serializeTypeAlias, isTypeReference, getNonNullableType, registerAdapter, findAdapter, isSchemaType, extractSchemaType, arktypeAdapter, typeboxAdapter, valibotAdapter, zodAdapter, serializeVariable, isStandardJSONSchema, detectTsRuntime, extractStandardSchemasFromTs, resolveCompiledPath, extractStandardSchemas, extractStandardSchemasFromProject, extract };
+export { BUILTIN_TYPE_SCHEMAS, isPrimitiveName, isBuiltinGeneric, isAnonymous, buildSchema, isPureRefSchema, withDescription, schemaIsAny, schemasAreEqual, deduplicateSchemas, findDiscriminatorProperty, TypeRegistry, getJSDocComment, getSourceLocation, getParamDescription, extractTypeParameters, isSymbolDeprecated, createProgram, extractParameters, registerReferencedTypes, serializeClass, serializeEnum, serializeFunctionExport, serializeInterface, serializeTypeAlias, isTypeReference, getNonNullableType, registerAdapter, findAdapter, isSchemaType, extractSchemaType, arktypeAdapter, typeboxAdapter, valibotAdapter, zodAdapter, serializeVariable, isStandardJSONSchema, detectTsRuntime, extractStandardSchemasFromTs, resolveCompiledPath, extractStandardSchemas, extractStandardSchemasFromProject, normalizeSchema, normalizeExport, normalizeType, normalizeMembers, extract };

package/dist/src/index.d.ts

@@ -425,7 +425,69 @@ declare function deduplicateSchemas(schemas: SpecSchema[]): SpecSchema[];
 * A valid discriminator has a unique literal value in each union member.
 */
 declare function findDiscriminatorProperty(unionTypes: ts12.Type[], checker: ts12.TypeChecker): string | undefined;
+import { SpecSchema as SpecSchema2, SpecExport as SpecExport8, SpecType as SpecType2, SpecMember } from "@openpkg-ts/spec";
+/**
+* Options for schema normalization
+*/
+interface NormalizeOptions {
+	/** Include $schema field in output */
+	includeSchemaField?: boolean;
+	/** Target JSON Schema dialect (default: 'draft-2020-12') */
+	dialect?: "draft-2020-12" | "draft-07";
+}
+/**
+* JSON Schema 2020-12 compatible output type.
+* Uses Record<string, unknown> for flexibility since JSON Schema is highly polymorphic.
+*/
+type JSONSchema = Record<string, unknown>;
+/**
+* Normalize a SpecSchema to JSON Schema 2020-12.
+*
+* @param schema - The SpecSchema to normalize
+* @param options - Normalization options
+* @returns JSON Schema 2020-12 compatible schema
+*/
+declare function normalizeSchema(schema: SpecSchema2, options?: NormalizeOptions): JSONSchema;
+/**
+* Normalize a SpecExport, normalizing its schema and nested schemas.
+*
+* For interfaces and classes, this function will:
+* 1. Normalize any existing schema
+* 2. Normalize member schemas
+* 3. Generate a JSON Schema from members if members exist (populates `schema` field)
+*/
+declare function normalizeExport(exp: SpecExport8, options?: NormalizeOptions): SpecExport8;
+/**
+* Normalize a SpecType, normalizing its schema and nested schemas.
+*
+* For interfaces and classes, this function will:
+* 1. Normalize any existing schema
+* 2. Normalize member schemas
+* 3. Generate a JSON Schema from members if members exist (populates `schema` field)
+*/
+declare function normalizeType(type: SpecType2, options?: NormalizeOptions): SpecType2;
+/**
+* Convert a members array to JSON Schema properties format.
+*
+* This function transforms the SpecMember[] array representation used by
+* interfaces/classes into a JSON Schema 2020-12 object schema with properties,
+* required array, and additionalProperties.
+*
+* Member Kind Mappings:
+* | Member Kind        | JSON Schema Output                                    |
+* |--------------------|-------------------------------------------------------|
+* | property           | Direct schema in properties                           |
+* | method             | { "x-ts-function": true, "x-ts-signatures": [...] }   |
+* | getter             | Schema in properties (read-only via extension)        |
+* | setter             | Schema in properties (write-only via extension)       |
+* | index              | additionalProperties schema                           |
+*
+* @param members - The members array from an interface/class
+* @param options - Normalization options
+* @returns JSON Schema object with properties, required, and additionalProperties
+*/
+declare function normalizeMembers(members: SpecMember[], options?: NormalizeOptions): JSONSchema;
 import ts13 from "typescript";
 declare function isExported(node: ts13.Node): boolean;
 declare function getNodeName(node: ts13.Node): string | undefined;
-export { zodAdapter, withDescription, valibotAdapter, typeboxAdapter, serializeVariable, serializeTypeAlias, serializeInterface, serializeFunctionExport, serializeEnum, serializeClass, schemasAreEqual, schemaIsAny, resolveCompiledPath, registerReferencedTypes, registerAdapter, isTypeReference, isSymbolDeprecated, isStandardJSONSchema, isSchemaType, isPureRefSchema, isPrimitiveName, isExported, isBuiltinGeneric, isAnonymous, getSourceLocation, getParamDescription, getNonNullableType, getNodeName, getJSDocComment, findDiscriminatorProperty, findAdapter, extractTypeParameters, extractStandardSchemasFromTs, extractStandardSchemasFromProject, extractStandardSchemas, extractSchemaType, extractParameters, extract, detectTsRuntime, deduplicateSchemas, createProgram, buildSchema, arktypeAdapter, TypeRegistry, TypeReference2 as TypeReference, TsRuntime, StandardSchemaExtractionResult, StandardSchemaExtractionOutput, StandardJSONSchemaV1, StandardJSONSchemaTarget, StandardJSONSchemaOptions, SerializerContext, SchemaExtractionResult, SchemaAdapter, ProjectExtractionOutput, ProjectExtractionInfo, ProgramResult, ProgramOptions, ForgottenExport, ExtractStandardSchemasOptions, ExtractResult, ExtractOptions, ExtractFromProjectOptions, Diagnostic, BUILTIN_TYPE_SCHEMAS };
+export { zodAdapter, withDescription, valibotAdapter, typeboxAdapter, serializeVariable, serializeTypeAlias, serializeInterface, serializeFunctionExport, serializeEnum, serializeClass, schemasAreEqual, schemaIsAny, resolveCompiledPath, registerReferencedTypes, registerAdapter, normalizeType, normalizeSchema, normalizeMembers, normalizeExport, isTypeReference, isSymbolDeprecated, isStandardJSONSchema, isSchemaType, isPureRefSchema, isPrimitiveName, isExported, isBuiltinGeneric, isAnonymous, getSourceLocation, getParamDescription, getNonNullableType, getNodeName, getJSDocComment, findDiscriminatorProperty, findAdapter, extractTypeParameters, extractStandardSchemasFromTs, extractStandardSchemasFromProject, extractStandardSchemas, extractSchemaType, extractParameters, extract, detectTsRuntime, deduplicateSchemas, createProgram, buildSchema, arktypeAdapter, TypeRegistry, TypeReference2 as TypeReference, TsRuntime, StandardSchemaExtractionResult, StandardSchemaExtractionOutput, StandardJSONSchemaV1, StandardJSONSchemaTarget, StandardJSONSchemaOptions, SerializerContext, SchemaExtractionResult, SchemaAdapter, ProjectExtractionOutput, ProjectExtractionInfo, ProgramResult, ProgramOptions, NormalizeOptions, JSONSchema, ForgottenExport, ExtractStandardSchemasOptions, ExtractResult, ExtractOptions, ExtractFromProjectOptions, Diagnostic, BUILTIN_TYPE_SCHEMAS };

package/dist/src/index.js

@@ -27,6 +27,10 @@ import {
   isStandardJSONSchema,
   isSymbolDeprecated,
   isTypeReference,
+  normalizeExport,
+  normalizeMembers,
+  normalizeSchema,
+  normalizeType,
   registerAdapter,
   registerReferencedTypes,
   resolveCompiledPath,
@@ -42,7 +46,7 @@ import {
   valibotAdapter,
   withDescription,
   zodAdapter
-} from "../shared/chunk-7fp2zqf8.js";
+} from "../shared/chunk-qwkv7jxy.js";
 // src/types/utils.ts
 function isExported(node) {
   const modifiers = node.modifiers;
@@ -73,6 +77,10 @@ export {
   resolveCompiledPath,
   registerReferencedTypes,
   registerAdapter,
+  normalizeType,
+  normalizeSchema,
+  normalizeMembers,
+  normalizeExport,
   isTypeReference,
   isSymbolDeprecated,
   isStandardJSONSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpkg-ts/extract",
-  "version": "0.22.1",
+  "version": "0.23.1",
   "description": "TypeScript export extraction to OpenPkg spec",
   "keywords": [
     "openpkg",
@@ -40,7 +40,7 @@
     "format": "biome format --write src/"
   },
   "dependencies": {
-    "@openpkg-ts/spec": "^0.19.0",
+    "@openpkg-ts/spec": "^0.23.0",
     "chalk": "^5.4.1",
     "commander": "^12.0.0",
     "tree-sitter-wasms": "^0.1.13",