feat(comparisons): SHA unifying, legacy-json comparison

[avivkeller]

This PR does two things:

1. In preparation for 2), this PR changes our generation and comparison to use the same nodejs/node SHA. Previously, the latest SHA was always used. Now, main will always use the latest SHA, and a PR will use the SHA that main most recently ran off of.

2. Adds a legacy-json comparator

Note: Compare and Generate Docs appears to have failed, however, this is not the case. It works, see https://github.com/nodejs/doc-kit/actions/runs/20274890876?pr=521. It thinks it failed, as there is no main SHA to compare against.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
api-docs-tooling	Ready	Preview	Dec 19, 2025 0:16am

[codecov]

Codecov Report

❌ Patch coverage is 0% with 82 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.87%. Comparing base (9ddf8f9) to head (22feb92).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
scripts/compare-builds/web.mjs	0.00%	44 Missing ⚠️
scripts/compare-builds/legacy-json.mjs	0.00%	34 Missing ⚠️
scripts/compare-builds/utils.mjs	0.00%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #521      +/-   ##
==========================================
+ Coverage   79.58%   79.87%   +0.28%     
==========================================
  Files         120      122       +2     
  Lines       12056    12013      -43     
  Branches      841      841              
==========================================
  Hits         9595     9595              
+ Misses       2458     2415      -43     
  Partials        3        3              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[avivkeller]

Example output (Note that this output has been manually modified to demonstrate the diff, and is not based on an actual PR change):

legacy-html generator

assert.json

Expected values to be strictly deep-equal:
+ actual - expected
... Skipped lines

  {
    api: 'assert',
    modules: [
      {
        classes: [
...
                  'pr-url': 'https://github.com/nodejs/node/pull/58849',
+                 description: 'Messageee may now be a `printf`-like format string or function.',
-                 description: 'Message may now be a `printf`-like format string or function.',
                  version: 'REPLACEME'
                },
                {
                  'pr-url': 'https://github.com/nodejs/node/pull/30766',
                  description: 'NaN is now treated as being identical if both sides are NaN.',
...
                  name: 'return',
+                 textRaw: 'Returnes: {Promise}',
-                 textRaw: 'Returns: {Promise}',
                  type: 'Promise'
                }
              }
            ],
            textRaw: '`assert.rejects(asyncFn[, error][, message])`',
...
                name: 'comparison_details',
+               textRaw: 'Comparieson details',
-               textRaw: 'Comparison details',
                type: 'module'
              }
            ],
            name: 'partialDeepStrictEqual',
            signatures: [
...
    ],
+   source: 'doc/api/assert_me.md',
-   source: 'doc/api/assert.md',
    type: 'module'
  }

[Copilot]

Pull request overview

This PR refactors the build comparison workflow to use consistent Node.js SHA references across base and head comparisons, and adds a new legacy-json comparator. The main branch will always use the latest nodejs/node SHA, while PRs will use the SHA that main most recently ran against, ensuring accurate comparisons.

Key changes:

• Consolidates comparison logic into the main generation workflow
• Adds SHA tracking via artifacts to ensure base/head use the same Node.js version
• Introduces a new legacy-json comparator to detect differences in JSON output
• Simplifies the web comparator implementation

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
.github/workflows/generate.yml	Renamed workflow, added prepare job for SHA coordination, integrated comparison steps into generation job
.github/workflows/leave-comment.yml	New workflow to aggregate and post comparison results to PRs
.github/workflows/compare-builds.yml	Removed entire file as comparison logic moved to generate.yml
scripts/compare-builds/utils.mjs	New utility module exporting shared BASE and HEAD paths
scripts/compare-builds/web.mjs	Refactored to use shared utils and simplified comparison logic
scripts/compare-builds/legacy-json.mjs	New comparator for detecting differences in legacy JSON output

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[avivkeller]

Bump @nodejs/web-infra

[ovflowd]

Code itself looks good, would appreciate some more breakdown of functions, more documentation... We need to ensure DX and maintainability here are doable.

[avivkeller]

more documentation

I added some documentation files I was already working on to this PR. It's a bit unrelated, so I can also move them to a follow-up.