Add generation dependency index

[koxudaxi]

Summary by CodeRabbit

Release Notes

• New Features

  • Added automated validation via pre-commit hook to ensure consistent parser state management during development.

• Documentation

  • Added development guidelines for parser generation state constraints and required mutation patterns.

• Tests

  • Added comprehensive test coverage validating state management operations and usage patterns across parser implementations.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d117e785-7403-4007-8cc5-66cb9182d724

📥 Commits

Reviewing files that changed from the base of the PR and between 5b66f67 and 09f3e41.

📒 Files selected for processing (13)

• .pre-commit-config.yaml
• docs/development-contributing.md
• scripts/check_generation_store_usage.py
• src/datamodel_code_generator/parser/base.py
• src/datamodel_code_generator/parser/generation.py
• src/datamodel_code_generator/parser/graphql.py
• src/datamodel_code_generator/parser/jsonschema.py
• src/datamodel_code_generator/parser/openapi.py
• tests/model/test_base.py
• tests/parser/test_base.py
• tests/parser/test_generation.py
• tests/parser/test_generation_store_usage.py
• tests/test_types.py

---

📝 Walkthrough

Walkthrough

This PR introduces a controlled mutation system for the parser's model-graph construction via a new GenerationStore that tracks stable model/datatype facts, provides index queries, and replaces direct object mutations with centralized APIs across all parsers, accompanied by AST-based linting, documentation, pre-commit enforcement, and comprehensive tests.

Changes

Generation Store Model Graph State Management

Layer / File(s)	Summary
Generation Store core infrastructure src/datamodel_code_generator/parser/generation.py	New module implementing immutable ModelFact/DataTypeFact/GenerationFacts containers, a _GenerationModelList that invalidates caches on mutations, GenerationIndexBuilder for rebuilding stable-ID facts snapshots, and GenerationIndex query layer plus GenerationStore with controlled mutation methods and lazy fact refresh.
Generation Store usage checker scripts/check_generation_store_usage.py	AST-based linter that loads GENERATION_STORE_MUTATION_METHODS and validates parser code does not bypass store mutations; detects forbidden patterns (direct sequence mutators, reference assignments, Reference.children reads) and reports violations with line/column information.
Parser initialization and sort_data_models refactoring src/datamodel_code_generator/parser/base.py	Parser.__init__ now initializes self.generation_store via GenerationStore.create_with_results(). sort_data_models accepts optional generation_index parameter for generation-aware reference-class computation. sort_base_classes_for_mro uses set_model_base_classes helper to route mutations through store when available.
Root model collapse refactoring src/datamodel_code_generator/parser/base.py	Refactors __collapse_root_models to use generation_index.root_collapse_reference_usage() for reference decisions and generation_store operations (update_model_reference, collapse_root_data_type, replace_field_type, detach_data_type_ref) instead of direct mutations; uses index queries for follow-up checks.
Reference redirect, field mutations, and discriminator handling src/datamodel_code_generator/parser/base.py	Routes duplicate root-model removal, base-class deduplication, model reuse/collapse, and discriminator handling through generation_store APIs: replaces direct reference mutations with redirect_reference_users, field appends with append_field, and field-data-type updates with replace_field_type/detach_data_type_ref.
Type override and imported-name renaming src/datamodel_code_generator/parser/base.py	Type override logic uses detach_data_type_ref instead of direct reference nulling. Imported-name renaming uses generation_store.update_model_reference(). Dataclass field ordering uses generation_store.set_fields(). Generic base-class injection uses generation_store.set_base_classes().
Circular import handling and module dependency graph src/datamodel_code_generator/parser/base.py	SCC relocation wraps updates in generation_store.defer_refresh() and uses generation_store.update_model_reference() instead of direct mutation. Module dependency graph construction uses generation_store.index.reference_classes_for_model() instead of walking object relationships.
Schema parser model registration updates src/datamodel_code_generator/parser/graphql.py, src/datamodel_code_generator/parser/jsonschema.py, src/datamodel_code_generator/parser/openapi.py	GraphQL, JSON Schema, and OpenAPI parsers now register models via generation_store.register_model() instead of appending to self.results. JSON Schema parser also routes variant/field reference updates through generation_store.replace_data_type_ref() and generation_store.replace_field_type().
Documentation and pre-commit enforcement docs/development-contributing.md, .pre-commit-config.yaml	New "Parser generation state" contributing guideline section documents naming authority, required GenerationStore mutation helper usage, and prohibited direct mutations. Pre-commit hook generation-store-usage runs checker on parser Python files to enforce constraints.
Comprehensive test coverage tests/parser/test_generation.py, tests/parser/test_generation_store_usage.py, tests/parser/test_base.py, tests/model/test_base.py, tests/test_types.py	Extensive test suites validate GenerationStore registration/refresh/facts/index behavior, reference operations, defer_refresh batching, model/field mutations and invalidation, root-collapse queries, AST checker correctness, and reference-children compatibility across models and removal scenarios.

Sequence Diagrams

sequenceDiagram
  participant Parser
  participant Store as GenerationStore
  participant Index as GenerationIndex
  participant Model
  Parser->>Store: create_with_results()
  Parser->>Store: register_model(model)
  Parser->>Store: replace_field_type(field, new_type)
  Store->>Store: defer_refresh()
  Store->>Index: rebuild facts snapshot
  Index-->>Store: provide reference classes
  Store-->>Parser: return query results

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Possibly related PRs

• koxudaxi/datamodel-code-generator#3089: Targets Parser.__reuse_model skip logic for root models during collapse, overlapping with this PR's refactor of reuse/collapse paths.
• koxudaxi/datamodel-code-generator#2726: Modifies Parser.__init__ and model-processing flow; this PR's GenerationStore initialization overlaps at parser-construction level.
• koxudaxi/datamodel-code-generator#2676: Modifies JsonSchemaParser.parse_all_of root-model and allOf logic; this PR routes those mutations through generation_store.

Suggested labels

breaking-change-analyzed, breaking-change

Poem

🐰 The stores are built, the facts now tracked,
No mutations slip through cracks unzapped,
With indices and hooks on guard,
The parser's graphs stay fresh and hard—
Through generation's controlled art! 🐇

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/generation-store-index

---

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.}

[github-actions]

📚 Docs Preview: https://pr-3154.datamodel-code-generator.pages.dev

[codspeed-hq]

Merging this PR will improve performance by 16.55%

⚠️ Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 11 improved benchmarks
⏩ 98 skipped benchmarks¹

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
⚡	WallTime	test_perf_large_models_pydantic_v2	3.9 s	3.3 s	+20%
⚡	WallTime	test_perf_duplicate_names	1,064.8 ms	934.4 ms	+13.96%
⚡	WallTime	test_perf_aws_style_openapi_pydantic_v2	1.9 s	1.7 s	+13.31%
⚡	WallTime	test_perf_graphql_style_pydantic_v2	835 ms	744.3 ms	+12.19%
⚡	WallTime	test_perf_kubernetes_style_pydantic_v2	2.7 s	2.4 s	+11.8%
⚡	WallTime	test_perf_complex_refs	2.2 s	1.9 s	+15.2%
⚡	WallTime	test_perf_stripe_style_pydantic_v2	2 s	1.8 s	+10.8%
⚡	WallTime	test_perf_deep_nested	6.2 s	4.8 s	+30.69%
⚡	WallTime	test_perf_multiple_files_input	3.8 s	3.3 s	+13.49%
⚡	WallTime	test_perf_openapi_large	3 s	2.6 s	+14.1%
⚡	WallTime	test_perf_all_options_enabled	6.6 s	5.1 s	+28.4%

Tip

Curious why this is faster? Comment @codspeedbot explain why this is faster on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing feature/generation-store-index (09f3e41) with main (5b66f67)}

Footnotes

1. 98 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 100.00%. Comparing base (5b66f67) to head (09f3e41).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##              main     #3154    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files           89        92     +3     
  Lines        18650     19346   +696     
  Branches      2156      2203    +47     
==========================================
+ Hits         18650     19346   +696     

Flag	Coverage Δ
unittests	100.00% <100.00%> (ø)

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.

[github-actions]

Breaking Change Analysis

Result: No breaking changes detected

Reasoning: PR #3154 is an internal refactoring that introduces a GenerationStore/GenerationIndex abstraction layer for centralizing parser mutations. All changes are additive and backward compatible: new function parameters default to None, Parser.results remains list-compatible (using a list subclass), no CLI arguments or generated output formats changed, no public API was removed or renamed. The module docstring explicitly states "preserve output compatibility first." The only enforcement mechanism (a pre-commit hook for store usage) applies only to parser contributors, not end users.

---

This analysis was performed by Claude Code Action

[github-actions]

🎉 Released in 0.58.0

This PR is now available in the latest release. See the release notes for details.