chore(ipa): CLOUDP-453871 add snapshot and compare scripts for behavior-neutral refactors

[DatMitro]

Proposed changes

Adds two dev scripts for checking that a change to the IPA ruleset does not change its results:

• ipa-snapshot.js lints a spec and writes the findings and the collector entries (violations, adoptions, exceptions) as sorted JSON.
• ipa-snapshot-compare.js compares two snapshots per rule, or this checkout against a git ref, and exits 1 on any difference, so a refactor can be shown to be behavior-neutral.

The collector log path can now be set with IPA_COLLECTOR_FILE, so a snapshot does not overwrite the log in the working directory.

Usage. These are manual dev scripts. Nothing is committed and no CI check is added. To check that a change does not alter results, compare this checkout against a git ref:

node tools/spectral/ipa/scripts/ipa-snapshot-compare.js --spec openapi/v2.json --base origin/main   # add --verbose for the entries

The ref is checked out into a temporary worktree (nothing to build) and removed afterwards, the head is this checkout including uncommitted changes (or --head <git-ref>), and the scripts and spec come from your checkout, so the base ref does not need to contain them. A run on openapi/v2.json takes about 15 seconds. To keep snapshots, write them with ipa-snapshot.js --spec <file> --out <dir> and compare two directories with ipa-snapshot-compare.js <base-dir> <head-dir>; they are large (the collector one is about 166 MB on v2.json, mostly one adoption entry per component per rule), so they are not meant to be committed. Also documented in the IPA CONTRIBUTING guide.

Jira ticket: CLOUDP-453871

Checklist

• I have signed the MongoDB CLA
• I have added tests that prove my fix is effective or that my feature works

Changes to Spectral

• I have read the README file for Spectral Updates

Further comments

Used by the later sub-tasks of CLOUDP-453870. Nothing in the lint run changes: only the collector file name is read from an environment variable.

[wtrocki]

@DatMitro What is the proposed interface to use snapshots? E.g Would we have snapshot committed with github actions checks present?

[DatMitro]

@DatMitro What is the proposed interface to use snapshots? E.g Would we have snapshot committed with github actions checks present?

Right now it's a manual dev tool, with no committed snapshots and no CI check. You run ipa-snapshot.js on the base and on the change, then ipa-snapshot-compare.js on the two outputdirs. I wouldn't commit snapshots: the collector one is ~166 MB on v2.json, and both are cheap to regenerate from any ref. A CI job that snapshots base and head is possible, but it would fail on every intentional rule change. I can make a follow-up item to add the changes as a non-blocking comment on PRs

[maks-m-mongo-leaf]

@DatMitro how exactly do you plan to use these scripts in the future subtasks of https://jira.mongodb.org/browse/CLOUDP-453870 ?

[DatMitro]

@DatMitro how exactly do you plan to use these scripts in the future subtasks of https://jira.mongodb.org/browse/CLOUDP-453870 ?

@maks-m-mongo-leaf I will run it after every change to ensure no classification differences were made during the refactor. In future migrations/fixes as well. I already ran it on the other open PR as it's stacked.