feat: introduce classifyRuleId's for rules

.cursor/rules/classify-rule-id.mdc

@@ -0,0 +1,102 @@
+---
+description: Conventions for ClassifyRuleIdRule definitions and ruleId constant naming
+globs: src/**/*.classify*.ts
+alwaysApply: false
+---
+
+# ClassifyRuleIdRule Authoring Conventions
+
+## Purpose
+
+`ClassifyRuleIdRule` attaches a stable string identifier (`classifyRuleId`) to each diff so a `diffClassifier` can reclassify it via a simple table lookup, without re-implementing the original condition logic.
+
+## Type Forms
+
+`ClassifyRuleIdRule` is one of:
+
+- **Single element** – same ruleId for all actions:
+  ```ts
+  export const requiredItemClassifyRuleIdRule: ClassifyRuleIdRule =
+    ({ after }) => (requiredItemHasPropertyDefault(after)
+      ? JSON_SCHEMA_CLASSIFY_RULE_IDS.REQUIRED_ITEM_AFTER_PROPERTY_HAS_DEFAULT
+      : JSON_SCHEMA_CLASSIFY_RULE_IDS.REQUIRED_ITEM_AFTER_PROPERTY_HAS_NO_DEFAULT)
+  ```
+
+- **3-tuple `[add, remove, replace]`** – when add/remove/replace have different conditions or inspect different sides:
+  ```ts
+  export const enumItemClassifyRuleIdRule: ClassifyRuleIdRule = [
+    ({ before }) => (isNotEmptyArray(before.parent)
+      ? JSON_SCHEMA_CLASSIFY_RULE_IDS.ENUM_ITEM_BEFORE_ENUM_NON_EMPTY
+      : JSON_SCHEMA_CLASSIFY_RULE_IDS.ENUM_ITEM_BEFORE_ENUM_EMPTY),
+    ({ after }) => (isNotEmptyArray(after.parent)
+      ? JSON_SCHEMA_CLASSIFY_RULE_IDS.ENUM_ITEM_AFTER_ENUM_NON_EMPTY
+      : JSON_SCHEMA_CLASSIFY_RULE_IDS.ENUM_ITEM_AFTER_ENUM_EMPTY),
+    JSON_SCHEMA_CLASSIFY_RULE_IDS.ENUM_ITEM,  // replace: static fallback
+  ]
+  ```
+
+## Side Selection in Resolvers
+
+| Tuple position | Inspect side | Rationale |
+|---|---|---|
+| add (index 0) | `after` | Added state is in `after` |
+| remove (index 1) | `before` | Removed state is in `before` |
+| replace (index 2) | `after` (or both) | New state or comparison between sides |
+| array-item add | `before.parent` | State of the sibling array before adding |
+| array-item remove | `after.parent` | State of the sibling array after removing |
+
+## Placement & Structure
+
+- Place `ClassifyRuleIdRule` **directly before** its corresponding `ClassifyRule`.
+- Extract shared boolean helpers between the two (e.g., `propertyHasDefault`, `propertyIsRequired`).
+- Place helpers immediately before the `ClassifyRuleIdRule`.
+- Both live in the same `*.classify.ts` file; constants go in the matching `*.classify.ruleIds.ts`.
+
+## Do NOT Encode Action in the ruleId String
+
+`diff.action` is already available on the diff object. Encode the **condition**, not the action.
+
+```ts
+// ❌ encodes action
+REQUIRED_ITEM_ADD_NO_DEFAULT: 'json-schema.required.item.add-no-default'
+
+// ✅ describes condition from relevant side
+REQUIRED_ITEM_AFTER_PROPERTY_HAS_NO_DEFAULT: 'json-schema.required.item.after-property-has-no-default'
+```
+
+Exception: static constants for structurally unique cases are fine (`TYPE_ADD`, `TYPE_REMOVE`).
+
+## Naming Conventions
+
+**OpenAPI / REST** (`REST_CLASSIFY_RULE_IDS` in `openapi3.classify.ruleIds.ts`):
+```
+rest.{object}.{property}[.item].{details}
+```
+Example: `rest.operation.security.item.after-security-requirements-are-subset-of-before`
+
+**JSON Schema** (`JSON_SCHEMA_CLASSIFY_RULE_IDS` in `jsonSchema.classify.ruleIds.ts`):
+```
+json-schema.{keyword}[.{sub-property}][.item].{details}
+```
+Example: `json-schema.required.item.after-property-has-no-default`
+
+`details` rules:
+- Use `before-{condition}` when describing the before-state (remove context).
+- Use `after-{condition}` when describing the after-state (add/replace context).
+- Use a plain condition phrase when action-independent (e.g., `incompatible`, `subset-of-before`).
+- Keep it in kebab-case and human-readable.
+
+## JSDoc for Each Constant
+
+Every constant must have a JSDoc comment stating:
+1. What structural condition it represents.
+2. The default classification behaviour.
+
+```ts
+/**
+ * JSON Schema `required` array item was added and the corresponding property
+ * in the after object has no `default` value.
+ * By default, adding it to `required` is breaking.
+ */
+REQUIRED_ITEM_AFTER_PROPERTY_HAS_NO_DEFAULT: 'json-schema.required.item.after-property-has-no-default',
+```

jest.config.ts

@@ -3,6 +3,7 @@ module.exports = {
   testTimeout: 100000,
   transform: {
     '^.+\\.tsx?$': 'ts-jest',
+    '^.+\\.ya?ml$': '<rootDir>/test/transforms/yaml-transform.cjs',
   },
   transformIgnorePatterns: [
     '<rootDir>/node_modules/',

src/api.ts

@@ -1,4 +1,4 @@
-import { COMPARE_MODE_DEFAULT, COMPARE_SCOPE_ROOT, CompareEngine, CompareOptions, CompareResult } from './types'
+import { COMPARE_MODE_DEFAULT, COMPARE_SCOPE_ROOT, CompareEngine, CompareOptions, CompareResult, Diff, DiffClassifier, DiffType } from './types'
 import { compareJsonSchema } from './jsonSchema'
 import { compareGraphApi } from './graphapi'
 import { compareAsyncApi } from './asyncapi'
@@ -17,6 +17,10 @@ import {
   OpenApiSpecVersion,
 } from '@netcracker/qubership-apihub-api-unifier'
 import { DEFAULT_NORMALIZED_RESULT, DEFAULT_OPTION_DEFAULTS_META_KEY, DEFAULT_OPTION_ORIGINS_META_KEY, DIFF_META_KEY } from './core'
+import { matchingDiffClassifier, MatchingRule } from './core'
+import openapi3Rules from './openapi/openapi3.classify.rules.yaml'
+import jsonSchemaRules from './jsonSchema/jsonSchema.classify.rules.yaml'
+import generalRules from './core/general.classify.rules.yaml'
 
 function isOpenApiSpecVersion(specType: SpecType): specType is OpenApiSpecVersion {
   return specType === SPEC_TYPE_OPEN_API_30 || specType === SPEC_TYPE_OPEN_API_31
@@ -54,15 +58,27 @@ export const COMPARE_ENGINES_MAP: Record<SpecType, CompareEngine> = {
   [SPEC_TYPE_GRAPH_API]: compareGraphApi,
 }
 
+function buildOobClassifier(specType: SpecType): DiffClassifier | undefined {
+  if (isOpenApiSpecVersion(specType)) {
+    return matchingDiffClassifier([
+      ...(jsonSchemaRules as MatchingRule[]),
+      ...(openapi3Rules as MatchingRule[]),
+      ...(generalRules as MatchingRule[]),
+    ])
+  }
+  return undefined
+}
+
 // Wrapper function. Use it!
 export function apiDiff(before: unknown, after: unknown, options: CompareOptions = {}): CompareResult {
   const beforeSpec = resolveSpec(before)
   const afterSpec = resolveSpec(after)
   if (!areSpecTypesCompatible(beforeSpec.type, afterSpec.type)) {
     throw new Error(`Specification cannot be different. Got ${beforeSpec.type} and ${afterSpec.type}`)
   }
-  const engine = COMPARE_ENGINES_MAP[selectEngineSpecType(beforeSpec.type, afterSpec.type)]
-  return engine(before, after, {
+  const engineSpecType = selectEngineSpecType(beforeSpec.type, afterSpec.type)
+  const engine = COMPARE_ENGINES_MAP[engineSpecType]
+  const result = engine(before, after, {
     mode: COMPARE_MODE_DEFAULT,
     normalizedResult: DEFAULT_NORMALIZED_RESULT,
     metaKey: DIFF_META_KEY,
@@ -75,4 +91,35 @@ export function apiDiff(before: unknown, after: unknown, options: CompareOptions
     createdMergedJso: new Set(),
     ...options,
   })
+
+  const oobClassifier = buildOobClassifier(engineSpecType)
+
+  if (oobClassifier || options.diffClassifier) {
+    for (const diff of result.diffs) {
+      const preType = diff.type
+
+      if (oobClassifier) {
+        const oobResult = oobClassifier(diff)
+        if (oobResult?.type !== undefined) {
+          //TODO this a a part of validation harness for transition period
+          // from classify rules to separate diff identification and classification
+          if (oobResult.type !== preType) {
+            throw new Error(
+              `OOB classifier type mismatch for classifyRuleId '${diff.classifyRuleId}': engine='${preType}', oob='${oobResult.type}'`,
+            )
+          }
+          diff.type = oobResult.type
+        }
+      }
+
+      if (options.diffClassifier) {
+        const userResult = options.diffClassifier(diff)
+        if (userResult?.type !== undefined) {
+          diff.type = userResult.type
+        }
+      }
+    }
+  }
+
+  return result
 }

src/core/diff.ts

@@ -22,12 +22,16 @@ export const NEVER_KEY = Symbol('never-key')
 
 export const createDiff = <D extends Diff>(diff: Omit<D, 'type'>, ctx: CompareContext): D => {
   const classifierRule = ctx.rules?.$ ?? {}//todo. rules should be evaluated, like in json-crawl
-  const mutableDiffCopy = { ...diff, type: unclassified } as D
+  const index = diff.action === DiffAction.rename ? 2 : [DiffAction.add, DiffAction.remove, DiffAction.replace].indexOf(diff.action)
+
+  const classifyRuleIdDef = ctx.rules?.classifyRuleId
+  const classifyRuleIdElement = Array.isArray(classifyRuleIdDef) ? classifyRuleIdDef[index] : classifyRuleIdDef
+  const classifyRuleId = isFunc(classifyRuleIdElement) ? classifyRuleIdElement(ctx) : classifyRuleIdElement
+  const mutableDiffCopy = { ...diff, type: unclassified, classifyRuleId, effectiveBwcScope: ctx.apiCompatibilityScope } as D
 
   if (classifierRule) {
     const classifier = Array.isArray(classifierRule) ? classifierRule : allUnclassified
 
-    const index = diff.action === DiffAction.rename ? 2 : [DiffAction.add, DiffAction.remove, DiffAction.replace].indexOf(diff.action)
     const changeType = classifier[index]
 
     try {

src/core/general.classify.rules.yaml

@@ -0,0 +1,20 @@
+# General matching rules that apply across all classifyRuleIds.
+#
+# Rules use classifyRuleId: '*' (WILDCARD_CLASSIFY_RULE_ID) to match any ruleId.
+# Wildcard rules are collected into a separate list inside matchingDiffClassifier
+# and applied after all specific (per-ruleId) rules have been processed.
+#
+# The `type` filter in a wildcard rule is checked against the accumulated result
+# type from preceding specific rules, not the engine's final diff type. This
+# allows the wildcard to react to the type established by specific rules.
+#
+# This rule replicates the engine's reclassifyBreakingToRisky logic:
+# any diff whose path is marked as NOT_BACKWARD_COMPATIBLE and whose
+# accumulated classification is 'breaking' is promoted to 'risky'.
+
+- match:
+    classifyRuleId: "*"
+    effectiveBwcScope: NOT_BACKWARD_COMPATIBLE
+    type: breaking
+  set:
+    type: risky

src/core/index.ts

@@ -5,3 +5,4 @@ export * from './mapping'
 export * from './diff'
 export * from './rules'
 export * from './description'
+export * from './matchingDiffClassifier'

src/core/matchingDiffClassifier.ts

@@ -0,0 +1,113 @@
+import { ActionType, ApiCompatibilityKind, CompareScope, Diff, DiffClassifier, DiffClassifierResult, DiffType } from '../types'
+
+/** Use this as `classifyRuleId` in a matching rule to match any ruleId. */
+export const WILDCARD_CLASSIFY_RULE_ID = '*'
+
+export type MatchingRuleMatch = {
+  /**
+   * The classifyRuleId to match. Use WILDCARD_CLASSIFY_RULE_ID ('*') to match any
+   * classifyRuleId. Wildcard rules are collected into a separate list and
+   * applied after all specific rules have been processed.
+   */
+  classifyRuleId: string
+  action?: ActionType | ActionType[]
+  scope?: CompareScope | CompareScope[]
+  /**
+   * Matches against the accumulated result type from rules applied so far,
+   * falling back to the diff's original type when no preceding rule has
+   * matched yet. This lets wildcard rules react to the type set by specific
+   * rules rather than only the engine's final diff type.
+   */
+  type?: DiffType | DiffType[]
+  effectiveBwcScope?: ApiCompatibilityKind | ApiCompatibilityKind[]
+}
+
+export type MatchingRule = {
+  match: MatchingRuleMatch
+  set: { type: DiffType }
+}
+
+function matchesValue<T>(value: T | undefined, filter: T | T[]): boolean {
+  return Array.isArray(filter) ? filter.includes(value as T) : value === filter
+}
+
+function ruleApplies(diff: Diff, match: MatchingRuleMatch, currentType?: DiffType): boolean {
+  if (match.action !== undefined && !matchesValue(diff.action as ActionType, match.action)) {
+    return false
+  }
+  if (match.scope !== undefined && !matchesValue(diff.scope, match.scope)) {
+    return false
+  }
+  if (match.type !== undefined && !matchesValue(currentType ?? diff.type, match.type)) {
+    return false
+  }
+  if (
+    match.effectiveBwcScope !== undefined &&
+    !matchesValue(diff.effectiveBwcScope, match.effectiveBwcScope as ApiCompatibilityKind | ApiCompatibilityKind[])
+  ) {
+    return false
+  }
+  return true
+}
+
+/**
+ * Builds a DiffClassifier from an ordered array of matching rules.
+ *
+ * Rules are grouped by classifyRuleId. Rules whose classifyRuleId is
+ * WILDCARD_CLASSIFY_RULE_ID ('*') are collected into a separate wildcard list and
+ * applied after all specific rules for the diff's classifyRuleId.
+ *
+ * Rules are applied in direct (array) order; the LAST matching rule wins.
+ * Place a more-general rule first and the more-specific (overriding) rule
+ * after it so the specific rule takes precedence.
+ *
+ * The `type` filter checks the accumulated result type from preceding rules,
+ * falling back to the diff's original type. This allows wildcard rules to
+ * react to the type established by specific rules.
+ */
+export function matchingDiffClassifier(rules: MatchingRule[]): DiffClassifier {
+  const ruleMap = new Map<string, MatchingRule[]>()
+  const wildcardRules: MatchingRule[] = []
+
+  for (const rule of rules) {
+    const id = rule.match.classifyRuleId
+    if (id === WILDCARD_CLASSIFY_RULE_ID) {
+      wildcardRules.push(rule)
+    } else {
+      let group = ruleMap.get(id)
+      if (!group) {
+        group = []
+        ruleMap.set(id, group)
+      }
+      group.push(rule)
+    }
+  }
+
+  return (diff: Diff): DiffClassifierResult | undefined => {
+    if (!diff.classifyRuleId) {
+      return undefined
+    }
+    const candidates = ruleMap.get(diff.classifyRuleId)
+    if (!candidates && wildcardRules.length === 0) {
+      return undefined
+    }
+
+    let result: DiffClassifierResult | undefined = undefined
+
+    // Specific rules applied in direct order; last match wins.
+    for (const candidate of candidates ?? []) {
+      if (ruleApplies(diff, candidate.match, result?.type)) {
+        result = { type: candidate.set.type }
+      }
+    }
+
+    // Wildcard rules applied in direct order after all specific rules.
+    for (const candidate of wildcardRules) {
+      if (ruleApplies(diff, candidate.match, result?.type)) {
+        result = { type: candidate.set.type }
+      }
+    }
+
+    return result
+  }
+}

src/index.ts

@@ -27,8 +27,16 @@ export type {
   DiffReplace,
   DiffRename,
   DiffMetaRecord,
+  DiffClassifier,
+  DiffClassifierResult,
+  ClassifyRuleIdResolver,
+  ClassifyRuleIdElement,
+  ClassifyRuleIdRule,
 } from './types'
 
+export { matchingDiffClassifier, WILDCARD_CLASSIFY_RULE_ID } from './core'
+export type { MatchingRule, MatchingRuleMatch } from './core'
+
 export {
   isDiffAdd,
   isDiffRemove,
@@ -42,3 +50,5 @@ export {
   onlyExistedArrayIndexes
 } from './utils'
 
+export { REST_CLASSIFY_RULE_IDS } from './openapi'
+export { JSON_SCHEMA_CLASSIFY_RULE_IDS } from './jsonSchema'

src/jsonSchema/index.ts

@@ -2,6 +2,7 @@ export * from './jsonSchema.compare'
 export * from './jsonSchema.resolver'
 export * from './jsonSchema.classify'
 export * from './jsonSchema.mapping'
+export * from './jsonSchema.classify.ruleIds'
 export * from './jsonSchema.types'
 export * from './jsonSchema.adapter'
 export * from './jsonSchema.utils'