Conversation
Split monolithic README into focused docs pages covering input formats, CLI reference, output formats, comparison modes, and programmatic API. The README now serves as a concise overview with links to deeper docs. Key improvements: - Explain what config files are and where YAML/JSON configs come from - Show clear before/after examples for plugin-aware and rule matching - Document all supported file formats with inline code examples - Clarify the left/right convention and how labels are derived Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
Important Review skippedReview was skipped due to path filters ⛔ Files ignored due to path filters (1)
CodeRabbit blocks several paths by default. You can override this behavior by explicitly including those paths in the path filters. For example, including ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
WalkthroughThis pull request adds comprehensive documentation for the pack-config-diff tool, introducing six new documentation files covering getting started, CLI reference, input/output formats, comparison modes, and programmatic API usage. The README is updated with reworded descriptions and expanded guidance linking to the new documentation. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Review: Documentation overhaulThis PR does a good job restructuring the README and splitting content into focused docs pages. The structure, link organization, and concept explanations (left/right convention, format limitations table, comparison modes walkthrough) are clear improvements. A few accuracy issues need fixing before merge. Critical: detailed output format is wrong in multiple docs The example output shown in the README, Minor:
Minor:
|
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| dev: false | ||
| prod: true | ||
| Impact: Minification is now enabled, usually reducing bundle size at the cost of build time. | ||
| Docs: https://webpack.js.org/configuration/optimization/#optimizationminimize |
There was a problem hiding this comment.
The output shown here doesn't match what formatDetailed (aliased from formatContextual) actually produces.
The actual output uses:
- A header block with
=separators and the titleWebpack/Rspack Configuration Comparison - A two-line comparing block:
Comparing: dev.json/vs: prod.json - Entry labels
What it does:,Affects:,Default:,Values:,Impact:,Documentation:— notDescription:/Docs: - Values grouped under a
Values:block, not labelled inline asdev: "development"
This example was likely copied from the old README before the formatter was redesigned. It should be regenerated by running the tool against the sample dev.json/prod.json configs shown just above it.
| Docs: https://webpack.js.org/configuration/target/ | ||
|
|
||
| Legend: [+] added, [-] removed, [~] changed | ||
| ``` |
There was a problem hiding this comment.
Same format mismatch as in docs/getting-started.md. The actual formatDetailed output does not use Description: or Docs: labels, and the header is not pack-config-diff — Semantic config diff. The real output from src/formatter.ts (formatContextual) uses:
================================================================================
Webpack/Rspack Configuration Comparison
================================================================================
Comparing: dev.json
vs: prod.json
and per-entry:
What it does:
<description>
Affects: <affects>
Default: <default>
Values:
dev: <oldValue>
prod: <newValue>
Impact: <impact>
Documentation: <url>
This entire block should be regenerated from the actual tool output.
| Description: Defines target runtime environment for output bundles. | ||
| prod-client: "web" | ||
| Docs: https://webpack.js.org/configuration/target/ | ||
| ... |
There was a problem hiding this comment.
Same issue as in the dedicated docs pages — the format shown here (Description:, Docs:, Comparing: X ↔ Y) does not match the actual formatDetailed output. The header and per-entry labels are different. Should be regenerated from actual tool output.
| maxDepth: null, // limit comparison depth (null = unlimited) | ||
| ignoreKeys: [], // keys to skip everywhere | ||
| ignorePaths: [], // dot-paths to skip (supports wildcards) | ||
| pathSeparator: "." // separator for human-readable paths |
There was a problem hiding this comment.
normalizePaths is a valid DiffOptions property (declared in src/types.ts and handled in src/diffEngine.ts) but is missing from this options table. Consider adding:
| pathSeparator: "." // separator for human-readable paths | |
| normalizePaths: true, // normalize absolute paths to relative (default: true) | |
| pathSeparator: "." // separator for human-readable paths |
| } | ||
| ``` | ||
|
|
||
| ### With real plugins |
There was a problem hiding this comment.
This section is misleading. Node.js require() does not natively support export default syntax in .js files — it's CJS, not ESM. The code in src/cli.ts does handle moduleExports?.default (to support pre-transpiled output from ts-node or babel), but a plain .js file with export default { ... } will throw a SyntaxError when require()'d directly.
This pattern works for .ts files (ts-node transpiles them) but should not be documented as a supported .js feature unless the project adds ESM support. Consider removing this subsection from the .js docs, or clarifying that it only works when the file has already been transpiled.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/cli-reference.md`:
- Around line 5-7: Change the usage code fence for the CLI example so it
includes the bash language tag (i.e., replace the opening triple backticks for
the block containing "pack-config-diff --left=<file> --right=<file> [options]"
with ```bash) to satisfy markdown linting; locate the fenced block that contains
the "pack-config-diff --left=<file> --right=<file> [options]" usage and add the
language tag to the opening fence.
- Around line 110-115: Update the Exit codes table to reflect that exit code 0
is returned both when no differences are found and when the CLI shows the help
text; specifically mention that run() returns 0 for "no differences" and for
"help displayed (e.g., --help)" so CI/scripts won't misinterpret help output as
success-with-no-diff. Locate the table entry for code `0` in
docs/cli-reference.md and change its Meaning cell to include both cases (no
differences found and help displayed), optionally mirroring the run() behavior
described in the CLI implementation.
In `@docs/comparison-modes.md`:
- Around line 21-24: The fenced code block under the "Without `--plugin-aware`"
example is unlabeled (violates MD040); update the plain fenced block that
currently contains "1 changes: +0 -0 ~1" to include a language identifier (e.g.,
change the opening fence to ```text) so the snippet is labeled and
markdownlint-compliant; locate the example near the "Without `--plugin-aware`"
heading to make the edit.
In `@docs/output-formats.md`:
- Around line 13-42: The fenced code block containing the pack-config-diff
example is missing a language specifier and triggers markdownlint MD040; add a
language identifier (for example `text`) after the opening triple backticks to
label the block (the block starting with "pack-config-diff — Semantic config
diff") so the linter stops flagging it.
- Around line 108-111: The docs incorrectly claim YAML mirrors the JSON
"entries" shape; update docs/output-formats.md to explain that the YAML
formatter emits top-level keys metadata and summary and a grouped changes
structure (keyed by change type) rather than raw entries — reference the actual
output keys metadata, summary, changes (not entries) and the formatter
implementation (formatter/exported function that builds these keys) when
rewording the section and adjust the example wording to describe the grouped
changes format consumers should expect.
In `@docs/programmatic-api.md`:
- Around line 40-51: The constructor options documentation for DiffEngine is
missing two supported options: add `format` and `normalizePaths` to the options
list in the docs so examples match the implementation; update the code sample
under "Constructor options" to include `format: "default" | "compact" | ...` (or
the actual allowed values from the DiffEngine constructor) and `normalizePaths:
true | false` alongside the existing keys, and ensure the option descriptions
correspond to the behavior implemented in the DiffEngine constructor and types
(e.g., `format` controls output formatting and `normalizePaths` toggles path
normalization).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: c3d5d0e5-7318-4193-a74c-b390110315ed
📒 Files selected for processing (7)
README.mddocs/cli-reference.mddocs/comparison-modes.mddocs/getting-started.mddocs/input-formats.mddocs/output-formats.mddocs/programmatic-api.md
| ``` | ||
| pack-config-diff --left=<file> --right=<file> [options] | ||
| ``` |
There was a problem hiding this comment.
Add a language tag to the usage fence.
Use bash for the usage block to keep markdown linting consistent.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/cli-reference.md` around lines 5 - 7, Change the usage code fence for
the CLI example so it includes the bash language tag (i.e., replace the opening
triple backticks for the block containing "pack-config-diff --left=<file>
--right=<file> [options]" with ```bash) to satisfy markdown linting; locate the
fenced block that contains the "pack-config-diff --left=<file> --right=<file>
[options]" usage and add the language tag to the opening fence.
| ## Exit codes | ||
|
|
||
| | Code | Meaning | | ||
| |------|---------| | ||
| | `0` | No differences found | | ||
| | `1` | Differences found, or an error occurred | |
There was a problem hiding this comment.
Exit code 0 meaning is incomplete.
run() returns 0 both when no differences are found and when --help is shown (src/cli.ts:294-345). Please reflect that in the table to avoid CI/script confusion.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/cli-reference.md` around lines 110 - 115, Update the Exit codes table to
reflect that exit code 0 is returned both when no differences are found and when
the CLI shows the help text; specifically mention that run() returns 0 for "no
differences" and for "help displayed (e.g., --help)" so CI/scripts won't
misinterpret help output as success-with-no-diff. Locate the table entry for
code `0` in docs/cli-reference.md and change its Meaning cell to include both
cases (no differences found and help displayed), optionally mirroring the run()
behavior described in the CLI implementation.
| Without `--plugin-aware`: | ||
| ``` | ||
| 1 changes: +0 -0 ~1 | ||
| ``` |
There was a problem hiding this comment.
Add language identifiers to plain fenced code blocks.
Several output/example blocks use unlabeled fences. Please tag them (for example text) to satisfy markdownlint MD040 and keep docs lint-clean.
Suggested patch
-```
+```text
1 changes: +0 -0 ~1</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against the current code and only fix it if needed.
In @docs/comparison-modes.md around lines 21 - 24, The fenced code block under
the "Without --plugin-aware" example is unlabeled (violates MD040); update the
plain fenced block that currently contains "1 changes: +0 -0 ~1" to include a
language identifier (e.g., change the opening fence to ```text) so the snippet
is labeled and markdownlint-compliant; locate the example near the "Without
--plugin-aware" heading to make the edit.
</details>
<!-- fingerprinting:phantom:triton:hawk -->
<!-- This is an auto-generated comment by CodeRabbit -->
| ``` | ||
| pack-config-diff — Semantic config diff | ||
| Comparing: dev.json ↔ prod.json | ||
| Found 3 difference(s): 1 added, 0 removed, 2 changed | ||
|
|
||
| 1. [~] mode | ||
| Description: Sets webpack optimization defaults for development or production. | ||
| Affects: Minification, tree-shaking, and debug ergonomics | ||
| Default: production | ||
| dev: "development" | ||
| prod: "production" | ||
| Impact: Switching mode from development to production changes optimization defaults and debugging behavior. | ||
| Docs: https://webpack.js.org/configuration/mode/ | ||
|
|
||
| 2. [~] optimization.minimize | ||
| Description: Enables or disables code minimization. | ||
| Affects: Bundle size and build time | ||
| Default: true in production | ||
| dev: false | ||
| prod: true | ||
| Impact: Minification is now enabled, usually reducing bundle size at the cost of build time. | ||
| Docs: https://webpack.js.org/configuration/optimization/#optimizationminimize | ||
|
|
||
| 3. [+] target | ||
| Description: Defines target runtime environment for output bundles. | ||
| prod: "web" | ||
| Docs: https://webpack.js.org/configuration/target/ | ||
|
|
||
| Legend: [+] added, [-] removed, [~] changed | ||
| ``` |
There was a problem hiding this comment.
Specify a language for this fenced output block.
This unlabeled fence triggers markdownlint MD040; text would be appropriate here.
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 31-31: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/output-formats.md` around lines 13 - 42, The fenced code block
containing the pack-config-diff example is missing a language specifier and
triggers markdownlint MD040; add a language identifier (for example `text`)
after the opening triple backticks to label the block (the block starting with
"pack-config-diff — Semantic config diff") so the linter stops flagging it.
| ## `yaml` | ||
|
|
||
| Same structure as `json` but in YAML. Useful if your tooling prefers YAML: | ||
|
|
There was a problem hiding this comment.
YAML structure description is incorrect.
The doc says YAML has the same structure as JSON, but implementation outputs metadata, summary, and grouped changes (not raw entries) per src/formatter.ts:6-23. Please update wording to avoid misleading downstream tooling users.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/output-formats.md` around lines 108 - 111, The docs incorrectly claim
YAML mirrors the JSON "entries" shape; update docs/output-formats.md to explain
that the YAML formatter emits top-level keys metadata and summary and a grouped
changes structure (keyed by change type) rather than raw entries — reference the
actual output keys metadata, summary, changes (not entries) and the formatter
implementation (formatter/exported function that builds these keys) when
rewording the section and adjust the example wording to describe the grouped
changes format consumers should expect.
| ### Constructor options | ||
|
|
||
| ```javascript | ||
| const engine = new DiffEngine({ | ||
| includeUnchanged: false, // include unchanged values in results | ||
| pluginAware: false, // compare class instances by properties | ||
| matchRulesByTest: false, // match module.rules by test pattern | ||
| maxDepth: null, // limit comparison depth (null = unlimited) | ||
| ignoreKeys: [], // keys to skip everywhere | ||
| ignorePaths: [], // dot-paths to skip (supports wildcards) | ||
| pathSeparator: "." // separator for human-readable paths | ||
| }) |
There was a problem hiding this comment.
Constructor options list is incomplete.
DiffEngine also supports format and normalizePaths (see src/diffEngine.ts:14-26 / src/types.ts:34-44). Please include them here so the API reference is complete.
Suggested patch
const engine = new DiffEngine({
includeUnchanged: false, // include unchanged values in results
+ format: "detailed", // output-oriented mode metadata (json/yaml/summary/detailed/markdown)
+ normalizePaths: true, // normalize absolute paths before diffing
pluginAware: false, // compare class instances by properties
matchRulesByTest: false, // match module.rules by test pattern
maxDepth: null, // limit comparison depth (null = unlimited)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ### Constructor options | |
| ```javascript | |
| const engine = new DiffEngine({ | |
| includeUnchanged: false, // include unchanged values in results | |
| pluginAware: false, // compare class instances by properties | |
| matchRulesByTest: false, // match module.rules by test pattern | |
| maxDepth: null, // limit comparison depth (null = unlimited) | |
| ignoreKeys: [], // keys to skip everywhere | |
| ignorePaths: [], // dot-paths to skip (supports wildcards) | |
| pathSeparator: "." // separator for human-readable paths | |
| }) | |
| const engine = new DiffEngine({ | |
| includeUnchanged: false, // include unchanged values in results | |
| format: "detailed", // output-oriented mode metadata (json/yaml/summary/detailed/markdown) | |
| normalizePaths: true, // normalize absolute paths before diffing | |
| pluginAware: false, // compare class instances by properties | |
| matchRulesByTest: false, // match module.rules by test pattern | |
| maxDepth: null, // limit comparison depth (null = unlimited) | |
| ignoreKeys: [], // keys to skip everywhere | |
| ignorePaths: [], // dot-paths to skip (supports wildcards) | |
| pathSeparator: "." // separator for human-readable paths | |
| }) |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/programmatic-api.md` around lines 40 - 51, The constructor options
documentation for DiffEngine is missing two supported options: add `format` and
`normalizePaths` to the options list in the docs so examples match the
implementation; update the code sample under "Constructor options" to include
`format: "default" | "compact" | ...` (or the actual allowed values from the
DiffEngine constructor) and `normalizePaths: true | false` alongside the
existing keys, and ensure the option descriptions correspond to the behavior
implemented in the DiffEngine constructor and types (e.g., `format` controls
output formatting and `normalizePaths` toggles path normalization).
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 770d8612fb
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| If the module uses `export default`, the tool resolves it: | ||
|
|
||
| ```javascript | ||
| // webpack.config.js | ||
| export default { |
There was a problem hiding this comment.
export default .js guidance
This section says a plain .js config can use native export default, but the CLI loader calls require() for .js files (src/cli.ts loadJsLikeConfig), which will fail on ESM syntax/ERR_REQUIRE_ESM in common setups. Users following this example will hit runtime load errors, so the docs should limit .js examples to CommonJS (or explicitly require an ESM-compatible loading path).
Useful? React with 👍 / 👎.
| 1. [~] plugins.[0].filename | ||
| left: "[name].css" | ||
| right: "[name]-[contenthash].css" |
There was a problem hiding this comment.
The example implies --plugin-aware will emit nested property diffs like plugins.[0].filename, but DiffEngine only uses plugin-aware logic to decide equality and, when unequal, records a single change at the instance path (it does not recurse into class-instance fields). This makes the shown output unattainable and can mislead users troubleshooting plugin option changes.
Useful? React with 👍 / 👎.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
| ``` | ||
| pack-config-diff — Semantic config diff | ||
| Comparing: dev.json ↔ prod.json | ||
| Found 3 difference(s): 1 added, 0 removed, 2 changed | ||
|
|
||
| 1. [~] mode | ||
| Description: Sets webpack optimization defaults for development or production. | ||
| Affects: Minification, tree-shaking, and debug ergonomics | ||
| Default: production | ||
| dev: "development" | ||
| prod: "production" | ||
| Impact: Switching mode from development to production changes optimization defaults and debugging behavior. | ||
| Docs: https://webpack.js.org/configuration/mode/ | ||
|
|
||
| 2. [~] optimization.minimize | ||
| Description: Enables or disables code minimization. | ||
| Affects: Bundle size and build time | ||
| Default: true in production | ||
| dev: false | ||
| prod: true | ||
| Impact: Minification is now enabled, usually reducing bundle size at the cost of build time. | ||
| Docs: https://webpack.js.org/configuration/optimization/#optimizationminimize | ||
|
|
||
| 3. [+] target | ||
| Description: Defines target runtime environment for output bundles. | ||
| prod: "web" | ||
| Docs: https://webpack.js.org/configuration/target/ | ||
|
|
||
| Legend: [+] added, [-] removed, [~] changed | ||
| ``` |
There was a problem hiding this comment.
The detailed output example here doesn't match what the actual formatter produces. The real output from formatContextual() (aliased as formatDetailed()) looks substantially different:
================================================================================
Webpack/Rspack Configuration Comparison
================================================================================
Comparing: dev.json
vs: prod.json
Found 2 difference(s): 0 added, 0 removed, 2 changed
================================================================================
1. [~] mode
What it does:
Defines the environment mode (development, production, or none)...
Affects: Minification, tree-shaking, source maps, and performance optimizations
Values:
dev: "development"
prod: "production"
Impact: Enabling production optimizations (minification, tree-shaking)
Documentation: https://webpack.js.org/configuration/mode/
...
================================================================================
Legend:
[+] = Added in prod
[-] = Removed from prod
[~] = Changed between configs
Key mismatches with the example shown:
- Header is
Webpack/Rspack Configuration Comparison(with===separators), notpack-config-diff — Semantic config diff Comparing:uses a two-line format (Comparing: X/vs: Y), notX ↔ Y- The field label is
What it does:notDescription: - Values are under a
Values:section, not listed directly - The doc link label is
Documentation:notDocs: - The Legend is multi-line with dynamic labels, not
[+] added, [-] removed, [~] changed
The same mismatch applies to the detailed examples in docs/getting-started.md, docs/comparison-modes.md, and README.md. These all need to be updated to reflect the actual formatter output.
| ```json | ||
| // left.json | ||
| { | ||
| "module": { | ||
| "rules": [ | ||
| { "test": "\\.js$", "use": "babel-loader" }, | ||
| { "test": "\\.css$", "use": "css-loader" } | ||
| ] | ||
| } | ||
| } |
There was a problem hiding this comment.
These code blocks are fenced as json but contain // left.json / // right.json comments, which are invalid JSON syntax. Readers who try to copy-paste them as actual JSON files will get parse errors.
Suggest splitting the file label out as prose and using a plain (unfenced or text-fenced) label, or switching the fence language to something that supports // comments (e.g. jsonc for display purposes). The same pattern appears in the // right.json block immediately below.
| const engine = new DiffEngine({ | ||
| includeUnchanged: false, // include unchanged values in results | ||
| pluginAware: false, // compare class instances by properties | ||
| matchRulesByTest: false, // match module.rules by test pattern | ||
| maxDepth: null, // limit comparison depth (null = unlimited) | ||
| ignoreKeys: [], // keys to skip everywhere | ||
| ignorePaths: [], // dot-paths to skip (supports wildcards) | ||
| pathSeparator: "." // separator for human-readable paths | ||
| }) |
There was a problem hiding this comment.
The DiffEngine constructor also accepts a normalizePaths option (defaulting to true) which controls whether absolute filesystem paths are converted to relative paths before comparison. This is the programmatic equivalent of --no-normalize-paths and should be documented here so users who want to control path normalization via the API know the option exists.
There's also a format field in the internal Required<DiffOptions> type, though it doesn't appear to influence the engine's comparison logic (formatting is handled separately by DiffFormatter), so it may be an artefact — worth double-checking.
| const engine = new DiffEngine({ | |
| includeUnchanged: false, // include unchanged values in results | |
| pluginAware: false, // compare class instances by properties | |
| matchRulesByTest: false, // match module.rules by test pattern | |
| maxDepth: null, // limit comparison depth (null = unlimited) | |
| ignoreKeys: [], // keys to skip everywhere | |
| ignorePaths: [], // dot-paths to skip (supports wildcards) | |
| pathSeparator: "." // separator for human-readable paths | |
| }) | |
| const engine = new DiffEngine({ | |
| includeUnchanged: false, // include unchanged values in results | |
| pluginAware: false, // compare class instances by properties | |
| matchRulesByTest: false, // match module.rules by test pattern | |
| maxDepth: null, // limit comparison depth (null = unlimited) | |
| ignoreKeys: [], // keys to skip everywhere | |
| ignorePaths: [], // dot-paths to skip (supports wildcards) | |
| normalizePaths: true, // convert absolute paths to relative before comparing | |
| pathSeparator: "." // separator for human-readable paths | |
| }) |
| If your config exports a function (common with webpack's `--env` support), the tool calls it automatically with `({}, { mode: "production" })`: | ||
|
|
||
| ```javascript | ||
| // webpack.config.js | ||
| module.exports = (env, argv) => ({ | ||
| mode: argv.mode || "development", | ||
| output: { | ||
| filename: argv.mode === "production" ? "[name]-[contenthash].js" : "[name].js" | ||
| } | ||
| }) | ||
| ``` |
There was a problem hiding this comment.
Worth calling out a subtle constraint here: the tool always invokes function exports with ({}, { mode: "production" }) — this is hardcoded in cli.ts. That means even the --left (baseline/dev) config is evaluated with argv.mode === "production".
For the example above, both sides will resolve to mode: "production", so any mode-driven branching will look identical regardless of which file is --left or --right. Documenting this constraint (e.g., "Note: both configs are called with argv = { mode: 'production' }, so mode-dependent output will reflect production settings for both sides") would help users avoid unexpected results.
|
Review: docs look good overall but a few issues need fixing. See inline comments for detail. Summary: 1) The detailed output examples across all new doc files show wrong format - wrong header, wrong comparison line format, wrong field labels (Description vs What it does, Docs vs Documentation), wrong legend. Run the actual CLI and paste real output. 2) comparison-modes.md has json-fenced blocks with slash-slash comments which is invalid JSON. 3) programmatic-api.md is missing normalizePaths from the DiffEngine constructor options. 4) Minor: function-export argv is hardcoded to mode=production for both left and right sides, which means mode-driven configs resolve identically for both sides. |
1 participant
Summary
Key clarity improvements
webpack.config.jsexports). Explains where they come from (Shakapacker exports, manual dumps, CI artifacts)Test plan
npx jest)Fixes the unclear documentation noted in review — the existing README assumed familiarity with Shakapacker and didn't explain what the input files are.
🤖 Generated with Claude Code
Note
Low Risk
Low risk: documentation-only changes with no runtime/code behavior impact. Main risk is broken/incorrect docs links or examples misleading users.
Overview
Updates
README.mdto be a concise overview with a quick start, clearer explanation of--left/--rightinputs (JS/TS/JSON/YAML), and links to deeper docs instead of embedding full CLI help.Adds new docs pages:
docs/getting-started.md,docs/input-formats.md,docs/output-formats.md,docs/comparison-modes.md,docs/cli-reference.md, anddocs/programmatic-api.md, including concrete examples for markdown/JSON/YAML output, plugin-aware diffs, rule matching, and path normalization.Written by Cursor Bugbot for commit 770d861. Configure here.
Summary by CodeRabbit
Documentation