@blundergoat/gruff-ts 0.1.0

package/src/rule-list.ts

@@ -0,0 +1,179 @@
+// Console command catalogue, shell completion scripts, and rule-list renderers for CLI surfaces.
+import { VERSION } from "./constants.ts";
+import { ruleDescriptors } from "./rules.ts";
+
+type RuleListFormat = "text" | "json";
+type CompletionShell = "bash" | "fish" | "zsh";
+
+// Pre-formatted token strings, not arrays - the shell-specific renderers paste them straight into
+// completion scripts (bash `$commands`, zsh `_describe`, etc.) so the formatting must already be shell-safe.
+interface CompletionContext {
+  commands: string;
+  options: string;
+}
+
+const ANSI_GREEN = "\x1b[32m";
+const ANSI_YELLOW = "\x1b[33m";
+const ANSI_RESET_FG = "\x1b[39m";
+
+const CONSOLE_COMMANDS = [
+  { name: "analyse", description: "Run gruff analysis." },
+  { 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: "list", description: "List commands" },
+  { name: "list-rules", description: "List gruff rule metadata." },
+  { name: "report", description: "Render a gruff report to stdout or a file." },
+  {
+    name: "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.",
+  },
+] as const;
+
+// Rule catalogue renderer. JSON is the integration surface for docs and audits; text is allowed to
+// stay plain because it is only for terminal inspection and should not become another schema.
+function renderRuleList(format: RuleListFormat): string {
+  const descriptors = ruleDescriptors();
+  if (format === "json") {
+    return `${JSON.stringify({ tool: { name: "gruff-ts", version: VERSION }, rules: descriptors }, null, 2)}\n`;
+  }
+  const lines = ["gruff-ts " + VERSION + ` rules (${descriptors.length})`, ""];
+  for (const descriptor of descriptors) {
+    const threshold = typeof descriptor.threshold === "number" ? ` | threshold: ${descriptor.threshold}` : "";
+    const options = descriptor.optionKeys && descriptor.optionKeys.length > 0 ? ` | options: ${descriptor.optionKeys.join(",")}` : "";
+    lines.push(`${descriptor.ruleId} | ${descriptor.pillar} | ${descriptor.severity} | ${descriptor.confidence} | ${descriptor.description}${threshold}${options}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+// The Symfony-style command catalogue shown for `gruff-ts`, `gruff-ts list`, and `gruff-ts help`.
+// `shouldUseAnsi` is autodetected by the caller from TTY and `--ansi` flags, never from this layer.
+function renderConsoleList(shouldUseAnsi = false): string {
+  const listCommand = ansiWrap("list", ANSI_GREEN, shouldUseAnsi);
+  return [
+    "gruff-ts " + ansiWrap(VERSION, ANSI_GREEN, shouldUseAnsi),
+    "",
+    ansiWrap("Usage:", ANSI_YELLOW, shouldUseAnsi),
+    "  command [options] [arguments]",
+    "",
+    ansiWrap("Options:", ANSI_YELLOW, shouldUseAnsi),
+    formatConsoleRow("-h, --help", `Display help for the given command. When no command is given display help for the ${listCommand} command`, 22, shouldUseAnsi),
+    formatConsoleRow("    --silent", "Do not output any message", 22, shouldUseAnsi),
+    formatConsoleRow("-q, --quiet", "Only errors are displayed. All other output is suppressed", 22, shouldUseAnsi),
+    formatConsoleRow("-V, --version", "Display this application version", 22, shouldUseAnsi),
+    formatConsoleRow("    --ansi|--no-ansi", "Force (or disable --no-ansi) ANSI output", 22, shouldUseAnsi),
+    formatConsoleRow("-n, --no-interaction", "Do not ask any interactive question", 22, shouldUseAnsi),
+    formatConsoleRow("-v|vv|vvv, --verbose", "Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug", 22, shouldUseAnsi),
+    "",
+    ansiWrap("Available commands:", ANSI_YELLOW, shouldUseAnsi),
+    ...CONSOLE_COMMANDS.map((command) => formatConsoleRow(command.name, command.description, 12, shouldUseAnsi)),
+  ].join("\n") + "\n";
+}
+
+// Two-column row: label padded to `width`, then description. Width is fixed per section so the
+// catalogue lines up regardless of label length - matches Symfony console output conventions.
+function formatConsoleRow(label: string, description: string, width: number, shouldUseAnsi: boolean): string {
+  const paddedLabel = ansiWrap(label, ANSI_GREEN, shouldUseAnsi);
+  const padding = " ".repeat(Math.max(1, width - label.length));
+  const rowDescription = description;
+  return `  ${paddedLabel}${padding}${rowDescription}`;
+}
+
+// `shouldUseAnsi` is the only gate. We never sniff `process.stdout.isTTY` here because the caller may be
+// rendering to a file or capture buffer where ANSI codes would be garbage.
+function ansiWrap(text: string, color: string, shouldUseAnsi: boolean): string {
+  if (!shouldUseAnsi) {
+    return text;
+  }
+  const ansiColor = color;
+  return `${ansiColor}${text}${ANSI_RESET_FG}`;
+}
+
+// Dispatches by shell with bash as the default - chosen because bash completion is most likely to
+// be installed and least likely to break silently if the user pipes the output through `source`.
+function renderCompletionScript(shell: CompletionShell): string {
+  const context = completionContext();
+  if (shell === "fish") {
+    return renderFishCompletion(context);
+  }
+  if (shell === "zsh") {
+    return renderZshCompletion(context);
+  }
+  return renderBashCompletion(context);
+}
+
+// Filters out `help` from the completion list - Commander handles it implicitly and exposing it
+// would suggest `gruff-ts help` is a real subcommand on equal footing with `analyse`.
+function completionContext(): CompletionContext {
+  return {
+    commands: CONSOLE_COMMANDS.filter((command) => command.name !== "help").map((command) => command.name).join(" "),
+    options: "-h --help --silent -q --quiet -V --version --ansi --no-ansi -n --no-interaction -v -vv -vvv --verbose",
+  };
+}
+
+// Fish's `complete` builtin is invoked once per token. Trailing newline matters - fish ignores
+// the final entry without one.
+function renderFishCompletion(context: CompletionContext): string {
+  return [
+    "complete -c gruff-ts -f",
+    ...context.commands.split(" ").map((command) => `complete -c gruff-ts -n '__fish_use_subcommand' -a '${command}'`),
+    ...context.options.split(" ").map((option) => `complete -c gruff-ts -a '${option}'`),
+    "",
+  ].join("\n");
+}
+
+// `#compdef gruff-ts` must be on line 1 - zsh's autoloader rejects the file otherwise. Uses
+// `_arguments` rather than `_describe` so option completion still works after a subcommand.
+function renderZshCompletion(context: CompletionContext): string {
+  return [
+    "#compdef gruff-ts",
+    "_gruff_ts() {",
+    "  local -a commands",
+    `  commands=(${context.commands})`,
+    "  _arguments '1:command:->commands' '*::arg:->args'",
+    "  case $state in",
+    "    commands) _describe 'command' commands ;;",
+    "    args) _values 'option' " + context.options.split(" ").map((option) => `'${option}'`).join(" ") + " ;;",
+    "  esac",
+    "}",
+    "_gruff_ts \"$@\"",
+    "",
+  ].join("\n");
+}
+
+// Bash completion: a function registered via `complete -F`. The `--format` / `--fail-on` value
+// lists are duplicated from `cli-program.ts` because completion runs without loading the analyser.
+function renderBashCompletion({ commands, options }: CompletionContext): string {
+  const commandsLine = `  commands=\"${commands}\"`;
+  const optionsLine = `  options=\"${options}\"`;
+  return [
+    "_gruff_ts_completion() {",
+    "  local current previous commands options",
+    "  COMPREPLY=()",
+    "  current=\"${COMP_WORDS[COMP_CWORD]}\"",
+    "  previous=\"${COMP_WORDS[COMP_CWORD-1]}\"",
+    commandsLine,
+    optionsLine,
+    "  if [ \"$COMP_CWORD\" -eq 1 ]; then",
+    "    COMPREPLY=( $(compgen -W \"$commands $options\" -- \"$current\") )",
+    "  else",
+    "    case \"$previous\" in",
+    "      --format) COMPREPLY=( $(compgen -W \"text json html markdown github hotspot sarif\" -- \"$current\") ) ;;",
+    "      --fail-on) COMPREPLY=( $(compgen -W \"none advisory warning error\" -- \"$current\") ) ;;",
+    "      *) COMPREPLY=( $(compgen -W \"$options\" -- \"$current\") ) ;;",
+    "    esac",
+    "  fi",
+    "}",
+    "complete -F _gruff_ts_completion gruff-ts",
+    "",
+  ].join("\n");
+}
+
+// Bash is the fallback for any unknown shell name - see `renderCompletionScript` for why bash wins.
+function completionShell(shellName: unknown): CompletionShell {
+  return shellName === "fish" || shellName === "zsh" ? shellName : "bash";
+}
+
+export type { RuleListFormat, CompletionShell };
+export { renderRuleList, renderConsoleList, renderCompletionScript, completionShell };

package/src/rules.ts

@@ -0,0 +1,135 @@
+// Rule descriptor catalogue that defines the public rule metadata emitted by list-rules and reports.
+import type { RuleDescriptor } from "./types.ts";
+
+const RULE_DESCRIPTORS: readonly RuleDescriptor[] = [
+  { ruleId: "complexity.cognitive", pillar: "complexity", severity: "warning", confidence: "high", description: "Flags functions with high combined branch and nesting complexity.", remediation: "Split nested decisions into smaller named functions.", threshold: 15 },
+  { ruleId: "complexity.cyclomatic", pillar: "complexity", severity: "warning", confidence: "high", description: "Flags functions with many independent branch paths.", remediation: "Reduce branching or move policy tables out of imperative code.", threshold: 15 },
+  { ruleId: "complexity.npath", pillar: "complexity", severity: "warning", confidence: "medium", description: "Flags functions with high approximate NPath complexity.", remediation: "Break apart compound branch combinations.", threshold: 200 },
+  { ruleId: "dead-code.unused-private-method", pillar: "dead-code", severity: "advisory", confidence: "low", description: "Flags private methods without an apparent same-file call site.", remediation: "Remove the method or add a direct call site." },
+  { ruleId: "design.circular-import", pillar: "design", severity: "warning", confidence: "medium", description: "Flags simple relative import cycles inside the discovered source set.", remediation: "Extract the shared contract or invert one dependency." },
+  { ruleId: "design.deep-relative-import", pillar: "design", severity: "advisory", confidence: "medium", description: "Flags relative imports that climb too many parent directories.", remediation: "Move the shared module closer or add a local boundary.", threshold: 2 },
+  { ruleId: "design.god-function", pillar: "design", severity: "warning", confidence: "high", description: "Flags functions that are both long and complex.", remediation: "Split responsibilities into smaller functions." },
+  { ruleId: "design.large-module-concentration", pillar: "design", severity: "advisory", confidence: "medium", description: "Flags a production module that dominates project source lines.", remediation: "Split unrelated responsibilities once stable seams are visible.", threshold: 55, optionKeys: ["minFiles", "minLines"] },
+  { ruleId: "design.package-bin-missing", pillar: "design", severity: "warning", confidence: "high", description: "Flags package bin entries that point at missing files.", remediation: "Update the bin path or add the executable file." },
+  { ruleId: "design.package-bin-not-executable", pillar: "design", severity: "warning", confidence: "high", description: "Flags package bin targets that are not executable.", remediation: "Make the bin target executable and keep its shebang valid." },
+  { ruleId: "docs.fixture-purpose-missing", pillar: "documentation", severity: "advisory", confidence: "medium", description: "Flags large or scanner-relevant fixtures without a nearby purpose comment.", remediation: "Explain what scanner path, regression, or fixture behavior the source covers." },
+  { ruleId: "docs.magic-threshold-without-rationale", pillar: "documentation", severity: "advisory", confidence: "medium", description: "Flags threshold-like numeric values without a nearby rationale comment.", remediation: "Explain the threshold, limit, budget, or default near the value." },
+  { ruleId: "docs.missing-error-behavior-doc", pillar: "documentation", severity: "advisory", confidence: "medium", description: "Flags commented functions whose error behavior is not described.", remediation: "Document thrown errors, diagnostics, exits, reports, or recovery behavior." },
+  { ruleId: "docs.missing-file-overview", pillar: "documentation", severity: "advisory", confidence: "medium", description: "Flags source files without a top-of-file purpose comment.", remediation: "Add a brief file overview before imports or declarations." },
+  { ruleId: "docs.missing-function-doc", pillar: "documentation", severity: "advisory", confidence: "medium", description: "Flags functions without a leading maintainer comment.", remediation: "Add a short JSDoc or line comment explaining the function's purpose." },
+  { ruleId: "docs.missing-interface-doc", pillar: "documentation", severity: "advisory", confidence: "medium", description: "Flags interfaces without a leading maintainer comment.", remediation: "Add a short JSDoc or line comment explaining the interface contract." },
+  { ruleId: "docs.missing-invariant-doc", pillar: "documentation", severity: "advisory", confidence: "medium", description: "Flags commented declarations that own schema, fingerprint, baseline, or determinism contracts without saying so.", remediation: "Document the invariant, contract, schema, fingerprint, or deterministic behavior." },
+  { ruleId: "docs.missing-param-tag", pillar: "documentation", severity: "advisory", confidence: "medium", description: "Flags documented exports with parameters missing @param tags.", remediation: "Document every current parameter in the JSDoc." },
+  { ruleId: "docs.missing-public-doc", pillar: "documentation", severity: "advisory", confidence: "medium", description: "Flags exported class, type, and enum APIs without a nearby doc comment.", remediation: "Add a short comment explaining the public API contract." },
+  { ruleId: "docs.missing-return-tag", pillar: "documentation", severity: "advisory", confidence: "medium", description: "Flags documented non-void exports without @returns.", remediation: "Document the returned value or remove stale JSDoc." },
+  { ruleId: "docs.missing-side-effect-doc", pillar: "documentation", severity: "advisory", confidence: "medium", description: "Flags commented functions that perform observable side effects without naming them.", remediation: "Name the filesystem, process, environment, network, or persistence side effect." },
+  { ruleId: "docs.missing-why-for-complex-code", pillar: "documentation", severity: "advisory", confidence: "medium", description: "Flags comments on complex functions that do not explain why the shape exists.", remediation: "Explain the tradeoff, compatibility reason, or invariant behind the complex control flow." },
+  { 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." },
+  { ruleId: "modernisation.double-cast", pillar: "modernisation", severity: "warning", confidence: "medium", description: "Flags casts through unknown or any into another type.", remediation: "Use a parser, type guard, or narrower assertion." },
+  { ruleId: "modernisation.loose-equality", pillar: "modernisation", severity: "advisory", confidence: "medium", description: "Flags loose equality comparisons that may coerce values.", remediation: "Use === or !== unless intentionally checking nullish values." },
+  { ruleId: "modernisation.non-null-assertion", pillar: "modernisation", severity: "warning", confidence: "medium", description: "Flags non-null assertions that bypass null checks.", remediation: "Narrow the value or handle null and undefined explicitly." },
+  { ruleId: "modernisation.nullish-coalescing-candidate", pillar: "modernisation", severity: "advisory", confidence: "medium", description: "Flags || fallbacks that may erase valid falsy values.", remediation: "Use ?? when only null or undefined should fall back." },
+  { ruleId: "modernisation.object-spread-candidate", pillar: "modernisation", severity: "advisory", confidence: "medium", description: "Flags Object.assign({}, ...) cloning that can use object spread.", remediation: "Use object spread when shallow-cloning plain objects." },
+  { ruleId: "modernisation.optional-chaining-candidate", pillar: "modernisation", severity: "advisory", confidence: "medium", description: "Flags repeated guard-and-property access patterns.", remediation: "Use optional chaining for clearer null-safe access." },
+  { ruleId: "modernisation.public-property", pillar: "modernisation", severity: "advisory", confidence: "high", description: "Flags public class properties that expose representation.", remediation: "Prefer readonly properties or accessors when invariants matter." },
+  { ruleId: "modernisation.readonly-property-candidate", pillar: "modernisation", severity: "advisory", confidence: "medium", description: "Flags class properties that appear readonly-worthy.", remediation: "Mark the property readonly when mutation is not part of the contract." },
+  { ruleId: "modernisation.ts-comment-without-rationale", pillar: "modernisation", severity: "warning", confidence: "medium", description: "Flags TypeScript suppression comments without a rationale.", remediation: "Add a short reason or remove the suppression." },
+  { ruleId: "modernisation.tsconfig-exact-optional-disabled", pillar: "modernisation", severity: "warning", confidence: "high", description: "Flags tsconfig files without exactOptionalPropertyTypes enabled.", remediation: "Enable exactOptionalPropertyTypes unless migration is blocked." },
+  { 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." },
+  { ruleId: "naming.generic-function", pillar: "naming", severity: "advisory", confidence: "high", description: "Flags generic function names that hide intent.", remediation: "Name the domain action instead of a generic operation." },
+  { ruleId: "naming.generic-parameter", pillar: "naming", severity: "advisory", confidence: "medium", description: "Flags placeholder parameter names in multi-parameter, long, exported, or complex functions.", remediation: "Use a name that describes the parameter's role.", optionKeys: ["minCyclomatic", "minLineCount", "minParameters"] },
+  { ruleId: "naming.hungarian-notation", pillar: "naming", severity: "advisory", confidence: "medium", description: "Flags identifiers named after storage type prefixes.", remediation: "Name the domain concept instead of the storage type." },
+  { ruleId: "naming.identifier-quality", pillar: "naming", severity: "advisory", confidence: "medium", description: "Flags placeholder or numbered identifiers on declarations, function parameters, and destructured locals.", remediation: "Use names that explain domain role or intent." },
+  { ruleId: "naming.inconsistent-casing", pillar: "naming", severity: "advisory", confidence: "medium", description: "Flags the same canonical identifier appearing in two different surface forms (for example CONSTANT_CASE and camelCase) in one file.", remediation: "Choose one form and use it consistently within the file." },
+  { ruleId: "naming.negative-boolean", pillar: "naming", severity: "advisory", confidence: "medium", description: "Flags boolean identifiers framed as a negation on declarations, parameters, and interface fields.", remediation: "Invert the framing so callers do not read a double negation." },
+  { ruleId: "naming.short-variable", pillar: "naming", severity: "advisory", confidence: "medium", description: "Flags very short variable names outside common loop counters; covers declarations, function parameters, and destructured locals.", remediation: "Use a name that describes the domain role." },
+  { ruleId: "security.async-foreach", pillar: "security", severity: "warning", confidence: "medium", description: "Flags async callbacks passed to forEach.", remediation: "Use for...of with await, Promise.all, or an explicit queue." },
+  { ruleId: "security.disabled-tls-verification", pillar: "security", severity: "error", confidence: "high", description: "Flags code that disables TLS certificate verification.", remediation: "Remove the override and fix certificate trust at the source." },
+  { ruleId: "security.document-write", pillar: "security", severity: "warning", confidence: "high", description: "Flags document.write usage.", remediation: "Use safe DOM APIs and encode untrusted content." },
+  { ruleId: "security.dynamic-regexp", pillar: "security", severity: "warning", confidence: "medium", description: "Flags external input used to construct regular expressions.", remediation: "Use a fixed pattern, escape user input, or enforce strict length and character limits." },
+  { ruleId: "security.eval-call", pillar: "security", severity: "error", confidence: "high", description: "Flags eval() dynamic code execution.", remediation: "Replace eval with explicit parsing or a safe dispatch table." },
+  { ruleId: "security.floating-promise", pillar: "security", severity: "warning", confidence: "medium", description: "Flags promise-like calls without await, return, or void.", remediation: "Await it, return it, or mark intentional fire-and-forget with void." },
+  { ruleId: "security.github-actions-broad-permissions", pillar: "security", severity: "warning", confidence: "medium", description: "Flags GitHub Actions workflows that grant broad write permissions.", remediation: "Reduce workflow permissions to read-only by default and grant write scopes only to trusted jobs." },
+  { ruleId: "security.github-actions-pull-request-target", pillar: "security", severity: "warning", confidence: "medium", description: "Flags pull_request_target workflows paired with risky execution or trust context.", remediation: "Use pull_request for untrusted code or isolate checkout, secrets, and write permissions behind trust checks." },
+  { ruleId: "security.github-actions-remote-shell", pillar: "security", severity: "warning", confidence: "medium", description: "Flags workflow run steps that pipe remote downloads to a shell.", remediation: "Vendor the installer, pin an audited action, or verify downloaded content before execution." },
+  { ruleId: "security.github-actions-secrets-in-pr", pillar: "security", severity: "warning", confidence: "medium", description: "Flags pull request workflows that reference GitHub secrets.", remediation: "Avoid exposing secrets to pull request workflows unless the code path is trusted and tightly gated." },
+  { ruleId: "security.github-actions-unpinned-action", pillar: "security", severity: "warning", confidence: "medium", description: "Flags third-party GitHub Actions that are not pinned to a full commit SHA.", remediation: "Pin third-party actions to a reviewed 40-character commit SHA and update them deliberately." },
+  { ruleId: "security.inner-html", pillar: "security", severity: "warning", confidence: "high", description: "Flags innerHTML assignment.", remediation: "Use safe DOM APIs or sanitize trusted HTML centrally." },
+  { ruleId: "security.insecure-random", pillar: "security", severity: "warning", confidence: "high", description: "Flags Math.random usage in source.", remediation: "Use crypto-backed randomness for security-sensitive values." },
+  { ruleId: "security.javascript-url", pillar: "security", severity: "error", confidence: "high", description: "Flags javascript: URL literals that execute script.", remediation: "Use safe routes or event handlers instead of executable URL strings." },
+  { ruleId: "security.new-function", pillar: "security", severity: "error", confidence: "high", description: "Flags Function constructor dynamic code execution.", remediation: "Replace dynamic construction with explicit functions or dispatch." },
+  { ruleId: "security.open-redirect-candidate", pillar: "security", severity: "warning", confidence: "medium", description: "Flags external input sent to redirect or navigation sinks.", remediation: "Redirect only to relative paths or destinations from an allowlist." },
+  { ruleId: "security.path-traversal-candidate", pillar: "security", severity: "warning", confidence: "medium", description: "Flags external input sent to filesystem path sinks.", remediation: "Validate paths against an allowlist and resolve them under a safe root." },
+  { ruleId: "security.process-exec", pillar: "security", severity: "warning", confidence: "high", description: "Flags child-process execution calls.", remediation: "Validate arguments and prefer fixed command vectors." },
+  { ruleId: "security.proto-access", pillar: "security", severity: "warning", confidence: "medium", description: "Flags direct __proto__ access that can enable prototype pollution.", remediation: "Use Object.getPrototypeOf, Object.create(null), or validated keys." },
+  { ruleId: "security.remote-install-script", pillar: "security", severity: "error", confidence: "medium", description: "Flags package scripts that pipe remote content to a shell.", remediation: "Vendor, pin, or remove remote shell execution." },
+  { ruleId: "security.risky-lifecycle-script", pillar: "security", severity: "warning", confidence: "medium", description: "Flags package lifecycle scripts that run automatically.", remediation: "Move setup behind an explicit command when possible." },
+  { ruleId: "security.sql-concatenation", pillar: "security", severity: "warning", confidence: "high", description: "Flags SQL text composed with runtime string interpolation.", remediation: "Use parameterized queries or query builders." },
+  { ruleId: "security.ssrf-candidate", pillar: "security", severity: "warning", confidence: "medium", description: "Flags external input sent to network request sinks.", remediation: "Validate destinations against an allowlist and block internal hosts." },
+  { ruleId: "security.string-timer", pillar: "security", severity: "warning", confidence: "high", description: "Flags string callbacks passed to timers.", remediation: "Pass a function callback instead of source text." },
+  { ruleId: "security.throw-non-error", pillar: "security", severity: "warning", confidence: "medium", description: "Flags thrown non-Error values.", remediation: "Throw an Error subclass with a clear message." },
+  { ruleId: "security.url-dependency", pillar: "security", severity: "warning", confidence: "medium", description: "Flags dependencies installed from URL or git specs.", remediation: "Prefer registry versions that can be locked and audited." },
+  { ruleId: "security.weak-crypto", pillar: "security", severity: "warning", confidence: "high", description: "Flags weak crypto primitives such as md5, sha1, or createCipher.", remediation: "Use modern algorithms and authenticated encryption." },
+  { ruleId: "sensitive-data.api-key-pattern", pillar: "sensitive-data", severity: "error", confidence: "high", description: "Flags vendor API key patterns.", remediation: "Remove the secret and load it from a secure runtime source." },
+  { ruleId: "sensitive-data.aws-access-key", pillar: "sensitive-data", severity: "error", confidence: "high", description: "Flags AWS access key looking values.", remediation: "Remove the key and rotate it immediately." },
+  { ruleId: "sensitive-data.database-url-password", pillar: "sensitive-data", severity: "error", confidence: "high", description: "Flags database URLs that include passwords.", remediation: "Move credentials into a secret store or runtime environment." },
+  { ruleId: "sensitive-data.hardcoded-env-value", pillar: "sensitive-data", severity: "error", confidence: "medium", description: "Flags environment-style secret values committed in text.", remediation: "Load secret-like values from secure runtime configuration.", threshold: 16 },
+  { ruleId: "sensitive-data.high-entropy-string", pillar: "sensitive-data", severity: "error", confidence: "medium", description: "Flags high-entropy string literals that may be secrets.", remediation: "Remove the value and load it from a secure runtime source.", threshold: 32 },
+  { ruleId: "sensitive-data.jwt-token", pillar: "sensitive-data", severity: "error", confidence: "high", description: "Flags JWT-looking token literals.", remediation: "Remove the token and rotate the credential if real." },
+  { ruleId: "sensitive-data.pii-pattern", pillar: "sensitive-data", severity: "error", confidence: "high", description: "Flags PII-like identifier patterns.", remediation: "Remove personal data from source and fixtures." },
+  { ruleId: "sensitive-data.private-key", pillar: "sensitive-data", severity: "error", confidence: "high", description: "Flags private key block markers.", remediation: "Remove the key material and rotate affected credentials." },
+  { ruleId: "size.file-length", pillar: "size", severity: "warning", confidence: "high", description: "Flags files longer than the configured threshold.", remediation: "Split unrelated responsibilities into smaller files.", threshold: 750 },
+  { ruleId: "size.function-length", pillar: "size", severity: "warning", confidence: "high", description: "Flags functions longer than the configured threshold.", remediation: "Extract named helpers or split workflows.", threshold: 200 },
+  { ruleId: "size.parameter-count", pillar: "size", severity: "warning", confidence: "high", description: "Flags functions with too many parameters.", remediation: "Group related options or reduce the function's responsibility.", threshold: 7 },
+  { ruleId: "size.stylesheet-length", pillar: "size", severity: "warning", confidence: "high", description: "Flags stylesheets longer than the configured threshold.", remediation: "Split unrelated component styles into smaller files.", threshold: 1500 },
+  { ruleId: "test-quality.conditional-logic", pillar: "test-quality", severity: "advisory", confidence: "high", description: "Flags tests with conditional logic.", remediation: "Split branch-specific expectations into separate tests." },
+  { ruleId: "test-quality.exception-type-only", pillar: "test-quality", severity: "advisory", confidence: "high", description: "Flags tests that only assert exception type.", remediation: "Assert message, code, or observable behavior as well." },
+  { ruleId: "test-quality.global-state-mutation", pillar: "test-quality", severity: "warning", confidence: "high", description: "Flags tests mutating process or global runtime state.", remediation: "Isolate state changes and restore them around the test." },
+  { ruleId: "test-quality.loop-in-test", pillar: "test-quality", severity: "advisory", confidence: "high", description: "Flags loops inside test bodies.", remediation: "Use table tests or separate named cases." },
+  { ruleId: "test-quality.magic-number-assertion", pillar: "test-quality", severity: "advisory", confidence: "medium", description: "Flags assertions against unexplained numeric literals.", remediation: "Name expected values or assert domain-specific outcomes." },
+  { ruleId: "test-quality.missing-nearby-test", pillar: "test-quality", severity: "advisory", confidence: "medium", description: "Flags exported production files without nearby tests.", remediation: "Add a focused test beside the source or in a nearby test directory." },
+  { ruleId: "test-quality.mock-only-test", pillar: "test-quality", severity: "advisory", confidence: "high", description: "Flags tests that only verify mock interaction.", remediation: "Assert observable behavior in addition to collaboration." },
+  { ruleId: "test-quality.no-assertions", pillar: "test-quality", severity: "warning", confidence: "high", description: "Flags tests without apparent assertions.", remediation: "Add assertions for observable behavior." },
+  { ruleId: "test-quality.no-throw-only-test", pillar: "test-quality", severity: "advisory", confidence: "high", description: "Flags tests that only assert code does not throw.", remediation: "Assert the observable result or state change." },
+  { ruleId: "test-quality.only-skip", pillar: "test-quality", severity: "advisory", confidence: "high", description: "Flags focused or skipped test markers.", remediation: "Remove .only and either enable or delete skipped tests." },
+  { ruleId: "test-quality.setup-bloat", pillar: "test-quality", severity: "advisory", confidence: "medium", description: "Flags tests with too much setup before the first assertion.", remediation: "Extract builders or reduce fixture setup.", threshold: 12 },
+  { ruleId: "test-quality.sleep-in-test", pillar: "test-quality", severity: "advisory", confidence: "high", description: "Flags sleeps in tests.", remediation: "Synchronize on behavior instead of wall-clock time." },
+  { 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." },
+];
+
+/**
+ * Return the deterministic rule catalogue used by list-rules.
+ *
+ * @returns Sorted rule descriptor metadata.
+ */
+export function ruleDescriptors(): RuleDescriptor[] {
+  return [...RULE_DESCRIPTORS].sort((left, right) => left.ruleId.localeCompare(right.ruleId));
+}