feat: show diff when docs out-of-sync with --check

Author: bmish

lib/generator.ts

@@ -18,6 +18,7 @@ import { findSectionHeader, replaceOrCreateHeader } from './markdown.js';
 import { resolveConfigsToRules } from './config-resolution.js';
 import { RuleDocTitleFormat } from './rule-doc-title-format.js';
 import { parseConfigEmojiOptions } from './configs.js';
+import { diff } from 'jest-diff';
 import type { RuleDetails } from './types.js';
 
 /**
@@ -188,6 +189,7 @@ export async function generate(
             pathToDoc
           )}`
         );
+        console.error(diff(contentsNew, contents, { expand: false }));
         process.exitCode = 1;
       }
     } else {
@@ -251,6 +253,7 @@ export async function generate(
           pathToReadme
         )} is out-of-date.`
       );
+      console.error(diff(readmeContentsNew, readmeContents, { expand: false }));
       process.exitCode = 1;
     }
   } else {

package-lock.json

@@ -40,12 +40,13 @@
     "lint:types": "tsc",
     "prepublishOnly": "tsc",
     "release": "release-it",
-    "test": "node --max-old-space-size=4096 --experimental-vm-modules node_modules/jest/bin/jest.js --coverage"
+    "test": "node --max-old-space-size=4096 --experimental-vm-modules node_modules/jest/bin/jest.js --colors --coverage"
   },
   "dependencies": {
     "@typescript-eslint/utils": "^5.38.1",
     "camelcase": "^7.0.0",
     "commander": "^9.4.0",
+    "jest-diff": "^29.2.1",
     "markdown-table": "^3.0.2",
     "type-fest": "^3.0.0"
   },

package.json

@@ -1082,11 +1082,41 @@ exports[`generator #generate with \`--url-configs\` option with only recommended
 `;
 
 exports[`generator #generate with --check prints the issues, exits with failure, and does not write changes 1`] = `
+[
+  "- Expected
++ Received
+
+- # Description for no-foo (\`test/no-foo\`)
+-
+- <!-- end auto-generated rule header -->
+-
++ # test/no-foo",
+]
+`;
+
+exports[`generator #generate with --check prints the issues, exits with failure, and does not write changes 2`] = `
+[
+  "- Expected
++ Received
+
+  ## Rules
+- <!-- begin auto-generated rules list -->
+-
+- | Name                           | Description             |
+- | :----------------------------- | :---------------------- |
+- | [no-foo](docs/rules/no-foo.md) | Description for no-foo. |
+-
+- <!-- end auto-generated rules list -->
+",
+]
+`;
+
+exports[`generator #generate with --check prints the issues, exits with failure, and does not write changes 3`] = `
 "## Rules
 "
 `;
 
-exports[`generator #generate with --check prints the issues, exits with failure, and does not write changes 2`] = `""`;
+exports[`generator #generate with --check prints the issues, exits with failure, and does not write changes 4`] = `"# test/no-foo"`;
 
 exports[`generator #generate with --config-emoji and removing default emoji for a config reverts to using a badge for the config 1`] = `
 "## Rules

test/lib/__snapshots__/generator-test.ts.snap

@@ -2728,7 +2728,7 @@ describe('generator', function () {
 
           'README.md': '## Rules\n',
 
-          'docs/rules/no-foo.md': '',
+          'docs/rules/no-foo.md': '# test/no-foo',
 
           // Needed for some of the test infrastructure to work.
           node_modules: mockFs.load(
@@ -2745,7 +2745,7 @@ describe('generator', function () {
       it('prints the issues, exits with failure, and does not write changes', async function () {
         const consoleErrorStub = sinon.stub(console, 'error');
         await generate('.', { check: true });
-        expect(consoleErrorStub.callCount).toBe(2);
+        expect(consoleErrorStub.callCount).toBe(4);
         // Use join to handle both Windows and Unix paths.
         expect(consoleErrorStub.firstCall.args).toStrictEqual([
           `Please run eslint-doc-generator. A rule doc is out-of-date: ${join(
@@ -2754,9 +2754,11 @@ describe('generator', function () {
             'no-foo.md'
           )}`,
         ]);
-        expect(consoleErrorStub.secondCall.args).toStrictEqual([
+        expect(consoleErrorStub.secondCall.args).toMatchSnapshot(); // Diff
+        expect(consoleErrorStub.thirdCall.args).toStrictEqual([
           'Please run eslint-doc-generator. README.md is out-of-date.',
         ]);
+        expect(consoleErrorStub.getCall(3).args).toMatchSnapshot(); // Diff
         consoleErrorStub.restore();
 
         expect(readFileSync('README.md', 'utf8')).toMatchSnapshot();