@openpkg-ts/spec 0.2.2 → 0.3.0

package/README.md

@@ -1,33 +1,43 @@
 # @openpkg-ts/spec
 
-Canonical schema, TypeScript types, validation, normalization, deref, diff, and migration helpers for OpenPkg specs.
+OpenPkg schema, types, validation, and diffing utilities.
 
 ## Install
+
 ```bash
 npm install @openpkg-ts/spec
 ```
 
-## Quick Helpers
-```ts
-import { normalize, validateSpec } from '@openpkg-ts/spec';
+## Usage
+
+```typescript
+import { validateSpec, normalize, diffSpec } from '@openpkg-ts/spec';
 
-const normalized = normalize(spec);
-const result = validateSpec(normalized);
+// Validate
+const result = validateSpec(normalize(spec));
 if (!result.ok) {
-  throw new Error(result.errors.map((e) => `${e.instancePath || '/'} ${e.message}`).join('\n'));
+  console.error(result.errors);
 }
+
+// Diff two specs
+const diff = diffSpec(oldSpec, newSpec);
+console.log(`Coverage delta: ${diff.coverageDelta}%`);
 ```
 
-```ts
-import { dereference, diffSpec } from '@openpkg-ts/spec';
+## Exports
 
-const left = dereference(specA);
-const right = dereference(specB);
-const diff = diffSpec(left, right);
-```
+- `validateSpec` / `assertSpec` - Schema validation
+- `normalize` - Ensure consistent structure
+- `dereference` - Resolve `$ref` pointers
+- `diffSpec` - Compare specs
+
+## Documentation
+
+- [Spec Overview](../../docs/spec/overview.md)
+- [Types Reference](../../docs/spec/types.md)
+- [Drift Types](../../docs/spec/drift-types.md)
+- [Diffing](../../docs/spec/diffing.md)
 
-## See Also
-- [SDK generator](../sdk/README.md)
-- [CLI usage](../cli/README.md)
+## License
 
-MIT License
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpkg-ts/spec",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Shared schema, validation, and diff utilities for OpenPkg specs",
   "keywords": [
     "openpkg",

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

@@ -86,7 +86,12 @@
             "optionality-mismatch",
             "deprecated-mismatch",
             "visibility-mismatch",
+            "async-mismatch",
+            "property-type-drift",
             "example-drift",
+            "example-syntax-error",
+            "example-runtime-error",
+            "example-assertion-failed",
             "broken-link"
           ]
         },
@@ -153,6 +158,10 @@
           "type": "string",
           "description": "UI-friendly label"
         },
+        "alias": {
+          "type": "string",
+          "description": "Export alias if re-exported with a different name (id uses alias, name uses original)"
+        },
         "category": {
           "type": "string",
           "description": "Grouping hint for navigation"
@@ -164,7 +173,7 @@
         "kind": {
           "type": "string",
           "description": "Kind of export",
-          "enum": ["function", "class", "variable", "interface", "type", "enum"]
+          "enum": ["function", "class", "variable", "interface", "type", "enum", "namespace", "external"]
         },
         "description": {
           "type": "string",
@@ -193,6 +202,15 @@
           "description": "Class/interface/enum members",
           "items": { "type": "object" }
         },
+        "extends": {
+          "type": "string",
+          "description": "Base class or interface that this class/interface extends"
+        },
+        "implements": {
+          "type": "array",
+          "description": "Interfaces implemented by this class",
+          "items": { "type": "string" }
+        },
         "tags": {
           "type": "array",
           "description": "JSDoc/TSDoc tags",
@@ -235,6 +253,10 @@
           "type": "string",
           "description": "UI-friendly label"
         },
+        "alias": {
+          "type": "string",
+          "description": "Export alias if re-exported with a different name (id uses alias, name uses original)"
+        },
         "category": {
           "type": "string",
           "description": "Grouping hint for navigation"
@@ -246,7 +268,7 @@
         "kind": {
           "type": "string",
           "description": "Kind of type definition",
-          "enum": ["interface", "type", "enum", "class"]
+          "enum": ["interface", "type", "enum", "class", "external"]
         },
         "description": {
           "type": "string",
@@ -264,6 +286,15 @@
           "description": "Members for classes/interfaces/enums",
           "items": { "type": "object" }
         },
+        "extends": {
+          "type": "string",
+          "description": "Base class or interface that this class/interface extends"
+        },
+        "implements": {
+          "type": "array",
+          "description": "Interfaces implemented by this class",
+          "items": { "type": "string" }
+        },
         "tags": {
           "type": "array",
           "description": "JSDoc/TSDoc tags",
@@ -318,6 +349,13 @@
         "description": {
           "type": "string",
           "description": "Parameter description"
+        },
+        "default": {
+          "description": "Default value for the parameter"
+        },
+        "rest": {
+          "type": "boolean",
+          "description": "Whether this is a rest parameter (...args)"
         }
       }
     },

package/dist/index.d.ts

@@ -1,148 +0,0 @@
-declare const SCHEMA_VERSION = "0.2.0";
-declare const SCHEMA_URL = "https://unpkg.com/@openpkg-ts/spec/schemas/v0.2.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 SpecDocSignal = "description" | "params" | "returns" | "examples";
-type SpecDocDrift = {
-	type: "param-mismatch" | "param-type-mismatch" | "return-type-mismatch" | "generic-constraint-mismatch" | "optionality-mismatch" | "deprecated-mismatch" | "visibility-mismatch" | "example-drift" | "broken-link";
-	target?: string;
-	issue: string;
-	suggestion?: string;
-};
-type SpecVisibility = "public" | "protected" | "private";
-type SpecDocsMetadata = {
-	coverageScore?: number;
-	missing?: SpecDocSignal[];
-	drift?: SpecDocDrift[];
-};
-type SpecTypeParameter = {
-	name: string;
-	constraint?: string;
-	default?: string;
-};
-type SpecSignatureParameter = {
-	name: string;
-	required?: boolean;
-	description?: string;
-	schema: SpecSchema;
-};
-type SpecSignatureReturn = {
-	schema: SpecSchema;
-	description?: string;
-	tsType?: string;
-};
-type SpecSignature = {
-	parameters?: SpecSignatureParameter[];
-	returns?: SpecSignatureReturn;
-	description?: string;
-	typeParameters?: SpecTypeParameter[];
-};
-type SpecMember = {
-	id?: string;
-	name?: string;
-	kind?: string;
-	description?: string;
-	tags?: SpecTag[];
-	visibility?: SpecVisibility;
-	flags?: Record<string, unknown>;
-	schema?: SpecSchema;
-	signatures?: SpecSignature[];
-};
-type SpecExportKind = "function" | "class" | "variable" | "interface" | "type" | "enum" | "module" | "namespace" | "reference";
-type SpecTypeKind = "class" | "interface" | "type" | "enum";
-type SpecExport = {
-	id: string;
-	name: string;
-	slug?: string;
-	displayName?: string;
-	category?: string;
-	importPath?: string;
-	kind: SpecExportKind;
-	signatures?: SpecSignature[];
-	typeParameters?: SpecTypeParameter[];
-	members?: SpecMember[];
-	type?: string | SpecSchema;
-	schema?: SpecSchema;
-	description?: string;
-	examples?: string[];
-	docs?: SpecDocsMetadata;
-	source?: SpecSource;
-	deprecated?: boolean;
-	flags?: Record<string, unknown>;
-	tags?: SpecTag[];
-};
-type SpecType = {
-	id: string;
-	name: string;
-	slug?: string;
-	displayName?: string;
-	category?: string;
-	importPath?: 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.2.0";
-	meta: OpenPkgMeta;
-	exports: SpecExport[];
-	types?: SpecType[];
-	examples?: SpecExample[];
-	docs?: SpecDocsMetadata;
-	extensions?: SpecExtension;
-};
-declare function dereference(spec: OpenPkg): OpenPkg;
-type SpecDiff = {
-	breaking: string[];
-	nonBreaking: string[];
-	docsOnly: string[];
-	coverageDelta: number;
-	oldCoverage: number;
-	newCoverage: number;
-	newUndocumented: string[];
-	improvedExports: string[];
-	regressedExports: string[];
-	driftIntroduced: number;
-	driftResolved: number;
-};
-declare function diffSpec(oldSpec: OpenPkg, newSpec: OpenPkg): SpecDiff;
-declare function normalize(spec: OpenPkg): OpenPkg;
-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[];
-export { validateSpec, normalize, getValidationErrors, diffSpec, dereference, assertSpec, SpecVisibility, SpecTypeParameter, SpecTypeKind, SpecType, SpecTag, SpecSource, SpecSignatureReturn, SpecSignatureParameter, SpecSignature, SpecSchema, SpecMember, SpecExtension, SpecExportKind, SpecExport, SpecExample, SpecDocsMetadata, SpecDocSignal, SpecDocDrift, SCHEMA_VERSION, SCHEMA_URL, OpenPkgMeta, OpenPkg, JSON_SCHEMA_DRAFT };

package/dist/index.js

@@ -1,673 +0,0 @@
-// src/constants.ts
-var SCHEMA_VERSION = "0.2.0";
-var SCHEMA_URL = "https://unpkg.com/@openpkg-ts/spec/schemas/v0.2.0/openpkg.schema.json";
-var JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
-// 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/diff.ts
-function diffSpec(oldSpec, newSpec) {
-  const result = {
-    breaking: [],
-    nonBreaking: [],
-    docsOnly: [],
-    coverageDelta: 0,
-    oldCoverage: 0,
-    newCoverage: 0,
-    newUndocumented: [],
-    improvedExports: [],
-    regressedExports: [],
-    driftIntroduced: 0,
-    driftResolved: 0
-  };
-  diffCollections(result, oldSpec.exports, newSpec.exports);
-  diffCollections(result, oldSpec.types ?? [], newSpec.types ?? []);
-  result.oldCoverage = oldSpec.docs?.coverageScore ?? 0;
-  result.newCoverage = newSpec.docs?.coverageScore ?? 0;
-  result.coverageDelta = Math.round((result.newCoverage - result.oldCoverage) * 10) / 10;
-  const oldExportMap = toExportMap(oldSpec.exports);
-  const newExportMap = toExportMap(newSpec.exports);
-  for (const [id, newExport] of newExportMap.entries()) {
-    const oldExport = oldExportMap.get(id);
-    const newScore = newExport.docs?.coverageScore ?? 0;
-    const newDriftCount = newExport.docs?.drift?.length ?? 0;
-    if (!oldExport) {
-      if (newScore < 100 || (newExport.docs?.missing?.length ?? 0) > 0) {
-        result.newUndocumented.push(id);
-      }
-      result.driftIntroduced += newDriftCount;
-      continue;
-    }
-    const oldScore = oldExport.docs?.coverageScore ?? 0;
-    const oldDriftCount = oldExport.docs?.drift?.length ?? 0;
-    if (newScore > oldScore) {
-      result.improvedExports.push(id);
-    } else if (newScore < oldScore) {
-      result.regressedExports.push(id);
-    }
-    if (newDriftCount > oldDriftCount) {
-      result.driftIntroduced += newDriftCount - oldDriftCount;
-    } else if (oldDriftCount > newDriftCount) {
-      result.driftResolved += oldDriftCount - newDriftCount;
-    }
-  }
-  return result;
-}
-function toExportMap(exports) {
-  const map = new Map;
-  for (const exp of exports) {
-    if (exp && typeof exp.id === "string") {
-      map.set(exp.id, exp);
-    }
-  }
-  return map;
-}
-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;
-}
-// 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));
-  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/validate.ts
-import Ajv from "ajv/dist/2020.js";
-import addFormats from "ajv-formats";
-// schemas/v0.2.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.2.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.2.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"
-        }
-      }
-    },
-    exports: {
-      type: "array",
-      description: "List of exported items",
-      items: {
-        $ref: "#/$defs/export"
-      }
-    },
-    types: {
-      type: "array",
-      description: "List of type definitions",
-      items: {
-        $ref: "#/$defs/typeDef"
-      }
-    },
-    docs: {
-      $ref: "#/$defs/docsMetadata",
-      description: "Aggregate documentation coverage metadata"
-    }
-  },
-  $defs: {
-    docSignal: {
-      type: "string",
-      enum: ["description", "params", "returns", "examples"]
-    },
-    docDrift: {
-      type: "object",
-      required: ["type", "issue"],
-      properties: {
-        type: {
-          type: "string",
-          enum: [
-            "param-mismatch",
-            "param-type-mismatch",
-            "return-type-mismatch",
-            "generic-constraint-mismatch",
-            "optionality-mismatch",
-            "deprecated-mismatch",
-            "visibility-mismatch",
-            "example-drift",
-            "broken-link"
-          ]
-        },
-        target: {
-          type: "string",
-          description: "Relevant identifier (e.g., parameter name)"
-        },
-        issue: {
-          type: "string",
-          description: "Human-friendly drift explanation"
-        },
-        suggestion: {
-          type: "string",
-          description: "Optional remediation hint"
-        }
-      },
-      additionalProperties: false
-    },
-    docsMetadata: {
-      type: "object",
-      description: "Documentation coverage metadata",
-      additionalProperties: false,
-      properties: {
-        coverageScore: {
-          type: "number",
-          minimum: 0,
-          maximum: 100,
-          description: "Documentation coverage value from 0-100."
-        },
-        missing: {
-          type: "array",
-          description: "Doc components missing for this entity",
-          items: {
-            $ref: "#/$defs/docSignal"
-          },
-          uniqueItems: true
-        },
-        drift: {
-          type: "array",
-          description: "Detected documentation drift signals",
-          items: {
-            $ref: "#/$defs/docDrift"
-          }
-        }
-      }
-    },
-    export: {
-      type: "object",
-      required: ["id", "name", "kind"],
-      properties: {
-        id: {
-          type: "string",
-          description: "Unique identifier for the export"
-        },
-        name: {
-          type: "string",
-          description: "Export name"
-        },
-        slug: {
-          type: "string",
-          description: "Stable slug for linking"
-        },
-        displayName: {
-          type: "string",
-          description: "UI-friendly label"
-        },
-        category: {
-          type: "string",
-          description: "Grouping hint for navigation"
-        },
-        importPath: {
-          type: "string",
-          description: "Recommended import path"
-        },
-        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"
-          }
-        },
-        type: {
-          description: "Type reference or inline schema for variables",
-          oneOf: [{ type: "string" }, { $ref: "#/$defs/schema" }]
-        },
-        members: {
-          type: "array",
-          description: "Class/interface/enum members",
-          items: { type: "object" }
-        },
-        tags: {
-          type: "array",
-          description: "JSDoc/TSDoc tags",
-          items: {
-            type: "object",
-            required: ["name", "text"],
-            properties: {
-              name: { type: "string" },
-              text: { type: "string" }
-            },
-            additionalProperties: false
-          }
-        },
-        source: {
-          $ref: "#/$defs/sourceLocation"
-        },
-        docs: {
-          $ref: "#/$defs/docsMetadata",
-          description: "Documentation coverage metadata for this export"
-        }
-      }
-    },
-    typeDef: {
-      type: "object",
-      required: ["id", "name", "kind"],
-      properties: {
-        id: {
-          type: "string",
-          description: "Unique identifier for the type"
-        },
-        name: {
-          type: "string",
-          description: "Type name"
-        },
-        slug: {
-          type: "string",
-          description: "Stable slug for linking"
-        },
-        displayName: {
-          type: "string",
-          description: "UI-friendly label"
-        },
-        category: {
-          type: "string",
-          description: "Grouping hint for navigation"
-        },
-        importPath: {
-          type: "string",
-          description: "Recommended import path"
-        },
-        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"
-        },
-        members: {
-          type: "array",
-          description: "Members for classes/interfaces/enums",
-          items: { type: "object" }
-        },
-        tags: {
-          type: "array",
-          description: "JSDoc/TSDoc tags",
-          items: {
-            type: "object",
-            required: ["name", "text"],
-            properties: {
-              name: { type: "string" },
-              text: { type: "string" }
-            },
-            additionalProperties: false
-          }
-        },
-        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"
-        },
-        schema: {
-          $ref: "#/$defs/schema"
-        },
-        description: {
-          type: "string",
-          description: "Parameter description"
-        }
-      }
-    },
-    returns: {
-      type: "object",
-      properties: {
-        schema: {
-          $ref: "#/$defs/schema"
-        },
-        description: {
-          type: "string",
-          description: "Return value description"
-        }
-      }
-    },
-    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;
-}
-export {
-  validateSpec,
-  normalize,
-  getValidationErrors,
-  diffSpec,
-  dereference,
-  assertSpec,
-  SCHEMA_VERSION,
-  SCHEMA_URL,
-  JSON_SCHEMA_DRAFT
-};