loki5512344
f8004e669b
- parser::java::class_name: exactly-one-public-top-level-type rule
(package-info/module-info and 0-or-2-public files skipped)
- check gains name_mismatches[] (JSON, omitted when clean) + human lines;
exit 2 covers both kinds; fix engine untouched by design — a file rename
is not a byte edit, and mv keeps the FQN so no imports change
- output split into output/{mod,check} to stay under the 250-line rule
- e2e: reports Bad.java, stays quiet on Good.java, suggested rename makes
check pass and preserves the file bytes
131 lines
5.9 KiB
Markdown
131 lines
5.9 KiB
Markdown
# jmove skill (for AI agents)
|
||
|
||
## What this tool does
|
||
|
||
Moves or renames source files — or whole directories of them — 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] [--source-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).
|
||
|
||
Directory moves: `mv <dir> <target>` relocates every indexed file under
|
||
`<dir>` mirrored under `<target>` in one atomic batch. `--json` adds
|
||
`moved_files[]` (from/to per file) and `left_behind[]` — real files under
|
||
`<dir>` that are not indexable and deliberately stay where they are.
|
||
Emptied source directories are pruned; a directory with leftovers is not.
|
||
A source that is nested in its own target fails with `PLAN_REJECTED`.
|
||
|
||
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 and Java layout errors
|
||
|
||
```
|
||
jmove check [--root DIR] [--json]
|
||
```
|
||
|
||
Run after any move (or any edit) to validate project consistency. Reports
|
||
broken relative imports and Java files whose single public type is named
|
||
differently from the file (each finding carries the exact `jmove mv` that
|
||
renames it; exit code 2 covers both kinds).
|
||
|
||
### 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). TS/JS:
|
||
`ts/unused-import` deletes whole statements whose every bound name is
|
||
unreferenced; mixed statements (one name live) stay untouched because ESM
|
||
imports carry module side effects, so partial specifier surgery is
|
||
deliberately off. 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.
|
||
- Monorepos with duplicate packages (`guava` vs `android/guava` under one
|
||
`--root`): the same FQN exists in parallel trees, so resolution picks the
|
||
sorted-first copy and a move rewrites the wrong files. Pass the global
|
||
`--source-root DIR` to index (and fix/move) only that subtree; each tree
|
||
is then self-contained and correct. Without the flag behavior is
|
||
unchanged; `--source-root` on a non-directory exits 1.
|
||
|
||
## 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 or Java name mismatches
|
||
|
||
## 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.
|