feat: Add --enable-command-header option to include command-line in file headers

[koxudaxi]

Summary by CodeRabbit

Release Notes

• New Features

  • Added --enable-command-header CLI option to include command-line options in generated file headers for reproducibility.

• Documentation

  • Updated CLI reference documentation with the new --enable-command-header option and usage examples.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Warning

Rate limit exceeded

@koxudaxi has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 0 minutes and 47 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 70d5687 and e9d9d50.

📒 Files selected for processing (2)

• src/datamodel_code_generator/__init__.py (2 hunks)
• src/datamodel_code_generator/watch.py (1 hunks)

Walkthrough

This PR introduces a new --enable-command-header CLI option that embeds the datamodel-codegen command-line invocation into generated file headers for reproducibility. The feature is threaded through the CLI argument parser, configuration, and generator API, with corresponding documentation and test coverage.

Changes

Cohort / File(s)	Summary
Documentation docs/cli-reference/index.md	Updated categories table index count for Template Customization from 15 to 16; added --enable-command-header entry linking to template-customization reference.
Documentation docs/cli-reference/quick-reference.md	Added --enable-command-header to Template Customization section and alphabetical index, documenting the new CLI option.
Documentation docs/cli-reference/template-customization.md	Detailed reference documentation for --enable-command-header including purpose, usage examples, and input/output schema samples.
CLI Arguments & Metadata src/datamodel_code_generator/arguments.py, src/datamodel_code_generator/cli_options.py	Added --enable-command-header boolean flag to Model customization group with help text for reproducibility; registered option in CLI metadata dictionary under TEMPLATE category.
Core API src/datamodel_code_generator/__init__.py	Extended generate() function signature with enable_command_header: bool and command_line: str | None parameters; integrated command-line injection into header generation logic for both standard and CSV output paths.
CLI Configuration & Entry Point src/datamodel_code_generator/__main__.py	Added enable_command_header: bool = False field to Config class; extended run_generate_from_config() with command_line: str | None parameter; modified main() to conditionally construct command line string using shlex.join() and forward both new parameters to generate().
Test Data & Cases tests/data/expected/main/openapi/enable_command_header.py	Generated expected output fixture file containing Pydantic model definitions (Pet, Pets, User, Users, Id, Rules, Error, Api, Apis, Event, Result) from OpenAPI spec.
Test Implementation tests/main/openapi/test_main_openapi.py	Added test case test_enable_command_header() exercising the new CLI flag with command-line normalization via regex transform for stable test output validation.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Parameter threading across API layers: Understanding the flow from CLI parsing through Config, run_generate_from_config(), to generate() requires tracing multiple files in sequence.
• Duplicate test definition: The test file summary indicates the test_enable_command_header() function appears twice—verify intentionality and consolidate if redundant.
• Header injection logic: Review the command-line injection in __init__.py to confirm proper placement and formatting in generated headers across both standard and CSV paths.
• Command-line construction: Verify shlex.join() usage in __main__.py correctly serializes CLI arguments for reproducibility.

Poem

🐰 A new flag hops into the fold,
--enable-command-header bold,
Commands preserved, headers grown wise,
Reproducibility now materializes! ✨
The feature tree blooms, line by line!

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main feature being added: a new CLI option --enable-command-header that includes command-line invocations in file headers.
Docstring Coverage	✅ Passed	Docstring coverage is 83.33% which is sufficient. The required threshold is 80.00%.

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codspeed-hq]

CodSpeed Performance Report

Merging #2684 will not alter performance

_{Comparing feat/enable-command-header (e9d9d50) with main (ad0de0d)}

Summary

✅ 52 untouched
⏩ 10 skipped¹

Footnotes

1. 10 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.53%. Comparing base (ad0de0d) to head (e9d9d50).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2684   +/-   ##
=======================================
  Coverage   99.53%   99.53%           
=======================================
  Files          81       81           
  Lines       11322    11334   +12     
  Branches     1353     1354    +1     
=======================================
+ Hits        11269    11281   +12     
  Misses         32       32           
  Partials       21       21           

Flag	Coverage Δ
unittests	99.53% <100.00%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[koxudaxi]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

docs/cli-reference/template-customization.md (1)

1290-1296: Consider adding a security note about sensitive data.

The documentation clearly explains the feature's purpose for reproducibility. However, consider adding a brief note warning users that command-line arguments may contain sensitive information (API keys, passwords, file paths with usernames, etc.) that will be embedded in generated files.

📝 Suggested addition

Add a note or warning box after line 1296:

!!! warning "Sensitive Data"
    Be cautious when using this option if your command-line includes sensitive information such as API keys, passwords, or personal file paths. This data will be embedded in the generated file headers.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ad0de0d and 70d5687.

📒 Files selected for processing (9)

• docs/cli-reference/index.md (2 hunks)
• docs/cli-reference/quick-reference.md (2 hunks)
• docs/cli-reference/template-customization.md (2 hunks)
• src/datamodel_code_generator/__init__.py (2 hunks)
• src/datamodel_code_generator/__main__.py (5 hunks)
• src/datamodel_code_generator/arguments.py (1 hunks)
• src/datamodel_code_generator/cli_options.py (1 hunks)
• tests/data/expected/main/openapi/enable_command_header.py (1 hunks)
• tests/main/openapi/test_main_openapi.py (2 hunks)

🧰 Additional context used

🧬 Code graph analysis (2)

tests/data/expected/main/openapi/enable_command_header.py (3)

tests/data/expected/parser/openapi/openapi_parser_parse_modular/bar.py (1)

• Field (6-7)

src/datamodel_code_generator/model/base.py (1)

• name (599-601)

src/datamodel_code_generator/__init__.py (1)

• Error (303-312)

tests/main/openapi/test_main_openapi.py (1)

tests/main/conftest.py (2)

• output_file (94-96)
• run_main_and_assert (196-352)

🪛 LanguageTool

docs/cli-reference/quick-reference.md

[grammar] ~191-~191: Ensure spelling is correct
Context: ...command-line options in file header for reproducibil... - [--enable-faux-immutability](mod...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (12)

• GitHub Check: 3.10 on Windows
• GitHub Check: py312-isort5 on Ubuntu
• GitHub Check: py312-pydantic1 on Ubuntu
• GitHub Check: 3.11 on Windows
• GitHub Check: 3.9 on Windows
• GitHub Check: 3.11 on Ubuntu
• GitHub Check: 3.13 on Windows
• GitHub Check: 3.13 on macOS
• GitHub Check: 3.12 on Windows
• GitHub Check: 3.14 on Windows
• GitHub Check: benchmarks
• GitHub Check: Analyze (python)

🔇 Additional comments (15)

tests/data/expected/main/openapi/enable_command_header.py (1)

1-70: LGTM! Test fixture follows expected pattern.

The test fixture correctly demonstrates the new command header format at line 4. The [COMMAND] placeholder indicates that tests normalize the actual command-line for reproducibility, which is a good practice.

docs/cli-reference/index.md (2)

15-15: LGTM! Option count updated correctly.

The Template Customization category now correctly shows 16 options after adding --enable-command-header.

---

63-63: LGTM! New option added to alphabetical index.

The new --enable-command-header option is correctly placed in alphabetical order with proper linking.

docs/cli-reference/template-customization.md (1)

1290-1563: LGTM! Comprehensive documentation added.

The documentation section follows the established pattern with clear usage examples, input schema, and output demonstration. The feature's purpose for reproducibility is well-explained.

docs/cli-reference/quick-reference.md (1)

114-114: LGTM! Quick reference updated consistently.

The new option is correctly added to both the categorized table and alphabetical index with consistent descriptions.

Note: The static analysis grammar hint at line 191 is a false positive—the description is intentionally truncated with "..." to fit the table format.

Also applies to: 191-191

src/datamodel_code_generator/cli_options.py (1)

175-175: LGTM! CLI option metadata correctly defined.

The metadata entry is properly configured with the appropriate category and follows the established pattern.

src/datamodel_code_generator/__init__.py (1)

392-393: LGTM! New parameters follow existing patterns.

The new enable_command_header and command_line parameters are correctly typed and positioned alongside related header configuration options like enable_version_header.

src/datamodel_code_generator/arguments.py (1)

201-206: LGTM! CLI argument correctly defined.

The new argument follows the established pattern used by similar header-related options (--enable-version-header, --disable-timestamp) with appropriate action, default, and help text.

tests/main/openapi/test_main_openapi.py (2)

8-8: LGTM: Import added to support test normalization.

The re module import is correctly placed and necessary for the regex pattern matching in the new test_enable_command_header test function.

---

917-943: LGTM: Well-structured test with appropriate normalization.

The test properly validates the --enable-command-header feature:

• Follows the established testing pattern in this file
• Uses a normalize_command transform to mask the actual command line with a placeholder, ensuring stable test outputs despite dynamic file paths
• The regex substitution approach is cleaner than attempting to mock the command construction
• Includes proper @pytest.mark.cli_doc metadata for documentation generation

src/datamodel_code_generator/__main__.py (5)

7-7: LGTM: Appropriate import for command-line construction.

The shlex module import is correctly added to support shlex.join() on line 954, which properly quotes command-line arguments containing spaces or special characters.

---

389-389: LGTM: Config field properly added.

The new enable_command_header boolean field is appropriately positioned in the Config class and defaults to False, ensuring backward compatibility as an opt-in feature.

---

667-667: LGTM: Function signature appropriately extended.

The addition of the command_line: str | None parameter properly threads the command-line string through the call chain. The nullable type is appropriate for when the feature is disabled.

---

689-690: LGTM: Parameters correctly forwarded to generate().

The enable_command_header and command_line parameters are properly passed through to the generate() function call, completing the threading of this feature through the call chain.

---

954-954: LGTM: Command-line construction correctly implemented.

The conditional construction of command_line using shlex.join() is appropriate:

• Only builds the command string when enable_command_header is True
• Uses shlex.join() to properly quote arguments containing spaces or special characters
• Correctly reconstructs the full command by prefixing "datamodel-codegen"
• The args variable is guaranteed to be a sequence of strings at this point