@blundergoat/gruff-ts 0.1.0

package/src/line-rules.ts

@@ -0,0 +1,538 @@
+// Per-line and per-source line rules: security/modernisation regex passes, type-safety
+// (ts-comment, non-null, double-cast, exported-any), reliability (async-forEach, floating-promise,
+// non-Error throw, useless/swallowed catches), and the naming-pusher fanout used by both line
+// detection and the block-rule parameter pass. Dead-code rules (unused imports, unreachable) are
+// invoked by the cli orchestrator before/after this module so the stable per-line emission order
+// stays a single contract.
+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 { analyseReliabilityLine, analyseSwallowedCatches, analyseTypeSafetyLine, analyseUselessCatches } from "./safety-rules.ts";
+import { analyseSecurityFlowLine } from "./security-flow-rules.ts";
+import { codeLineForMatching } from "./source-text.ts";
+import { byteLine } from "./text-scans.ts";
+import type { Config, Finding, Pillar, Severity } from "./types.ts";
+
+// Descriptor for one regex-backed line rule. `pattern` is the cheap test and `globalPattern`
+// (optional) is used when the rule needs all matches for emission, not just the first hit.
+interface LineRuleCheck {
+  ruleId: string;
+  pattern: RegExp;
+  globalPattern?: RegExp;
+  message: string;
+  severity: Severity;
+  pillar: Pillar;
+}
+
+/*
+ * Per-line scratch state shared across every line rule in a single pass. `codeLine` is the
+ * comment-masked variant - checks that must stay stable against literal content operate on it.
+ */
+interface LineRuleContext {
+  file: SourceFile;
+  line: string;
+  codeLine: string;
+  lineNumber: number;
+  config: Config;
+  findings: Finding[];
+  codeChecks: LineRuleCheck[];
+  literalChecks: LineRuleCheck[];
+  variables: RegExp;
+}
+
+const CODE_LINE_CHECKS = codeLineChecks();
+const LITERAL_LINE_CHECKS = literalLineChecks();
+const VARIABLE_DECLARATIONS = /\b(?:const|let|for\s*\(\s*const|for\s*\(\s*let)\s+([A-Za-z_$][A-Za-z0-9_$]*)/g;
+
+/*
+ * Per-line rule pipeline plus the two multi-line catch detectors. Excludes analyseUnusedImports
+ * and analyseUnreachable so the dead-code module can own them; the orchestrator in cli.ts wraps
+ * this call with those rules to preserve the stable, deterministic emission order.
+ */
+export function analyseLineRules(file: SourceFile, source: string, codeSource: string, config: Config, findings: Finding[]): void {
+  const sourceLines = source.split(/\r?\n/);
+  const codeLines = codeSource.split(/\r?\n/);
+  const context: LineRuleContext = {
+    file,
+    line: "",
+    codeLine: "",
+    lineNumber: 0,
+    config,
+    findings,
+    codeChecks: CODE_LINE_CHECKS,
+    literalChecks: LITERAL_LINE_CHECKS,
+    variables: VARIABLE_DECLARATIONS,
+  };
+  sourceLines.forEach((line, index) => {
+    context.line = line;
+    context.codeLine = codeLines[index] ?? codeLineForMatching(line);
+    context.lineNumber = index + 1;
+    context.variables.lastIndex = 0;
+    analyseLineRuleContext(context);
+  });
+
+  analyseProcessExecCalls(file, source, codeSource, findings);
+  analyseUselessCatches(file, codeSource, findings);
+  analyseSwallowedCatches(file, source, codeSource, findings);
+}
+
+// All per-line checks for a single line in their stable, deterministic emission order. Each helper
+// either no-ops (rule skipped or no match) or appends to `findings`.
+function analyseLineRuleContext(context: LineRuleContext): void {
+  analyseTypeSafetyLine(context.file, context.line, context.codeLine, context.lineNumber, context.findings);
+  analyseReliabilityLine(context.file, context.codeLine, context.lineNumber, context.findings);
+  pushCommentedOutCodeFinding(context);
+  pushBooleanPrefixFinding(context);
+  pushHungarianNotationFindings(context);
+  pushOptionalChainingFindings(context);
+  pushNullishCoalescingFindings(context);
+  pushLooseEqualityFinding(context);
+  pushStringTimerFinding(context);
+  analyseSecurityFlowLine(context.file, context.codeLine, context.lineNumber, context.findings);
+  pushPatternCheckFindings(context);
+  pushVariableNameFindings(context);
+}
+
+// Code-shape rules: those that must match against the masked code (no comment or literal noise).
+// Targets the eval / new-Function / Math.random / innerHTML / proto-access family of security/waste signals.
+function codeLineChecks(): LineRuleCheck[] {
+  return [
+    { ruleId: "security.eval-call", pattern: /\beval\s*\(/, message: "eval() executes dynamic code.", severity: "error", pillar: "security" },
+    { ruleId: "security.new-function", pattern: /\bnew\s+Function\s*\(|(?:^|[=(:,])\s*Function\s*\(/, message: "Function constructor executes dynamic code.", severity: "error", pillar: "security" },
+    { ruleId: "security.insecure-random", pattern: /\bMath\.random\s*\(/, message: "Math.random() is not suitable for security-sensitive randomness.", severity: "warning", pillar: "security" },
+    { 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" },
+  ];
+}
+
+// Rules that need to see the raw line including literals (e.g., `"javascript:"` URL detection,
+// `"md5"` weak-crypto match). Global patterns are auto-generated so global-match operations stay
+// safe - see `withGlobalPattern`.
+function literalLineChecks(): LineRuleCheck[] {
+  const checks: LineRuleCheck[] = [
+    { ruleId: "security.weak-crypto", pattern: /\b(?:createHash|createHmac)\s*\(\s*["'](?:md5|sha1)["']|\bcreateCipher\s*\(|\b(?:secureProtocol|minVersion|maxVersion)\s*:\s*["'](?:SSLv2_method|SSLv3_method|TLSv1(?:_method)?|TLSv1\.1)["']/i, message: "Weak cryptographic primitive is used.", severity: "warning", pillar: "security" },
+    { ruleId: "security.disabled-tls-verification", pattern: /\b(?:process\.env\.)?NODE_TLS_REJECT_UNAUTHORIZED\b\s*=\s*["']0["']|\brejectUnauthorized\s*:\s*false\b/i, message: "TLS certificate verification is disabled.", severity: "error", pillar: "security" },
+    { ruleId: "security.javascript-url", pattern: /["'`]\s*javascript\s*:(?!\s+URL\b)/i, message: "javascript: URL literal can execute script.", severity: "error", pillar: "security" },
+    { ruleId: "security.proto-access", pattern: /\[\s*["']__proto__["']\s*\]/, message: "Direct __proto__ access can enable prototype pollution.", severity: "warning", pillar: "security" },
+    { 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: "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);
+}
+
+// Returns a new check whose `globalPattern` has the `g` flag, leaving the original `pattern`
+// untouched. Required because `pattern.exec` stateful iteration would corrupt callers that share
+// a check across multiple files.
+function withGlobalPattern(check: LineRuleCheck): LineRuleCheck {
+  return {
+    ...check,
+    globalPattern: check.pattern.flags.includes("g") ? check.pattern : new RegExp(check.pattern.source, `${check.pattern.flags}g`),
+  };
+}
+
+/*
+ * Targets `// const x = …;`-style commented-out code. The detector is intentionally conservative
+ * because clever false positives drown the rule. Reports the stable `waste.commented-out-code` finding.
+ */
+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" }));
+  }
+}
+
+// Detects typed boolean declarations (or those with a literal true/false initializer) and runs
+// the boolean-prefix and negative-boolean checks. Surface is fixed to "declaration".
+function pushBooleanPrefixFinding(context: LineRuleContext): void {
+  const booleanDeclaration = context.codeLine.match(/\b(?:const|let|var|public|private|protected)\s+([A-Za-z_$][A-Za-z0-9_$]*)\??(?:\s*:\s*boolean|\s*=\s*(?:true|false)\b)/);
+  const name = booleanDeclaration?.[1] ?? "";
+  if (!name) {
+    return;
+  }
+  pushBooleanPrefixAt(context.file, context.lineNumber, name, context.config, context.findings, "declaration");
+  pushNegativeBooleanAt(context.file, context.lineNumber, name, context.config, context.findings, "declaration");
+}
+
+
+
+// Walks all `strFoo` / `intBar` / `arrBaz` identifiers on the line. The prefix regex is
+// auto-generated from `config.hungarianPrefixes`. Reports `naming.hungarian-notation`.
+function pushHungarianNotationFindings(context: LineRuleContext): void {
+  const regex = hungarianPrefixRegex(context.config.hungarianPrefixes);
+  if (regex === null) {
+    return;
+  }
+  for (const hungarian of context.codeLine.matchAll(regex)) {
+    const name = hungarian[1] ?? "";
+    context.findings.push(
+      makeFinding({
+        ruleId: "naming.hungarian-notation",
+        message: `Identifier \`${name}\` uses type-style Hungarian notation.`,
+        filePath: context.file.displayPath,
+        line: context.lineNumber,
+        severity: "advisory",
+        pillar: "naming",
+        confidence: "medium",
+        symbol: name,
+        remediation: "Name the domain concept instead of the storage type.",
+        metadata: { identifierName: name },
+      }),
+    );
+  }
+}
+
+// Detects `foo && foo.bar` patterns where `foo?.bar` would say the same thing. Backreference
+// in the regex enforces identical identifiers on both sides. Reports `modernisation.optional-chaining-candidate`.
+function pushOptionalChainingFindings(context: LineRuleContext): void {
+  for (const optional of context.codeLine.matchAll(/\b([A-Za-z_$][A-Za-z0-9_$]*)\s*&&\s*\1\.[A-Za-z_$][A-Za-z0-9_$]*/g)) {
+    const name = optional[1] ?? "";
+    context.findings.push(
+      makeFinding({
+        ruleId: "modernisation.optional-chaining-candidate",
+        message: `Guarded property access on \`${name}\` can usually use optional chaining.`,
+        filePath: context.file.displayPath,
+        line: context.lineNumber,
+        severity: "advisory",
+        pillar: "modernisation",
+        confidence: "medium",
+        symbol: name,
+        remediation: "Use optional chaining for the guarded property access.",
+      }),
+    );
+  }
+}
+
+// Targets `x || defaultValue` patterns where the fallback is a literal - `??` would preserve
+// legitimately-falsy values (0, "", false). Reports `modernisation.nullish-coalescing-candidate`.
+function pushNullishCoalescingFindings(context: LineRuleContext): void {
+  for (const fallback of context.codeLine.matchAll(/=\s*([A-Za-z_$][A-Za-z0-9_$.]*)\s*\|\|\s*(["'`]\s*["'`]|\d+|true|false)/g)) {
+    const name = fallback[1] ?? "";
+    context.findings.push(
+      makeFinding({
+        ruleId: "modernisation.nullish-coalescing-candidate",
+        message: `Fallback for \`${name}\` can usually use nullish coalescing to preserve falsy values.`,
+        filePath: context.file.displayPath,
+        line: context.lineNumber,
+        severity: "advisory",
+        pillar: "modernisation",
+        confidence: "medium",
+        symbol: name,
+        remediation: "Use ?? when only null or undefined should trigger the fallback.",
+      }),
+    );
+  }
+}
+
+/*
+ * Loose `==` / `!=` against non-null operands. The `looseEqualityOperator` helper excludes intentional
+ * `x == null` checks (which legitimately match null and undefined). Reports the stable
+ * `modernisation.loose-equality` finding.
+ */
+function pushLooseEqualityFinding(context: LineRuleContext): void {
+  const looseOperator = looseEqualityOperator(context.codeLine);
+  if (looseOperator) {
+    context.findings.push(finding({ ruleId: "modernisation.loose-equality", message: `Loose equality operator ${looseOperator} may coerce values.`, file: context.file, line: context.lineNumber, severity: "advisory", pillar: "modernisation" }));
+  }
+}
+
+/*
+ * `setTimeout("alert(1)", …)` and friends evaluate the string as code, an `eval`-equivalent.
+ * Reports the stable `security.string-timer` finding when a literal string callback is detected.
+ */
+function pushStringTimerFinding(context: LineRuleContext): void {
+  if (stringTimerCandidate(context.codeLine)) {
+    context.findings.push(finding({ ruleId: "security.string-timer", message: "Timer callback is provided as a string.", file: context.file, line: context.lineNumber, severity: "warning", pillar: "security" }));
+  }
+}
+
+// Runs the descriptor-driven line checks split into code-shape vs literal-aware. Literal checks
+// use `rawPatternStartsInCode` to confirm the match starts in real code, not inside a comment.
+// Reports each matching rule's stable line-anchored finding.
+function pushPatternCheckFindings(context: LineRuleContext): void {
+  for (const check of context.codeChecks) {
+    if (check.pattern.test(context.codeLine)) {
+      context.findings.push(finding({ ruleId: check.ruleId, message: check.message, file: context.file, line: context.lineNumber, severity: check.severity, pillar: check.pillar }));
+    }
+  }
+  for (const check of context.literalChecks) {
+    if (isSuppressedByPathContext(check.ruleId, context.file.displayPath)) {
+      continue;
+    }
+    if (rawPatternStartsInCode(context.line, context.codeLine, check.globalPattern ?? check.pattern)) {
+      context.findings.push(finding({ ruleId: check.ruleId, message: check.message, file: context.file, line: context.lineNumber, severity: check.severity, pillar: check.pillar }));
+    }
+  }
+}
+
+// Per-rule path-context allowlist. CLI entry points, build scripts, and server diagnostic modules
+// are expected to write to stdout; the console-log rule would otherwise drown them in advisories.
+function isSuppressedByPathContext(ruleId: string, displayPath: string): boolean {
+  if (ruleId !== "waste.console-log") {
+    return false;
+  }
+  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
+// 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");
+  }
+}
+
+// Walks `const { foo, bar: alias } = ...` patterns. Aliased names (the part after `:`) become the
+// local binding; defaults are stripped. Required because the naming rules check the local name only.
+function destructuredLocalNames(codeLine: string): string[] {
+  const names: string[] = [];
+  for (const block of codeLine.matchAll(/\b(?:const|let)\s+\{([^}]+)\}\s*=/g)) {
+    const inner = block[1] ?? "";
+    for (const part of inner.split(",")) {
+      const trimmed = part.trim().replace(/\s*=[^,]*$/, "");
+      const aliased = trimmed.match(/[A-Za-z_$][A-Za-z0-9_$]*\s*:\s*([A-Za-z_$][A-Za-z0-9_$]*)/);
+      const plain = trimmed.match(/^([A-Za-z_$][A-Za-z0-9_$]*)$/);
+      const name = aliased?.[1] ?? plain?.[1];
+      if (name) {
+        names.push(name);
+      }
+    }
+  }
+  return names;
+}
+
+// Thin wrapper that fills in `"declaration"` for the surface field. Same back-end as parameter
+// and destructure callers, which use their own surface labels.
+function pushShortVariableFinding(context: LineRuleContext, name: string): void {
+  pushShortVariableAt(context.file, context.lineNumber, name, context.config, context.findings, "declaration");
+}
+
+
+// Thin wrapper that fills in `"declaration"` for the surface field; parameter and destructure
+// callers use their own surface labels via the underlying `pushIdentifierQualityAt`.
+function pushIdentifierQualityFinding(context: LineRuleContext, name: string): void {
+  pushIdentifierQualityAt(context.file, context.lineNumber, name, context.config, context.findings, "declaration");
+}
+
+
+
+// True iff the pattern matches somewhere on the raw line *and* the match's start position falls on
+// a code character in `codeLine`. Required for literal-rule checks where the raw line is needed to
+// see the literal content, but the match must still begin in executable code (not inside a comment).
+function rawPatternStartsInCode(rawLine: string, codeLine: string, pattern: RegExp): boolean {
+  const globalPattern = pattern;
+  let match: RegExpExecArray | null;
+  globalPattern.lastIndex = 0;
+  while ((match = globalPattern["exec"](rawLine)) !== null) {
+    const index = match.index ?? 0;
+    if (isNonWhitespaceCharacter(codeLine[index] ?? "")) {
+      return true;
+    }
+    if (match[0] === "") {
+      globalPattern.lastIndex += 1;
+    }
+  }
+  return false;
+}
+
+// Used by `rawPatternStartsInCode` to confirm a position holds executable code rather than the
+// space character produced by `maskNonCode`.
+function isNonWhitespaceCharacter(character: string): boolean {
+  return character !== "" && character !== " " && character !== "\t" && character !== "\r" && character !== "\n";
+}
+
+// Returns the loose operator (`==` or `!=`) when present and not part of `===`/`!==`/null check.
+// Used by the modernisation rule; sufficient context lookback keeps `x == null` quiet.
+function looseEqualityOperator(codeLine: string): string | undefined {
+  for (const match of codeLine.matchAll(/[=!]=/g)) {
+    const index = match.index ?? 0;
+    const operator = match[0] ?? "";
+    if (!isLooseEqualityCandidate(codeLine, index, operator)) {
+      continue;
+    }
+    return operator;
+  }
+  return undefined;
+}
+
+// Two-pass filter: reject `===`/`!==` (strict equality) and reject `x == null` (intentional double-test).
+function isLooseEqualityCandidate(codeLine: string, index: number, operator: string): boolean {
+  return !isStrictEqualityOperator(codeLine, index, operator) && !isNullEqualityComparison(codeLine, index, operator);
+}
+
+// Looks one char before and after - `===` shows up as `==` plus a trailing `=`. The leading `!` /
+// `=` check catches `!==` and `===` from either side.
+function isStrictEqualityOperator(codeLine: string, index: number, operator: string): boolean {
+  const before = codeLine[index - 1] ?? "";
+  const after = codeLine[index + operator.length] ?? "";
+  return before === "=" || before === "!" || after === "=";
+}
+
+// `x == null` matches both null and undefined and is a documented idiom - exempting it is the
+// rule's intentional false-positive escape hatch. 24-character lookback window is large enough to
+// span `someObject.field == null` without matching unrelated tokens.
+function isNullEqualityComparison(codeLine: string, index: number, operator: string): boolean {
+  const left = codeLine.slice(Math.max(0, index - 24), index).trimEnd();
+  const right = codeLine.slice(index + operator.length, Math.min(codeLine.length, index + operator.length + 24)).trimStart();
+  return /\bnull$/.test(left) || /^null\b/.test(right);
+}
+
+// Two cases: a bare `setTimeout("…")` call, or one accessed via window/self/globalThis. Both
+// invoke `eval`-equivalent string-to-code semantics in browsers.
+function stringTimerCandidate(codeLine: string): boolean {
+  return (
+    /(?:^|[^.\w$])(?:setTimeout|setInterval|execScript)\s*\(\s*["'`]/.test(codeLine) ||
+    /\b(?:window|self|globalThis)\.(?:setTimeout|setInterval|execScript)\s*\(\s*["'`]/.test(codeLine)
+  );
+}
+
+/*
+ * Targets child_process-style calls across single- and multi-line expressions. Stable invariant:
+ * masked-source matching keeps fixture strings quiet. Unmatched calls recover by being skipped
+ * rather than guessed, while fixed literal-command argv calls stay quiet.
+ */
+function analyseProcessExecCalls(file: SourceFile, rawSource: string, codeSource: string, findings: Finding[]): void {
+  const processCallPattern = /\b(?:(child_process|childProcess|cp)\.)?(exec|spawn|execFile|execSync|execFileSync|spawnSync|fork)\s*\(/g;
+  for (const match of codeSource.matchAll(processCallPattern)) {
+    const start = match.index ?? 0;
+    const callName = match[2] ?? "";
+    if (!callName || isMemberProcessExecFalsePositive(codeSource, start, Boolean(match[1]))) {
+      continue;
+    }
+    const openParen = start + match[0].length - 1;
+    const closeParen = matchingCloseParen(codeSource, openParen);
+    if (closeParen === undefined) {
+      continue;
+    }
+    const codeSegment = codeSource.slice(start, closeParen + 1);
+    const rawSegment = rawSource.slice(start, closeParen + 1);
+    if (isSafeProcessExecCall(file, callName, rawSource, start, rawSegment, codeSegment)) {
+      continue;
+    }
+    findings.push(finding({ ruleId: "security.process-exec", message: "Child-process execution is used; validate arguments are not user-controlled.", file, line: byteLine(codeSource, start), severity: "warning", pillar: "security" }));
+  }
+}
+
+// Excludes ordinary member calls such as `pattern.exec(...)`; module receivers like `cp.exec(...)`
+// remain valid process-exec candidates.
+function isMemberProcessExecFalsePositive(codeSource: string, start: number, hasProcessReceiver: boolean): boolean {
+  return !hasProcessReceiver && codeSource[start - 1] === ".";
+}
+
+// Tiny parenthesis matcher over masked source. Strings and comments are already blanked by
+// `maskNonCode`, so nested call parentheses are the only structure this needs to balance.
+function matchingCloseParen(source: string, openParen: number): number | undefined {
+  let depth = 0;
+  for (let index = openParen; index < source.length; index += 1) {
+    const character = source[index];
+    if (character === "(") {
+      depth += 1;
+    } else if (character === ")") {
+      depth -= 1;
+      if (depth === 0) {
+        return index;
+      }
+    }
+  }
+  return undefined;
+}
+
+// Fixed command vectors and known safe wrappers are intentionally not shell-interpolated, so this
+// rule stays focused on dynamic commands and shell-enabled process calls.
+function isSafeProcessExecCall(file: SourceFile, callName: string, rawSource: string, callStart: number, rawSegment: string, codeSegment: string): boolean {
+  return (
+    isFixedArgvProcessCallSegment(callName, rawSource, callStart, rawSegment, codeSegment) ||
+    isSafeExecWrapperCall(file, callName, codeSegment) ||
+    isFixedTestHarnessProcessCall(file, callName, rawSegment, codeSegment)
+  );
+}
+
+// Suppresses argv-form process calls where the command is fixed by a literal, `process.execPath`,
+// a local const literal selector, or a terminal-binary version probe.
+function isFixedArgvProcessCallSegment(callName: string, rawSource: string, callStart: number, rawSegment: string, codeSegment: string): boolean {
+  if (/\bshell\s*:\s*true\b/.test(codeSegment)) {
+    return false;
+  }
+  if (!["spawn", "spawnSync", "execFile", "execFileSync"].includes(callName)) {
+    return false;
+  }
+  const argsText = rawSegment.slice(rawSegment.indexOf("(") + 1, rawSegment.lastIndexOf(")"));
+  return (
+    /^\s*(?:["'][^"']+["']|process\.execPath)\s*(?:,\s*(?:\[|[A-Za-z_$][A-Za-z0-9_$]*)|$)/s.test(argsText) ||
+    isFixedTerminalVersionProbe(argsText) ||
+    hasConstLiteralCommandVector(rawSource, callStart, argsText)
+  );
+}
+
+// Agent/tool discovery commonly runs a manifest-backed terminal binary with `--version`. The
+// argument vector is fixed, and the binary field is a known capability slot rather than request data.
+function isFixedTerminalVersionProbe(argsText: string): boolean {
+  return /^\s*[A-Za-z_$][A-Za-z0-9_$]*(?:\.[A-Za-z_$][A-Za-z0-9_$]*)*\.terminalBinary\s*,\s*\[\s*["']--version["']\s*\]/s.test(argsText);
+}
+
+// The safe-exec module is the wrapper implementation: it validates against an allow-list, rejects
+// unsafe args, sets `shell: false`, and bounds execution. Flagging its one spawn call is noise.
+function isSafeExecWrapperCall(file: SourceFile, callName: string, codeSegment: string): boolean {
+  return /(?:^|\/)safe-exec\.ts$/.test(file.displayPath) && ["spawn", "spawnSync"].includes(callName) && /\bshell\s*:\s*false\b/.test(codeSegment);
+}
+
+// Test harnesses often launch the current Node process or syntax-check a local shell script. Keep
+// dynamic production process calls visible while suppressing those fixed test-driver invocations.
+function isFixedTestHarnessProcessCall(file: SourceFile, callName: string, rawSegment: string, codeSegment: string): boolean {
+  if (!isTestLikeProcessExecPath(file.displayPath) || /\bshell\s*:\s*true\b/.test(codeSegment)) {
+    return false;
+  }
+  const argsText = rawSegment.slice(rawSegment.indexOf("(") + 1, rawSegment.lastIndexOf(")"));
+  if (/^\s*process\.execPath\s*,\s*\[/.test(argsText)) {
+    return true;
+  }
+  return ["exec", "execSync"].includes(callName) && /^\s*(?:"node scripts\/[^"]+"|'node scripts\/[^']+'|`(?:bash -n|wc -l\b)[^`]*`)/s.test(argsText);
+}
+
+// Test-only paths get a few extra fixed-harness exemptions; production paths still report them.
+function isTestLikeProcessExecPath(path: string): boolean {
+  return /(?:^|\/)(?:test|tests)\/|(?:^|\/)[^/]+\.(?:test|spec)\.[cm]?[jt]sx?$/.test(path);
+}
+
+// Handles local command variables such as `const whichCmd = platform ? "where" : "which"` when
+// the call still uses an argv array. Calls or templates in the declaration remain reportable.
+function hasConstLiteralCommandVector(rawSource: string, callStart: number, argsText: string): boolean {
+  const firstArg = argsText.match(/^\s*([A-Za-z_$][A-Za-z0-9_$]*)\s*,\s*(?:\[|[A-Za-z_$][A-Za-z0-9_$]*)/s)?.[1];
+  if (!firstArg) {
+    return false;
+  }
+  const declaration = rawSource.slice(0, callStart).match(new RegExp(`\\bconst\\s+${escapeRegex(firstArg)}\\s*=\\s*([^;]+);\\s*$`, "s"));
+  const initializer = declaration?.[1] ?? "";
+  return /["'][^"']+["']/.test(initializer) && !/[`$()[\]{}]/.test(initializer);
+}
+
+
+
+const HUNGARIAN_PREFIX_REGEX_CACHE = new WeakMap<Set<string>, RegExp | null>();
+
+
+// Counterpart to `booleanPrefixRegex` for the `naming.hungarian-notation` rule. Returns a global
+// regex (callers iterate matches) anchored to declaration keywords + visibility modifiers, so a
+// reference to `IUser` inside a comment is not flagged - the regex is part of the stable contract.
+function hungarianPrefixRegex(prefixes: Set<string>): RegExp | null {
+  if (HUNGARIAN_PREFIX_REGEX_CACHE.has(prefixes)) {
+    return HUNGARIAN_PREFIX_REGEX_CACHE.get(prefixes) ?? null;
+  }
+  const escapedPrefixes = [...prefixes].map(escapeRegex);
+  const regex = prefixes.size === 0 ? null : new RegExp(`\\b(?:const|let|var|public|private|protected)\\s+((?:${escapedPrefixes.join("|")})[A-Z][A-Za-z0-9_$]*)`, "g");
+  HUNGARIAN_PREFIX_REGEX_CACHE.set(prefixes, regex);
+  return regex;
+}