@pgsql/transform 18.8.0 → 18.10.0

package/esm/graph.js

@@ -0,0 +1,184 @@
+const keyOf = (q) => `${q.schema ?? ''}.${q.name}`;
+/**
+ * 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 function buildStatementGraph(facts) {
+    const nodes = facts.map((f, index) => ({
+        index,
+        facts: f,
+        out: [],
+        in: []
+    }));
+    const producers = new Map();
+    facts.forEach((f, i) => {
+        for (const created of f.creates) {
+            const key = keyOf(created);
+            const list = producers.get(key) ?? [];
+            list.push(i);
+            producers.set(key, list);
+        }
+    });
+    // The producer a reference binds to is the closest preceding statement
+    // that creates the object (redefinitions shadow earlier ones); when the
+    // reference precedes every producer, it binds to the first one — that is
+    // exactly the forward edge a reordering pass must satisfy.
+    const bind = (ref, from) => {
+        const list = producers.get(keyOf(ref));
+        if (!list || list.length === 0)
+            return undefined;
+        let found;
+        for (const i of list) {
+            if (i === from)
+                return undefined; // self-dependency: never an edge
+            if (i < from)
+                found = i;
+        }
+        return found ?? list[0];
+    };
+    const edges = [];
+    const addEdge = (from, to, kind, via) => {
+        if (edges.some(e => e.from === from && e.to === to && e.kind === kind))
+            return;
+        const edge = { from, to, kind, via };
+        edges.push(edge);
+        nodes[from].out.push(edge);
+        nodes[to].in.push(edge);
+    };
+    facts.forEach((f, i) => {
+        const bodyOnly = new Set(f.bodyReferences.map(keyOf));
+        const fkKeys = new Set(f.fkTargets.map(keyOf));
+        for (const ref of f.references) {
+            const to = bind(ref, i);
+            if (to === undefined)
+                continue;
+            const key = keyOf(ref);
+            const kind = fkKeys.has(key) ? 'fk' : bodyOnly.has(key) ? 'late' : 'hard';
+            addEdge(i, to, kind, ref);
+        }
+    });
+    const components = condense(nodes);
+    const order = stableTopoOrder(nodes, components);
+    return { nodes, edges, producers, components, order };
+}
+/**
+ * Tarjan SCC over `hard` + `fk` edges (`late` edges are ignored — they are
+ * call-time bindings and legitimately cyclic). Components are returned in
+ * reverse-topological completion order and then re-sorted topologically with
+ * source-order tie-breaking by {@link stableTopoOrder}; here we only sort
+ * each component's members and order components by their smallest member so
+ * output is deterministic.
+ */
+function condense(nodes) {
+    const n = nodes.length;
+    const indexOf = new Array(n).fill(-1);
+    const low = new Array(n).fill(0);
+    const onStack = new Array(n).fill(false);
+    const stack = [];
+    const components = [];
+    let counter = 0;
+    const orderingEdges = (v) => nodes[v].out.filter(e => e.kind !== 'late').map(e => e.to);
+    // Iterative Tarjan (DDL scripts can be tens of thousands of statements).
+    const visit = (root) => {
+        const frames = [{ v: root, edges: orderingEdges(root), i: 0 }];
+        indexOf[root] = low[root] = counter++;
+        stack.push(root);
+        onStack[root] = true;
+        while (frames.length > 0) {
+            const frame = frames[frames.length - 1];
+            if (frame.i < frame.edges.length) {
+                const w = frame.edges[frame.i++];
+                if (indexOf[w] === -1) {
+                    indexOf[w] = low[w] = counter++;
+                    stack.push(w);
+                    onStack[w] = true;
+                    frames.push({ v: w, edges: orderingEdges(w), i: 0 });
+                }
+                else if (onStack[w]) {
+                    low[frame.v] = Math.min(low[frame.v], indexOf[w]);
+                }
+            }
+            else {
+                frames.pop();
+                if (frames.length > 0) {
+                    const parent = frames[frames.length - 1];
+                    low[parent.v] = Math.min(low[parent.v], low[frame.v]);
+                }
+                if (low[frame.v] === indexOf[frame.v]) {
+                    const component = [];
+                    for (;;) {
+                        const w = stack.pop();
+                        onStack[w] = false;
+                        component.push(w);
+                        if (w === frame.v)
+                            break;
+                    }
+                    component.sort((a, b) => a - b);
+                    components.push(component);
+                }
+            }
+        }
+    };
+    for (let v = 0; v < n; v++) {
+        if (indexOf[v] === -1)
+            visit(v);
+    }
+    components.sort((a, b) => a[0] - b[0]);
+    return components;
+}
+/**
+ * Topologically order the condensation with source order breaking ties
+ * (Kahn's algorithm over components, min-heap on smallest member index),
+ * then flatten: members of each component stay in source order.
+ */
+function stableTopoOrder(nodes, components) {
+    const componentOf = new Array(nodes.length).fill(0);
+    components.forEach((members, c) => {
+        for (const m of members)
+            componentOf[m] = c;
+    });
+    const succ = components.map(() => new Set());
+    const indegree = new Array(components.length).fill(0);
+    for (const node of nodes) {
+        for (const e of node.out) {
+            if (e.kind === 'late')
+                continue;
+            const from = componentOf[e.from];
+            const to = componentOf[e.to];
+            if (from === to)
+                continue;
+            // Dependency edge from → to means `to` must come first.
+            if (!succ[to].has(from)) {
+                succ[to].add(from);
+                indegree[from]++;
+            }
+        }
+    }
+    const ready = [];
+    for (let c = 0; c < components.length; c++) {
+        if (indegree[c] === 0)
+            ready.push(c);
+    }
+    const takeMin = () => {
+        let best = 0;
+        for (let i = 1; i < ready.length; i++) {
+            if (components[ready[i]][0] < components[ready[best]][0])
+                best = i;
+        }
+        return ready.splice(best, 1)[0];
+    };
+    const order = [];
+    while (ready.length > 0) {
+        const c = takeMin();
+        order.push(...components[c]);
+        for (const next of succ[c]) {
+            if (--indegree[next] === 0)
+                ready.push(next);
+        }
+    }
+    return order;
+}

package/esm/index.js

@@ -1,4 +1,7 @@
 export { classifyStatements } from './facts';
+export { buildStatementGraph } from './graph';
+export { identityOf } from './naming';
+export { orderStatements, restructureSql } from './restructure';
 export { COMMON_EXTENSIONS, ExtensionRouter } from './extension-router';
 export { createExtensionResult, createExtensionVisitor, transformExtensions, } from './extension-transform';
 export { RoleRouter } from './role-router';

package/esm/naming.js

@@ -0,0 +1,65 @@
+/**
+ * Derive the identity of the object a statement primarily creates or
+ * targets, or `null` when the statement creates nothing (grants, comments —
+ * such statements ride with the change of the object they attach to).
+ *
+ * Table-scoped kinds are recovered from the classifier's table-qualified
+ * names (`table.trigger`) and, for indexes and constraints, from the
+ * targeted relation.
+ */
+export function identityOf(facts) {
+    if (facts.kind === 'extension' && facts.extension) {
+        return { kind: 'extension', schema: null, name: facts.extension.name };
+    }
+    const created = facts.creates[0];
+    if (!created)
+        return null;
+    switch (facts.kind) {
+        case 'schema':
+            return { kind: 'schema', schema: null, name: created.name };
+        case 'trigger':
+        case 'policy': {
+            const dot = created.name.indexOf('.');
+            if (dot > 0) {
+                return {
+                    kind: facts.kind,
+                    schema: created.schema,
+                    name: created.name.slice(dot + 1),
+                    table: created.name.slice(0, dot)
+                };
+            }
+            return { kind: facts.kind, schema: created.schema, name: created.name };
+        }
+        case 'index': {
+            // IndexStmt records the index name in creates and the indexed relation
+            // in references (same-schema RangeVar).
+            const rel = facts.references.find(r => r.schema === created.schema) ?? facts.references[0];
+            return {
+                kind: 'index',
+                schema: created.schema,
+                name: created.name,
+                table: rel?.name
+            };
+        }
+        case 'fk_constraint':
+        case 'constraint':
+        case 'rls_enable':
+            // ALTER TABLE statements target their table.
+            return { kind: 'constraint', schema: created.schema, name: created.name, table: created.name };
+        case 'seed_dml':
+            return { kind: 'seed_dml', schema: created.schema, name: created.name, table: created.name };
+        case 'table':
+            // AlterTableStmt facts also classify as `table`-targeting; the created
+            // name is the table either way.
+            return { kind: 'table', schema: created.schema, name: created.name };
+        case 'view':
+        case 'function':
+        case 'type':
+            return { kind: facts.kind, schema: created.schema, name: created.name };
+        default:
+            if (facts.nodeTag === 'CreateSeqStmt') {
+                return { kind: 'sequence', schema: created.schema, name: created.name };
+            }
+            return { kind: 'other', schema: created.schema, name: created.name };
+    }
+}

package/esm/restructure.js

@@ -0,0 +1,327 @@
+/**
+ * Granularity restructuring: rewrite a DDL script between equivalent shapes
+ * without changing the schema it produces.
+ *
+ * Three levels, two directions:
+ *
+ * - `atomic` — every table is a bare `CREATE TABLE ()` followed by one
+ *   `ALTER TABLE ADD COLUMN` per column and one `ADD CONSTRAINT` per
+ *   constraint (the shape machine emitters produce).
+ * - `object` — each table is fully baked: columns and same-table constraints
+ *   (PK / UNIQUE / CHECK / NOT NULL / DEFAULT) fold into the `CREATE TABLE`;
+ *   cross-object statements (FKs, indexes, triggers, policies) stay separate.
+ * - `consolidated` — additionally inlines foreign keys into the table
+ *   definition whenever the dependency graph proves it safe (the referenced
+ *   table can be ordered first); FKs on cycles stay as `ALTER TABLE`.
+ *
+ * Every fold is validated against the {@link buildStatementGraph} statement
+ * graph: a candidate merge is rejected if it would create an ordering cycle,
+ * so the pass degrades gracefully to the atomic form instead of emitting an
+ * undeployable script. Output statements are re-emitted in the graph's
+ * stable topological order.
+ */
+import { Deparser, parseSql } from 'plpgsql-parser';
+import { classifyStatements } from './facts';
+import { buildStatementGraph } from './graph';
+const relKey = (rel) => rel ? `${rel.schemaname ?? ''}.${rel.relname}` : null;
+const sameRel = (a, b) => !!a && !!b && relKey(a) === relKey(b);
+/**
+ * Restructure a DDL script to the requested granularity. The input and
+ * output scripts deploy to identical schemas; only statement shape and
+ * order change.
+ */
+export function restructureSql(sql, options) {
+    const warnings = [];
+    const parsed = parseSql(sql);
+    const stmts = (parsed?.stmts ?? [])
+        .map((s) => s?.stmt)
+        .filter(Boolean);
+    let outStmts;
+    let folded = 0;
+    let exploded = 0;
+    if (options.granularity === 'atomic') {
+        const result = explodeStatements(stmts);
+        outStmts = result.stmts;
+        exploded = result.exploded;
+    }
+    else {
+        const facts = classifyStatements(sql);
+        const graph = buildStatementGraph(facts);
+        const result = foldStatements(stmts, graph, options.granularity === 'consolidated', warnings);
+        outStmts = result.stmts;
+        folded = result.folded;
+    }
+    const ordered = orderStatements(outStmts);
+    const text = ordered.map(s => `${Deparser.deparse(s)};`).join('\n\n');
+    return { sql: text, folded, exploded, warnings };
+}
+/**
+ * Re-emit statements in the stable topological order of their dependency
+ * graph. Statements are deparsed and re-classified so the ordering reflects
+ * exactly what will be emitted.
+ */
+export function orderStatements(stmts) {
+    if (stmts.length <= 1)
+        return stmts;
+    const script = stmts.map(s => `${Deparser.deparse(s)};`).join('\n');
+    const graph = buildStatementGraph(classifyStatements(script));
+    if (graph.order.length !== stmts.length)
+        return stmts;
+    return graph.order.map(i => stmts[i]);
+}
+/**
+ * Fold `ALTER TABLE` commands into their table's `CREATE TABLE` statement.
+ * `inlineFks` additionally folds `ADD FOREIGN KEY` when the graph proves the
+ * referenced table can be created first.
+ */
+function foldStatements(stmts, graph, inlineFks, warnings) {
+    // Locate the CREATE TABLE for each relation.
+    const createIndex = new Map();
+    stmts.forEach((s, i) => {
+        const create = s?.CreateStmt;
+        if (create?.relation) {
+            const key = relKey(create.relation);
+            if (key && !createIndex.has(key))
+                createIndex.set(key, i);
+        }
+    });
+    // Fold bookkeeping is a union-find over statements: folding j into the
+    // CREATE at i merges their graph nodes, and the merged node's dependency
+    // set is the union of both. Reachability is then computed over merged
+    // nodes so a second fold cannot silently complete a cycle the first one
+    // started (the mutual-FK case).
+    const rep = new Map();
+    const find = (v) => {
+        let r = v;
+        while (rep.has(r))
+            r = rep.get(r);
+        return r;
+    };
+    // Per-statement dependencies: typed graph edges plus the implicit edge
+    // from every ALTER to its own table's CREATE (the facts model records the
+    // alter as *targeting* the table, so the graph carries no self edge).
+    const deps = new Map();
+    stmts.forEach((s, j) => {
+        const set = new Set();
+        for (const e of graph.nodes[j]?.out ?? []) {
+            if (e.kind !== 'late')
+                set.add(e.to);
+        }
+        const alterKey = relKey(s?.AlterTableStmt?.relation);
+        const own = alterKey ? createIndex.get(alterKey) : undefined;
+        if (own !== undefined && own !== j)
+            set.add(own);
+        deps.set(j, set);
+    });
+    const depsOf = (v) => [...(deps.get(find(v)) ?? [])].map(find).filter(t => t !== find(v));
+    const dependsOn = (from, target) => {
+        const goal = find(target);
+        const seen = new Set();
+        const stack = [find(from)];
+        while (stack.length > 0) {
+            const v = stack.pop();
+            if (v === goal)
+                return true;
+            if (seen.has(v))
+                continue;
+            seen.add(v);
+            stack.push(...depsOf(v));
+        }
+        return false;
+    };
+    /**
+     * A command at statement `j` may fold into the CREATE at statement `i`
+     * iff none of j's dependencies (other than i itself) transitively depend
+     * on i — otherwise the merged node would sit on a cycle.
+     */
+    const safeToFold = (j, i) => !depsOf(j).some(t => t !== find(i) && dependsOn(t, i));
+    /** Merge statement `j` into the CREATE at `i`. */
+    const absorb = (i, j) => {
+        const target = find(i);
+        const merged = deps.get(target) ?? new Set();
+        for (const t of deps.get(find(j)) ?? [])
+            merged.add(t);
+        deps.set(target, merged);
+        if (find(j) !== target)
+            rep.set(find(j), target);
+    };
+    const remove = new Set();
+    let folded = 0;
+    stmts.forEach((s, j) => {
+        const alter = s?.AlterTableStmt;
+        if (!alter || alter.objtype !== 'OBJECT_TABLE')
+            return;
+        const key = relKey(alter.relation);
+        const i = key ? createIndex.get(key) : undefined;
+        if (i === undefined || i === j)
+            return;
+        const create = stmts[i].CreateStmt;
+        const remaining = [];
+        for (const wrapped of alter.cmds ?? []) {
+            const cmd = wrapped?.AlterTableCmd;
+            if (!cmd) {
+                remaining.push(wrapped);
+                continue;
+            }
+            const constraint = cmd.def?.Constraint;
+            const isFk = cmd.subtype === 'AT_AddConstraint' && constraint?.contype === 'CONSTR_FOREIGN';
+            const selfFk = isFk && sameRel(constraint?.pktable, alter.relation);
+            let foldable = false;
+            switch (cmd.subtype) {
+                case 'AT_AddColumn':
+                    foldable = !!cmd.def?.ColumnDef;
+                    break;
+                case 'AT_ColumnDefault':
+                    foldable = !!cmd.name && cmd.def !== undefined;
+                    break;
+                case 'AT_SetNotNull':
+                    foldable = !!cmd.name;
+                    break;
+                case 'AT_AddConstraint':
+                    foldable = isFk ? selfFk || inlineFks : true;
+                    break;
+                default:
+                    foldable = false;
+            }
+            if (foldable && !selfFk && !safeToFold(j, i)) {
+                warnings.push(`kept atomic: statement ${j} on ${key} would create an ordering cycle if folded`);
+                foldable = false;
+            }
+            if (!foldable) {
+                remaining.push(wrapped);
+                continue;
+            }
+            if (!applyFold(create, cmd)) {
+                remaining.push(wrapped);
+                continue;
+            }
+            absorb(i, j);
+            folded++;
+        }
+        if (remaining.length === 0) {
+            remove.add(j);
+        }
+        else {
+            alter.cmds = remaining;
+        }
+    });
+    return { stmts: stmts.filter((_, i) => !remove.has(i)), folded };
+}
+/** Apply one foldable ALTER TABLE command onto a CreateStmt. */
+function applyFold(create, cmd) {
+    create.tableElts = create.tableElts ?? [];
+    const findColumn = (name) => create.tableElts.find((e) => e?.ColumnDef?.colname === name)?.ColumnDef;
+    switch (cmd.subtype) {
+        case 'AT_AddColumn':
+            create.tableElts.push({ ColumnDef: cmd.def.ColumnDef });
+            return true;
+        case 'AT_ColumnDefault': {
+            const col = findColumn(cmd.name);
+            if (!col)
+                return false;
+            col.constraints = col.constraints ?? [];
+            col.constraints.push({ Constraint: { contype: 'CONSTR_DEFAULT', raw_expr: cmd.def } });
+            return true;
+        }
+        case 'AT_SetNotNull': {
+            const col = findColumn(cmd.name);
+            if (!col)
+                return false;
+            col.constraints = col.constraints ?? [];
+            col.constraints.push({ Constraint: { contype: 'CONSTR_NOTNULL' } });
+            return true;
+        }
+        case 'AT_AddConstraint':
+            create.tableElts.push({ Constraint: cmd.def.Constraint });
+            return true;
+        default:
+            return false;
+    }
+}
+/** Column-level constraint types that stay inline on `ADD COLUMN`. */
+const INLINE_COLUMN_CONSTRAINTS = new Set(['CONSTR_DEFAULT', 'CONSTR_NOTNULL', 'CONSTR_NULL', 'CONSTR_IDENTITY', 'CONSTR_GENERATED']);
+/**
+ * Explode consolidated `CREATE TABLE` statements into the atomic shape:
+ * bare create, one `ADD COLUMN` per column (keeping column-local defaults /
+ * NOT NULL inline), one `ADD CONSTRAINT` per table-level or key constraint.
+ */
+function explodeStatements(stmts) {
+    const out = [];
+    let exploded = 0;
+    const alterFor = (relation, cmd) => ({
+        AlterTableStmt: {
+            objtype: 'OBJECT_TABLE',
+            relation,
+            cmds: [{ AlterTableCmd: cmd }]
+        }
+    });
+    for (const s of stmts) {
+        const create = s?.CreateStmt;
+        const elts = create?.tableElts ?? [];
+        // Typed tables / partitions / inheritance keep their shape.
+        if (!create || elts.length === 0 || create.ofTypename || create.partbound || create.inhRelations) {
+            out.push(s);
+            continue;
+        }
+        const relation = create.relation;
+        const columns = [];
+        const constraints = [];
+        for (const elt of elts) {
+            if (elt?.ColumnDef)
+                columns.push(elt.ColumnDef);
+            else if (elt?.Constraint)
+                constraints.push(elt.Constraint);
+            else {
+                // Unknown element (e.g. LIKE clause): keep the table intact.
+                columns.length = 0;
+                constraints.length = 0;
+                break;
+            }
+        }
+        if (columns.length === 0 && constraints.length === 0) {
+            out.push(s);
+            continue;
+        }
+        out.push({ CreateStmt: { ...create, tableElts: [] } });
+        for (const col of columns) {
+            const inline = [];
+            for (const wrapped of col.constraints ?? []) {
+                const c = wrapped?.Constraint;
+                if (c && INLINE_COLUMN_CONSTRAINTS.has(c.contype)) {
+                    inline.push(wrapped);
+                }
+                else if (c) {
+                    // Promote a column constraint (PK/UNIQUE/CHECK/FK) to table level.
+                    constraints.push(columnConstraintToTable(c, col.colname));
+                }
+            }
+            out.push(alterFor(relation, {
+                subtype: 'AT_AddColumn',
+                def: { ColumnDef: { ...col, constraints: inline.length > 0 ? inline : undefined } }
+            }));
+            exploded++;
+        }
+        for (const constraint of constraints) {
+            out.push(alterFor(relation, {
+                subtype: 'AT_AddConstraint',
+                def: { Constraint: constraint }
+            }));
+            exploded++;
+        }
+    }
+    return { stmts: out, exploded };
+}
+/** Rewrite a column-level constraint as its table-level equivalent. */
+function columnConstraintToTable(constraint, colname) {
+    const strNode = (sval) => ({ String: { sval } });
+    switch (constraint.contype) {
+        case 'CONSTR_PRIMARY':
+        case 'CONSTR_UNIQUE':
+            return { ...constraint, keys: [strNode(colname)] };
+        case 'CONSTR_FOREIGN':
+            return { ...constraint, fk_attrs: [strNode(colname)] };
+        default:
+            // CHECK and others are valid table constraints as-is.
+            return constraint;
+    }
+}

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;