feat(transform): statement dependency graph + granularity restructuring (atomic ↔ object ↔ consolidated)

[pyramation]

Summary

Adds two modules to @pgsql/transform that let a DDL script be rewritten between equivalent shapes without changing the schema it deploys — the substrate for exporting pgpm modules at different human-readability levels.

graph.ts — buildStatementGraph(facts): turns classifyStatements output into a typed statement dependency graph:

• edges are hard (must resolve at CREATE time), fk (hard, but the edges FK-inlining must respect), or late (PL/pgSQL body references — call-time bound, never ordering constraints, legitimately cyclic);
• Tarjan SCC condensation over hard+fk edges (iterative, handles huge scripts) + stable topological order (source order breaks ties).

restructure.ts — restructureSql(sql, { granularity }) with three levels:

• atomic: explode CREATE TABLE into bare create + one ADD COLUMN per column + one ADD CONSTRAINT per constraint (column-level PK/UNIQUE/FK promoted to table-level; DEFAULT/NOT NULL/IDENTITY stay inline on the column);
• object: fold columns and same-table constraints back into the CREATE TABLE; cross-object statements stay separate;
• consolidated: additionally inline FKs as table constraints when the graph proves the referenced table can be ordered first.

Fold safety is a union-find merge over the statement graph: folding an ALTER into its CREATE merges their nodes and unions their dependencies, and a candidate fold is rejected iff it would put the merged node on a cycle. This is what makes mutual FKs degrade gracefully — the first FK inlines, the second is provably cycle-forming and stays an ALTER TABLE (with a warning). Output is re-emitted in the graph's stable topo order, so forward references are repaired for free.

const { sql, folded, warnings } = restructureSql(atomicExport, { granularity: 'consolidated' });
const { sql: atomicAgain } = restructureSql(sql, { granularity: 'atomic' }); // round-trips

Tests cover fold/explode round-trips, self-FKs, mutual-FK cycle rejection, late-edge (PL/pgSQL) cycles, and forward-reference reordering.

Link to Devin session: https://app.devin.ai/sessions/562099f8b3d94877b5ab57ec8bb90bec
Requested by: @pyramation

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring