Merge pull request #1553 from constructive-io/feat/graph-convergence

refactor(slice): converge on @pgsql/transform's graph substrate (Phase 2)

Author: pyramation

pgpm/slice/__tests__/object-graph.test.ts

@@ -33,7 +33,7 @@ describe('buildObjectGraph', () => {
     const intoUsers = graph.incoming.get(objectKey({ schema: 'auth', name: 'users' }))!;
     const kinds = intoUsers.map(e => `${e.from.program}:${e.kind}`).sort();
     expect(kinds).toContain('app/posts:fk');
-    expect(kinds).toContain('auth/uid:body');
+    expect(kinds).toContain('auth/uid:late');
   });
 });
 
@@ -58,7 +58,7 @@ describe('danglingEdges', () => {
     const summary = dangling.map(e => `${e.from.program}:${e.kind}`).sort();
     // auth/uid's body reference to auth.users originates inside the dropped
     // set, so it must NOT dangle; the FK and the policy accessor call must.
-    expect(summary).toEqual(['app/policy:reference', 'app/posts:fk', 'app/posts:reference']);
+    expect(summary).toEqual(['app/policy:hard', 'app/posts:fk']);
   });
 
   it('is empty when the referencing statements are dropped too', () => {

pgpm/slice/src/closure.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 
+import { objectKey } from './object-graph';
 import { extractSqlFacts } from './refs';
 import {
   ClosureAutoInclude,
@@ -9,10 +10,6 @@ import {
   PatternStrategy
 } from './types';
 
-function objectKey(schema: string | null, name: string): string {
-  return `${schema ?? ''}\u0000${name}`;
-}
-
 function refLabel(schema: string | null, name: string): string {
   return schema ? `${schema}.${name}` : name;
 }
@@ -51,7 +48,7 @@ export function buildAstEdges(graph: DependencyGraph, moduleDir: string): AstEdg
     const f = facts.get(change.name);
     if (!f) continue;
     for (const c of f.creates) {
-      const key = objectKey(c.schema, c.name);
+      const key = objectKey(c);
       if (!producerByObject.has(key)) producerByObject.set(key, change.name);
     }
   }
@@ -63,7 +60,7 @@ export function buildAstEdges(graph: DependencyGraph, moduleDir: string): AstEdg
   for (const [changeName, f] of facts) {
     if (f.dynamicSql) dynamicSqlChanges.push(changeName);
     for (const r of f.references) {
-      const producer = producerByObject.get(objectKey(r.schema, r.name));
+      const producer = producerByObject.get(objectKey(r));
       if (!producer) {
         unresolvedReferences.push({ change: changeName, ref: refLabel(r.schema, r.name) });
         continue;

pgpm/slice/src/object-graph.ts

@@ -2,10 +2,10 @@
  * Unified SQL object graph — the semantic IR over parsed programs.
  *
  * Nodes are database objects (keyed by qualified name) with the statements
- * that create them; edges are the references statements make to objects:
- * plain references, late-bound PL/pgSQL body references, and foreign-key
- * targets. Programs are named (typically one per pgpm change), so ownership
- * queries answer change-level questions directly:
+ * that create them; edges are the references statements make to objects,
+ * typed with `@pgsql/transform`'s edge taxonomy (`hard | fk | late`).
+ * Programs are named (typically one per pgpm change), so ownership queries
+ * answer change-level questions directly:
  *
  * - which objects live in a schema set (subsystem selection)
  * - which surviving statements still reach into a dropped object set
@@ -14,9 +14,15 @@
  * - which programs create nothing outside a dropped set (whole-change
  *   pruning by ownership, not survivor counting)
  *
+ * Each program's intra-program edges come straight from
+ * `buildStatementGraph`; references with no in-program producer (external
+ * dependencies, which the statement graph deliberately omits) are added with
+ * the same kind classification, so the object graph is a superset projection
+ * of the statement graph over the same facts.
+ *
  * Pure and I/O-free; built from `SqlProgram`s parsed once elsewhere.
  */
-import type { SqlProgram, StatementFacts } from '@pgpmjs/transform';
+import { buildStatementGraph, EdgeKind, SqlProgram, StatementFacts } from '@pgpmjs/transform';
 
 import { SqlObjectRef } from './refs';
 
@@ -26,7 +32,13 @@ export interface StatementId {
   statement: number;
 }
 
-export type ObjectEdgeKind = 'reference' | 'body' | 'fk';
+/**
+ * How an edge constrains ordering — `@pgsql/transform`'s taxonomy:
+ * `hard` (must exist at CREATE time), `fk` (a hard edge from a foreign-key
+ * target), `late` (reached only inside a PL/pgSQL body, resolved at call
+ * time).
+ */
+export type ObjectEdgeKind = EdgeKind;
 
 /** One reference from a statement to an object. */
 export interface ObjectEdge {
@@ -78,29 +90,60 @@ export function buildObjectGraph(
   const incoming = new Map<string, ObjectEdge[]>();
 
   const addEdge = (edge: ObjectEdge): void => {
-    edges.push(edge);
     const list = incoming.get(edge.to);
-    if (list) list.push(edge);
-    else incoming.set(edge.to, [edge]);
+    if (list) {
+      if (list.some(
+        e => e.kind === edge.kind &&
+          e.from.program === edge.from.program &&
+          e.from.statement === edge.from.statement
+      )) return;
+      list.push(edge);
+    } else {
+      incoming.set(edge.to, [edge]);
+    }
+    edges.push(edge);
   };
 
   for (const [name, program] of programMap) {
-    program.statements.forEach((stmt, i) => {
+    const facts = program.statements.map(s => s.facts);
+    const statementGraph = buildStatementGraph(facts);
+
+    facts.forEach((stmt, i) => {
       const id: StatementId = { program: name, statement: i };
-      for (const c of stmt.facts.creates) {
+      for (const c of stmt.creates) {
         const key = objectKey(c);
         const node = objects.get(key);
         if (node) node.createdBy.push(id);
         else objects.set(key, { ref: { schema: c.schema, name: c.name }, createdBy: [id] });
       }
-      for (const r of stmt.facts.references) {
-        addEdge({ from: id, to: objectKey(r), kind: 'reference' });
-      }
-      for (const r of stmt.facts.bodyReferences) {
-        addEdge({ from: id, to: objectKey(r), kind: 'body' });
+    });
+
+    // Intra-program edges, exactly as the statement graph typed them.
+    for (const e of statementGraph.edges) {
+      addEdge({ from: { program: name, statement: e.from }, to: objectKey(e.via), kind: e.kind });
+    }
+
+    // References with no in-program producer are external dependencies: the
+    // statement graph induces no edge for them, but the object graph keeps
+    // them (that is what contract/cascade queries measure). Same kind
+    // classification: fk beats late beats hard.
+    facts.forEach((stmt, i) => {
+      const id: StatementId = { program: name, statement: i };
+      const bodyOnly = new Set(stmt.bodyReferences.map(objectKey));
+      const fkKeys = new Set(stmt.fkTargets.map(objectKey));
+      const seen = new Set<string>();
+      for (const r of stmt.references) {
+        const key = objectKey(r);
+        seen.add(key);
+        if (statementGraph.producers.has(`${r.schema ?? ''}.${r.name}`)) continue;
+        const kind: EdgeKind = fkKeys.has(key) ? 'fk' : bodyOnly.has(key) ? 'late' : 'hard';
+        addEdge({ from: id, to: key, kind });
       }
-      for (const t of stmt.facts.fkTargets) {
-        addEdge({ from: id, to: objectKey(t), kind: 'fk' });
+      for (const t of stmt.fkTargets) {
+        const key = objectKey(t);
+        if (seen.has(key)) continue;
+        if (statementGraph.producers.has(`${t.schema ?? ''}.${t.name}`)) continue;
+        addEdge({ from: id, to: key, kind: 'fk' });
       }
     });
   }

pgpm/slice/src/partition.ts

@@ -4,6 +4,7 @@ import { join } from 'path';
 import { parsePlanFile } from '@pgpmjs/ast/files/plan/parser';
 
 import { AstEdges, buildAstEdges } from './closure';
+import { objectKey } from './object-graph';
 import { extractSqlFacts, SqlObjectRef } from './refs';
 import { buildDependencyGraph } from './slice';
 import { DependencyGraph } from './types';
@@ -150,10 +151,6 @@ export interface PartitionModuleResult extends PartitionResult {
   seedChanges: string[];
 }
 
-function objectKey(schema: string | null, name: string): string {
-  return `${schema ?? ''}\u0000${name}`;
-}
-
 /**
  * On-disk entry point: parse a module's plan + deploy SQL, resolve the given
  * per-tenant seed *objects* to the changes that create them, and partition the
@@ -178,15 +175,15 @@ export function partitionModule(options: PartitionModuleOptions): PartitionModul
     if (!existsSync(deployPath)) continue;
     const facts = extractSqlFacts(readFileSync(deployPath, 'utf-8'));
     for (const c of facts.creates) {
-      const key = objectKey(c.schema, c.name);
+      const key = objectKey(c);
       if (!producerByObject.has(key)) producerByObject.set(key, change.name);
     }
   }
 
   const seedChanges: string[] = [];
   const unresolvedSeeds: PartitionWarning[] = [];
   for (const obj of options.seedObjects) {
-    const producer = producerByObject.get(objectKey(obj.schema, obj.name));
+    const producer = producerByObject.get(objectKey(obj));
     if (!producer) {
       unresolvedSeeds.push({
         kind: 'unknown-seed',

pgpm/slice/src/refs.ts

@@ -1,4 +1,4 @@
-import { classifyStatements } from '@pgpmjs/transform';
+import { buildStatementGraph, classifyStatements, QualifiedName } from '@pgpmjs/transform';
 
 /**
  * The parser runs on a WASM build of the real PostgreSQL parser; callers must
@@ -8,11 +8,10 @@ export { loadModule } from 'plpgsql-parser';
 
 /**
  * A (possibly schema-qualified) database object name extracted from SQL.
+ * Alias of `@pgsql/transform`'s `QualifiedName` — one name type across the
+ * facts substrate and the slice layer.
  */
-export interface SqlObjectRef {
-  schema: string | null;
-  name: string;
-}
+export type SqlObjectRef = QualifiedName;
 
 /**
  * AST-derived facts about a change's deploy SQL, used to discover
@@ -46,27 +45,27 @@ function pushUnique(list: SqlObjectRef[], r: SqlObjectRef): void {
  * including references reached inside PL/pgSQL function bodies (which are
  * opaque strings in `CREATE FUNCTION` and invisible to a plain SQL parse).
  *
- * Aggregates `@pgsql/transform`'s per-statement `classifyStatements` facts to
- * the change level: references satisfied by objects the same change creates
- * (in any statement) are dropped.
+ * A thin change-level adapter over `@pgsql/transform`: `classifyStatements`
+ * produces the per-statement facts and `buildStatementGraph`'s producer index
+ * decides which references are internal — a reference with an in-script
+ * producer is satisfied by the change itself, so only external references
+ * (the statement graph's non-edges) surface as change-level dependencies.
  */
 export function extractSqlFacts(sql: string): ChangeSqlFacts {
+  const statements = classifyStatements(sql);
+  const graph = buildStatementGraph(statements);
   const facts: ChangeSqlFacts = { creates: [], references: [], dynamicSql: false };
 
-  for (const stmt of classifyStatements(sql)) {
+  for (const stmt of statements) {
     for (const c of stmt.creates) {
       pushUnique(facts.creates, { schema: c.schema, name: c.name });
     }
     for (const r of stmt.references) {
+      if (graph.producers.has(`${r.schema ?? ''}.${r.name}`)) continue;
       pushUnique(facts.references, { schema: r.schema, name: r.name });
     }
     if (stmt.dynamicSql) facts.dynamicSql = true;
   }
 
-  // A change does not depend on objects it creates itself.
-  facts.references = facts.references.filter(
-    r => !facts.creates.some(c => c.schema === r.schema && c.name === r.name)
-  );
-
   return facts;
 }