@ontrails/warden 1.0.0-beta.4 → 1.0.0-beta.42

package/src/rules/warden-rules-use-ast.ts

@@ -0,0 +1,1109 @@
+/**
+ * Self-governance rule: warden rules must inspect the AST via the helpers in
+ * `../source/*` helpers rather than regex-scanning raw source text. Raw-text scans
+ * produce false positives on string literals, template payloads, and
+ * docstrings — see TRL-335 and ADR-0036.
+ *
+ * Three detection families are enforced:
+ *
+ * 1. `rawScanSite` — string methods on a raw-source identifier, e.g.
+ *    `sourceCode.split(/\n/)`, `rawText.match(...)`, `text.replace(...)`.
+ * 2. `regexScanSite` — regex-receiver methods consuming a raw-source
+ *    argument, e.g. `/re/.test(sourceCode)`, `new RegExp(...).exec(text)`.
+ * 3. `regexConstructionSite` — constructing a regex directly from a raw
+ *    source identifier, e.g. `new RegExp(sourceCode)`, `RegExp(rawText, 'g')`.
+ *    Interpolating raw source into a regex constructor is the same class of
+ *    bug as scanning with one — see TRL-345.
+ * 4. `rawNodeFieldCastSite` — asserting AST nodes through
+ *    `as unknown as { field?: ... }` where a typed accessor exists on
+ *    `../source/*`.
+ *
+ * This rule is path-anchored to this package's own `src/rules/` directory so
+ * it never fires against a consumer repo that happens to share the same
+ * folder layout. Support modules such as `types.ts`, `index.ts`,
+ * `registry-names.ts`, and anything under `__tests__` are excluded.
+ */
+import { basename as pathBasename, dirname, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  getNodeArgument,
+  getNodeArguments,
+  getNodeBodyNode,
+  getNodeBodyStatements,
+  getNodeCallee,
+  getNodeComputed,
+  getNodeDeclarations,
+  getNodeElements,
+  getNodeExpression,
+  getNodeId,
+  getNodeKey,
+  getNodeKind,
+  getNodeLeft,
+  getNodeName,
+  getNodeObject,
+  getNodeParam,
+  getNodeParams,
+  getNodeProperties,
+  getNodeProperty,
+  getNodeTypeAnnotation,
+  getNodeValueNode,
+  getStringValue,
+  isAstNode,
+  offsetToLine,
+  parse,
+  walk,
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const RULE_NAME = 'warden-rules-use-ast';
+
+/**
+ * Absolute path to this package's rules directory, resolved from the rule's
+ * own module URL. Anchoring to the real on-disk location prevents the rule
+ * from firing against a foreign `packages/warden/src/rules/` in a consumer
+ * repository that happens to share the same folder structure.
+ *
+ * Dist-layout safeguard: when this module is bundled/transpiled to `dist/`
+ * (e.g. `packages/warden/dist/rules/warden-rules-use-ast.js`), the files
+ * being linted still live under `src/rules/`. A strict equality check
+ * against only the dist directory would cause the rule to silently emit
+ * zero diagnostics — a silent no-op. To keep the anchor robust, we compute
+ * a source-equivalent dir by substituting `/dist/` with `/src/` on the
+ * resolved path and accept either. This preserves the anti-false-positive
+ * guarantee from TRL-341 (we still require an exact directory match, not a
+ * suffix match) while surviving a future bundling change.
+ */
+const SELF_MODULE_DIR = resolve(dirname(fileURLToPath(import.meta.url)));
+
+/**
+ * Replace only the LAST occurrence of `/dist/` with `/src/`. A blanket
+ * `replaceAll` over-substitutes on paths that contain other `/dist/`
+ * segments higher up (e.g. `/home/runner/dist-artifacts/warden/dist/rules/`
+ * would incorrectly become `/home/runner/src-artifacts/warden/src/rules/`,
+ * a nonexistent directory — silently defeating the rule).
+ *
+ * Exported for unit testing. Not part of the public rule API.
+ */
+export const replaceLastDistSegmentWithSrc = (path: string): string => {
+  const distSegment = `${sep}dist${sep}`;
+  const srcSegment = `${sep}src${sep}`;
+  const lastIdx = path.lastIndexOf(distSegment);
+  if (lastIdx === -1) {
+    return path;
+  }
+  return (
+    path.slice(0, lastIdx) +
+    srcSegment +
+    path.slice(lastIdx + distSegment.length)
+  );
+};
+
+const SELF_RULES_DIRS: ReadonlySet<string> = new Set(
+  SELF_MODULE_DIR.includes(`${sep}dist${sep}`)
+    ? [SELF_MODULE_DIR, replaceLastDistSegmentWithSrc(SELF_MODULE_DIR)]
+    : [SELF_MODULE_DIR]
+);
+
+/**
+ * Stems of files in `src/rules/` (and their bundled `dist/rules/` twins) that
+ * are not themselves Warden rules and therefore must not be checked. These
+ * are support modules without a `check()` function.
+ */
+const EXCLUDED_STEMS: readonly string[] = [
+  'index',
+  'registry-names',
+  'scan',
+  'specs',
+  'structure',
+  'types',
+];
+
+/**
+ * Both `.ts` (source layout) and `.js` (dist layout) basenames must be
+ * excluded so the rule stays silent when pointed at a bundled tree.
+ */
+const EXCLUDED_BASENAMES: ReadonlySet<string> = new Set(
+  EXCLUDED_STEMS.flatMap((stem) => [`${stem}.ts`, `${stem}.js`])
+);
+
+const isTargetFile = (filePath: string): boolean => {
+  const absolute = resolve(filePath);
+  if (!SELF_RULES_DIRS.has(dirname(absolute))) {
+    return false;
+  }
+  const basename = pathBasename(absolute);
+  if (EXCLUDED_BASENAMES.has(basename)) {
+    return false;
+  }
+  if (basename.endsWith('.test.ts') || basename.endsWith('.test.js')) {
+    return false;
+  }
+  return true;
+};
+
+/**
+ * Names of the WardenRule methods that receive raw source text as their
+ * first parameter. The first parameter's *actual binding name* (not a fixed
+ * list of names) is what we track via scope analysis — see `buildSourceParamIndex`.
+ *
+ * `checkTopo` does not receive raw source text (it takes a `Topo`) so it is
+ * intentionally excluded.
+ */
+const SOURCE_PARAM_METHOD_NAMES: ReadonlySet<string> = new Set([
+  'check',
+  'checkWithContext',
+]);
+
+/**
+ * String methods that indicate raw-text *scanning* when called on a
+ * source-text identifier. Deliberately narrow: these are the patterns that
+ * produce false positives on string literals, template payloads, and
+ * docstrings — the regression TRL-333/TRL-334/TRL-335 fixed.
+ *
+ * Not flagged: `.slice`, `.substring`, `.indexOf`, `.includes`. These also
+ * take source text as input, but have legitimate AST-adjacent uses — e.g.
+ * `sourceCode.slice(node.start, node.end)` to recover a node's original
+ * text from an AST-resolved range, or `sourceCode.includes('marker')` as a
+ * fast-bail check before parsing. Flagging them would produce false
+ * positives on idiomatic rules.
+ */
+const RAW_SCAN_METHODS: ReadonlySet<string> = new Set([
+  'match',
+  'matchAll',
+  'replace',
+  'replaceAll',
+  'search',
+  'split',
+]);
+
+/**
+ * Methods on a regex receiver that consume a raw-text argument. Flagged
+ * when the argument is a raw-source identifier (`sourceCode`, `text`, etc.).
+ */
+const REGEX_SCAN_METHODS: ReadonlySet<string> = new Set(['exec', 'test']);
+
+const getIdentifierName = (node: AstNode | undefined): string | null => {
+  if (!node || node.type !== 'Identifier') {
+    return null;
+  }
+  const name = getNodeName(node);
+  return typeof name === 'string' ? name : null;
+};
+
+/**
+ * Scope-based source-param resolution. Each detector returns the
+ * candidate `Identifier` AST node that must resolve to the enclosing
+ * `check` / `checkWithContext` method's first parameter binding — i.e.
+ * not shadowed by any intervening `const`/`let`/`var`/param declaration.
+ * See `resolvesToSourceParam` for the walk.
+ */
+interface RawScanSite {
+  readonly methodName: string;
+  readonly identifier: AstNode;
+  readonly identifierName: string;
+  readonly start: number;
+}
+
+interface MemberCallParts {
+  readonly object: AstNode | undefined;
+  readonly property: AstNode | undefined;
+}
+
+/**
+ * Extract the `object`/`property` of a non-computed member call, or null
+ * for anything else. Keeps `rawScanSite` under the max-statements budget.
+ */
+const memberCallParts = (node: AstNode): MemberCallParts | null => {
+  if (node.type !== 'CallExpression') {
+    return null;
+  }
+  const callee = getNodeCallee(node);
+  if (
+    !callee ||
+    (callee.type !== 'MemberExpression' &&
+      callee.type !== 'StaticMemberExpression')
+  ) {
+    return null;
+  }
+  const object = getNodeObject(callee);
+  const property = getNodeProperty(callee);
+  const computed = getNodeComputed(callee);
+  return computed ? null : { object, property };
+};
+
+const rawScanSite = (node: AstNode): RawScanSite | null => {
+  const parts = memberCallParts(node);
+  if (!parts || !parts.object) {
+    return null;
+  }
+  const receiver = getIdentifierName(parts.object);
+  if (!receiver) {
+    return null;
+  }
+  const methodName = getIdentifierName(parts.property);
+  if (!methodName || !RAW_SCAN_METHODS.has(methodName)) {
+    return null;
+  }
+  return {
+    identifier: parts.object,
+    identifierName: receiver,
+    methodName,
+    start: node.start,
+  };
+};
+
+/**
+ * True when `node` is a regex-producing expression: a regex literal
+ * (`/foo/`), `new RegExp(...)`, or a plain `RegExp(...)` call.
+ */
+const isRegexProducer = (node: AstNode | undefined): boolean => {
+  if (!node) {
+    return false;
+  }
+  if (node.type === 'Literal' && 'regex' in node && node['regex']) {
+    return true;
+  }
+  if (node.type === 'RegExpLiteral') {
+    return true;
+  }
+  if (node.type === 'NewExpression' || node.type === 'CallExpression') {
+    const callee = getNodeCallee(node);
+    return getIdentifierName(callee) === 'RegExp';
+  }
+  return false;
+};
+
+/**
+ * First identifier argument of a call expression, or null. The returned
+ * identifier must still resolve to a tracked source-param binding (see
+ * `resolvesToSourceParam`) before a diagnostic is emitted — this pre-filter
+ * only narrows the candidate arg.
+ */
+const firstIdentifierArgument = (
+  node: AstNode
+): { identifier: AstNode; name: string } | null => {
+  const args = getNodeArguments(node);
+  if (!args) {
+    return null;
+  }
+  for (const arg of args) {
+    const name = getIdentifierName(arg);
+    if (name) {
+      return { identifier: arg, name };
+    }
+  }
+  return null;
+};
+
+const regexScanMethodName = (parts: MemberCallParts): string | null => {
+  if (!isRegexProducer(parts.object)) {
+    return null;
+  }
+  const methodName = getIdentifierName(parts.property);
+  if (!methodName || !REGEX_SCAN_METHODS.has(methodName)) {
+    return null;
+  }
+  return methodName;
+};
+
+/**
+ * Detects `/regex/.test(sourceCode)`, `new RegExp(...).exec(text)`, and
+ * similar regex-receiver calls that consume a raw-source identifier.
+ */
+const regexScanSite = (node: AstNode): RawScanSite | null => {
+  const parts = memberCallParts(node);
+  if (!parts) {
+    return null;
+  }
+  const methodName = regexScanMethodName(parts);
+  if (!methodName) {
+    return null;
+  }
+  const arg = firstIdentifierArgument(node);
+  if (!arg) {
+    return null;
+  }
+  return {
+    identifier: arg.identifier,
+    identifierName: arg.name,
+    methodName,
+    start: node.start,
+  };
+};
+
+interface RegexConstructionSite {
+  readonly kind: 'new' | 'call';
+  readonly identifier: AstNode;
+  readonly identifierName: string;
+  readonly start: number;
+}
+
+/**
+ * Detects `new RegExp(sourceCode)` / `RegExp(rawText, 'g')` — constructing a
+ * regex from raw source text. Same anti-pattern family as
+ * `sourceCode.match(...)` and `/re/.test(sourceCode)`: raw source fed into a
+ * scanner. Fires when the callee is an `Identifier` named `RegExp` and at
+ * least one argument is an identifier that resolves, via scope analysis, to
+ * the enclosing `check` / `checkWithContext` method's first parameter.
+ */
+const regexConstructionSite = (node: AstNode): RegexConstructionSite | null => {
+  if (node.type !== 'NewExpression' && node.type !== 'CallExpression') {
+    return null;
+  }
+  const callee = getNodeCallee(node);
+  if (getIdentifierName(callee) !== 'RegExp') {
+    return null;
+  }
+  const arg = firstIdentifierArgument(node);
+  if (!arg) {
+    return null;
+  }
+  return {
+    identifier: arg.identifier,
+    identifierName: arg.name,
+    kind: node.type === 'NewExpression' ? 'new' : 'call',
+    start: node.start,
+  };
+};
+
+const DIAGNOSTIC_ADVICE =
+  'Warden rules must inspect source code via @ontrails/source helpers, not regex-scan raw source text. ' +
+  'Use findStringLiterals, findTrailDefinitions, findConfigProperty, or a similar AST walker. ' +
+  'Raw-text scanning produces false positives on string literals, template payloads, and docstrings — see TRL-335, ADR-0036.';
+
+interface DetectedSite {
+  readonly identifier: AstNode;
+  readonly message: string;
+  readonly severity: 'error' | 'warn';
+  readonly start: number;
+}
+
+const detectRawScan = (node: AstNode): DetectedSite | null => {
+  const scan = rawScanSite(node);
+  if (!scan) {
+    return null;
+  }
+  return {
+    identifier: scan.identifier,
+    message: `${RULE_NAME}: ${scan.identifierName}.${scan.methodName}(...) treats source text as a string. ${DIAGNOSTIC_ADVICE}`,
+    severity: 'error',
+    start: scan.start,
+  };
+};
+
+const detectRegexScan = (node: AstNode): DetectedSite | null => {
+  const regex = regexScanSite(node);
+  if (!regex) {
+    return null;
+  }
+  return {
+    identifier: regex.identifier,
+    message: `${RULE_NAME}: regex.${regex.methodName}(${regex.identifierName}) scans raw source text. ${DIAGNOSTIC_ADVICE}`,
+    severity: 'error',
+    start: regex.start,
+  };
+};
+
+const detectRegexConstruction = (node: AstNode): DetectedSite | null => {
+  const construction = regexConstructionSite(node);
+  if (!construction) {
+    return null;
+  }
+  const prefix = construction.kind === 'new' ? 'new RegExp' : 'RegExp';
+  return {
+    identifier: construction.identifier,
+    message: `${RULE_NAME}: ${prefix}(${construction.identifierName}) constructs a regex from raw source text. ${DIAGNOSTIC_ADVICE}`,
+    severity: 'error',
+    start: construction.start,
+  };
+};
+
+const AST_FIELD_ACCESSORS: ReadonlyMap<string, string> = new Map([
+  ['alternate', 'getNodeAlternate'],
+  ['argument', 'getNodeArgument'],
+  ['arguments', 'getNodeArguments'],
+  ['body', 'getNodeBodyNode or getNodeBodyStatements'],
+  ['callee', 'getNodeCallee'],
+  ['cases', 'getNodeCases'],
+  ['computed', 'getNodeComputed'],
+  ['consequent', 'getNodeConsequent'],
+  ['declaration', 'getNodeDeclaration'],
+  ['declarations', 'getNodeDeclarations'],
+  ['discriminant', 'getNodeDiscriminant'],
+  ['elements', 'getNodeElements'],
+  ['exportKind', 'getNodeExportKind'],
+  ['exported', 'getNodeExported'],
+  ['expression', 'getNodeExpression'],
+  ['id', 'getNodeId'],
+  ['imported', 'getNodeImported'],
+  ['init', 'getNodeInit'],
+  ['key', 'getNodeKey'],
+  ['kind', 'getNodeKind'],
+  ['left', 'getNodeLeft'],
+  ['local', 'getNodeLocal'],
+  ['name', 'getNodeName'],
+  ['object', 'getNodeObject'],
+  ['operator', 'getNodeOperator'],
+  ['param', 'getNodeParam'],
+  ['params', 'getNodeParams'],
+  ['properties', 'getNodeProperties'],
+  ['property', 'getNodeProperty'],
+  ['returnType', 'getNodeReturnType'],
+  ['right', 'getNodeRight'],
+  ['source', 'getNodeSource'],
+  ['specifiers', 'getNodeSpecifiers'],
+  ['superClass', 'getNodeSuperClass'],
+  ['test', 'getNodeTest'],
+  ['typeAnnotation', 'getNodeTypeAnnotation'],
+  ['value', 'getNodeValue or getNodeValueNode'],
+]);
+
+const typeLiteralMembers = (
+  annotation: AstNode | undefined
+): readonly AstNode[] => {
+  if (annotation?.type !== 'TSTypeLiteral') {
+    return [];
+  }
+  const { members } = annotation;
+  return Array.isArray(members) ? members.filter(isAstNode) : [];
+};
+
+const typePropertyName = (member: AstNode): string | null => {
+  if (member.type !== 'TSPropertySignature' || getNodeComputed(member)) {
+    return null;
+  }
+  const key = getNodeKey(member);
+  if (key?.type === 'Identifier') {
+    return getNodeName(key) ?? null;
+  }
+  return key ? getStringValue(key) : null;
+};
+
+const knownAccessorEntries = (
+  annotation: AstNode | undefined
+): readonly [string, string][] =>
+  typeLiteralMembers(annotation).flatMap((member) => {
+    const field = typePropertyName(member);
+    const accessor = field ? AST_FIELD_ACCESSORS.get(field) : undefined;
+    return field && accessor ? [[field, accessor] as const] : [];
+  });
+
+const isUnknownAssertion = (node: AstNode | undefined): node is AstNode =>
+  node?.type === 'TSAsExpression' &&
+  getNodeTypeAnnotation(node)?.type === 'TSUnknownKeyword';
+
+const detectRawNodeFieldCast = (node: AstNode): DetectedSite | null => {
+  if (node.type !== 'TSAsExpression') {
+    return null;
+  }
+  const expression = getNodeExpression(node);
+  if (!isUnknownAssertion(expression)) {
+    return null;
+  }
+  const entries = knownAccessorEntries(getNodeTypeAnnotation(node));
+  if (entries.length === 0) {
+    return null;
+  }
+  const fields = entries.map(([field, accessor]) => `${field} -> ${accessor}`);
+  return {
+    identifier: expression,
+    message: `${RULE_NAME}: raw AST node-field cast should use typed helpers from the shared source helpers (${fields.join(', ')}). Raw node-field casts drift from the shared source helper surface.`,
+    severity: 'warn',
+    start: node.start,
+  };
+};
+
+/**
+ * Dispatch chain for per-node detectors. Each detector tries one family in
+ * priority order. First match wins; descent into children still happens so
+ * nested offenses (e.g. a regex scan inside a callback passed to a raw-text
+ * scan) are still caught.
+ */
+const DETECTORS: readonly ((node: AstNode) => DetectedSite | null)[] = [
+  detectRawScan,
+  detectRegexScan,
+  detectRegexConstruction,
+  detectRawNodeFieldCast,
+];
+
+const detectSite = (node: AstNode): DetectedSite | null => {
+  for (const detector of DETECTORS) {
+    const site = detector(node);
+    if (site) {
+      return site;
+    }
+  }
+  return null;
+};
+
+// ---------------------------------------------------------------------------
+// Scope analysis (Option A — parameter-origin tracking).
+//
+// The pre-TRL-346 detectors gated on identifier spelling alone (a fixed set
+// like `sourceCode`, `text`, `source`, `rawText`). That over-fires on
+// unrelated locals that happen to share one of those names, and under-fires
+// when a rule author picks a different name for the source parameter.
+//
+// Option A walks the AST with a scope stack, records the first parameter of
+// any `check` / `checkWithContext` method (its *actual binding name*), and
+// only flags a call site when the candidate identifier still refers to that
+// exact binding — i.e. no intervening `const`/`let`/`var`/param has
+// shadowed it.
+// ---------------------------------------------------------------------------
+
+interface Scope {
+  readonly declaredNames: ReadonlySet<string>;
+  readonly sourceParamName: string | null;
+}
+
+/**
+ * Walk inner→outer. The first scope that declares `name` is the binding; the
+ * identifier resolves to a tracked source-param only when that declaring
+ * scope's `sourceParamName` matches. An identifier with no declaring scope
+ * (e.g. a free variable) is not a source-param binding.
+ */
+const resolvesToSourceParam = (
+  name: string,
+  scopes: readonly Scope[]
+): boolean => {
+  for (let i = scopes.length - 1; i >= 0; i -= 1) {
+    const scope = scopes[i];
+    if (scope && scope.declaredNames.has(name)) {
+      return scope.sourceParamName === name;
+    }
+  }
+  return false;
+};
+
+const FUNCTION_NODE_TYPES: ReadonlySet<string> = new Set([
+  'ArrowFunctionExpression',
+  'FunctionDeclaration',
+  'FunctionExpression',
+]);
+
+/**
+ * Name of a function-like node when it is a recognized WardenRule method
+ * (`check` or `checkWithContext`). Returns null otherwise.
+ *
+ * Handles three shapes:
+ *   - object-literal method shorthand: `{ check(sc) { ... } }`
+ *     (Property with `method: true`, or MethodDefinition)
+ *   - arrow/function property: `{ check: (sc) => { ... } }`
+ *   - top-level function declaration: `function check(sc) { ... }`
+ *
+ * The context-to-function link is resolved by the caller via the
+ * `methodFunctionStarts` map: we pre-walk the AST once to map the start
+ * offset of every recognized function to its method name, then consult the
+ * map when the scope walker enters that function.
+ */
+const methodNameFromKey = (key: AstNode | undefined): string | null => {
+  if (!key) {
+    return null;
+  }
+  if (key.type === 'Identifier') {
+    return getNodeName(key) ?? null;
+  }
+  // String-literal keys like `'check': (sc) => { ... }`.
+  if (
+    (key.type === 'Literal' || key.type === 'StringLiteral') &&
+    getStringValue(key) !== null
+  ) {
+    return getStringValue(key);
+  }
+  return null;
+};
+
+const firstParamIdentifierName = (fn: AstNode): string | null => {
+  const params = getNodeParams(fn);
+  const [first] = params ?? [];
+  if (!first) {
+    return null;
+  }
+  if (first.type === 'Identifier') {
+    return getIdentifierName(first);
+  }
+  if (first.type === 'AssignmentPattern') {
+    const left = getNodeLeft(first);
+    return left?.type === 'Identifier' ? getIdentifierName(left) : null;
+  }
+  return null;
+};
+
+/**
+ * Collect start offsets of function-like AST nodes that represent the body
+ * of a recognized WardenRule source-receiving method. Value is the declared
+ * first-parameter name, used as `sourceParamName` when the scope walker
+ * pushes that function's scope.
+ */
+const methodPropertyFunction = (
+  node: AstNode
+): { fn: AstNode; name: string } | null => {
+  const key = getNodeKey(node);
+  const value = getNodeValueNode(node);
+  const name = methodNameFromKey(key);
+  if (!name || !value || !FUNCTION_NODE_TYPES.has(value.type)) {
+    return null;
+  }
+  return SOURCE_PARAM_METHOD_NAMES.has(name) ? { fn: value, name } : null;
+};
+
+const namedFunctionDeclaration = (
+  node: AstNode
+): { fn: AstNode; name: string } | null => {
+  const name = getIdentifierName(getNodeId(node));
+  if (!name || !SOURCE_PARAM_METHOD_NAMES.has(name)) {
+    return null;
+  }
+  return { fn: node, name };
+};
+
+const recognizedMethodFunction = (
+  node: AstNode
+): { fn: AstNode; name: string } | null => {
+  if (node.type === 'Property' || node.type === 'MethodDefinition') {
+    return methodPropertyFunction(node);
+  }
+  if (node.type === 'FunctionDeclaration') {
+    return namedFunctionDeclaration(node);
+  }
+  return null;
+};
+
+const buildSourceParamIndex = (ast: AstNode): ReadonlyMap<number, string> => {
+  const index = new Map<number, string>();
+  walk(ast, (node) => {
+    const recognized = recognizedMethodFunction(node);
+    if (!recognized) {
+      return;
+    }
+    const paramName = firstParamIdentifierName(recognized.fn);
+    if (paramName) {
+      index.set(recognized.fn.start, paramName);
+    }
+  });
+  return index;
+};
+
+/**
+ * Collect identifier names introduced at this scope by
+ * `const`/`let`/`var`/function declarations or function params. We only
+ * inspect direct children — nested block statements and nested functions
+ * have their own scopes.
+ */
+const expandObjectPatternProperty = (property: AstNode): readonly AstNode[] => {
+  if (property.type === 'Property') {
+    const value = getNodeValueNode(property);
+    return value ? [value] : [];
+  }
+  if (property.type === 'RestElement') {
+    const argument = getNodeArgument(property);
+    return argument ? [argument] : [];
+  }
+  return [];
+};
+
+const PATTERN_EXPANDERS: Record<string, (p: AstNode) => readonly AstNode[]> = {
+  ArrayPattern: (pattern) => {
+    const elements = getNodeElements(pattern);
+    return elements.filter((el): el is AstNode => el !== null);
+  },
+  AssignmentPattern: (pattern) => {
+    const left = getNodeLeft(pattern);
+    return left ? [left] : [];
+  },
+  ObjectPattern: (pattern) => {
+    const properties = getNodeProperties(pattern) ?? [];
+    return properties.flatMap(expandObjectPatternProperty);
+  },
+  RestElement: (pattern) => {
+    const argument = getNodeArgument(pattern);
+    return argument ? [argument] : [];
+  },
+};
+
+/**
+ * Collect identifier names introduced by a binding pattern (function
+ * parameter, destructuring target, etc.). Iterative worklist over
+ * {@link PATTERN_EXPANDERS}: each expander yields one level of child
+ * patterns, and the loop bottoms out at `Identifier` nodes. The iterative
+ * shape avoids mutual recursion so every helper stays under the
+ * `max-statements` budget.
+ */
+const visitPatternNode = (
+  current: AstNode,
+  into: Set<string>,
+  worklist: AstNode[]
+): void => {
+  if (current.type === 'Identifier') {
+    const name = getIdentifierName(current);
+    if (name) {
+      into.add(name);
+    }
+    return;
+  }
+  const expand = PATTERN_EXPANDERS[current.type];
+  if (expand) {
+    worklist.push(...expand(current));
+  }
+};
+
+const collectBindingIdsFromPattern = (
+  pattern: AstNode | undefined,
+  into: Set<string>
+): void => {
+  if (!pattern) {
+    return;
+  }
+  const worklist: AstNode[] = [pattern];
+  while (worklist.length > 0) {
+    const current = worklist.pop();
+    if (current) {
+      visitPatternNode(current, into, worklist);
+    }
+  }
+};
+
+interface FunctionScopeBindingsEx {
+  /** Param names exactly — used to identify the source-param binding. */
+  readonly paramNames: Set<string>;
+  /** Hoisted `var` names inside the function body. May overlap with params. */
+  readonly hoistedVarNames: Set<string>;
+  /** Combined set of declared names visible in this function scope. */
+  readonly declaredNames: Set<string>;
+}
+
+const collectParamBindingsFromFunction = (fn: AstNode): Set<string> => {
+  const paramNames = new Set<string>();
+  const params = getNodeParams(fn) ?? [];
+  for (const param of params) {
+    collectBindingIdsFromPattern(param, paramNames);
+  }
+  return paramNames;
+};
+
+const collectHoistedVarsFromFunctionBody = (fn: AstNode): Set<string> => {
+  const hoistedVarNames = new Set<string>();
+  const body = getNodeBodyNode(fn);
+  if (body && typeof body === 'object' && (body as AstNode).type) {
+    // eslint-disable-next-line no-use-before-define
+    collectHoistedVarBindings(body, hoistedVarNames);
+  }
+  return hoistedVarNames;
+};
+
+/**
+ * Combine param names and body-level hoisted `var` names into a single
+ * declared-names set, while keeping the two subsets addressable. The
+ * hoisted set is kept separate so the scope walker can tell whether a
+ * source-param identity has been overwritten by a same-named hoisted local —
+ * a shadow that would otherwise be invisible because both names live in the
+ * same function-scope binding set.
+ */
+const collectFunctionScopeBindingsEx = (
+  fn: AstNode
+): FunctionScopeBindingsEx => {
+  const paramNames = collectParamBindingsFromFunction(fn);
+  const hoistedVarNames = collectHoistedVarsFromFunctionBody(fn);
+  const declaredNames = new Set<string>(paramNames);
+  for (const name of hoistedVarNames) {
+    declaredNames.add(name);
+  }
+  return { declaredNames, hoistedVarNames, paramNames };
+};
+
+const addVariableDeclarationNames = (
+  stmt: AstNode,
+  names: Set<string>
+): void => {
+  const declarations = getNodeDeclarations(stmt) ?? [];
+  for (const decl of declarations) {
+    collectBindingIdsFromPattern(getNodeId(decl), names);
+  }
+};
+
+const isVarVariableDeclaration = (stmt: AstNode): boolean =>
+  stmt.type === 'VariableDeclaration' && getNodeKind(stmt) === 'var';
+
+/**
+ * True when `node` owns its own VariableEnvironment and therefore stops `var`
+ * hoisting from composing into the enclosing function/program scope.
+ */
+const ownsVariableEnvironmentForHoisting = (node: AstNode): boolean =>
+  FUNCTION_NODE_TYPES.has(node.type) || node.type === 'StaticBlock';
+
+/**
+ * Collect `var` declarations that hoist to the nearest function (or program)
+ * scope from anywhere inside `root`, without composing a nested function or
+ * static-block boundary. Mirrors the hoisting semantics used by
+ * {@link ./no-sync-result-assumption.ts} so `if (cond) { var sourceCode = ... }`
+ * inside a `check()` body correctly shadows the method's first parameter.
+ */
+const collectHoistedVarBindings = (root: AstNode, out: Set<string>): void => {
+  const walkVar = (node: AstNode, isRoot: boolean): void => {
+    if (!isRoot && ownsVariableEnvironmentForHoisting(node)) {
+      return;
+    }
+    if (isVarVariableDeclaration(node)) {
+      addVariableDeclarationNames(node, out);
+    }
+    for (const val of Object.values(node)) {
+      if (Array.isArray(val)) {
+        for (const item of val) {
+          if (item && typeof item === 'object' && (item as AstNode).type) {
+            walkVar(item as AstNode, false);
+          }
+        }
+      } else if (val && typeof val === 'object' && (val as AstNode).type) {
+        walkVar(val as AstNode, false);
+      }
+    }
+  };
+  walkVar(root, true);
+};
+
+const addFunctionDeclarationName = (
+  stmt: AstNode,
+  names: Set<string>
+): void => {
+  const name = getIdentifierName(getNodeId(stmt));
+  if (name) {
+    names.add(name);
+  }
+};
+
+const collectBlockDeclarationNames = (block: AstNode): Set<string> => {
+  const names = new Set<string>();
+  const body = getNodeBodyStatements(block);
+  for (const stmt of body) {
+    // `var` is function-scoped, not block-scoped — hoisted into the nearest
+    // enclosing function (or program) scope by
+    // {@link collectHoistedVarBindings}. Registering it here would make
+    // `if (cond) { var x = ... }` look block-local and fail to shadow a
+    // same-named outer binding when the write escapes the block.
+    if (
+      stmt.type === 'VariableDeclaration' &&
+      !isVarVariableDeclaration(stmt)
+    ) {
+      addVariableDeclarationNames(stmt, names);
+    } else if (stmt.type === 'FunctionDeclaration') {
+      addFunctionDeclarationName(stmt, names);
+    }
+  }
+  return names;
+};
+
+/**
+ * Collect the names a `CatchClause` parameter introduces into its body. The
+ * catch clause has its own binding scope distinct from the surrounding block;
+ * without this, `try {} catch (sourceCode) { sourceCode.split(...) }` would
+ * resolve `sourceCode` to the enclosing `check()` parameter and fire.
+ */
+const collectCatchClauseDeclarationNames = (node: AstNode): Set<string> => {
+  const names = new Set<string>();
+  const param = getNodeParam(node);
+  collectBindingIdsFromPattern(param, names);
+  return names;
+};
+
+interface ScopeWalkContext {
+  readonly diagnostics: WardenDiagnostic[];
+  readonly filePath: string;
+  readonly methodFunctionStarts: ReadonlyMap<number, string>;
+  readonly sourceCode: string;
+}
+
+const recordDiagnostic = (ctx: ScopeWalkContext, site: DetectedSite): void => {
+  ctx.diagnostics.push({
+    filePath: ctx.filePath,
+    line: offsetToLine(ctx.sourceCode, site.start),
+    message: site.message,
+    rule: RULE_NAME,
+    severity: site.severity,
+  });
+};
+
+/**
+ * Emit a diagnostic if `node` is a detected site whose candidate identifier
+ * resolves (via the current scope stack) to a tracked source-param binding.
+ */
+const maybeRecordDetection = (
+  node: AstNode,
+  scopes: readonly Scope[],
+  ctx: ScopeWalkContext
+): void => {
+  const site = detectSite(node);
+  if (!site) {
+    return;
+  }
+  if (site.severity === 'warn') {
+    recordDiagnostic(ctx, site);
+    return;
+  }
+  const name = getIdentifierName(site.identifier);
+  if (name && resolvesToSourceParam(name, scopes)) {
+    recordDiagnostic(ctx, site);
+  }
+};
+
+/**
+ * Resolve the effective source-param name for a function scope. A hoisted
+ * `var` with the same name as the source param overwrites the param's slot
+ * in the function's VariableEnvironment, so the enclosing identifier no
+ * longer resolves to the raw-source binding.
+ */
+const resolveScopeSourceParamName = (
+  methodParamName: string | null,
+  hoistedVarNames: ReadonlySet<string>
+): string | null =>
+  methodParamName && hoistedVarNames.has(methodParamName)
+    ? null
+    : methodParamName;
+
+const pushFunctionScope = (
+  node: AstNode,
+  ctx: ScopeWalkContext,
+  scopes: Scope[]
+): void => {
+  const methodParamName = ctx.methodFunctionStarts.get(node.start) ?? null;
+  const { declaredNames, hoistedVarNames } =
+    collectFunctionScopeBindingsEx(node);
+  scopes.push({
+    declaredNames,
+    sourceParamName: resolveScopeSourceParamName(
+      methodParamName,
+      hoistedVarNames
+    ),
+  });
+};
+
+/** Collector for scope frames that carry no source-param identity. */
+const SIMPLE_SCOPE_COLLECTORS: Record<
+  string,
+  (node: AstNode) => ReadonlySet<string>
+> = {
+  BlockStatement: collectBlockDeclarationNames,
+  CatchClause: collectCatchClauseDeclarationNames,
+};
+
+/**
+ * Push the scope a function node introduces, or null when the node is not
+ * scope-introducing. Returning a dispose function keeps `visitWithScopes`
+ * small and keeps the scope stack strictly paired.
+ */
+const enterScopeForNode = (
+  node: AstNode,
+  ctx: ScopeWalkContext,
+  scopes: Scope[]
+): boolean => {
+  if (FUNCTION_NODE_TYPES.has(node.type)) {
+    pushFunctionScope(node, ctx, scopes);
+    return true;
+  }
+  const collector = SIMPLE_SCOPE_COLLECTORS[node.type];
+  if (collector) {
+    scopes.push({
+      declaredNames: collector(node),
+      sourceParamName: null,
+    });
+    return true;
+  }
+  return false;
+};
+
+interface EnterFrame {
+  kind: 'enter';
+  node: AstNode;
+}
+type WalkFrame = EnterFrame | { kind: 'leave'; pushed: boolean };
+
+/**
+ * Build "enter" frames for every AST child of `node`. Returned reversed so
+ * consumers can `Array#push(...frames)` onto a stack and still visit
+ * children in source order via `Array#pop`.
+ */
+const collectChildFrames = (node: AstNode): readonly EnterFrame[] => {
+  const frames: EnterFrame[] = [];
+  for (const value of Object.values(node)) {
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (item && typeof item === 'object' && (item as AstNode).type) {
+          frames.push({ kind: 'enter', node: item as AstNode });
+        }
+      }
+      continue;
+    }
+    if (value && typeof value === 'object' && (value as AstNode).type) {
+      frames.push({ kind: 'enter', node: value as AstNode });
+    }
+  }
+  return frames.toReversed();
+};
+
+const processFrame = (
+  frame: WalkFrame,
+  scopes: Scope[],
+  ctx: ScopeWalkContext,
+  stack: WalkFrame[]
+): void => {
+  if (frame.kind === 'leave') {
+    if (frame.pushed) {
+      scopes.pop();
+    }
+    return;
+  }
+  const { node } = frame;
+  maybeRecordDetection(node, scopes, ctx);
+  const pushed = enterScopeForNode(node, ctx, scopes);
+  stack.push({ kind: 'leave', pushed });
+  stack.push(...collectChildFrames(node));
+};
+
+/**
+ * Scope-aware AST walker. Iterative DFS: each enter frame schedules the
+ * node's children in source order and queues a matching leave frame so
+ * scope pops stay balanced with their pushes.
+ */
+const analyze = (
+  sourceCode: string,
+  filePath: string,
+  ast: AstNode
+): readonly WardenDiagnostic[] => {
+  const ctx: ScopeWalkContext = {
+    diagnostics: [],
+    filePath,
+    methodFunctionStarts: buildSourceParamIndex(ast),
+    sourceCode,
+  };
+  const scopes: Scope[] = [];
+  const stack: WalkFrame[] = [{ kind: 'enter', node: ast }];
+  while (stack.length > 0) {
+    const frame = stack.pop();
+    if (frame) {
+      processFrame(frame, scopes, ctx, stack);
+    }
+  }
+  return ctx.diagnostics;
+};
+
+/**
+ * Warden rule enforcing that warden rules themselves walk the AST rather than
+ * regex-scan raw source text or hand-cast recurring AST node fields.
+ */
+export const wardenRulesUseAst: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (!isTargetFile(filePath)) {
+      return [];
+    }
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+    return analyze(sourceCode, filePath, ast);
+  },
+  description:
+    'Enforces that warden rules inspect source code via @ontrails/source helpers rather than regex-scanning raw source text or hand-casting node fields.',
+  name: RULE_NAME,
+  severity: 'error',
+};