@blundergoat/gruff-ts 0.1.0

package/src/class-rules.ts

@@ -0,0 +1,326 @@
+// Class + naming-inventory rules: exported-declaration docs, class/file-name mismatch,
+// public-property + readonly candidates, inconsistent casing, acronym case, interface fields.
+// Pulls the declaration walkers and casing helpers out of cli.ts so the orchestrator just calls
+// the entry points.
+import { type FunctionBlock, parameterNames } from "./blocks.ts";
+import { type ExportedDeclaration, exportedDeclarations, pushMissingPublicDocFinding } from "./doc-rules.ts";
+import { type SourceFile } from "./discovery.ts";
+import { makeFinding } from "./findings.ts";
+import { fileBaseName, finding, normalizedIdentifier } from "./findings-helpers.ts";
+import { pushAbbreviationAt, pushBooleanPrefixAt, pushNegativeBooleanAt } from "./naming-pushers.ts";
+import { byteLine } from "./text-scans.ts";
+import type { Config, Finding } from "./types.ts";
+
+// One identifier observation. `line` is the declaration line in the original source so the casing
+// and acronym rules can report a stable, reproducible location.
+interface DeclaredIdentifier {
+  name: string;
+  line: number;
+}
+
+// Aggregates `const`/`let`/`var` declarations, callable parameters, and interface fields into a
+// single de-duplicated list. The naming rules walk this once instead of re-parsing the file.
+export function collectDeclaredIdentifiers(source: string, codeSource: string, blocks: FunctionBlock[]): DeclaredIdentifier[] {
+  const inventory: DeclaredIdentifier[] = [];
+  const seen = new Set<string>();
+  const push = (name: string, line: number): void => {
+    if (!name) return;
+    const key = `${name}@${line}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    inventory.push({ name, line });
+  };
+
+  for (const match of codeSource.matchAll(/\b(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][A-Za-z0-9_$]*)/g)) {
+    push(match[1] ?? "", byteLine(source, match.index ?? 0));
+  }
+  for (const block of blocks) {
+    for (const parameter of parameterNames(block.params)) {
+      push(parameter.name, block.declarationLine);
+    }
+  }
+  for (const fieldMatch of collectInterfaceFieldDeclarations(source, codeSource)) {
+    push(fieldMatch.name, fieldMatch.line);
+  }
+  return inventory;
+}
+
+// Walks every interface body line and matches the field declaration regex. Used both for the
+// naming inventory (above) and for the per-field interface rules (boolean prefix, abbreviation).
+function collectInterfaceFieldDeclarations(source: string, codeSource: string): DeclaredIdentifier[] {
+  const fieldRegex = /^[ \t]*(?:readonly\s+)?([A-Za-z_$][A-Za-z0-9_$]*)\??\s*:/;
+  const out: DeclaredIdentifier[] = [];
+  for (const { lineIndex, sourceLine } of walkInterfaceBodyLines(source, codeSource)) {
+    const name = sourceLine.match(fieldRegex)?.[1] ?? "";
+    if (name) out.push({ name, line: lineIndex + 1 });
+  }
+  return out;
+}
+
+// Strips separators and digits so `userId`, `user_id`, and `userID` all collapse to `userid`.
+// Two names sharing this key but differing in original form are the casing-drift signal.
+function casingCanonicalKey(name: string): string {
+  return name.toLowerCase().replace(/[_\-0-9]/g, "");
+}
+
+/*
+ * Groups identifiers by their canonical key and reports the second-seen variant whenever two or
+ * more spellings exist. The "second variant" anchor keeps the stable fingerprint on the diverging
+ * identifier rather than the original - useful when the original form is the project convention.
+ */
+export function analyseInconsistentCasing(file: SourceFile, inventory: DeclaredIdentifier[], findings: Finding[]): void {
+  const groups = new Map<string, DeclaredIdentifier[]>();
+  for (const entry of inventory) {
+    const key = casingCanonicalKey(entry.name);
+    if (!key) continue;
+    const list = groups.get(key) ?? [];
+    list.push(entry);
+    groups.set(key, list);
+  }
+  for (const [, entries] of groups) {
+    const surfaces = new Set(entries.map((entry) => entry.name));
+    if (surfaces.size < 2) continue;
+    const sorted = [...entries].sort((a, b) => a.line - b.line);
+    const second = sorted.find((entry, index) => index > 0 && entry.name !== sorted[0]?.name);
+    if (!second) continue;
+    findings.push(
+      makeFinding({
+        ruleId: "naming.inconsistent-casing",
+        message: `Identifier \`${second.name}\` shares a canonical key with \`${sorted[0]?.name}\` in the same file.`,
+        filePath: file.displayPath,
+        line: second.line,
+        severity: "advisory",
+        pillar: "naming",
+        confidence: "medium",
+        symbol: second.name,
+        remediation: "Choose one form and use it consistently within the file.",
+        metadata: { variants: [...surfaces].sort() },
+      }),
+    );
+  }
+}
+
+// Splits camelCase, PascalCase, snake_case, and kebab-case into tokens. The regex preserves
+// uppercase runs as a single token so the acronym detector sees `URL` and `url` as the same word.
+function tokensForAcronymCheck(name: string): string[] {
+  const split = name.split(/[_\-]+/).filter(Boolean);
+  const tokens: string[] = [];
+  for (const part of split) {
+    const matches = part.match(/[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z0-9]+|[A-Z]+/g);
+    if (matches) tokens.push(...matches);
+    else tokens.push(part);
+  }
+  return tokens;
+}
+
+// Three-bucket classification used to detect when one project uses both `URL` and `Url` styles -
+// the rule flags drift when two of the three buckets are seen for the same acronym in one file.
+function acronymCaseClass(token: string): "upper" | "lower" | "title" {
+  if (token === token.toUpperCase()) return "upper";
+  if (token === token.toLowerCase()) return "lower";
+  return "title";
+}
+
+/*
+ * Reports when an acronym from `config.knownAcronyms` appears as all-caps plus another case form.
+ * The all-caps gate exists because lower/title-only forms like `apiToken` beside `googleApiKey`
+ * are idiomatic enough to avoid noisy findings. Like `analyseInconsistentCasing`, the finding
+ * anchors on the second occurrence so the stable fingerprint sticks to the divergence.
+ */
+export function analyseAcronymCase(file: SourceFile, inventory: DeclaredIdentifier[], config: Config, findings: Finding[]): void {
+  const observed = new Map<string, Map<string, { name: string; line: number }>>();
+  for (const entry of inventory) {
+    recordAcronymCases(observed, config, entry);
+  }
+  for (const [acronym, cases] of observed) {
+    pushAcronymCaseFinding(file, acronym, cases, findings);
+  }
+}
+
+// Adds one identifier's acronym tokens to the observed case map, skipping fixture-only constants.
+function recordAcronymCases(observed: Map<string, Map<string, { name: string; line: number }>>, config: Config, entry: DeclaredIdentifier): void {
+  if (isFixtureIdentifier(entry.name)) {
+    return;
+  }
+  for (const token of tokensForAcronymCheck(entry.name)) {
+    const lower = token.toLowerCase();
+    if (!config.knownAcronyms.has(lower)) continue;
+    const cases = observed.get(lower) ?? new Map();
+    const caseKey = acronymCaseClass(token);
+    if (!cases.has(caseKey)) cases.set(caseKey, { name: entry.name, line: entry.line });
+    observed.set(lower, cases);
+  }
+}
+
+// Reports the stable acronym-case finding only after the all-caps-vs-other drift gate passes.
+function pushAcronymCaseFinding(file: SourceFile, acronym: string, cases: Map<string, { name: string; line: number }>, findings: Finding[]): void {
+  if (!shouldReportAcronymCase(cases)) {
+    return;
+  }
+  const occurrences = [...cases.values()].sort((a, b) => a.line - b.line);
+  const second = occurrences[1];
+  if (!second) {
+    return;
+  }
+  findings.push(
+    makeFinding({
+      ruleId: "naming.acronym-case",
+      message: `Acronym \`${acronym.toUpperCase()}\` appears in multiple cases in this file.`,
+      filePath: file.displayPath,
+      line: second.line,
+      severity: "advisory",
+      pillar: "naming",
+      confidence: "medium",
+      symbol: second.name,
+      remediation: "Use one casing for each acronym throughout the file.",
+      metadata: { acronym: acronym.toUpperCase(), variants: [...cases.keys()].sort() },
+    }),
+  );
+}
+
+// Requires an upper-case acronym plus a different case; lower/title-only mixes stay quiet.
+function shouldReportAcronymCase(cases: Map<string, { name: string; line: number }>): boolean {
+  return cases.has("upper") && cases.size >= 2;
+}
+
+// Fixture constants often use SCREAMING_SNAKE vendor token names that should not force local
+// camelCase variables to adopt the same acronym style.
+function isFixtureIdentifier(name: string): boolean {
+  return /(?:^|[_-])fixture(?:[_-]|$)/i.test(name);
+}
+
+/*
+ * Walks every interface field and runs three checks per field: abbreviation, boolean prefix,
+ * negative boolean. The stable ordering matches `pushAbbreviationAt` → `pushBooleanPrefixAt` →
+ * `pushNegativeBooleanAt` so multiple findings on one field surface in a deterministic sequence.
+ */
+export function analyseInterfaceFields(file: SourceFile, source: string, codeSource: string, config: Config, findings: Finding[]): void {
+  const fieldRegex = /^[ \t]*(?:readonly\s+)?([A-Za-z_$][A-Za-z0-9_$]*)\??\s*:\s*([^;]+)/;
+  for (const { lineIndex, sourceLine } of walkInterfaceBodyLines(source, codeSource)) {
+    const match = sourceLine.match(fieldRegex);
+    const name = match?.[1] ?? "";
+    if (!name) continue;
+    pushAbbreviationAt(file, lineIndex + 1, name, config, findings, "interface-field");
+    if (/^\s*boolean\b/.test(match?.[2] ?? "")) {
+      pushBooleanPrefixAt(file, lineIndex + 1, name, config, findings, "interface-field");
+      pushNegativeBooleanAt(file, lineIndex + 1, name, config, findings, "interface-field");
+    }
+  }
+}
+
+const INTERFACE_HEADER_REGEX = /\b(?:export\s+)?(?:interface\s+[A-Za-z_$][A-Za-z0-9_$]*(?:\s*<[^>]*>)?(?:\s+extends\s+[^{]+)?|type\s+[A-Za-z_$][A-Za-z0-9_$]*(?:\s*<[^>]*>)?\s*=\s*)\s*\{/g;
+
+function* walkInterfaceBodyLines(source: string, codeSource: string): Generator<{ lineIndex: number; sourceLine: string }> {
+  const codeLines = codeSource.split(/\r?\n/);
+  const sourceLines = source.split(/\r?\n/);
+  for (const header of codeSource.matchAll(INTERFACE_HEADER_REGEX)) {
+    const headerEnd = (header.index ?? 0) + header[0].length;
+    if (codeSource.slice(headerEnd, headerEnd + 30).trimStart().startsWith("[")) {
+      continue;
+    }
+    const headerLineIndex = byteLine(source, headerEnd - 1) - 1;
+    const headerLine = codeLines[headerLineIndex] ?? "";
+    let depth = 1 + countBraceChange(headerLine.slice(headerLine.lastIndexOf("{") + 1));
+    for (let lineIndex = headerLineIndex + 1; depth > 0 && lineIndex < codeLines.length; lineIndex += 1) {
+      const codeLine = codeLines[lineIndex] ?? "";
+      if (depth === 1) {
+        yield { lineIndex, sourceLine: sourceLines[lineIndex] ?? "" };
+      }
+      depth += countBraceChange(codeLine);
+    }
+  }
+}
+
+// Net brace delta (`{` minus `}`) for a slice of text. Used by the interface-body walker to track
+// nesting depth without parsing the source twice.
+function countBraceChange(text: string): number {
+  let delta = 0;
+  for (const character of text) {
+    if (character === "{") {
+      delta += 1;
+    } else if (character === "}") {
+      delta -= 1;
+    }
+  }
+  return delta;
+}
+
+/*
+ * Three class-pillar rules in their stable, deterministic emission order: exported-declaration
+ * docs and file-name mismatch, public-property, readonly candidates.
+ */
+export function analyseClassRules(file: SourceFile, source: string, codeSource: string, findings: Finding[]): void {
+  analyseExportedDeclarations(file, source, codeSource, findings);
+  analysePublicProperties(file, source, codeSource, findings);
+  analyseReadonlyCandidates(file, source, codeSource, findings);
+}
+
+/*
+ * Two rules per exported declaration. Both fire from one walk so the file isn't re-scanned for
+ * each rule. Reports the stable `docs.missing-public-doc` and `naming.class-file-mismatch`
+ * findings per declaration.
+ */
+function analyseExportedDeclarations(file: SourceFile, source: string, codeSource: string, findings: Finding[]): void {
+  for (const declaration of exportedDeclarations(source, codeSource)) {
+    pushMissingPublicDocFinding(file, source, declaration, findings);
+    pushClassFileMismatchFinding(file, declaration, findings);
+  }
+}
+
+/*
+ * Compares normalised forms (lowercased, no underscores) so `UserProfile` and `user-profile.ts`
+ * match. Reports the stable `naming.class-file-mismatch` finding when the exported class diverges
+ * from the file name.
+ */
+function pushClassFileMismatchFinding(file: SourceFile, declaration: ExportedDeclaration, findings: Finding[]): void {
+  const fileName = fileBaseName(file.displayPath);
+  if (declaration.kind !== "class" || normalizedIdentifier(declaration.name) === normalizedIdentifier(fileName)) {
+    return;
+  }
+  findings.push(
+    makeFinding({
+      ruleId: "naming.class-file-mismatch",
+      message: `Exported class \`${declaration.name}\` does not match file name \`${fileName}\`.`,
+      filePath: file.displayPath,
+      line: declaration.line,
+      severity: "advisory",
+      pillar: "naming",
+      confidence: "medium",
+      symbol: declaration.name,
+      remediation: "Rename the class or file so the primary export is easy to locate.",
+      metadata: { className: declaration.name, fileName },
+    }),
+  );
+}
+
+// Targets `public foo =` and `public foo:` patterns. The rule message recommends `readonly` or
+// accessors because both preserve the field's invariant better than a raw public field, and
+// reports each match as a stable `modernisation.public-property` finding.
+function analysePublicProperties(file: SourceFile, source: string, codeSource: string, findings: Finding[]): void {
+  const publicProperty = /\bpublic\s+[A-Za-z_$][A-Za-z0-9_$]*\s*[=:]/g;
+  for (const match of codeSource.matchAll(publicProperty)) {
+    findings.push(finding({ ruleId: "modernisation.public-property", message: "Public class property exposes representation; prefer readonly or accessors when invariants matter.", file, line: byteLine(source, match.index ?? 0), severity: "advisory", pillar: "modernisation" }));
+  }
+}
+
+// Visibility-modifier fields without `readonly`. The negative lookahead skips already-readonly
+// properties; each remaining match reports a stable `modernisation.readonly-property-candidate`.
+function analyseReadonlyCandidates(file: SourceFile, source: string, codeSource: string, findings: Finding[]): void {
+  const readonlyCandidate = /\b(?:public|private|protected)\s+(?!readonly\b)([A-Za-z_$][A-Za-z0-9_$]*)\s*:\s*[^;=\n]+;/g;
+  for (const match of codeSource.matchAll(readonlyCandidate)) {
+    const name = match[1] ?? "";
+    findings.push(
+      makeFinding({
+        ruleId: "modernisation.readonly-property-candidate",
+        message: `Property \`${name}\` can be marked readonly if it is only assigned during construction.`,
+        filePath: file.displayPath,
+        line: byteLine(source, match.index ?? 0),
+        severity: "advisory",
+        pillar: "modernisation",
+        confidence: "medium",
+        symbol: name,
+        remediation: "Mark the property readonly when mutation is not part of the type contract.",
+      }),
+    );
+  }
+}

package/src/cli-program.ts

@@ -0,0 +1,326 @@
+// Commander CLI shell wiring that keeps option normalization and stdout behavior outside the analyzer.
+import { Command, Help } from "commander";
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { performance } from "node:perf_hooks";
+import { DEFAULT_BASELINE } from "./baseline.ts";
+import { VERSION } from "./constants.ts";
+import { startDashboard } from "./dashboard.ts";
+import { renderReport, renderSummary } from "./report-renderers.ts";
+import { completionShell, renderCompletionScript, renderConsoleList, renderRuleList, type RuleListFormat } from "./rule-list.ts";
+import { exitFor } from "./scoring.ts";
+import type { AnalysisOptions, AnalysisReport } from "./types.ts";
+
+type AnalyseRunner = (options: AnalysisOptions) => AnalysisReport;
+
+// The `report` command intentionally rejects `--baseline` because its output is meant to reflect
+// raw findings; this flag lets `normalizeOptions` enforce that without per-command branching.
+interface NormalizeContext {
+  shouldAllowBaselineFlag: boolean;
+}
+
+// Honours `--silent`/`--quiet` before writing to stdout. Always appends a trailing newline so piped
+// callers (e.g., `gruff-ts analyse | jq`) see a complete line even when a renderer forgot one.
+function writeCommandOutput(program: Command, output: string): void {
+  if (outputSuppressed(program)) {
+    return;
+  }
+  process.stdout.write(output.endsWith("\n") ? output : `${output}\n`);
+}
+
+// `--silent` and `--quiet` both suppress non-error stdout - they are intentionally treated the same
+// here because Commander exposes them as independent flags but the CLI's contract is uniform.
+function outputSuppressed(program: Command): boolean {
+  const options = program.opts() as { quiet?: boolean; silent?: boolean };
+  return options.quiet === true || options.silent === true;
+}
+
+// Three-state ANSI resolution: explicit `--ansi` forces colour, explicit `--no-ansi` forbids it,
+// otherwise autodetect from TTY. Required because pipelines and CI logs would otherwise eat colour codes.
+function ansiEnabled(program: Command): boolean {
+  const options = program.opts() as { ansi?: boolean };
+  if (options.ansi === true) {
+    return true;
+  }
+  if (options.ansi === false) {
+    return false;
+  }
+  return process.stdout.isTTY === true;
+}
+
+// `runAnalyse` is injected rather than imported to keep `cli-program.ts` off the analyser's
+// dependency graph; see `.goat-flow/lessons/verification.md` on the original cli.ts ↔ cli-program.ts cycle.
+export function buildProgram(runAnalyse: AnalyseRunner): Command {
+  const program = new Command();
+  configureRootProgram(program);
+  registerAnalyseCommand(program, runAnalyse);
+  registerCompletionCommand(program);
+  registerDashboardCommand(program, runAnalyse);
+  registerListCommand(program);
+  registerListRulesCommand(program);
+  registerReportCommand(program, runAnalyse);
+  registerSummaryCommand(program, runAnalyse);
+  return program;
+}
+
+// Adds the Symfony-style global flags (`--silent`, `--quiet`, `--ansi`, `--no-interaction`, `-v`)
+// and replaces the default help formatter so the bare root command lists the catalogue instead of
+// Commander's auto-generated usage block.
+function configureRootProgram(program: Command): void {
+  program
+    .name("gruff-ts")
+    .usage("command [options] [arguments]")
+    .helpOption("-h, --help", "Display help for the given command. When no command is given display help for the list command")
+    .version(VERSION, "-V, --version", "Display this application version")
+    .option("--silent", "Do not output any message")
+    .option("-q, --quiet", "Only errors are displayed. All other output is suppressed")
+    .option("--ansi", "Force ANSI output")
+    .option("--no-ansi", "Disable ANSI output")
+    .option("-n, --no-interaction", "Do not ask any interactive question")
+    .option("-v, --verbose", "Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug", (_value, previous: number) => previous + 1, 0)
+    .addHelpCommand("help [command]", "Display help for a command")
+    .showHelpAfterError()
+    .configureHelp({
+
+      // Custom root help: the bare `gruff-ts` invocation prints the Symfony-style command catalogue;
+      // subcommand help still uses Commander's default formatter via `rootHelpText`.
+      formatHelp(command, helper) {
+        return rootHelpText(program, command, helper);
+      },
+    })
+    .action(() => {
+      writeCommandOutput(program, renderConsoleList(ansiEnabled(program)));
+    });
+}
+
+// Returns the catalogue view when the user asked for root help; defers to Commander's default
+// formatter for subcommand help. `showGlobalOptions = true` so the global flags surface there too.
+function rootHelpText(program: Command, command: Command, helper: Help): string {
+  if (command === program) {
+    return renderConsoleList(ansiEnabled(program));
+  }
+  const defaultHelp = new Help();
+  defaultHelp.showGlobalOptions = true;
+  if (helper.helpWidth !== undefined) {
+    defaultHelp.helpWidth = helper.helpWidth;
+  }
+  if (helper.minWidthToWrap !== undefined) {
+    defaultHelp.minWidthToWrap = helper.minWidthToWrap;
+  }
+  return defaultHelp.formatHelp(command, defaultHelp);
+}
+
+// The primary entry point. Sets `process.exitCode` (not `process.exit`) so async writers in the
+// renderer get a chance to flush before Node tears down. Default fail-on is `error`, matching CI.
+function registerAnalyseCommand(program: Command, runAnalyse: AnalyseRunner): void {
+  program
+    .command("analyse")
+    .description("Run gruff analysis.")
+    .argument("[paths...]", "Files or directories to analyse.")
+    .option("--config <path>", "Path to a gruff YAML config file.")
+    .option("--no-config", "Skip auto-applying the default .gruff-ts.yaml file for this run.")
+    .option("--format <format>", "Output format: text, json, html, markdown, github, hotspot, or sarif.", "text")
+    .option("--fail-on <severity>", "Finding severity that fails the run: advisory, warning, error, or none.", "error")
+    .option("--include-ignored", "Include files under default and Git ignored paths; config ignores still apply.")
+    .option("--diff [mode]", "Filter findings to changed files. Use working-tree, staged, unstaged, or a base ref.")
+    .option("--history-file <path>", "Append score trend history to this JSON file.")
+    .option("--baseline [path]", "Suppress findings that match a gruff baseline JSON file.")
+    .option("--generate-baseline [path]", "Write current findings to a gruff baseline JSON file.")
+    .option("--no-baseline", "Skip auto-applying the default baseline file for this run.")
+    .action((paths: string[], rawOptions: Record<string, unknown>) => {
+      const options = normalizeOptions(paths, rawOptions, { shouldAllowBaselineFlag: true });
+      const report = runAnalyse(options);
+      writeCommandOutput(program, renderReport(report, options.format));
+      process.exitCode = exitFor(report, options.failOn);
+    });
+}
+
+// Emits the static completion script for the requested shell. Does not touch the filesystem or
+// run a scan - callers pipe the output into their shell config themselves.
+function registerCompletionCommand(program: Command): void {
+  program
+    .command("completion")
+    .description("Dump the shell completion script")
+    .argument("[shell]", "Shell to generate completion for: bash, zsh, or fish.", "bash")
+    .action((shell: string) => {
+      writeCommandOutput(program, renderCompletionScript(completionShell(shell)));
+    });
+}
+
+// Wires the `dashboard` subcommand to `startDashboard`. Defaults bind to loopback (127.0.0.1:8767)
+// because the dashboard accepts a `projectRoot` query parameter and would otherwise be unauthenticated.
+function registerDashboardCommand(program: Command, runAnalyse: AnalyseRunner): void {
+  program
+    .command("dashboard")
+    .description("Serve the local gruff dashboard.")
+    .option("--host <host>", "Host to bind.", "127.0.0.1")
+    .option("--port <port>", "Port to bind.", "8767")
+    .option("--project-root <path>", "Default project root.", ".")
+    .action((rawOptions: Record<string, unknown>) => {
+      startDashboard(String(rawOptions.host ?? "127.0.0.1"), Number(rawOptions.port ?? 8767), resolve(String(rawOptions.projectRoot ?? ".")), runAnalyse, !outputSuppressed(program));
+    });
+}
+
+// Mirrors the bare-root help output. Exists so users coming from Symfony's console conventions
+// can run `gruff-ts list` the way they expect.
+function registerListCommand(program: Command): void {
+  program
+    .command("list")
+    .description("List commands")
+    .action(() => {
+      writeCommandOutput(program, renderConsoleList(ansiEnabled(program)));
+    });
+}
+
+// Read-only catalogue dump. JSON is the canonical form consumed by docs builds; text is for humans.
+// Anything other than `json` falls back to `text` rather than erroring so old aliases keep working.
+function registerListRulesCommand(program: Command): void {
+  program
+    .command("list-rules")
+    .description("List gruff rule metadata.")
+    .option("--format <format>", "Output format: text or json.", "text")
+    .action((rawOptions: Record<string, unknown>) => {
+      const format: RuleListFormat = rawOptions.format === "json" ? "json" : "text";
+      writeCommandOutput(program, renderRuleList(format));
+    });
+}
+
+// `report` differs from `analyse` in two ways: default format is `html`, and baseline suppression is
+// disallowed (`shouldAllowBaselineFlag: false`) because reports are meant to capture the raw scan, not a
+// filtered view. Writes the rendered output to `--output` when provided; otherwise to stdout.
+function registerReportCommand(program: Command, runAnalyse: AnalyseRunner): void {
+  program
+    .command("report")
+    .description("Render a gruff report to stdout or a file.")
+    .argument("[paths...]", "Files or directories to analyse.")
+    .option("--format <format>", "Report format: html or json.", "html")
+    .option("--output <path>", "Write report to a file.")
+    .option("--config <path>", "Path to a gruff YAML config file.")
+    .option("--no-config", "Skip auto-applying the default .gruff-ts.yaml file for this run.")
+    .option("--fail-on <severity>", "Finding severity that fails the run.", "none")
+    .option("--include-ignored", "Include files under default and Git ignored paths; config ignores still apply.")
+    .option("--no-baseline", "Skip auto-applying the default baseline file for this run.")
+    .action((paths: string[], rawOptions: Record<string, unknown>) => {
+      const format = rawOptions.format === "json" ? "json" : "html";
+      const options = normalizeOptions(paths, { ...rawOptions, format }, { shouldAllowBaselineFlag: false });
+      const report = runAnalyse(options);
+      const rendered = renderReport(report, format);
+      if (typeof rawOptions.output === "string") {
+        writeFileSync(rawOptions.output, rendered);
+      } else {
+        writeCommandOutput(program, rendered);
+      }
+      process.exitCode = exitFor(report, options.failOn);
+    });
+}
+
+// Same analyser run as `analyse` but renders only the pillar/rule/offender digest. Format is locked
+// to `text` because the summary shape is intentionally not part of the JSON report contract.
+function registerSummaryCommand(program: Command, runAnalyse: AnalyseRunner): void {
+  program
+    .command("summary")
+    .description(
+      "Print a compact digest of a scan: per-pillar finding counts, top rules, and top file offenders. Runs the analyser once and renders only the summary; no per-finding spam.",
+    )
+    .argument("[paths...]", "Files or directories to analyse.")
+    .option("--config <path>", "Path to a gruff YAML config file.")
+    .option("--no-config", "Skip auto-applying the default .gruff-ts.yaml file for this run.")
+    .option("--fail-on <severity>", "Finding severity that fails the run: advisory, warning, error, or none.", "error")
+    .option("--include-ignored", "Include files under default and Git ignored paths; config ignores still apply.")
+    .option("--diff [mode]", "Filter findings to changed files. Use working-tree, staged, unstaged, or a base ref.")
+    .option("--history-file <path>", "Append score trend history to this JSON file.")
+    .option("--baseline [path]", "Suppress findings that match a gruff baseline JSON file.")
+    .option("--generate-baseline [path]", "Write current findings to a gruff baseline JSON file.")
+    .option("--no-baseline", "Skip auto-applying the default baseline file for this run.")
+    .action((paths: string[], rawOptions: Record<string, unknown>) => {
+      const startedAt = performance.now();
+      const options = normalizeOptions(paths, { ...rawOptions, format: "text" }, { shouldAllowBaselineFlag: true });
+      const report = runAnalyse(options);
+      const elapsedMs = performance.now() - startedAt;
+      writeCommandOutput(program, renderSummary(report, elapsedMs, summaryPathLabel(options.paths, report.run.projectRoot)));
+      process.exitCode = exitFor(report, options.failOn);
+    });
+}
+
+// Summary output should name the scanned operand, not merely the process cwd used to run gruff-ts.
+function summaryPathLabel(paths: string[], projectRoot: string): string {
+  if (paths.length === 0) {
+    return projectRoot;
+  }
+  return paths.map((path) => resolve(path)).join(", ");
+}
+
+// Single source of truth for translating Commander's loose option bag into the strict
+// `AnalysisOptions` shape that drives baseline matching. The fingerprint contract is the invariant:
+// two CLI invocations producing identical AnalysisOptions must produce identical, stable findings -
+// adding new fields here without folding them into that hash is a deterministic-output regression.
+function normalizeOptions(paths: string[], rawOptions: Record<string, unknown>, context: NormalizeContext): AnalysisOptions {
+  const format = stringChoice(rawOptions.format, ["text", "json", "html", "markdown", "github", "hotspot", "sarif"], "text");
+  const failOn = stringChoice(rawOptions.failOn, ["none", "advisory", "warning", "error"], "error");
+  const baselineValue = rawOptions.baseline;
+  const shouldSkipBaseline =
+    !context.shouldAllowBaselineFlag ||
+    baselineValue === false ||
+    rawOptions.noBaseline === true;
+  return {
+    paths,
+    ...configOption(rawOptions),
+    shouldSkipConfig:
+      rawOptions.config === false ||
+      rawOptions.noConfig === true,
+    format,
+    failOn,
+    shouldIncludeIgnored: rawOptions.includeIgnored === true,
+    ...diffOption(rawOptions),
+    ...historyFileOption(rawOptions),
+    ...baselineOption(baselineValue, context),
+    ...generateBaselineOption(rawOptions),
+    shouldSkipBaseline,
+  };
+}
+
+// Conditional spreads (not `config: undefined`) because `AnalysisOptions` runs under
+// `exactOptionalPropertyTypes` - the absent and `undefined` cases are not interchangeable.
+function configOption(rawOptions: Record<string, unknown>): Partial<Pick<AnalysisOptions, "config">> {
+  return typeof rawOptions.config === "string" ? { config: rawOptions.config } : {};
+}
+
+// `--diff` without an argument means "working-tree". A boolean `true` arrives when Commander parsed
+// the flag standalone; an explicit string keeps whatever ref the user passed (e.g., `main`).
+function diffOption(rawOptions: Record<string, unknown>): Partial<Pick<AnalysisOptions, "diff">> {
+  if (typeof rawOptions.diff === "string") {
+    return { diff: rawOptions.diff };
+  }
+  return rawOptions.diff === true ? { diff: "working-tree" } : {};
+}
+
+// Conditional spread keeps `historyFile` absent rather than `undefined` under exactOptionalPropertyTypes.
+function historyFileOption(rawOptions: Record<string, unknown>): Partial<Pick<AnalysisOptions, "historyFile">> {
+  return typeof rawOptions.historyFile === "string" ? { historyFile: rawOptions.historyFile } : {};
+}
+
+// `--baseline` with no value implies the conventional default file (`gruff-baseline.json`); commands
+// that disallow baseline input (e.g., `report`) short-circuit so the option is never set. The fingerprint
+// contract requires that two scans with the same baseline file produce identical suppression behaviour.
+function baselineOption(baselineValue: unknown, context: NormalizeContext): Partial<Pick<AnalysisOptions, "baseline">> {
+  if (!context.shouldAllowBaselineFlag) {
+    return {};
+  }
+  if (typeof baselineValue === "string") {
+    return { baseline: baselineValue };
+  }
+  return baselineValue === true ? { baseline: DEFAULT_BASELINE } : {};
+}
+
+// Mirrors `--baseline`: a bare `--generate-baseline` writes to the default path; a string value
+// overrides it. Absent (not present) and absent-because-undefined are distinct here.
+function generateBaselineOption(rawOptions: Record<string, unknown>): Partial<Pick<AnalysisOptions, "generateBaseline">> {
+  if (typeof rawOptions.generateBaseline === "string") {
+    return { generateBaseline: rawOptions.generateBaseline };
+  }
+  return rawOptions.generateBaseline === true ? { generateBaseline: DEFAULT_BASELINE } : {};
+}
+
+function stringChoice<T extends string>(value: unknown, choices: readonly T[], fallback: T): T {
+  return typeof value === "string" && choices.includes(value as T) ? (value as T) : fallback;
+}

package/src/cli.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// CLI shell: thin entrypoint that wires the analyser into the commander-based CLI program. The
+// analyse pipeline itself lives in `./analyser.ts`; this file is just bootstrap plus re-exports.
+import { argv } from "node:process";
+import { pathToFileURL } from "node:url";
+import { analyse } from "./analyser.ts";
+import { buildProgram as buildCliProgram } from "./cli-program.ts";
+import { absolutize, displayPath } from "./discovery.ts";
+import { renderReport } from "./report-renderers.ts";
+import { ruleDescriptors } from "./rules.ts";
+export type { AnalysisReport, Finding, OutputFormat, Pillar, RuleDescriptor, Severity } from "./types.ts";
+
+const buildProgram = (): ReturnType<typeof buildCliProgram> => buildCliProgram(analyse);
+
+if (import.meta.url === pathToFileURL(argv[1] ?? "").href) {
+  buildProgram().parse(argv);
+}
+
+export { absolutize, analyse, buildProgram, displayPath, renderReport, ruleDescriptors };