@pgsql/transform 18.7.0 → 18.9.0

package/esm/transform.js

@@ -47,6 +47,36 @@ function createResult() {
         errors: [],
     };
 }
+/**
+ * Routing claims: each routable site (a RangeVar, a qualified name list, a
+ * bare schema-name field) is resolved through the router at most once per
+ * transform result.
+ *
+ * The walker visits parents before children, so a statement-level handler
+ * with namespace context (e.g. `AlterFunctionStmt` routing its
+ * `ObjectWithArgs` as a `function`) claims the site before a generic child
+ * visitor (`ObjectWithArgs`, namespace `unknown`) reaches it — first (most
+ * contextual) visitor wins. Without claims a site is routed twice, which
+ * corrupts cyclic mappings (a→b, b→a swaps back) and applies the less precise
+ * namespace second.
+ */
+const routingClaims = new WeakMap();
+function claimSite(result, site, field = '*') {
+    let byNode = routingClaims.get(result);
+    if (!byNode) {
+        byNode = new WeakMap();
+        routingClaims.set(result, byNode);
+    }
+    let fields = byNode.get(site);
+    if (!fields) {
+        fields = new Set();
+        byNode.set(site, fields);
+    }
+    if (fields.has(field))
+        return false;
+    fields.add(field);
+    return true;
+}
 /**
  * Transform a schema name if it exists in the mapping
  */
@@ -75,6 +105,8 @@ export function shouldTransformSchema(schemaName, schemaMapping) {
 export function transformNameList(names, schemaMapping, result, ns = 'unknown') {
     if (!names || names.length < 2)
         return;
+    if (!claimSite(result, names))
+        return;
     const router = asRouter(schemaMapping);
     // For schema-qualified names, the first element is the schema.
     const first = names[0];
@@ -110,6 +142,8 @@ export function transformSchemaNameField(container, field, schemaMapping, result
     const schemaName = container?.[field];
     if (typeof schemaName !== 'string')
         return;
+    if (!claimSite(result, container, field))
+        return;
     // A bare schema name is an operation on the schema itself: only the
     // schema-level default applies.
     const newName = asRouter(schemaMapping).resolve(schemaName, undefined, 'schema');
@@ -121,11 +155,16 @@ export function transformSchemaNameField(container, field, schemaMapping, result
 }
 /**
  * Transform a RangeVar-like relation object (has schemaname/relname fields).
- * Many statement nodes embed a relation that the walker does NOT auto-recurse into.
+ * The walker auto-recurses into embedded relations (concrete `RangeVar`
+ * fields are tag-synthesized), so the generic `RangeVar` visitor covers
+ * every occurrence; statement handlers call this directly only when they
+ * carry extra context, and the claim guard keeps each relation routed once.
  */
 export function transformRelation(relation, schemaMapping, result) {
     if (!relation?.schemaname)
         return;
+    if (!claimSite(result, relation))
+        return;
     const oldName = relation.schemaname;
     // A RangeVar names a relation (table/view/sequence/matview); route by the
     // relation name so object-level routes can send it to its own schema.
@@ -185,6 +224,8 @@ export function createSqlVisitor(schemaMapping, result, visitorOptions) {
         const schemaName = container?.[key];
         if (typeof schemaName !== 'string')
             return;
+        if (!claimSite(result, container, key))
+            return;
         const newName = router.resolve(schemaName, undefined, 'schema');
         if (newName && newName !== schemaName) {
             result.schemasFound.add(schemaName);
@@ -242,15 +283,6 @@ export function createSqlVisitor(schemaMapping, result, visitorOptions) {
             const node = path.node;
             transformNameList(node.funcname, router, result, 'function');
         },
-        // Transform CallStmt (CALL schema.procedure(...)).
-        // Note: The walker does NOT auto-recurse into CallStmt.funccall,
-        // so the FuncCall visitor above never sees it.
-        CallStmt: (path) => {
-            const node = path.node;
-            if (node.funccall?.funcname) {
-                transformNameList(node.funccall.funcname, router, result, 'function');
-            }
-        },
         // Transform TypeName nodes (type references with schema-qualified names)
         TypeName: (path) => {
             const node = path.node;
@@ -308,8 +340,9 @@ export function createSqlVisitor(schemaMapping, result, visitorOptions) {
             }
         },
         // Transform DropStmt (DROP SCHEMA name; DROP TABLE/INDEX/POLICY/TRIGGER/
-        // TYPE/FUNCTION schema.obj). The walker does NOT auto-recurse into
-        // DropStmt.objects.
+        // TYPE/FUNCTION schema.obj) with the namespace derived from removeType,
+        // so object routes apply; claims stop the generic List/ObjectWithArgs
+        // visitors from re-routing the same names with namespace `unknown`.
         DropStmt: (path) => {
             const node = path.node;
             if (node.removeType !== 'OBJECT_SCHEMA' && Array.isArray(node.objects)) {
@@ -343,79 +376,10 @@ export function createSqlVisitor(schemaMapping, result, visitorOptions) {
                 }
             }
         },
-        // Transform InsertStmt (INSERT INTO schema.table)
-        // Note: The walker does NOT auto-recurse into InsertStmt.relation.
-        InsertStmt: (path) => {
-            transformRelation(path.node.relation, schemaMapping, result);
-        },
-        // Transform CreateStmt (CREATE TABLE schema.table)
-        // Note: The walker does NOT auto-recurse into CreateStmt.relation.
-        CreateStmt: (path) => {
-            transformRelation(path.node.relation, schemaMapping, result);
-        },
-        // Transform UpdateStmt (UPDATE schema.table SET ...)
-        // Note: The walker does NOT auto-recurse into UpdateStmt.relation.
-        UpdateStmt: (path) => {
-            transformRelation(path.node.relation, schemaMapping, result);
-        },
-        // Transform DeleteStmt (DELETE FROM schema.table)
-        // Note: The walker does NOT auto-recurse into DeleteStmt.relation.
-        DeleteStmt: (path) => {
-            transformRelation(path.node.relation, schemaMapping, result);
-        },
-        // Transform MergeStmt (MERGE INTO schema.table USING ...)
-        // Note: The walker does NOT auto-recurse into MergeStmt.relation.
-        MergeStmt: (path) => {
-            transformRelation(path.node.relation, schemaMapping, result);
-        },
-        // Transform IndexStmt (CREATE INDEX ... ON schema.table)
-        // Note: The walker does NOT auto-recurse into IndexStmt.relation.
-        IndexStmt: (path) => {
-            transformRelation(path.node.relation, schemaMapping, result);
-        },
-        // Transform Constraint (REFERENCES schema.table for foreign keys)
-        // Note: The walker does NOT auto-recurse into Constraint.pktable.
-        Constraint: (path) => {
-            const node = path.node;
-            if (node.contype === 'CONSTR_FOREIGN' && node.pktable) {
-                transformRelation(node.pktable, schemaMapping, result);
-            }
-        },
-        // Transform CompositeTypeStmt (CREATE TYPE schema.name AS (...))
-        // Note: The walker does NOT auto-recurse into CompositeTypeStmt.typevar.
-        CompositeTypeStmt: (path) => {
-            transformRelation(path.node.typevar, schemaMapping, result);
-        },
-        // Transform ColumnDef (column definitions with schema-qualified types)
-        // Note: The walker does NOT auto-recurse into ColumnDef.typeName.
-        ColumnDef: (path) => {
-            const node = path.node;
-            if (node.typeName?.names) {
-                transformNameList(node.typeName.names, schemaMapping, result, 'type');
-            }
-        },
-        // Transform ViewStmt (CREATE VIEW schema.viewname AS ...)
-        // Note: The walker does NOT auto-recurse into ViewStmt.view.
-        ViewStmt: (path) => {
-            transformRelation(path.node.view, schemaMapping, result);
-        },
-        // Transform AlterTableStmt (ALTER TABLE schema.table ...)
-        // Note: The walker does NOT auto-recurse into AlterTableStmt.relation.
-        AlterTableStmt: (path) => {
-            transformRelation(path.node.relation, schemaMapping, result);
-        },
-        // Transform CreateSeqStmt (CREATE SEQUENCE schema.seqname)
-        // Note: The walker does NOT auto-recurse into CreateSeqStmt.sequence.
-        CreateSeqStmt: (path) => {
-            transformRelation(path.node.sequence, schemaMapping, result);
-        },
-        // Transform AlterSeqStmt (ALTER SEQUENCE schema.seqname [OWNED BY schema.table.col])
-        // Note: The walker does NOT auto-recurse into AlterSeqStmt.sequence.
-        // Also handles OWNED BY clause where the schema name is in DefElem.arg.List.items.
+        // Transform AlterSeqStmt OWNED BY (schema name in DefElem.arg.List.items;
+        // a bare name list no generic visitor covers)
         AlterSeqStmt: (path) => {
             const node = path.node;
-            transformRelation(node.sequence, schemaMapping, result);
-            // Handle OWNED BY option: schema name is in the name list
             if (node.options) {
                 for (const opt of node.options) {
                     if (opt?.DefElem?.defname === 'owned_by' && opt.DefElem?.arg?.List?.items) {
@@ -424,67 +388,12 @@ export function createSqlVisitor(schemaMapping, result, visitorOptions) {
                 }
             }
         },
-        // Transform CreatePolicyStmt (CREATE POLICY ... ON schema.table)
-        // Note: The walker does NOT auto-recurse into CreatePolicyStmt.table.
-        CreatePolicyStmt: (path) => {
-            transformRelation(path.node.table, schemaMapping, result);
-        },
-        // Transform RuleStmt (CREATE RULE ... ON schema.table)
-        // Note: The walker does NOT auto-recurse into RuleStmt.relation.
-        RuleStmt: (path) => {
-            transformRelation(path.node.relation, schemaMapping, result);
-        },
-        // Transform CopyStmt (COPY schema.table ...)
-        // Note: The walker does NOT auto-recurse into CopyStmt.relation.
-        CopyStmt: (path) => {
-            transformRelation(path.node.relation, schemaMapping, result);
-        },
-        // Transform ClusterStmt (CLUSTER schema.table USING index)
-        // Note: The walker does NOT auto-recurse into ClusterStmt.relation.
-        ClusterStmt: (path) => {
-            transformRelation(path.node.relation, schemaMapping, result);
-        },
-        // Transform VacuumRelation (VACUUM/ANALYZE schema.table)
-        // Note: The walker visits VacuumRelation but does NOT recurse into its relation.
-        VacuumRelation: (path) => {
-            transformRelation(path.node.relation, schemaMapping, result);
-        },
-        // Transform RefreshMatViewStmt (REFRESH MATERIALIZED VIEW schema.view)
-        // Note: The walker does NOT auto-recurse into RefreshMatViewStmt.relation.
-        RefreshMatViewStmt: (path) => {
-            transformRelation(path.node.relation, schemaMapping, result);
-        },
-        // Transform CreateTableAsStmt (CREATE MATERIALIZED VIEW schema.viewname AS ...)
-        // Note: The walker does NOT auto-recurse into CreateTableAsStmt.into.rel.
-        CreateTableAsStmt: (path) => {
-            transformRelation(path.node.into?.rel, schemaMapping, result);
-        },
-        // Transform TypeCast nodes (type casts like NULL::schema.type)
-        // Note: The walker visits TypeCast but does NOT recurse into the TypeName node.
-        TypeCast: (path) => {
-            const node = path.node;
-            if (node.typeName?.names) {
-                transformNameList(node.typeName.names, schemaMapping, result, 'type');
-            }
-        },
-        // Transform CreateFunctionStmt (CREATE FUNCTION schema.funcname)
-        // Also handles RETURNS [SETOF] schema.type via returnType.names
+        // Transform CreateFunctionStmt (CREATE FUNCTION schema.funcname).
+        // funcname is a bare name list (no generic visitor); return and parameter
+        // types are TypeName nodes the walker reaches on its own.
         CreateFunctionStmt: (path) => {
             const node = path.node;
             transformNameList(node.funcname, schemaMapping, result, 'function');
-            // Transform the return type (e.g., RETURNS SETOF schema.tablename)
-            if (node.returnType?.names) {
-                transformNameList(node.returnType.names, schemaMapping, result, 'type');
-            }
-            // Transform parameter types (the walker does NOT auto-recurse into
-            // FunctionParameter.argType TypeName nodes)
-            if (Array.isArray(node.parameters)) {
-                for (const param of node.parameters) {
-                    if (param?.FunctionParameter?.argType?.names) {
-                        transformNameList(param.FunctionParameter.argType.names, schemaMapping, result, 'type');
-                    }
-                }
-            }
             // Transform schema-qualified references inside the function body
             // (AS $$...$$ is a String under the 'as' DefElem, which the walker
             // does not parse as SQL). LANGUAGE plpgsql bodies are additionally
@@ -511,12 +420,11 @@ export function createSqlVisitor(schemaMapping, result, visitorOptions) {
             }
         },
         // Transform CreateTrigStmt (CREATE TRIGGER ... EXECUTE PROCEDURE schema.func)
-        // Note: The walker does NOT auto-recurse into CreateTrigStmt.relation,
-        // so we must explicitly transform the RangeVar here.
+        // funcname is a bare name list; the ON relation is a RangeVar the walker
+        // reaches on its own.
         CreateTrigStmt: (path) => {
             const node = path.node;
             transformNameList(node.funcname, schemaMapping, result, 'function');
-            transformRelation(node.relation, schemaMapping, result);
         },
         // Transform CommentStmt (COMMENT ON TABLE/COLUMN/FUNCTION schema.obj,
         // COMMENT ON SCHEMA schema)
@@ -527,13 +435,14 @@ export function createSqlVisitor(schemaMapping, result, visitorOptions) {
             // For functions, object is { ObjectWithArgs: { objname: [...] } }
             // For schemas, object is a bare { String: { sval } }
             if (node.object) {
+                const ns = namespaceOfObjectType(node.objtype);
                 // Handle List-wrapped objects (COMMENT ON TABLE schema.tbl, COMMENT ON COLUMN schema.tbl.col)
                 if (node.object?.List?.items) {
-                    transformNameList(node.object.List.items, schemaMapping, result);
+                    transformNameList(node.object.List.items, schemaMapping, result, ns);
                 }
                 // Handle ObjectWithArgs-style objects (COMMENT ON FUNCTION schema.func(args))
                 else if (node.object?.ObjectWithArgs?.objname) {
-                    transformNameList(node.object.ObjectWithArgs.objname, schemaMapping, result);
+                    transformNameList(node.object.ObjectWithArgs.objname, schemaMapping, result, ns);
                 }
                 // Handle bare schema names (COMMENT ON SCHEMA schema)
                 else if (node.object?.String && node.objtype === 'OBJECT_SCHEMA') {
@@ -590,41 +499,41 @@ export function createSqlVisitor(schemaMapping, result, visitorOptions) {
             const node = path.node;
             transformNameList(node.objname, schemaMapping, result);
         },
-        // Transform AlterObjectSchemaStmt (ALTER ... SET SCHEMA newschema)
-        // The walker does NOT auto-recurse into AlterObjectSchemaStmt.relation
-        // or .object, so we must transform relation, object names, and newschema.
+        // Transform AlterObjectSchemaStmt (ALTER ... SET SCHEMA newschema):
+        // object name lists and the destination schema. The relation form is a
+        // RangeVar the walker reaches on its own.
         AlterObjectSchemaStmt: (path) => {
             const node = path.node;
-            transformRelation(node.relation, schemaMapping, result);
+            const ns = namespaceOfObjectType(node.objectType);
             // Non-relation objects (ALTER TYPE/FUNCTION ... SET SCHEMA)
             if (node.object?.List?.items) {
-                transformNameList(node.object.List.items, schemaMapping, result);
+                transformNameList(node.object.List.items, schemaMapping, result, ns);
             }
             else if (node.object?.ObjectWithArgs?.objname) {
-                transformNameList(node.object.ObjectWithArgs.objname, schemaMapping, result);
+                transformNameList(node.object.ObjectWithArgs.objname, schemaMapping, result, ns);
             }
             else if (node.object?.TypeName?.names) {
-                transformNameList(node.object.TypeName.names, schemaMapping, result);
+                transformNameList(node.object.TypeName.names, schemaMapping, result, ns);
             }
             // Transform the newschema (destination schema)
             transformSchemaNameField(node, 'newschema', schemaMapping, result);
         },
         // Transform RenameStmt (ALTER SCHEMA old RENAME TO new;
-        // ALTER TABLE schema.tbl RENAME ...). The walker does NOT auto-recurse
-        // into RenameStmt.relation or .object.
+        // ALTER TABLE schema.tbl RENAME ...). The relation form is a RangeVar
+        // the walker reaches on its own.
         RenameStmt: (path) => {
             const node = path.node;
-            transformRelation(node.relation, schemaMapping, result);
             if (node.renameType === 'OBJECT_SCHEMA') {
                 // subname is the old schema name; newname is the target
                 transformSchemaNameField(node, 'subname', schemaMapping, result);
                 transformSchemaNameField(node, 'newname', schemaMapping, result);
             }
+            const ns = namespaceOfObjectType(node.renameType);
             if (node.object?.List?.items) {
-                transformNameList(node.object.List.items, schemaMapping, result);
+                transformNameList(node.object.List.items, schemaMapping, result, ns);
             }
             else if (node.object?.ObjectWithArgs?.objname) {
-                transformNameList(node.object.ObjectWithArgs.objname, schemaMapping, result);
+                transformNameList(node.object.ObjectWithArgs.objname, schemaMapping, result, ns);
             }
         },
         // Transform AlterFunctionStmt (ALTER FUNCTION schema.fn(...) SET ...)
@@ -637,46 +546,26 @@ export function createSqlVisitor(schemaMapping, result, visitorOptions) {
         // Transform AlterOwnerStmt (ALTER ... OWNER TO role)
         AlterOwnerStmt: (path) => {
             const node = path.node;
-            transformRelation(node.relation, schemaMapping, result);
+            const ns = namespaceOfObjectType(node.objectType);
             if (node.object?.List?.items) {
-                transformNameList(node.object.List.items, schemaMapping, result);
+                transformNameList(node.object.List.items, schemaMapping, result, ns);
             }
             else if (node.object?.ObjectWithArgs?.objname) {
-                transformNameList(node.object.ObjectWithArgs.objname, schemaMapping, result);
+                transformNameList(node.object.ObjectWithArgs.objname, schemaMapping, result, ns);
             }
             else if (node.object?.String && node.objectType === 'OBJECT_SCHEMA') {
                 transformSchemaNameField(node.object.String, 'sval', schemaMapping, result);
             }
         },
-        // Transform CreateCastStmt (CREATE CAST (src AS tgt) WITH FUNCTION fn)
+        // Transform CreateCastStmt (CREATE CAST (src AS tgt) WITH FUNCTION fn).
+        // The function name gets its `function` namespace here; the cast's
+        // source/target/argument types are TypeName nodes the walker reaches on
+        // its own.
         CreateCastStmt: (path) => {
             const node = path.node;
-            if (node.sourcetype?.names) {
-                transformNameList(node.sourcetype.names, schemaMapping, result, 'type');
-            }
-            if (node.targettype?.names) {
-                transformNameList(node.targettype.names, schemaMapping, result, 'type');
-            }
             if (node.func?.objname) {
                 transformNameList(node.func.objname, schemaMapping, result, 'function');
             }
-            if (Array.isArray(node.func?.objargs)) {
-                for (const arg of node.func.objargs) {
-                    if (arg?.TypeName?.names) {
-                        transformNameList(arg.TypeName.names, schemaMapping, result, 'type');
-                    }
-                    else if (arg?.names) {
-                        transformNameList(arg.names, schemaMapping, result, 'type');
-                    }
-                }
-            }
-            if (Array.isArray(node.func?.objfuncargs)) {
-                for (const param of node.func.objfuncargs) {
-                    if (param?.FunctionParameter?.argType?.names) {
-                        transformNameList(param.FunctionParameter.argType.names, schemaMapping, result, 'type');
-                    }
-                }
-            }
         },
         // Transform CreateEventTrigStmt (CREATE EVENT TRIGGER ... EXECUTE FUNCTION schema.fn())
         CreateEventTrigStmt: (path) => {

package/facts.d.ts

@@ -94,6 +94,21 @@ export interface StatementFacts {
      * are incomplete and slicing should treat it conservatively.
      */
     dynamicSql: boolean;
+    /**
+     * The statement's source span in the classified script, as reported by the
+     * parser: `start` is the byte offset of the statement's first token, `len`
+     * runs to the end of the statement (the parser excludes the trailing `;`;
+     * for the final statement the span extends to the end of the script).
+     * `sql.slice(span.start, span.start + span.len)` is the statement's
+     * verbatim source, so consumers can carry original text alongside the
+     * facts without a second parse.
+     */
+    span: StatementSpan;
+}
+/** A statement's location in the source script (byte offsets). */
+export interface StatementSpan {
+    start: number;
+    len: number;
 }
 /**
  * Classify each top-level statement in a SQL script into {@link StatementFacts}.

package/facts.js

@@ -157,7 +157,8 @@ function classifyOne(nodeTag, node) {
         bodyReferences: [],
         securityRelevant: SECURITY_TAGS.has(nodeTag),
         securityDefiner: false,
-        dynamicSql: false
+        dynamicSql: false,
+        span: { start: 0, len: 0 }
     };
     switch (nodeTag) {
         case 'CreateSchemaStmt':
@@ -351,6 +352,8 @@ function classifyStatements(sql) {
             const nodeTag = stmtNode ? Object.keys(stmtNode)[0] : 'other';
             const node = stmtNode?.[nodeTag] ?? {};
             const facts = classifyOne(nodeTag, node);
+            const start = stmt?.stmt_location ?? 0;
+            facts.span = { start, len: stmt?.stmt_len ?? Math.max(0, sql.length - start) };
             if (stmtNode) {
                 (0, traverse_1.walk)(stmtNode, createFactsVisitor(facts));
             }

package/graph.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Statement-level dependency graph over classified SQL.
+ *
+ * {@link classifyStatements} reduces each top-level statement to
+ * {@link StatementFacts} — what it creates, what it references, which of
+ * those references live only inside PL/pgSQL bodies. This module turns a
+ * sequence of facts into a typed dependency graph and computes the orderings
+ * the granularity passes (consolidate / atomize) need:
+ *
+ * - **typed edges**: `hard` edges (the referenced object must exist at
+ *   CREATE time), `fk` edges (foreign-key targets — hard, but singled out
+ *   because they are the edges FK inlining must respect), and `late` edges
+ *   (PL/pgSQL body references, resolved at call time — they never constrain
+ *   deploy order and may legitimately form cycles).
+ * - **SCC condensation**: strongly connected components over hard+fk edges.
+ *   A well-formed DDL script condenses to singleton components; any larger
+ *   component is a genuine ordering cycle (e.g. mutually referencing FKs)
+ *   that granularity passes must leave in atomic form.
+ * - **topological order** of the condensation, stable with respect to the
+ *   original statement order (ties keep source order), so re-emission is
+ *   deterministic and minimally surprising.
+ */
+import { QualifiedName, StatementFacts } from './facts';
+/**
+ * How a dependency edge constrains ordering.
+ *
+ * - `hard` — name must resolve when the dependent statement executes.
+ * - `fk` — a hard edge arising from a foreign-key target; distinguished so
+ *   folding passes can decide whether an FK may be inlined into its table.
+ * - `late` — reached only inside a PL/pgSQL body; resolved at call time,
+ *   so it does not constrain deploy order.
+ */
+export type EdgeKind = 'hard' | 'fk' | 'late';
+/** A directed dependency: statement `from` depends on statement `to`. */
+export interface StatementEdge {
+    from: number;
+    to: number;
+    kind: EdgeKind;
+    /** The referenced object that induced this edge. */
+    via: QualifiedName;
+}
+/** A node in the statement graph: one top-level statement. */
+export interface StatementNode {
+    /** Index of the statement in the classified script. */
+    index: number;
+    facts: StatementFacts;
+    /** Outgoing edges (this statement's dependencies). */
+    out: StatementEdge[];
+    /** Incoming edges (statements that depend on this one). */
+    in: StatementEdge[];
+}
+/** The statement-level dependency graph for one SQL script. */
+export interface StatementGraph {
+    nodes: StatementNode[];
+    edges: StatementEdge[];
+    /**
+     * `schema.name` → indices of the statements that create that object.
+     * Trigger and policy names are table-qualified (`table.trigger`), matching
+     * {@link StatementFacts.creates}.
+     */
+    producers: Map<string, number[]>;
+    /**
+     * Strongly connected components over `hard` + `fk` edges, in topological
+     * order of the condensation. Singleton components are the common case;
+     * larger ones are genuine DDL ordering cycles.
+     */
+    components: number[][];
+    /**
+     * A stable topological order of all statements: components in condensation
+     * order, members of a component in source order. Ties between independent
+     * components keep source order.
+     */
+    order: number[];
+}
+/**
+ * Build the typed statement dependency graph for a classified script.
+ *
+ * Edges only exist between statements of the same script: a reference with
+ * no in-script producer is an external dependency and induces no edge (the
+ * caller decides what to do with those — pgpm expresses them as
+ * cross-package requires).
+ */
+export declare function buildStatementGraph(facts: StatementFacts[]): StatementGraph;