@ontrails/warden 1.0.0-beta.24 → 1.0.0-beta.29

package/src/rules/ast.ts

@@ -12,6 +12,12 @@ import { fileURLToPath } from 'node:url';
 import { DRAFT_ID_PREFIX, intentValues } from '@ontrails/core';
 import type { Intent } from '@ontrails/core';
 import { parseSync } from 'oxc-parser';
+import { ScopeTracker, walk as walkWithOxc } from 'oxc-walker';
+import type {
+  ScopeTrackerNode,
+  WalkerCallbackContext,
+  WalkOptions,
+} from 'oxc-walker';
 
 // ---------------------------------------------------------------------------
 // Types (minimal, avoiding full @oxc-project/types dep)
@@ -21,20 +27,640 @@ export interface AstNode {
   readonly type: string;
   readonly start: number;
   readonly end: number;
-  readonly key?: { readonly name?: string };
+  readonly parent?: AstNode | null;
+  readonly key?: unknown;
   readonly value?: unknown;
   readonly body?: AstNode | readonly AstNode[];
   readonly [key: string]: unknown;
 }
 
-interface StringLiteralNode extends AstNode {
+export interface ProgramNode extends AstNode {
+  readonly type: 'Program';
+  readonly body?: readonly AstNode[];
+}
+
+export interface IdentifierNode extends AstNode {
+  readonly type: 'Identifier';
+  readonly name?: string;
+}
+
+export interface StringLiteralNode extends AstNode {
   readonly type: 'Literal' | 'StringLiteral';
   readonly value?: unknown;
 }
 
-const isAstNode = (value: unknown): value is AstNode =>
+export interface CallExpressionNode extends AstNode {
+  readonly type: 'CallExpression' | 'NewExpression';
+  readonly arguments?: readonly AstNode[];
+  readonly callee?: AstNode;
+}
+
+export interface MemberExpressionNode extends AstNode {
+  readonly type: 'MemberExpression' | 'StaticMemberExpression';
+  readonly computed?: boolean;
+  readonly object?: AstNode;
+  readonly property?: AstNode;
+}
+
+export interface ImportDeclarationNode extends AstNode {
+  readonly type: 'ImportDeclaration';
+  readonly source?: AstNode;
+  readonly specifiers?: readonly AstNode[];
+}
+
+export interface ImportSpecifierNode extends AstNode {
+  readonly type:
+    | 'ImportDefaultSpecifier'
+    | 'ImportNamespaceSpecifier'
+    | 'ImportSpecifier';
+  readonly imported?: AstNode;
+  readonly local?: AstNode;
+}
+
+export interface ExportDeclarationNode extends AstNode {
+  readonly type:
+    | 'ExportAllDeclaration'
+    | 'ExportDefaultDeclaration'
+    | 'ExportNamedDeclaration';
+  readonly declaration?: AstNode;
+  readonly source?: AstNode;
+  readonly specifiers?: readonly AstNode[];
+}
+
+export interface ExportSpecifierNode extends AstNode {
+  readonly type: 'ExportSpecifier';
+  readonly exportKind?: string;
+  readonly exported?: AstNode;
+  readonly local?: AstNode;
+}
+
+export interface VariableDeclarationNode extends AstNode {
+  readonly type: 'VariableDeclaration';
+  readonly declarations?: readonly AstNode[];
+  readonly kind?: string;
+}
+
+export interface VariableDeclaratorNode extends AstNode {
+  readonly type: 'VariableDeclarator';
+  readonly id?: AstNode;
+  readonly init?: AstNode;
+}
+
+export interface DeclarationWithIdNode extends AstNode {
+  readonly type:
+    | 'ClassDeclaration'
+    | 'FunctionDeclaration'
+    | 'InterfaceDeclaration'
+    | 'TSInterfaceDeclaration'
+    | 'TSTypeAliasDeclaration';
+  readonly id?: AstNode;
+}
+
+export interface ClassMemberNode extends AstNode {
+  readonly type: 'MethodDefinition' | 'PropertyDefinition';
+  readonly computed?: boolean;
+  readonly key?: AstNode;
+  readonly value?: AstNode;
+}
+
+export interface ArrayExpressionNode extends AstNode {
+  readonly type: 'ArrayExpression';
+  readonly elements?: readonly (AstNode | null)[];
+}
+
+export interface ObjectExpressionNode extends AstNode {
+  readonly type: 'ObjectExpression' | 'ObjectPattern';
+  readonly properties?: readonly AstNode[];
+}
+
+export interface PropertyNode extends AstNode {
+  readonly type: 'Property';
+  readonly computed?: boolean;
+  readonly key?: AstNode;
+  readonly value?: AstNode;
+}
+
+export interface RestElementNode extends AstNode {
+  readonly type: 'RestElement';
+  readonly argument?: AstNode;
+}
+
+export interface AssignmentPatternNode extends AstNode {
+  readonly type: 'AssignmentPattern';
+  readonly left?: AstNode;
+  readonly right?: AstNode;
+}
+
+export interface ExpressionStatementNode extends AstNode {
+  readonly type: 'ExpressionStatement';
+  readonly expression?: AstNode;
+}
+
+export interface UnaryExpressionNode extends AstNode {
+  readonly type: 'AwaitExpression' | 'ChainExpression' | 'UnaryExpression';
+  readonly argument?: AstNode;
+}
+
+export interface BinaryExpressionNode extends AstNode {
+  readonly type:
+    | 'AssignmentExpression'
+    | 'BinaryExpression'
+    | 'ConditionalExpression'
+    | 'LogicalExpression';
+  readonly alternate?: AstNode;
+  readonly consequent?: AstNode;
+  readonly left?: AstNode;
+  readonly operator?: string;
+  readonly right?: AstNode;
+  readonly test?: AstNode;
+}
+
+export interface FunctionLikeNode extends AstNode {
+  readonly type:
+    | 'ArrowFunctionExpression'
+    | 'FunctionDeclaration'
+    | 'FunctionExpression';
+  readonly body?: AstNode;
+  readonly params?: readonly AstNode[];
+}
+
+export interface BlockStatementNode extends AstNode {
+  readonly type: 'BlockStatement' | 'StaticBlock';
+  readonly body?: readonly AstNode[];
+}
+
+export interface ReturnStatementNode extends AstNode {
+  readonly type: 'ReturnStatement';
+  readonly argument?: AstNode;
+}
+
+export type CuratedAstNode =
+  | ArrayExpressionNode
+  | AssignmentPatternNode
+  | BinaryExpressionNode
+  | BlockStatementNode
+  | CallExpressionNode
+  | ClassMemberNode
+  | DeclarationWithIdNode
+  | ExportDeclarationNode
+  | ExportSpecifierNode
+  | ExpressionStatementNode
+  | FunctionLikeNode
+  | IdentifierNode
+  | ImportDeclarationNode
+  | ImportSpecifierNode
+  | MemberExpressionNode
+  | ObjectExpressionNode
+  | ProgramNode
+  | PropertyNode
+  | RestElementNode
+  | ReturnStatementNode
+  | StringLiteralNode
+  | UnaryExpressionNode
+  | VariableDeclarationNode
+  | VariableDeclaratorNode;
+
+export interface AstParentContext {
+  readonly index: number | null;
+  readonly key: string | number | symbol | null | undefined;
+  readonly parent: AstNode | null;
+}
+
+export interface AstScopeDeclaration {
+  readonly end: number;
+  readonly node: AstNode;
+  readonly start: number;
+  readonly type: string;
+}
+
+export interface AstScopeContext extends AstParentContext {
+  readonly currentScope: string;
+  readonly getDeclaration: (name: string) => AstScopeDeclaration | null;
+  readonly isDeclared: (name: string) => boolean;
+  readonly isCurrentScopeUnder: (scope: string) => boolean;
+}
+
+export interface SourceEdit {
+  readonly end: number;
+  readonly replacement: string;
+  readonly start: number;
+}
+
+export interface SourceLocation {
+  readonly column: number;
+  readonly line: number;
+}
+
+export interface AstParseDiagnosticLabel {
+  readonly end: number;
+  readonly message: string | null;
+  readonly start: number;
+}
+
+export interface AstParseDiagnostic {
+  readonly helpMessage: string | null;
+  readonly labels: readonly AstParseDiagnosticLabel[];
+  readonly message: string;
+  readonly severity: string;
+}
+
+export interface AstParseResult {
+  readonly ast: AstNode | null;
+  readonly diagnostics: readonly AstParseDiagnostic[];
+}
+
+export interface AstFieldProjection {
+  readonly alternate?: AstNode;
+  readonly argument?: AstNode;
+  readonly arguments?: readonly AstNode[];
+  readonly body?: AstNode | readonly AstNode[];
+  readonly callee?: AstNode;
+  readonly cases?: readonly AstNode[];
+  readonly computed?: boolean;
+  readonly consequent?: AstNode;
+  readonly declaration?: AstNode;
+  readonly declarations?: readonly AstNode[];
+  readonly discriminant?: AstNode;
+  readonly elements?: readonly (AstNode | null)[];
+  readonly exportKind?: string;
+  readonly exported?: AstNode;
+  readonly expression?: AstNode;
+  readonly id?: AstNode;
+  readonly imported?: AstNode;
+  readonly init?: AstNode;
+  readonly key?: AstNode;
+  readonly kind?: string;
+  readonly left?: AstNode;
+  readonly local?: AstNode;
+  readonly name?: string;
+  readonly object?: AstNode;
+  readonly operator?: string;
+  readonly param?: AstNode;
+  readonly params?: readonly AstNode[];
+  readonly properties?: readonly AstNode[];
+  readonly property?: AstNode;
+  readonly returnType?: AstNode;
+  readonly right?: AstNode;
+  readonly source?: AstNode;
+  readonly specifiers?: readonly AstNode[];
+  readonly superClass?: AstNode;
+  readonly test?: AstNode;
+  readonly typeAnnotation?: AstNode;
+  readonly value?: unknown;
+}
+
+export const isAstNode = (value: unknown): value is AstNode =>
   Boolean(value && typeof value === 'object' && (value as AstNode).type);
 
+const isNodeType = <TNode extends CuratedAstNode>(
+  node: AstNode | null | undefined,
+  types: readonly string[]
+): node is TNode =>
+  node !== null && node !== undefined && types.includes(node.type);
+
+export const isProgram = (
+  node: AstNode | null | undefined
+): node is ProgramNode => isNodeType<ProgramNode>(node, ['Program']);
+
+export const isIdentifier = (
+  node: AstNode | null | undefined
+): node is IdentifierNode => isNodeType<IdentifierNode>(node, ['Identifier']);
+
+export const isCallExpression = (
+  node: AstNode | null | undefined
+): node is CallExpressionNode =>
+  isNodeType<CallExpressionNode>(node, ['CallExpression', 'NewExpression']);
+
+export const isMemberExpression = (
+  node: AstNode | null | undefined
+): node is MemberExpressionNode =>
+  isNodeType<MemberExpressionNode>(node, [
+    'MemberExpression',
+    'StaticMemberExpression',
+  ]);
+
+export const isImportDeclaration = (
+  node: AstNode | null | undefined
+): node is ImportDeclarationNode =>
+  isNodeType<ImportDeclarationNode>(node, ['ImportDeclaration']);
+
+export const isImportSpecifier = (
+  node: AstNode | null | undefined
+): node is ImportSpecifierNode =>
+  isNodeType<ImportSpecifierNode>(node, [
+    'ImportDefaultSpecifier',
+    'ImportNamespaceSpecifier',
+    'ImportSpecifier',
+  ]);
+
+export const isExportDeclaration = (
+  node: AstNode | null | undefined
+): node is ExportDeclarationNode =>
+  isNodeType<ExportDeclarationNode>(node, [
+    'ExportAllDeclaration',
+    'ExportDefaultDeclaration',
+    'ExportNamedDeclaration',
+  ]);
+
+export const isExportNamedDeclaration = (
+  node: AstNode | null | undefined
+): node is ExportDeclarationNode & {
+  readonly type: 'ExportNamedDeclaration';
+} =>
+  isNodeType<
+    ExportDeclarationNode & { readonly type: 'ExportNamedDeclaration' }
+  >(node, ['ExportNamedDeclaration']);
+
+export const isExportDefaultDeclaration = (
+  node: AstNode | null | undefined
+): node is ExportDeclarationNode & {
+  readonly type: 'ExportDefaultDeclaration';
+} =>
+  isNodeType<
+    ExportDeclarationNode & { readonly type: 'ExportDefaultDeclaration' }
+  >(node, ['ExportDefaultDeclaration']);
+
+export const isExportAllDeclaration = (
+  node: AstNode | null | undefined
+): node is ExportDeclarationNode & { readonly type: 'ExportAllDeclaration' } =>
+  isNodeType<ExportDeclarationNode & { readonly type: 'ExportAllDeclaration' }>(
+    node,
+    ['ExportAllDeclaration']
+  );
+
+export const isExportSpecifier = (
+  node: AstNode | null | undefined
+): node is ExportSpecifierNode =>
+  isNodeType<ExportSpecifierNode>(node, ['ExportSpecifier']);
+
+export const isVariableDeclaration = (
+  node: AstNode | null | undefined
+): node is VariableDeclarationNode =>
+  isNodeType<VariableDeclarationNode>(node, ['VariableDeclaration']);
+
+export const isVariableDeclarator = (
+  node: AstNode | null | undefined
+): node is VariableDeclaratorNode =>
+  isNodeType<VariableDeclaratorNode>(node, ['VariableDeclarator']);
+
+export const isDeclarationWithId = (
+  node: AstNode | null | undefined
+): node is DeclarationWithIdNode =>
+  isNodeType<DeclarationWithIdNode>(node, [
+    'ClassDeclaration',
+    'FunctionDeclaration',
+    'InterfaceDeclaration',
+    'TSInterfaceDeclaration',
+    'TSTypeAliasDeclaration',
+  ]);
+
+export const isClassMember = (
+  node: AstNode | null | undefined
+): node is ClassMemberNode =>
+  isNodeType<ClassMemberNode>(node, ['MethodDefinition', 'PropertyDefinition']);
+
+export const isArrayExpression = (
+  node: AstNode | null | undefined
+): node is ArrayExpressionNode =>
+  isNodeType<ArrayExpressionNode>(node, ['ArrayExpression']);
+
+export const isObjectExpression = (
+  node: AstNode | null | undefined
+): node is ObjectExpressionNode =>
+  isNodeType<ObjectExpressionNode>(node, ['ObjectExpression', 'ObjectPattern']);
+
+export const isProperty = (
+  node: AstNode | null | undefined
+): node is PropertyNode => isNodeType<PropertyNode>(node, ['Property']);
+
+export const isRestElement = (
+  node: AstNode | null | undefined
+): node is RestElementNode =>
+  isNodeType<RestElementNode>(node, ['RestElement']);
+
+export const isAssignmentPattern = (
+  node: AstNode | null | undefined
+): node is AssignmentPatternNode =>
+  isNodeType<AssignmentPatternNode>(node, ['AssignmentPattern']);
+
+export const isExpressionStatement = (
+  node: AstNode | null | undefined
+): node is ExpressionStatementNode =>
+  isNodeType<ExpressionStatementNode>(node, ['ExpressionStatement']);
+
+export const isUnaryExpression = (
+  node: AstNode | null | undefined
+): node is UnaryExpressionNode =>
+  isNodeType<UnaryExpressionNode>(node, [
+    'AwaitExpression',
+    'ChainExpression',
+    'UnaryExpression',
+  ]);
+
+export const isBinaryExpression = (
+  node: AstNode | null | undefined
+): node is BinaryExpressionNode =>
+  isNodeType<BinaryExpressionNode>(node, [
+    'AssignmentExpression',
+    'BinaryExpression',
+    'ConditionalExpression',
+    'LogicalExpression',
+  ]);
+
+export const isFunctionLike = (
+  node: AstNode | null | undefined
+): node is FunctionLikeNode =>
+  isNodeType<FunctionLikeNode>(node, [
+    'ArrowFunctionExpression',
+    'FunctionDeclaration',
+    'FunctionExpression',
+  ]);
+
+export const isBlockStatement = (
+  node: AstNode | null | undefined
+): node is BlockStatementNode =>
+  isNodeType<BlockStatementNode>(node, ['BlockStatement', 'StaticBlock']);
+
+export const isReturnStatement = (
+  node: AstNode | null | undefined
+): node is ReturnStatementNode =>
+  isNodeType<ReturnStatementNode>(node, ['ReturnStatement']);
+
+const projectAstFields = (
+  node: AstNode | null | undefined
+): AstFieldProjection | null => (node ? (node as AstFieldProjection) : null);
+
+export const getNodeAlternate = (
+  node: AstNode | null | undefined
+): AstNode | undefined => projectAstFields(node)?.alternate;
+
+export const getNodeArgument = (
+  node: AstNode | null | undefined
+): AstNode | undefined => projectAstFields(node)?.argument;
+
+export const getNodeArguments = (
+  node: AstNode | null | undefined
+): readonly AstNode[] => (isCallExpression(node) ? (node.arguments ?? []) : []);
+
+export const getNodeBody = (
+  node: AstNode | null | undefined
+): AstNode | readonly AstNode[] | undefined => projectAstFields(node)?.body;
+
+export const getNodeBodyNode = (
+  node: AstNode | null | undefined
+): AstNode | undefined => {
+  const body = getNodeBody(node);
+  return isAstNode(body) ? body : undefined;
+};
+
+export const getNodeBodyStatements = (
+  node: AstNode | null | undefined
+): readonly AstNode[] => {
+  const body = getNodeBody(node);
+  return Array.isArray(body) ? body : [];
+};
+
+export const getNodeCallee = (
+  node: AstNode | null | undefined
+): AstNode | undefined => (isCallExpression(node) ? node.callee : undefined);
+
+export const getNodeCases = (
+  node: AstNode | null | undefined
+): readonly AstNode[] => projectAstFields(node)?.cases ?? [];
+
+export const getNodeComputed = (
+  node: AstNode | null | undefined
+): boolean | undefined => projectAstFields(node)?.computed;
+
+export const getNodeConsequent = (
+  node: AstNode | null | undefined
+): AstNode | undefined => projectAstFields(node)?.consequent;
+
+export const getNodeDeclaration = (
+  node: AstNode | null | undefined
+): AstNode | undefined => projectAstFields(node)?.declaration;
+
+export const getNodeDeclarations = (
+  node: AstNode | null | undefined
+): readonly AstNode[] =>
+  isVariableDeclaration(node) ? (node.declarations ?? []) : [];
+
+export const getNodeDiscriminant = (
+  node: AstNode | null | undefined
+): AstNode | undefined => projectAstFields(node)?.discriminant;
+
+export const getNodeElements = (
+  node: AstNode | null | undefined
+): readonly (AstNode | null)[] => projectAstFields(node)?.elements ?? [];
+
+export const getNodeExported = (
+  node: AstNode | null | undefined
+): AstNode | undefined => projectAstFields(node)?.exported;
+
+export const getNodeExportKind = (
+  node: AstNode | null | undefined
+): string | undefined => projectAstFields(node)?.exportKind;
+
+export const getNodeExpression = (
+  node: AstNode | null | undefined
+): AstNode | undefined => projectAstFields(node)?.expression;
+
+export const getNodeId = (
+  node: AstNode | null | undefined
+): AstNode | undefined => projectAstFields(node)?.id;
+
+export const getNodeImported = (
+  node: AstNode | null | undefined
+): AstNode | undefined => projectAstFields(node)?.imported;
+
+export const getNodeInit = (
+  node: AstNode | null | undefined
+): AstNode | undefined => projectAstFields(node)?.init;
+
+export const getNodeKey = (
+  node: AstNode | null | undefined
+): AstNode | undefined => projectAstFields(node)?.key;
+
+export const getNodeKind = (
+  node: AstNode | null | undefined
+): string | undefined => projectAstFields(node)?.kind;
+
+export const getNodeLeft = (
+  node: AstNode | null | undefined
+): AstNode | undefined => projectAstFields(node)?.left;
+
+export const getNodeLocal = (
+  node: AstNode | null | undefined
+): AstNode | undefined => projectAstFields(node)?.local;
+
+export const getNodeName = (
+  node: AstNode | null | undefined
+): string | undefined => projectAstFields(node)?.name;
+
+export const getNodeObject = (
+  node: AstNode | null | undefined
+): AstNode | undefined => (isMemberExpression(node) ? node.object : undefined);
+
+export const getNodeOperator = (
+  node: AstNode | null | undefined
+): string | undefined => projectAstFields(node)?.operator;
+
+export const getNodeParam = (
+  node: AstNode | null | undefined
+): AstNode | undefined => projectAstFields(node)?.param;
+
+export const getNodeParams = (
+  node: AstNode | null | undefined
+): readonly AstNode[] => (isFunctionLike(node) ? (node.params ?? []) : []);
+
+export const getNodeProperties = (
+  node: AstNode | null | undefined
+): readonly AstNode[] =>
+  isObjectExpression(node) ? (node.properties ?? []) : [];
+
+export const getNodeProperty = (
+  node: AstNode | null | undefined
+): AstNode | undefined =>
+  isMemberExpression(node) ? node.property : undefined;
+
+export const getNodeReturnType = (
+  node: AstNode | null | undefined
+): AstNode | undefined => projectAstFields(node)?.returnType;
+
+export const getNodeRight = (
+  node: AstNode | null | undefined
+): AstNode | undefined => projectAstFields(node)?.right;
+
+export const getNodeSource = (
+  node: AstNode | null | undefined
+): AstNode | undefined => projectAstFields(node)?.source;
+
+export const getNodeSpecifiers = (
+  node: AstNode | null | undefined
+): readonly AstNode[] => projectAstFields(node)?.specifiers ?? [];
+
+export const getNodeSuperClass = (
+  node: AstNode | null | undefined
+): AstNode | undefined => projectAstFields(node)?.superClass;
+
+export const getNodeTest = (
+  node: AstNode | null | undefined
+): AstNode | undefined => projectAstFields(node)?.test;
+
+export const getNodeTypeAnnotation = (
+  node: AstNode | null | undefined
+): AstNode | undefined => projectAstFields(node)?.typeAnnotation;
+
+export const getNodeValue = (node: AstNode | null | undefined): unknown =>
+  projectAstFields(node)?.value;
+
+export const getNodeValueNode = (
+  node: AstNode | null | undefined
+): AstNode | undefined => {
+  const value = getNodeValue(node);
+  return isAstNode(value) ? value : undefined;
+};
+
 // ---------------------------------------------------------------------------
 // Parser
 // ---------------------------------------------------------------------------
@@ -49,6 +675,46 @@ export const parse = (filePath: string, sourceCode: string): AstNode | null => {
   }
 };
 
+/**
+ * Parse TypeScript source and surface parser diagnostics. OXC can recover a
+ * partial program for malformed input, so rewrite tooling should use this
+ * helper when applying edits would be unsafe after syntax errors.
+ */
+export const parseWithDiagnostics = (
+  filePath: string,
+  sourceCode: string
+): AstParseResult => {
+  try {
+    const result = parseSync(filePath, sourceCode, { sourceType: 'module' });
+    return {
+      ast: result.program as unknown as AstNode,
+      diagnostics: result.errors.map((error) => ({
+        helpMessage: error.helpMessage,
+        labels: error.labels.map((label) => ({
+          end: label.end,
+          message: label.message,
+          start: label.start,
+        })),
+        message: error.message,
+        severity: error.severity,
+      })),
+    };
+  } catch (error) {
+    return {
+      ast: null,
+      diagnostics: [
+        {
+          helpMessage: null,
+          labels: [],
+          message:
+            error instanceof Error ? error.message : 'Unable to parse source.',
+          severity: 'Error',
+        },
+      ],
+    };
+  }
+};
+
 // ---------------------------------------------------------------------------
 // Walker
 // ---------------------------------------------------------------------------
@@ -83,6 +749,94 @@ export const walk: WalkFn = (node, visit) => {
   walkChildren(n, visit, walk);
 };
 
+const toAstParentContext = (
+  parent: unknown,
+  ctx: WalkerCallbackContext
+): AstParentContext => ({
+  index: ctx.index,
+  key: ctx.key,
+  parent: isAstNode(parent) ? parent : null,
+});
+
+const toScopeDeclaration = (
+  declaration: ScopeTrackerNode | null
+): AstScopeDeclaration | null => {
+  if (!declaration) {
+    return null;
+  }
+
+  return {
+    end: declaration.end,
+    node: declaration.node as unknown as AstNode,
+    start: declaration.start,
+    type: declaration.type,
+  };
+};
+
+const walkWithOxcFacade = (
+  node: unknown,
+  enter: (node: AstNode, context: AstParentContext) => void,
+  scopeTracker?: ScopeTracker
+): void => {
+  if (!isAstNode(node)) {
+    return;
+  }
+
+  const options: Partial<WalkOptions> = {
+    enter(candidate, parent, ctx) {
+      if (!isAstNode(candidate)) {
+        return;
+      }
+      enter(candidate, toAstParentContext(parent, ctx));
+    },
+  };
+
+  if (scopeTracker) {
+    options.scopeTracker = scopeTracker;
+  }
+
+  walkWithOxc(node as never, options);
+};
+
+/**
+ * Walk an AST node tree with parent, key, and index context for each visited
+ * node. This is the supported Warden facade over `oxc-walker` for rules and
+ * regrades that need structural context.
+ */
+export const walkWithParents = (
+  node: unknown,
+  visit: (node: AstNode, context: AstParentContext) => void
+): void => {
+  walkWithOxcFacade(node, visit);
+};
+
+/**
+ * Walk an AST node tree with parent context and a scope query facade. The
+ * concrete `oxc-walker` tracker stays behind this helper so rule authors can
+ * ask Warden-shaped questions without depending on walker internals.
+ */
+export const walkWithScopeContext = (
+  node: unknown,
+  visit: (node: AstNode, context: AstScopeContext) => void
+): void => {
+  const scopeTracker = new ScopeTracker();
+
+  walkWithOxcFacade(
+    node,
+    (candidate, context) => {
+      visit(candidate, {
+        ...context,
+        currentScope: scopeTracker.getCurrentScope(),
+        getDeclaration: (name) =>
+          toScopeDeclaration(scopeTracker.getDeclaration(name)),
+        isCurrentScopeUnder: (scope) => scopeTracker.isCurrentScopeUnder(scope),
+        isDeclared: (name) => scopeTracker.isDeclared(name),
+      });
+    },
+    scopeTracker
+  );
+};
+
 const NESTED_SCOPE_TYPES = new Set([
   'ArrowFunctionExpression',
   'FunctionExpression',
@@ -135,6 +889,81 @@ export const offsetToLine = (sourceCode: string, offset: number): number => {
   return line;
 };
 
+/** Find the byte offset's line and column (1-based) in source code. */
+export const offsetToLineColumn = (
+  sourceCode: string,
+  offset: number
+): SourceLocation => {
+  let line = 1;
+  let column = 1;
+  const limit = Math.min(Math.max(offset, 0), sourceCode.length);
+
+  for (let i = 0; i < limit; i += 1) {
+    if (sourceCode[i] === '\n') {
+      line += 1;
+      column = 1;
+    } else {
+      column += 1;
+    }
+  }
+
+  return { column, line };
+};
+
+export const createSourceEdit = (
+  start: number,
+  end: number,
+  replacement: string
+): SourceEdit => ({ end, replacement, start });
+
+export const validateSourceEdits = (
+  edits: readonly SourceEdit[],
+  sourceLength?: number
+): readonly SourceEdit[] => {
+  const ordered = [...edits].toSorted(
+    (left, right) => left.start - right.start
+  );
+  for (let i = 0; i < ordered.length; i += 1) {
+    const edit = ordered[i];
+    if (!edit) {
+      continue;
+    }
+    if (
+      !Number.isSafeInteger(edit.start) ||
+      !Number.isSafeInteger(edit.end) ||
+      edit.start < 0 ||
+      edit.end < edit.start ||
+      (sourceLength !== undefined && edit.end > sourceLength)
+    ) {
+      throw new Error(`Invalid source edit range ${edit.start}-${edit.end}.`);
+    }
+
+    const previous = ordered[i - 1];
+    if (previous && edit.start < previous.end) {
+      throw new Error(
+        `Overlapping source edits ${previous.start}-${previous.end} and ${edit.start}-${edit.end}.`
+      );
+    }
+  }
+
+  return ordered;
+};
+
+export const applySourceEdits = (
+  sourceCode: string,
+  edits: readonly SourceEdit[]
+): string => {
+  validateSourceEdits(edits, sourceCode.length);
+
+  return [...edits]
+    .toSorted((left, right) => right.start - left.start)
+    .reduce(
+      (output, edit) =>
+        output.slice(0, edit.start) + edit.replacement + output.slice(edit.end),
+      sourceCode
+    );
+};
+
 /** Get the name of an Identifier node, or null. */
 export const identifierName = (node: AstNode | undefined): string | null => {
   if (node?.type !== 'Identifier') {
@@ -1865,7 +2694,9 @@ const extractImportSpecifierAlias = (
 };
 
 /**
- * Collect `import { foo as bar } from '...'` and `import bar from '...'`
+ * Collect `import {
+  foo as bar
+} from '...';` and `import bar from '...'`
  * specifier mappings keyed by local binding name. The value is the original
  * exported name for named imports. Default imports map to themselves because
  * the exported name cannot be recovered statically — callers should fall
@@ -2421,8 +3252,8 @@ const extractBlazeFromConfig = (config: AstNode): AstNode[] => {
   }
   for (const prop of properties) {
     if (
-      prop.type === 'Property' &&
-      prop.key?.name === 'blaze' &&
+      isProperty(prop) &&
+      identifierName(prop.key) === 'blaze' &&
       isAstNode(prop.value)
     ) {
       bodies.push(prop.value);