@openpkg-ts/spec 0.3.1 → 0.4.1

package/dist/index.d.ts

@@ -123,6 +123,21 @@ type OpenPkg = {
 	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[];
@@ -137,18 +152,51 @@ type SpecDiff = {
 	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;
+/** Supported schema versions */
+type SchemaVersion = "0.1.0" | "0.2.0" | "latest";
 type SpecError = {
 	instancePath: string;
 	message: string;
 	keyword: string;
 };
-declare function validateSpec(spec: unknown): {
+/**
+* Validate a spec against a specific schema version.
+*
+* @param spec - The spec object to validate
+* @param version - Schema version to validate against (default: 'latest')
+* @returns Validation result
+*/
+declare function validateSpec(spec: unknown, version?: SchemaVersion): {
 	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 };
+/**
+* Assert that a value is a valid OpenPkg spec.
+* Throws an error with details if validation fails.
+*
+* @param spec - The value to validate
+* @param version - Schema version to validate against (default: 'latest')
+*/
+declare function assertSpec(spec: unknown, version?: SchemaVersion): asserts spec is OpenPkg;
+/**
+* Get validation errors for a spec.
+*
+* @param spec - The spec to validate
+* @param version - Schema version to validate against (default: 'latest')
+* @returns Array of validation errors (empty if valid)
+*/
+declare function getValidationErrors(spec: unknown, version?: SchemaVersion): 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

@@ -159,7 +159,21 @@ function toMap(items) {
   }
   return map;
 }
-var DOC_KEYS = new Set(["description", "examples", "tags", "source", "rawComments"]);
+var DOC_KEYS = new Set([
+  "description",
+  "examples",
+  "tags",
+  "rawComments",
+  "source",
+  "docs",
+  "displayName",
+  "slug",
+  "importPath",
+  "category",
+  "coverageScore",
+  "missing",
+  "drift"
+]);
 function isDocOnlyChange(a, b) {
   const structuralA = normalizeForComparison(removeDocFields(a));
   const structuralB = normalizeForComparison(removeDocFields(b));
@@ -204,6 +218,70 @@ function sortKeys(value) {
   }
   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"];
@@ -419,7 +497,16 @@ var openpkg_schema_default = {
         kind: {
           type: "string",
           description: "Kind of export",
-          enum: ["function", "class", "variable", "interface", "type", "enum", "namespace", "external"]
+          enum: [
+            "function",
+            "class",
+            "variable",
+            "interface",
+            "type",
+            "enum",
+            "namespace",
+            "external"
+          ]
         },
         description: {
           type: "string",
@@ -660,8 +747,315 @@ var openpkg_schema_default = {
     }
   }
 };
+// schemas/v0.1.0/openpkg.schema.json
+var openpkg_schema_default2 = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://unpkg.com/@openpkg-ts/spec/schemas/v0.1.0/openpkg.schema.json",
+  title: "OpenPkg Specification",
+  description: "Schema for OpenPkg specification files",
+  type: "object",
+  required: ["openpkg", "meta", "exports"],
+  properties: {
+    $schema: {
+      type: "string",
+      description: "Reference to the OpenPkg schema version",
+      pattern: "^(https://raw\\.githubusercontent\\.com/ryanwaits/openpkg/main/schemas/v[0-9]+\\.[0-9]+\\.[0-9]+/openpkg\\.schema\\.json|https://unpkg\\.com/@openpkg-ts/spec/schemas/v[0-9]+\\.[0-9]+\\.[0-9]+/openpkg\\.schema\\.json)$"
+    },
+    openpkg: {
+      type: "string",
+      description: "OpenPkg specification version",
+      pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      const: "0.1.0"
+    },
+    meta: {
+      type: "object",
+      description: "Package metadata",
+      required: ["name"],
+      properties: {
+        name: {
+          type: "string",
+          description: "Package name"
+        },
+        version: {
+          type: "string",
+          description: "Package version"
+        },
+        description: {
+          type: "string",
+          description: "Package description"
+        },
+        license: {
+          type: "string",
+          description: "Package license"
+        },
+        repository: {
+          type: "string",
+          description: "Repository URL"
+        },
+        ecosystem: {
+          type: "string",
+          description: "Package ecosystem"
+        }
+      }
+    },
+    exports: {
+      type: "array",
+      description: "List of exported items",
+      items: {
+        $ref: "#/$defs/export"
+      }
+    },
+    types: {
+      type: "array",
+      description: "List of type definitions",
+      items: {
+        $ref: "#/$defs/typeDef"
+      }
+    }
+  },
+  $defs: {
+    export: {
+      type: "object",
+      required: ["id", "name", "kind"],
+      properties: {
+        id: {
+          type: "string",
+          description: "Unique identifier for the export"
+        },
+        name: {
+          type: "string",
+          description: "Export name"
+        },
+        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"
+        }
+      }
+    },
+    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"
+        }
+      }
+    },
+    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 LATEST_VERSION = "0.2.0";
+var schemas = {
+  "0.1.0": openpkg_schema_default2,
+  "0.2.0": openpkg_schema_default
+};
 var ajv = new Ajv({
   strict: false,
   allErrors: true,
@@ -669,8 +1063,23 @@ var ajv = new Ajv({
   $data: true
 });
 addFormats(ajv);
-var validate = ajv.compile(openpkg_schema_default);
-function validateSpec(spec) {
+var validatorCache = new Map;
+function getValidator(version = "latest") {
+  const resolvedVersion = version === "latest" ? LATEST_VERSION : version;
+  let validator = validatorCache.get(resolvedVersion);
+  if (validator) {
+    return validator;
+  }
+  const schema = schemas[resolvedVersion];
+  if (!schema) {
+    throw new Error(`Unknown schema version: ${resolvedVersion}. Available: ${Object.keys(schemas).join(", ")}`);
+  }
+  validator = ajv.compile(schema);
+  validatorCache.set(resolvedVersion, validator);
+  return validator;
+}
+function validateSpec(spec, version = "latest") {
+  const validate = getValidator(version);
   const ok = validate(spec);
   if (ok) {
     return { ok: true };
@@ -685,8 +1094,8 @@ function validateSpec(spec) {
     errors
   };
 }
-function assertSpec(spec) {
-  const result = validateSpec(spec);
+function assertSpec(spec, version = "latest") {
+  const result = validateSpec(spec, version);
   if (!result.ok) {
     const details = result.errors.map((error) => `- ${error.instancePath || "/"} ${error.message}`).join(`
 `);
@@ -694,8 +1103,8 @@ function assertSpec(spec) {
 ${details}`);
   }
 }
-function getValidationErrors(spec) {
-  const result = validateSpec(spec);
+function getValidationErrors(spec, version = "latest") {
+  const result = validateSpec(spec, version);
   return result.ok ? [] : result.errors;
 }
 export {
@@ -704,6 +1113,7 @@ export {
   getValidationErrors,
   diffSpec,
   dereference,
+  categorizeBreakingChanges,
   assertSpec,
   SCHEMA_VERSION,
   SCHEMA_URL,

package/package.json

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

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

@@ -173,7 +173,16 @@
         "kind": {
           "type": "string",
           "description": "Kind of export",
-          "enum": ["function", "class", "variable", "interface", "type", "enum", "namespace", "external"]
+          "enum": [
+            "function",
+            "class",
+            "variable",
+            "interface",
+            "type",
+            "enum",
+            "namespace",
+            "external"
+          ]
         },
         "description": {
           "type": "string",