@openpkg-ts/spec 0.11.0 → 0.12.0

package/dist/index.d.ts

@@ -1,12 +1,6 @@
 type SpecTag = {
 	name: string;
 	text: string;
-	paramName?: string;
-	typeAnnotation?: string;
-	reference?: string;
-	language?: string;
-	version?: string;
-	reason?: string;
 };
 type SpecTypeAliasKind = "alias" | "conditional" | "mapped" | "template-literal" | "infer";
 type SpecConditionalType = {
@@ -35,6 +29,10 @@ type SpecSource = {
 	file?: string;
 	line?: number;
 	url?: string;
+	/** Package name for external types (e.g., "@stacks/common") */
+	package?: string;
+	/** Package version for external types (e.g., "7.0.0") */
+	version?: string;
 };
 type SpecSchemaPrimitive = {
 	type: "string";
@@ -92,6 +90,7 @@ type SpecSchemaCombinator = {
 };
 type SpecSchemaRef = {
 	$ref: string;
+	typeArguments?: SpecSchema[];
 };
 type SpecSchemaFallback = {
 	type: string;
@@ -104,54 +103,22 @@ type SpecExample = {
 	title?: string;
 	description?: string;
 	language?: SpecExampleLanguage;
-	runnable?: boolean;
-	expectedOutput?: string;
-	tags?: string[];
-};
-type SpecRelationType = "uses" | "returns" | "implements" | "extends" | "see-also" | "companion";
-type SpecRelation = {
-	type: SpecRelationType;
-	target: string;
-	description?: string;
 };
 type SpecExtension = Record<string, unknown>;
-/**
-* All possible drift type identifiers.
-*/
-type DriftType = "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";
-type SpecDocDrift = {
-	type: DriftType;
-	target?: string;
-	issue: string;
-	suggestion?: string;
+/** Presentation metadata for an export/type (moved from inline fields) */
+type SpecPresentationMeta = {
+	slug?: string;
+	displayName?: string;
+	category?: string;
+	importPath?: string;
+	alias?: string;
 };
-/**
-* Drift categories group related drift types for progressive disclosure.
-*
-* - `structural`: Signature/type mismatches (mostly auto-fixable via JSDoc)
-* - `semantic`: Metadata/visibility/reference issues
-* - `example`: Code example problems
-*/
-type DriftCategory = "structural" | "semantic" | "example";
-/**
-* Maps each drift type to its category.
-*/
-declare const DRIFT_CATEGORIES: Record<DriftType, DriftCategory>;
-/**
-* Human-readable category labels.
-*/
-declare const DRIFT_CATEGORY_LABELS: Record<DriftCategory, string>;
-/**
-* Category descriptions for help text.
-*/
-declare const DRIFT_CATEGORY_DESCRIPTIONS: Record<DriftCategory, string>;
-type SpecVisibility = "public" | "protected" | "private";
-type SpecDocsMetadata = {
-	coverageScore?: number;
-	/** Rule IDs that failed quality checks */
-	missing?: string[];
-	drift?: SpecDocDrift[];
+/** Extensions structure with typed presentation field */
+type SpecExtensions = {
+	presentation?: Record<string, SpecPresentationMeta>;
+	[key: string]: unknown;
 };
+type SpecVisibility = "public" | "protected" | "private";
 type SpecTypeParameter = {
 	name: string;
 	constraint?: string;
@@ -196,11 +163,6 @@ 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[];
@@ -219,18 +181,10 @@ type SpecExport = {
 	conditionalType?: SpecConditionalType;
 	mappedType?: SpecMappedType;
 	decorators?: SpecDecorator[];
-	isAugmentation?: boolean;
-	augmentedModule?: string;
-	related?: SpecRelation[];
 };
 type SpecType = {
 	id: string;
 	name: string;
-	slug?: string;
-	displayName?: string;
-	alias?: string;
-	category?: string;
-	importPath?: string;
 	kind: SpecTypeKind;
 	description?: string;
 	schema?: SpecSchema;
@@ -244,7 +198,8 @@ type SpecType = {
 	typeAliasKind?: SpecTypeAliasKind;
 	conditionalType?: SpecConditionalType;
 	mappedType?: SpecMappedType;
-	related?: SpecRelation[];
+	/** Whether this type is from an external package (node_modules) */
+	external?: boolean;
 };
 type OpenPkgMeta = {
 	name: string;
@@ -328,7 +283,12 @@ type SpecGenerationInfo = {
 	fromCache?: boolean;
 };
 /** Supported OpenPkg spec versions */
-type OpenPkgVersion = "0.2.0" | "0.3.0";
+type OpenPkgVersion = "0.2.0" | "0.3.0" | "0.4.0";
+/** Minimal generation metadata for v0.4.0 */
+type SpecGenerationMeta = {
+	generator?: string;
+	timestamp?: string;
+};
 type OpenPkg = {
 	$schema?: string;
 	openpkg: OpenPkgVersion;
@@ -336,25 +296,14 @@ type OpenPkg = {
 	exports: SpecExport[];
 	types?: SpecType[];
 	examples?: SpecExample[];
-	extensions?: SpecExtension;
-	/** Required metadata about how this spec was generated */
-	generation: SpecGenerationInfo;
+	extensions?: SpecExtensions;
+	/** Optional generation metadata (minimal in v0.4.0) */
+	generation?: SpecGenerationMeta | SpecGenerationInfo;
 };
 declare const SCHEMA_VERSION: OpenPkgVersion;
-declare const SCHEMA_URL = "https://unpkg.com/@openpkg-ts/spec/schemas/v0.3.0/openpkg.schema.json";
+declare const SCHEMA_URL = "https://unpkg.com/@openpkg-ts/spec/schemas/v0.4.0/openpkg.schema.json";
 declare const JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
 declare function dereference(spec: OpenPkg): OpenPkg;
-/**
-* Export with optional docs metadata for diff comparison.
-* Pure OpenPkg specs won't have docs; enriched specs will.
-*/
-type ExportWithDocs = SpecExport & {
-	docs?: SpecDocsMetadata;
-};
-type SpecWithDocs = OpenPkg & {
-	docs?: SpecDocsMetadata;
-	exports: ExportWithDocs[];
-};
 type BreakingSeverity = "high" | "medium" | "low";
 interface CategorizedBreaking {
 	id: string;
@@ -374,31 +323,15 @@ type SpecDiff = {
 	breaking: string[];
 	nonBreaking: string[];
 	docsOnly: string[];
-	coverageDelta: number;
-	oldCoverage: number;
-	newCoverage: number;
-	newUndocumented: string[];
-	improvedExports: string[];
-	regressedExports: string[];
-	driftIntroduced: number;
-	driftResolved: number;
 };
 /**
 * Compare two OpenPkg specs and compute differences.
-* If specs are enriched (have docs metadata), coverage changes are tracked.
-* For pure structural specs, coverage fields will be 0.
 */
-declare function diffSpec(oldSpec: SpecWithDocs, newSpec: SpecWithDocs): SpecDiff;
+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: SpecWithDocs, newSpec: SpecWithDocs, memberChanges?: MemberChangeInfo[]): CategorizedBreaking[];
+declare function categorizeBreakingChanges(breaking: string[], oldSpec: OpenPkg, newSpec: OpenPkg, memberChanges?: MemberChangeInfo[]): CategorizedBreaking[];
 /**
 * Semver version bump type.
 */
@@ -458,7 +391,7 @@ declare function recommendSemverBump(diff: SpecDiff): SemverRecommendation;
 declare function calculateNextVersion(currentVersion: string, bump: SemverBump): string;
 declare function normalize(spec: OpenPkg): OpenPkg;
 /** Supported schema versions */
-type SchemaVersion = "0.1.0" | "0.2.0" | "0.3.0" | "latest";
+type SchemaVersion = "0.1.0" | "0.2.0" | "0.3.0" | "0.4.0" | "latest";
 type SpecError = {
 	instancePath: string;
 	message: string;
@@ -493,4 +426,4 @@ declare function assertSpec(spec: unknown, version?: SchemaVersion): asserts spe
 * @returns Array of validation errors (empty if valid)
 */
 declare function getValidationErrors(spec: unknown, version?: SchemaVersion): SpecError[];
-export { validateSpec, recommendSemverBump, normalize, getValidationErrors, diffSpec, dereference, categorizeBreakingChanges, calculateNextVersion, assertSpec, SpecVisibility, SpecTypeParameter, SpecTypeKind, SpecTypeAliasKind, SpecType, SpecThrows, SpecTag, SpecSource, SpecSignatureReturn, SpecSignatureParameter, SpecSignature, SpecSchemaRef, SpecSchemaPrimitive, SpecSchemaGeneric, SpecSchemaFallback, SpecSchemaComposite, SpecSchemaCombinator, SpecSchema, SpecRelationType, SpecRelation, SpecMember, SpecMappedType, SpecGenerationInfo, SpecExtension, SpecExportKind, SpecExport, SpecExampleLanguage, SpecExample, SpecDocsMetadata, SpecDocDrift, SpecDiff, SpecDecorator, SpecConditionalType, SemverRecommendation, SemverBump, SCHEMA_VERSION, SCHEMA_URL, OpenPkgVersion, OpenPkgMeta, OpenPkg, MemberChangeInfo, JSON_SCHEMA_DRAFT, GenerationIssueSeverity, GenerationIssue, EntryPointDetectionMethod, DriftType, DriftCategory, DRIFT_CATEGORY_LABELS, DRIFT_CATEGORY_DESCRIPTIONS, DRIFT_CATEGORIES, CategorizedBreaking, BreakingSeverity };
+export { validateSpec, recommendSemverBump, normalize, getValidationErrors, diffSpec, dereference, categorizeBreakingChanges, calculateNextVersion, assertSpec, SpecVisibility, SpecTypeParameter, SpecTypeKind, SpecTypeAliasKind, SpecType, SpecThrows, SpecTag, SpecSource, SpecSignatureReturn, SpecSignatureParameter, SpecSignature, SpecSchemaRef, SpecSchemaPrimitive, SpecSchemaGeneric, SpecSchemaFallback, SpecSchemaComposite, SpecSchemaCombinator, SpecSchema, SpecPresentationMeta, SpecMember, SpecMappedType, SpecGenerationMeta, SpecGenerationInfo, SpecExtensions, SpecExtension, SpecExportKind, SpecExport, SpecExampleLanguage, SpecExample, SpecDiff, SpecDecorator, SpecConditionalType, SemverRecommendation, SemverBump, SCHEMA_VERSION, SCHEMA_URL, OpenPkgVersion, OpenPkgMeta, OpenPkg, MemberChangeInfo, JSON_SCHEMA_DRAFT, GenerationIssueSeverity, GenerationIssue, EntryPointDetectionMethod, CategorizedBreaking, BreakingSeverity };

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/constants.ts
-var SCHEMA_VERSION = "0.3.0";
-var SCHEMA_URL = "https://unpkg.com/@openpkg-ts/spec/schemas/v0.3.0/openpkg.schema.json";
+var SCHEMA_VERSION = "0.4.0";
+var SCHEMA_URL = "https://unpkg.com/@openpkg-ts/spec/schemas/v0.4.0/openpkg.schema.json";
 var JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
 // src/deref.ts
 function dereference(spec) {
@@ -72,47 +72,10 @@ function diffSpec(oldSpec, newSpec) {
   const result = {
     breaking: [],
     nonBreaking: [],
-    docsOnly: [],
-    coverageDelta: 0,
-    oldCoverage: 0,
-    newCoverage: 0,
-    newUndocumented: [],
-    improvedExports: [],
-    regressedExports: [],
-    driftIntroduced: 0,
-    driftResolved: 0
+    docsOnly: []
   };
   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) {
@@ -159,21 +122,7 @@ function toMap(items) {
   }
   return map;
 }
-var DOC_KEYS = new Set([
-  "description",
-  "examples",
-  "tags",
-  "rawComments",
-  "source",
-  "docs",
-  "displayName",
-  "slug",
-  "importPath",
-  "category",
-  "coverageScore",
-  "missing",
-  "drift"
-]);
+var DOC_KEYS = new Set(["description", "examples", "tags", "rawComments", "source"]);
 function isDocOnlyChange(a, b) {
   const structuralA = normalizeForComparison(removeDocFields(a));
   const structuralB = normalizeForComparison(removeDocFields(b));
@@ -353,7 +302,7 @@ 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));
+  const normalized = structuredClone(spec);
   normalized.meta = {
     ecosystem: normalized.meta?.ecosystem ?? DEFAULT_ECOSYSTEM,
     ...normalized.meta
@@ -364,53 +313,78 @@ function normalize(spec) {
   const types = Array.isArray(normalized.types) ? [...normalized.types] : [];
   types.sort((a, b) => (a.name || "").localeCompare(b.name || ""));
   normalized.types = types.map((item) => normalizeType(item));
+  if (normalized.generation) {
+    normalized.generation = normalizeGeneration(normalized.generation);
+  }
   return normalized;
 }
+function normalizeGeneration(gen) {
+  if (!gen)
+    return;
+  const extendedGen = gen;
+  if (extendedGen.generator && typeof extendedGen.generator === "object") {
+    return {
+      generator: `${extendedGen.generator.name}@${extendedGen.generator.version}`,
+      timestamp: extendedGen.timestamp
+    };
+  }
+  return gen;
+}
 function normalizeExport(item) {
-  const clone = JSON.parse(JSON.stringify(item));
+  const clone = structuredClone(item);
   for (const field of arrayFieldsByExport) {
     if (!Array.isArray(clone[field])) {
       clone[field] = [];
     }
   }
+  if (clone.type !== undefined && typeof clone.type !== "string") {
+    if (!clone.schema) {
+      clone.schema = clone.type;
+    }
+    delete clone.type;
+  }
+  if (clone.tags && clone.tags.length > 0) {
+    clone.tags = clone.tags.map(normalizeTag);
+  }
+  if (clone.members && clone.members.length > 0) {
+    clone.members = clone.members.map(normalizeMember);
+  }
   return clone;
 }
 function normalizeType(item) {
-  const clone = JSON.parse(JSON.stringify(item));
+  const clone = structuredClone(item);
   for (const field of arrayFieldsByType) {
     if (!Array.isArray(clone[field])) {
       clone[field] = [];
     }
   }
+  if (clone.type !== undefined && typeof clone.type !== "string") {
+    if (!clone.schema) {
+      clone.schema = clone.type;
+    }
+    delete clone.type;
+  }
+  if (clone.tags && clone.tags.length > 0) {
+    clone.tags = clone.tags.map(normalizeTag);
+  }
+  if (clone.members && clone.members.length > 0) {
+    clone.members = clone.members.map(normalizeMember);
+  }
+  return clone;
+}
+function normalizeTag(tag) {
+  return {
+    name: tag.name,
+    text: tag.text
+  };
+}
+function normalizeMember(member) {
+  const clone = structuredClone(member);
+  if (clone.tags && clone.tags.length > 0) {
+    clone.tags = clone.tags.map(normalizeTag);
+  }
   return clone;
 }
-// src/types.ts
-var DRIFT_CATEGORIES = {
-  "param-mismatch": "structural",
-  "param-type-mismatch": "structural",
-  "return-type-mismatch": "structural",
-  "optionality-mismatch": "structural",
-  "generic-constraint-mismatch": "structural",
-  "property-type-drift": "structural",
-  "async-mismatch": "structural",
-  "deprecated-mismatch": "semantic",
-  "visibility-mismatch": "semantic",
-  "broken-link": "semantic",
-  "example-drift": "example",
-  "example-syntax-error": "example",
-  "example-runtime-error": "example",
-  "example-assertion-failed": "example"
-};
-var DRIFT_CATEGORY_LABELS = {
-  structural: "Signature mismatches",
-  semantic: "Metadata issues",
-  example: "Example problems"
-};
-var DRIFT_CATEGORY_DESCRIPTIONS = {
-  structural: "JSDoc types or parameters don't match the actual code signature",
-  semantic: "Deprecation, visibility, or reference issues",
-  example: "@example code has errors or doesn't work correctly"
-};
 // src/validate.ts
 import Ajv from "ajv/dist/2020.js";
 import addFormats from "ajv-formats";
@@ -1879,10 +1853,7 @@ var openpkg_schema_default3 = {
             },
             required: { type: "array", items: { type: "string" } },
             additionalProperties: {
-              oneOf: [
-                { type: "boolean" },
-                { type: "object", additionalProperties: true }
-              ]
+              oneOf: [{ type: "boolean" }, { type: "object", additionalProperties: true }]
             },
             anyOf: { type: "array", items: { $ref: "#/$defs/schema" } },
             allOf: { type: "array", items: { $ref: "#/$defs/schema" } },
@@ -2142,13 +2113,393 @@ var openpkg_schema_default3 = {
     }
   }
 };
+// schemas/v0.4.0/openpkg.schema.json
+var openpkg_schema_default4 = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://unpkg.com/@openpkg-ts/spec/schemas/v0.4.0/openpkg.schema.json",
+  title: "OpenPkg Specification v0.4.0",
+  description: "Minimal tool-agnostic TypeScript export representation",
+  type: "object",
+  required: ["openpkg", "meta", "exports"],
+  properties: {
+    $schema: {
+      type: "string",
+      description: "Reference to the OpenPkg schema version"
+    },
+    openpkg: {
+      type: "string",
+      const: "0.4.0"
+    },
+    meta: {
+      type: "object",
+      required: ["name"],
+      properties: {
+        name: { type: "string" },
+        version: { type: "string" },
+        description: { type: "string" },
+        license: { type: "string" },
+        repository: { type: "string" },
+        ecosystem: { type: "string" }
+      }
+    },
+    exports: {
+      type: "array",
+      items: { $ref: "#/$defs/export" }
+    },
+    types: {
+      type: "array",
+      items: { $ref: "#/$defs/typeDef" }
+    },
+    examples: {
+      type: "array",
+      items: { $ref: "#/$defs/example" }
+    },
+    extensions: {
+      type: "object",
+      properties: {
+        presentation: {
+          type: "object",
+          additionalProperties: { $ref: "#/$defs/presentationMeta" }
+        }
+      },
+      additionalProperties: true
+    },
+    generation: {
+      $ref: "#/$defs/generationMeta",
+      description: "Optional generation metadata"
+    }
+  },
+  $defs: {
+    generationMeta: {
+      type: "object",
+      properties: {
+        generator: { type: "string" },
+        timestamp: { type: "string", format: "date-time" }
+      }
+    },
+    presentationMeta: {
+      type: "object",
+      properties: {
+        slug: { type: "string" },
+        displayName: { type: "string" },
+        category: { type: "string" },
+        importPath: { type: "string" },
+        alias: { type: "string" }
+      },
+      additionalProperties: false
+    },
+    export: {
+      type: "object",
+      required: ["id", "name", "kind"],
+      properties: {
+        id: { type: "string" },
+        name: { type: "string" },
+        kind: {
+          type: "string",
+          enum: [
+            "function",
+            "class",
+            "variable",
+            "interface",
+            "type",
+            "enum",
+            "module",
+            "namespace",
+            "reference",
+            "external"
+          ]
+        },
+        description: { type: "string" },
+        examples: {
+          type: "array",
+          items: { $ref: "#/$defs/example" }
+        },
+        signatures: {
+          type: "array",
+          items: { $ref: "#/$defs/signature" }
+        },
+        type: { type: "string" },
+        schema: { $ref: "#/$defs/schema" },
+        members: {
+          type: "array",
+          items: { $ref: "#/$defs/member" }
+        },
+        extends: { type: "string" },
+        implements: {
+          type: "array",
+          items: { type: "string" }
+        },
+        tags: {
+          type: "array",
+          items: { $ref: "#/$defs/tag" }
+        },
+        source: { $ref: "#/$defs/sourceLocation" },
+        deprecated: { type: "boolean" },
+        flags: { type: "object", additionalProperties: true },
+        typeParameters: {
+          type: "array",
+          items: { $ref: "#/$defs/typeParameter" }
+        },
+        typeAliasKind: { $ref: "#/$defs/typeAliasKind" },
+        conditionalType: { $ref: "#/$defs/conditionalType" },
+        mappedType: { $ref: "#/$defs/mappedType" },
+        decorators: {
+          type: "array",
+          items: { $ref: "#/$defs/decorator" }
+        }
+      }
+    },
+    typeDef: {
+      type: "object",
+      required: ["id", "name", "kind"],
+      properties: {
+        id: { type: "string" },
+        name: { type: "string" },
+        kind: {
+          type: "string",
+          enum: ["interface", "type", "enum", "class", "external"]
+        },
+        description: { type: "string" },
+        schema: { $ref: "#/$defs/schema" },
+        type: { type: "string" },
+        members: {
+          type: "array",
+          items: { $ref: "#/$defs/member" }
+        },
+        extends: { type: "string" },
+        implements: {
+          type: "array",
+          items: { type: "string" }
+        },
+        tags: {
+          type: "array",
+          items: { $ref: "#/$defs/tag" }
+        },
+        source: { $ref: "#/$defs/sourceLocation" },
+        rawComments: { type: "string" },
+        typeAliasKind: { $ref: "#/$defs/typeAliasKind" },
+        conditionalType: { $ref: "#/$defs/conditionalType" },
+        mappedType: { $ref: "#/$defs/mappedType" }
+      }
+    },
+    tag: {
+      type: "object",
+      required: ["name", "text"],
+      properties: {
+        name: { type: "string" },
+        text: { type: "string" }
+      },
+      additionalProperties: false
+    },
+    signature: {
+      type: "object",
+      properties: {
+        parameters: {
+          type: "array",
+          items: { $ref: "#/$defs/parameter" }
+        },
+        returns: { $ref: "#/$defs/returns" },
+        description: { type: "string" },
+        typeParameters: {
+          type: "array",
+          items: { $ref: "#/$defs/typeParameter" }
+        },
+        overloadIndex: { type: "integer", minimum: 0 },
+        isImplementation: { type: "boolean" },
+        throws: {
+          type: "array",
+          items: { $ref: "#/$defs/throwsInfo" }
+        }
+      }
+    },
+    typeParameter: {
+      type: "object",
+      required: ["name"],
+      properties: {
+        name: { type: "string" },
+        constraint: { type: "string" },
+        default: { type: "string" }
+      }
+    },
+    parameter: {
+      type: "object",
+      required: ["name"],
+      properties: {
+        name: { type: "string" },
+        required: { type: "boolean" },
+        schema: { $ref: "#/$defs/schema" },
+        description: { type: "string" },
+        default: {},
+        rest: { type: "boolean" },
+        decorators: {
+          type: "array",
+          items: { $ref: "#/$defs/decorator" }
+        }
+      }
+    },
+    returns: {
+      type: "object",
+      properties: {
+        schema: { $ref: "#/$defs/schema" },
+        description: { type: "string" }
+      }
+    },
+    schema: {
+      oneOf: [
+        { type: "string" },
+        { type: "boolean" },
+        {
+          type: "object",
+          properties: {
+            $schema: { type: "string" },
+            type: { type: "string" },
+            format: { type: "string" },
+            enum: { type: "array" },
+            const: {},
+            items: { $ref: "#/$defs/schema" },
+            prefixedItems: {
+              type: "array",
+              items: { $ref: "#/$defs/schema" }
+            },
+            properties: {
+              type: "object",
+              additionalProperties: { $ref: "#/$defs/schema" }
+            },
+            required: { type: "array", items: { type: "string" } },
+            additionalProperties: {
+              oneOf: [{ type: "boolean" }, { type: "object" }]
+            },
+            anyOf: { type: "array", items: { $ref: "#/$defs/schema" } },
+            allOf: { type: "array", items: { $ref: "#/$defs/schema" } },
+            oneOf: { type: "array", items: { $ref: "#/$defs/schema" } },
+            $ref: { type: "string" },
+            discriminator: {
+              type: "object",
+              properties: { propertyName: { type: "string" } }
+            },
+            description: { type: "string" },
+            default: {},
+            minimum: { type: "number" },
+            maximum: { type: "number" },
+            exclusiveMinimum: { type: "number" },
+            exclusiveMaximum: { type: "number" },
+            minLength: { type: "integer" },
+            maxLength: { type: "integer" },
+            pattern: { type: "string" },
+            minItems: { type: "integer" },
+            maxItems: { type: "integer" },
+            uniqueItems: { type: "boolean" },
+            signatures: { type: "array", items: { $ref: "#/$defs/signature" } }
+          }
+        }
+      ]
+    },
+    sourceLocation: {
+      type: "object",
+      properties: {
+        file: { type: "string" },
+        line: { type: "integer", minimum: 1 },
+        url: { type: "string" }
+      }
+    },
+    typeAliasKind: {
+      type: "string",
+      enum: ["alias", "conditional", "mapped", "template-literal", "infer"]
+    },
+    conditionalType: {
+      type: "object",
+      required: ["checkType", "extendsType", "trueType", "falseType"],
+      properties: {
+        checkType: { type: "string" },
+        extendsType: { type: "string" },
+        trueType: { type: "string" },
+        falseType: { type: "string" }
+      },
+      additionalProperties: false
+    },
+    mappedType: {
+      type: "object",
+      required: ["typeParameter"],
+      properties: {
+        typeParameter: { type: "string" },
+        nameType: { type: "string" },
+        valueType: { type: "string" },
+        readonly: {
+          oneOf: [{ type: "boolean" }, { enum: ["+", "-"] }]
+        },
+        optional: {
+          oneOf: [{ type: "boolean" }, { enum: ["+", "-"] }]
+        }
+      },
+      additionalProperties: false
+    },
+    decorator: {
+      type: "object",
+      required: ["name"],
+      properties: {
+        name: { type: "string" },
+        arguments: { type: "array" },
+        argumentsText: { type: "array", items: { type: "string" } }
+      },
+      additionalProperties: false
+    },
+    throwsInfo: {
+      type: "object",
+      properties: {
+        type: { type: "string" },
+        description: { type: "string" }
+      },
+      additionalProperties: false
+    },
+    exampleLanguage: {
+      type: "string",
+      enum: ["ts", "js", "tsx", "jsx", "shell", "json"]
+    },
+    example: {
+      oneOf: [
+        { type: "string" },
+        {
+          type: "object",
+          required: ["code"],
+          properties: {
+            code: { type: "string" },
+            title: { type: "string" },
+            description: { type: "string" },
+            language: { $ref: "#/$defs/exampleLanguage" }
+          },
+          additionalProperties: false
+        }
+      ]
+    },
+    visibility: {
+      type: "string",
+      enum: ["public", "protected", "private"]
+    },
+    member: {
+      type: "object",
+      properties: {
+        id: { type: "string" },
+        name: { type: "string" },
+        kind: { type: "string" },
+        description: { type: "string" },
+        visibility: { $ref: "#/$defs/visibility" },
+        tags: { type: "array", items: { $ref: "#/$defs/tag" } },
+        flags: { type: "object", additionalProperties: true },
+        schema: { $ref: "#/$defs/schema" },
+        signatures: { type: "array", items: { $ref: "#/$defs/signature" } },
+        decorators: { type: "array", items: { $ref: "#/$defs/decorator" } }
+      }
+    }
+  }
+};
 
 // src/validate.ts
-var LATEST_VERSION = "0.3.0";
+var LATEST_VERSION = "0.4.0";
 var schemas = {
   "0.1.0": openpkg_schema_default,
   "0.2.0": openpkg_schema_default2,
-  "0.3.0": openpkg_schema_default3
+  "0.3.0": openpkg_schema_default3,
+  "0.4.0": openpkg_schema_default4
 };
 var ajv = new Ajv({
   strict: false,
@@ -2213,8 +2564,5 @@ export {
   assertSpec,
   SCHEMA_VERSION,
   SCHEMA_URL,
-  JSON_SCHEMA_DRAFT,
-  DRIFT_CATEGORY_LABELS,
-  DRIFT_CATEGORY_DESCRIPTIONS,
-  DRIFT_CATEGORIES
+  JSON_SCHEMA_DRAFT
 };

package/package.json

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

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

@@ -734,10 +734,7 @@
             },
             "required": { "type": "array", "items": { "type": "string" } },
             "additionalProperties": {
-              "oneOf": [
-                { "type": "boolean" },
-                { "type": "object", "additionalProperties": true }
-              ]
+              "oneOf": [{ "type": "boolean" }, { "type": "object", "additionalProperties": true }]
             },
             "anyOf": { "type": "array", "items": { "$ref": "#/$defs/schema" } },
             "allOf": { "type": "array", "items": { "$ref": "#/$defs/schema" } },

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

@@ -0,0 +1,378 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/@openpkg-ts/spec/schemas/v0.4.0/openpkg.schema.json",
+  "title": "OpenPkg Specification v0.4.0",
+  "description": "Minimal tool-agnostic TypeScript export representation",
+  "type": "object",
+  "required": ["openpkg", "meta", "exports"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Reference to the OpenPkg schema version"
+    },
+    "openpkg": {
+      "type": "string",
+      "const": "0.4.0"
+    },
+    "meta": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string" },
+        "version": { "type": "string" },
+        "description": { "type": "string" },
+        "license": { "type": "string" },
+        "repository": { "type": "string" },
+        "ecosystem": { "type": "string" }
+      }
+    },
+    "exports": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/export" }
+    },
+    "types": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/typeDef" }
+    },
+    "examples": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/example" }
+    },
+    "extensions": {
+      "type": "object",
+      "properties": {
+        "presentation": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/presentationMeta" }
+        }
+      },
+      "additionalProperties": true
+    },
+    "generation": {
+      "$ref": "#/$defs/generationMeta",
+      "description": "Optional generation metadata"
+    }
+  },
+  "$defs": {
+    "generationMeta": {
+      "type": "object",
+      "properties": {
+        "generator": { "type": "string" },
+        "timestamp": { "type": "string", "format": "date-time" }
+      }
+    },
+    "presentationMeta": {
+      "type": "object",
+      "properties": {
+        "slug": { "type": "string" },
+        "displayName": { "type": "string" },
+        "category": { "type": "string" },
+        "importPath": { "type": "string" },
+        "alias": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "export": {
+      "type": "object",
+      "required": ["id", "name", "kind"],
+      "properties": {
+        "id": { "type": "string" },
+        "name": { "type": "string" },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "function",
+            "class",
+            "variable",
+            "interface",
+            "type",
+            "enum",
+            "module",
+            "namespace",
+            "reference",
+            "external"
+          ]
+        },
+        "description": { "type": "string" },
+        "examples": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/example" }
+        },
+        "signatures": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/signature" }
+        },
+        "type": { "type": "string" },
+        "schema": { "$ref": "#/$defs/schema" },
+        "members": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/member" }
+        },
+        "extends": { "type": "string" },
+        "implements": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "tags": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/tag" }
+        },
+        "source": { "$ref": "#/$defs/sourceLocation" },
+        "deprecated": { "type": "boolean" },
+        "flags": { "type": "object", "additionalProperties": true },
+        "typeParameters": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/typeParameter" }
+        },
+        "typeAliasKind": { "$ref": "#/$defs/typeAliasKind" },
+        "conditionalType": { "$ref": "#/$defs/conditionalType" },
+        "mappedType": { "$ref": "#/$defs/mappedType" },
+        "decorators": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/decorator" }
+        }
+      }
+    },
+    "typeDef": {
+      "type": "object",
+      "required": ["id", "name", "kind"],
+      "properties": {
+        "id": { "type": "string" },
+        "name": { "type": "string" },
+        "kind": {
+          "type": "string",
+          "enum": ["interface", "type", "enum", "class", "external"]
+        },
+        "description": { "type": "string" },
+        "schema": { "$ref": "#/$defs/schema" },
+        "type": { "type": "string" },
+        "members": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/member" }
+        },
+        "extends": { "type": "string" },
+        "implements": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "tags": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/tag" }
+        },
+        "source": { "$ref": "#/$defs/sourceLocation" },
+        "rawComments": { "type": "string" },
+        "typeAliasKind": { "$ref": "#/$defs/typeAliasKind" },
+        "conditionalType": { "$ref": "#/$defs/conditionalType" },
+        "mappedType": { "$ref": "#/$defs/mappedType" }
+      }
+    },
+    "tag": {
+      "type": "object",
+      "required": ["name", "text"],
+      "properties": {
+        "name": { "type": "string" },
+        "text": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "signature": {
+      "type": "object",
+      "properties": {
+        "parameters": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/parameter" }
+        },
+        "returns": { "$ref": "#/$defs/returns" },
+        "description": { "type": "string" },
+        "typeParameters": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/typeParameter" }
+        },
+        "overloadIndex": { "type": "integer", "minimum": 0 },
+        "isImplementation": { "type": "boolean" },
+        "throws": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/throwsInfo" }
+        }
+      }
+    },
+    "typeParameter": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string" },
+        "constraint": { "type": "string" },
+        "default": { "type": "string" }
+      }
+    },
+    "parameter": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string" },
+        "required": { "type": "boolean" },
+        "schema": { "$ref": "#/$defs/schema" },
+        "description": { "type": "string" },
+        "default": {},
+        "rest": { "type": "boolean" },
+        "decorators": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/decorator" }
+        }
+      }
+    },
+    "returns": {
+      "type": "object",
+      "properties": {
+        "schema": { "$ref": "#/$defs/schema" },
+        "description": { "type": "string" }
+      }
+    },
+    "schema": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "boolean" },
+        {
+          "type": "object",
+          "properties": {
+            "$schema": { "type": "string" },
+            "type": { "type": "string" },
+            "format": { "type": "string" },
+            "enum": { "type": "array" },
+            "const": {},
+            "items": { "$ref": "#/$defs/schema" },
+            "prefixedItems": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/schema" }
+            },
+            "properties": {
+              "type": "object",
+              "additionalProperties": { "$ref": "#/$defs/schema" }
+            },
+            "required": { "type": "array", "items": { "type": "string" } },
+            "additionalProperties": {
+              "oneOf": [{ "type": "boolean" }, { "type": "object" }]
+            },
+            "anyOf": { "type": "array", "items": { "$ref": "#/$defs/schema" } },
+            "allOf": { "type": "array", "items": { "$ref": "#/$defs/schema" } },
+            "oneOf": { "type": "array", "items": { "$ref": "#/$defs/schema" } },
+            "$ref": { "type": "string" },
+            "discriminator": {
+              "type": "object",
+              "properties": { "propertyName": { "type": "string" } }
+            },
+            "description": { "type": "string" },
+            "default": {},
+            "minimum": { "type": "number" },
+            "maximum": { "type": "number" },
+            "exclusiveMinimum": { "type": "number" },
+            "exclusiveMaximum": { "type": "number" },
+            "minLength": { "type": "integer" },
+            "maxLength": { "type": "integer" },
+            "pattern": { "type": "string" },
+            "minItems": { "type": "integer" },
+            "maxItems": { "type": "integer" },
+            "uniqueItems": { "type": "boolean" },
+            "signatures": { "type": "array", "items": { "$ref": "#/$defs/signature" } }
+          }
+        }
+      ]
+    },
+    "sourceLocation": {
+      "type": "object",
+      "properties": {
+        "file": { "type": "string" },
+        "line": { "type": "integer", "minimum": 1 },
+        "url": { "type": "string" }
+      }
+    },
+    "typeAliasKind": {
+      "type": "string",
+      "enum": ["alias", "conditional", "mapped", "template-literal", "infer"]
+    },
+    "conditionalType": {
+      "type": "object",
+      "required": ["checkType", "extendsType", "trueType", "falseType"],
+      "properties": {
+        "checkType": { "type": "string" },
+        "extendsType": { "type": "string" },
+        "trueType": { "type": "string" },
+        "falseType": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "mappedType": {
+      "type": "object",
+      "required": ["typeParameter"],
+      "properties": {
+        "typeParameter": { "type": "string" },
+        "nameType": { "type": "string" },
+        "valueType": { "type": "string" },
+        "readonly": {
+          "oneOf": [{ "type": "boolean" }, { "enum": ["+", "-"] }]
+        },
+        "optional": {
+          "oneOf": [{ "type": "boolean" }, { "enum": ["+", "-"] }]
+        }
+      },
+      "additionalProperties": false
+    },
+    "decorator": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string" },
+        "arguments": { "type": "array" },
+        "argumentsText": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "throwsInfo": {
+      "type": "object",
+      "properties": {
+        "type": { "type": "string" },
+        "description": { "type": "string" }
+      },
+      "additionalProperties": false
+    },
+    "exampleLanguage": {
+      "type": "string",
+      "enum": ["ts", "js", "tsx", "jsx", "shell", "json"]
+    },
+    "example": {
+      "oneOf": [
+        { "type": "string" },
+        {
+          "type": "object",
+          "required": ["code"],
+          "properties": {
+            "code": { "type": "string" },
+            "title": { "type": "string" },
+            "description": { "type": "string" },
+            "language": { "$ref": "#/$defs/exampleLanguage" }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+    "visibility": {
+      "type": "string",
+      "enum": ["public", "protected", "private"]
+    },
+    "member": {
+      "type": "object",
+      "properties": {
+        "id": { "type": "string" },
+        "name": { "type": "string" },
+        "kind": { "type": "string" },
+        "description": { "type": "string" },
+        "visibility": { "$ref": "#/$defs/visibility" },
+        "tags": { "type": "array", "items": { "$ref": "#/$defs/tag" } },
+        "flags": { "type": "object", "additionalProperties": true },
+        "schema": { "$ref": "#/$defs/schema" },
+        "signatures": { "type": "array", "items": { "$ref": "#/$defs/signature" } },
+        "decorators": { "type": "array", "items": { "$ref": "#/$defs/decorator" } }
+      }
+    }
+  }
+}