@blundergoat/gruff-ts 0.1.0

package/src/context-doc-rules.ts

@@ -0,0 +1,241 @@
+// Context-doc rules: emit findings when a function or interface comment exists but does not
+// describe the WHY (complex control flow), side effects, error behavior, or public-contract
+// invariants the implementation carries. Each rule reports a stable, deterministic finding.
+import { approximateNpath, functionBodyContent, type FunctionBlock, maxNestingDepth } from "./blocks.ts";
+import { type CommentRecord } from "./comment-scanner.ts";
+import { threshold } from "./config.ts";
+import { type SourceFile } from "./discovery.ts";
+import { makeFinding } from "./findings.ts";
+import { countMatches } from "./text-scans.ts";
+import type { Config, Finding } from "./types.ts";
+
+// Generic declaration shape used by both function and interface comment-quality rules so they can
+// share `pushStaleDeclarationCommentFinding` and `pushRestatingSignatureCommentFinding` logic.
+export interface CommentedDeclaration {
+  kind: "function" | "interface";
+  name: string;
+  line: number;
+  isPublic: boolean;
+}
+
+type ContextDocFindingDetails = {
+  symbol: string;
+  ruleId: string;
+  message: string;
+  remediation: string;
+  metadata: Record<string, string>;
+};
+
+type ContextDocFindingInput = ContextDocFindingDetails & {
+  file: SourceFile;
+  comment: CommentRecord;
+};
+
+// Materialises one finding per missing context class. Each callable can theoretically produce
+// four (complex, side-effect, error-behavior, invariant) - the four classes are independent signals.
+// Reports each detected gap as a stable doc-context finding.
+export function pushFunctionContextFindings(file: SourceFile, block: FunctionBlock, comment: CommentRecord, config: Config, findings: Finding[]): void {
+  for (const detail of functionContextDocFindings(block, comment.text, config)) {
+    findings.push(contextDocFinding({ file, comment, ...detail }));
+  }
+}
+
+/*
+ * Interface-only context-doc rule. The caller is responsible for skipping signature-restatement
+ * comments so the useless-docblock rule's stable finding doesn't get duplicated by this one.
+ * Reports `docs.missing-invariant-doc` for interfaces that carry public-contract signals.
+ */
+export function pushDeclarationContextFindings(file: SourceFile, lines: string[], declaration: CommentedDeclaration, comment: CommentRecord, findings: Finding[]): void {
+  if (declaration.kind !== "interface") {
+    return;
+  }
+  if (!hasInvariantInterfaceSignal(lines, declaration) || hasInvariantMarker(comment.text)) {
+    return;
+  }
+  findings.push(
+    contextDocFinding({
+      file,
+      comment,
+      ...contextDocDetails(declaration.name, "docs.missing-invariant-doc", `Interface \`${declaration.name}\` defines a public contract that its comment does not describe.`, "Document the schema, fingerprint, baseline, report, or determinism invariant.", "invariant"),
+    }),
+  );
+}
+
+// Evaluates four context classes independently - collected into a list rather than emitted directly
+// so the caller can apply a single stable mapping over them.
+function functionContextDocFindings(block: FunctionBlock, commentText: string, config: Config): ContextDocFindingDetails[] {
+  const details: ContextDocFindingDetails[] = [];
+  const body = block.codeBody;
+  const complex = complexFunctionContextDocFinding(block, commentText, config);
+  const sideEffect = sideEffectContextDocFinding(block, body, commentText);
+  const errorBehavior = errorBehaviorContextDocFinding(block, body, commentText);
+  const invariant = invariantContextDocFinding(block, commentText);
+  if (complex) {
+    details.push(complex);
+  }
+  if (sideEffect) {
+    details.push(sideEffect);
+  }
+  if (errorBehavior) {
+    details.push(errorBehavior);
+  }
+  if (invariant) {
+    details.push(invariant);
+  }
+  return details;
+}
+
+// Requires "why" context only after callable complexity crosses the configured threshold.
+function complexFunctionContextDocFinding(block: FunctionBlock, commentText: string, config: Config): ContextDocFindingDetails | undefined {
+  if (!isComplexContextCandidate(block, config) || hasComplexWhyMarker(commentText)) {
+    return undefined;
+  }
+  return contextDocDetails(block.name, "docs.missing-why-for-complex-code", `Complex function \`${block.name}\` has a comment, but it does not explain why the control flow exists.`, "Explain the tradeoff, compatibility reason, or invariant behind the complex control flow.", "complex-code");
+}
+
+// Documents externally observable mutations when the comment does not mention them.
+function sideEffectContextDocFinding(block: FunctionBlock, body: string, commentText: string): ContextDocFindingDetails | undefined {
+  if (!hasSideEffectSignal(block.name, body) || hasSideEffectMarker(commentText)) {
+    return undefined;
+  }
+  return contextDocDetails(block.name, "docs.missing-side-effect-doc", `Function \`${block.name}\` performs side effects that its comment does not describe.`, "Name the observable side effect such as filesystem, process, environment, or network mutation.", "side-effect");
+}
+
+// Keeps thrown, diagnostic, and recovery behavior visible in maintainer comments.
+function errorBehaviorContextDocFinding(block: FunctionBlock, body: string, commentText: string): ContextDocFindingDetails | undefined {
+  if (!hasErrorBehaviorSignal(body) || hasErrorBehaviorMarker(commentText)) {
+    return undefined;
+  }
+  return contextDocDetails(block.name, "docs.missing-error-behavior-doc", `Function \`${block.name}\` has error behavior that its comment does not describe.`, "Document thrown errors, diagnostics, exits, reports, or recovery behavior.", "error-behavior");
+}
+
+// Protects schema and fingerprint invariants from becoming implicit tribal knowledge.
+function invariantContextDocFinding(block: FunctionBlock, commentText: string): ContextDocFindingDetails | undefined {
+  if (!hasInvariantFunctionSignal(block) || hasInvariantMarker(commentText)) {
+    return undefined;
+  }
+  return contextDocDetails(block.name, "docs.missing-invariant-doc", `Function \`${block.name}\` maintains a public contract that its comment does not describe.`, "Document the schema, fingerprint, baseline, sorting, or determinism invariant.", "invariant");
+}
+
+// Bundles the per-context-class metadata so the four detector helpers share one stable shape.
+// `contextClass` is the discriminator surfaced in finding metadata.
+function contextDocDetails(symbol: string, ruleId: string, message: string, remediation: string, contextClass: string): ContextDocFindingDetails {
+  return {
+    symbol,
+    ruleId,
+    message,
+    remediation,
+    metadata: { contextClass },
+  };
+}
+
+// Anchors every context-doc finding at the comment line (not the declaration line) so the
+// reviewer's eye lands on the documentation that needs editing. Reports a stable finding.
+function contextDocFinding(input: ContextDocFindingInput): Finding {
+  const { file, comment, symbol, ruleId, message, remediation, metadata } = input;
+  return makeFinding({
+    ruleId,
+    message,
+    filePath: file.displayPath,
+    line: comment.line,
+    severity: "advisory",
+    pillar: "documentation",
+    confidence: "medium",
+    symbol,
+    remediation,
+    metadata,
+  });
+}
+
+// Composite gate: any one of size, cyclomatic, cognitive, NPath, or nesting depth crossing the
+// configured stable threshold qualifies a callable as "complex enough to need WHY context".
+function isComplexContextCandidate(block: FunctionBlock, config: Config): boolean {
+  const cyclomatic = countMatches(block.codeBody, /\b(if|else if|switch|case|for|while|catch)\b|\?|&&|\|\|/g) + 1;
+  const cognitive = cyclomatic + maxNestingDepth(block.codeBody);
+  const npath = approximateNpath(functionBodyContent(block.codeBody));
+  return (
+    block.lineCount > threshold(config, "size.function-length", 200) ||
+    cyclomatic > threshold(config, "complexity.cyclomatic", 15) ||
+    cognitive > threshold(config, "complexity.cognitive", 15) ||
+    npath.value > threshold(config, "complexity.npath", 200) ||
+    maxNestingDepth(block.codeBody) > 3
+  );
+}
+
+// Vocabulary list signalling "the comment explains why" - the missing-why rule passes when any
+// listed word appears. Adding entries here loosens the rule; removing them tightens it.
+function hasComplexWhyMarker(text: string): boolean {
+  return /\b(?:because|why|intentional|tradeoff|compat|avoid|preserve)\b/i.test(text);
+}
+
+// Vocabulary for "comment names a side effect". Pairs with `SIDE_EFFECT_BODY_PATTERNS` - if the
+// body matches and none of these words appear, the missing-side-effect rule fires.
+function hasSideEffectMarker(text: string): boolean {
+  return /\b(?:writes|reads|persists|mutates|starts|spawns|network|filesystem|environment)\b/i.test(text);
+}
+
+// Vocabulary for "comment names error behaviour". Matches throws/reports/exits/swallows/fallback/
+// recover and the multi-word "returns diagnostic". Pairs with `hasErrorBehaviorSignal`.
+function hasErrorBehaviorMarker(text: string): boolean {
+  return /\b(?:throws|returns diagnostic|reports|exits|swallows|fallback|recover)\b/i.test(text);
+}
+
+// Vocabulary for "comment names a public contract". Seven canonical words; the rule fires when
+// the callable carries invariant signals (Finding/baseline/fingerprint references) but none of these.
+function hasInvariantMarker(text: string): boolean {
+  return /\b(?:invariant|contract|must|stable|deterministic|schema|fingerprint)\b/i.test(text);
+}
+
+const SIDE_EFFECT_BODY_PATTERNS = [
+  /\b(?:writeFile(?:Sync)?|appendFile(?:Sync)?|mkdir(?:Sync)?|rm(?:Sync)?|rename(?:Sync)?|createWriteStream)\s*\(/,
+  /\bprocess\.chdir\s*\(/,
+  /\bprocess\.env\.[A-Za-z0-9_]+\s*=/,
+  /\b(?:exec|execFile|spawn)(?:Sync)?\s*\(/,
+  /\b(?:response|res)\.(?:write|end|setHeader|writeHead)\s*\(/,
+  /\bcreateServer\s*\(|\.listen\s*\(/,
+] as const;
+
+// Two pathways: a body pattern match (writeFile, exec, listen, response.write, …) or a name
+// pattern (functions starting with write/recordHistory/startDashboard). Either is sufficient
+// evidence that the callable has externally observable effects.
+function hasSideEffectSignal(name: string, body: string): boolean {
+  return SIDE_EFFECT_BODY_PATTERNS.some((pattern) => pattern.test(body)) || /^(?:write|recordHistory|startDashboard)\b/.test(name);
+}
+
+// Detects throw, catch, process.exit, diagnostic emission, or finding/diagnostic push patterns -
+// the five places error behaviour can hide inside a callable body.
+function hasErrorBehaviorSignal(body: string): boolean {
+  return /\bthrow\b|\bcatch\b|\bprocess\.exit\s*\(|\bdiagnosticType\s*:|\b(?:findings|diagnostics)\.push\s*\(/.test(body);
+}
+
+// Searches both the callable name and body for vocabulary tied to the analyser's stable contracts
+// (fingerprint, schemaVersion, baseline, AnalysisReport, Finding, dedupe, sort). Any match
+// triggers the invariant-doc rule's expectation that the comment will name an invariant.
+function hasInvariantFunctionSignal(block: FunctionBlock): boolean {
+  const signalText = [block.name, block.codeBody].join("\n");
+  return /\b(?:fingerprint|schemaVersion|baseline|AnalysisReport|Finding|stable sort|deterministic|dedupe|sort)\b/i.test(signalText);
+}
+
+// Same idea as `hasInvariantFunctionSignal` but reads the interface body via `declarationBlockText`.
+// The contract vocabulary is slightly wider (`Baseline`, `report`) because interfaces often shape
+// public report types.
+function hasInvariantInterfaceSignal(lines: string[], declaration: CommentedDeclaration): boolean {
+  const blockText = declarationBlockText(lines, declaration.line);
+  const signalText = `${declaration.name}\n${blockText}`;
+  return /\b(?:fingerprint|schemaVersion|baseline|report|Finding|AnalysisReport|Baseline|stable|deterministic)\b/i.test(signalText);
+}
+
+// Collects lines from the declaration until the first `}` at column 0 - used to feed the interface
+// body to vocabulary detectors. A more precise parser would help but is unnecessary for word matches.
+function declarationBlockText(lines: string[], line: number): string {
+  const start = Math.max(0, line - 1);
+  const collected: string[] = [];
+  for (let index = start; index < lines.length; index += 1) {
+    const current = lines[index] ?? "";
+    collected.push(current);
+    if (current.trim() === "}") {
+      break;
+    }
+  }
+  return collected.join("\n");
+}

package/src/dashboard.ts

@@ -0,0 +1,114 @@
+// Loopback dashboard HTTP surface that renders live analyzer reports without exposing remote scans.
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import { chdir, cwd, stdout } from "node:process";
+import { dashboardErrorHtml, dashboardHomeHtml, renderHtml } from "./report-renderers.ts";
+import type { AnalysisOptions, AnalysisReport } from "./types.ts";
+
+type DashboardAnalyse = (options: AnalysisOptions) => AnalysisReport;
+
+// Host/port/projectRoot frozen at server start. The dashboard binds to a loopback host only -
+// `startDashboard` callers must not relax this without auditing for unauthenticated remote scans.
+interface DashboardContext {
+  host: string;
+  port: number;
+  projectRoot: string;
+}
+
+// Per-request projectRoot + scanPath. Sourced from `?projectRoot` and `?path` query parameters and
+// fed straight to `chdir`/`analyse`, so untrusted values would let a caller pivot the analyser to
+// arbitrary directories - only acceptable because the server is loopback-only.
+interface DashboardRouteInput {
+  root: string;
+  scanPath: string;
+}
+
+// Starts a loopback HTTP server. `analyse` is injected (not imported) to avoid a circular import
+// back into `cli.ts`; see `.goat-flow/lessons/verification.md` on the dashboard import cycle.
+// Side effect: opens a listening socket and writes the URL to stdout unless `shouldWriteOutput` is false.
+function startDashboard(host: string, port: number, projectRoot: string, analyse: DashboardAnalyse, shouldWriteOutput = true): void {
+  assertLoopbackHost(host);
+  const context: DashboardContext = { host, port, projectRoot };
+  const server = createServer((request, response) => handleDashboardRequest(context, analyse, request, response));
+  server.listen(port, host, () => {
+    if (shouldWriteOutput) {
+      stdout.write(`gruff-ts dashboard listening at http://${host}:${port}\n`);
+    }
+  });
+}
+
+// The dashboard accepts filesystem paths from query strings, so loopback binding is its safety
+// boundary. Throws before opening the listener when a caller asks for a public host.
+function assertLoopbackHost(host: string): void {
+  if (host !== "127.0.0.1" && host !== "localhost") {
+    throw new Error("Dashboard host must be 127.0.0.1 or localhost.");
+  }
+}
+
+// Four endpoints: `/health` (uptime probes), `/scan` (runs the analyser and renders HTML),
+// `/` (control page), anything else → 404. `/health` is the only response that survives proxies
+// uncached - the scan and home responses set `no-store` so the dashboard always sees fresh output.
+function handleDashboardRequest(context: DashboardContext, analyse: DashboardAnalyse, request: IncomingMessage, response: ServerResponse): void {
+  const url = new URL(request.url ?? "/", `http://${context.host}:${context.port}`);
+  if (url.pathname === "/health") {
+    writeTextResponse(response, 200, "ok", true);
+    return;
+  }
+  if (url.pathname === "/scan") {
+    renderDashboardScan(response, dashboardRouteInput(url, context.projectRoot), analyse);
+    return;
+  }
+  if (url.pathname !== "/") {
+    writeTextResponse(response, 404, "not found", false);
+    return;
+  }
+  const input = dashboardRouteInput(url, context.projectRoot);
+  writeHtmlResponse(response, 200, dashboardHomeHtml(input.root, input.scanPath));
+}
+
+// Reads `?projectRoot` and `?path`, falling back to the server's launch context. Both values flow
+// straight into `chdir` and `analyse`; see DashboardRouteInput for the loopback trust assumption.
+function dashboardRouteInput(url: URL, projectRoot: string): DashboardRouteInput {
+  return {
+    root: url.searchParams.get("projectRoot") ?? projectRoot,
+    scanPath: url.searchParams.get("path") ?? ".",
+  };
+}
+
+// chdirs into the caller-requested project root, runs `analyse`, and always restores the previous
+// cwd in `finally` - leaking the chdir would corrupt subsequent requests. The loopback server must
+// keep serving on analyser failure, so the catch reports the error as a rendered fallback page.
+function renderDashboardScan(response: ServerResponse, input: DashboardRouteInput, analyse: DashboardAnalyse): void {
+  const previous = cwd();
+  try {
+    chdir(input.root);
+    const report = analyse({
+      paths: [input.scanPath],
+      shouldSkipConfig: false,
+      format: "html",
+      failOn: "none",
+      shouldIncludeIgnored: false,
+      shouldSkipBaseline: false,
+    });
+    writeHtmlResponse(response, 200, renderHtml(report, { projectRoot: input.root, scanPath: input.scanPath }));
+  } catch (error) {
+    writeHtmlResponse(response, 500, dashboardErrorHtml(String(error), input.root, input.scanPath));
+  } finally {
+    chdir(previous);
+  }
+}
+
+// `no-store` is non-negotiable for dashboard responses: stale findings cached by a proxy would
+// mislead a maintainer reading the report. Writes the HTTP response body and closes the connection.
+function writeHtmlResponse(response: ServerResponse, statusCode: number, body: string): void {
+  response.writeHead(statusCode, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
+  response.end(body);
+}
+
+// `/health` opts in to `no-store` so uptime probes never read a cached "ok"; 404 responses do not,
+// because their content is constant and proxies can safely keep them. Writes the response and closes it.
+function writeTextResponse(response: ServerResponse, statusCode: number, body: string, shouldUseNoStore: boolean): void {
+  response.writeHead(statusCode, { "content-type": "text/plain; charset=utf-8", ...(shouldUseNoStore ? { "cache-control": "no-store" } : {}) });
+  response.end(body);
+}
+
+export { startDashboard };

package/src/dead-code-rules.ts

@@ -0,0 +1,183 @@
+// Dead-code rules: unused private methods, unreachable statements after terminators, unused
+// named imports. Invoked from the analyseTypeScriptRules orchestrator alongside the line-rules
+// pass; they share the same `codeSource` mask and emit findings on a stable per-file order.
+import { type SourceFile } from "./discovery.ts";
+import { makeFinding } from "./findings.ts";
+import { escapeRegex, finding } from "./findings-helpers.ts";
+import { byteLine, countMatches } from "./text-scans.ts";
+import type { Finding } from "./types.ts";
+
+// Deliberately single-file and low confidence because private methods can still be reached by
+// tests, decorators, framework hooks, or string-based reflection; reports stable advisory findings because removal still needs human confirmation.
+export function analyseDeadCode(file: SourceFile, source: string, findings: Finding[]): void {
+  for (const match of source.matchAll(/\bprivate\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*\(/g)) {
+    const name = match[1] ?? "";
+    const escaped = escapeRegex(name);
+    if (countMatches(source, new RegExp(`${escaped}\\s*\\(`, "g")) <= 1) {
+      findings.push(
+        makeFinding({
+          ruleId: "dead-code.unused-private-method",
+          message: `Private method \`${name}\` appears to be unused in this file.`,
+          filePath: file.displayPath,
+          line: byteLine(source, match.index ?? 0),
+          severity: "advisory",
+          pillar: "dead-code",
+          confidence: "low",
+          symbol: name,
+          remediation: "Remove the method or add a real call site.",
+        }),
+      );
+    }
+  }
+}
+
+// Line-by-line walker that resets the terminator flag at every `case:` / `default:` so dead-code
+// detection respects control-flow boundaries. Each line is walked once in source order, then
+// reports `waste.unreachable-code` with stable, deterministic fingerprint anchors.
+export function analyseUnreachable(file: SourceFile, source: string, findings: Finding[]): void {
+  let didPreviousTerminate = false;
+  let isInConditionalBranch = false;
+  source.split(/\r?\n/).forEach((line, index) => {
+    const trimmed = line.trim();
+    const branchLabel = isBranchLabel(trimmed);
+    if (branchLabel) {
+      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" }));
+    }
+    // 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
+    // conditional-opener shape suppresses the false positive on compact guard clauses.
+    didPreviousTerminate = isTerminatingStatement(trimmed) && !isInConditionalBranch;
+    isInConditionalBranch = isBracelessConditionalOpener(trimmed);
+  });
+}
+
+// Detects single-line conditional/loop openers that begin a one-statement body (no `{`). The next
+// line is the conditional body, so any terminator there is conditional rather than unconditional.
+function isBracelessConditionalOpener(trimmed: string): boolean {
+  if (trimmed.endsWith("{") || trimmed.endsWith("}")) {
+    return false;
+  }
+  return /^(?:if|else\s+if|for|while)\s*\(/.test(trimmed) || /^else\b/.test(trimmed) || /^do\b/.test(trimmed);
+}
+
+// `case X:` / `default:` open a new control path, so the unreachable walker must reset its
+// terminator flag here - otherwise the first statement in a fallthrough case looks dead.
+function isBranchLabel(trimmedLine: string): boolean {
+  return /^(?:case\b.*:|default\s*:)$/.test(trimmedLine);
+}
+
+// Three conditions must hold to flag a line: the prior statement terminated, this line has real
+// content, and it's not a `}` closer or a branch label. The `}` exclusion matters because the
+// closing brace of the terminating block looks like a statement to a naive walker.
+function isUnreachableStatement(trimmedLine: string, didPreviousTerminate: boolean, isBranchLabel: boolean): boolean {
+  return didPreviousTerminate && /\S/.test(trimmedLine) && !trimmedLine.startsWith(String.fromCharCode(125)) && !isBranchLabel;
+}
+
+// `return`, `throw`, and `process.exit(...)` exit the current control path. The trailing `;`
+// requirement filters out expressions like `return foo()` split across lines - without it the
+// walker would falsely flag the continuation as unreachable.
+function isTerminatingStatement(trimmedLine: string): boolean {
+  return /^(?:return|throw|process\.exit)\b/.test(trimmedLine) && trimmedLine.endsWith(";");
+}
+
+/*
+ * Reports `waste.unused-import` for every named specifier whose local name appears nowhere else
+ * in the file. Default imports and namespace imports are out of scope because the regex anchors
+ * on `{ … }`; walking lines in source order keeps the reports stable and deterministic. Receives
+ * both the masked code and the raw source so identifiers referenced inside template-literal
+ * `${...}` interpolations (which the mask would otherwise blank out) still count as used. Never
+ * throws - every regex is anchored and the input shape is validated upstream by the analyser; the
+ * helper writes to `findings` and returns void. Part of the public per-file rule contract that
+ * baselines depend on, so finding ordering and message shape are intentionally stable across releases.
+ */
+export function analyseUnusedImports(file: SourceFile, source: string, rawSource: string, findings: Finding[]): void {
+  for (const statement of namedImportStatements(source)) {
+    for (const specifier of namedImportSpecifiers(statement.source)) {
+      const name = unusedImportName(source, rawSource, specifier);
+      if (!name) {
+        continue;
+      }
+      findings.push(unusedImportFinding(file, name, statement.line));
+    }
+  }
+}
+
+// One complete named-import declaration, including multiline `{ ... }` bodies, plus the anchor
+// line where the `import` keyword began. Keeping the original source preserves alias parsing.
+interface NamedImportStatement {
+  source: string;
+  line: number;
+}
+
+// Finds only named import declarations and spans across newlines until the matching `from` source.
+// The non-greedy body keeps adjacent imports from merging into one statement.
+function namedImportStatements(source: string): NamedImportStatement[] {
+  return [...source.matchAll(/\bimport\s+(?:type\s+)?\{[\s\S]*?\}\s+from\s*["'][^"']+["']/g)].map((match) => ({ source: match[0] ?? "", line: byteLine(source, match.index ?? 0) }));
+}
+
+// Slices the `{ a, b as c }` body out of a named-import statement and splits on commas. No AST: a
+// regex-light approach is sufficient because `analyseUnusedImports` runs after the comment mask,
+// so commas inside string defaults never reach this function.
+function namedImportSpecifiers(source: string): string[] {
+  const trimmed = source.trim();
+  const openBrace = trimmed.indexOf(String.fromCharCode(123));
+  const closeBrace = trimmed.indexOf(String.fromCharCode(125), openBrace + 1);
+  if (!hasNamedImportBraces(openBrace, closeBrace)) {
+    return [];
+  }
+  return trimmed.slice(openBrace + 1, closeBrace).split(",");
+}
+
+// Both braces present and well-ordered. Indexes come from raw `indexOf` calls, so this guards
+// against the malformed slice that would otherwise feed an empty or reversed specifier list.
+function hasNamedImportBraces(openBrace: number, closeBrace: number): boolean {
+  return openBrace !== -1 && closeBrace !== -1 && closeBrace > openBrace;
+}
+
+// The local binding (after `as`, if present) must appear in the source exactly once - the
+// declaration itself. More than one match in the masked code, OR a `${...name...}` template-literal
+// interpolation in the raw source, counts as a real reference. Returning undefined suppresses the finding.
+function unusedImportName(source: string, rawSource: string, specifier: string): string | undefined {
+  const name = localImportName(specifier);
+  if (!name) {
+    return undefined;
+  }
+  const escaped = escapeRegex(name);
+  if (countMatches(source, new RegExp(`\\b${escaped}\\b`, "g")) > 1) {
+    return undefined;
+  }
+  if (new RegExp(`\\$\\{[^}]*\\b${escaped}\\b[^}]*\\}`).test(rawSource)) {
+    return undefined;
+  }
+  return name;
+}
+
+// Single makeFinding factory for `waste.unused-import`. The local binding name lands in both the
+// message and `metadata.importName` so downstream tooling can group by symbol while the stable
+// fingerprint identity remains (ruleId, filePath, line).
+function unusedImportFinding(file: SourceFile, name: string, line: number): Finding {
+  return makeFinding({
+    ruleId: "waste.unused-import",
+    message: `Imported symbol \`${name}\` does not appear to be used.`,
+    filePath: file.displayPath,
+    line,
+    severity: "advisory",
+    pillar: "waste",
+    confidence: "medium",
+    symbol: name,
+    remediation: "Remove the unused import.",
+    metadata: { importName: name },
+  });
+}
+
+// Returns the right-hand side of `as` when present, otherwise the specifier itself. The trailing
+// identifier regex protects against type-only specifiers that include extra tokens.
+function localImportName(specifier: string): string | undefined {
+  const parts = specifier.trim().split(/\s+as\s+/);
+  const candidate = parts[1] ?? parts[0] ?? "";
+  const match = candidate.trim().match(/^[A-Za-z_$][A-Za-z0-9_$]*/);
+  return match?.[0];
+}