chore: enforce Rust production file size limits

.github/workflows/pre-commit.yml

@@ -19,6 +19,8 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
 
       - name: Set up Python
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
@@ -52,6 +54,7 @@ jobs:
           exit 0
         env:
           SKIP: no-commit-to-branch
+          RUST_FILE_SIZE_BASE: ${{ github.event.pull_request.base.sha || github.event.merge_group.base_sha || github.event.before }}
 
       - name: Check pre-commit results
         if: steps.precommit.outputs.status != '0'

.pre-commit-config.yaml

@@ -28,6 +28,22 @@ repos:
 
 -   repo: local
     hooks:
+    -   id: rust-file-sizes
+        name: Rust production file sizes
+        language: python
+        entry: python scripts/check_rust_file_sizes.py
+        additional_dependencies: &rust_size_dependencies
+        - tree-sitter==0.25.2
+        - tree-sitter-rust==0.24.2
+        pass_filenames: false
+        always_run: true
+    -   id: rust-file-size-tests
+        name: Rust file-size checker tests
+        language: python
+        entry: python -m unittest discover -s scripts/tests -p test_rust_file_sizes.py
+        additional_dependencies: *rust_size_dependencies
+        files: '^(scripts/(check_rust_file_sizes.py|tests/test_rust_file_sizes.py)|\.rust-file-sizes.json|\.pre-commit-config.yaml)$'
+        pass_filenames: false
     -   id: rustfmt
         name: rustfmt
         language: system

.rust-file-sizes.json

@@ -0,0 +1,25 @@
+{
+  "version": 1,
+  "baseline": {
+    "crates/agentic-server-core/src/executor/accumulator/mod.rs": 706,
+    "crates/agentic-server-core/src/executor/accumulator/slot.rs": 679,
+    "crates/agentic-server-core/src/executor/compaction.rs": 530,
+    "crates/agentic-server-core/src/executor/engine.rs": 823,
+    "crates/agentic-server-core/src/executor/gateway.rs": 653,
+    "crates/agentic-server-core/src/executor/messages_stream.rs": 520,
+    "crates/agentic-server-core/src/executor/session.rs": 508,
+    "crates/agentic-server-core/src/storage/schema.rs": 552,
+    "crates/agentic-server-core/src/tool/registry.rs": 515,
+    "crates/agentic-server-core/src/tool/tool_search.rs": 1764,
+    "crates/agentic-server-core/src/tool/web_search/mod.rs": 535,
+    "crates/agentic-server-core/src/types/io/input.rs": 678,
+    "crates/agentic-server-core/src/types/io/output.rs": 1110,
+    "crates/agentic-server-core/src/types/request_response.rs": 582,
+    "crates/agentic-server-core/src/types/tools/params.rs": 537,
+    "crates/agentic-server/src/agentic_process.rs": 558,
+    "crates/agentic-server/src/auth.rs": 799,
+    "crates/agentic-server/src/handler/websocket/responses.rs": 864
+  },
+  "exceptions": {},
+  "generated": {}
+}

CONTRIBUTING.md

@@ -79,6 +79,85 @@ Code style is enforced by `rustfmt` and `clippy` via pre-commit. Key settings:
 
 Do not worry about manually formatting code -- the pre-commit hooks will handle it.
 
+### Rust production file sizes
+
+Prefer production modules below 300 lines; 300–500 lines is reasonable for one
+clear responsibility. The `rust-file-sizes` pre-commit hook enforces a maximum of
+500 physical production lines for new files. Existing oversized files have
+explicit caps in `.rust-file-sizes.json`, tracked for cleanup in
+[#312](https://github.com/vllm-project/agentic-api/issues/312). Split files by
+responsibility while preserving architecture boundaries, rather than moving
+arbitrary lines to satisfy the check.
+
+Run the same check used by CI:
+
+```bash
+pre-commit run rust-file-sizes --all-files
+pre-commit run rust-file-size-tests --all-files
+# Show the hook's success summary:
+pre-commit run rust-file-sizes --all-files --verbose
+```
+
+The checker scans all Git-tracked `.rs` files on every invocation, including
+staged additions. Stage new files before checking them. Full scans also catch
+deleted/renamed files and policy changes. The hook's pinned Python/Rust-parser
+dependencies are installed once by pre-commit and reused; a check neither builds
+the Rust workspace nor accesses the network. The existing Pre-commit workflow
+runs these hooks with `--all-files`.
+
+The local hook compares baseline entries with the committed policy at `HEAD`.
+CI compares against the PR base, merge-queue base, or the previous main commit,
+using `RUST_FILE_SIZE_BASE`; CI fetches full history for that comparison.
+This prevents an earlier commit in a PR from hiding a baseline addition or increase.
+To check a whole branch locally, select an already-fetched base:
+
+```bash
+RUST_FILE_SIZE_BASE=upstream/main pre-commit run rust-file-sizes --all-files
+```
+
+The script also accepts `--base-ref`, which overrides the environment variable.
+An unavailable base fails the check; fetch that revision before retrying. When
+introducing the policy, initial caps may only come from production counts in
+regular Rust files that already existed at the base revision. A repository's
+first commit or first push has no prior allowances.
+
+Counting rules:
+
+- Count physical lines, including comments and blanks, with or without a final
+  newline. CRLF and LF have the same count.
+- Parse Rust syntax with Tree-sitter; exclude `#[cfg(test)]` items and their
+  attributes, nested test modules/items/statements, fields, initializers, match
+  arms, inner `#![cfg(test)]`, and built-in `#[test]`/`#[bench]` functions.
+  A test-only item can appear anywhere in a file.
+  `all`/`any`/`not` predicates are excluded only when they require `test`; unknown
+  feature/platform configurations remain production code.
+- Only remove an entire physical line from the production count when no
+  non-whitespace source remains outside test-only ranges. A mixed line counts as
+  both production and test. Comments/blanks outside those ranges count as
+  production. Test lines have no size limit.
+- Exclude files named `tests.rs` and files under a `tests`, `benches`, or `examples`
+  directory. These names are reserved for dedicated non-production source.
+- Macros, including `cfg_attr` and attribute macros, are not expanded. Their
+  source is conservatively counted unless enclosed in a recognized test-only item.
+  Rust parser errors fail the check instead of undercounting.
+- Generated Rust requires an exact path in `generated`, with a nonempty string
+  identifying its generator and why it is excluded. Directory globs and generated
+  markers in source do not grant exclusions. Stale or conflicting entries fail.
+
+When a baselined file shrinks, lower its cap to the reported production count in
+the same commit; remove the entry at 500 lines or fewer. Delete or rename its
+policy entry when deleting or renaming the file. A rename detected by Git may
+retain or lower the original file's cap; copies and other new paths cannot inherit
+a baseline. The checker reports the required update and never rewrites the baseline.
+Outside initial setup and detected renames, new baseline entries are rejected.
+Caps cannot increase relative to the selected prior revision.
+A justified cohesion-based exception belongs in `exceptions`
+as an exact path mapped to `{"limit": 550, "reason": "Specific rationale and review/issue reference"}`.
+Keep any existing baseline cap so the exception remains explicit. Exceptions
+must exceed the normal allowance and be removed when no longer needed.
+Policy changes, including the initial baseline and every exception, require code
+review; the checker validates policy contents, not GitHub approval state.
+
 ## Reporting Issues
 
 Use the issue templates provided on the