@blundergoat/gruff-ts 0.1.0 → 0.1.1

package/src/rules.ts

@@ -27,7 +27,6 @@ const RULE_DESCRIPTORS: readonly RuleDescriptor[] = [
   { ruleId: "docs.stale-comment", pillar: "documentation", severity: "advisory", confidence: "medium", description: "Flags comments that reference missing files, unknown rules, stale CLI flags, or the wrong declaration.", remediation: "Update the comment or add historical context explaining why it remains useful." },
   { ruleId: "docs.stale-param-tag", pillar: "documentation", severity: "advisory", confidence: "medium", description: "Flags @param tags for parameters no longer in the signature.", remediation: "Remove stale tags or update the function signature." },
   { ruleId: "docs.suppression-without-rationale", pillar: "documentation", severity: "advisory", confidence: "medium", description: "Flags lint, formatter, coverage, or tool suppressions without a maintainer rationale.", remediation: "Explain why the suppression is intentional, a false positive, or tracked elsewhere." },
-  { ruleId: "docs.todo-density", pillar: "documentation", severity: "advisory", confidence: "high", description: "Flags files with a high count of TODO/FIXME markers (opt-in, disabled by default).", remediation: "Resolve stale markers, link them to tracked work, or enable docs.todo-without-tracking for context-aware coverage.", threshold: 4 },
   { ruleId: "docs.todo-without-tracking", pillar: "documentation", severity: "advisory", confidence: "high", description: "Flags TODO, FIXME, HACK, and XXX comments without tracking context.", remediation: "Attach a tracking URL, issue id, owner, date, ADR, or .goat-flow task reference." },
   { ruleId: "docs.useless-docblock", pillar: "documentation", severity: "advisory", confidence: "medium", description: "Flags comments or docblocks that only restate the symbol name.", remediation: "Replace the comment with useful contract or behavior detail." },
   { ruleId: "modernisation.date-now-candidate", pillar: "modernisation", severity: "advisory", confidence: "high", description: "Flags verbose current-time expressions that can use Date.now().", remediation: "Use Date.now() for current epoch milliseconds." },
@@ -44,7 +43,6 @@ const RULE_DESCRIPTORS: readonly RuleDescriptor[] = [
   { ruleId: "modernisation.tsconfig-index-safety-disabled", pillar: "modernisation", severity: "warning", confidence: "high", description: "Flags tsconfig files without noUncheckedIndexedAccess enabled.", remediation: "Enable noUncheckedIndexedAccess unless migration is blocked." },
   { ruleId: "modernisation.tsconfig-strict-disabled", pillar: "modernisation", severity: "warning", confidence: "high", description: "Flags tsconfig files without strict mode enabled.", remediation: "Enable strict unless migration is blocked." },
   { ruleId: "modernisation.var-declaration", pillar: "modernisation", severity: "advisory", confidence: "high", description: "Flags var declarations.", remediation: "Use let or const with the narrowest useful scope." },
-  { ruleId: "naming.abbreviation", pillar: "naming", severity: "advisory", confidence: "medium", description: "Flags identifiers in the project abbreviation denylist (opt-in, disabled by default).", remediation: "Use the full domain term or add the abbreviation to allowlists.acceptedAbbreviations." },
   { ruleId: "naming.acronym-case", pillar: "naming", severity: "advisory", confidence: "medium", description: "Flags mixed casings of a known acronym in one file.", remediation: "Use one casing for each acronym throughout the file." },
   { ruleId: "naming.boolean-prefix", pillar: "naming", severity: "advisory", confidence: "medium", description: "Flags boolean names without intent-revealing prefixes on declarations, function parameters (typed `: boolean` or with `= true|false` default), and interface/type-literal fields.", remediation: "Use prefixes such as is, has, can, should, or will." },
   { ruleId: "naming.class-file-mismatch", pillar: "naming", severity: "advisory", confidence: "medium", description: "Flags exported classes whose name differs from the file name.", remediation: "Rename the class or file so the primary export is easy to locate." },
@@ -109,20 +107,20 @@ const RULE_DESCRIPTORS: readonly RuleDescriptor[] = [
   { ruleId: "test-quality.snapshot-only-test", pillar: "test-quality", severity: "advisory", confidence: "high", description: "Flags tests that rely only on snapshots.", remediation: "Add targeted assertions for important behavior." },
   { ruleId: "test-quality.trivial-assertion", pillar: "test-quality", severity: "warning", confidence: "high", description: "Flags tautological assertions.", remediation: "Assert a real result from the system under test." },
   { ruleId: "test-quality.unused-mock", pillar: "test-quality", severity: "advisory", confidence: "medium", description: "Flags mocks created but not used.", remediation: "Remove unused mocks or wire them into the behavior under test." },
-  { ruleId: "waste.any-type", pillar: "waste", severity: "warning", confidence: "high", description: "Flags any type usage.", remediation: "Use unknown with validation or a precise type." },
-  { ruleId: "waste.broad-runtime-version", pillar: "waste", severity: "advisory", confidence: "medium", description: "Flags broad runtime dependency version ranges.", remediation: "Use bounded semver ranges and lockfiles." },
-  { ruleId: "waste.commented-out-code", pillar: "waste", severity: "advisory", confidence: "high", description: "Flags comments that appear to contain disabled code.", remediation: "Delete dead code or restore it behind a real feature path." },
-  { ruleId: "waste.console-log", pillar: "waste", severity: "advisory", confidence: "high", description: "Flags console log/debug calls in source.", remediation: "Remove debug logging or route through structured logging." },
-  { ruleId: "waste.empty-function", pillar: "waste", severity: "advisory", confidence: "high", description: "Flags functions with no executable body.", remediation: "Delete the function or add the missing implementation." },
-  { ruleId: "waste.exported-any", pillar: "waste", severity: "warning", confidence: "medium", description: "Flags exported APIs exposing any.", remediation: "Use a named interface, unknown with validation, or precise generics." },
-  { ruleId: "waste.redundant-boolean-cast", pillar: "waste", severity: "advisory", confidence: "medium", description: "Flags redundant boolean casts in condition expressions.", remediation: "Use the condition value directly or name the boolean conversion." },
-  { ruleId: "waste.redundant-variable", pillar: "waste", severity: "advisory", confidence: "medium", description: "Flags variables returned immediately after assignment.", remediation: "Return the expression directly." },
-  { ruleId: "waste.swallowed-catch", pillar: "waste", severity: "warning", confidence: "medium", description: "Flags empty catch blocks.", remediation: "Handle, report, rethrow, or document intentional ignore paths." },
-  { ruleId: "waste.useless-catch", pillar: "waste", severity: "advisory", confidence: "high", description: "Flags catch blocks that only rethrow the caught value.", remediation: "Remove the catch block or add meaningful handling." },
-  { ruleId: "waste.useless-return", pillar: "waste", severity: "advisory", confidence: "medium", description: "Flags terminal bare return statements in void functions.", remediation: "Remove the final return statement." },
-  { ruleId: "waste.unreachable-code", pillar: "waste", severity: "warning", confidence: "high", description: "Flags statements after terminating statements.", remediation: "Delete unreachable code or restructure the control flow." },
-  { ruleId: "waste.unused-import", pillar: "waste", severity: "advisory", confidence: "medium", description: "Flags named imports with no apparent usage.", remediation: "Remove unused imports." },
-  { ruleId: "waste.unused-parameter", pillar: "waste", severity: "advisory", confidence: "medium", description: "Flags parameters with no apparent usage.", remediation: "Remove the parameter or prefix it with _ if intentional." },
+  { ruleId: "waste.any-type", pillar: "maintainability", severity: "warning", confidence: "high", description: "Flags any type usage.", remediation: "Use unknown with validation or a precise type." },
+  { ruleId: "waste.broad-runtime-version", pillar: "maintainability", severity: "advisory", confidence: "medium", description: "Flags broad runtime dependency version ranges.", remediation: "Use bounded semver ranges and lockfiles." },
+  { ruleId: "waste.commented-out-code", pillar: "maintainability", severity: "advisory", confidence: "high", description: "Flags comments that appear to contain disabled code.", remediation: "Delete dead code or restore it behind a real feature path." },
+  { ruleId: "waste.console-log", pillar: "maintainability", severity: "advisory", confidence: "high", description: "Flags console log/debug calls in source.", remediation: "Remove debug logging or route through structured logging." },
+  { ruleId: "waste.empty-function", pillar: "maintainability", severity: "advisory", confidence: "high", description: "Flags functions with no executable body.", remediation: "Delete the function or add the missing implementation." },
+  { ruleId: "waste.exported-any", pillar: "maintainability", severity: "warning", confidence: "medium", description: "Flags exported APIs exposing any.", remediation: "Use a named interface, unknown with validation, or precise generics." },
+  { ruleId: "waste.redundant-boolean-cast", pillar: "maintainability", severity: "advisory", confidence: "medium", description: "Flags redundant boolean casts in condition expressions.", remediation: "Use the condition value directly or name the boolean conversion." },
+  { ruleId: "waste.redundant-variable", pillar: "maintainability", severity: "advisory", confidence: "medium", description: "Flags variables returned immediately after assignment.", remediation: "Return the expression directly." },
+  { ruleId: "waste.swallowed-catch", pillar: "maintainability", severity: "warning", confidence: "medium", description: "Flags empty catch blocks.", remediation: "Handle, report, rethrow, or document intentional ignore paths." },
+  { ruleId: "waste.useless-catch", pillar: "maintainability", severity: "advisory", confidence: "high", description: "Flags catch blocks that only rethrow the caught value.", remediation: "Remove the catch block or add meaningful handling." },
+  { ruleId: "waste.useless-return", pillar: "maintainability", severity: "advisory", confidence: "medium", description: "Flags terminal bare return statements in void functions.", remediation: "Remove the final return statement." },
+  { ruleId: "waste.unreachable-code", pillar: "maintainability", severity: "warning", confidence: "high", description: "Flags statements after terminating statements.", remediation: "Delete unreachable code or restructure the control flow." },
+  { ruleId: "waste.unused-import", pillar: "maintainability", severity: "advisory", confidence: "medium", description: "Flags named imports with no apparent usage.", remediation: "Remove unused imports." },
+  { ruleId: "waste.unused-parameter", pillar: "maintainability", severity: "advisory", confidence: "medium", description: "Flags parameters with no apparent usage.", remediation: "Remove the parameter or prefix it with _ if intentional." },
 ];
 
 /**

package/src/safety-rules.ts

@@ -38,7 +38,7 @@ export function analyseUselessCatches(file: SourceFile, source: string, findings
         filePath: file.displayPath,
         line: byteLine(source, match.index ?? 0),
         severity: "advisory",
-        pillar: "waste",
+        pillar: "maintainability",
         confidence: "high",
         remediation: "Remove the catch block or add meaningful handling.",
         metadata: { binding },
@@ -67,7 +67,7 @@ export function analyseSwallowedCatches(file: SourceFile, rawSource: string, cod
         filePath: file.displayPath,
         line: byteLine(rawSource, match.index ?? 0),
         severity: "warning",
-        pillar: "waste",
+        pillar: "maintainability",
         confidence: "medium",
         remediation: "Handle the error explicitly, rethrow it, or document an intentional ignore path.",
         metadata: { ...(binding ? { binding } : {}) },
@@ -180,7 +180,7 @@ function pushExportedAnyFinding(file: SourceFile, codeLine: string, lineNumber:
       filePath: file.displayPath,
       line: lineNumber,
       severity: "warning",
-      pillar: "waste",
+      pillar: "maintainability",
       confidence: "medium",
       symbol: exportedAny,
       remediation: "Use a named interface, unknown plus validation, or a precise generic type.",

package/src/scoring.ts

@@ -3,8 +3,9 @@ import { grade } from "./report-renderers.ts";
 import type { AnalysisReport, FailThreshold, Finding, Pillar, Severity } from "./types.ts";
 
 // Builds the per-pillar and per-file score breakdown that ships in `gruff.analysis.v1`. The composite
-// score is the mean of pillar scores so adding a pillar shifts the headline number, and `topOffenders`
-// is intentionally truncated to 10 - both shapes are part of the public report contract.
+// score is the mean of pillar scores so adding a pillar shifts the headline number. `topOffenders` is
+// the full file list sorted worst-first; renderers cap it themselves (HTML/hotspot keep their 10-row
+// UX, summary honours `--top`). The field shape is part of the `gruff.analysis.v1` schema contract.
 function scoreReport(findings: Finding[]): AnalysisReport["score"] {
   const byPillar = new Map<Pillar, Finding[]>();
   const byFile = new Map<string, Finding[]>();
@@ -23,8 +24,7 @@ function scoreReport(findings: Finding[]): AnalysisReport["score"] {
       score: Math.max(0, 100 - fileFindings.reduce((sum, finding) => sum + severityPenalty(finding.severity), 0)),
       findings: fileFindings.length,
     }))
-    .sort((left, right) => left.score - right.score)
-    .slice(0, 10);
+    .sort((left, right) => left.score - right.score);
   return { composite, grade: grade(composite), pillars, topOffenders };
 }
 

package/src/test-fixtures.ts

@@ -608,8 +608,6 @@ function catalogueCoverageOptions(): AnalyseProjectOptions {
           "complexity.cyclomatic": { threshold: 2, severity: "warning" },
           "complexity.npath": { threshold: 2, severity: "warning" },
           "design.large-module-concentration": { threshold: 35, severity: "advisory", options: { minFiles: 4, minLines: 8 } },
-          "docs.todo-density": { enabled: true, threshold: 1, severity: "advisory" },
-          "naming.abbreviation": { enabled: true },
           "size.file-length": { threshold: 8, severity: "warning" },
           "size.function-length": { threshold: 8, severity: "warning" },
           "size.parameter-count": { threshold: 3, severity: "warning" },

package/src/text-scans.ts

@@ -26,157 +26,6 @@ function firstLine(source: string, pattern: RegExp): number {
   return source.split(/\r?\n/).findIndex((line) => pattern.test(line)) + 1 || 1;
 }
 
-// Mutable lexer state threaded through the task-marker scanner. `quote === "\`"` survives across
-// newlines because template literals can span lines; ordinary quotes reset at end of line.
-interface TodoMarkerScanState {
-  isInBlockComment: boolean;
-  quote: string | undefined;
-  isEscaped: boolean;
-}
-
-// One scanner step yields the comment bytes for this position, how many extra characters to skip
-// (e.g., to consume `*/`), and whether the rest of the line is comment text (no need to keep scanning).
-interface CommentScanStep {
-  comment: string;
-  skip: number;
-  isDone: boolean;
-}
-
-// Task-marker counter consumed by the density rule. Skipping strings is mandatory - markers inside
-// string literals must not inflate the count, or every fixture string containing a task keyword
-// would trip. `isScript` flips `#` line-comment recognition for shell-like config files.
-function todoMarkerSummary(source: string, isScript: boolean): { count: number; firstLine: number } {
-  if (!source.includes("TODO") && !source.includes("FIXME")) {
-    return { count: 0, firstLine: 1 };
-  }
-  let count = 0;
-  let firstLine = 0;
-  const state: TodoMarkerScanState = { isInBlockComment: false, quote: undefined, isEscaped: false };
-
-  source.split(/\r?\n/).forEach((line, index) => {
-    const markerCount = countMatches(commentTextForLine(line, state, isScript), /\b(?:TODO|FIXME)\b/g);
-    if (markerCount === 0) {
-      return;
-    }
-    count += markerCount;
-    if (firstLine === 0) {
-      firstLine = index + 1;
-    }
-  });
-
-  return { count, firstLine: firstLine || 1 };
-}
-
-// Returns only the comment portions of `line` - strings, regex literals, and code are dropped.
-// Mutates `state` so block comments and template literals can carry across line boundaries.
-function commentTextForLine(line: string, state: TodoMarkerScanState, isScript: boolean): string {
-  let comment = "";
-  for (let index = 0; index < line.length; index += 1) {
-    const step = commentScanStep(line, index, state, isScript);
-    comment += step.comment;
-    index += step.skip;
-    if (step.isDone) {
-      break;
-    }
-  }
-  if (state.quote !== "`") {
-    state.quote = undefined;
-    state.isEscaped = false;
-  }
-  return comment;
-}
-
-// Three-state dispatcher: in a block comment, in a quoted string, or in executable code. Each
-// branch must be exhaustive - falling through would let a task keyword inside a string get counted.
-function commentScanStep(line: string, index: number, state: TodoMarkerScanState, isScript: boolean): CommentScanStep {
-  const character = line[index] ?? "";
-  const next = line[index + 1] ?? "";
-  if (state.isInBlockComment) {
-    return blockCommentScanStep(character, next, state);
-  }
-  if (state.quote) {
-    return quotedScanStep(character, state);
-  }
-  return openCodeCommentScanStep(line, index, state, isScript);
-}
-
-// Priority order: quote → block opener → line comment. Quotes must come first because `/* ... */`
-// inside a string is just text, and `// foo` inside a string would otherwise prematurely end scanning.
-function openCodeCommentScanStep(line: string, index: number, state: TodoMarkerScanState, isScript: boolean): CommentScanStep {
-  const character = line[index] ?? "";
-  const next = line[index + 1] ?? "";
-  const quoteStep = quoteStartScanStep(character, state);
-  if (quoteStep) {
-    return quoteStep;
-  }
-  const blockStep = blockStartScanStep(character, next, state);
-  if (blockStep) {
-    return blockStep;
-  }
-  return lineCommentScanStep(line, index, character, next, isScript);
-}
-
-// Detects opening quote of a string or template literal and mutates `state.quote` so subsequent
-// characters are routed through `quotedScanStep` rather than the code branch.
-function quoteStartScanStep(character: string, state: TodoMarkerScanState): CommentScanStep | undefined {
-  if (character === "\"" || character === "'" || character === "`") {
-    state.quote = character;
-    return emptyCommentScanStep();
-  }
-  return undefined;
-}
-
-// Detects `/*` opener. Returns `skip: 1` so the caller advances past `*` and does not re-enter on
-// the next character as if `*` were code.
-function blockStartScanStep(character: string, next: string, state: TodoMarkerScanState): CommentScanStep | undefined {
-  if (character === "/" && next === "*") {
-    state.isInBlockComment = true;
-    return { comment: "", skip: 1, isDone: false };
-  }
-  return undefined;
-}
-
-// Slices the comment payload after `//` (or `#` in config files) and signals `isDone: true` so the
-// caller stops walking the line - everything to the right is comment text.
-function lineCommentScanStep(line: string, index: number, character: string, next: string, isScript: boolean): CommentScanStep {
-  if (character === "/" && next === "/") {
-    return { comment: line.slice(index + 2), skip: line.length, isDone: true };
-  }
-  if (!isScript && character === "#") {
-    return { comment: line.slice(index + 1), skip: line.length, isDone: true };
-  }
-  return emptyCommentScanStep();
-}
-
-// Inside a block comment until `*/` is seen. Each character is treated as comment text so task
-// markers inside the block contribute to the count.
-function blockCommentScanStep(character: string, next: string, state: TodoMarkerScanState): CommentScanStep {
-  if (character === "*" && next === "/") {
-    state.isInBlockComment = false;
-    return { comment: "", skip: 1, isDone: false };
-  }
-  return { comment: character, skip: 0, isDone: false };
-}
-
-// Consumes the body of a string/template literal. `\` toggles `isEscaped` so the next character
-// is not interpreted as the closing quote - necessary for sequences like `"\""` and `"\\\""`.
-function quotedScanStep(character: string, state: TodoMarkerScanState): CommentScanStep {
-  if (state.isEscaped) {
-    state.isEscaped = false;
-  } else if (character === "\\") {
-    state.isEscaped = true;
-  } else if (character === state.quote) {
-    state.quote = undefined;
-  }
-  return emptyCommentScanStep();
-}
-
-// No-op step used by branches that consumed a character but produced no comment text - keeps the
-// caller loop branchless at the cost of one allocation per non-comment character.
-function emptyCommentScanStep(): CommentScanStep {
-  return { comment: "", skip: 0, isDone: false };
-}
-
 // One-based line number containing byte offset `index`. Used to anchor findings extracted from
 // regex match indices; off-by-one would shift every reported line in the resulting reports.
 function byteLine(source: string, index: number): number {
@@ -190,4 +39,4 @@ function byteLine(source: string, index: number): number {
   return line;
 }
 
-export { byteLine, countMatches, firstLine, todoMarkerSummary };
+export { byteLine, countMatches, firstLine };

package/src/types.ts

@@ -6,7 +6,7 @@ export type Pillar =
   | "size"
   | "complexity"
   | "dead-code"
-  | "waste"
+  | "maintainability"
   | "naming"
   | "documentation"
   | "modernisation"
@@ -48,7 +48,6 @@ export interface Config {
   booleanPrefixes: Set<string>;
   hungarianPrefixes: Set<string>;
   placeholderNames: Set<string>;
-  abbreviationDenylist: Set<string>;
   negativeBooleanAllowed: Set<string>;
   knownAcronyms: Set<string>;
   rules: Map<string, { enabled?: boolean; threshold?: number; severity?: Severity; options: Map<string, number> }>;