[vitali87]

Summary

• Adds codebase_rag/editing/signature_spec.py: parameter specs, the --map parser, literal type checks, and the report and site types.
• Adds codebase_rag/editing/signature_contract.py: measures an applied change through the structural delta and undoes it when its postcondition fails.
• Nothing calls these yet. feat(signature): the change_signature operation (#1533, 4/9) #2166 builds SignatureChanger on them and feat(signature): expose change_signature through the CLI and MCP, with docs (#1533, 5/9) #2164 exposes it as cgr change-signature.

Demo

No user-visible change: this layer adds internal building blocks only. The command they feed is shown in #2164's Demo. Below are this layer's new tests run on this branch.

Animated run

• Before (e43a3e5c7, feat(signature): contract expectation, shared call-site helpers and constants for change_signature (#1533, 1/9) #2163): neither module nor its tests exist.
• After (34d367d4f, this branch): 59 tests pass across the mapping parser, parameter parsing, literal checks and the contract check.

Type of Change

• Bug fix
• New feature
• Performance improvement
• Refactoring (no functional changes)
• Documentation
• CI/CD or tooling
• Dependencies

Related Issues

Part of #1533 (split from #1912; stack: #2163 → #2161 → #2162 → #2166 → #2164 → #2169 → #2168 → #2165 → #2167).

Test Plan

• Unit tests pass (make test-parallel or uv run pytest -n auto -m "not integration")

• New tests added

• Integration tests pass (make test-integration, requires Docker)

• Manual testing (describe below)

• uv run python -m pytest codebase_rag/tests/test_signature_spec.py codebase_rag/tests/test_signature_contract.py -p no:randomly -q at 34d367d4f: 59 passed.

• The full suite was not run locally. The CI Unit Tests run at 34d367d4f was cancelled before it finished.

Checklist

• PR title follows Conventional Commits format
• All pre-commit checks pass (make pre-commit)
• No hardcoded strings in non-config/non-constants files
• No # type: ignore, cast(), Any, or object type hints
• New comments and docstrings explain why, not what (see Comment Policy)

SKIP=no-commit-to-branch pre-commit run --from-ref e43a3e5c7 --to-ref 34d367d4f (ruff, ruff-format, ty, bandit, generate-readme and the file hygiene hooks): passed. The unit-suite step of make pre-commit was not run locally.

Unchecked items:

• signature_spec.py declares _LITERAL_PREFIX = "=", _DEFINITION = "definition", _CALL = "call" and _IDENTIFIER_RE as module constants rather than in codebase_rag/constants.
• test_signature_contract.py uses cast(StructuralDelta, delta) in a test helper. The non-test modules have none of these.
• Comments were not re-audited against the policy in this pass.

---

Files changed

• codebase_rag/editing/signature_contract.py
• codebase_rag/editing/signature_spec.py
• codebase_rag/tests/test_signature_contract.py
• codebase_rag/tests/test_signature_spec.py

Diff stats

+873 additions, -0 deletions (873 LOC)

Dependencies

This PR depends on: pr-1

Dependency graph

Merge in this order:

pr-1: feat(signature): contract expectation, shared call-site helpers and constants for change_signature (#1533, 1/9)
└── pr-2: feat(signature): parameter specs, mapping sources and the change_signature contract check (#1533, 2/9)  <-- this PR
    └── pr-3: feat(signature): read the header, bind call arguments, render the rewrite (#1533, 3/9)
        └── pr-4: feat(signature): the change_signature operation (#1533, 4/9)
            └── pr-5: feat(signature): expose change_signature through the CLI and MCP, with docs (#1533, 5/9)
                └── pr-6: test(signature): acceptance, transaction and MCP tests for change_signature (#1533, 6/9)
                    └── pr-7: test(signature): mapping tests for change_signature (#1533, 7/9)
                        └── pr-8: test(signature): definition and renamed-parameter tests for change_signature (#1533, 8/9)
                            └── pr-9: test(signature): hierarchy, receiver and default guards for change_signature (#1533, 9/9)

Summary by CodeRabbit

• New Features
  • Added signature editing with validation for parameter mappings and declarations, including parameter names, ordering, and supported literal-to-annotation compatibility.
  • Signature change reports show mapped and unmapped call sites, verification results, and graph completeness. When verification fails, changes are rolled back where possible, with reports noting when rollback is refused or re-ingestion is incomplete.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: vitali87/code-graph-rag/.coderabbit.yaml
• Review profile: QUIET
• Plan: Advanced
• Run ID: 83002693-f54d-4fcc-a9d5-94daeec2f78d

---

📥 Commits

Reviewing files that changed from the base of the PR and between ea91e59 and 4834cf4.

---

📒 Files selected for processing (2)

• codebase_rag/tests/test_signature_contract.py
• codebase_rag/tests/test_signature_spec.py

---

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 2 remain after this review.

---

---

📝 Walkthrough

Walkthrough

The change adds parameter and site records, mapping and parameter validation helpers, and enforce_contract to measure and verify signature changes. Failed verification triggers an attempted rollback, with rollback and re-ingestion outcomes recorded in the report.

Changes

Signature Change Contracts

Layer / File(s)	Summary
Define and validate signature specifications codebase_rag/editing/signature_spec.py, codebase_rag/tests/test_signature_spec.py	Adds parameter, site, and report records. Parses mappings and parameter declarations, validates sources, literals, and parameter ordering, and serializes site records. Tests cover parsing, validation, and serialization.
Measure, verify, and handle signature changes codebase_rag/editing/signature_contract.py, codebase_rag/tests/test_signature_contract.py	Adds enforce_contract to measure and verify an applied change. On verification failure, it attempts rollback and records rollback conflicts or re-ingestion failures in the report. Tests cover verification, rollback, and measurement-error outcomes.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Other

Sequence Diagram(s)

sequenceDiagram
  participant enforce_contract
  participant measurement
  participant transaction_undo
  participant reingest
  enforce_contract->>measurement: measure structural delta
  measurement-->>enforce_contract: verification findings
  enforce_contract->>transaction_undo: undo transaction after failed verification
  transaction_undo-->>enforce_contract: rollback result
  enforce_contract->>reingest: re-ingest files after successful rollback
  reingest-->>enforce_contract: re-ingestion result

Loading

---

Merge Risk | ⚪ Minimal · up to 4834c

Merge Risk: ⚪ Minimal · up to 4834c

This change adds internal building blocks for signature changes that nothing calls yet, so it has no user-visible effect. No merge-blocking risk was found.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 4834c

The change adds internal building blocks rather than a new user-facing command. Recovery targets the original transaction, protects later edits, and reports graph-refresh failures. No introduced security issue was established, but concurrent, interrupted, and repeated recovery behavior remains unproven.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The evidenced mutation scope is the supplied repository transaction and graph-refresh callback. The inspected caller does not establish remote, cross-tenant, or elevated-privilege reachability; production integration and its authority are outside this PR's demonstrated execution path.

Trust Boundaries and Controls

• observed — The helper consumes caller-provided reports and callbacks rather than authenticating an external request. Its demonstrated controls address structural correctness and rollback ownership; literal type checking is not a general validation or sandbox boundary.

Resilience and Maintainability Implications

• observed — Recovery outcomes expose failed verification, refused rollback, and incomplete graph refresh separately. Measurement errors leave the committed edit in place without a verdict; whether ValueError and ReingestAborted always imply no graph mutation depends on callback behavior not established by the inspected harness.

Hardening Proposals

• proposed — Before production integration, establish single-operation ownership and repeat-safe recovery across undo and graph refresh, including interruption handling. Validate the callback's no-write error guarantees and require callers to distinguish applied edits from verified edits.

---

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly names the parameter specifications, mapping sources, and contract check added by this change.
Description check	✅ Passed	The description covers the change, demo, feature type, related work, and test plan. It also states which checks were not run.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

---

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

---

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

[github-actions]

pr-split analysis

Metric	Value
Total LOC	448
Files changed	2
Suggested groups	2
Largest group	343 LOC
LOC overflow	0
File scatter	0

This PR has 448 LOC and could be split into 2 smaller PRs:

Group	Title	Diff	Depends On	Files
pr-1	chore(split): review signature-spec-1	+343/-0	—	codebase_rag/editing/signature_spec.py
pr-2	chore(split): review signature-contract-2	+105/-0	—	codebase_rag/editing/signature_contract.py

Run pr-split split locally to create these sub-PRs, or adjust --max-loc to change the target size.

[vitali87]

@greptile full review

[greptile-apps]

Confidence Score: 5/5

[Medium impact] Safe to merge.

Summary

This update completes the signature-change contract flow by validating declared parameters and mappings, checking literal compatibility, measuring the applied structural change, and safely reporting rollback and graph-recovery outcomes. The rollback-error handling previously raised in review is now addressed: unexpected rollback failures are converted into an incomplete-state report so callers can invalidate and rebuild the graph.

_{Reviews (2) · Last reviewed commit: "fix(signature): report a rollback that r..." · Reviewed by Greptile}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[vitali87]

@greptile review