@macrulez/devtoolz 0.1.0 → 0.2.1

package/README.md

@@ -37,6 +37,23 @@ looking for is never touched.
   symbol is really declared, and auto-detects a pnpm/npm/yarn workspace
   so a sibling package importing your export doesn't read as dead either.
   `--strict` checks the entry points too, for when you actually want that.
+- **`unused-deps`** — finds `package.json` dependencies nothing imports,
+  and the reverse: a package genuinely imported but never declared (a
+  "phantom" dependency, working only because something else hoisted it
+  into `node_modules`). Knows about the usual ways a dependency is used
+  without ever being imported — invoked from `scripts`/`lint-staged` by
+  its bin name, referenced as a string or bare key in a config file
+  (`vitest.config.ts`'s `environment: 'happy-dom'`,
+  `postcss.config.js`'s `plugins: { autoprefixer: {} }`) — plus a small,
+  explicit list of packages no static analysis could ever catch
+  (`@types/*`, `typescript`, `@vitest/coverage-*`, `postcss`/`sass`).
+  `--strict` checks that last list too, for a manual audit.
+- **`circular-imports`** — finds import cycles (`A → B → … → A`) in your
+  own code — the kind that can silently produce `undefined` at module
+  load time in ESM. Reports every cycle found, not just the first, as
+  its full chain. A cycle made entirely of `import type` is harmless at
+  runtime (types are erased) and hidden by default — `--include-types`
+  shows those too, clearly marked.
 - **`case-check`** — finds imports whose case doesn't match the real
   file on disk. Windows and macOS are case-insensitive by default, so
   `import './foo'` against a real `Foo.ts` works fine right up until it
@@ -64,12 +81,71 @@ looking for is never touched.
   dropped rather than reported as noise (see `--help`/features.md for
   exactly which). `--lang` opts into `tsx`/`js`/`jsx` (default: `ts`
   only — `tsx` needs the package to actually configure JSX itself).
+- **`empty-catch`** — finds `catch` blocks that do nothing with the
+  error, or do so little it's effectively swallowed: fully empty, or a
+  body that's nothing but `console.*` calls with no `throw`, no write to
+  an outer-scope variable, no meaningful `return`. Syntactically valid
+  code that ordinary lint rules can't catch — needs a semantic check, not
+  a syntactic one. A comment inside the block (found via a real token
+  scan, not text matching) exempts the finding, same principle as
+  ESLint's `no-empty` for documented empty blocks. Handles `.vue` files.
+- **`todo-report`** — summarizes `TODO`/`FIXME`/`HACK` comments across
+  the project — file:line plus the note's actual text, including one
+  wrapped across several `//` lines or a multi-line `/* */` block, joined
+  back into one readable line. `--tags` configures the list (default
+  `TODO,FIXME,HACK`); `--max <n>` turns the default "fail on any finding"
+  into a ratchet for a project that's knowingly living with existing
+  debt. Handles `.vue` files, including `<!-- -->` template comments.
+- **`scripts-check`** — cross-checks `package.json`'s `scripts` against
+  README/docs and `.github/workflows/*.yml`: a mentioned-but-undeclared
+  script (`npm run X`, `npm test`/`start`, `yarn`/`pnpm run X`) is a
+  real broken link — renamed a script, forgot to update the docs or CI —
+  and, as a weaker signal, a declared script nothing documents. npm's
+  own reserved lifecycle names (`prepublishOnly`,
+  `preinstall`, `postinstall`, `prepare`, any `pre*`/`post*` for another
+  declared script) are exempt from the second direction — npm calls
+  those itself. A CI step under its own `working-directory:` (a `demo/`
+  subproject, say) is understood to belong to a different `package.json`
+  entirely, not flagged against this one's.
+- **`orphan-tests`** — finds test files whose source disappeared —
+  renamed or deleted, the test still green, testing nothing real
+  anymore. Reliable only under a simple naming convention: co-located
+  (`Foo.test.ts` next to `Foo.ts`, including a sibling `__tests__`/`tests`
+  directory one level down), or an explicit `--source-dir`/`--test-dir`
+  mirror. A scenario/integration test with no single corresponding source
+  file is a known false positive under that strict rule — `--ignore`
+  is the documented way to exclude it, not something this command tries
+  to guess.
+- **`stale-ts-ignore`** — finds a `// @ts-ignore` that no longer
+  suppresses anything: the code below it was fixed, the comment wasn't
+  removed. There's no compiler API for "was this specific directive
+  needed" — this runs a real project-wide typecheck twice (once as-is,
+  once with every directive masked out) and compares the delta at each
+  directive's own line, so it's the most expensive command here, and
+  says so up front when there's real work to do. Skips the expensive
+  part entirely when there's not a single `@ts-ignore` in the project.
+  `.vue` files get an isolated per-file check (same technique as
+  `readme-check`'s own virtual-file typechecking) — a plain
+  `ts.Program` can't include `.vue` in a whole-project run at all.
+- **`full-check`** — runs all twelve other commands in one sweep, each in
+  its own safe read-only mode — the three that can write to disk
+  (`strip-comments`/`console-strip`/`case-check`) are always called as a
+  preview, `-y`/`--fix` are never passed. One summary table: which
+  commands are clean, which found something, which errored. Since
+  `stale-ts-ignore` is the one command that can make a bare `full-check`
+  noticeably slower, running it with no flags in a real terminal asks
+  first — `--skip stale-ts-ignore` skips both the question and the
+  command, `--no-prompt` runs everything without asking (the default
+  answer either way).
 
 `strip-comments`, `console-strip`, and `case-check` share the same safety
 model: `--dry-run` (or just running with neither `--dry-run` nor `-y`)
 only previews, `-y`/`--yes` is required to actually write anything,
-`--diff` shows a real unified diff per file. `dead-exports` is read-only,
-it never writes anything — there's nothing to preview. Every command
+`--diff` shows a real unified diff per file. `dead-exports`,
+`unused-deps`, `circular-imports`, `exports-doctor`, `readme-check`,
+`empty-catch`, `todo-report`, `scripts-check`, `orphan-tests`,
+`stale-ts-ignore`, and `full-check` are all read-only — none of them ever
+write anything, there's nothing to preview or apply. Every command
 supports `--json` for machine-readable output.
 
 ## Tone
@@ -109,6 +185,11 @@ devtoolz console-strip src -y
 
 devtoolz dead-exports src                      # report-only, nothing to apply
 
+devtoolz unused-deps                           # package.json deps vs what's actually imported
+devtoolz unused-deps path/to/package --strict   # also check @types/*, typescript, etc.
+
+devtoolz circular-imports src                  # find import cycles (A -> B -> ... -> A)
+
 devtoolz case-check src --fix --diff --dry-run # preview a case fix
 devtoolz case-check src --fix -y               # apply it
 
@@ -117,6 +198,20 @@ devtoolz exports-doctor path/to/package         # or a specific package director
 
 devtoolz readme-check                          # typecheck ts blocks in ./README.md
 devtoolz readme-check --file docs/guide.md      # check another doc instead/as well
+
+devtoolz empty-catch src                       # find catch blocks that swallow the error
+
+devtoolz todo-report src                       # summarize TODO/FIXME/HACK comments
+devtoolz todo-report src --max 20              # ratchet: fail only once findings exceed 20
+
+devtoolz scripts-check                         # package.json scripts vs README/CI mentions
+
+devtoolz orphan-tests src                      # test files whose source disappeared
+
+devtoolz stale-ts-ignore                       # find @ts-ignore comments suppressing nothing
+
+devtoolz full-check                            # run every command, one summary table
+devtoolz full-check --skip stale-ts-ignore     # same, minus the expensive one
 ```
 
 Every command has built-in `--help` — `devtoolz --help` lists every
@@ -175,6 +270,33 @@ Scanned 3 files.
   src/types.ts:1    Options       (type)
 ```
 
+`devtoolz unused-deps` against a package with one truly unused dependency
+and one phantom (imported but never declared):
+
+```
+🧰 devtoolz, reporting for duty
+
+Scanned 1 file.
+
+2 problems found:
+  phantom  dotenv    resolves from C:\tmp\demo-pkg\node_modules\dotenv — not declared in package.json
+  unused   left-pad  (dependencies, not imported anywhere)
+```
+
+`devtoolz circular-imports src` against two files that import each other:
+
+```
+🧰 devtoolz — chores, automated
+
+Scanned 2 files.
+
+1 circular import found:
+
+  src/order.ts
+  → src/user.ts
+  → src/order.ts
+```
+
 `devtoolz case-check src --fix --diff --dry-run` after a file got renamed
 `Helper.ts` → `helper.ts` on someone's Mac, with the import never updated:
 
@@ -221,6 +343,79 @@ Typechecked 1 code block across 1 file.
   README.md:6:7  ts  Type 'string' is not assignable to type 'number'.
 ```
 
+`devtoolz empty-catch src` against a `catch` block that only logs the
+error and never rethrows or handles it:
+
+```
+Scanned 1 file.
+
+1 problem found:
+  src/example.ts:4:5  console-only  only logged, never handled — silently swallowed either way
+```
+
+`devtoolz todo-report src` against a `TODO` wrapped across several `//`
+lines — joined back into one readable note, not cut off mid-sentence:
+
+```
+Scanned 1 file.
+
+1 comment found (TODO: 1):
+  src/example.ts:9:4  TODO  TODO: replace the hardcoded timeout below with a value read from config once loadConfig() above actually works end to end
+```
+
+`devtoolz scripts-check` against a package whose README has a typo'd
+script name, and two real scripts nothing documents:
+
+```
+Checked 1 source against package.json's scripts.
+
+3 problems found:
+  README.md:4     buld    mentioned here, but not in package.json scripts
+  package.json:4  build   in package.json scripts, but not mentioned anywhere checked
+  package.json:6  deploy  in package.json scripts, but not mentioned anywhere checked
+```
+
+`devtoolz orphan-tests src` after `parseQuery.ts` was renamed/removed but
+its test survived:
+
+```
+Scanned 3 files.
+
+1 orphan test found:
+  src/parseQuery.test.ts  orphan  no matching source found (tried .ts, .tsx, .js, .jsx, .mjs, .cjs, .vue)
+```
+
+`devtoolz stale-ts-ignore` against a `@ts-ignore` above a line that
+typechecks cleanly on its own — the code was fixed, the comment wasn't:
+
+```
+Checked 1 @ts-ignore directive.
+
+1 stale @ts-ignore found:
+  src/example.ts:2  @ts-ignore  doesn't suppress anything — the line below it typechecks cleanly without it
+```
+
+`devtoolz full-check` against a small package with a few real, unrelated
+problems scattered across it:
+
+```
+✖ strip-comments    1 found
+✔ console-strip     clean
+✖ dead-exports      1 found
+✔ case-check        clean
+✔ exports-doctor    clean
+✔ readme-check      clean
+✔ unused-deps       clean
+✔ circular-imports  clean
+✖ empty-catch       1 found
+✔ todo-report       clean
+✖ scripts-check     3 found
+✔ orphan-tests      clean
+✔ stale-ts-ignore   clean
+
+9 clean, 4 found something — see `devtoolz <command> --help` for full detail on any of them.
+```
+
 ## Development
 
 ```bash

package/dist/cli.js

@@ -1,18 +1,36 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 import { resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
 import { runStripComments } from './commands/strip-comments/run.js';
 import { renderStripCommentsReport } from './commands/strip-comments/report.js';
 import { runConsoleStrip } from './commands/console-strip/run.js';
 import { renderConsoleStripReport } from './commands/console-strip/report.js';
 import { runDeadExports } from './commands/dead-exports/run.js';
 import { renderDeadExportsReport } from './commands/dead-exports/report.js';
+import { runCircularImports } from './commands/circular-imports/run.js';
+import { renderCircularImportsReport } from './commands/circular-imports/report.js';
+import { runUnusedDeps } from './commands/unused-deps/run.js';
+import { renderUnusedDepsReport } from './commands/unused-deps/report.js';
 import { runCaseCheck } from './commands/case-check/run.js';
 import { renderCaseCheckReport } from './commands/case-check/report.js';
 import { runExportsDoctor } from './commands/exports-doctor/run.js';
 import { renderExportsDoctorReport } from './commands/exports-doctor/report.js';
 import { runReadmeCheck } from './commands/readme-check/run.js';
 import { renderReadmeCheckReport } from './commands/readme-check/report.js';
+import { runEmptyCatch } from './commands/empty-catch/run.js';
+import { renderEmptyCatchReport } from './commands/empty-catch/report.js';
+import { runTodoReport } from './commands/todo-report/run.js';
+import { renderTodoReportReport } from './commands/todo-report/report.js';
+import { DEFAULT_TAGS } from './commands/todo-report/core.js';
+import { runScriptsCheck } from './commands/scripts-check/run.js';
+import { renderScriptsCheckReport } from './commands/scripts-check/report.js';
+import { runOrphanTests } from './commands/orphan-tests/run.js';
+import { renderOrphanTestsReport } from './commands/orphan-tests/report.js';
+import { runStaleTsIgnore } from './commands/stale-ts-ignore/run.js';
+import { renderStaleTsIgnoreReport } from './commands/stale-ts-ignore/report.js';
+import { runFullCheck, FULL_CHECK_COMMAND_NAMES, SLOW_FULL_CHECK_COMMAND, } from './commands/full-check/run.js';
+import { renderFullCheckReport } from './commands/full-check/report.js';
 function wrapText(text, width) {
     const words = text.split(' ');
     const lines = [];
@@ -241,6 +259,71 @@ program
     }
     process.exitCode = report.exitCode;
 });
+program
+    .command('circular-imports')
+    .description('Find import cycles in the local module graph (A -> B -> ... -> A)')
+    .argument('[paths...]', 'files/directories to process', [])
+    .option('--cwd <path>', 'root paths are resolved against', process.cwd())
+    .option('--ext <list>', 'comma-separated extensions to include', '.ts,.tsx,.js,.jsx,.cjs,.mjs')
+    .option('--ignore <glob>', 'extra ignore pattern (repeatable), on top of the built-in defaults', (val, prev) => [...prev, val], [])
+    .option('--no-respect-gitignore', "don't also honor the project's .gitignore")
+    .option('--include-types', 'also report cycles made entirely of `import type` edges (harmless at runtime by default, so hidden)', false)
+    .option('--json', 'machine-readable output', false)
+    .option('--quiet', 'suppress output when there is nothing to report', false)
+    .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .action((paths, options) => {
+    const report = runCircularImports({
+        paths,
+        cwd: resolve(options.cwd),
+        extensions: options.ext.split(',').map((e) => e.trim()),
+        ignoreGlobs: options.ignore,
+        respectGitignore: options.respectGitignore,
+        includeTypes: options.includeTypes,
+    });
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        const text = renderCircularImportsReport(report, {
+            quiet: options.quiet,
+            plain: options.plain,
+        });
+        if (text)
+            console.log(text);
+    }
+    process.exitCode = report.exitCode;
+});
+program
+    .command('unused-deps')
+    .description('Find package.json dependencies nothing imports, and imports of packages package.json never declared')
+    .argument('[dir]', 'package directory to check — also the scan root', '.')
+    .option('--ext <list>', 'comma-separated extensions to include', '.ts,.tsx,.js,.jsx,.cjs,.mjs')
+    .option('--ignore <glob>', 'extra ignore pattern (repeatable), on top of the built-in defaults', (val, prev) => [...prev, val], [])
+    .option('--no-respect-gitignore', "don't also honor the project's .gitignore")
+    .option('--strict', 'also check packages that are structurally undetectable as "used" (currently: @types/*)', false)
+    .option('--ignore-package <name>', 'exempt a specific dependency from the unused/phantom check (repeatable)', (val, prev) => [...prev, val], [])
+    .option('--json', 'machine-readable output', false)
+    .option('--quiet', 'suppress output when there is nothing to report', false)
+    .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .action((dir, options) => {
+    const report = runUnusedDeps({
+        dir: resolve(dir),
+        extensions: options.ext.split(',').map((e) => e.trim()),
+        ignoreGlobs: options.ignore,
+        respectGitignore: options.respectGitignore,
+        strict: options.strict,
+        ignorePackages: options.ignorePackage,
+    });
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        const text = renderUnusedDepsReport(report, { quiet: options.quiet, plain: options.plain });
+        if (text)
+            console.log(text);
+    }
+    process.exitCode = report.exitCode;
+});
 program
     .command('case-check')
     .description("Find imports whose case doesn't match the real file on disk — works on Windows/Mac, breaks on Linux CI")
@@ -326,5 +409,236 @@ program
     }
     process.exitCode = report.exitCode;
 });
+program
+    .command('empty-catch')
+    .description('Find catch blocks that do nothing with the error, or only log it — both silently swallow it')
+    .argument('[paths...]', 'files/directories to process', [])
+    .option('--cwd <path>', 'root paths are resolved against', process.cwd())
+    .option('--ext <list>', 'comma-separated extensions to include', '.ts,.tsx,.js,.jsx,.cjs,.mjs,.vue')
+    .option('--ignore <glob>', 'extra ignore pattern (repeatable), on top of the built-in defaults', (val, prev) => [...prev, val], [])
+    .option('--no-respect-gitignore', "don't also honor the project's .gitignore")
+    .option('--json', 'machine-readable output', false)
+    .option('--quiet', 'suppress output when there is nothing to report', false)
+    .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .action((paths, options) => {
+    const report = runEmptyCatch({
+        paths,
+        cwd: resolve(options.cwd),
+        extensions: options.ext.split(',').map((e) => e.trim()),
+        ignoreGlobs: options.ignore,
+        respectGitignore: options.respectGitignore,
+    });
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        const text = renderEmptyCatchReport(report, { quiet: options.quiet, plain: options.plain });
+        if (text)
+            console.log(text);
+    }
+    process.exitCode = report.exitCode;
+});
+program
+    .command('todo-report')
+    .description('Summarize TODO/FIXME/HACK comments across the project — file:line + the text itself')
+    .argument('[paths...]', 'files/directories to process', [])
+    .option('--cwd <path>', 'root paths are resolved against', process.cwd())
+    .option('--ext <list>', 'comma-separated extensions to include', '.ts,.tsx,.js,.jsx,.cjs,.mjs,.vue')
+    .option('--ignore <glob>', 'extra ignore pattern (repeatable), on top of the built-in defaults', (val, prev) => [...prev, val], [])
+    .option('--no-respect-gitignore', "don't also honor the project's .gitignore")
+    .option('--tags <list>', 'comma-separated tags to look for', DEFAULT_TAGS.join(','))
+    .option('--max <n>', "don't fail unless findings exceed this count (a ratchet, not a hard zero)", '0')
+    .option('--json', 'machine-readable output', false)
+    .option('--quiet', 'suppress output when there is nothing to report', false)
+    .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .action((paths, options) => {
+    const report = runTodoReport({
+        paths,
+        cwd: resolve(options.cwd),
+        extensions: options.ext.split(',').map((e) => e.trim()),
+        ignoreGlobs: options.ignore,
+        respectGitignore: options.respectGitignore,
+        tags: options.tags.split(',').map((t) => t.trim()),
+        max: Number(options.max),
+    });
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        const text = renderTodoReportReport(report, { quiet: options.quiet, plain: options.plain });
+        if (text)
+            console.log(text);
+    }
+    process.exitCode = report.exitCode;
+});
+program
+    .command('scripts-check')
+    .description("Cross-checks package.json's scripts against README/docs and .github/workflows — a mention of a script that doesn't exist, and (weaker signal) a script nothing documents")
+    .argument('[dir]', 'package directory to check', '.')
+    .option('--file <path>', 'markdown/doc file to check, relative to [dir] (repeatable) — default: README.md', (val, prev) => [...prev, val], [])
+    .option('--json', 'machine-readable output', false)
+    .option('--quiet', 'suppress output when there is nothing to report', false)
+    .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .action((dir, options) => {
+    const report = runScriptsCheck({ dir: resolve(dir), files: options.file });
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        const text = renderScriptsCheckReport(report, {
+            quiet: options.quiet,
+            plain: options.plain,
+        });
+        if (text)
+            console.log(text);
+    }
+    process.exitCode = report.exitCode;
+});
+program
+    .command('orphan-tests')
+    .description('Finds test files whose source disappeared — renamed or deleted, test still green, testing nothing real anymore. Reliable only under a co-located (X.test.ts next to X.ts) or --source-dir/--test-dir mirrored naming convention')
+    .argument('[paths...]', 'files/directories to process (co-located mode only)', [])
+    .option('--cwd <path>', 'root paths are resolved against', process.cwd())
+    .option('--ext <list>', 'comma-separated extensions to consider as possible test files', '.ts,.tsx,.js,.jsx,.mjs,.cjs')
+    .option('--ignore <glob>', 'extra ignore pattern (repeatable), on top of the built-in defaults', (val, prev) => [...prev, val], [])
+    .option('--no-respect-gitignore', "don't also honor the project's .gitignore")
+    .option('--test-suffix <list>', 'comma-separated suffixes that mark a test file', '.test,.spec')
+    .option('--source-ext <list>', 'comma-separated extensions tried for a matching source file', '.ts,.tsx,.js,.jsx,.mjs,.cjs,.vue')
+    .option('--source-dir <path>', 'mirrored layout: source root, relative to --cwd (must be given together with --test-dir)')
+    .option('--test-dir <path>', 'mirrored layout: test root, relative to --cwd (must be given together with --source-dir)')
+    .option('--json', 'machine-readable output', false)
+    .option('--quiet', 'suppress output when there is nothing to report', false)
+    .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .action((paths, options) => {
+    const report = runOrphanTests({
+        paths,
+        cwd: resolve(options.cwd),
+        extensions: options.ext.split(',').map((e) => e.trim()),
+        ignoreGlobs: options.ignore,
+        respectGitignore: options.respectGitignore,
+        testSuffixes: options.testSuffix.split(',').map((s) => s.trim()),
+        sourceExtensions: options.sourceExt.split(',').map((e) => e.trim()),
+        ...(options.sourceDir ? { sourceDir: options.sourceDir } : {}),
+        ...(options.testDir ? { testDir: options.testDir } : {}),
+    });
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        const text = renderOrphanTestsReport(report, { quiet: options.quiet, plain: options.plain });
+        if (text)
+            console.log(text);
+    }
+    process.exitCode = report.exitCode;
+});
+program
+    .command('stale-ts-ignore')
+    .description("Finds a `// @ts-ignore` that no longer suppresses anything — the code below it was fixed, the comment wasn't removed. Runs a full project typecheck twice, so it's the most expensive command here")
+    .argument('[dir]', 'package directory to check', '.')
+    .option('--tsconfig <path>', 'tsconfig.json to read compiler options from (auto-detected by default)')
+    .option('--ignore <glob>', 'extra ignore pattern (repeatable), on top of the built-in defaults — applies to .vue file discovery only', (val, prev) => [...prev, val], [])
+    .option('--no-respect-gitignore', "don't also honor the project's .gitignore for .vue discovery")
+    .option('--json', 'machine-readable output', false)
+    .option('--quiet', 'suppress output when there is nothing to report', false)
+    .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .action((dir, options) => {
+    const report = runStaleTsIgnore({
+        dir: resolve(dir),
+        ...(options.tsconfig ? { tsconfig: options.tsconfig } : {}),
+        ignoreGlobs: options.ignore,
+        respectGitignore: options.respectGitignore,
+        ...(options.quiet ? {} : { onProgress: (message) => console.error(message) }),
+    });
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        const text = renderStaleTsIgnoreReport(report, {
+            quiet: options.quiet,
+            plain: options.plain,
+        });
+        if (text)
+            console.log(text);
+    }
+    process.exitCode = report.exitCode;
+});
+// Only `full-check` ever prompts — every other command here is a single,
+// fast, non-interactive check. `stale-ts-ignore` is the one command a
+// bare `full-check` can turn into a genuinely slow run, so this asks
+// about that ONE command specifically, not a general "run everything?"
+// confirmation. Defaults to running it (Enter alone picks option 1) —
+// matches what happens when there's no TTY to ask at all (see
+// `shouldPrompt` below), so a script and an interactive "just press
+// enter" run behave the same way.
+// Deliberately a SINGLE `question()` call, no retry-on-invalid-input loop
+// — found via real testing that a second `question()` on the same (or
+// even a fresh) `readline/promises` interface can silently lose the
+// answer and hang forever once more than one line was already available
+// on stdin when the first question resolved (a real, reproducible
+// readline quirk with piped/non-interactive input, not something specific
+// to this code). One question, with an explicit default on anything else
+// typed, sidesteps the whole bug class instead of risking it.
+async function promptStaleTsIgnoreChoice() {
+    process.stderr.write('stale-ts-ignore runs a full project typecheck twice — this can take noticeably longer than the other commands on a large project.\n\n' +
+        '  1) Run it anyway (full sweep)\n' +
+        '  2) Skip it for this run\n\n');
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    let answer;
+    try {
+        answer = (await rl.question('Choice [1/2, Enter = 1]: ')).trim();
+    }
+    finally {
+        rl.close();
+    }
+    if (answer === '2')
+        return false;
+    if (answer !== '' && answer !== '1') {
+        process.stderr.write(`(didn't recognize "${answer}" — running it, same as Enter)\n`);
+    }
+    return true;
+}
+program
+    .command('full-check')
+    .description('Runs every other command in its own safe/read-only mode — a full diagnostic sweep, never applies a fix')
+    .argument('[dir]', 'directory every command scans/reads from', '.')
+    .option('--skip <command>', `skip a command by name (repeatable) — valid names: ${FULL_CHECK_COMMAND_NAMES.join(', ')}`, (val, prev) => [...prev, val], [])
+    .option('--no-prompt', "don't ask about stale-ts-ignore even in an interactive terminal — runs it unless --skip already excludes it")
+    .option('--json', 'machine-readable output', false)
+    .option('--quiet', 'suppress output when there is nothing to report', false)
+    .option('--plain', 'disable color/banner/celebration copy, even in a real terminal', false)
+    .action(async (dir, options) => {
+    const skip = new Set(options.skip);
+    const shouldPrompt = options.prompt &&
+        !options.json &&
+        !skip.has(SLOW_FULL_CHECK_COMMAND) &&
+        Boolean(process.stdin.isTTY) &&
+        Boolean(process.stdout.isTTY);
+    if (shouldPrompt) {
+        const runIt = await promptStaleTsIgnoreChoice();
+        if (!runIt)
+            skip.add(SLOW_FULL_CHECK_COMMAND);
+        process.stderr.write('\n');
+    }
+    const showProgress = !options.json && !options.quiet;
+    const report = runFullCheck({
+        dir: resolve(dir),
+        skip: [...skip],
+        ...(showProgress
+            ? {
+                onCommandStart: (command) => process.stderr.write(`Running ${command}...\n`),
+                onProgress: (message) => process.stderr.write(`${message}\n`),
+            }
+            : {}),
+    });
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        const text = renderFullCheckReport(report, { quiet: options.quiet, plain: options.plain });
+        if (text)
+            console.log(text);
+    }
+    process.exitCode = report.exitCode;
+});
 program.parse(process.argv);
 //# sourceMappingURL=cli.js.map