feat(cli): codemap rename alias for homonym-safe renames by SutuSebastian · Pull Request #166 · stainless-code/codemap

SutuSebastian · 2026-06-05T06:27:41Z

Summary

Adds codemap rename — thin CLI alias → apply rename-preview (Moat A: no new write semantics; same policy gates as apply).
Positional ergonomics: codemap rename <old> <new> [--define-in <file_path>] [--in-file <prefix>] [--kind <k>] [apply flags…]
Scoped-flag mapping: --define-in / --in-file / --kind (space or = form) → recipe params; apply flags pass through unchanged.
Changeset: .changeset/rename-alias-cli.md (patch).

Closes the roadmap gap left after homonym define_in shipped in #165.

Implementation

Layer	Files
Alias parser	`src/cli/rename-alias.ts` — `resolveRenameAlias`, `formatParamsCli`, `printRenameAliasHelp`
Dispatch	`src/cli/main.ts` — rewrite before `apply`; rename-local errors exit 1
Tests	`src/cli/rename-alias.test.ts` (29 unit), `src/cli/cmd-apply.test.ts` (homonym e2e + parse-error e2e)

Not in scope (by design): no MCP rename tool — agents use apply + define_in in params.

Review hardening (cycles 1–12)

Multi-agent review loop addressed parser edge cases:

Missing --params / scoped-flag operands → rename-local or apply-delegated errors
Apply flags before <old> <new>; equals-form scoped flags (--params=, --commit=)
Trailing bare --params (preserve state, strip when redundant, reject flag-as-operand)
Stray positionals; partial old/new; scoped flags followed by flags
Help guards: sole-arg only (rename --help); symbol names like --help stay positional
Apply-flag whitelist in passthrough so dash-prefixed symbol names rewrite correctly
--commit / --max-passes no longer pair with a following apply flag (rename + parseApplyRest)
CodeRabbit #discussion_r3360831534 resolved
Docs: README, roadmap, architecture, glossary, skill, rule, synthesis §7, testing-coverage; shipped plan deleted

Cycle 12 verdict: CLEAN (61 tests pass; docs/consumer + Moat A + cross-refs).

Usage

codemap rename helper worker --define-in src/lib/helper-module.ts --dry-run
codemap rename usePermissions useAccess --kind function --yes
codemap rename --params old=foo,new=bar,define_in=src/a.ts --dry-run

Test plan

bun test src/cli/rename-alias.test.ts (29 cases)
bun test src/cli/cmd-apply.test.ts — homonym scoped apply + codemap rename e2e + parse-error e2e
CI green on ce8ddd4
Changeset present for release

`define_in` on rename-preview shipped in #165; this adds the thin `codemap rename` → `apply rename-preview` alias with positional ergonomics and plan doc for the scoped-rename slice.

changeset-bot · 2026-06-05T06:27:45Z

🦋 Changeset detected

Latest commit: 7b0ce69

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 · 2026-06-05T06:27:53Z

📝 Walkthrough

Walkthrough

This PR implements codemap rename as a CLI alias that rewrites to codemap apply rename-preview. It includes the alias parsing logic, CLI dispatch integration, unit and integration tests, and comprehensive documentation of the feature status, acceptance criteria, and usage examples.

Changes

Codemap rename CLI alias

Layer / File(s)	Summary
CLI alias implementation logic `src/cli/rename-alias.ts`	Implements `formatParamsCli` for deterministic param serialization, `resolveRenameAlias` to parse rename command arguments and rewrite them into an `apply rename-preview` invocation with correct flag and param handling, and `printRenameAliasHelp` for usage text.
CLI dispatch and help integration `src/cli/main.ts`, `src/cli/bootstrap.ts`	Adds `rename` subcommand branch in `main.ts` that detects the command, prints help when requested, and rewrites argv. Updates `bootstrap.ts` help text to document the new alias syntax and flags.
Alias unit tests `src/cli/rename-alias.test.ts`	Comprehensive tests for `resolveRenameAlias` covering positional arguments, explicit `--params`, mixed positional+flag params, `--in-file`/`--kind` mapping, and edge cases. Also tests `formatParamsCli` deterministic serialization.
Integration test with homonym scope `src/cli/cmd-apply.test.ts`	Verifies `rename` command with `--define-in` correctly rewrites only the anchored homonym definition and its consumer, leaving other homonyms unaffected.
Documentation, plan, and roadmap updates `docs/plans/scoped-rename-define-in.md`, `docs/roadmap.md`, `docs/testing-coverage.md`, `README.md`, `docs/architecture.md`	Adds feature plan documenting status, shipped items, remaining work, and acceptance criteria. Updates roadmap and architecture docs. Adds testing-coverage entry and README example.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

enhancement

Poem

A rabbit's rewrite, swift and neat,
Commands renamed, semantic and sweet,
The old becomes new with a flag's gentle hand,
Aliases woven through code's well-planned land. 🐰

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the primary change: implementing a CLI alias for codemap rename that enables homonym-safe renames. It is specific and directly relates to the main objective of the PR.
Docstring Coverage	✅ Passed	Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%.
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

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

✨ 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 feat/scoped-rename-alias

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

_{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 `@src/cli/rename-alias.ts`:
- Around line 32-36: When handling the case where a === "--params" inside the
loop over tail (using variables tail and i and constant RENAME_RECIPE_ID), do
not inject an empty string as a fabricated operand; instead preserve the flag as
missing so the downstream apply parsing hits the real missing-argument error
path. Concretely, change the branch that currently returns ["apply",
RENAME_RECIPE_ID, "--params", ""] to return the flag without a value (e.g.
["apply", RENAME_RECIPE_ID, "--params"]) so the parser sees a true missing
operand for "--params".

🪄 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: 39d6a414-2e23-44a4-b6d3-b08bd89fc60d

📥 Commits

Reviewing files that changed from the base of the PR and between 2e1e5e0 and 7416338.

📒 Files selected for processing (10)

README.md
docs/architecture.md
docs/plans/scoped-rename-define-in.md
docs/roadmap.md
docs/testing-coverage.md
src/cli/bootstrap.ts
src/cli/cmd-apply.test.ts
src/cli/main.ts
src/cli/rename-alias.test.ts
src/cli/rename-alias.ts

Align with --define-in/--in-file/--kind: pass bare --params through so apply reports the real missing-argument error instead of accepting {}.

Return rename-local errors for missing scoped-flag operands, extract old/new regardless of apply-flag order, reject stray positionals, and align README/roadmap/architecture/skill with the shipped alias.

Support equals-form scoped flags, reject partial old/new at the alias layer, add changeset and glossary/rule coverage, delete shipped plan.

Report unexpected positionals when old/new are already bound via --params; align glossary shorthand with full rename flag surface.

Only early-return bare --params when it is the sole rename arg; otherwise keep merged params, positionals, and apply flags. Delegate incomplete old/new to apply when applyTail still carries --params.

Mirror query/apply parser guard: when --params is not followed by a value token, treat it as bare trailing --params instead of parsing the next flag as k=v input.

When old/new are already serialized, drop no-op trailing --params tokens so apply argv stays parseable (e.g. before --dry-run).

Align --define-in, --in-file, and --kind with --params: a following flag is not a valid operand value.

Treat --params followed by apply flags as bare passthrough, whitelist apply flags in splitPassthrough so symbol names like --help stay positional, and only show rename help when it is the sole argument.

Rename alias and apply parser no longer pair value-taking apply flags with a following flag, so `rename a b --commit --dry-run` preserves dry-run semantics end-to-end.

Replace dogfood bench fixture paths in README and rename --help with consumer-facing placeholder paths.

feat(cli): add codemap rename alias for homonym-safe renames

7416338

`define_in` on rename-preview shipped in #165; this adds the thin `codemap rename` → `apply rename-preview` alias with positional ergonomics and plan doc for the scoped-rename slice.

coderabbitai Bot reviewed Jun 5, 2026

View reviewed changes

Comment thread src/cli/rename-alias.ts

SutuSebastian added 12 commits June 5, 2026 09:44

fix(cli): preserve missing --params operand in rename alias

609b140

Align with --define-in/--in-file/--kind: pass bare --params through so apply reports the real missing-argument error instead of accepting {}.

fix(cli): harden rename alias parsing and docs

172278a

Return rename-local errors for missing scoped-flag operands, extract old/new regardless of apply-flag order, reject stray positionals, and align README/roadmap/architecture/skill with the shipped alias.

fix(cli): polish rename alias edge cases and docs

ffc6568

Support equals-form scoped flags, reject partial old/new at the alias layer, add changeset and glossary/rule coverage, delete shipped plan.

fix(cli): improve stray-arg error after complete rename params

36718fb

Report unexpected positionals when old/new are already bound via --params; align glossary shorthand with full rename flag surface.

test(cli): cover stray positional after rename --params

bba068b

fix(cli): preserve state on trailing bare --params in rename

97ade6b

Only early-return bare --params when it is the sole rename arg; otherwise keep merged params, positionals, and apply flags. Delegate incomplete old/new to apply when applyTail still carries --params.

fix(cli): reject flag tokens as --params operands in rename

7ff7d8f

Mirror query/apply parser guard: when --params is not followed by a value token, treat it as bare trailing --params instead of parsing the next flag as k=v input.

fix(cli): strip redundant bare --params from rename rewrite

a0ef0de

When old/new are already serialized, drop no-op trailing --params tokens so apply argv stays parseable (e.g. before --dry-run).

fix(cli): reject flag tokens as scoped-flag operands in rename

6f70740

Align --define-in, --in-file, and --kind with --params: a following flag is not a valid operand value.

fix(cli): harden rename alias flag parsing and help guards

d427c3a

Treat --params followed by apply flags as bare passthrough, whitelist apply flags in splitPassthrough so symbol names like --help stay positional, and only show rename help when it is the sole argument.

fix(cli): reject flag tokens as --commit/--max-passes operands

ce8ddd4

Rename alias and apply parser no longer pair value-taking apply flags with a following flag, so `rename a b --commit --dry-run` preserves dry-run semantics end-to-end.

docs(cli): use generic paths in rename alias examples

7b0ce69

Replace dogfood bench fixture paths in README and rename --help with consumer-facing placeholder paths.

SutuSebastian merged commit 4bfb067 into main Jun 5, 2026
11 checks passed

SutuSebastian deleted the feat/scoped-rename-alias branch June 5, 2026 07:45

github-actions Bot mentioned this pull request Jun 5, 2026

chore: version packages #168

Merged

SutuSebastian added a commit that referenced this pull request Jun 5, 2026

merge: sync feat/transport-parity-mcp with main after #166

fb0ea34

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat(cli): codemap rename alias for homonym-safe renames#166

feat(cli): codemap rename alias for homonym-safe renames#166
SutuSebastian merged 13 commits into
mainfrom
feat/scoped-rename-alias

SutuSebastian commented Jun 5, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Jun 5, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jun 5, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Suggested labels

Poem

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Uh oh!

Conversation

SutuSebastian commented Jun 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Implementation

Review hardening (cycles 1–12)

Usage

Test plan

Uh oh!

changeset-bot Bot commented Jun 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

coderabbitai Bot commented Jun 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Suggested labels

Poem

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

SutuSebastian commented Jun 5, 2026 •

edited

Loading

changeset-bot Bot commented Jun 5, 2026 •

edited

Loading

coderabbitai Bot commented Jun 5, 2026 •

edited

Loading