@blundergoat/gruff-ts 0.1.0 → 0.1.1

package/scripts/dependency-update.sh

@@ -0,0 +1,177 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+NPM_AUDIT_LEVEL="${NPM_AUDIT_LEVEL:-moderate}"
+DRY_RUN=0
+LATEST=0
+RUN_AUDIT=1
+RUN_CHECK=1
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  scripts/dependency-update.sh [options]
+
+Updates npm dependencies, then verifies the result.
+
+Default behavior:
+  - npm update
+  - npm audit --audit-level=moderate
+  - npm run check
+
+Options:
+  --dry-run            Show npm outdated output without changing files
+  --latest            Update direct dependencies/devDependencies to @latest
+  --audit-level LEVEL  npm audit threshold (default: moderate)
+  --no-audit           Skip npm audit after update
+  --no-check           Skip npm run check after update
+  --help, -h           Show this help
+
+Environment:
+  NPM_AUDIT_LEVEL      Default audit threshold when --audit-level is omitted
+USAGE
+}
+
+die() {
+  printf 'dependency-update: %s\n' "$*" >&2
+  exit 1
+}
+
+repo_root() {
+  local script_dir
+  script_dir="$(CDPATH='' cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+  CDPATH='' cd -- "$script_dir/.." && pwd
+}
+
+parse_args() {
+  while [[ "$#" -gt 0 ]]; do
+    case "$1" in
+      --dry-run)
+        DRY_RUN=1
+        ;;
+      --latest)
+        LATEST=1
+        ;;
+      --audit-level)
+        [[ "$#" -ge 2 ]] || die "--audit-level requires a value"
+        NPM_AUDIT_LEVEL="$2"
+        shift
+        ;;
+      --audit-level=*)
+        NPM_AUDIT_LEVEL="${1#*=}"
+        ;;
+      --no-audit)
+        RUN_AUDIT=0
+        ;;
+      --no-check)
+        RUN_CHECK=0
+        ;;
+      --help|-h)
+        usage
+        exit 0
+        ;;
+      *)
+        usage >&2
+        die "unknown option: $1"
+        ;;
+    esac
+    shift
+  done
+}
+
+require_tool() {
+  command -v "$1" >/dev/null 2>&1 || die "$1 is required"
+}
+
+print_outdated() {
+  local output
+  local status
+
+  if output=$(npm outdated --long 2>&1); then
+    printf '%s\n' "$output"
+    echo "All dependencies are current within the configured ranges."
+    return 0
+  else
+    status=$?
+  fi
+
+  # npm outdated exits non-zero when it finds outdated dependencies.
+  if [[ -n "$output" ]]; then
+    printf '%s\n' "$output"
+  fi
+  if ((status == 1)); then
+    return 0
+  fi
+
+  return "$status"
+}
+
+read_direct_dependencies() {
+  local field="$1"
+  # Print one key per line, nothing for an empty section. `console.log(keys.join("\n"))` would
+  # emit a lone newline when the section is empty, and `mapfile -t` would then read a single
+  # empty element, causing the install loop below to run `npm install --save-prod @latest`.
+  node -e "const pkg = require('./package.json'); for (const key of Object.keys(pkg['$field'] || {})) console.log(key);"
+}
+
+install_latest_dependencies() {
+  local -a dependencies=()
+  local -a dev_dependencies=()
+  local dependency
+
+  mapfile -t dependencies < <(read_direct_dependencies dependencies)
+  mapfile -t dev_dependencies < <(read_direct_dependencies devDependencies)
+
+  if [[ "${#dependencies[@]}" -gt 0 ]]; then
+    for dependency in "${dependencies[@]}"; do
+      dependency="${dependency}@latest"
+      echo "Updating production dependency: $dependency"
+      npm install --save-prod "$dependency"
+    done
+  fi
+
+  if [[ "${#dev_dependencies[@]}" -gt 0 ]]; then
+    for dependency in "${dev_dependencies[@]}"; do
+      dependency="${dependency}@latest"
+      echo "Updating development dependency: $dependency"
+      npm install --save-dev "$dependency"
+    done
+  fi
+}
+
+main() {
+  parse_args "$@"
+  cd "$(repo_root)"
+
+  require_tool node
+  require_tool npm
+  [[ -f package.json ]] || die "package.json not found"
+  [[ -f package-lock.json ]] || die "package-lock.json not found"
+
+  if [[ "$DRY_RUN" -eq 1 ]]; then
+    echo "--- Outdated dependencies ---"
+    print_outdated
+    exit 0
+  fi
+
+  echo "--- Update dependencies ---"
+  if [[ "$LATEST" -eq 1 ]]; then
+    install_latest_dependencies
+  else
+    npm update
+  fi
+
+  if [[ "$RUN_AUDIT" -eq 1 ]]; then
+    echo ""
+    echo "--- Dependency audit ---"
+    npm audit --audit-level="$NPM_AUDIT_LEVEL"
+  fi
+
+  if [[ "$RUN_CHECK" -eq 1 ]]; then
+    echo ""
+    echo "--- TypeScript + tests ---"
+    npm run check
+  fi
+}
+
+main "$@"

package/scripts/preflight-checks.sh

@@ -33,6 +33,8 @@ FAILED=0
 FAILURES=()
 TMP_FILES=()
 START_TIME=$(date +%s%N)
+NPM_REGISTRY_URL="${NPM_REGISTRY_URL:-https://registry.npmjs.org/}"
+NPM_AUDIT_LEVEL="${NPM_AUDIT_LEVEL:-moderate}"
 
 usage() {
   cat <<'USAGE'
@@ -40,12 +42,16 @@ Usage:
   scripts/preflight-checks.sh
 
 Runs the local preflight gate:
+  - release version is internally consistent and not already published to npm
+  - npm dependency audit
   - npm run check (TypeScript compile plus unit tests)
   - gruff-ts full-project scan
   - shellcheck for scripts/*.sh when shellcheck is installed
 
 Environment:
   GRUFF_TS_FAIL_ON   gruff-ts severity that fails static analysis (default: advisory)
+  NPM_REGISTRY_URL   npm registry used for the published-version check
+  NPM_AUDIT_LEVEL    npm audit threshold (default: moderate)
 USAGE
 }
 
@@ -176,6 +182,71 @@ make_temp_file() {
   printf '%s\n' "$temp_file"
 }
 
+read_package_name() {
+  node -p "require('./package.json').name"
+}
+
+read_package_version() {
+  node -p "require('./package.json').version"
+}
+
+npm_version_check() {
+  local package_name
+  local version
+  local output
+  local status
+
+  package_name="$(read_package_name)" || return 1
+  version="$(read_package_version)" || return 1
+  [[ -n "$package_name" ]] || {
+    printf 'package.json has no name field\n'
+    return 1
+  }
+  [[ -n "$version" ]] || {
+    printf 'package.json has no version field\n'
+    return 1
+  }
+
+  output=$(bash scripts/bump-version.sh --check 2>&1)
+  status=$?
+  if ((status != 0)); then
+    printf '%s\n' "$output"
+    return "$status"
+  fi
+
+  output=$(npm view "${package_name}@${version}" version --registry="$NPM_REGISTRY_URL" 2>&1)
+  status=$?
+  if ((status == 0)); then
+    printf '%s@%s is already published on %s; run scripts/bump-version.sh <next-version>\n' "$package_name" "$version" "$NPM_REGISTRY_URL"
+    return 1
+  fi
+
+  if printf '%s\n' "$output" | grep -Eq '(^|[[:space:]])(E404|404)([[:space:]]|$)'; then
+    printf 'lockstep ok; %s@%s is not published on %s' "$package_name" "$version" "$NPM_REGISTRY_URL"
+    return 0
+  fi
+
+  printf '%s\n' "$output"
+  return "$status"
+}
+
+npm_audit_check() {
+  local output
+  local status
+  local summary
+
+  output=$(npm audit --audit-level="$NPM_AUDIT_LEVEL" 2>&1)
+  status=$?
+  if ((status != 0)); then
+    printf '%s\n' "$output"
+    return "$status"
+  fi
+
+  summary=$(printf '%s\n' "$output" | awk '/found .* vulnerabilities|audited .* packages/ { line = $0 } END { print line }')
+  printf '%s' "${summary:-completed}"
+  return 0
+}
+
 npm_check() {
   local output
   local status
@@ -340,6 +411,10 @@ main() {
     return 127
   fi
 
+  run_step "Release version" npm_version_check
+
+  run_step "Dependency audit" npm_audit_check
+
   run_step "TypeScript + tests" npm_check
 
   run_step "Gruff full-project scan" gruff_ts_check

package/src/analyser.ts

@@ -1,5 +1,5 @@
-// Analyser pipeline: walks discovered sources, runs every rule pass (size, complexity, dead-code,
-// waste, naming, documentation, modernisation, security, sensitive-data, test-quality, design),
+// Analyser pipeline: walks discovered sources, runs every rule pass (complexity, dead-code, design,
+// documentation, maintainability, modernisation, naming, security, sensitive-data, size, test-quality),
 // aggregates findings into the `gruff.analysis.v1` schema, and exposes `analyse` to the CLI shell.
 import { existsSync, readFileSync } from "node:fs";
 import { cwd } from "node:process";
@@ -18,14 +18,13 @@ import { analyseDeadCode, analyseUnreachable, analyseUnusedImports } from "./dea
 import { analyseCommentQualityRules } from "./comment-rules.ts";
 import { analyseDocRules, analyseFileOverviewDoc, analyseInterfaceDocs } from "./doc-rules.ts";
 import { analyseLineRules } from "./line-rules.ts";
-import { pushAbbreviationAt, pushBooleanPrefixAt, pushIdentifierQualityAt, pushNegativeBooleanAt, pushShortVariableAt } from "./naming-pushers.ts";
+import { pushBooleanPrefixAt, pushIdentifierQualityAt, pushNegativeBooleanAt, pushShortVariableAt } from "./naming-pushers.ts";
 import { analyseTestBlock } from "./test-block-rules.ts";
 import { analyseGithubActionsRules } from "./github-actions-rules.ts";
 import { analyseProjectConfigRules } from "./project-config-rules.ts";
 import { scoreReport, summarize } from "./scoring.ts";
 import { analyseSensitiveData } from "./sensitive-data-rules.ts";
 import { maskNonCode, maskTemplateLiteralBodies, parseDiagnostics } from "./source-text.ts";
-import { todoMarkerSummary } from "./text-scans.ts";
 import type { AnalysisOptions, AnalysisReport, Config, Finding, RunDiagnostic } from "./types.ts";
 
 /**
@@ -308,18 +307,6 @@ function analyseTextRules(file: SourceFile, source: string, config: Config, find
     }
   }
 
-  /*
-   * Opt-in by default per M38 (.goat-flow/tasks/0.1/M38-css-metrics-and-todo-density-calibration.md):
-   * raw marker density produced too many false positives in other gruff projects; prefer the
-   * context-aware docs.todo-without-tracking rule when task-marker scanning matters.
-   */
-  if (config.rules.get("docs.todo-density")?.enabled === true) {
-    const todoMarkers = todoMarkerSummary(source, file.isScript);
-    if (todoMarkers.count >= threshold(config, "docs.todo-density", 4)) {
-      findings.push(finding({ ruleId: "docs.todo-density", message: `File contains ${todoMarkers.count} TODO/FIXME markers.`, file, line: todoMarkers.firstLine, severity: ruleSeverity(config, "docs.todo-density", "advisory"), pillar: "documentation" }));
-    }
-  }
-
   analyseSensitiveData(file, source, config, findings);
   analyseGithubActionsRules(file, source, findings);
   analyseProjectConfigRules(file, source, findings);
@@ -390,9 +377,8 @@ function analyseBlocks(file: SourceFile, blocks: FunctionBlock[], config: Config
 }
 
 /*
- * Per-parameter naming-rule fanout. Each parameter is checked for short-name / opaque-abbreviation
- * / placeholder forms; typed booleans get the extra prefix and negative-name checks. Reports findings
- * to the shared sink.
+ * Per-parameter naming-rule fanout. Each parameter is checked for short-name / placeholder forms;
+ * typed booleans get the extra prefix and negative-name checks. Reports findings to the shared sink.
  */
 function pushParameterNamingFindings(context: BlockRuleContext): void {
   const line = context.block.declarationLine;
@@ -400,7 +386,6 @@ function pushParameterNamingFindings(context: BlockRuleContext): void {
   for (const parameter of params) {
     pushShortVariableAt(context.file, line, parameter.name, context.config, context.findings, "parameter");
     pushIdentifierQualityAt(context.file, line, parameter.name, context.config, context.findings, "parameter");
-    pushAbbreviationAt(context.file, line, parameter.name, context.config, context.findings, "parameter");
     if (isBooleanParameter(parameter.raw)) {
       pushBooleanPrefixAt(context.file, line, parameter.name, context.config, context.findings, "parameter");
       pushNegativeBooleanAt(context.file, line, parameter.name, context.config, context.findings, "parameter");

package/src/blocks.ts

@@ -223,7 +223,7 @@ function pushEmptyFunctionFinding(context: BlockRuleContext): void {
     return;
   }
   if (isEmptyFunctionBody(context.block.codeBody)) {
-    context.findings.push(blockFinding({ ruleId: "waste.empty-function", message: `Function \`${context.block.name}\` has no executable body.`, file: context.file, block: context.block, severity: "advisory", pillar: "waste" }));
+    context.findings.push(blockFinding({ ruleId: "waste.empty-function", message: `Function \`${context.block.name}\` has no executable body.`, file: context.file, block: context.block, severity: "advisory", pillar: "maintainability" }));
   }
 }
 
@@ -287,7 +287,7 @@ function unusedParameterFinding(context: BlockRuleContext, parameterName: string
     filePath: context.file.displayPath,
     line: context.block.startLine,
     severity: "advisory",
-    pillar: "waste",
+    pillar: "maintainability",
     confidence: "medium",
     symbol: context.block.name,
     remediation: "Remove the parameter or prefix it with _ if it is intentionally unused.",
@@ -306,7 +306,7 @@ function pushRedundantVariableFindings(context: BlockRuleContext): void {
         filePath: context.file.displayPath,
         line: context.block.startLine + redundant.lineOffset,
         severity: "advisory",
-        pillar: "waste",
+        pillar: "maintainability",
         confidence: "medium",
         symbol: redundant.name,
         remediation: "Return the expression directly.",
@@ -327,7 +327,7 @@ function pushUselessReturnFindings(context: BlockRuleContext): void {
         filePath: context.file.displayPath,
         line: context.block.startLine + lineOffset,
         severity: "advisory",
-        pillar: "waste",
+        pillar: "maintainability",
         confidence: "medium",
         symbol: context.block.name,
         remediation: "Remove the final return statement.",

package/src/class-rules.ts

@@ -7,7 +7,7 @@ import { type ExportedDeclaration, exportedDeclarations, pushMissingPublicDocFin
 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 { pushBooleanPrefixAt, pushNegativeBooleanAt } from "./naming-pushers.ts";
 import { byteLine } from "./text-scans.ts";
 import type { Config, Finding } from "./types.ts";
 
@@ -46,7 +46,7 @@ export function collectDeclaredIdentifiers(source: string, codeSource: string, b
 }
 
 // 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).
+// naming inventory (above) and for the per-field interface rules (boolean prefix, negative-boolean).
 function collectInterfaceFieldDeclarations(source: string, codeSource: string): DeclaredIdentifier[] {
   const fieldRegex = /^[ \t]*(?:readonly\s+)?([A-Za-z_$][A-Za-z0-9_$]*)\??\s*:/;
   const out: DeclaredIdentifier[] = [];
@@ -190,9 +190,9 @@ function isFixtureIdentifier(name: string): boolean {
 }
 
 /*
- * 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.
+ * Walks every interface field and runs two checks per boolean field: boolean prefix and
+ * negative boolean. The stable ordering matches `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*([^;]+)/;
@@ -200,7 +200,6 @@ export function analyseInterfaceFields(file: SourceFile, source: string, codeSou
     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");

package/src/cli-program.ts

@@ -1,12 +1,13 @@
 // Commander CLI shell wiring that keeps option normalization and stdout behavior outside the analyzer.
-import { Command, Help } from "commander";
+import { Command, Help, InvalidArgumentError } 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 { promptYesNo, shouldPromptForInit, writeDefaultConfig } from "./init-config.ts";
+import { renderReport, renderSummary, renderSummaryJson } 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";
@@ -35,6 +36,49 @@ function outputSuppressed(program: Command): boolean {
   return options.quiet === true || options.silent === true;
 }
 
+// Per-command config-loading state passed into maybePromptInitConfig. analyse/summary/report
+// take both flags from normalizeOptions; dashboard has no equivalent flags so it passes
+// `{ shouldSkipConfig: false, hasExplicitConfig: false }`.
+interface InitPromptOptions {
+  shouldSkipConfig: boolean;
+  hasExplicitConfig: boolean;
+}
+
+// Asks the user whether to run `init` when no config exists, then writes the file if they agree.
+// Called from analyse/summary/report/dashboard before kicking off their main work so the
+// freshly-written file is picked up by loadConfig on the same invocation. Pure decision logic
+// lives in shouldPromptForInit; this function only handles orchestration and side effects.
+async function maybePromptInitConfig(program: Command, projectRoot: string, options: InitPromptOptions): Promise<void> {
+  const programOptions = program.opts() as { interaction?: boolean };
+  const context = {
+    projectRoot,
+    shouldSkipConfig: options.shouldSkipConfig,
+    hasExplicitConfig: options.hasExplicitConfig,
+    isInteractionAllowed: programOptions.interaction !== false,
+    isOutputSuppressed: outputSuppressed(program),
+    isStdinTty: process.stdin.isTTY === true,
+    isStdoutTty: process.stdout.isTTY === true,
+    isStderrTty: process.stderr.isTTY === true,
+  };
+  if (!shouldPromptForInit(context)) {
+    return;
+  }
+  const accepted = await promptYesNo(`No gruff config found at ${projectRoot}. Run 'gruff-ts init' to create .gruff-ts.yaml? [y/N] `);
+  if (!accepted) {
+    return;
+  }
+  const result = writeDefaultConfig(projectRoot, false);
+  if (result.status === "written") {
+    process.stderr.write(`Wrote ${result.path}\n`);
+  }
+}
+
+// AnalysisOptions → InitPromptOptions shim used by analyse/summary/report so they share one
+// branch and shouldSkipConfig stays the single source of truth for opt-out behaviour.
+function promptOptionsFromAnalysis(options: AnalysisOptions): InitPromptOptions {
+  return { shouldSkipConfig: options.shouldSkipConfig, hasExplicitConfig: typeof options.config === "string" };
+}
+
 // 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 {
@@ -56,6 +100,7 @@ export function buildProgram(runAnalyse: AnalyseRunner): Command {
   registerAnalyseCommand(program, runAnalyse);
   registerCompletionCommand(program);
   registerDashboardCommand(program, runAnalyse);
+  registerInitCommand(program);
   registerListCommand(program);
   registerListRulesCommand(program);
   registerReportCommand(program, runAnalyse);
@@ -127,8 +172,9 @@ function registerAnalyseCommand(program: Command, runAnalyse: AnalyseRunner): vo
     .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>) => {
+    .action(async (paths: string[], rawOptions: Record<string, unknown>) => {
       const options = normalizeOptions(paths, rawOptions, { shouldAllowBaselineFlag: true });
+      await maybePromptInitConfig(program, process.cwd(), promptOptionsFromAnalysis(options));
       const report = runAnalyse(options);
       writeCommandOutput(program, renderReport(report, options.format));
       process.exitCode = exitFor(report, options.failOn);
@@ -156,11 +202,45 @@ function registerDashboardCommand(program: Command, runAnalyse: AnalyseRunner):
     .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(async (rawOptions: Record<string, unknown>) => {
+      const projectRoot = resolve(String(rawOptions.projectRoot ?? "."));
+      await maybePromptInitConfig(program, projectRoot, { shouldSkipConfig: false, hasExplicitConfig: false });
+      startDashboard(String(rawOptions.host ?? "127.0.0.1"), Number(rawOptions.port ?? 8767), projectRoot, runAnalyse, !outputSuppressed(program));
+    });
+}
+
+// Writes the default `.gruff-ts.yaml` to the current working directory. Refuses to clobber an
+// existing config unless `--force` is passed; sets process.exitCode=1 in that case so scripted
+// callers can detect the refusal without parsing stdout.
+function registerInitCommand(program: Command): void {
+  program
+    .command("init")
+    .description("Write the default .gruff-ts.yaml to the current directory.")
+    .option("--force", "Write .gruff-ts.yaml even when another supported config (.gruff.yaml/.yml/.json) is present; overwrites .gruff-ts.yaml if it exists.")
     .action((rawOptions: Record<string, unknown>) => {
-      startDashboard(String(rawOptions.host ?? "127.0.0.1"), Number(rawOptions.port ?? 8767), resolve(String(rawOptions.projectRoot ?? ".")), runAnalyse, !outputSuppressed(program));
+      const result = writeDefaultConfig(process.cwd(), rawOptions.force === true);
+      if (result.status === "exists") {
+        process.stderr.write(`Refusing to overwrite existing config: ${result.path}. Re-run with --force to replace it.\n`);
+        process.exitCode = 1;
+        return;
+      }
+      const verb = result.status === "overwritten" ? "Overwrote" : "Wrote";
+      writeCommandOutput(program, initSuccessMessage(verb, result.path));
     });
 }
 
+// Keeps `init` as a config-only write while pointing existing projects at the adoption flow.
+function initSuccessMessage(verb: "Wrote" | "Overwrote", configPath: string): string {
+  return [
+    `${verb} ${configPath}`,
+    "",
+    "Next: generate an adoption baseline with:",
+    "  gruff-ts analyse . --generate-baseline gruff-baseline.json --fail-on=none",
+    "Then gate new findings with:",
+    "  gruff-ts analyse . --baseline gruff-baseline.json --fail-on=warning",
+  ].join("\n");
+}
+
 // 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 {
@@ -173,12 +253,12 @@ function registerListCommand(program: Command): void {
 }
 
 // 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.
+// `--format` is validated by `parseSummaryFormat`; unsupported values fail fast as a usage error.
 function registerListRulesCommand(program: Command): void {
   program
     .command("list-rules")
     .description("List gruff rule metadata.")
-    .option("--format <format>", "Output format: text or json.", "text")
+    .option("--format <format>", "Output format: text or json.", parseSummaryFormat, "text")
     .action((rawOptions: Record<string, unknown>) => {
       const format: RuleListFormat = rawOptions.format === "json" ? "json" : "text";
       writeCommandOutput(program, renderRuleList(format));
@@ -200,9 +280,10 @@ function registerReportCommand(program: Command, runAnalyse: AnalyseRunner): voi
     .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>) => {
+    .action(async (paths: string[], rawOptions: Record<string, unknown>) => {
       const format = rawOptions.format === "json" ? "json" : "html";
       const options = normalizeOptions(paths, { ...rawOptions, format }, { shouldAllowBaselineFlag: false });
+      await maybePromptInitConfig(program, process.cwd(), promptOptionsFromAnalysis(options));
       const report = runAnalyse(options);
       const rendered = renderReport(report, format);
       if (typeof rawOptions.output === "string") {
@@ -214,8 +295,7 @@ function registerReportCommand(program: Command, runAnalyse: AnalyseRunner): voi
     });
 }
 
-// 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.
+// Same analyser run as `analyse` but renders only the pillar/rule/offender digest.
 function registerSummaryCommand(program: Command, runAnalyse: AnalyseRunner): void {
   program
     .command("summary")
@@ -225,6 +305,8 @@ function registerSummaryCommand(program: Command, runAnalyse: AnalyseRunner): vo
     .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 or json.", parseSummaryFormat, "text")
+    .option("--top <n>", "How many top rules and file offenders to list.", parseNonNegativeInteger, 10)
     .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.")
@@ -232,16 +314,47 @@ function registerSummaryCommand(program: Command, runAnalyse: AnalyseRunner): vo
     .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();
+    .action(async (paths: string[], rawOptions: Record<string, unknown>) => {
       const options = normalizeOptions(paths, { ...rawOptions, format: "text" }, { shouldAllowBaselineFlag: true });
+      const summaryFormat = rawOptions.format === "json" ? "json" : "text";
+      const top = typeof rawOptions.top === "number" ? rawOptions.top : 10;
+      await maybePromptInitConfig(program, process.cwd(), promptOptionsFromAnalysis(options));
+      const startedAt = performance.now();
       const report = runAnalyse(options);
       const elapsedMs = performance.now() - startedAt;
-      writeCommandOutput(program, renderSummary(report, elapsedMs, summaryPathLabel(options.paths, report.run.projectRoot)));
+      const pathLabel = summaryPathLabel(options.paths, report.run.projectRoot);
+      const rendered = summaryFormat === "json"
+        ? renderSummaryJson(report, elapsedMs, pathLabel, top)
+        : renderSummary(report, elapsedMs, pathLabel, top);
+      writeCommandOutput(program, rendered);
       process.exitCode = exitFor(report, options.failOn);
     });
 }
 
+/*
+ * Commander `--format` argParser for the summary command. Throws `InvalidArgumentError` when the
+ * input is neither `text` nor `json`; commander reports that as a usage error and exits non-zero
+ * before the command body runs.
+ */
+function parseSummaryFormat(rawFormat: string): "text" | "json" {
+  if (rawFormat === "text" || rawFormat === "json") {
+    return rawFormat;
+  }
+  throw new InvalidArgumentError("must be text or json");
+}
+
+/*
+ * Commander argParser for `--top`-style numeric flags. Throws `InvalidArgumentError` on non-integer
+ * or negative input so commander reports a usage error and exits non-zero before the command runs.
+ */
+function parseNonNegativeInteger(rawCount: string): number {
+  const parsed = Number(rawCount);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new InvalidArgumentError("must be a non-negative integer");
+  }
+  return parsed;
+}
+
 // 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) {

package/src/cli.ts

@@ -13,7 +13,10 @@ export type { AnalysisReport, Finding, OutputFormat, Pillar, RuleDescriptor, Sev
 const buildProgram = (): ReturnType<typeof buildCliProgram> => buildCliProgram(analyse);
 
 if (import.meta.url === pathToFileURL(argv[1] ?? "").href) {
-  buildProgram().parse(argv);
+  // Action handlers in cli-program.ts are async (await maybePromptInitConfig). parseAsync is
+  // required so rejections after the first await surface through Commander's error path instead
+  // of escaping as unhandled promise rejections.
+  await buildProgram().parseAsync(argv);
 }
 
 export { absolutize, analyse, buildProgram, displayPath, renderReport, ruleDescriptors };