feat(transform): granularity driver — restructure pgpm changes between atomic / object / consolidated

[pyramation]

Summary

pgpm-side driver for the granularity restructuring added in pgsql-parser#325. restructureChanges(changes, { granularity }) in @pgpmjs/transform rewrites a module's deploy surface between three equivalent shapes:

• atomic — bare CREATE TABLE + one ALTER per column/constraint (today's export shape);
• object — each table fully baked with its columns and same-table constraints, cross-object statements (FKs, indexes, triggers) separate;
• consolidated — additionally inlines FKs the statement graph proves safe (mutual-FK cycles degrade to ALTER TABLE with a warning).

Pipeline: flatten deploy scripts in plan order → restructureSql (upstream fold/explode guarded by the statement dependency graph) → re-slice into changes grouped by created object (schemas/<schema>/tables/<name> naming via defaultChangeName, overridable via changeName) → change dependencies recomputed from statement-graph edges plus schema-of-created-object edges. Like the other drivers here it's structurally typed on the bundle seams (no @pgpmjs/bundle/@pgpmjs/core dependency).

const { changes, warnings } = restructureChanges(moduleChanges, { granularity: 'consolidated' });
// and back: restructureChanges(changes, { granularity: 'atomic' })

Draft: depends on @pgsql/transform publishing restructureSql/buildStatementGraph (pgsql-parser#325). CI will fail on the missing exports until that release lands and the dep resolves ≥ that version; tests pass locally against the built PR dist (39/39 in pgpm/transform).

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