feat(impact): scope homonym symbols with inPath

[SutuSebastian]

Summary

• Add inPath / --in / MCP in to disambiguate homonym symbols by defining file (same prefix/exact rules as codemap show --in).
• Unscoped homonym symbols union per-defining-file call graphs instead of merging by name only.
• Mismatched scope returns empty matches with skipped_scope.
• Plan retired; contracts lifted to docs/architecture.md and glossary.

Test plan

• bun test src/application/impact-engine.test.ts src/cli/cmd-impact.test.ts
• MCP impact homonym + skipped_scope tests
• bun run check

Summary by CodeRabbit

• New Features

  • Added --in <path> option to disambiguate homonym symbols by specifying a defining file in impact analysis
  • Updated homonym resolution to union call graphs across per-file results when unscoped

• Documentation

  • Updated impact analysis documentation with scoping examples, CLI/MCP parameter details, and result envelope changes including new skipped_scope field

[changeset-bot]

🦋 Changeset detected

Latest commit: ffdb650

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@stainless-code/codemap	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Warning

Review limit reached

@SutuSebastian, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 51 minutes and 2 seconds. Learn how PR review limits work.

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, 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 include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e36f60dc-9859-439a-b463-7637817c5e68

📥 Commits

Reviewing files that changed from the base of the PR and between cbcf1e8 and ffdb650.

📒 Files selected for processing (1)

• docs/glossary.md

📝 Walkthrough

Walkthrough

The PR extends codemap impact and MCP impact tool to disambiguate homonym symbols via an optional --in (CLI) or in (MCP) file-path argument. When provided, the engine filters a symbol's defining-file set and returns skipped_scope if no matches remain. Core engine, CLI, and MCP layers implement scope-aware call-walk and argument parsing; tests and documentation follow.

Changes

Core Engine and CLI/MCP Homonym Scoping

Layer / File(s)	Summary
Core Engine: Homonym Scoping and Scope-Based Result Filtering src/application/impact-engine.ts	Extended ImpactResult with optional skipped_scope field; added inPath?: string to FindImpactOpts; added scopeFiles?: string[] to WalkOpts. Reworked findImpact() to filter symbol defining files by inPath using prefix/exact matching rules and return empty result with skipped_scope on mismatch. Enhanced walkCalls() SQL to optionally restrict first-hop rows to selected scope files. Introduced filterMatchedInByInPath() and emptyImpactResult() helper functions.
Engine Tests: Homonym Scoping Behavior src/application/impact-engine.test.ts	Added test suite verifying unscoped homonym union across defining files; inPath scoping to single defining file; directory-prefix matching; and skipped_scope reporting on scope mismatch.
CLI: --in Argument Parsing and Wiring src/cli/cmd-impact.ts, src/cli/cmd-impact.test.ts	Extended ImpactOpts type with inPath field. Updated parseImpactRest() to parse --in <path> flag, validate presence of value, and include inPath in "run" result. Updated help text, usage line, and examples to document homonym disambiguation. Added test cases validating flag parsing and error handling.
CLI: Command Execution and Terminal Output src/cli/cmd-impact.ts	Updated runImpactCmd() to convert opts.inPath to project-relative path and forward to findImpact(). Extended renderTerminal() to emit skipped_scope message when present in result.
MCP/Tool Handler: Argument Schema and Converter src/application/tool-handlers.ts	Extended impactArgsSchema Zod schema with optional in: z.string().min(1).optional(); updated ImpactArgs interface with in?: string; implemented handleImpact() to compute project-relative inPath from args.in and pass to findImpact().
MCP Server: Tool Registration and Tests src/application/mcp-server.ts, src/application/mcp-server.test.ts	Updated impact MCP tool description to document in parameter, depth semantics, and skipped_scope response field. Added test cases verifying scope constraint matching and skipped_scope reporting for mismatched paths.
Integration: Command Wiring and Help Text src/cli/main.ts, src/cli/bootstrap.ts, src/cli/cmd-mcp.ts	Updated main.ts to wire inPath through impact command routing. Updated help text in bootstrap.ts and reworded cmd-mcp.ts tool description.
Documentation: API Contract and Behavior docs/architecture.md, docs/glossary.md, README.md	Updated documentation to describe --in argument, homonym union semantics for unscoped queries, inPath scope filtering, and skipped_scope response field.
Documentation: MCP/Tool Templates templates/agent-content/mcp-instructions.md, templates/agent-content/skill/10-recipes-context.md	Updated agent templates to document optional in? parameter and scope disambiguation behavior for homonym symbols.
Project Management: Lifecycle and Roadmap .agents/skills/harden-pr/LEDGER.md, docs/plans/security-hardening-orchestrator.md, docs/roadmap.md	Added LEDGER rejection notes documenting by-design scoping behavior. Updated PR schedule and session log in orchestrator plan with concrete PR 2 status. Updated roadmap to reference architecture docs instead of removed plan file.
Changeset .changeset/impact-inpath-homonyms.md	Added changeset documenting behavioral update to codemap impact homonym disambiguation, --in/in scope-based filtering, and skipped_scope reporting.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• stainless-code/codemap#50: Introduced initial findImpact and walkCalls implementation; this PR extends it with inPath scope filtering and skipped_scope reporting.
• stainless-code/codemap#114: Also modifies walkCalls() SQL logic in impact-engine.ts; this PR adds scope clause for inPath constraint; retrieved PR changed minimum-depth row selection determinism.

Suggested labels

enhancement

Poem

🐰 Two files, one name—oh what a sight!
Now --in picks the path so right.
Union graphs unscoped, yet focused when you say,
Homonyms disambiguate, blooming bright today! 🌸

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately summarizes the main change: adding inPath scoping for homonym symbols in the impact command, which is the core feature across all modified files.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/impact-inpath-homonyms

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/glossary.md`:
- Line 325: Update the documented result envelope in the "impact" glossary entry
to include the optional skipped_backends? field (an array indicating backends
ignored due to explicit --via mismatch), so the envelope section matches runtime
output from the findImpact engine (application/impact-engine.ts) and the
CLI/MCP/HTTP dispatchers; specifically add `skipped_backends?` alongside
`skipped_scope?` in the envelope description and briefly note that mismatched
explicit `--via` choices populate this field instead of failing.

🪄 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: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3151da89-4645-40be-8432-78d12032fb52

📥 Commits

Reviewing files that changed from the base of the PR and between a5caca8 and cbcf1e8.

📒 Files selected for processing (20)

• .agents/skills/harden-pr/LEDGER.md
• .changeset/impact-inpath-homonyms.md
• README.md
• docs/architecture.md
• docs/glossary.md
• docs/plans/impact-inpath-homonyms.md
• docs/plans/security-hardening-orchestrator.md
• docs/roadmap.md
• src/application/impact-engine.test.ts
• src/application/impact-engine.ts
• src/application/mcp-server.test.ts
• src/application/mcp-server.ts
• src/application/tool-handlers.ts
• src/cli/bootstrap.ts
• src/cli/cmd-impact.test.ts
• src/cli/cmd-impact.ts
• src/cli/cmd-mcp.ts
• src/cli/main.ts
• templates/agent-content/mcp-instructions.md
• templates/agent-content/skill/10-recipes-context.md

💤 Files with no reviewable changes (1)

• docs/plans/impact-inpath-homonyms.md