@openpkg-ts/spec 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,179 @@
+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" | "async-mismatch" | "property-type-drift" | "example-drift" | "example-syntax-error" | "example-runtime-error" | "example-assertion-failed" | "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" | "external";
+type SpecTypeKind = "class" | "interface" | "type" | "enum" | "external";
+type SpecExport = {
+	id: string;
+	name: string;
+	slug?: string;
+	displayName?: string;
+	alias?: 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[];
+	extends?: string;
+	implements?: string[];
+};
+type SpecType = {
+	id: string;
+	name: string;
+	slug?: string;
+	displayName?: string;
+	alias?: string;
+	category?: string;
+	importPath?: string;
+	kind: SpecTypeKind;
+	description?: string;
+	schema?: SpecSchema;
+	type?: string | SpecSchema;
+	members?: SpecMember[];
+	source?: SpecSource;
+	tags?: SpecTag[];
+	rawComments?: string;
+	extends?: string;
+	implements?: 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 BreakingSeverity = "high" | "medium" | "low";
+interface CategorizedBreaking {
+	id: string;
+	name: string;
+	kind: SpecExportKind;
+	severity: BreakingSeverity;
+	reason: string;
+}
+/** Minimal member change info for categorization (avoids circular dep with SDK) */
+interface MemberChangeInfo {
+	className: string;
+	memberName: string;
+	memberKind: "method" | "property" | "accessor" | "constructor";
+	changeType: "added" | "removed" | "signature-changed";
+}
+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;
+/**
+* Categorize breaking changes by severity
+*
+* @param breaking - Array of breaking change IDs
+* @param oldSpec - Previous spec version
+* @param newSpec - Current spec version
+* @param memberChanges - Optional member-level changes for classes
+* @returns Categorized breaking changes sorted by severity (high first)
+*/
+declare function categorizeBreakingChanges(breaking: string[], oldSpec: OpenPkg, newSpec: OpenPkg, memberChanges?: MemberChangeInfo[]): CategorizedBreaking[];
+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, categorizeBreakingChanges, assertSpec, SpecVisibility, SpecTypeParameter, SpecTypeKind, SpecType, SpecTag, SpecSource, SpecSignatureReturn, SpecSignatureParameter, SpecSignature, SpecSchema, SpecMember, SpecExtension, SpecExportKind, SpecExport, SpecExample, SpecDocsMetadata, SpecDocSignal, SpecDocDrift, SpecDiff, SCHEMA_VERSION, SCHEMA_URL, OpenPkgMeta, OpenPkg, MemberChangeInfo, JSON_SCHEMA_DRAFT, CategorizedBreaking, BreakingSeverity };

package/dist/index.js

@@ -0,0 +1,776 @@
+// 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;
+}
+function categorizeBreakingChanges(breaking, oldSpec, newSpec, memberChanges) {
+  const oldExportMap = toExportMap(oldSpec.exports);
+  const newExportMap = toExportMap(newSpec.exports);
+  const categorized = [];
+  for (const id of breaking) {
+    const oldExport = oldExportMap.get(id);
+    const newExport = newExportMap.get(id);
+    if (!newExport) {
+      const kind = oldExport?.kind ?? "variable";
+      categorized.push({
+        id,
+        name: oldExport?.name ?? id,
+        kind,
+        severity: kind === "function" || kind === "class" ? "high" : "medium",
+        reason: "removed"
+      });
+      continue;
+    }
+    if (oldExport?.kind === "class" && memberChanges?.length) {
+      const classChanges = memberChanges.filter((mc) => mc.className === id);
+      if (classChanges.length > 0) {
+        const hasConstructorChange = classChanges.some((mc) => mc.memberKind === "constructor");
+        const hasMethodRemoval = classChanges.some((mc) => mc.changeType === "removed" && mc.memberKind === "method");
+        categorized.push({
+          id,
+          name: oldExport.name,
+          kind: "class",
+          severity: hasConstructorChange || hasMethodRemoval ? "high" : "medium",
+          reason: hasConstructorChange ? "constructor changed" : hasMethodRemoval ? "methods removed" : "methods changed"
+        });
+        continue;
+      }
+    }
+    if (oldExport?.kind === "interface" || oldExport?.kind === "type") {
+      categorized.push({
+        id,
+        name: oldExport.name,
+        kind: oldExport.kind,
+        severity: "medium",
+        reason: "type definition changed"
+      });
+      continue;
+    }
+    if (oldExport?.kind === "function") {
+      categorized.push({
+        id,
+        name: oldExport.name,
+        kind: "function",
+        severity: "high",
+        reason: "signature changed"
+      });
+      continue;
+    }
+    categorized.push({
+      id,
+      name: oldExport?.name ?? id,
+      kind: oldExport?.kind ?? "variable",
+      severity: "low",
+      reason: "changed"
+    });
+  }
+  const severityOrder = { high: 0, medium: 1, low: 2 };
+  return categorized.sort((a, b) => severityOrder[a.severity] - severityOrder[b.severity]);
+}
+// 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",
+            "async-mismatch",
+            "property-type-drift",
+            "example-drift",
+            "example-syntax-error",
+            "example-runtime-error",
+            "example-assertion-failed",
+            "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"
+        },
+        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"
+        },
+        importPath: {
+          type: "string",
+          description: "Recommended import path"
+        },
+        kind: {
+          type: "string",
+          description: "Kind of export",
+          enum: ["function", "class", "variable", "interface", "type", "enum", "namespace", "external"]
+        },
+        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" }
+        },
+        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",
+          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"
+        },
+        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"
+        },
+        importPath: {
+          type: "string",
+          description: "Recommended import path"
+        },
+        kind: {
+          type: "string",
+          description: "Kind of type definition",
+          enum: ["interface", "type", "enum", "class", "external"]
+        },
+        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" }
+        },
+        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",
+          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"
+        },
+        default: {
+          description: "Default value for the parameter"
+        },
+        rest: {
+          type: "boolean",
+          description: "Whether this is a rest parameter (...args)"
+        }
+      }
+    },
+    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,
+  categorizeBreakingChanges,
+  assertSpec,
+  SCHEMA_VERSION,
+  SCHEMA_URL,
+  JSON_SCHEMA_DRAFT
+};

package/package.json

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