Output and Exit Codes

This page will inshallah help you read what refac prints, in text and in JSON.

TextCopy Anchor Link

Lines that start with // are refac's report. The other lines are the moved or renamed things.

MoveCopy Anchor Link

A skipped file next to a moved one is listed and the command still succeeds. A request in which nothing moved at all, for example only unsupported files, exits 1.

// Alhamdulillah 1 requested path was successfully refactored:

// Typescript results:

// 1 TypeScript/JavaScript source file moved (limit: 30).

src/lib/util.ts -> src/core/util.ts

// Markdown links to the moved files:

// Note: Checked 0 Markdown files; updated 0 links in 0 files.

RenameCopy Anchor Link

// Dry run: nothing was changed. Planned and verified rename:
total -> grandTotal
// src/core/util.ts (1 edit)
// src/main.ts (2 edits)
// 3 edit(s) in 2 file(s).
// Run the same command without --dry-run to write these edits.

A real rename starts with // Alhamdulillah symbol renamed:. A batch prints one block per rename and a total line. The // Note: lines name places refac did not change, and you may need to: the name inside strings and comments, untyped Python and Dart receivers, and Rust macro_rules! bodies, which are marked ATTENTION because the build breaks until you edit them.

Move a Rust moduleCopy Anchor Link

// Dry run: nothing was changed. Planned Rust module move:
crate::engine::matching -> crate::domain::matching
// move src/engine/matching.rs -> src/domain/matching.rs
// src/domain/mod.rs (2 edits)
// src/engine/mod.rs (1 edit)
// 3 edit(s) in 2 file(s); 1 path(s) would move.

A real move starts with // Alhamdulillah Rust module moved semantically:.

JSONCopy Anchor Link

--json works on move, move-module, rename, and doctor. A command prints one document on stdout.

moveCopy Anchor Link

{
  "status": "ok",
  "operation": "move",
  "project_path": ".",
  "source_path": ["n.md"],
  "target_path": ["x/n.md"],
  "result": "// Alhamdulillah 1 requested path was successfully refactored:\n..."
}

result holds the text report. With --batch, source_path and target_path are filled as well. With --dry-run the document adds dry_run, moved_paths, edited_files, edits, files, moves, and notes, and the paths are relative to the project path:

{
  "status": "ok",
  "operation": "move",
  "dry_run": true,
  "moved_paths": 1,
  "edited_files": 1,
  "edits": 1,
  "files": [{ "path": "r.md", "edits": 1 }],
  "moves": [{ "from": "n.md", "to": "x/n.md" }],
  "notes": ["Markdown: Checked 6 Markdown files; updated 1 link in 1 file."]
}

move-moduleCopy Anchor Link

status, operation (move-module), project_path, source_module, target_module, dry_run, compiled, moved_paths, edited_files, edits, files, and moves. compiled is true when cargo check passed: false for a plain --dry-run, true for --dry-run --check and for a real move.

renameCopy Anchor Link

{
  "status": "ok",
  "operation": "rename",
  "project_path": ".",
  "file": "src/core/util.ts",
  "symbol": "total",
  "new_name": "grandTotal",
  "dry_run": true,
  "edits": 3,
  "edited_files": 2,
  "files": [
    { "path": "src/core/util.ts", "edits": 1 },
    { "path": "src/main.ts", "edits": 2 }
  ],
  "notes": []
}

A batch prints "operation": "rename-batch" with project_path, dry_run, the totals, and a renames list that holds one object per rename.

doctorCopy Anchor Link

A list with one object per language: language, server, status (ready, missing, or broken), used_for, env_var, executable, version, looked (every place and what was there), requirements, start_check (only for doctor <language>), and install (the steps).

ErrorsCopy Anchor Link

A failure prints a document on stderr and exits 1:

{
  "status": "error",
  "error": "Source path does not exist: nope.md (Resolved to: \"/path/to/project/nope.md\")"
}

For a move that was only partly done, error holds the whole report: what moved and what failed.

Exit codesCopy Anchor Link

When a step fails, the message says Nothing was changed, or, in the rare case that an undo itself fails, which files to inspect with git status. A failed run inshallah won't leave you guessing.