feat(cli): expose --why as documented public alias for --explain (#161) (#198)

The MVP requested by #161 — a single-site suppression diagnosis at
`react-doctor --why <file:line>` — was already implemented as a
hidden alias for `--explain`. Promote it to a documented option so
users can reach it without reading the source.

Updates the README's CLI reference and suppressions section to make
the discovery story explicit:

- `--explain <file:line>` (and its `--why` alias) classify what the
  scanner sees at a single location, matching every status in the
  issue's classifier table (MISSING, WRONG_RULE, GAP_CODE, etc.).
- `--verbose` mode already surfaces the same suppression hint
  inline next to every flagged site, and `--json` mode includes it
  on each diagnostic as `suppressionHint`. A single scan therefore
  doubles as a suppression audit without a separate flag, which
  covers the "Bonus" and most of the "Maximum" goals from the
  request.

Removes the unused `Option` import that the previous
`addOption(...).hideHelp()` wiring left behind.

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Aiden Bai <aidenybai@users.noreply.github.com>

Author: aidenybai

packages/react-doctor/README.md

@@ -151,10 +151,11 @@ Options:
   --fail-on <level>       exit with error on diagnostics: error, warning, none
   --annotations           output diagnostics as GitHub Actions annotations
   --explain <file:line>   diagnose why a rule fired or why a suppression didn't apply
+  --why <file:line>       alias for --explain
   -h, --help              display help
 ```
 
-When a suppression isn't working, `--explain <file:line>` reports what the scanner sees at that location, including why a nearby `react-doctor-disable-next-line` didn't apply. The same hint surfaces inline with `--verbose` and in `--json` output as `diagnostic.suppressionHint`.
+When a suppression isn't working, `--explain <file:line>` (or its alias `--why <file:line>`) reports what the scanner sees at that location, including why a nearby `react-doctor-disable-next-line` didn't apply. The diagnosis distinguishes the common failure modes — adjacent comment for a different rule (use the comma form), a code line between the comment and the diagnostic (the chain is broken), or no nearby suppression at all. The same hint surfaces inline with `--verbose` for every flagged site, and in `--json` output as `diagnostic.suppressionHint`, so a single scan doubles as a suppression audit without a separate flag.
 
 `--json` produces a parsable object on stdout with all human-readable output suppressed. Errors still produce a JSON object with `ok: false`, so stdout is always a valid document.
 

packages/react-doctor/src/cli.ts

@@ -2,7 +2,7 @@ import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { performance } from "node:perf_hooks";
-import { Command, Option } from "commander";
+import { Command } from "commander";
 import { CANONICAL_GITHUB_URL } from "./constants.js";
 import { runInstallSkill } from "./install-skill.js";
 import { scan } from "./scan.js";
@@ -400,7 +400,7 @@ const program = new Command()
     "--explain <file:line>",
     "diagnose why a rule fired or why a suppression didn't apply at a specific location",
   )
-  .addOption(new Option("--why <file:line>", "alias for --explain").hideHelp())
+  .option("--why <file:line>", "alias for --explain")
   .option(
     "--respect-inline-disables",
     "respect inline `// eslint-disable*` / `// oxlint-disable*` comments (default)",