@sikkuumiii/defuse 0.0.0-stage → 0.5.0

package/src/cli.ts

@@ -0,0 +1,747 @@
+#!/usr/bin/env node
+/**
+ * THE COMMAND-LINE INTERFACE
+ *
+ * Hand-rolled argument parsing, no library. It is about 60 lines, you can read
+ * all of them, and it means the tool has exactly two runtime dependencies -
+ * both of them the parser.
+ *
+ * Commands:
+ *   defuse scan <path>     scan a file or directory
+ *   defuse ast <file>      print the syntax tree (learning / debugging)
+ *   defuse rules           list the rules and what they do NOT cover
+ *   defuse doctor          check every grammar loads and every query compiles
+ *
+ * EXIT CODES matter for CI:
+ *   0  nothing at or above the --fail-on threshold
+ *   1  findings at or above the threshold
+ *   2  the tool itself failed (bad arguments, unreadable path, internal error)
+ */
+
+import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+import { SEVERITY_ORDER, type Severity } from './core/finding.js';
+import { buildCoverageReport } from './core/coverage.js';
+import { LICENCE_LINE, LICENCE_SPDX } from './core/licence.js';
+import { scan, type ScanResult } from './engine/scan.js';
+import { SHAPE_QUERY_SOURCES } from './engine/shapes.js';
+import { dumpAst } from './parse/astDump.js';
+import { detectLanguage, LANGUAGES } from './parse/languages.js';
+import { getLanguage, initEngine } from './parse/parser.js';
+import { parseFile, useNodeGrammars } from './parse/node-grammars.js';
+import { checkDependencies, findLockfiles, queryOsv } from './platform/deps.js';
+import { RUNTIME_VERSION_RULE } from './platform/runtime-version.js';
+import { ALL_RULES, validateRegistry } from './rules/registry.js';
+import { color, g, setAsciiMode, wrapText } from './report/colors.js';
+import { BANNER_WIDTH, bannerLines } from './report/mark.js';
+import { renderHuman } from './report/human.js';
+import { renderJson } from './report/json.js';
+import { renderSarif } from './report/sarif.js';
+import { renderHtmlReport } from './report/html-report.js';
+
+interface Args {
+  readonly command: string;
+  readonly positional: readonly string[];
+  readonly flags: ReadonlyMap<string, string | true>;
+}
+
+/**
+ * Flags that TAKE A VALUE, so `--explain xss` works as well as `--explain=xss`.
+ *
+ * Without this list the parser cannot tell `--explain xss` (one flag with a
+ * value) from `--json somefile.js` (a boolean flag followed by a path) - both
+ * are "a flag then a word". Every real CLI parser solves it the same way: by
+ * being told in advance which flags expect something after them.
+ */
+const VALUE_FLAGS = new Set([
+  'explain',
+  'only',
+  'exclude',
+  'min-severity',
+  'fail-on',
+  'depth',
+  'max-lines',
+  'report',
+  'report-name',
+  'report-by',
+  'report-note',
+]);
+
+function parseArgs(argv: readonly string[]): Args {
+  const positional: string[] = [];
+  const flags = new Map<string, string | true>();
+
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (token === undefined) continue;
+
+    if (token.startsWith('--')) {
+      const body = token.slice(2);
+      const eq = body.indexOf('=');
+      if (eq !== -1) {
+        flags.set(body.slice(0, eq), body.slice(eq + 1));
+        continue;
+      }
+      // `--explain xss`: consume the next token as this flag's value, but only
+      // if it exists and is not itself a flag.
+      const next = argv[i + 1];
+      if (VALUE_FLAGS.has(body) && next !== undefined && !next.startsWith('-')) {
+        flags.set(body, next);
+        i++;
+        continue;
+      }
+      flags.set(body, true);
+    } else if (token.startsWith('-') && token.length > 1) {
+      flags.set(token.slice(1), true);
+    } else {
+      positional.push(token);
+    }
+  }
+
+  return { command: positional[0] ?? '', positional: positional.slice(1), flags };
+}
+
+function flagString(args: Args, name: string): string | undefined {
+  const value = args.flags.get(name);
+  return typeof value === 'string' ? value : undefined;
+}
+
+const SEVERITIES = new Set(Object.keys(SEVERITY_ORDER));
+
+function parseSeverity(value: string | undefined, fallback: Severity): Severity {
+  if (!value) return fallback;
+  if (!SEVERITIES.has(value)) {
+    throw new Error(`unknown severity '${value}'. Use one of: ${[...SEVERITIES].join(', ')}`);
+  }
+  return value as Severity;
+}
+
+
+/* --------------------------------------------------------------- config -- */
+
+/**
+ * Per-project settings, so a repository can carry its own scan policy.
+ *
+ * Without this, every option lives in whichever command line last ran it -
+ * which means a CI job and a developer's terminal can silently disagree about
+ * what counts as a failure. A file in the repo is the only place both of them
+ * can read the same answer from.
+ *
+ * DELIBERATELY SMALL. Four keys, all of which already exist as flags, and no
+ * ability to enable, disable or reconfigure a RULE. A config that can turn
+ * rules off invites a repo to quietly switch off the ones it fails, and the
+ * finding disappears with no record. Suppression already has an honest form -
+ * `defuse:ignore <rule> - <reason>` on the line, which the report counts
+ * and lists.
+ *
+ * The command line always wins, so a person can override the file without
+ * editing it, and `--no-config` ignores it entirely.
+ */
+interface FileConfig {
+  readonly exclude?: readonly string[];
+  readonly only?: readonly string[];
+  readonly failOn?: string;
+  readonly minSeverity?: string;
+}
+
+const CONFIG_NAME = '.defuse.json';
+
+function loadConfig(startDir: string): { config: FileConfig; path: string | null } {
+  for (const dir of [startDir, process.cwd()]) {
+    const candidate = path.join(dir, CONFIG_NAME);
+    if (!existsSync(candidate)) continue;
+    try {
+      const parsed = JSON.parse(readFileSync(candidate, 'utf8')) as FileConfig;
+      return { config: parsed, path: candidate };
+    } catch (error) {
+      // A broken config is reported, never ignored. Silently falling back to
+      // defaults would mean a repo believing it has a policy that never ran.
+      console.error(
+        color.red(`error: ${candidate} is not valid JSON — ${(error as Error).message}`),
+      );
+      process.exit(2);
+    }
+  }
+  return { config: {}, path: null };
+}
+
+/* ------------------------------------------------------------------ help -- */
+
+function printHelp(): void {
+  const b = color.bold;
+  console.log(`
+${b('Defuse')} — honesty-first static application security testing
+${color.dim(`Signature matching plus data-flow verification, in all ${LANGUAGES.length} languages.`)}
+${color.dim('Flows are followed across functions and, where imports resolve, across files.')}
+
+${b('USAGE')}
+  defuse scan <path> [options]
+  defuse ast <file> [options]
+  defuse rules [--explain <rule-id>]
+  defuse doctor
+  defuse deps [path] [--json]   known advisories for pinned library versions.
+                                The one command that uses the network: it sends
+                                package names and versions (no code) to osv.dev.
+
+${b('SCAN OPTIONS')}
+  --full                    the long terminal report: reasoning and limits on every
+                            finding, the gauge arithmetic, OWASP table and every
+                            unchecked rule by name. Default is a short report.
+  --json                    machine-readable output (superset of the terminal report)
+  --sarif                   SARIF 2.1.0, for GitHub/GitLab code scanning. A
+                            flow-verified finding carries its traced path as a
+                            SARIF codeFlow; a signature-based one carries none,
+                            and every message opens with which it is.
+  --report=<file.html>      also write a report for the project owner: one
+                            self-contained HTML file (nothing loaded from the
+                            web) that prints to PDF - proven problems with their
+                            paths, what to review, what was cleared, and what
+                            was not checked
+  --report-name=<name>      the project name shown on that report
+  --report-by=<name>        "Prepared by" on that report
+  --report-note=<text>      one line under the report's header, e.g. that it is a sample or a draft
+  --compact                 with --json or --sarif, emit a single line
+  --min-severity=<level>    hide findings below this level in the terminal report
+                            (they remain in --json).  critical|high|medium|low|info
+  --fail-on=<level>         exit code 1 at or above this level. default: high
+                            use --fail-on=none to always exit 0
+  --only=<ids>              comma-separated rule ids, e.g. --only=sql-injection,xss
+  --exclude=<globs>         comma-separated paths to skip. A bare word matches any
+                            directory of that name; * and ** work as usual.
+                            e.g. --exclude=tests,vendor,**/*.min.js
+  --no-config               ignore .defuse.json
+  --deps                    also check pinned library versions against osv.dev.
+                            Off by default: it sends package names and versions
+                            (no code) off the machine. Same as defuse deps.
+  --show-suppressed         list findings silenced by defuse:ignore comments
+  --coverage-matrix         print the full rule x language support table
+  --no-cross-file           do not resolve imports; analyse each file alone.
+                            Faster, at the cost of every finding that crosses a
+                            module. It does NOT save memory - that was measured
+                            and was not true. Set DEFUSE_TREE_BUDGET_MB to trade
+                            memory for speed instead.
+  --ascii                   plain ASCII output - no box-drawing characters.
+                            Chosen automatically when redirecting on Windows.
+  --quiet                   suppress the banner and the per-file progress line
+
+${b('AST OPTIONS')}
+  --depth=<n>               how deep to print (default 12)
+  --anonymous               include punctuation/keyword nodes
+  --max-lines=<n>           truncate output (default 400)
+
+${b('ENVIRONMENT')}
+  DEFUSE_TREE_BUDGET_MB        how much memory syntax trees may hold before the
+                            least recently used one is freed and the file parsed
+                            again on demand. Default 1024. Lower it to finish on
+                            a small machine; raise it to go faster. The findings
+                            are the same either way - a test fails if they are
+                            not - and the report says when files were re-parsed.
+
+${b('EXIT CODES')}
+  0  nothing at or above the --fail-on threshold
+  1  findings at or above it
+  2  the tool failed
+
+${b('THE POINT OF THIS TOOL')}
+  Every finding is labelled ${color.yellow('signature-based')} or ${color.green('flow-verified')}.
+  ${color.yellow('signature-based')} = we matched a shape. Unverified, may be a false positive.
+  ${color.green('flow-verified')}   = we followed attacker data from its source into the sink
+                    and print every hop, so you can check the claim yourself.
+  The report also lists what was NOT checked. That is the product.
+
+${b('LICENCE')}
+  ${LICENCE_LINE}
+`);
+}
+
+/* ------------------------------------------------------------------ scan -- */
+
+async function commandScan(args: Args): Promise<number> {
+  const target = args.positional[0];
+  if (!target) {
+    console.error(color.red('error: scan needs a path.  usage: defuse scan <path>'));
+    return 2;
+  }
+  /* Extra paths used to be dropped in silence. `scan src ui docs` printed a
+   * clean, confident report for `src` and said nothing about the two
+   * directories it never opened - a scanner reporting on less than it was
+   * asked about, without saying so, which is the one failure mode this whole
+   * project is built to avoid. Refuse instead of quietly narrowing. */
+  if (args.positional.length > 1) {
+    console.error(
+      color.red(
+        `error: scan takes ONE path, but ${args.positional.length} were given ` +
+          `(${args.positional.join(', ')}).`,
+      ),
+    );
+    console.error(
+      '       Scan the common parent and narrow with --exclude=<globs>, ' +
+        'or run the scans separately.',
+    );
+    return 2;
+  }
+
+  let resolved: string;
+  try {
+    resolved = path.resolve(target);
+    await stat(resolved);
+  } catch {
+    console.error(color.red(`error: cannot read '${target}'`));
+    return 2;
+  }
+
+  const asJson = args.flags.has('json');
+  const asSarif = args.flags.has('sarif');
+  const quiet = args.flags.has('quiet') || asJson || asSarif;
+  // Decoration for a person at a terminal only: never in piped output, CI logs,
+  // or a window too narrow to hold it.
+  if (!quiet && process.stdout.isTTY && (process.stdout.columns ?? 0) >= BANNER_WIDTH) {
+    const purple = (s: string): string => (color.enabled ? `\x1b[38;2;121;44;247m${s}\x1b[39m` : s);
+    console.log(`\n${bannerLines().map(purple).join('\n')}`);
+  }
+  const configForOnly = args.flags.has('no-config')
+    ? ({} as FileConfig)
+    : loadConfig(statSync(resolved).isDirectory() ? resolved : path.dirname(resolved)).config;
+  const only =
+    flagString(args, 'only')?.split(',').map((s) => s.trim()).filter(Boolean) ??
+    configForOnly.only ??
+    [];
+
+  for (const id of only) {
+    if (!ALL_RULES.some((r) => r.id === id) && id !== RUNTIME_VERSION_RULE.id) {
+      console.error(
+        color.red(
+          `error: unknown rule '${id}'. Known: ${[...ALL_RULES.map((r) => r.id), RUNTIME_VERSION_RULE.id].join(', ')}`,
+        ),
+      );
+      return 2;
+    }
+  }
+
+  // The command line wins over the file; the file wins over the defaults.
+  const { config, path: configPath } = args.flags.has('no-config')
+    ? { config: {} as FileConfig, path: null }
+    : loadConfig(statSync(resolved).isDirectory() ? resolved : path.dirname(resolved));
+  if (configPath && !quiet) {
+    console.error(color.dim(`using ${path.relative(process.cwd(), configPath) || CONFIG_NAME}`));
+  }
+
+  const minSeverity = parseSeverity(
+    flagString(args, 'min-severity') ?? config.minSeverity,
+    'info',
+  );
+  const failOnRaw = flagString(args, 'fail-on') ?? config.failOn ?? 'high';
+  const failOn = failOnRaw === 'none' ? null : parseSeverity(failOnRaw, 'high');
+
+  const exclude =
+    flagString(args, 'exclude')?.split(',').map((s) => s.trim()).filter(Boolean) ??
+    config.exclude ??
+    [];
+
+  let result: ScanResult = await scan(resolved, {
+    only,
+    exclude,
+    noCrossFile: args.flags.has('no-cross-file'),
+    ...(quiet
+      ? {}
+      : {
+          // analyze() reports 2N steps for N files: every file is read once,
+          // then checked once. "scanning 3/4" for a two-file folder looked like
+          // a counting bug, so the two passes are named and counted per file.
+          onProgress: (done, total, file) => {
+            const files = total / 2;
+            const step = done > files ? `checking ${done - files}` : `reading ${done}`;
+            process.stderr.write(
+              `\r${color.dim(`${step}/${files} ${path.basename(file).slice(0, 40)}`.padEnd(70))}`,
+            );
+          },
+        }),
+  });
+
+  if (!quiet) process.stderr.write(`\r${' '.repeat(70)}\r`);
+
+  /*
+   * --deps: the one network call, added here rather than inside scan() so the
+   * browser page (which runs scan's engine) can never make it. The findings
+   * join the same list, so every report and SARIF carries them unchanged.
+   */
+  if (args.flags.has('deps')) {
+    if (!quiet) process.stderr.write(color.dim('sending package names and versions (no code) to api.osv.dev...\n'));
+    try {
+      const deps = await checkDependencies(
+        statSync(resolved).isDirectory() ? resolved : path.dirname(resolved),
+        (f) => path.relative(process.cwd(), f) || f,
+        exclude,
+      );
+      result = { ...result, findings: [...result.findings, ...deps.findings], dependencies: deps.report };
+    } catch (error) {
+      console.error(color.red(`error: --deps lookup failed, so the scan was not reported - ${(error as Error).message}`));
+      return 2;
+    }
+  }
+
+  /*
+   * The client report is WRITTEN BY THE TOOL, never piped. On Windows,
+   * PowerShell's `>` writes UTF-16, and a report redirected that way opens as
+   * noise in a browser - so the file is written here, as UTF-8, and the
+   * terminal says where it went.
+   */
+  const reportPath = flagString(args, 'report');
+  if (args.flags.has('report') && !reportPath) {
+    console.error(color.red('error: --report needs a file name, e.g. --report=report.html'));
+    return 2;
+  }
+  if (reportPath) {
+    const html = renderHtmlReport(result, {
+      generatedAt: new Date(),
+      root: path.relative(process.cwd(), resolved),
+      ...(flagString(args, 'report-name') ? { projectName: flagString(args, 'report-name')! } : {}),
+      ...(flagString(args, 'report-by') ? { preparedBy: flagString(args, 'report-by')! } : {}),
+      ...(flagString(args, 'report-note') ? { note: flagString(args, 'report-note')! } : {}),
+    });
+    writeFileSync(path.resolve(reportPath), html, 'utf8');
+    console.error(color.dim(`client report written to ${path.resolve(reportPath)}`));
+  }
+
+  if (asSarif) {
+    console.log(renderSarif(result, !args.flags.has('compact')));
+  } else if (asJson) {
+    console.log(renderJson(result, !args.flags.has('compact')));
+  } else {
+    console.log(
+      renderHuman(result, {
+        showSuppressed: args.flags.has('show-suppressed'),
+        showCoverageMatrix: args.flags.has('coverage-matrix'),
+        full: args.flags.has('full'),
+        minSeverity,
+        target: path.relative(process.cwd(), resolved) || '.',
+      }),
+    );
+  }
+
+  if (!failOn) return 0;
+  const triggering = result.findings.filter(
+    (f) => SEVERITY_ORDER[f.severity] >= SEVERITY_ORDER[failOn],
+  );
+  return triggering.length > 0 ? 1 : 0;
+}
+
+/* ------------------------------------------------------------------- ast -- */
+
+async function commandAst(args: Args): Promise<number> {
+  const target = args.positional[0];
+  if (!target) {
+    console.error(color.red('error: ast needs a file.  usage: defuse ast <file>'));
+    return 2;
+  }
+
+  useNodeGrammars();
+  const outcome = await parseFile(path.resolve(target));
+  if (outcome.status === 'skipped') {
+    console.error(color.red(`error: ${outcome.reason}`));
+    return 2;
+  }
+
+  const file = outcome.file;
+  console.log(
+    color.dim(
+      `${file.path}\n${file.language.displayName} (grammar: ${file.grammar}, detected by ${file.detectedBy})\n`,
+    ),
+  );
+  console.log(
+    dumpAst(file.root, {
+      includeAnonymous: args.flags.has('anonymous'),
+      maxDepth: Number(flagString(args, 'depth') ?? 12),
+      maxLines: Number(flagString(args, 'max-lines') ?? 400),
+    }),
+  );
+
+  if (file.parseIssues.length > 0) {
+    console.log(color.yellow(`\n${file.parseIssues.length} parse issue(s):`));
+    for (const issue of file.parseIssues) {
+      console.log(color.dim(`  ${issue.kind} at ${issue.line}:${issue.column}  ${issue.text}`));
+    }
+  }
+  return 0;
+}
+
+/* ----------------------------------------------------------------- rules -- */
+
+function commandRules(args: Args): number {
+  const explain = flagString(args, 'explain');
+
+  if (explain) {
+    const rule = ALL_RULES.find((r) => r.id === explain);
+    if (!rule) {
+      console.error(color.red(`error: no rule '${explain}'`));
+      return 2;
+    }
+    console.log(`\n${color.bold(rule.name)}  ${color.dim(`(${rule.id})`)}`);
+    console.log(color.dim(`${rule.cwe} · ${rule.owasp} · severity ${rule.severity}\n`));
+    console.log(`${color.cyan('In one line')}\n  ${wrapText(rule.summary, 86, '  ')}\n`);
+    console.log(`${color.cyan('The vulnerability')}\n  ${wrapText(rule.explanation, 86, '  ')}\n`);
+    console.log(`${color.green('How to fix it')}\n  ${wrapText(rule.fix, 86, '  ')}\n`);
+    console.log(`${color.yellow('What this rule cannot tell you')}\n  ${wrapText(rule.limitations, 86, '  ')}\n`);
+    console.log(color.cyan('Per-language support'));
+    for (const language of LANGUAGES) {
+      const support = rule.support[language.id];
+      const status = support?.status ?? 'not-implemented';
+      const mark = status === 'implemented' ? color.green(g('dotFull')) : status === 'partial' ? color.yellow(g('dotHalf')) : color.gray(g('dotEmpty'));
+      console.log(`  ${mark} ${language.displayName.padEnd(12)} ${color.dim(status)}`);
+      console.log(`    ${color.dim(wrapText(support?.note ?? 'no pattern for this language', 82, '    '))}`);
+    }
+    console.log('');
+    return 0;
+  }
+
+  const coverage = buildCoverageReport();
+  console.log(`\n${color.bold(`${ALL_RULES.length} rules`)} ${color.dim('· run with --explain <id> for the full write-up')}\n`);
+  for (const rule of ALL_RULES) {
+    const cells = coverage.matrix.filter((c) => c.ruleId === rule.id);
+    const marks = cells
+      .map((c) =>
+        c.status === 'implemented' ? color.green(g('dotFull')) : c.status === 'partial' ? color.yellow(g('dotHalf')) : color.gray('○'),
+      )
+      .join('');
+    console.log(`  ${marks}  ${color.bold(rule.id.padEnd(20))} ${color.dim(`${rule.cwe} · ${rule.severity}`)}`);
+    console.log(`         ${color.dim(rule.name)}`);
+  }
+  console.log(
+    color.dim(
+      `\n  legend: ${color.green(g('dotFull'))} implemented  ${color.yellow(g('dotHalf'))} partial  ${color.gray(g('dotEmpty'))} not implemented` +
+        `\n  columns: ${LANGUAGES.map((l) => l.id).join(' ')}\n`,
+    ),
+  );
+  return 0;
+}
+
+/* ------------------------------------------------------------------ deps -- */
+
+async function commandDeps(args: Args): Promise<number> {
+  const target = args.positional[0] ?? '.';
+  try {
+    await stat(target);
+  } catch {
+    console.error(color.red(`error: cannot read '${target}'`));
+    return 2;
+  }
+  const asJson = args.flags.has('json');
+  const { read, unread } = findLockfiles(path.resolve(target));
+  const rel = (f: string): string => path.relative(process.cwd(), f) || f;
+  const pinned = read.flatMap((r) => r.packages);
+
+  // Said BEFORE anything is sent, on stderr so --json stays clean.
+  console.error(
+    color.dim(
+      pinned.length
+        ? `Sending ${pinned.length} package names and versions (no code) to api.osv.dev...`
+        : 'No pinned packages found - nothing sent anywhere.',
+    ),
+  );
+  let result: Awaited<ReturnType<typeof queryOsv>>;
+  try {
+    result = pinned.length ? await queryOsv(pinned) : { hits: [], checked: 0, incomplete: [] };
+  } catch (error) {
+    console.error(color.red(`error: the advisory lookup failed, so nothing was checked - ${(error as Error).message}`));
+    return 2;
+  }
+
+  if (asJson) {
+    console.log(
+      JSON.stringify(
+        {
+          source: 'api.osv.dev',
+          checkedAt: new Date().toISOString(),
+          confidence: 'signature-based',
+          read: read.map((r) => ({ file: rel(r.file), packages: r.packages.length, skipped: r.skipped })),
+          notRead: unread.map(rel),
+          checked: result.checked,
+          incomplete: result.incomplete,
+          hits: result.hits.map((h) => ({ ...h, pkg: { ...h.pkg, file: rel(h.pkg.file) } })),
+        },
+        null,
+        args.flags.has('compact') ? 0 : 2,
+      ),
+    );
+    return result.hits.length ? 1 : 0;
+  }
+
+  const sev = (s: string): string =>
+    (s === 'critical' || s === 'high' ? color.red : s === 'medium' ? color.yellow : color.dim)(s.toUpperCase().padEnd(8));
+  console.log(`\n${color.bold('Dependency check')} ${color.dim('- known advisories for pinned library versions, from osv.dev')}\n`);
+  for (const r of read) console.log(`  read      ${rel(r.file)}  ${color.dim(`(${r.packages.length} packages)`)}`);
+  for (const f of unread) console.log(`  ${color.yellow('not read')}  ${rel(f)}  ${color.dim('- this lockfile format is not supported yet')}`);
+  if (!read.length && !unread.length) console.log(color.dim('  no lockfiles found (package-lock.json, composer.lock, requirements.txt, go.mod)'));
+
+  for (const h of result.hits) {
+    console.log(`\n  ${color.bold(`${h.pkg.name} ${h.pkg.version}`)}  ${color.dim(`${h.pkg.ecosystem} · ${rel(h.pkg.file)}`)}`);
+    for (const a of h.advisories) {
+      const ids = [a.id, ...a.aliases.filter((x) => x.startsWith('CVE-'))].join(' ');
+      const fix = a.fixed.length ? color.green(`fixed in ${a.fixed.join(', ')}`) : color.dim('no fixed version published');
+      console.log(`    ${sev(a.severity)} ${ids}\n             ${a.summary}\n             ${fix}`);
+    }
+  }
+
+  const skipped = read.flatMap((r) => r.skipped.map((s) => `${rel(r.file)}: ${s}`));
+  if (skipped.length || result.incomplete.length || unread.length) {
+    console.log(`\n${color.bold('  What this check did NOT read')}`);
+    for (const s of [...skipped, ...result.incomplete]) console.log(`    ${g('cross')} ${s}`);
+    for (const f of unread) console.log(`    ${g('cross')} ${rel(f)}: format not supported yet`);
+  }
+  console.log(
+    `\n  ${result.checked} distinct package versions checked, ${color.bold(String(result.hits.length))} with known advisories.\n` +
+      color.dim(
+        '  signature-based: an advisory matching a pinned version means the vulnerable code is\n' +
+          '  installed - not that this project ever calls it.\n',
+      ),
+  );
+  return result.hits.length ? 1 : 0;
+}
+
+/* ---------------------------------------------------------------- doctor -- */
+
+/**
+ * A self-check. The nastiest failure a scanner can have is a query with a
+ * typo'd node name: it compiles conceptually, matches nothing, and reports a
+ * clean scan forever. `doctor` compiles every query against every grammar so
+ * that failure is loud instead of silent.
+ */
+async function commandDoctor(): Promise<number> {
+  useNodeGrammars();
+  console.log(`\n${color.bold('Defuse self-check')}\n`);
+  let failures = 0;
+
+  try {
+    validateRegistry();
+    console.log(`  ${color.green(g('tick'))} rule registry satisfies the honesty contract`);
+  } catch (error) {
+    failures++;
+    console.log(`  ${color.red(g('cross'))} ${(error as Error).message}`);
+  }
+
+  await initEngine();
+  const { Query } = await import('web-tree-sitter');
+
+  for (const language of LANGUAGES) {
+    const grammars = [language.grammar, ...(language.dialects ?? []).map((d) => d.grammar)];
+    for (const grammar of grammars) {
+      try {
+        const loaded = await getLanguage(grammar);
+        for (const kind of ['calls', 'assignments'] as const) {
+          new Query(loaded, SHAPE_QUERY_SOURCES[kind][language.id]);
+        }
+        console.log(
+          `  ${color.green(g('tick'))} ${language.displayName.padEnd(12)} grammar '${grammar}' loads; shape queries compile`,
+        );
+      } catch (error) {
+        failures++;
+        console.log(
+          `  ${color.red(g('cross'))} ${language.displayName.padEnd(12)} grammar '${grammar}': ${(error as Error).message}`,
+        );
+      }
+    }
+  }
+
+  // Language detection sanity: every declared extension must map back correctly.
+  for (const language of LANGUAGES) {
+    const all = [...language.extensions, ...(language.dialects ?? []).flatMap((d) => d.extensions)];
+    for (const ext of all) {
+      const match = detectLanguage(`example${ext}`);
+      if (match?.spec.id !== language.id) {
+        failures++;
+        console.log(`  ${color.red(g('cross'))} extension ${ext} does not resolve to ${language.id}`);
+      }
+    }
+  }
+  if (failures === 0) console.log(`  ${color.green(g('tick'))} all declared extensions resolve to a language`);
+
+  console.log(
+    failures === 0
+      ? `\n  ${color.green('All checks passed.')}\n`
+      : `\n  ${color.red(`${failures} check(s) failed.`)}\n`,
+  );
+  return failures === 0 ? 0 : 1;
+}
+
+/* ------------------------------------------------------------------ main -- */
+
+async function main(): Promise<number> {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.flags.has('ascii')) setAsciiMode(true);
+
+  if (args.flags.has('version') || args.flags.has('v')) {
+    console.log(buildCoverageReport().engine.version);
+    console.log(LICENCE_SPDX);
+    return 0;
+  }
+  if (args.command === '' || args.flags.has('help') || args.flags.has('h')) {
+    printHelp();
+    return args.command === '' ? 2 : 0;
+  }
+
+  switch (args.command) {
+    case 'scan':
+      return commandScan(args);
+    case 'ast':
+      return commandAst(args);
+    case 'rules':
+      return commandRules(args);
+    case 'doctor':
+      return commandDoctor();
+    case 'deps':
+      return commandDeps(args);
+    default:
+      console.error(color.red(`error: unknown command '${args.command}'`));
+      printHelp();
+      return 2;
+  }
+}
+
+main()
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((error: unknown) => {
+    const message = (error as Error).message ?? String(error);
+
+    /*
+     * `Aborted()` is the WebAssembly heap giving up, and on its own it tells
+     * the reader nothing at all.
+     *
+     * Every syntax tree tree-sitter builds lives in a WASM heap that JavaScript
+     * garbage collection cannot reach, and nothing frees them during a scan
+     * because cross-file tracing has to be able to resolve into any file at any
+     * time. Memory therefore grows with total SOURCE BYTES - measured at 60-70x
+     * - and past roughly 120MB on an 8GB machine the heap aborts or the
+     * operating system kills the process.
+     *
+     * The failure is total: no findings, no partial report, nothing. Somebody
+     * hitting this deserves to know what happened and what to do instead of a
+     * bare `Aborted()`, which is what they got the first time it happened to a
+     * real user scanning VS Code.
+     */
+    if (/Aborted|Maximum call stack|heap out of memory|allocation failed/i.test(message)) {
+      console.error(color.red('\nout of memory - the scan did not finish and produced no report.'));
+      console.error(
+        color.dim(
+          '\n  Memory grows with the total SIZE of the source, not the file count: about\n' +
+            '  60-70x the bytes on disk, because every parsed syntax tree is held for the\n' +
+            '  whole scan so cross-file tracing can resolve into it. On an 8GB machine that\n' +
+            '  is a ceiling of roughly 120MB of source.\n' +
+            '\n  Scan one package at a time instead:\n' +
+            '    scan src/vs/base      scan src/vs/platform      scan src/vs/editor\n' +
+            '\n  --exclude=tests,node_modules also helps, and node --max-old-space-size=8192\n' +
+            '  buys some headroom. This is a known limitation, recorded in the report\'s\n' +
+            '  "not implemented" list, and it needs a redesign rather than a flag.',
+        ),
+      );
+      if (process.env['NS1_DEBUG']) console.error((error as Error).stack);
+      process.exitCode = 2;
+      return;
+    }
+
+    console.error(color.red(`\ninternal error: ${message}`));
+    if (process.env['NS1_DEBUG']) console.error((error as Error).stack);
+    process.exitCode = 2;
+  });