@openpkg-ts/spec 0.3.1 → 0.4.0

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,6 +152,16 @@ 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;
 type SpecError = {
 	instancePath: string;
@@ -151,4 +176,4 @@ declare function validateSpec(spec: unknown): {
 };
 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 };
+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

@@ -204,6 +204,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"];
@@ -704,6 +768,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.0",
   "description": "Shared schema, validation, and diff utilities for OpenPkg specs",
   "keywords": [
     "openpkg",