111 lines
4.5 KiB
Markdown
111 lines
4.5 KiB
Markdown
# jmove skill (for AI agents)
|
||
|
||
## What this tool does
|
||
|
||
Moves or renames source files inside a project and updates every import
|
||
statement referencing them. Never breaks imports. Supported: TypeScript,
|
||
JavaScript, Java (package declaration + all importers + the file move are
|
||
kept in sync); Python/Go on the roadmap. Single binary, no LSP needed.
|
||
|
||
## When to use
|
||
|
||
- The user asks to move/rename/reorganize source files or packages.
|
||
- You refactored a directory layout and imports now point at nothing.
|
||
- You need to verify the project has no broken imports (`check`).
|
||
|
||
## Commands
|
||
|
||
### mv — move a file and rewrite its importers
|
||
|
||
```
|
||
jmove mv <source> <target> [--root DIR] [--dry-run] [--json] [--no-git]
|
||
```
|
||
|
||
Always run `--dry-run` first and confirm the change set looks right.
|
||
Moving onto an existing path fails with `TARGET_EXISTS` — choose another
|
||
target (Phase 1 has no overwrite mode).
|
||
|
||
Git integration: inside a git repository, a tracked file is renamed with
|
||
`git mv` so the rename is staged (history-preserving `git log --follow` /
|
||
`git diff -M` work). Untracked files, non-repositories and `--no-git`
|
||
fall back to a plain filesystem rename. The import rewrites land in the
|
||
working tree unstaged either way — stage or commit them yourself.
|
||
`--json` reports the choice as `moved_via` (`"git"`/`"fs"`) and, on a
|
||
dry-run, `would_move_via`.
|
||
|
||
### check — find broken imports
|
||
|
||
```
|
||
jmove check [--root DIR] [--json]
|
||
```
|
||
|
||
Run after any move (or any edit) to validate project consistency.
|
||
|
||
### fix — auto-repair import problems
|
||
|
||
```
|
||
jmove fix [--root DIR] [--rule ID] [--dry-run] [--json]
|
||
```
|
||
|
||
Runs the deterministic rules over the whole project and applies the
|
||
repairs through the same atomic engine as `mv` (dry-run diff, rollback,
|
||
exit codes). Current Java rules: `java/unused-import` (deletes single-type
|
||
imports whose name is provably unreferenced), `java/missing-import`
|
||
(inserts the import of a project class used by simple name — unique FQN
|
||
candidate required) and `java/import-order` (Google style: statics first,
|
||
then single-type, ASCII-sorted, duplicates dropped). Unknown `--rule`
|
||
fails with `INVALID_ARGUMENT` and lists the known ids. A candidate the
|
||
engine cannot prove safe is reported with `"applied": false` and a
|
||
`candidates` array of FQN options — resolve it yourself (pick one, add
|
||
the import) and re-run; `fix` never guesses. When two rules want the same
|
||
bytes (order rewrite vs an unused deletion), the urgent rule applies and
|
||
the other is deferred (`"applied": false`, "skipped") — re-run `fix`
|
||
until it reports "nothing to change" (converges in 2–3 runs).
|
||
|
||
Recommended: `fix --dry-run --json`, inspect `files[].fixes[]`
|
||
(`rule`, `line`, `message`, `applied`, optional `candidates`), then apply
|
||
without `--dry-run`. For Java projects the practical loop is: `mv` →
|
||
`fix` → `fix` again if anything was "skipped" → `check`.
|
||
|
||
## Java specifics
|
||
|
||
- Moving a `.java` file rewrites three coordinated edits: its own
|
||
`package` declaration, every `import <fqn>` naming the class (static
|
||
member imports keep their member suffix) and the physical move.
|
||
- The target must be a `.java` path under the same source root
|
||
(`src/main/java`, `src`, …) and its directory maps to the new package.
|
||
Anything else exits `1` with code `PLAN_REJECTED`.
|
||
- A class in the default package (no `package` declaration) can only be
|
||
renamed inside its directory.
|
||
- `check` never reports unresolved Java imports (jdk, third-party,
|
||
`pkg.*`) as broken — they are external by design, like TS bare
|
||
specifiers.
|
||
|
||
## Recommended agent workflow
|
||
|
||
1. `jmove mv <src> <target> --dry-run --json` — preview.
|
||
2. Inspect `affected_files`; if unexpected, abort and ask the user.
|
||
3. `jmove mv <src> <target> --json` — apply (atomic, rolls back on error).
|
||
4. Java moves: `jmove fix --json` — heal bare same-package references
|
||
left behind by the move (they break `javac` otherwise).
|
||
5. `jmove check --json` — verify nothing is broken.
|
||
|
||
## Output format (--json)
|
||
|
||
Every response: `{ "status": "ok" | "dry_run" | "error", "operation": "...", ... }`.
|
||
Errors carry a stable `code` (`TARGET_EXISTS`, `SOURCE_NOT_FOUND`, ...)
|
||
and a `hint` describing the next action. On success, `mv` reports
|
||
`changed_files` with line-level `old`/`new` import diffs and counters
|
||
(`moved`, `updated_imports`).
|
||
|
||
## Exit codes
|
||
|
||
- `0` — success
|
||
- `1` — operation failed (read `--json` error or stderr)
|
||
- `2` — `check` found broken imports
|
||
|
||
## Rules of use
|
||
|
||
- Never run `mv` without a prior `--dry-run` in the same session.
|
||
- After every successful `mv`, run `check`; treat exit code `2` as
|
||
a failed refactor.
|