@blundergoat/gruff-ts 0.1.0 → 0.1.1

package/src/comment-rules.ts

@@ -294,6 +294,7 @@ function knownCliFlags(): Set<string> {
     "--config",
     "--diff",
     "--fail-on",
+    "--force",
     "--format",
     "--generate-baseline",
     "--help",
@@ -309,6 +310,7 @@ function knownCliFlags(): Set<string> {
     "--project-root",
     "--quiet",
     "--silent",
+    "--top",
     "--verbose",
     "--version",
   ]);

package/src/config.ts

@@ -35,7 +35,6 @@ function defaultConfig(): Config {
     booleanPrefixes: new Set(["is", "has", "can", "should", "does", "did", "was", "will", "may", "in", "scan", "supports", "requires"]),
     hungarianPrefixes: new Set(["str", "obj", "arr", "bool", "int", "num"]),
     placeholderNames: new Set(["foo", "bar", "baz", "tmp", "temp", "thing", "stuff", "data", "value", "item"]),
-    abbreviationDenylist: new Set(["ctx", "pkg", "opts", "fn", "idx", "cb"]),
     negativeBooleanAllowed: new Set(["nostore", "nofollow", "noreferrer", "noscript", "noindex"]),
     knownAcronyms: new Set(["url", "http", "https", "id", "xml", "json", "html", "css", "api", "sql", "db", "io", "ui", "uuid", "ip", "tcp", "udp", "ast", "cli", "npm"]),
     rules: new Map(),
@@ -100,14 +99,13 @@ function applyAllowlistConfig(config: Config, raw: Record<string, unknown>): voi
   applyNamingAllowlist(config, allowlists, "booleanPrefixes");
   applyNamingAllowlist(config, allowlists, "hungarianPrefixes");
   applyNamingAllowlist(config, allowlists, "placeholderNames");
-  applyNamingAllowlist(config, allowlists, "abbreviationDenylist");
   applyNamingAllowlist(config, allowlists, "negativeBooleanAllowed");
   applyNamingAllowlist(config, allowlists, "knownAcronyms");
 }
 
 // Replaces the entire list when the user provides that key - there is no merge with defaults.
 // The "set the whole list" semantic is intentional so users can deliberately empty a list.
-function applyNamingAllowlist(config: Config, allowlists: Record<string, unknown> | undefined, key: "bannedGenericNames" | "booleanPrefixes" | "hungarianPrefixes" | "placeholderNames" | "abbreviationDenylist" | "negativeBooleanAllowed" | "knownAcronyms"): void {
+function applyNamingAllowlist(config: Config, allowlists: Record<string, unknown> | undefined, key: "bannedGenericNames" | "booleanPrefixes" | "hungarianPrefixes" | "placeholderNames" | "negativeBooleanAllowed" | "knownAcronyms"): void {
   if (!allowlists || !(key in allowlists)) {
     return;
   }
@@ -619,4 +617,4 @@ function isSeverity(configValue: unknown): configValue is Severity {
   return configValue === "advisory" || configValue === "warning" || configValue === "error";
 }
 
-export { isString, loadConfig, objectValue, optionNumber, ruleEnabled, ruleSeverity, threshold };
+export { defaultConfigPath, isString, loadConfig, objectValue, optionNumber, ruleEnabled, ruleSeverity, threshold };

package/src/constants.ts

@@ -1,4 +1,4 @@
 // Shared release constants that keep CLI, reports, and rule catalogue output in sync.
-const VERSION = "0.1.0";
+const VERSION = "0.1.1";
 
 export { VERSION };

package/src/dead-code-rules.ts

@@ -44,7 +44,7 @@ export function analyseUnreachable(file: SourceFile, source: string, findings: F
       didPreviousTerminate = false;
     }
     if (isUnreachableStatement(trimmed, didPreviousTerminate, branchLabel)) {
-      findings.push(finding({ ruleId: "waste.unreachable-code", message: "Statement appears after a terminating statement.", file, line: index + 1, severity: "warning", pillar: "waste" }));
+      findings.push(finding({ ruleId: "waste.unreachable-code", message: "Statement appears after a terminating statement.", file, line: index + 1, severity: "warning", pillar: "maintainability" }));
     }
     // A terminating statement inside a braceless conditional body does not unconditionally exit:
     // `if (x)\n  return y;\nnextLine` - `nextLine` runs when `x` is falsy. Tracking the prior line's
@@ -165,7 +165,7 @@ function unusedImportFinding(file: SourceFile, name: string, line: number): Find
     filePath: file.displayPath,
     line,
     severity: "advisory",
-    pillar: "waste",
+    pillar: "maintainability",
     confidence: "medium",
     symbol: name,
     remediation: "Remove the unused import.",

package/src/init-config.ts

@@ -0,0 +1,248 @@
+// Renders the default .gruff-ts.yaml file from the rule descriptor registry so `gruff-ts init`
+// can drop a config into a fresh project that mirrors the analyser's effective defaults.
+import { existsSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { defaultConfigPath, loadConfig } from "./config.ts";
+import { ruleDescriptors } from "./rules.ts";
+import type { RuleDescriptor } from "./types.ts";
+
+const DEFAULT_CONFIG_FILE_NAME = ".gruff-ts.yaml";
+
+// Default option values for rules with `optionKeys`. The source of truth is the
+// `optionNumber(config, ruleId, key, default)` call site in the rule implementation; mirroring
+// them here keeps `gruff-ts init` self-contained. `init-config.test.ts` asserts the values
+// here match the implementation defaults so drift fails the test suite, not user projects.
+const RULE_OPTION_DEFAULTS: Readonly<Record<string, Readonly<Record<string, number>>>> = {
+  "design.large-module-concentration": { minFiles: 4, minLines: 80 },
+  "naming.generic-parameter": { minCyclomatic: 8, minLineCount: 30, minParameters: 3 },
+};
+
+// Default starter list copied from `defaultConfig()` in config.ts. Generated separately because
+// the YAML form (a block sequence) is more reviewable than the inline `[...]` form a Set would emit.
+const DEFAULT_ACCEPTED_ABBREVIATIONS: readonly string[] = ["id", "db", "fs", "io", "ui", "tx", "rx"];
+
+// Result of an init write attempt, including the no-clobber branch for existing config files.
+interface InitResult {
+  path: string;
+  status: "written" | "overwritten" | "exists";
+}
+
+// Inputs the analyse/summary actions must collect before deciding whether to ask the user about
+// running `init`. Kept as an explicit shape so the predicate is testable without TTY mocking. All
+// three stream TTY states matter: stdin so the answer can be typed, stderr so the prompt is seen,
+// and stdout so a piped consumer (e.g. `... --format=json | jq`) does not block on hidden input.
+interface InitPromptContext {
+  projectRoot: string;
+  shouldSkipConfig: boolean;
+  hasExplicitConfig: boolean;
+  isInteractionAllowed: boolean;
+  isOutputSuppressed: boolean;
+  isStdinTty: boolean;
+  isStdoutTty: boolean;
+  isStderrTty: boolean;
+}
+
+/**
+ * Render the default .gruff-ts.yaml content from the rule descriptor registry.
+ *
+ * @param ignoredPaths Optional `paths.ignore` entries to inject verbatim (block-sequence form). The
+ *   `gruff-ts init --force` flow forwards the existing file's entries so user-curated exclusions
+ *   survive regeneration; an empty list emits `ignore: []` for fresh projects.
+ * @returns A YAML document string terminated by a trailing newline.
+ */
+function renderDefaultConfig(ignoredPaths: readonly string[] = []): string {
+  return [renderPathsSection(ignoredPaths), "", renderAllowlistsSection(), "", renderRulesSection()].join("\n") + "\n";
+}
+
+/**
+ * Write the default config to `<projectRoot>/.gruff-ts.yaml`. Performs a filesystem write side
+ * effect when no supported config exists, or when `shouldOverwrite` is true and `.gruff-ts.yaml`
+ * is the incumbent. Refuses to clobber (no side effect) when ANY supported config file is present
+ * (the four-name precedence list in `DEFAULT_CONFIG_FILES`), not just `.gruff-ts.yaml` -
+ * otherwise `init` would silently create a higher-precedence file alongside an existing
+ * `.gruff.yaml` / `.gruff.yml` / `.gruff.json` and quietly change the effective config. When
+ * overwriting an existing `.gruff-ts.yaml`, the file's `paths.ignore` entries are preserved so
+ * `init --force` does not erase project-specific recursive-scan exclusions.
+ *
+ * @param projectRoot Directory to write the config file into.
+ * @param shouldOverwrite Overwrite an existing config file when true.
+ * @returns The resolved path and whether a file was written, overwritten, or skipped. When the
+ *   refusal is triggered by a non-canonical name, `path` points at that file so the caller's
+ *   error message names the actual blocker.
+ */
+function writeDefaultConfig(projectRoot: string, shouldOverwrite: boolean): InitResult {
+  const targetPath = join(projectRoot, DEFAULT_CONFIG_FILE_NAME);
+  const existingConfigPath = defaultConfigPath(projectRoot);
+  if (existingConfigPath !== undefined && !shouldOverwrite) {
+    return { path: existingConfigPath, status: "exists" };
+  }
+  const targetExists = existsSync(targetPath);
+  // Preserve paths.ignore from whichever supported config exists, not just `.gruff-ts.yaml` -
+  // otherwise `init --force` against a project with only `.gruff.yaml`/`.yml`/`.json` would
+  // silently drop user-curated ignore entries when generating the new canonical file.
+  const preservedIgnoredPaths = existingConfigPath !== undefined ? readExistingIgnoredPaths(projectRoot) : [];
+  writeFileSync(targetPath, renderDefaultConfig(preservedIgnoredPaths));
+  return { path: targetPath, status: targetExists ? "overwritten" : "written" };
+}
+
+/*
+ * Recover the existing file's `paths.ignore` block before `init --force` overwrites it. The
+ * try/catch swallows YAML-parse errors and the fallback returns an empty list so a malformed
+ * existing config does not block regeneration - the user is opting into clobbering, but the
+ * documented contract is that curated ignore entries survive when readable.
+ */
+function readExistingIgnoredPaths(projectRoot: string): readonly string[] {
+  try {
+    const config = loadConfig(projectRoot, {
+      paths: [],
+      shouldSkipConfig: false,
+      format: "text",
+      failOn: "none",
+      shouldIncludeIgnored: false,
+      shouldSkipBaseline: true,
+    });
+    return config.ignoredPaths;
+  } catch {
+    return [];
+  }
+}
+
+// `paths.ignore` defaults to empty for fresh projects - discovery.ts already filters node_modules,
+// .git, etc. regardless of config. When `init --force` regenerates an existing config, the caller
+// forwards the existing entries so user-curated exclusions survive.
+function renderPathsSection(ignoredPaths: readonly string[]): string {
+  const header = [
+    "paths:",
+    "  # Recursive scans already respect .gitignore plus built-in default directories",
+    "  # such as .git, node_modules, dist, coverage, generated, tmp, and vendor.",
+    "  # Add project-specific generated or local outputs here when Git does not ignore them.",
+    "  # Examples:",
+    "  #   - \"out/**\"",
+    "  #   - \".next/**\"",
+    "  #   - \"src/generated/**\"",
+  ];
+  if (ignoredPaths.length === 0) {
+    return [...header, "  ignore: []"].join("\n");
+  }
+  return [
+    ...header,
+    "  ignore:",
+    ...ignoredPaths.map((ignoredPath) => `    - ${JSON.stringify(ignoredPath)}`),
+  ].join("\n");
+}
+
+// `acceptedAbbreviations` is emitted as a block sequence for reviewability; the seven naming
+// allowlists below it stay commented out so users see the override knobs without changing defaults.
+function renderAllowlistsSection(): string {
+  return [
+    "allowlists:",
+    "  acceptedAbbreviations:",
+    ...DEFAULT_ACCEPTED_ABBREVIATIONS.map((abbreviation) => `    - ${abbreviation}`),
+    "  secretPreviews: []",
+    "  # Names that trigger naming.generic-function. Each key replaces the built-in",
+    "  # default when present; an empty list disables that rule's blacklist branch.",
+    "  # Default: [process, handle, doit, run, execute, manage]",
+    "  # bannedGenericNames: [process, handle, doit, run, execute, manage]",
+    "  # Accepted prefixes for boolean identifiers. Names without one of these",
+    "  # prefixes trigger naming.boolean-prefix.",
+    "  # Default: [is, has, can, should, does, did, was, will, may, in, scan, supports, requires]",
+    "  # booleanPrefixes: [is, has, can, should, does, did, was, will, may, in, scan, supports, requires]",
+    "  # Hungarian type-style prefixes flagged by naming.hungarian-notation.",
+    "  # Default: [str, obj, arr, bool, int, num]",
+    "  # hungarianPrefixes: [str, obj, arr, bool, int, num]",
+    "  # Placeholder words flagged as generic by naming.identifier-quality. The",
+    "  # numbered-suffix branch (foo1, value2) stays active even when this is empty.",
+    "  # Default: [foo, bar, baz, tmp, temp, thing, stuff, data, value, item]",
+    "  # placeholderNames: [foo, bar, baz, tmp, temp, thing, stuff, data, value, item]",
+    "  # Negative-framed boolean names that should NOT trigger naming.negative-boolean.",
+    "  # Defaults are HTTP-header conventions; add project terms as needed.",
+    "  # Default: [nostore, nofollow, noreferrer, noscript, noindex]",
+    "  # negativeBooleanAllowed: [nostore, nofollow, noreferrer, noscript, noindex]",
+    "  # Known acronyms whose mixed casings trigger naming.acronym-case. Stored",
+    "  # case-insensitively; match is against canonical lowercase.",
+    "  # Default: [url, http, https, id, xml, json, html, css, api, sql, db, io, ui, uuid, ip, tcp, udp, ast, cli, npm]",
+    "  # knownAcronyms: [url, http, https, id, xml, json, html, css, api, sql, db, io, ui, uuid, ip, tcp, udp, ast, cli, npm]",
+  ].join("\n");
+}
+
+// Walks the registry in its canonical (sorted) order so the generated YAML is byte-stable.
+function renderRulesSection(): string {
+  const lines = ["rules:"];
+  for (const descriptor of ruleDescriptors()) {
+    lines.push(...renderRuleEntry(descriptor));
+  }
+  return lines.join("\n");
+}
+
+// One rule entry: a `# pillar/severity: description` comment line, the rule id, `enabled`, then
+// threshold/severity/options only when the descriptor declares them. Omitting absent keys keeps
+// the generated file aligned with the descriptor's actual contract.
+function renderRuleEntry(descriptor: RuleDescriptor): string[] {
+  const lines: string[] = [];
+  lines.push(`  # ${descriptor.pillar}/${descriptor.severity}: ${descriptor.description}`);
+  lines.push(`  ${descriptor.ruleId}:`);
+  lines.push("    enabled: true");
+  if (typeof descriptor.threshold === "number") {
+    lines.push(`    threshold: ${descriptor.threshold}`);
+    lines.push(`    severity: ${descriptor.severity}`);
+  }
+  const optionDefaults = RULE_OPTION_DEFAULTS[descriptor.ruleId];
+  if (optionDefaults) {
+    lines.push("    options:");
+    for (const [key, value] of Object.entries(optionDefaults)) {
+      lines.push(`      ${key}: ${value}`);
+    }
+  }
+  return lines;
+}
+
+/**
+ * Decide whether the analyse/summary actions should prompt the user to run `init`.
+ *
+ * Returns true only when every gate passes: interaction is allowed, output isn't suppressed, the
+ * user hasn't already opted in (--config) or out (--no-config) of config loading, all three
+ * standard streams are TTYs (stdin to type, stderr to display, stdout to confirm the run is not
+ * piping machine output to a downstream consumer), and no supported config file is already
+ * present at the project root.
+ *
+ * @param context CLI-collected state needed to make the decision.
+ * @returns Whether the prompt should be shown.
+ */
+function shouldPromptForInit(context: InitPromptContext): boolean {
+  if (!context.isInteractionAllowed) {
+    return false;
+  }
+  if (context.isOutputSuppressed) {
+    return false;
+  }
+  if (context.shouldSkipConfig || context.hasExplicitConfig) {
+    return false;
+  }
+  if (!context.isStdinTty || !context.isStdoutTty || !context.isStderrTty) {
+    return false;
+  }
+  return defaultConfigPath(context.projectRoot) === undefined;
+}
+
+/**
+ * Ask the user a yes/no question on stderr and return their answer.
+ *
+ * Defaults to "no" when the user just presses enter so the prompt is safe to dismiss. Reads from
+ * stdin; closes the readline interface in a finally so a Ctrl-C exits cleanly.
+ *
+ * @param question Prompt text written to stderr verbatim.
+ * @returns True when the user typed y or yes (case-insensitive); false otherwise.
+ */
+async function promptYesNo(question: string): Promise<boolean> {
+  const readlineInterface = createInterface({ input: process.stdin, output: process.stderr });
+  try {
+    const answer = await readlineInterface.question(question);
+    return /^(y|yes)$/i.test(answer.trim());
+  } finally {
+    readlineInterface.close();
+  }
+}
+
+export type { InitPromptContext, InitResult };
+export { DEFAULT_CONFIG_FILE_NAME, RULE_OPTION_DEFAULTS, promptYesNo, renderDefaultConfig, shouldPromptForInit, writeDefaultConfig };

package/src/line-rules.ts

@@ -7,7 +7,7 @@
 import { type SourceFile } from "./discovery.ts";
 import { makeFinding } from "./findings.ts";
 import { escapeRegex, finding, isCommentedOutCode } from "./findings-helpers.ts";
-import { type NamingSurface, pushAbbreviationAt, pushBooleanPrefixAt, pushIdentifierQualityAt, pushNegativeBooleanAt, pushShortVariableAt } from "./naming-pushers.ts";
+import { type NamingSurface, pushBooleanPrefixAt, pushIdentifierQualityAt, pushNegativeBooleanAt, pushShortVariableAt } from "./naming-pushers.ts";
 import { analyseReliabilityLine, analyseSwallowedCatches, analyseTypeSafetyLine, analyseUselessCatches } from "./safety-rules.ts";
 import { analyseSecurityFlowLine } from "./security-flow-rules.ts";
 import { codeLineForMatching } from "./source-text.ts";
@@ -104,7 +104,7 @@ function codeLineChecks(): LineRuleCheck[] {
     { ruleId: "security.inner-html", pattern: /\.innerHTML\s*=(?!\s*(?:""|''))|\bdangerouslySetInnerHTML\b/, message: "HTML injection sink can introduce XSS.", severity: "warning", pillar: "security" },
     { ruleId: "security.proto-access", pattern: /\.__proto__\b/, message: "Direct __proto__ access can enable prototype pollution.", severity: "warning", pillar: "security" },
     { ruleId: "security.document-write", pattern: /\bdocument\.write\s*\(/, message: "document.write() can introduce injection risks.", severity: "warning", pillar: "security" },
-    { ruleId: "waste.redundant-boolean-cast", pattern: /\b(?:if|while)\s*\(\s*(?:!!\s*[A-Za-z_$][A-Za-z0-9_$.]*|Boolean\s*\()/, message: "Condition contains a redundant boolean cast.", severity: "advisory", pillar: "waste" },
+    { ruleId: "waste.redundant-boolean-cast", pattern: /\b(?:if|while)\s*\(\s*(?:!!\s*[A-Za-z_$][A-Za-z0-9_$.]*|Boolean\s*\()/, message: "Condition contains a redundant boolean cast.", severity: "advisory", pillar: "maintainability" },
   ];
 }
 
@@ -120,8 +120,8 @@ function literalLineChecks(): LineRuleCheck[] {
     { ruleId: "security.sql-concatenation", pattern: /\b(?:query|execute|raw)\s*\(\s*(?:`[^`]*(?:SELECT|INSERT|UPDATE|DELETE)[^`]*\$\{|["'][^"']*(?:SELECT|INSERT|UPDATE|DELETE)[^"']*["']\s*\+)/i, message: "SQL text is composed with runtime string interpolation.", severity: "warning", pillar: "security" },
     { ruleId: "modernisation.date-now-candidate", pattern: /\bnew\s+Date\s*\(\s*\)\s*\.getTime\s*\(\s*\)|\bNumber\s*\(\s*new\s+Date\s*\(\s*\)\s*\)/, message: "Current-time expression can use Date.now().", severity: "advisory", pillar: "modernisation" },
     { ruleId: "modernisation.object-spread-candidate", pattern: /\bObject\.assign\s*\(\s*\{\s*\}\s*,/, message: "Object.assign clone can usually use object spread.", severity: "advisory", pillar: "modernisation" },
-    { ruleId: "waste.console-log", pattern: /\bconsole\.(log|debug)\s*\(/, message: "console logging is committed in source.", severity: "advisory", pillar: "waste" },
-    { ruleId: "waste.any-type", pattern: /:\s*any\b|as\s+any\b/, message: "any weakens TypeScript's type guarantees.", severity: "warning", pillar: "waste" },
+    { ruleId: "waste.console-log", pattern: /\bconsole\.(log|debug)\s*\(/, message: "console logging is committed in source.", severity: "advisory", pillar: "maintainability" },
+    { ruleId: "waste.any-type", pattern: /:\s*any\b|as\s+any\b/, message: "any weakens TypeScript's type guarantees.", severity: "warning", pillar: "maintainability" },
     { ruleId: "modernisation.var-declaration", pattern: /\bvar\s+[A-Za-z_$]/, message: "var declaration should usually be let or const.", severity: "advisory", pillar: "modernisation" },
   ];
   return checks.map(withGlobalPattern);
@@ -143,7 +143,7 @@ function withGlobalPattern(check: LineRuleCheck): LineRuleCheck {
  */
 function pushCommentedOutCodeFinding(context: LineRuleContext): void {
   if (isCommentedOutCode(context.line)) {
-    context.findings.push(finding({ ruleId: "waste.commented-out-code", message: "Comment appears to contain disabled source code.", file: context.file, line: context.lineNumber, severity: "advisory", pillar: "waste" }));
+    context.findings.push(finding({ ruleId: "waste.commented-out-code", message: "Comment appears to contain disabled source code.", file: context.file, line: context.lineNumber, severity: "advisory", pillar: "maintainability" }));
   }
 }
 
@@ -279,19 +279,17 @@ function isSuppressedByPathContext(ruleId: string, displayPath: string): boolean
   return /(?:^|\/)(?:scripts|bin)\//.test(displayPath) || /(?:^|\/)cli[/.]/i.test(displayPath) || /(?:^|\/)server[/.]/i.test(displayPath);
 }
 
-// Per-line variable-name pass that runs short/identifier-quality/abbreviation checks on both
+// Per-line variable-name pass that runs short/identifier-quality checks on both
 // regular `const`/`let` declarations and destructured names. Reports any findings produced.
 function pushVariableNameFindings(context: LineRuleContext): void {
   for (const match of context.codeLine.matchAll(context.variables)) {
     const name = match[1] ?? "";
     pushShortVariableFinding(context, name);
     pushIdentifierQualityFinding(context, name);
-    pushAbbreviationAt(context.file, context.lineNumber, name, context.config, context.findings, "declaration");
   }
   for (const name of destructuredLocalNames(context.codeLine)) {
     pushShortVariableAt(context.file, context.lineNumber, name, context.config, context.findings, "destructure");
     pushIdentifierQualityAt(context.file, context.lineNumber, name, context.config, context.findings, "destructure");
-    pushAbbreviationAt(context.file, context.lineNumber, name, context.config, context.findings, "destructure");
   }
 }
 

package/src/naming-pushers.ts

@@ -124,37 +124,6 @@ export function pushIdentifierQualityAt(file: SourceFile, line: number, name: st
   );
 }
 
-/*
- * Reports `naming.abbreviation` when the name is on `abbreviationDenylist` and not on the user's
- * `acceptedAbbreviations` allowlist. `surface` distinguishes parameter / variable / interface-field
- * - same stable rule contract, different metadata, so consumers can filter on origin.
- */
-export function pushAbbreviationAt(file: SourceFile, line: number, name: string, config: Config, findings: Finding[], surface: NamingSurface): void {
-  if (config.rules.get("naming.abbreviation")?.enabled !== true) {
-    return;
-  }
-  if (config.acceptedAbbreviations.has(name.toLowerCase())) {
-    return;
-  }
-  if (!config.abbreviationDenylist.has(name.toLowerCase())) {
-    return;
-  }
-  findings.push(
-    makeFinding({
-      ruleId: "naming.abbreviation",
-      message: `Identifier \`${name}\` uses an opaque abbreviation.`,
-      filePath: file.displayPath,
-      line,
-      severity: "advisory",
-      pillar: "naming",
-      confidence: "medium",
-      symbol: name,
-      remediation: "Use the full domain term or add the abbreviation to allowlists.acceptedAbbreviations.",
-      metadata: { identifierName: name, surface },
-    }),
-  );
-}
-
 // Returns `"generic"` for low-information names from the configured set, `"numbered"` for
 // `foo1` / `bar2` style trailing-digit identifiers, or undefined when the name is acceptable.
 // The variant string lands in finding metadata so consumers can split the two failure modes.

package/src/project-config-rules.ts

@@ -198,7 +198,7 @@ function pushBroadRuntimeDependencyFinding(
       filePath: file.displayPath,
       line: jsonKeyLine(source, packageName),
       severity: "advisory",
-      pillar: "waste",
+      pillar: "maintainability",
       confidence: "medium",
       symbol: packageName,
       remediation: "Use a bounded semver range and rely on the lockfile for repeatable installs.",

package/src/report-renderers.ts

@@ -26,7 +26,7 @@ function renderReport(report: AnalysisReport, format: OutputFormat): string {
     case "github":
       return renderGithub(report);
     case "hotspot":
-      return JSON.stringify({ schemaVersion: "gruff.hotspot.v1", tool: report.tool, score: report.score.composite, files: report.score.topOffenders }, null, 2);
+      return JSON.stringify({ schemaVersion: "gruff.hotspot.v1", tool: report.tool, score: report.score.composite, files: report.score.topOffenders.slice(0, 10) }, null, 2);
     case "sarif":
       return renderSarif(report);
     case "text":
@@ -179,7 +179,7 @@ function sarifLevel(severity: Severity): "error" | "warning" | "note" {
  * because the CLI should be able to improve wording/layout without a schema bump; callers that need
  * durable machine output should use `analyse --format=json` instead.
  */
-function renderSummary(report: AnalysisReport, elapsedMs?: number, pathLabel?: string): string {
+function renderSummary(report: AnalysisReport, elapsedMs?: number, pathLabel?: string, top = 10): string {
   const pillarCounts = countBy(report.findings, (finding) => finding.pillar);
   const ruleCounts = countBy(report.findings, (finding) => finding.ruleId);
   const lines = [
@@ -189,25 +189,56 @@ function renderSummary(report: AnalysisReport, elapsedMs?: number, pathLabel?: s
     `Score: ${report.score.composite.toFixed(1)} (${report.score.grade})`,
     `Findings: ${report.summary.total} total, ${report.summary.error} error, ${report.summary.warning} warning, ${report.summary.advisory} advisory`,
     `Analysed files: ${report.paths.analysedFiles}`,
+    ...(report.baseline ? [summaryBaselineLine(report.baseline)] : []),
   ];
   if (report.diagnostics.length > 0) {
     lines.push("", "Diagnostics:", ...report.diagnostics.map(summaryDiagnosticLine));
   }
   lines.push("", "Per-pillar counts:");
   lines.push(...renderRankedCounts(pillarCounts, "No findings by pillar."));
-  lines.push("", "Top rules:");
-  lines.push(...renderRankedCounts(ruleCounts, "No rule findings."));
-  lines.push("", "Top file offenders:");
+  lines.push("", `Top ${top} rules:`);
+  lines.push(...renderRankedCounts(ruleCounts, "No rule findings.", top));
+  lines.push("", `Top ${top} file offenders:`);
   lines.push(
     ...(
       report.score.topOffenders.length === 0
         ? ["- No file offenders."]
-        : report.score.topOffenders.map((offender) => `- ${offender.filePath}: ${offender.findings} findings, score ${offender.score.toFixed(1)}`)
+        : report.score.topOffenders.slice(0, top).map((offender) => `- ${offender.filePath}: ${offender.findings} findings, score ${offender.score.toFixed(1)}`)
     ),
   );
   return `${lines.join("\n")}\n`;
 }
 
+/*
+ * Renders the stable public `gruff.summary.v1` JSON contract for the `summary --format=json` flow.
+ * The schema shape (scope/score/findings/topRules/topOffenders) is part of that contract - downstream
+ * CI integrations parse it, so field renames or removals are breaking changes for users.
+ */
+function renderSummaryJson(report: AnalysisReport, elapsedMs?: number, pathLabel?: string, top = 10): string {
+  const pillarCounts = countBy(report.findings, (finding) => finding.pillar);
+  const ruleCounts = countBy(report.findings, (finding) => finding.ruleId);
+  const payload = {
+    schemaVersion: "gruff.summary.v1",
+    tool: report.tool,
+    scope: {
+      paths: pathLabel ?? report.run.projectRoot,
+      projectRoot: report.run.projectRoot,
+      analysedFiles: report.paths.analysedFiles,
+      ignoredPaths: report.paths.ignoredPaths.length,
+      missingPaths: report.paths.missingPaths.length,
+      diagnostics: report.diagnostics.length,
+      elapsedSeconds: typeof elapsedMs === "number" ? Number((elapsedMs / 1000).toFixed(3)) : undefined,
+    },
+    score: report.score,
+    findings: report.summary,
+    baseline: report.baseline,
+    pillars: renderRankedCountRows(pillarCounts),
+    topRules: renderRankedCountRows(ruleCounts, top),
+    topOffenders: report.score.topOffenders.slice(0, top),
+  };
+  return `${JSON.stringify(payload, null, 2)}\n`;
+}
+
 // Shared text formatter for diagnostic rows in plain-text summaries and the `text` format. Stable
 // "- {type}: {message} (path)" shape is part of the contract that scripts grepping the text output
 // rely on, so the format must stay deterministic across both call sites.
@@ -216,6 +247,15 @@ function summaryDiagnosticLine(diagnostic: AnalysisReport["diagnostics"][number]
   return `- ${diagnostic.diagnosticType}: ${diagnostic.message}${location}`;
 }
 
+// Documents the summary baseline contract so suppressed findings are not mistaken for a clean scan.
+function summaryBaselineLine(baseline: NonNullable<AnalysisReport["baseline"]>): string {
+  if (baseline.generated) {
+    return `Baseline: generated ${baseline.path}; current findings still shown`;
+  }
+  const findingNoun = baseline.suppressed === 1 ? "finding" : "findings";
+  return `Baseline: ${baseline.source} ${baseline.path}; suppressed ${baseline.suppressed} ${findingNoun}`;
+}
+
 // Human-sized summary runtime without pretending sub-millisecond precision is useful.
 function formatSummaryDuration(elapsedMs: number): string {
   const bounded = Math.max(0, elapsedMs);
@@ -234,16 +274,23 @@ function countBy<T extends string>(findings: Finding[], keyFor: (finding: Findin
   return counts;
 }
 
-function renderRankedCounts<T extends string>(counts: Map<T, number>, emptyText: string): string[] {
+function renderRankedCounts<T extends string>(counts: Map<T, number>, emptyText: string, limit?: number): string[] {
   if (counts.size === 0) {
     return [`- ${emptyText}`];
   }
   return [...counts.entries()]
     .sort(([leftKey, leftCount], [rightKey, rightCount]) => rightCount - leftCount || leftKey.localeCompare(rightKey))
-    .slice(0, 10)
+    .slice(0, limit ?? counts.size)
     .map(([key, count]) => `- ${key}: ${count}`);
 }
 
+function renderRankedCountRows<T extends string>(counts: Map<T, number>, limit?: number): Array<{ name: T; count: number }> {
+  return [...counts.entries()]
+    .sort(([leftKey, leftCount], [rightKey, rightCount]) => rightCount - leftCount || leftKey.localeCompare(rightKey))
+    .slice(0, limit ?? counts.size)
+    .map(([name, count]) => ({ name, count }));
+}
+
 /*
  * Default terminal output. Findings are listed verbatim (no truncation) - the analyser keeps them
  * sorted into the stable order, so piping into `grep` produces deterministic results.
@@ -424,13 +471,15 @@ function htmlPillars(report: AnalysisReport): string {
   return `<section class="pillars"><h2 class="section-head">pillar grades <span class="aside">weighted composite</span></h2><div class="pillar-grid">${items}</div></section>`;
 }
 
-// Top-10 offender table, ordered by ascending score (worst first). `scoreReport` already truncated
-// the list to 10 - this stable, deterministic limit is part of the public report contract.
+// Top-10 offender table, ordered by ascending score (worst first). `scoreReport` returns the full
+// sorted list; summary and hotspot apply their own caps from the same source. The HTML report caps
+// at 10 rows so the visual layout stays stable regardless of project size - that 10 is the contract.
 function htmlOffenders(report: AnalysisReport): string {
   const rows =
     report.score.topOffenders.length === 0
       ? '<tr><td colspan="4">No offenders found.</td></tr>'
       : report.score.topOffenders
+          .slice(0, 10)
           .map((file) => {
             const letter = grade(file.score);
             return `<tr><td class="file-path">${htmlLocation(file.filePath)}</td><td class="num">${file.score.toFixed(1)}</td><td class="num">${file.findings}</td><td class="num"><span class="grade-pill ${gradeClass(letter)}">${letter}</span></td></tr>`;
@@ -688,4 +737,4 @@ function escapeHtml(htmlText: string): string {
   return htmlText.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
 }
 
-export { dashboardErrorHtml, dashboardHomeHtml, grade, renderHtml, renderReport, renderSummary };
+export { dashboardErrorHtml, dashboardHomeHtml, grade, renderHtml, renderReport, renderSummary, renderSummaryJson };

package/src/rule-list.ts

@@ -21,6 +21,7 @@ const CONSOLE_COMMANDS = [
   { name: "completion", description: "Dump the shell completion script" },
   { name: "dashboard", description: "Serve the local gruff dashboard." },
   { name: "help", description: "Display help for a command" },
+  { name: "init", description: "Write the default .gruff-ts.yaml to the current directory." },
   { name: "list", description: "List commands" },
   { name: "list-rules", description: "List gruff rule metadata." },
   { name: "report", description: "Render a gruff report to stdout or a file." },