# @macrulez/devtoolz — AI Reference

A toolbox of independent command-line commands (binary `devtoolz`) for routine
developer chores on a JavaScript/TypeScript project: strip comments and leftover
`console.log`, find dead exports and unused dependencies, catch import-case bugs that
only break on Linux CI, find import cycles, verify `package.json` paths and README code
examples, find swallowed errors, collect TODOs, check scripts and test files for
consistency, find stale `@ts-ignore`. One binary, one subcommand per chore. The image
commands `image-hash` and `image-batch` moved to `@macrulez/mediatoolz` in 0.5.0; here
they are stubs that print where they went and exit 2.
Version 0.5.0.

This document is hand-written for AI agents and other tools that drive this CLI: every
flag, default, exit code and behavior note below is verified against the TypeScript
source. It covers what `--help` does not make obvious: which command to pick, whether a
command can change files, exit codes, the JSON shapes, the rules each check uses to
decide something is a problem, and the false positives to expect. For narrative docs, see
the site:

- Full docs (EN): https://npm.vuecraft.ru/en/packages/devtoolz/guide/overview
- Full docs (RU): https://npm.vuecraft.ru/packages/devtoolz/guide/overview
- GitHub: https://github.com/macrulezru/devtoolz
- npm: https://www.npmjs.com/package/@macrulez/devtoolz

Links starting with "/" are relative to https://npm.vuecraft.ru.

Install: `npm install -g @macrulez/devtoolz`, or run without installing:
`npx @macrulez/devtoolz <command> ...`. Node >= 20.

---

## 1. Read this first — rules that prevent most mistakes

1. **Only these commands can change files: `strip-comments`, `console-strip`,
   `case-check --fix`.** Everything else is read-only. The three code-changing
   ones PREVIEW by default and write only with `-y`/`--yes` (and never with `--dry-run`).
2. **Exit code 1 means "found something", not "the tool broke".** Every diagnostic
   command exits 1 when it reports findings and 0 when clean. A preview of a
   code-changing command that WOULD change something also exits 1 (so a CI step fails
   until the change is applied). There is no separate code for a crash: an uncaught
   exception also exits 1. See section 4 for the exact rules.
3. **Add `--json` whenever you will parse the result.** It prints the full report as one
   JSON document on stdout, with no banner and no color. The human text output is for
   people; do not parse it.
4. **Output is colored only in a real terminal.** Piped, `CI`, `NO_COLOR`, `TERM=dumb`
   turn color off; `--color` or `FORCE_COLOR=1` force it on; `--plain` removes color, the
   banner and the joke lines; `--quiet` prints nothing when there is nothing to report.
   Text is identical with and without color.
5. **Nothing here is interactive except `full-check` (one question).** It is avoidable:
   `full-check --no-prompt`. Without a terminal nothing asks.
6. **`[paths...]` vs `[dir]`.** Some commands take file/directory paths to scan
   (`[paths...]`, default current directory); others take ONE package directory
   (`[dir]`, default `.`) because they read one `package.json` there. Passing a directory
   to a `[dir]` command does not scan sub-packages.
7. **Preview before applying**: run the code-changing commands once without `-y`
   (add `--diff` to see exactly what changes), then again with `-y`.

---

## 2. Choosing a command

| Task | Command | Changes files? |
|---|---|---|
| Remove `//`, `/* */`, `/** */`, `<!-- -->` comments | `strip-comments` | with `-y` |
| Remove forgotten `console.log`/`console.debug`/`debugger` | `console-strip` | with `-y` |
| Exports nothing imports | `dead-exports` | no |
| Dependencies nothing imports / imports not declared | `unused-deps` | no |
| Import cycles | `circular-imports` | no |
| Import path case differs from the file on disk | `case-check` | with `--fix -y` |
| `package.json` main/module/types/bin/exports point at missing files | `exports-doctor` | no |
| README/docs `ts` code blocks do not typecheck | `readme-check` | no |
| `catch` blocks that swallow the error | `empty-catch` | no |
| List TODO/FIXME/HACK | `todo-report` | no |
| Docs/CI mention a script that does not exist | `scripts-check` | no |
| Test files whose source is gone | `orphan-tests` | no |
| `@ts-ignore` that suppresses nothing | `stale-ts-ignore` | no |
| Run all diagnostics, one summary | `full-check` | no (always preview) |

Typical pre-commit chain: `case-check`, `circular-imports`, `dead-exports`,
`unused-deps`, `empty-catch`. Typical library-publish chain: `exports-doctor`,
`readme-check`, `scripts-check`. Or just `full-check`.

---

## 3. Shared behavior

### Common flags
Present on EVERY command: `--json`, `--quiet`, `--plain`, `--color`.
Commands that scan files also take: `--cwd <path>` (paths are resolved against it,
default the current directory), `--ext <list>`, `--ignore <glob>` (repeatable, added on
top of the defaults), `--no-respect-gitignore`.

### What gets scanned
`[paths...]` are files and/or directories (directories are walked recursively). An explicitly named file is included whatever its
extension. Always ignored: `node_modules`, `dist`, `build`, `.git`, `coverage`, `.nuxt`,
`.output`, `.next`; plus the `.gitignore` in the `--cwd` root only (nested `.gitignore`
files are NOT read); plus every `--ignore` pattern (gitignore syntax). `dead-exports`
also always skips build-tool config files (`*.config.{ts,js,mjs,cjs}`).
Default extensions: `.ts,.tsx,.js,.jsx,.cjs,.mjs` (+ `.vue` for `strip-comments`,
`console-strip`, `case-check`, `empty-catch`, `todo-report`).
`.vue`: the `<script>` block goes through the same TypeScript parser as `.ts`; template
`<!-- -->` comments are handled by a line-aware scan.

### Parsing
Code is parsed with the TypeScript Compiler API, not regex: a `//` or `console.log`
inside a string, template literal or regex literal is never treated as code.

---

## 4. Exit codes and `--json` report shapes

Every report has `exitCode`. Diagnostics: 1 if there are findings, else 0.

| Command | Exit 1 when |
|---|---|
| `strip-comments` | preview (no `-y`, or `--dry-run`) AND something would be stripped. With `-y`: 0. |
| `console-strip` | preview with pending changes, OR any call was left in place for manual review (`skipped` non-empty) — even with `-y`. |
| `case-check` | without `--fix -y`: any finding. With `--fix -y`: only alias findings (never auto-fixed) remain. |
| `dead-exports`, `circular-imports`, `empty-catch`, `unused-deps`, `exports-doctor`, `readme-check`, `scripts-check`, `orphan-tests`, `stale-ts-ignore` | any finding, or a fatal `error` (unreadable `package.json`, bad tsconfig, ...) |
| `todo-report` | findings > `--max` (default 0 = any finding fails) |
| `full-check` | any command reported findings or errored (see 5.14) |

Report shapes (all include `exitCode`; `error` is a string or null where noted):

- `strip-comments`: `{filesScanned, changes:[{file, count, diff?}], applied, exitCode}`
- `console-strip`: `{filesScanned, changes:[{file, count, diff?}], skipped:[{file, line,
  column, reason:"embedded-in-expression"|"braceless-body", snippet}], applied, exitCode}`
- `dead-exports`: `{filesScanned, findings:[{file, line, name, isDefault, isType}],
  hasUnresolvableDynamicImports, exitCode}`
- `circular-imports`: `{filesScanned, findings:[{files:[...], typeOnly}], exitCode}`
  (the cycle is `files[0] -> ... -> files[n] -> files[0]`)
- `unused-deps`: `{filesScanned, findings:[{kind:"unused"|"phantom", name, section?,
  resolvedFrom?}], error, exitCode}`
- `case-check`: `{filesScanned, findings:[{file, line, column, specifier,
  correctedSpecifier, isAlias}], changes:[{file, count, diff?}], applied, exitCode}`
- `exports-doctor`: `{packageName, findings:[{location, path, kind:"missing"|
  "case-mismatch"|"missing-shebang"|"types-missing", realPath?}], error, exitCode}`
- `readme-check`: `{fileResults:[{file, blocksChecked}], findings:[{file, line, column,
  lang, message}], error, exitCode}`
- `empty-catch`: `{filesScanned, findings:[{file, line, column, kind:"empty"|
  "console-only"}], exitCode}`
- `todo-report`: `{filesScanned, findings:[{file, line, column, tag, text}],
  countsByTag, max, exitCode}`
- `scripts-check`: `{findings:[{file, line, name, kind:"missing"|"undocumented"}],
  sourcesScanned:[...], error, exitCode}`
- `orphan-tests`: `{filesScanned, findings:[{file, triedExtensions}], error, exitCode}`
- `stale-ts-ignore`: `{directivesChecked, findings:[{file, line}], error, exitCode}`
- `full-check`: `{results:[{command, skipped, findingsCount, exitCode, error,
  report:<that command's own report>}], error, exitCode}`

File paths in reports are relative to `--cwd` (or the package directory) with `/`
separators.

---

## 5. Commands

### 5.1 `strip-comments [paths...]`
Removes `//`, `/* */`, `/** */` and (in `.vue` templates) `<!-- -->` comments in place.
Flags: `--keep-jsdoc` (keep a `/** */` directly above an exported declaration; every other
comment still goes), `--dry-run`, `-y/--yes`, `--diff` (a unified diff per changed file,
also under `changes[].diff` in JSON). A trailing comment on a code line is removed
without deleting the line. Removes ALL comments, including license headers, `// @ts-ignore`,
`// eslint-disable`, `/* istanbul ignore */`, `// prettier-ignore` and `#region`-style
markers — those are comments too. Do not run it on a codebase where such directives matter.

### 5.2 `console-strip [paths...]`
Removes `console.log`/`console.debug` calls and bare `debugger;` statements that are a
WHOLE STATEMENT on their own. `--methods <list>` (default `log,debug`; `warn` and `error`
are excluded on purpose — usually legitimate logging), `--no-debugger`. A call that is part
of a larger expression (`const r = console.log(x) || y`) or the body of a brace-less
`if/while/for` is NEVER deleted: it is reported in `skipped` with `reason`
(`embedded-in-expression` | `braceless-body`) and makes the exit code 1 even after `-y`.
Same `--dry-run`, `-y`, `--diff` as above.

### 5.3 `dead-exports [paths...]`
Named exports nothing imports. An export is NOT reported if: any `import` of it exists in
the scanned files; it is reachable from a public entry point through a chain of
`export { x } from` / `export * from` (a named re-export clears only that symbol); its
module is imported as a namespace (`import * as ns`) — then every export of that module
counts as used; it is a type used via `import type`.
Public entry points (exempt by default) are auto-detected from `package.json`
`exports`/`main`/`module`/`bin`, plus `src/index.ts(x)`. Flags: `--entry <path>`
(repeatable, extra public entries), `--strict` (also check the entry points themselves —
external consumers are unknown, so use for an app, not a library), `--no-workspace`
(a pnpm/npm/yarn workspace is auto-detected so a sibling package importing the export
counts). No `--fix`: never deletes anything.
`hasUnresolvableDynamicImports: true` means an `import(variable)` could not be resolved;
treat the findings as possibly containing false positives.
False positives to expect: exports used only via a framework convention (file-based
routes, Nuxt/Next pages, config default exports consumed by a tool), by a build-time
plugin, or by external consumers of an application.

### 5.4 `circular-imports [paths...]`
Cycles in the local import graph (A -> B -> ... -> A), every cycle reported once as its full
chain. A cycle made ONLY of `import type` edges is hidden (types are erased, harmless at
runtime): `--include-types` shows those, marked `typeOnly: true`. Flags: the common scan
flags. Read-only.

### 5.5 `unused-deps [dir]`
Dependencies in `package.json` that nothing imports ("unused") and packages imported but
not declared ("phantom": works only because something else hoisted it). Counts as used
besides a direct import: invoked by its bin name from `scripts` or `lint-staged`; named in
a known config file (`vitest.config.*`, `.eslintrc*`, `.stylelintrc*`, `postcss.config.*`,
`tsconfig.json`, ...) as a quoted string or bare identifier (word-boundary matched).
Packages that can never appear as text are exempt by default: `@types/*`, `typescript`,
`@vitest/coverage-*`, `@vitest/ui`, `@nuxt/schema`, `postcss`, `sass`, `less`, `stylus`;
`--strict` checks
them too. `--ignore-package <name>` (repeatable) exempts a dependency in both directions.
`[dir]` is both the scan root and where `package.json` is read. Never edits `package.json`.
Fatal `error` and exit 1 when `package.json` cannot be read.

### 5.6 `case-check [paths...]`
Import specifiers whose case differs from the file on disk (fine on Windows/macOS,
breaks on Linux CI). Checks every path segment. Resolves `tsconfig.json` path aliases
(`@/...`); `--tsconfig <path>` overrides auto-detection. `--fix` rewrites the specifier to
its real case, only with `-y`; ALIAS-resolved findings (`isAlias: true`) are reported but
never auto-fixed. `--dry-run`, `--diff` as in 5.1.

### 5.7 `exports-doctor [dir]`
Resolves every path `package.json` declares (`main`, `module`, `types`, `typings`, `bin`,
`exports` incl. nested conditions, subpath maps, fallback arrays) against the disk.
Finding kinds: `missing`; `case-mismatch` (real path in `realPath`); `missing-shebang` (a
`bin` file without `#!/usr/bin/env node`); `types-missing` (a subpath whose runtime
conditions resolve but that declares no `types` anywhere — TypeScript consumers get no
types; not raised for a plain-string subpath). Run it AFTER the build: a path into `dist`
is `missing` until built. Only `[dir]`, no scan flags.

### 5.8 `readme-check [dir]`
Typechecks fenced code blocks of README (or `--file <path>`, repeatable, relative to
`[dir]`) with the TypeScript compiler against the package's own `tsconfig.json`
(`--tsconfig`). Nothing is executed, only compiled. Default languages `ts`;
`--lang ts,tsx` to add `tsx`. The virtual file sits at the package root, so a
self-import of the package's published name resolves like a consumer's — this needs the
package BUILT and `moduleResolution` `bundler`/`node16`/`nodenext`. Each block is checked
in isolation; deliberately NOT reported: `Cannot find name` (context from outside the
block), `Cannot find module` for a relative path, "declared but never read", and a
self-import failing only because the package's own tsconfig lacks a modern
`moduleResolution`. A bare-package `Cannot find module 'pkg'` IS reported.

### 5.9 `empty-catch [paths...]`
`catch` blocks that do nothing with the error: fully empty (`kind: "empty"`) or containing
only `console.*` calls with no `throw`, no write to an outer variable, no meaningful
`return` (`kind: "console-only"`). A COMMENT inside the block exempts it (a human made the
call). No `--fix`. Handles `.vue`.

### 5.10 `todo-report [paths...]`
Lists comments carrying a tag with file:line:column and the text; a note wrapped across
several `//` lines or a multi-line `/* */` is joined into one text. `--tags <list>` (default
`TODO,FIXME,HACK`; matched as a whole word anywhere in a comment, case-insensitively, shown
in the configured spelling). `--max <n>` (default 0): fail only when findings exceed n —
use as a ratchet for existing debt. A tag inside a string literal is not a finding.

### 5.11 `scripts-check [dir]`
Cross-checks `package.json` `scripts` with README/docs (`--file`, repeatable, default
`README.md`) and `.github/workflows/*.yml`. `missing`: a script mentioned as `npm run X`,
`npm run-script X`, `yarn run X`, `pnpm run X`, `npm test` or `npm start` but not declared
— the high-value direction. `undocumented`: a declared script mentioned nowhere (bare
`yarn X` / `pnpm X` also count as mentions here) — a weak signal. Exempt from
`undocumented`: `prepublishOnly`, `preinstall`, `postinstall`, `prepare`, and `pre*`/`post*`
that have a declared peer script. A CI step under its own `working-directory:` is treated
as belonging to another `package.json`. Text-based, not AST-based.

### 5.12 `orphan-tests [paths...]`
Test files whose source is gone. A file is a test if its name has one of
`--test-suffix` (default `.test,.spec`) and an extension in `--ext`; its source is looked
up under `--source-ext` (default `.ts,.tsx,.js,.jsx,.mjs,.cjs,.vue`) next to it, or one
level up from a sibling `__tests__`/`tests`/`test`/`spec`/`specs` directory. Mirrored
layouts: `--source-dir` and `--test-dir` (always BOTH, relative to `--cwd`). Reliable ONLY
under a 1:1 naming convention. Known false positive: a scenario/integration test with no
single source file (`ssr.test.ts`) — exclude with `--ignore`.

### 5.13 `stale-ts-ignore [dir]`
A `// @ts-ignore` that no longer suppresses anything. Method: a real project-wide
typecheck is run twice — as is, and with every `@ts-ignore` masked (same length, so lines
do not shift) — and a directive is stale if no new diagnostic appears at its line. The most
expensive command (a full `tsc --noEmit` twice); skipped instantly when the project has no
`@ts-ignore`. Needs a loadable `tsconfig.json` (`--tsconfig`; fatal `error` otherwise).
`.vue` files get an isolated per-file check. `--ignore`/`--no-respect-gitignore` affect only
`.vue` discovery. Does NOT report `@ts-expect-error` (TypeScript already reports an unused
one itself). Never edits.

### 5.14 `full-check [dir]`
Runs the 13 diagnostics above in one sweep , each in its
safe mode: the three code-changing ones are always called as previews, `-y`/`--fix` are
never passed. One summary table; `--json` returns every command's own report under
`results[].report`. One command throwing does not stop the others (`results[].error`).
`--skip <name>` (repeatable) with names `strip-comments`, `console-strip`, `dead-exports`,
`case-check`, `exports-doctor`, `readme-check`, `unused-deps`, `circular-imports`,
`empty-catch`, `todo-report`, `scripts-check`, `orphan-tests`, `stale-ts-ignore`.
`--no-prompt`: in a real terminal a bare `full-check` asks whether to run the slow
`stale-ts-ignore`; `--no-prompt` (or `--skip stale-ts-ignore`, or any non-TTY/`--json`)
removes the question. Note that `strip-comments` and `console-strip` exit 1 as previews
whenever they would change something, so a repo with any comment makes `full-check` fail:
`--skip strip-comments --skip console-strip` for a CI gate.


## 6. Recipes

CI gate for a library:
`devtoolz exports-doctor && devtoolz readme-check && devtoolz scripts-check`
(run after the build), or `devtoolz full-check --no-prompt --skip strip-comments
--skip console-strip`.

Strip comments safely: `devtoolz strip-comments src --diff` (review), then
`devtoolz strip-comments src -y`. Keep export tooltips with `--keep-jsdoc`.

Find work, machine-readable: `devtoolz dead-exports src --json`; take
`findings[].file` and `.name`.

Ratchet TODO debt: `devtoolz todo-report src --max 20` (exit 1 only above 20).


---

## 7. Pitfalls

- `strip-comments` removes every comment kind, including `@ts-ignore`, `eslint-disable`
  and license headers. Preview with `--diff` first.
- A preview that WOULD change files exits 1 — a pipeline running `strip-comments src`
  without `-y` will fail by design.
- `console-strip -y` can still exit 1: calls it refused to touch are listed in `skipped`.
- `exports-doctor` and `readme-check` give `missing`/`Cannot find module` errors if the
  package was not built first.
- `dead-exports` on an app or a framework project (file-based routing, Nuxt/Next pages)
  reports exports that the framework consumes by convention; use `--entry` or `--ignore`.
- `orphan-tests` is only reliable with 1:1 test naming; `scripts-check` is text-based.
- `.gitignore` is read from the `--cwd` root only.
- `stale-ts-ignore` takes as long as two typechecks of the whole project.