@openpkg-ts/spec 0.1.0

package/README.md

@@ -0,0 +1,66 @@
+# @openpkg-ts/spec
+
+Shared contract for the OpenPkg specification, including versioned JSON Schema files, TypeScript types, validation helpers, and diff utilities. The package is still under construction; functionality will be filled in as the spec is extracted from the CLI and SDK.
+
+## Development
+
+```bash
+bun install
+bun run build
+```
+
+The build compiles ESM output and type declarations under `dist/`. Schemas are published verbatim from the `schemas/` directory.
+
+
+## Usage Examples
+
+### Validate & Normalize a Generated Spec
+```ts
+import { readFile } from 'node:fs/promises';
+import { normalize, validateSpec } from '@openpkg-ts/spec';
+
+const raw = await readFile('openpkg.json', 'utf8');
+const spec = JSON.parse(raw);
+const normalized = normalize(spec);
+
+const result = validateSpec(normalized);
+if (!result.ok) {
+  for (const err of result.errors) {
+    console.error(`schema: ${err.instancePath || '/'} ${err.message}`);
+  }
+  process.exit(1);
+}
+
+console.log('✅ spec is valid and normalized');
+```
+
+### Diff Two Spec Snapshots
+```ts
+import { readFile } from 'node:fs/promises';
+import { dereference, diffSpec, normalize } from '@openpkg-ts/spec';
+
+const [currentPath, nextPath] = process.argv.slice(2);
+const load = async (file: string) =>
+  dereference(normalize(JSON.parse(await readFile(file, 'utf8'))));
+
+const current = await load(currentPath);
+const next = await load(nextPath);
+const diff = diffSpec(current, next);
+
+console.log('Breaking changes:', diff.breaking);
+console.log('Non-breaking changes:', diff.nonBreaking);
+console.log('Docs-only changes:', diff.docsOnly);
+```
+
+### Assert Valid Specs in Tests
+```ts
+import { expect, test } from 'bun:test';
+import { normalize, validateSpec } from '@openpkg-ts/spec';
+import spec from '../openpkg.json' assert { type: 'json' };
+
+test('generated spec stays schema-valid', () => {
+  const normalized = normalize(spec);
+  const result = validateSpec(normalized);
+  expect(result.ok).toBe(true);
+});
+```

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+declare const SCHEMA_VERSION = "0.1.0";
+declare const SCHEMA_URL = "https://unpkg.com/@openpkg-ts/spec/schemas/v0.1.0/openpkg.schema.json";
+declare const JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
+type SpecTag = {
+	name: string
+	text: string
+};
+type SpecSource = {
+	file?: string
+	line?: number
+	url?: string
+};
+type SpecSchema = unknown;
+type SpecExample = Record<string, unknown>;
+type SpecExtension = Record<string, unknown>;
+type SpecSignatureParameter = {
+	name: string
+	required?: boolean
+	description?: string
+	schema: SpecSchema
+};
+type SpecSignatureReturn = {
+	schema: SpecSchema
+	description?: string
+};
+type SpecSignature = {
+	parameters?: SpecSignatureParameter[]
+	returns?: SpecSignatureReturn
+	description?: string
+};
+type SpecMember = unknown;
+type SpecExportKind = "function" | "class" | "variable" | "interface" | "type" | "enum" | "module" | "namespace" | "reference";
+type SpecTypeKind = "class" | "interface" | "type" | "enum";
+type SpecExport = {
+	id: string
+	name: string
+	kind: SpecExportKind
+	signatures?: SpecSignature[]
+	members?: SpecMember[]
+	type?: string | SpecSchema
+	schema?: SpecSchema
+	description?: string
+	examples?: string[]
+	source?: SpecSource
+	flags?: Record<string, unknown>
+	tags?: SpecTag[]
+};
+type SpecType = {
+	id: string
+	name: string
+	kind: SpecTypeKind
+	description?: string
+	schema?: SpecSchema
+	type?: string | SpecSchema
+	members?: SpecMember[]
+	source?: SpecSource
+	tags?: SpecTag[]
+	rawComments?: string
+};
+type OpenPkgMeta = {
+	name: string
+	version?: string
+	description?: string
+	license?: string
+	repository?: string
+	ecosystem?: string
+};
+type OpenPkg = {
+	$schema?: string
+	openpkg: "0.1.0"
+	meta: OpenPkgMeta
+	exports: SpecExport[]
+	types?: SpecType[]
+	examples?: SpecExample[]
+	extensions?: SpecExtension
+};
+type SpecError = {
+	instancePath: string
+	message: string
+	keyword: string
+};
+declare function validateSpec(spec: unknown): {
+	ok: true
+} | {
+	ok: false
+	errors: SpecError[]
+};
+declare function assertSpec(spec: unknown): asserts spec is OpenPkg;
+declare function getValidationErrors(spec: unknown): SpecError[];
+declare function normalize(spec: OpenPkg): OpenPkg;
+declare function dereference(spec: OpenPkg): OpenPkg;
+declare function migrate_0_1_0__to__0_2_0(spec: OpenPkg): OpenPkg;
+type SpecDiff = {
+	breaking: string[]
+	nonBreaking: string[]
+	docsOnly: string[]
+};
+declare function diffSpec(a: OpenPkg, b: OpenPkg): SpecDiff;
+export { validateSpec, normalize, migrate_0_1_0__to__0_2_0 as migrate, getValidationErrors, diffSpec, dereference, assertSpec, SpecTypeKind, SpecType, SpecTag, SpecSource, SpecSignatureReturn, SpecSignatureParameter, SpecSignature, SpecSchema, SpecMember, SpecExtension, SpecExportKind, SpecExport, SpecExample, SCHEMA_VERSION, SCHEMA_URL, OpenPkgMeta, OpenPkg, JSON_SCHEMA_DRAFT };

package/dist/index.js

@@ -0,0 +1,566 @@
+// src/constants.ts
+var SCHEMA_VERSION = "0.1.0";
+var SCHEMA_URL = "https://unpkg.com/@openpkg-ts/spec/schemas/v0.1.0/openpkg.schema.json";
+var JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
+// src/validate.ts
+import Ajv from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+// schemas/v0.1.0/openpkg.schema.json
+var openpkg_schema_default = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://unpkg.com/@openpkg-ts/spec/schemas/v0.1.0/openpkg.schema.json",
+  title: "OpenPkg Specification",
+  description: "Schema for OpenPkg specification files",
+  type: "object",
+  required: [
+    "openpkg",
+    "meta",
+    "exports"
+  ],
+  properties: {
+    $schema: {
+      type: "string",
+      description: "Reference to the OpenPkg schema version",
+      pattern: "^(https://raw\\.githubusercontent\\.com/ryanwaits/openpkg/main/schemas/v[0-9]+\\.[0-9]+\\.[0-9]+/openpkg\\.schema\\.json|https://unpkg\\.com/@openpkg-ts/spec/schemas/v[0-9]+\\.[0-9]+\\.[0-9]+/openpkg\\.schema\\.json)$"
+    },
+    openpkg: {
+      type: "string",
+      description: "OpenPkg specification version",
+      pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      const: "0.1.0"
+    },
+    meta: {
+      type: "object",
+      description: "Package metadata",
+      required: [
+        "name"
+      ],
+      properties: {
+        name: {
+          type: "string",
+          description: "Package name"
+        },
+        version: {
+          type: "string",
+          description: "Package version"
+        },
+        description: {
+          type: "string",
+          description: "Package description"
+        },
+        license: {
+          type: "string",
+          description: "Package license"
+        },
+        repository: {
+          type: "string",
+          description: "Repository URL"
+        },
+        ecosystem: {
+          type: "string",
+          description: "Package ecosystem",
+          enum: [
+            "js/ts",
+            "python",
+            "rust",
+            "go",
+            "java"
+          ]
+        }
+      }
+    },
+    exports: {
+      type: "array",
+      description: "List of exported items",
+      items: {
+        $ref: "#/$defs/export"
+      }
+    },
+    types: {
+      type: "array",
+      description: "List of type definitions",
+      items: {
+        $ref: "#/$defs/typeDef"
+      }
+    }
+  },
+  $defs: {
+    export: {
+      type: "object",
+      required: [
+        "id",
+        "name",
+        "kind"
+      ],
+      properties: {
+        id: {
+          type: "string",
+          description: "Unique identifier for the export"
+        },
+        name: {
+          type: "string",
+          description: "Export name"
+        },
+        kind: {
+          type: "string",
+          description: "Kind of export",
+          enum: [
+            "function",
+            "class",
+            "variable",
+            "interface",
+            "type",
+            "enum"
+          ]
+        },
+        description: {
+          type: "string",
+          description: "JSDoc/TSDoc description"
+        },
+        examples: {
+          type: "array",
+          description: "Usage examples from documentation",
+          items: {
+            type: "string"
+          }
+        },
+        signatures: {
+          type: "array",
+          description: "Function/method signatures",
+          items: {
+            $ref: "#/$defs/signature"
+          }
+        },
+        properties: {
+          type: "array",
+          description: "Class/interface properties",
+          items: {
+            $ref: "#/$defs/property"
+          }
+        },
+        source: {
+          $ref: "#/$defs/sourceLocation"
+        }
+      }
+    },
+    typeDef: {
+      type: "object",
+      required: [
+        "id",
+        "name",
+        "kind"
+      ],
+      properties: {
+        id: {
+          type: "string",
+          description: "Unique identifier for the type"
+        },
+        name: {
+          type: "string",
+          description: "Type name"
+        },
+        kind: {
+          type: "string",
+          description: "Kind of type definition",
+          enum: [
+            "interface",
+            "type",
+            "enum",
+            "class"
+          ]
+        },
+        description: {
+          type: "string",
+          description: "JSDoc/TSDoc description"
+        },
+        schema: {
+          $ref: "#/$defs/schema"
+        },
+        type: {
+          type: "string",
+          description: "Type expression for type aliases"
+        },
+        properties: {
+          type: "array",
+          description: "Properties for interfaces/classes",
+          items: {
+            $ref: "#/$defs/property"
+          }
+        },
+        source: {
+          $ref: "#/$defs/sourceLocation"
+        }
+      }
+    },
+    signature: {
+      type: "object",
+      properties: {
+        parameters: {
+          type: "array",
+          items: {
+            $ref: "#/$defs/parameter"
+          }
+        },
+        returns: {
+          $ref: "#/$defs/returns"
+        },
+        description: {
+          type: "string",
+          description: "Signature-level description"
+        }
+      }
+    },
+    parameter: {
+      type: "object",
+      required: [
+        "name",
+        "required"
+      ],
+      properties: {
+        name: {
+          type: "string",
+          description: "Parameter name"
+        },
+        required: {
+          type: "boolean",
+          description: "Whether the parameter is required"
+        },
+        description: {
+          type: "string",
+          description: "Parameter description"
+        },
+        schema: {
+          $ref: "#/$defs/schema"
+        }
+      }
+    },
+    returns: {
+      type: "object",
+      properties: {
+        schema: {
+          $ref: "#/$defs/schema"
+        },
+        description: {
+          type: "string",
+          description: "Return value description"
+        }
+      }
+    },
+    property: {
+      type: "object",
+      required: [
+        "name",
+        "required"
+      ],
+      properties: {
+        name: {
+          type: "string",
+          description: "Property name"
+        },
+        required: {
+          type: "boolean",
+          description: "Whether the property is required"
+        },
+        description: {
+          type: "string",
+          description: "Property description"
+        },
+        schema: {
+          $ref: "#/$defs/schema"
+        }
+      }
+    },
+    schema: {
+      anyOf: [
+        {
+          type: "boolean"
+        },
+        {
+          type: "object",
+          properties: {
+            $ref: {
+              type: "string",
+              description: "Reference to another type",
+              pattern: "^#/types/[A-Za-z0-9_.-]+$"
+            }
+          },
+          required: [
+            "$ref"
+          ],
+          additionalProperties: false
+        },
+        {
+          type: "object",
+          not: {
+            required: [
+              "$ref"
+            ]
+          },
+          additionalProperties: true
+        }
+      ]
+    },
+    sourceLocation: {
+      type: "object",
+      required: [
+        "file",
+        "line"
+      ],
+      properties: {
+        file: {
+          type: "string",
+          description: "Source file path"
+        },
+        line: {
+          type: "integer",
+          description: "Line number in source file",
+          minimum: 1
+        }
+      }
+    }
+  }
+};
+
+// src/validate.ts
+var ajv = new Ajv({
+  strict: false,
+  allErrors: true,
+  allowUnionTypes: true,
+  $data: true
+});
+addFormats(ajv);
+var validate = ajv.compile(openpkg_schema_default);
+function validateSpec(spec) {
+  const ok = validate(spec);
+  if (ok) {
+    return { ok: true };
+  }
+  const errors = (validate.errors ?? []).map((error) => ({
+    instancePath: error.instancePath ?? "",
+    message: error.message ?? "invalid",
+    keyword: error.keyword ?? "unknown"
+  }));
+  return {
+    ok: false,
+    errors
+  };
+}
+function assertSpec(spec) {
+  const result = validateSpec(spec);
+  if (!result.ok) {
+    const details = result.errors.map((error) => `- ${error.instancePath || "/"} ${error.message}`).join(`
+`);
+    throw new Error(`Invalid OpenPkg spec:
+${details}`);
+  }
+}
+function getValidationErrors(spec) {
+  const result = validateSpec(spec);
+  return result.ok ? [] : result.errors;
+}
+// src/normalize.ts
+var DEFAULT_ECOSYSTEM = "js/ts";
+var arrayFieldsByExport = ["signatures", "members", "examples", "tags"];
+var arrayFieldsByType = ["members", "tags"];
+function normalize(spec) {
+  const normalized = JSON.parse(JSON.stringify(spec));
+  normalized.meta = {
+    ecosystem: normalized.meta?.ecosystem ?? DEFAULT_ECOSYSTEM,
+    ...normalized.meta
+  };
+  normalized.exports = Array.isArray(normalized.exports) ? [...normalized.exports] : [];
+  normalized.exports.sort((a, b) => (a.name || "").localeCompare(b.name || ""));
+  normalized.exports = normalized.exports.map((item) => normalizeExport(item));
+  const types = Array.isArray(normalized.types) ? [...normalized.types] : [];
+  types.sort((a, b) => (a.name || "").localeCompare(b.name || ""));
+  normalized.types = types.map((item) => normalizeType(item));
+  normalized.examples = normalized.examples ?? [];
+  normalized.extensions = normalized.extensions ?? {};
+  return normalized;
+}
+function normalizeExport(item) {
+  const clone = JSON.parse(JSON.stringify(item));
+  for (const field of arrayFieldsByExport) {
+    if (!Array.isArray(clone[field])) {
+      clone[field] = [];
+    }
+  }
+  return clone;
+}
+function normalizeType(item) {
+  const clone = JSON.parse(JSON.stringify(item));
+  for (const field of arrayFieldsByType) {
+    if (!Array.isArray(clone[field])) {
+      clone[field] = [];
+    }
+  }
+  return clone;
+}
+// src/deref.ts
+function dereference(spec) {
+  const clone = JSON.parse(JSON.stringify(spec));
+  const typeLookup = buildTypeLookup(clone.types);
+  const visit = (value, seen) => {
+    if (Array.isArray(value)) {
+      return value.map((item) => visit(item, new Set(seen)));
+    }
+    if (value && typeof value === "object") {
+      const record = value;
+      const ref = readTypeRef(record);
+      if (ref) {
+        return resolveTypeRef(ref, typeLookup, seen);
+      }
+      const next = {};
+      for (const [key, nested] of Object.entries(record)) {
+        next[key] = visit(nested, seen);
+      }
+      return next;
+    }
+    return value;
+  };
+  clone.exports = clone.exports.map((item) => visit(item, new Set));
+  if (clone.types) {
+    clone.types = clone.types.map((item) => visit(item, new Set));
+  }
+  return clone;
+}
+function buildTypeLookup(types) {
+  const map = new Map;
+  if (!Array.isArray(types)) {
+    return map;
+  }
+  for (const type of types) {
+    if (type && typeof type.id === "string") {
+      map.set(type.id, type);
+    }
+  }
+  return map;
+}
+function readTypeRef(value) {
+  const ref = value["$ref"];
+  if (typeof ref !== "string") {
+    return null;
+  }
+  const prefix = "#/types/";
+  if (!ref.startsWith(prefix)) {
+    return null;
+  }
+  return ref.slice(prefix.length);
+}
+function resolveTypeRef(id, lookup, seen) {
+  if (seen.has(id)) {
+    return { $ref: `#/types/${id}` };
+  }
+  const target = lookup.get(id);
+  if (!target) {
+    return { $ref: `#/types/${id}` };
+  }
+  seen.add(id);
+  if (target.schema) {
+    return JSON.parse(JSON.stringify(target.schema));
+  }
+  return JSON.parse(JSON.stringify(target));
+}
+// src/migrate/v0_1_0__to__0_2_0.ts
+function migrate_0_1_0__to__0_2_0(spec) {
+  return spec;
+}
+// src/diff.ts
+function diffSpec(a, b) {
+  const result = { breaking: [], nonBreaking: [], docsOnly: [] };
+  diffCollections(result, a.exports, b.exports);
+  diffCollections(result, a.types ?? [], b.types ?? []);
+  return result;
+}
+function diffCollections(result, oldItems, newItems) {
+  const oldMap = toMap(oldItems);
+  const newMap = toMap(newItems);
+  for (const [id, oldItem] of oldMap.entries()) {
+    const newItem = newMap.get(id);
+    if (!newItem) {
+      result.breaking.push(id);
+      continue;
+    }
+    const docOnly = isDocOnlyChange(oldItem, newItem);
+    const identical = isDeepEqual(oldItem, newItem);
+    if (identical) {
+      continue;
+    }
+    if (docOnly) {
+      result.docsOnly.push(id);
+      continue;
+    }
+    result.breaking.push(id);
+  }
+  for (const id of newMap.keys()) {
+    if (!oldMap.has(id)) {
+      result.nonBreaking.push(id);
+    }
+  }
+}
+function toMap(items) {
+  const map = new Map;
+  for (const item of items) {
+    if (item && typeof item.id === "string") {
+      map.set(item.id, item);
+    }
+  }
+  return map;
+}
+var DOC_KEYS = new Set(["description", "examples", "tags", "source", "rawComments"]);
+function isDocOnlyChange(a, b) {
+  const structuralA = normalizeForComparison(removeDocFields(a));
+  const structuralB = normalizeForComparison(removeDocFields(b));
+  if (structuralA !== structuralB) {
+    return false;
+  }
+  const fullA = normalizeForComparison(a);
+  const fullB = normalizeForComparison(b);
+  return fullA !== fullB;
+}
+function isDeepEqual(a, b) {
+  return normalizeForComparison(a) === normalizeForComparison(b);
+}
+function removeDocFields(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => removeDocFields(item));
+  }
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  const entries = Object.entries(value).filter(([key]) => !DOC_KEYS.has(key));
+  const cleaned = {};
+  for (const [key, val] of entries) {
+    cleaned[key] = removeDocFields(val);
+  }
+  return cleaned;
+}
+function normalizeForComparison(value) {
+  return JSON.stringify(sortKeys(value));
+}
+function sortKeys(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortKeys(item));
+  }
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+  const result = {};
+  for (const [key, val] of entries) {
+    result[key] = sortKeys(val);
+  }
+  return result;
+}
+export {
+  validateSpec,
+  normalize,
+  migrate_0_1_0__to__0_2_0 as migrate,
+  getValidationErrors,
+  diffSpec,
+  dereference,
+  assertSpec,
+  SCHEMA_VERSION,
+  SCHEMA_URL,
+  JSON_SCHEMA_DRAFT
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@openpkg-ts/spec",
+  "version": "0.1.0",
+  "description": "Shared schema, validation, and diff utilities for OpenPkg specs",
+  "keywords": [
+    "openpkg",
+    "json-schema",
+    "validation",
+    "typescript",
+    "spec"
+  ],
+  "homepage": "https://github.com/openpkg/openpkg#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openpkg/openpkg.git",
+    "directory": "packages/spec"
+  },
+  "license": "MIT",
+  "author": "Ryan Waits",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "schemas"
+  ],
+  "scripts": {
+    "build": "bunup",
+    "dev": "bunup --watch",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --write src/",
+    "format": "biome format --write src/"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^20.0.0",
+    "bunup": "latest",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/schemas/v0.1.0/openpkg.schema.json

@@ -0,0 +1,314 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/@openpkg-ts/spec/schemas/v0.1.0/openpkg.schema.json",
+  "title": "OpenPkg Specification",
+  "description": "Schema for OpenPkg specification files",
+  "type": "object",
+  "required": [
+    "openpkg",
+    "meta",
+    "exports"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Reference to the OpenPkg schema version",
+      "pattern": "^(https://raw\\.githubusercontent\\.com/ryanwaits/openpkg/main/schemas/v[0-9]+\\.[0-9]+\\.[0-9]+/openpkg\\.schema\\.json|https://unpkg\\.com/@openpkg-ts/spec/schemas/v[0-9]+\\.[0-9]+\\.[0-9]+/openpkg\\.schema\\.json)$"
+    },
+    "openpkg": {
+      "type": "string",
+      "description": "OpenPkg specification version",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "const": "0.1.0"
+    },
+    "meta": {
+      "type": "object",
+      "description": "Package metadata",
+      "required": [
+        "name"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Package name"
+        },
+        "version": {
+          "type": "string",
+          "description": "Package version"
+        },
+        "description": {
+          "type": "string",
+          "description": "Package description"
+        },
+        "license": {
+          "type": "string",
+          "description": "Package license"
+        },
+        "repository": {
+          "type": "string",
+          "description": "Repository URL"
+        },
+        "ecosystem": {
+          "type": "string",
+          "description": "Package ecosystem",
+          "enum": [
+            "js/ts",
+            "python",
+            "rust",
+            "go",
+            "java"
+          ]
+        }
+      }
+    },
+    "exports": {
+      "type": "array",
+      "description": "List of exported items",
+      "items": {
+        "$ref": "#/$defs/export"
+      }
+    },
+    "types": {
+      "type": "array",
+      "description": "List of type definitions",
+      "items": {
+        "$ref": "#/$defs/typeDef"
+      }
+    }
+  },
+  "$defs": {
+    "export": {
+      "type": "object",
+      "required": [
+        "id",
+        "name",
+        "kind"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique identifier for the export"
+        },
+        "name": {
+          "type": "string",
+          "description": "Export name"
+        },
+        "kind": {
+          "type": "string",
+          "description": "Kind of export",
+          "enum": [
+            "function",
+            "class",
+            "variable",
+            "interface",
+            "type",
+            "enum"
+          ]
+        },
+        "description": {
+          "type": "string",
+          "description": "JSDoc/TSDoc description"
+        },
+        "examples": {
+          "type": "array",
+          "description": "Usage examples from documentation",
+          "items": {
+            "type": "string"
+          }
+        },
+        "signatures": {
+          "type": "array",
+          "description": "Function/method signatures",
+          "items": {
+            "$ref": "#/$defs/signature"
+          }
+        },
+        "properties": {
+          "type": "array",
+          "description": "Class/interface properties",
+          "items": {
+            "$ref": "#/$defs/property"
+          }
+        },
+        "source": {
+          "$ref": "#/$defs/sourceLocation"
+        }
+      }
+    },
+    "typeDef": {
+      "type": "object",
+      "required": [
+        "id",
+        "name",
+        "kind"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique identifier for the type"
+        },
+        "name": {
+          "type": "string",
+          "description": "Type name"
+        },
+        "kind": {
+          "type": "string",
+          "description": "Kind of type definition",
+          "enum": [
+            "interface",
+            "type",
+            "enum",
+            "class"
+          ]
+        },
+        "description": {
+          "type": "string",
+          "description": "JSDoc/TSDoc description"
+        },
+        "schema": {
+          "$ref": "#/$defs/schema"
+        },
+        "type": {
+          "type": "string",
+          "description": "Type expression for type aliases"
+        },
+        "properties": {
+          "type": "array",
+          "description": "Properties for interfaces/classes",
+          "items": {
+            "$ref": "#/$defs/property"
+          }
+        },
+        "source": {
+          "$ref": "#/$defs/sourceLocation"
+        }
+      }
+    },
+    "signature": {
+      "type": "object",
+      "properties": {
+        "parameters": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/parameter"
+          }
+        },
+        "returns": {
+          "$ref": "#/$defs/returns"
+        },
+        "description": {
+          "type": "string",
+          "description": "Signature-level description"
+        }
+      }
+    },
+    "parameter": {
+      "type": "object",
+      "required": [
+        "name",
+        "required"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Parameter name"
+        },
+        "required": {
+          "type": "boolean",
+          "description": "Whether the parameter is required"
+        },
+        "description": {
+          "type": "string",
+          "description": "Parameter description"
+        },
+        "schema": {
+          "$ref": "#/$defs/schema"
+        }
+      }
+    },
+    "returns": {
+      "type": "object",
+      "properties": {
+        "schema": {
+          "$ref": "#/$defs/schema"
+        },
+        "description": {
+          "type": "string",
+          "description": "Return value description"
+        }
+      }
+    },
+    "property": {
+      "type": "object",
+      "required": [
+        "name",
+        "required"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Property name"
+        },
+        "required": {
+          "type": "boolean",
+          "description": "Whether the property is required"
+        },
+        "description": {
+          "type": "string",
+          "description": "Property description"
+        },
+        "schema": {
+          "$ref": "#/$defs/schema"
+        }
+      }
+    },
+    "schema": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "$ref": {
+              "type": "string",
+              "description": "Reference to another type",
+              "pattern": "^#/types/[A-Za-z0-9_.-]+$"
+            }
+          },
+          "required": [
+            "$ref"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "not": {
+            "required": [
+              "$ref"
+            ]
+          },
+          "additionalProperties": true
+        }
+      ]
+    },
+    "sourceLocation": {
+      "type": "object",
+      "required": [
+        "file",
+        "line"
+      ],
+      "properties": {
+        "file": {
+          "type": "string",
+          "description": "Source file path"
+        },
+        "line": {
+          "type": "integer",
+          "description": "Line number in source file",
+          "minimum": 1
+        }
+      }
+    }
+  }
+}