/** * Unified AST traversal. * * `walk` is the single entry point for every AST shape in the ecosystem — a * parsed script, a `ParseResult`, a lone SQL node, or a PL/pgSQL function body — * layered over the two primitives in this package: * * - `walkSqlAst` SQL nodes, driven by the runtime schema * - `walkPlpgsqlAst` PL/pgSQL nodes, bridging into hydrated SQL expressions * * On top of dispatch it adds the three things the primitives cannot provide, * because they see one node at a time and never the statement it belongs to: * * 1. a {@link WalkContext} on every callback (`stmtTag`, `isWrite`, `isRead`, * `insideFunction`, `functionName`), refined by the nearest enclosing * statement — so an `INSERT` nested in a CTE or in a PL/pgSQL body reports * `isWrite`, not the context of whatever statement contains it * 2. visitor composition — N visitors in a single pass, each free to mix SQL * and `PLpgSQL_*` tags in the same object * 3. `ctx.abort()`, which ends the whole walk (returning `false` from a * handler still means "skip this node's children") * * Parsing lives one layer up: `plpgsql-parser`'s `walkSql(sqlText, ...)` parses * and hydrates, then delegates here. */ import type { PlpgsqlNodePath } from './plpgsql'; import type { Visitor as SqlVisitor, Walker as SqlWalker } from './traverse'; import { NodePath } from './traverse'; /** Statement tags that write data. */ export declare const WRITE_STATEMENTS: ReadonlySet; /** Statement tags that only read data. */ export declare const READ_STATEMENTS: ReadonlySet; /** * Statement-level context threaded through every visitor callback. The node * path tells you *where* a node sits; the context tells you *what it is part * of* — which statement, whether that statement writes, and whether you are * inside a function body. */ export interface WalkContext { /** Tag of the nearest enclosing statement, or `null` when walking a bare node. */ readonly stmtTag: string | null; /** Index of the enclosing statement within the script, or `-1` if unknown. */ readonly stmtIndex: number; /** Whether the enclosing statement writes data. */ readonly isWrite: boolean; /** Whether the enclosing statement only reads data. */ readonly isRead: boolean; /** Whether this node came from inside a PL/pgSQL function body. */ readonly insideFunction: boolean; /** Dotted name of the enclosing function, when known. */ readonly functionName: string | null; /** End the entire walk. Unlike returning `false`, no further nodes are visited. */ abort(reason?: string): void; } export type UnifiedWalker = (path: NodePath | PlpgsqlNodePath, ctx: WalkContext) => boolean | void; /** * Visitor keyed by node tag. SQL tags (`SelectStmt`, `RangeVar`, ...) and * PL/pgSQL tags (`PLpgSQL_stmt_dynexecute`, ...) may be mixed freely. The * reserved `statement` key fires once per top-level statement, before its * children are visited. */ export type UnifiedVisitor = { [tag: string]: UnifiedWalker; }; export interface WalkOptions { /** Walk hydrated PL/pgSQL function bodies of a parsed script. Default: true */ walkFunctionBodies?: boolean; /** Recurse into hydrated SQL expressions inside PL/pgSQL bodies. Default: true */ walkSqlExpressions?: boolean; /** * Visitor for hydrated SQL expressions inside PL/pgSQL bodies. Defaults to * the visitors passed to `walk`, so one visitor object covers both universes. */ sqlVisitor?: SqlVisitor | SqlWalker; } export interface WalkResult { /** Whether a visitor called `ctx.abort()`. */ aborted: boolean; /** The first abort reason, if one was given. */ reason?: string; /** Every abort reason, in call order. */ reasons: string[]; } /** * Walk any AST with one or more visitors. * * Dispatch is by shape: * * | Input | Walked | * | ---------------------------------------- | --------------------------------------------- | * | `{ sql, functions }` (parsed script) | every statement, then every hydrated body | * | `{ stmts: [...] }` (parse result) | every statement, with statement context | * | `{ PLpgSQL_*: ... }` | PL/pgSQL body, descending into hydrated SQL | * | any other SQL node | the SQL node | * | an array | each element | */ export declare function walk(root: any, visitors: UnifiedVisitor | UnifiedWalker | Array, options?: WalkOptions): WalkResult;