feat(comparators): compare more generators (#523)

* feat(comparators): compare more generators

* remove comparator too large

* Update object-assertion.mjs

Author: avivkeller

.github/workflows/generate.yml

@@ -74,30 +74,41 @@ jobs:
     runs-on: ubuntu-latest
     needs: prepare
     strategy:
+      fail-fast: false
       matrix:
         include:
           - target: man-page
             input: './node/doc/api/cli.md'
+
           - target: addon-verify
             input: './node/doc/api/addons.md'
+
           - target: api-links
             input: './node/lib/*.js'
+            compare: object-assertion
+
           - target: orama-db
             input: './node/doc/api/*.md'
+            compare: file-size
+
           - target: json-simple
             input: './node/doc/api/*.md'
+
           - target: legacy-json
             input: './node/doc/api/*.md'
-            compare: true
+            compare: object-assertion
+
           - target: legacy-html
             input: './node/doc/api/*.md'
+            compare: file-size
+
           - target: web
             input: './node/doc/api/*.md'
-            compare: true
+            compare: file-size
+
           - target: llms-txt
             input: './node/doc/api/*.md'
-      fail-fast: false
-
+            compare: file-size
     steps:
       - name: Harden Runner
         uses: step-security/harden-runner@95d9a5deda9de15063e7595e9719c11c38c90ae2 # v2.13.2
@@ -154,8 +165,10 @@ jobs:
 
       - name: Compare to base branch
         if: ${{ matrix.compare && needs.prepare.outputs.base-run }}
+        env:
+          GENERATOR: ${{ matrix.target }}
         run: |
-          node scripts/compare-builds/${{ matrix.target }}.mjs > out/comparison.txt
+          node scripts/comparators/${{ matrix.compare }}.mjs > out/comparison.txt
 
       - name: Upload ${{ matrix.target }} artifacts
         uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0

docs/comparators.md

@@ -20,23 +20,23 @@ Comparators are scripts that:
 
 ## Comparator Structure
 
-Comparators are standalone ESM scripts located in `scripts/compare-builds/`:
+Comparators are standalone ESM scripts located in `scripts/comparators/`:
 
 ```
-scripts/compare-builds/
-├── utils.mjs           # Shared utilities (BASE, HEAD paths)
-├── legacy-json.mjs     # Compare legacy JSON output
-├── web.mjs             # Compare web bundle sizes
-└── your-comparator.mjs # Your new comparator
+scripts/comparators/
+├── constants.mjs        # Shared constants (BASE, HEAD, TITLE paths)
+├── file-size.mjs        # Compare file sizes between builds
+├── object-assertion.mjs # Deep equality assertion for JSON objects
+└── your-comparator.mjs  # Your new comparator
 ```
 
 ### Naming Convention
 
-**Each comparator must have the same name as the generator it compares.** For example:
+Comparators can be reused across multiple generators. You specify which comparator to use in the workflow file using the `compare` field. For example:
 
-- `web.mjs` compares output from the `web` generator
-- `legacy-json.mjs` compares output from the `legacy-json` generator
-- `my-format.mjs` would compare output from a `my-format` generator
+- `file-size.mjs` can compare output from `web`, `legacy-html`, or any generator
+- `object-assertion.mjs` can compare JSON output from `legacy-json`, `json-simple`, etc.
+- `my-comparator.mjs` would be a custom comparator for specific needs
 
 ## Creating a Comparator
 
@@ -48,7 +48,7 @@ Create a new file in `scripts/compare-builds/` with the same name as your genera
 // scripts/compare-builds/my-format.mjs
 import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { BASE, HEAD } from './utils.mjs';
+import { BASE, HEAD, TITLE } from './utils.mjs';
 
 // Fetch files from both directories
 const [baseFiles, headFiles] = await Promise.all([BASE, HEAD].map(() => await readdir(dir)));
@@ -105,7 +105,7 @@ const differences = results.filter(Boolean);
 
 // Output markdown results
 if (differences.length > 0) {
-  console.log('## `my-format` Generator');
+  console.log(TITLE);
   console.log('');
   console.log(`Found ${differences.length} difference(s):`);
   console.log('');
@@ -161,5 +161,4 @@ node scripts/compare-builds/my-format.mjs
 
 The comparator will automatically run in GitHub Actions when:
 
-1. Your generator is configured with `compare: true` in the workflow
-2. The comparator filename matches the generator name
+1. Your generator is configured with `compare: <my-comparator>` in the workflow, which tells the system which comparator script to run

scripts/comparators/constants.mjs

@@ -0,0 +1,10 @@
+import { fileURLToPath } from 'node:url';
+
+export const BASE =
+  process.env.BASE || fileURLToPath(import.meta.resolve('../../base'));
+
+export const HEAD =
+  process.env.HEAD || fileURLToPath(import.meta.resolve('../../out'));
+
+export const TITLE =
+  process.env.TITLE || `## \`${process.env.GENERATOR ?? '...'}\` Generator`;

scripts/compare-builds/web.mjs scripts/comparators/file-size.mjsscripts/compare-builds/web.mjs renamed to scripts/comparators/file-size.mjs

@@ -1,7 +1,7 @@
 import { stat, readdir } from 'node:fs/promises';
 import path from 'node:path';
 
-import { BASE, HEAD } from './utils.mjs';
+import { BASE, HEAD, TITLE } from './constants.mjs';
 
 const UNITS = ['B', 'KB', 'MB', 'GB'];
 
@@ -63,8 +63,8 @@ if (changed.length) {
     return `| \`${file}\` | ${formatBytes(base)} | ${formatBytes(head)} | ${diffFormatted} |`;
   });
 
-  console.log('## Web Generator');
+  console.log(TITLE);
   console.log('| File | Base | Head | Diff |');
   console.log('|-|-|-|-|');
-  console.log(rows.join('\n'));
+  console.log(rows.join('\n') + '\n');
 }

scripts/compare-builds/legacy-json.mjs scripts/comparators/object-assertion.mjsscripts/compare-builds/legacy-json.mjs renamed to scripts/comparators/object-assertion.mjs

@@ -2,7 +2,7 @@ import assert from 'node:assert';
 import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
-import { BASE, HEAD } from './utils.mjs';
+import { BASE, HEAD, TITLE } from './constants.mjs';
 
 const files = await readdir(BASE);
 
@@ -17,7 +17,7 @@ const getFileDiff = async file => {
   const headContent = JSON.parse(await readFile(headPath, 'utf-8'));
 
   try {
-    assert.deepStrictEqual(baseContent, headContent);
+    assert.deepStrictEqual(headContent, baseContent);
     return null;
   } catch ({ message }) {
     return details(file, message);
@@ -29,6 +29,6 @@ const results = await Promise.all(files.map(getFileDiff));
 const filteredResults = results.filter(Boolean);
 
 if (filteredResults.length) {
-  console.log('## `legacy-json` generator');
-  console.log(filteredResults.join('\n'));
+  console.log(TITLE);
+  console.log(filteredResults.join('\n') + '\n');
 }

scripts/compare-builds/utils.mjs

@@ -14,17 +14,10 @@
     <link rel="canonical" href="https://nodejs.org/api/__FILENAME__.html" />
     <script async defer src="assets/api.js" type="text/javascript"></script>
     <script>
-      const storedTheme = localStorage.getItem('theme');
-
-      // Follow operating system theme preference
-      if (storedTheme === null && window.matchMedia) {
-        const mq = window.matchMedia('(prefers-color-scheme: dark)');
-        if (mq.matches) {
-          document.documentElement.classList.add('dark-mode');
-        }
-      } else if (storedTheme === 'dark') {
+      (localStorage.getItem('theme') === 'dark' ||
+        (localStorage.getItem('theme') === null &&
+          window.matchMedia?.('(prefers-color-scheme: dark)').matches)) &&
         document.documentElement.classList.add('dark-mode');
-      }
     </script>
   </head>
   <body class="alt apidoc" id="api-section-__FILENAME__">