@openpkg-ts/extract 0.22.0 → 0.23.0

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-nymjpc96.js";
+} from "../shared/chunk-y5d5qgyt.js";
 
 // src/cli/spec.ts
 import * as fs from "node:fs";

package/dist/shared/{chunk-nymjpc96.js → chunk-y5d5qgyt.js}

@@ -125,9 +125,15 @@ function buildSchema(type, checker, ctx, _depth = 0) {
       return buildFunctionSchema(callSignatures, checker, ctx);
     }
     const symbol2 = type.getSymbol() || type.aliasSymbol;
-    if (symbol2) {
+    if (symbol2 && !isAnonymous(type)) {
       return { $ref: `#/types/${symbol2.getName()}` };
     }
+    if (type.flags & ts.TypeFlags.Object) {
+      const properties = type.getProperties();
+      if (properties.length > 0) {
+        return buildObjectSchema(properties, checker, ctx);
+      }
+    }
     return { type: checker.typeToString(type) };
   }
   if (ctx && type.flags & ts.TypeFlags.Object) {
@@ -1498,6 +1504,169 @@ function serializeTypeAlias(node, ctx) {
   };
 }
 
+// src/schema/registry.ts
+function isTypeReference(type) {
+  return !!(type.flags & 524288 && type.objectFlags && type.objectFlags & 4);
+}
+function getNonNullableType(type) {
+  if (type.isUnion()) {
+    const nonNullable = type.types.filter((t) => !(t.flags & 32768) && !(t.flags & 65536));
+    if (nonNullable.length === 1) {
+      return nonNullable[0];
+    }
+  }
+  return type;
+}
+var adapters = [];
+function registerAdapter(adapter) {
+  adapters.push(adapter);
+}
+function findAdapter(type, checker) {
+  return adapters.find((a) => a.matches(type, checker));
+}
+function isSchemaType(type, checker) {
+  return adapters.some((a) => a.matches(type, checker));
+}
+function extractSchemaType(type, checker) {
+  const adapter = findAdapter(type, checker);
+  if (!adapter)
+    return null;
+  const outputType = adapter.extractOutputType(type, checker);
+  if (!outputType)
+    return null;
+  const inputType = adapter.extractInputType?.(type, checker) ?? undefined;
+  return {
+    adapter,
+    outputType,
+    inputType
+  };
+}
+
+// src/schema/adapters/arktype.ts
+var ARKTYPE_TYPE_PATTERN = /^Type</;
+var arktypeAdapter = {
+  id: "arktype",
+  packages: ["arktype"],
+  matches(type, checker) {
+    const typeName = checker.typeToString(type);
+    return ARKTYPE_TYPE_PATTERN.test(typeName);
+  },
+  extractOutputType(type, checker) {
+    if (!isTypeReference(type)) {
+      return null;
+    }
+    const args = checker.getTypeArguments(type);
+    if (args.length < 1) {
+      return null;
+    }
+    return args[0];
+  },
+  extractInputType(type, checker) {
+    if (!isTypeReference(type)) {
+      return null;
+    }
+    const args = checker.getTypeArguments(type);
+    if (args.length < 2) {
+      return null;
+    }
+    return args[1];
+  }
+};
+
+// src/schema/adapters/typebox.ts
+var TYPEBOX_TYPE_PATTERN = /^T[A-Z]/;
+var typeboxAdapter = {
+  id: "typebox",
+  packages: ["@sinclair/typebox"],
+  matches(type, checker) {
+    const typeName = checker.typeToString(type);
+    if (!TYPEBOX_TYPE_PATTERN.test(typeName)) {
+      return false;
+    }
+    const typeProperty = type.getProperty("type");
+    return typeProperty !== undefined;
+  },
+  extractOutputType(type, checker) {
+    const staticSymbol = type.getProperty("static");
+    if (staticSymbol) {
+      return checker.getTypeOfSymbol(staticSymbol);
+    }
+    return null;
+  }
+};
+
+// src/schema/adapters/valibot.ts
+var VALIBOT_TYPE_PATTERN = /Schema(<|$)/;
+var valibotAdapter = {
+  id: "valibot",
+  packages: ["valibot"],
+  matches(type, checker) {
+    const typeName = checker.typeToString(type);
+    return VALIBOT_TYPE_PATTERN.test(typeName) && !typeName.includes("Zod");
+  },
+  extractOutputType(type, checker) {
+    const typesSymbol = type.getProperty("~types");
+    if (!typesSymbol) {
+      return null;
+    }
+    let typesType = checker.getTypeOfSymbol(typesSymbol);
+    typesType = getNonNullableType(typesType);
+    const outputSymbol = typesType.getProperty("output");
+    if (!outputSymbol) {
+      return null;
+    }
+    return checker.getTypeOfSymbol(outputSymbol);
+  },
+  extractInputType(type, checker) {
+    const typesSymbol = type.getProperty("~types");
+    if (!typesSymbol) {
+      return null;
+    }
+    let typesType = checker.getTypeOfSymbol(typesSymbol);
+    typesType = getNonNullableType(typesType);
+    const inputSymbol = typesType.getProperty("input");
+    if (!inputSymbol) {
+      return null;
+    }
+    return checker.getTypeOfSymbol(inputSymbol);
+  }
+};
+
+// src/schema/adapters/zod.ts
+var ZOD_TYPE_PATTERN = /^Zod[A-Z]/;
+var zodAdapter = {
+  id: "zod",
+  packages: ["zod"],
+  matches(type, checker) {
+    const typeName = checker.typeToString(type);
+    return ZOD_TYPE_PATTERN.test(typeName);
+  },
+  extractOutputType(type, checker) {
+    const outputSymbol = type.getProperty("_output");
+    if (outputSymbol) {
+      return checker.getTypeOfSymbol(outputSymbol);
+    }
+    const typeSymbol = type.getProperty("_type");
+    if (typeSymbol) {
+      return checker.getTypeOfSymbol(typeSymbol);
+    }
+    return null;
+  },
+  extractInputType(type, checker) {
+    const inputSymbol = type.getProperty("_input");
+    if (inputSymbol) {
+      return checker.getTypeOfSymbol(inputSymbol);
+    }
+    return null;
+  }
+};
+
+// src/schema/adapters/index.ts
+registerAdapter(zodAdapter);
+registerAdapter(valibotAdapter);
+registerAdapter(arktypeAdapter);
+registerAdapter(typeboxAdapter);
+
 // src/serializers/variables.ts
 function serializeVariable(node, statement, ctx) {
   const symbol = ctx.typeChecker.getSymbolAtLocation(node.name);
@@ -1508,8 +1677,14 @@ function serializeVariable(node, statement, ctx) {
   const { description, tags, examples } = getJSDocComment(statement);
   const source = getSourceLocation(node, declSourceFile);
   const type = ctx.typeChecker.getTypeAtLocation(node);
-  registerReferencedTypes(type, ctx);
-  const schema = buildSchema(type, ctx.typeChecker, ctx);
+  const schemaExtraction = extractSchemaType(type, ctx.typeChecker);
+  const typeToSerialize = schemaExtraction?.outputType ?? type;
+  registerReferencedTypes(typeToSerialize, ctx);
+  const schema = buildSchema(typeToSerialize, ctx.typeChecker, ctx);
+  const flags = schemaExtraction ? {
+    schemaLibrary: schemaExtraction.adapter.id,
+    ...schemaExtraction.inputType && schemaExtraction.inputType !== schemaExtraction.outputType ? { hasTransform: true } : {}
+  } : undefined;
   return {
     id: name,
     name,
@@ -1518,6 +1693,7 @@ function serializeVariable(node, statement, ctx) {
     tags,
     source,
     schema,
+    ...flags ? { flags } : {},
     ...examples.length > 0 ? { examples } : {}
   };
 }
@@ -1980,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";
@@ -2231,12 +2824,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(),
@@ -2577,4 +3172,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, 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

@@ -1,26 +1,37 @@
 import {
   BUILTIN_TYPE_SCHEMAS,
   TypeRegistry,
+  arktypeAdapter,
   buildSchema,
   createProgram,
   deduplicateSchemas,
   detectTsRuntime,
   extract,
   extractParameters,
+  extractSchemaType,
   extractStandardSchemas,
   extractStandardSchemasFromProject,
   extractStandardSchemasFromTs,
   extractTypeParameters,
+  findAdapter,
   findDiscriminatorProperty,
   getJSDocComment,
+  getNonNullableType,
   getParamDescription,
   getSourceLocation,
   isAnonymous,
   isBuiltinGeneric,
   isPrimitiveName,
   isPureRefSchema,
+  isSchemaType,
   isStandardJSONSchema,
   isSymbolDeprecated,
+  isTypeReference,
+  normalizeExport,
+  normalizeMembers,
+  normalizeSchema,
+  normalizeType,
+  registerAdapter,
   registerReferencedTypes,
   resolveCompiledPath,
   schemaIsAny,
@@ -31,170 +42,11 @@ import {
   serializeInterface,
   serializeTypeAlias,
   serializeVariable,
-  withDescription
-} from "../shared/chunk-nymjpc96.js";
-// src/schema/registry.ts
-function isTypeReference(type) {
-  return !!(type.flags & 524288 && type.objectFlags && type.objectFlags & 4);
-}
-function getNonNullableType(type) {
-  if (type.isUnion()) {
-    const nonNullable = type.types.filter((t) => !(t.flags & 32768) && !(t.flags & 65536));
-    if (nonNullable.length === 1) {
-      return nonNullable[0];
-    }
-  }
-  return type;
-}
-var adapters = [];
-function registerAdapter(adapter) {
-  adapters.push(adapter);
-}
-function findAdapter(type, checker) {
-  return adapters.find((a) => a.matches(type, checker));
-}
-function isSchemaType(type, checker) {
-  return adapters.some((a) => a.matches(type, checker));
-}
-function extractSchemaType(type, checker) {
-  const adapter = findAdapter(type, checker);
-  if (!adapter)
-    return null;
-  const outputType = adapter.extractOutputType(type, checker);
-  if (!outputType)
-    return null;
-  const inputType = adapter.extractInputType?.(type, checker) ?? undefined;
-  return {
-    adapter,
-    outputType,
-    inputType
-  };
-}
-
-// src/schema/adapters/arktype.ts
-var ARKTYPE_TYPE_PATTERN = /^Type</;
-var arktypeAdapter = {
-  id: "arktype",
-  packages: ["arktype"],
-  matches(type, checker) {
-    const typeName = checker.typeToString(type);
-    return ARKTYPE_TYPE_PATTERN.test(typeName);
-  },
-  extractOutputType(type, checker) {
-    if (!isTypeReference(type)) {
-      return null;
-    }
-    const args = checker.getTypeArguments(type);
-    if (args.length < 1) {
-      return null;
-    }
-    return args[0];
-  },
-  extractInputType(type, checker) {
-    if (!isTypeReference(type)) {
-      return null;
-    }
-    const args = checker.getTypeArguments(type);
-    if (args.length < 2) {
-      return null;
-    }
-    return args[1];
-  }
-};
-
-// src/schema/adapters/typebox.ts
-var TYPEBOX_TYPE_PATTERN = /^T[A-Z]/;
-var typeboxAdapter = {
-  id: "typebox",
-  packages: ["@sinclair/typebox"],
-  matches(type, checker) {
-    const typeName = checker.typeToString(type);
-    if (!TYPEBOX_TYPE_PATTERN.test(typeName)) {
-      return false;
-    }
-    const typeProperty = type.getProperty("type");
-    return typeProperty !== undefined;
-  },
-  extractOutputType(type, checker) {
-    const staticSymbol = type.getProperty("static");
-    if (staticSymbol) {
-      return checker.getTypeOfSymbol(staticSymbol);
-    }
-    return null;
-  }
-};
-
-// src/schema/adapters/valibot.ts
-var VALIBOT_TYPE_PATTERN = /Schema(<|$)/;
-var valibotAdapter = {
-  id: "valibot",
-  packages: ["valibot"],
-  matches(type, checker) {
-    const typeName = checker.typeToString(type);
-    return VALIBOT_TYPE_PATTERN.test(typeName) && !typeName.includes("Zod");
-  },
-  extractOutputType(type, checker) {
-    const typesSymbol = type.getProperty("~types");
-    if (!typesSymbol) {
-      return null;
-    }
-    let typesType = checker.getTypeOfSymbol(typesSymbol);
-    typesType = getNonNullableType(typesType);
-    const outputSymbol = typesType.getProperty("output");
-    if (!outputSymbol) {
-      return null;
-    }
-    return checker.getTypeOfSymbol(outputSymbol);
-  },
-  extractInputType(type, checker) {
-    const typesSymbol = type.getProperty("~types");
-    if (!typesSymbol) {
-      return null;
-    }
-    let typesType = checker.getTypeOfSymbol(typesSymbol);
-    typesType = getNonNullableType(typesType);
-    const inputSymbol = typesType.getProperty("input");
-    if (!inputSymbol) {
-      return null;
-    }
-    return checker.getTypeOfSymbol(inputSymbol);
-  }
-};
-
-// src/schema/adapters/zod.ts
-var ZOD_TYPE_PATTERN = /^Zod[A-Z]/;
-var zodAdapter = {
-  id: "zod",
-  packages: ["zod"],
-  matches(type, checker) {
-    const typeName = checker.typeToString(type);
-    return ZOD_TYPE_PATTERN.test(typeName);
-  },
-  extractOutputType(type, checker) {
-    const outputSymbol = type.getProperty("_output");
-    if (outputSymbol) {
-      return checker.getTypeOfSymbol(outputSymbol);
-    }
-    const typeSymbol = type.getProperty("_type");
-    if (typeSymbol) {
-      return checker.getTypeOfSymbol(typeSymbol);
-    }
-    return null;
-  },
-  extractInputType(type, checker) {
-    const inputSymbol = type.getProperty("_input");
-    if (inputSymbol) {
-      return checker.getTypeOfSymbol(inputSymbol);
-    }
-    return null;
-  }
-};
-
-// src/schema/adapters/index.ts
-registerAdapter(zodAdapter);
-registerAdapter(valibotAdapter);
-registerAdapter(arktypeAdapter);
-registerAdapter(typeboxAdapter);
+  typeboxAdapter,
+  valibotAdapter,
+  withDescription,
+  zodAdapter
+} from "../shared/chunk-y5d5qgyt.js";
 // src/types/utils.ts
 function isExported(node) {
   const modifiers = node.modifiers;
@@ -225,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.0",
+  "version": "0.23.0",
   "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",