fix(shared): resolve prefixItems alternatives in pattern validation

[YoofiTT96]

Description

A prefixItems entry is either a node or a oneOf/anyOf holding alternatives. Every rule that walks $.properties.nodes.prefixItems[*] has to cope with both shapes, and each coped differently. Four coped wrongly or not at all.

Part of #2932 rework

declaration-paths.ts now owns where a pattern declares a node. It builds the queries that find declarations and reads the resulting pointers back, both driven by one keyword list, so a rule cannot disagree with another about where a declaration lives. The shape-handling disappears from the rules instead of being repeated four ways, and interface-id-exists-on-node is a net deletion.

None of this concerns #2859. These are pre-existing gaps in the prefixItems model, reachable by a pattern that uses no new construct. They are grouped because they are one theme with one release note, and because they carry every behaviour change in the wider items-support work — leaving that work free to be purely additive.

Closes #3058
Closes #3062
Closes #3068
Closes #3069

Behaviour changes — breaking

main never looked inside oneOf or anyOf, so every shape below was accepted. Each is now checked. No published API changes.

Shape	Now	Before
Two alternatives of one entry share a node unique-id oneOf: [ node "db", node "db" ]	error	calm generate emitted both nodes. Verified: with a decision selecting db, architecture validation reports the duplicate
A relationship names an interface belonging to a sibling alternative webapp -> postgres, interfaces: ["my-port"] where my-port is on mysql	error	interfaces were pooled across an entry, so the chosen node need never have declared it. Architecture validation caught it after generation
An entry declares both keywords { oneOf: [...], anyOf: [...] }	error	an element must satisfy both, so the entry is unsatisfiable when the id sets are disjoint and declares unselectable alternatives when they overlap
Nothing references an alternative oneOf: [ node "orphan" ]	warning	invisible to the rule. Fails a build only under --strict

One further rejection is a deliberate contract, not a correction. A unique-id names one kind of thing, so a node id may not equal an interface id even across alternatives that never appear together. Both architectures such a pattern produces are valid, so this rejects something that was not broken. It is recorded in PATTERN-DECISIONS.md rather than justified by #3058.

No pattern in this repository changes result. Every tracked .json declaring properties.nodes.prefixItems or properties.relationships.prefixItems — 28 files, 13 of which use alternatives — was run against the real ruleset on main and on this branch. The findings are byte-identical.

Worth knowing

Two alternatives may expose the same interface id, because only one of them is ever built. A decision never names an interface on its own, so nothing has to tell them apart:

oneOf: [ postgres exposing "db-port", mysql exposing "db-port" ]      accepted

Do not give an entry its own properties as well as alternatives. calm generate keeps the selected alternative and discards the entry's own properties, so whatever it declares is silently lost. Validation reports a duplicate id when the two halves share one, which catches the common case without naming the fault. A rule that names it directly is worth a follow-up.

The two-keyword check is a filtered given with the built-in falsy, not a custom function. Spectral's xor cannot express it, because an entry may legitimately declare neither keyword.

When unique-ids-must-be-unique-in-pattern finds an id twice, it points at the second one. That is only useful if the second one is the later in the file.

It is not, because the rule finds ids by running one query per declaration site and joining the results. Every fixed entry arrives before any alternative, whatever order they appear in. So a pattern declaring dup as an alternative at index 0 and again as a fixed entry at index 1 was reported at index 0 — the earlier of the two.

The matches are now sorted by position before the rule looks for duplicates.

PATTERN-DECISIONS.md is a new behaviour contract at the repository root. It records what each tool guarantees, with no implementation detail and no test references, so it does not go stale when a function is renamed.

Review round

Four of the five review findings led to a change, and the fifth changed in a different way than its diagnosis suggested.

Ordering no longer compares pointer text at all. Text put an alternative ahead of the entry that holds it, because oneOf precedes properties, so a node id declared in both was blamed on the entry — the half an architecture always builds. byBuildOrder compares the parsed indices of the containing declaration instead, which also removes the digit padding that capped array indices at 999,999. There was no test pinning which side gets blamed for that shape; there is now.

JSONPathMatch is exported from helper-functions.ts rather than redeclared, and the hand-rolled groupBy is lodash's.

On the performance finding: these paths are rooted at properties.nodes, so they are lookups, not full-document traversals — adding 5,000 relationships to a document leaves the timing unchanged. Against main the trade runs the other way from how the comment reads, since main runs one query over the pattern and three per node inspected where this runs three over the pattern and one per node. But the eager part was real: all three queries ran before the search started, so a node declared as a plain prefixItems entry paid for two it never needed. The lookup now returns at the first path that matches, and declaredId reads its path with lodash instead of a JSONPath query. Over 600 endpoints on a 300-node pattern that is 23ms against main's 112ms.

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 Documentation update
• 🎨 Code style/formatting changes
• ♻️ Refactoring (no functional changes)
• ⚡ Performance improvements
• ✅ Test additions or updates
• 🔧 Chore (maintenance, dependencies, CI, etc.)

A pattern that validates clean today can fail after this change, so a BREAKING CHANGE: footer is on the commit. Without it fix(shared) would ship these rejections as a patch release.

Affected Components

• CLI (cli/)
• Schema (calm/)
• CALM AI (calm-ai/)
• CALM Hub (calm-hub/)
• CALM Hub UI (calm-hub-ui/)
• CALM Server (calm-server/)
• CALM Widgets (calm-widgets/)
• Documentation (docs/)
• Shared (shared/)
• VS Code Extension (calm-plugins/vscode/)
• Dependencies
• CI/CD

cli/ is the JUnit fixture only, which pins the live rule list. No CLI source changes.

Commit Message Format ✅

fix(shared): resolve prefixItems alternatives in pattern validation, carrying a BREAKING CHANGE: footer that lists the rejections above.

The review round adds fix(shared): order declarations by index, not by pointer text, refactor(shared): reuse the shared match type and lodash groupBy, and perf(shared): stop searching declaration sites at the first match.

Testing

• I have tested my changes locally
• I have added/updated unit tests
• All existing tests pass

Four spec files are new: rules-pattern.spec.ts, node-id-exists.spec.ts, declaration-paths.spec.ts and is-defined-in-oneof-or-anyof.spec.ts. No ruleset-level test existed, because validate.spec.ts mocks Spectral out, so selectors and registration were untested. The last two rules had no unit test at all, on main or here.

Every new guarantee was mutation-tested rather than trusted. Reintroducing the interface pooling, dropping the document-order sort, treating an entry's properties as an alternative, and unregistering the keyword rule each turn the matching tests red and leave the rest green.

Coverage on the changed files is 100% statements and branches, except interface-id-exists-on-node at 95.45/92.85 on a pre-existing branch. Across src/spectral it is 94.64/93.04. Full root npm test is green.

After the review round: shared passes 105 files and 1208 tests, cli 29 files and 659 tests, and root npm test is green. Restoring the raw-pointer sort turns the new ordering test red along with the existing numeric one, and nothing else.

Checklist

• My commits follow the conventional commit format
• I have updated documentation if necessary
• I have added tests for my changes (if applicable)
• My changes follow the project's coding standards

[markscott-ms]

I've read through the pattern decisions and performed a review of the code and am satisfied that this seems reasonable.