@pgsql/semantics 18.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Dan Lynch <pyramation@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# @pgsql/semantics
+
+<p align="center" width="100%">
+  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
+</p>
+
+<p align="center" width="100%">
+  <a href="https://github.com/constructive-io/pgsql-parser/actions/workflows/run-tests.yaml">
+    <img height="20" src="https://github.com/constructive-io/pgsql-parser/actions/workflows/run-tests.yaml/badge.svg" />
+  </a>
+   <a href="https://github.com/constructive-io/pgsql-parser/blob/main/LICENSE-MIT"><img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/></a>
+   <a href="https://www.npmjs.com/package/@pgsql/semantics"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/pgsql-parser?filename=packages%2Fsemantics%2Fpackage.json"/></a>
+</p>
+
+AST-derived **semantic facts** for PostgreSQL statements: given a SQL script,
+extract what each statement *is*, what it *creates*, and what it *references* —
+including references reached inside PL/pgSQL function bodies (via `plpgsql-parser`
+hydration). Read-only: the input is never modified.
+
+This is the fact-extraction layer that grew up inside [`@pgsql/transform`](../transform).
+It extracts *semantics* (which relations/functions/types a statement reads and
+creates, which namespaces it touches), independent of any transformation.
+`@pgsql/transform` re-exports the same symbols, so existing consumers are
+unaffected.
+
+## Installation
+
+```bash
+npm install @pgsql/semantics
+```
+
+The parser runs on a WASM build of the real PostgreSQL parser; call `loadModule()`
+from `plpgsql-parser` once before using any synchronous API.
+
+## Usage
+
+```typescript
+import { loadModule } from 'plpgsql-parser';
+import { classifyStatements } from '@pgsql/semantics';
+
+await loadModule();
+
+const facts = classifyStatements(sql);
+// per statement: kind (schema|table|view|index|type|function|trigger|policy|grant|...),
+// creates, references (incl. inside PL/pgSQL bodies), bodyReferences,
+// referencedSchemas, roles, fkTargets, extension, securityRelevant,
+// securityDefiner, dynamicSql, span, stmt
+```
+
+## Exports
+
+- `classifyStatements(sql)` — classify each top-level statement into `StatementFacts[]`.
+- Types: `StatementFacts`, `StatementKind`, `QualifiedName`, `ExtensionFact`, `ExtensionAction`, `StatementSpan`.
+
+---
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Related
+
+* [pgpm](https://pgpm.dev): A Postgres Package Manager that brings modular development to PostgreSQL with reusable packages, deterministic migrations, recursive dependency resolution, and tag-aware versioning.
+* [pgsql-test](https://www.npmjs.com/package/pgsql-test): Instant, isolated PostgreSQL databases for each test with automatic transaction rollbacks, context switching, and clean seeding for fast, reliable database testing.
+* [pgsql-seed](https://www.npmjs.com/package/pgsql-seed): PostgreSQL seeding utilities for CSV, JSON, SQL data loading, and pgpm deployment.
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): The real PostgreSQL parser for Node.js, providing symmetric parsing and deparsing of SQL statements with actual PostgreSQL parser integration.
+* [pgsql-deparser](https://www.npmjs.com/package/pgsql-deparser): A streamlined tool designed for converting PostgreSQL ASTs back into SQL queries, focusing solely on deparser functionality to complement `pgsql-parser`.
+* [@pgsql/parser](https://www.npmjs.com/package/@pgsql/parser): Multi-version PostgreSQL parser with dynamic version selection at runtime, supporting PostgreSQL 15, 16, and 17 in a single package.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): Offers TypeScript type definitions for PostgreSQL AST nodes, facilitating type-safe construction, analysis, and manipulation of ASTs.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): Provides TypeScript enum definitions for PostgreSQL constants, enabling type-safe usage of PostgreSQL enums and constants in your applications.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): A comprehensive utility library for PostgreSQL, offering type-safe AST node creation and enum value conversions, simplifying the construction and manipulation of PostgreSQL ASTs.
+* [@pgsql/traverse](https://www.npmjs.com/package/@pgsql/traverse): PostgreSQL AST traversal utilities for pgsql-parser, providing a visitor pattern for traversing PostgreSQL Abstract Syntax Tree nodes, similar to Babel's traverse functionality but specifically designed for PostgreSQL AST structures.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): A TypeScript tool that parses PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [libpg-query](https://github.com/constructive-io/libpg-query-node): The real PostgreSQL parser exposed for Node.js, used primarily in `pgsql-parser` for parsing and deparsing SQL queries.
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating Software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the Software code or Software CLI, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/esm/facts.js

@@ -0,0 +1,393 @@
+import { walkSqlAst } from '@pgsql/traverse';
+import { parseSql, transformSync, walkPlpgsqlAst } from 'plpgsql-parser';
+const SECURITY_TAGS = new Set([
+    'CreatePolicyStmt',
+    'AlterPolicyStmt',
+    'GrantStmt',
+    'GrantRoleStmt',
+    'AlterDefaultPrivilegesStmt',
+    'SecLabelStmt',
+    'AlterOwnerStmt',
+    'CreateRoleStmt',
+    'AlterRoleStmt'
+]);
+const KIND_BY_TAG = {
+    CreateSchemaStmt: 'schema',
+    CreateExtensionStmt: 'extension',
+    CreateStmt: 'table',
+    ViewStmt: 'view',
+    IndexStmt: 'index',
+    CompositeTypeStmt: 'type',
+    CreateEnumStmt: 'type',
+    CreateDomainStmt: 'type',
+    CreateRangeStmt: 'type',
+    DefineStmt: 'type',
+    CreateFunctionStmt: 'function',
+    CreateTrigStmt: 'trigger',
+    CreateEventTrigStmt: 'trigger',
+    CreatePolicyStmt: 'policy',
+    AlterPolicyStmt: 'policy',
+    GrantStmt: 'grant',
+    GrantRoleStmt: 'grant',
+    AlterDefaultPrivilegesStmt: 'grant',
+    CommentStmt: 'comment',
+    InsertStmt: 'seed_dml',
+    UpdateStmt: 'seed_dml',
+    DeleteStmt: 'seed_dml'
+};
+function qn(schema, name) {
+    return { schema: schema ?? null, name };
+}
+/**
+ * Read the `SCHEMA <name>` clause of a `CreateExtensionStmt` from its options
+ * (`{ DefElem: { defname: 'schema', arg: { String: { sval } } } }`), or `null`
+ * when the statement specifies no schema.
+ */
+function extensionSchemaOption(options) {
+    if (!Array.isArray(options))
+        return null;
+    for (const opt of options) {
+        const def = opt?.DefElem;
+        if (def?.defname === 'schema') {
+            const sval = def.arg?.String?.sval;
+            return typeof sval === 'string' ? sval : null;
+        }
+    }
+    return null;
+}
+function nameListToQualified(names) {
+    if (!Array.isArray(names) || names.length === 0)
+        return null;
+    const parts = names
+        .map((n) => n?.String?.sval)
+        .filter((s) => typeof s === 'string');
+    if (parts.length === 0)
+        return null;
+    if (parts.length === 1)
+        return qn(null, parts[0]);
+    return qn(parts[parts.length - 2], parts[parts.length - 1]);
+}
+function isCatalogSchema(schema) {
+    return schema === 'pg_catalog' || schema === 'information_schema';
+}
+function pushRef(refs, ref) {
+    if (!ref || !ref.schema || isCatalogSchema(ref.schema))
+        return;
+    if (refs.some(r => r.schema === ref.schema && r.name === ref.name))
+        return;
+    refs.push(ref);
+}
+function collectRoles(node, roles) {
+    const push = (role) => {
+        if (typeof role === 'string' && role.length > 0 && !roles.includes(role)) {
+            roles.push(role);
+        }
+    };
+    if (Array.isArray(node?.grantees)) {
+        for (const g of node.grantees)
+            push(g?.RoleSpec?.rolename);
+    }
+    if (Array.isArray(node?.roles)) {
+        for (const r of node.roles)
+            push(r?.RoleSpec?.rolename);
+    }
+    push(node?.newowner?.rolename);
+    push(node?.role?.rolename);
+}
+/**
+ * Create a read-only visitor that accumulates references, roles and FK
+ * targets into the provided facts object.
+ */
+function createFactsVisitor(facts, bodyRefs) {
+    const push = (ref) => {
+        pushRef(facts.references, ref);
+        if (bodyRefs)
+            pushRef(bodyRefs, ref);
+    };
+    return {
+        RangeVar: (path) => {
+            const node = path.node;
+            if (node.schemaname) {
+                push(qn(node.schemaname, node.relname));
+            }
+        },
+        FuncCall: (path) => {
+            push(nameListToQualified(path.node.funcname));
+        },
+        TypeName: (path) => {
+            push(nameListToQualified(path.node.names));
+        },
+        ColumnRef: (path) => {
+            // schema.table.column references carry cross-schema information
+            const fields = path.node.fields;
+            if (Array.isArray(fields) && fields.length >= 3) {
+                const parts = fields
+                    .map((f) => f?.String?.sval)
+                    .filter((s) => typeof s === 'string');
+                if (parts.length >= 3) {
+                    push(qn(parts[0], parts[1]));
+                }
+            }
+        },
+        Constraint: (path) => {
+            const node = path.node;
+            if (node.contype === 'CONSTR_FOREIGN' && node.pktable) {
+                const target = qn(node.pktable.schemaname ?? null, node.pktable.relname);
+                if (!facts.fkTargets.some(t => t.schema === target.schema && t.name === target.name)) {
+                    facts.fkTargets.push(target);
+                }
+                if (target.schema)
+                    pushRef(facts.references, target);
+            }
+        }
+    };
+}
+function classifyOne(nodeTag, node) {
+    const facts = {
+        kind: KIND_BY_TAG[nodeTag] ?? 'other',
+        nodeTag,
+        creates: [],
+        references: [],
+        referencedSchemas: [],
+        roles: [],
+        fkTargets: [],
+        bodyReferences: [],
+        securityRelevant: SECURITY_TAGS.has(nodeTag),
+        securityDefiner: false,
+        dynamicSql: false,
+        span: { start: 0, len: 0 }
+    };
+    switch (nodeTag) {
+        case 'CreateSchemaStmt':
+            facts.creates.push(qn(null, node.schemaname));
+            break;
+        case 'CreateExtensionStmt':
+            facts.extension = {
+                name: node.extname,
+                schema: extensionSchemaOption(node.options),
+                action: 'create',
+                ifNotExists: node.if_not_exists === true
+            };
+            break;
+        case 'CreateStmt':
+        case 'ViewStmt': {
+            const rel = nodeTag === 'ViewStmt' ? node.view : node.relation;
+            if (rel)
+                facts.creates.push(qn(rel.schemaname ?? null, rel.relname));
+            break;
+        }
+        case 'IndexStmt':
+            if (node.relation) {
+                facts.creates.push(qn(node.relation.schemaname ?? null, node.idxname ?? node.relation.relname));
+            }
+            break;
+        case 'CreateFunctionStmt': {
+            const name = nameListToQualified(node.funcname);
+            if (name)
+                facts.creates.push(name);
+            for (const opt of node.options ?? []) {
+                const def = opt?.DefElem;
+                if (def?.defname === 'security' && def?.arg?.Boolean?.boolval === true) {
+                    facts.securityDefiner = true;
+                }
+            }
+            break;
+        }
+        case 'CreateTrigStmt':
+            if (node.relation) {
+                // Trigger names are only unique per table; qualify with the table.
+                facts.creates.push(qn(node.relation.schemaname ?? null, `${node.relation.relname}.${node.trigname}`));
+            }
+            pushRef(facts.references, nameListToQualified(node.funcname));
+            break;
+        case 'CreatePolicyStmt':
+        case 'AlterPolicyStmt':
+            if (node.table) {
+                // Policy names are only unique per table; qualify with the table.
+                facts.creates.push(qn(node.table.schemaname ?? null, `${node.table.relname}.${node.policy_name}`));
+                // The guarded table lives on `node.table`; the generic RangeVar walker
+                // does not descend into it, so capture the reference explicitly.
+                if (node.table.schemaname) {
+                    pushRef(facts.references, qn(node.table.schemaname, node.table.relname));
+                }
+            }
+            break;
+        case 'CreateSeqStmt':
+            if (node.sequence) {
+                facts.creates.push(qn(node.sequence.schemaname ?? null, node.sequence.relname));
+            }
+            break;
+        case 'CompositeTypeStmt':
+            if (node.typevar) {
+                facts.creates.push(qn(node.typevar.schemaname ?? null, node.typevar.relname));
+            }
+            break;
+        case 'CreateEnumStmt':
+        case 'CreateRangeStmt': {
+            const name = nameListToQualified(node.typeName);
+            if (name)
+                facts.creates.push(name);
+            break;
+        }
+        case 'CreateDomainStmt': {
+            // `typeName` on a domain is the base type; the name is `domainname`.
+            const name = nameListToQualified(node.domainname);
+            if (name)
+                facts.creates.push(name);
+            break;
+        }
+        case 'AlterObjectSchemaStmt':
+            // ALTER EXTENSION <name> SET SCHEMA <newschema>. Other object types
+            // (TABLE/TYPE/FUNCTION ... SET SCHEMA) keep their default classification.
+            if (node.objectType === 'OBJECT_EXTENSION') {
+                const name = node.object?.String?.sval;
+                if (typeof name === 'string') {
+                    facts.kind = 'extension';
+                    facts.extension = {
+                        name,
+                        schema: typeof node.newschema === 'string' ? node.newschema : null,
+                        action: 'set_schema'
+                    };
+                }
+            }
+            break;
+        case 'DropStmt':
+            // DROP EXTENSION <name> [, ...]. Extension names are bare String nodes.
+            // Other DROP object types keep their default classification. When
+            // several extensions are dropped in one statement the first names the
+            // fact; the full list stays available via the raw node.
+            if (node.removeType === 'OBJECT_EXTENSION' && Array.isArray(node.objects)) {
+                const name = node.objects[0]?.String?.sval;
+                if (typeof name === 'string') {
+                    facts.kind = 'extension';
+                    facts.extension = { name, schema: null, action: 'drop' };
+                }
+            }
+            break;
+        case 'AlterTableStmt': {
+            if (node.relation) {
+                facts.creates.push(qn(node.relation.schemaname ?? null, node.relation.relname));
+            }
+            const cmds = node.cmds ?? [];
+            for (const cmd of cmds) {
+                const subtype = cmd?.AlterTableCmd?.subtype;
+                if (subtype === 'AT_EnableRowSecurity' || subtype === 'AT_ForceRowSecurity' ||
+                    subtype === 'AT_DisableRowSecurity' || subtype === 'AT_NoForceRowSecurity') {
+                    facts.kind = 'rls_enable';
+                    facts.securityRelevant = true;
+                }
+                else if (subtype === 'AT_AddConstraint') {
+                    const contype = cmd?.AlterTableCmd?.def?.Constraint?.contype;
+                    facts.kind = contype === 'CONSTR_FOREIGN' ? 'fk_constraint' : 'constraint';
+                }
+                else if (subtype === 'AT_ChangeOwner') {
+                    facts.securityRelevant = true;
+                    const owner = cmd?.AlterTableCmd?.newowner?.rolename;
+                    if (owner && !facts.roles.includes(owner))
+                        facts.roles.push(owner);
+                }
+            }
+            break;
+        }
+        case 'InsertStmt':
+        case 'UpdateStmt':
+        case 'DeleteStmt':
+            if (node.relation) {
+                facts.creates.push(qn(node.relation.schemaname ?? null, node.relation.relname));
+            }
+            break;
+        default:
+            break;
+    }
+    collectRoles(node, facts.roles);
+    return facts;
+}
+/** Read a `CreateFunctionStmt` DefElem option's scalar/list value. */
+function functionOption(node, defname) {
+    for (const opt of node.options ?? []) {
+        if (opt?.DefElem?.defname === defname)
+            return opt.DefElem.arg;
+    }
+    return undefined;
+}
+/**
+ * Collect references from a `LANGUAGE sql` function body supplied as a string
+ * literal (`AS $$ ... $$`). That body is an opaque String node the AST walker
+ * never parses, so — mirroring the schema transformer's body rewrite — parse
+ * it standalone and walk each statement with the facts visitor. The standard
+ * `BEGIN ATOMIC` / `RETURN` `sql_body` form is already part of the AST and is
+ * covered by the outer walk, so only the string form needs this.
+ */
+function collectSqlBodyReferences(node, facts) {
+    const language = functionOption(node, 'language')?.String?.sval;
+    if (typeof language !== 'string' || language.toLowerCase() !== 'sql')
+        return;
+    const asArg = functionOption(node, 'as');
+    const items = asArg?.List?.items ?? [];
+    const body = items[0]?.String?.sval;
+    if (typeof body !== 'string')
+        return;
+    try {
+        const stmts = parseSql(body)?.stmts ?? [];
+        const visitor = createFactsVisitor(facts, facts.bodyReferences);
+        for (const stmt of stmts) {
+            if (stmt?.stmt)
+                walkSqlAst(stmt.stmt, visitor);
+        }
+    }
+    catch {
+        // A non-parseable body (C symbol name, etc.) contributes no references.
+    }
+}
+/**
+ * Classify each top-level statement in a SQL script into {@link StatementFacts}.
+ *
+ * Uses the same parser stack as the schema transformer (pgsql AST walk plus
+ * hydrated PL/pgSQL body walk), so references inside function bodies are
+ * included. The input SQL is never modified.
+ */
+export function classifyStatements(sql) {
+    const allFacts = [];
+    transformSync(sql, (ctx) => {
+        const stmts = ctx.sql?.stmts ?? [];
+        for (const stmt of stmts) {
+            const stmtNode = stmt?.stmt;
+            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) {
+                facts.stmt = stmtNode;
+                walkSqlAst(stmtNode, createFactsVisitor(facts));
+            }
+            if (nodeTag === 'CreateFunctionStmt') {
+                collectSqlBodyReferences(node, facts);
+            }
+            allFacts.push(facts);
+        }
+        for (const fn of ctx.functions ?? []) {
+            const facts = allFacts[fn.stmtIndex];
+            if (!facts || !fn.plpgsql?.hydrated)
+                continue;
+            // Refs already found outside the body (signature types, defaults)
+            // constrain deploy order and are not body-only.
+            const outer = new Set(facts.references.map(r => `${r.schema ?? '?'}.${r.name}`));
+            walkPlpgsqlAst(fn.plpgsql.hydrated, {
+                PLpgSQL_stmt_dynexecute: () => { facts.dynamicSql = true; },
+                PLpgSQL_stmt_dynfors: () => { facts.dynamicSql = true; }
+            }, {
+                walkSqlExpressions: true,
+                sqlVisitor: createFactsVisitor(facts, facts.bodyReferences)
+            });
+            facts.bodyReferences = facts.bodyReferences.filter(r => !outer.has(`${r.schema ?? '?'}.${r.name}`));
+        }
+    }, { hydrate: true });
+    for (const facts of allFacts) {
+        const selfRef = (r) => facts.creates.some(c => c.schema === r.schema && c.name === r.name);
+        facts.references = facts.references.filter(r => !selfRef(r));
+        facts.bodyReferences = facts.bodyReferences.filter(r => !selfRef(r));
+        facts.referencedSchemas = [...new Set(facts.references.map(r => r.schema).filter(Boolean))];
+    }
+    return allFacts;
+}

package/esm/index.js

@@ -0,0 +1 @@
+export { classifyStatements } from './facts';

package/facts.d.ts

@@ -0,0 +1,128 @@
+/**
+ * A (possibly schema-qualified) object name extracted from a statement.
+ */
+export interface QualifiedName {
+    schema: string | null;
+    name: string;
+}
+/**
+ * Coarse statement classification used for tier/package sorting.
+ */
+export type StatementKind = 'schema' | 'extension' | 'table' | 'view' | 'index' | 'type' | 'function' | 'trigger' | 'policy' | 'grant' | 'rls_enable' | 'fk_constraint' | 'constraint' | 'comment' | 'seed_dml' | 'other';
+/**
+ * The action a statement performs on a PostgreSQL extension.
+ *
+ * - `create` — `CREATE EXTENSION` (`CreateExtensionStmt`).
+ * - `set_schema` — `ALTER EXTENSION ... SET SCHEMA` (`AlterObjectSchemaStmt`
+ *   with `objectType: OBJECT_EXTENSION`); only succeeds for relocatable
+ *   extensions, so it is surfaced as its own action.
+ * - `drop` — `DROP EXTENSION` (`DropStmt` with `removeType: OBJECT_EXTENSION`).
+ */
+export type ExtensionAction = 'create' | 'set_schema' | 'drop';
+/**
+ * Facts about an extension-level statement. Unlike ordinary objects, an
+ * extension is installed into exactly one schema and its member objects are
+ * renamed with it, so the relevant fact is the extension name plus the schema
+ * it is (being) placed in.
+ */
+export interface ExtensionFact {
+    /** The extension name (`CREATE EXTENSION <name>`). */
+    name: string;
+    /**
+     * The schema the statement places the extension in, or `null` when none is
+     * specified (`CREATE EXTENSION <name>` with no `SCHEMA` clause installs into
+     * the current default — typically `public` or the extension's fixed schema).
+     * `DROP EXTENSION` carries no schema.
+     */
+    schema: string | null;
+    /** Which extension operation this statement performs. */
+    action: ExtensionAction;
+    /** `CREATE EXTENSION IF NOT EXISTS`. */
+    ifNotExists?: boolean;
+}
+/**
+ * AST-derived facts about a single top-level SQL statement.
+ *
+ * Read-only: classification never modifies the statement. Facts are the
+ * substrate for classifier-driven slicing (schema / functionality / security
+ * tiers) — replacing path/name-glob decisions with computed properties like
+ * "this trigger function references billing".
+ */
+export interface StatementFacts {
+    /** Coarse category of the statement. */
+    kind: StatementKind;
+    /** The raw parser node tag (e.g. `CreateStmt`, `CreatePolicyStmt`). */
+    nodeTag: string;
+    /** Objects this statement creates or directly targets. */
+    creates: QualifiedName[];
+    /**
+     * Schema-qualified objects this statement references — tables, functions
+     * and types reached anywhere in the statement, including PL/pgSQL bodies.
+     * Unqualified references are omitted (they resolve via search_path and
+     * carry no cross-schema information).
+     */
+    references: QualifiedName[];
+    /**
+     * The subset of `references` reached only inside a PL/pgSQL body. These
+     * are late-binding: Postgres resolves them at call time, not at CREATE
+     * time, so they do not constrain deploy order (and legitimately form
+     * recursion cycles between functions).
+     */
+    bodyReferences: QualifiedName[];
+    /** Distinct schemas reached by `references`. */
+    referencedSchemas: string[];
+    /** Role names granted to, owning, or bound by this statement. */
+    roles: string[];
+    /**
+     * For extension-level statements (`kind: 'extension'`): the extension being
+     * created, relocated, or dropped. Absent for every other statement.
+     */
+    extension?: ExtensionFact;
+    /** Foreign-key target tables (from column/table FK constraints). */
+    fkTargets: QualifiedName[];
+    /**
+     * Whether the statement is part of the security surface: policies, grants,
+     * RLS enable/force, security labels, ownership.
+     */
+    securityRelevant: boolean;
+    /** For functions: declared with SECURITY DEFINER. */
+    securityDefiner: boolean;
+    /**
+     * For functions: the body executes dynamic SQL (EXECUTE / EXECUTE ... USING
+     * / FOR ... IN EXECUTE). Analogous to `eval` — references inside the
+     * dynamic string are invisible to the AST, so edges from this statement
+     * 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;
+    /**
+     * The raw parsed statement node (`{ CreateStmt: {...} }` etc.), exactly as
+     * the parser produced it. Facts are still read-only — the node is carried
+     * so consumers like `revertFor`/`verifyFor` can derive inverse or
+     * existence-check statements without a second parse. Absent only for
+     * facts constructed by hand.
+     */
+    stmt?: Record<string, any>;
+}
+/** 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}.
+ *
+ * Uses the same parser stack as the schema transformer (pgsql AST walk plus
+ * hydrated PL/pgSQL body walk), so references inside function bodies are
+ * included. The input SQL is never modified.
+ */
+export declare function classifyStatements(sql: string): StatementFacts[];

package/facts.js

@@ -0,0 +1,396 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyStatements = classifyStatements;
+const traverse_1 = require("@pgsql/traverse");
+const plpgsql_parser_1 = require("plpgsql-parser");
+const SECURITY_TAGS = new Set([
+    'CreatePolicyStmt',
+    'AlterPolicyStmt',
+    'GrantStmt',
+    'GrantRoleStmt',
+    'AlterDefaultPrivilegesStmt',
+    'SecLabelStmt',
+    'AlterOwnerStmt',
+    'CreateRoleStmt',
+    'AlterRoleStmt'
+]);
+const KIND_BY_TAG = {
+    CreateSchemaStmt: 'schema',
+    CreateExtensionStmt: 'extension',
+    CreateStmt: 'table',
+    ViewStmt: 'view',
+    IndexStmt: 'index',
+    CompositeTypeStmt: 'type',
+    CreateEnumStmt: 'type',
+    CreateDomainStmt: 'type',
+    CreateRangeStmt: 'type',
+    DefineStmt: 'type',
+    CreateFunctionStmt: 'function',
+    CreateTrigStmt: 'trigger',
+    CreateEventTrigStmt: 'trigger',
+    CreatePolicyStmt: 'policy',
+    AlterPolicyStmt: 'policy',
+    GrantStmt: 'grant',
+    GrantRoleStmt: 'grant',
+    AlterDefaultPrivilegesStmt: 'grant',
+    CommentStmt: 'comment',
+    InsertStmt: 'seed_dml',
+    UpdateStmt: 'seed_dml',
+    DeleteStmt: 'seed_dml'
+};
+function qn(schema, name) {
+    return { schema: schema ?? null, name };
+}
+/**
+ * Read the `SCHEMA <name>` clause of a `CreateExtensionStmt` from its options
+ * (`{ DefElem: { defname: 'schema', arg: { String: { sval } } } }`), or `null`
+ * when the statement specifies no schema.
+ */
+function extensionSchemaOption(options) {
+    if (!Array.isArray(options))
+        return null;
+    for (const opt of options) {
+        const def = opt?.DefElem;
+        if (def?.defname === 'schema') {
+            const sval = def.arg?.String?.sval;
+            return typeof sval === 'string' ? sval : null;
+        }
+    }
+    return null;
+}
+function nameListToQualified(names) {
+    if (!Array.isArray(names) || names.length === 0)
+        return null;
+    const parts = names
+        .map((n) => n?.String?.sval)
+        .filter((s) => typeof s === 'string');
+    if (parts.length === 0)
+        return null;
+    if (parts.length === 1)
+        return qn(null, parts[0]);
+    return qn(parts[parts.length - 2], parts[parts.length - 1]);
+}
+function isCatalogSchema(schema) {
+    return schema === 'pg_catalog' || schema === 'information_schema';
+}
+function pushRef(refs, ref) {
+    if (!ref || !ref.schema || isCatalogSchema(ref.schema))
+        return;
+    if (refs.some(r => r.schema === ref.schema && r.name === ref.name))
+        return;
+    refs.push(ref);
+}
+function collectRoles(node, roles) {
+    const push = (role) => {
+        if (typeof role === 'string' && role.length > 0 && !roles.includes(role)) {
+            roles.push(role);
+        }
+    };
+    if (Array.isArray(node?.grantees)) {
+        for (const g of node.grantees)
+            push(g?.RoleSpec?.rolename);
+    }
+    if (Array.isArray(node?.roles)) {
+        for (const r of node.roles)
+            push(r?.RoleSpec?.rolename);
+    }
+    push(node?.newowner?.rolename);
+    push(node?.role?.rolename);
+}
+/**
+ * Create a read-only visitor that accumulates references, roles and FK
+ * targets into the provided facts object.
+ */
+function createFactsVisitor(facts, bodyRefs) {
+    const push = (ref) => {
+        pushRef(facts.references, ref);
+        if (bodyRefs)
+            pushRef(bodyRefs, ref);
+    };
+    return {
+        RangeVar: (path) => {
+            const node = path.node;
+            if (node.schemaname) {
+                push(qn(node.schemaname, node.relname));
+            }
+        },
+        FuncCall: (path) => {
+            push(nameListToQualified(path.node.funcname));
+        },
+        TypeName: (path) => {
+            push(nameListToQualified(path.node.names));
+        },
+        ColumnRef: (path) => {
+            // schema.table.column references carry cross-schema information
+            const fields = path.node.fields;
+            if (Array.isArray(fields) && fields.length >= 3) {
+                const parts = fields
+                    .map((f) => f?.String?.sval)
+                    .filter((s) => typeof s === 'string');
+                if (parts.length >= 3) {
+                    push(qn(parts[0], parts[1]));
+                }
+            }
+        },
+        Constraint: (path) => {
+            const node = path.node;
+            if (node.contype === 'CONSTR_FOREIGN' && node.pktable) {
+                const target = qn(node.pktable.schemaname ?? null, node.pktable.relname);
+                if (!facts.fkTargets.some(t => t.schema === target.schema && t.name === target.name)) {
+                    facts.fkTargets.push(target);
+                }
+                if (target.schema)
+                    pushRef(facts.references, target);
+            }
+        }
+    };
+}
+function classifyOne(nodeTag, node) {
+    const facts = {
+        kind: KIND_BY_TAG[nodeTag] ?? 'other',
+        nodeTag,
+        creates: [],
+        references: [],
+        referencedSchemas: [],
+        roles: [],
+        fkTargets: [],
+        bodyReferences: [],
+        securityRelevant: SECURITY_TAGS.has(nodeTag),
+        securityDefiner: false,
+        dynamicSql: false,
+        span: { start: 0, len: 0 }
+    };
+    switch (nodeTag) {
+        case 'CreateSchemaStmt':
+            facts.creates.push(qn(null, node.schemaname));
+            break;
+        case 'CreateExtensionStmt':
+            facts.extension = {
+                name: node.extname,
+                schema: extensionSchemaOption(node.options),
+                action: 'create',
+                ifNotExists: node.if_not_exists === true
+            };
+            break;
+        case 'CreateStmt':
+        case 'ViewStmt': {
+            const rel = nodeTag === 'ViewStmt' ? node.view : node.relation;
+            if (rel)
+                facts.creates.push(qn(rel.schemaname ?? null, rel.relname));
+            break;
+        }
+        case 'IndexStmt':
+            if (node.relation) {
+                facts.creates.push(qn(node.relation.schemaname ?? null, node.idxname ?? node.relation.relname));
+            }
+            break;
+        case 'CreateFunctionStmt': {
+            const name = nameListToQualified(node.funcname);
+            if (name)
+                facts.creates.push(name);
+            for (const opt of node.options ?? []) {
+                const def = opt?.DefElem;
+                if (def?.defname === 'security' && def?.arg?.Boolean?.boolval === true) {
+                    facts.securityDefiner = true;
+                }
+            }
+            break;
+        }
+        case 'CreateTrigStmt':
+            if (node.relation) {
+                // Trigger names are only unique per table; qualify with the table.
+                facts.creates.push(qn(node.relation.schemaname ?? null, `${node.relation.relname}.${node.trigname}`));
+            }
+            pushRef(facts.references, nameListToQualified(node.funcname));
+            break;
+        case 'CreatePolicyStmt':
+        case 'AlterPolicyStmt':
+            if (node.table) {
+                // Policy names are only unique per table; qualify with the table.
+                facts.creates.push(qn(node.table.schemaname ?? null, `${node.table.relname}.${node.policy_name}`));
+                // The guarded table lives on `node.table`; the generic RangeVar walker
+                // does not descend into it, so capture the reference explicitly.
+                if (node.table.schemaname) {
+                    pushRef(facts.references, qn(node.table.schemaname, node.table.relname));
+                }
+            }
+            break;
+        case 'CreateSeqStmt':
+            if (node.sequence) {
+                facts.creates.push(qn(node.sequence.schemaname ?? null, node.sequence.relname));
+            }
+            break;
+        case 'CompositeTypeStmt':
+            if (node.typevar) {
+                facts.creates.push(qn(node.typevar.schemaname ?? null, node.typevar.relname));
+            }
+            break;
+        case 'CreateEnumStmt':
+        case 'CreateRangeStmt': {
+            const name = nameListToQualified(node.typeName);
+            if (name)
+                facts.creates.push(name);
+            break;
+        }
+        case 'CreateDomainStmt': {
+            // `typeName` on a domain is the base type; the name is `domainname`.
+            const name = nameListToQualified(node.domainname);
+            if (name)
+                facts.creates.push(name);
+            break;
+        }
+        case 'AlterObjectSchemaStmt':
+            // ALTER EXTENSION <name> SET SCHEMA <newschema>. Other object types
+            // (TABLE/TYPE/FUNCTION ... SET SCHEMA) keep their default classification.
+            if (node.objectType === 'OBJECT_EXTENSION') {
+                const name = node.object?.String?.sval;
+                if (typeof name === 'string') {
+                    facts.kind = 'extension';
+                    facts.extension = {
+                        name,
+                        schema: typeof node.newschema === 'string' ? node.newschema : null,
+                        action: 'set_schema'
+                    };
+                }
+            }
+            break;
+        case 'DropStmt':
+            // DROP EXTENSION <name> [, ...]. Extension names are bare String nodes.
+            // Other DROP object types keep their default classification. When
+            // several extensions are dropped in one statement the first names the
+            // fact; the full list stays available via the raw node.
+            if (node.removeType === 'OBJECT_EXTENSION' && Array.isArray(node.objects)) {
+                const name = node.objects[0]?.String?.sval;
+                if (typeof name === 'string') {
+                    facts.kind = 'extension';
+                    facts.extension = { name, schema: null, action: 'drop' };
+                }
+            }
+            break;
+        case 'AlterTableStmt': {
+            if (node.relation) {
+                facts.creates.push(qn(node.relation.schemaname ?? null, node.relation.relname));
+            }
+            const cmds = node.cmds ?? [];
+            for (const cmd of cmds) {
+                const subtype = cmd?.AlterTableCmd?.subtype;
+                if (subtype === 'AT_EnableRowSecurity' || subtype === 'AT_ForceRowSecurity' ||
+                    subtype === 'AT_DisableRowSecurity' || subtype === 'AT_NoForceRowSecurity') {
+                    facts.kind = 'rls_enable';
+                    facts.securityRelevant = true;
+                }
+                else if (subtype === 'AT_AddConstraint') {
+                    const contype = cmd?.AlterTableCmd?.def?.Constraint?.contype;
+                    facts.kind = contype === 'CONSTR_FOREIGN' ? 'fk_constraint' : 'constraint';
+                }
+                else if (subtype === 'AT_ChangeOwner') {
+                    facts.securityRelevant = true;
+                    const owner = cmd?.AlterTableCmd?.newowner?.rolename;
+                    if (owner && !facts.roles.includes(owner))
+                        facts.roles.push(owner);
+                }
+            }
+            break;
+        }
+        case 'InsertStmt':
+        case 'UpdateStmt':
+        case 'DeleteStmt':
+            if (node.relation) {
+                facts.creates.push(qn(node.relation.schemaname ?? null, node.relation.relname));
+            }
+            break;
+        default:
+            break;
+    }
+    collectRoles(node, facts.roles);
+    return facts;
+}
+/** Read a `CreateFunctionStmt` DefElem option's scalar/list value. */
+function functionOption(node, defname) {
+    for (const opt of node.options ?? []) {
+        if (opt?.DefElem?.defname === defname)
+            return opt.DefElem.arg;
+    }
+    return undefined;
+}
+/**
+ * Collect references from a `LANGUAGE sql` function body supplied as a string
+ * literal (`AS $$ ... $$`). That body is an opaque String node the AST walker
+ * never parses, so — mirroring the schema transformer's body rewrite — parse
+ * it standalone and walk each statement with the facts visitor. The standard
+ * `BEGIN ATOMIC` / `RETURN` `sql_body` form is already part of the AST and is
+ * covered by the outer walk, so only the string form needs this.
+ */
+function collectSqlBodyReferences(node, facts) {
+    const language = functionOption(node, 'language')?.String?.sval;
+    if (typeof language !== 'string' || language.toLowerCase() !== 'sql')
+        return;
+    const asArg = functionOption(node, 'as');
+    const items = asArg?.List?.items ?? [];
+    const body = items[0]?.String?.sval;
+    if (typeof body !== 'string')
+        return;
+    try {
+        const stmts = (0, plpgsql_parser_1.parseSql)(body)?.stmts ?? [];
+        const visitor = createFactsVisitor(facts, facts.bodyReferences);
+        for (const stmt of stmts) {
+            if (stmt?.stmt)
+                (0, traverse_1.walkSqlAst)(stmt.stmt, visitor);
+        }
+    }
+    catch {
+        // A non-parseable body (C symbol name, etc.) contributes no references.
+    }
+}
+/**
+ * Classify each top-level statement in a SQL script into {@link StatementFacts}.
+ *
+ * Uses the same parser stack as the schema transformer (pgsql AST walk plus
+ * hydrated PL/pgSQL body walk), so references inside function bodies are
+ * included. The input SQL is never modified.
+ */
+function classifyStatements(sql) {
+    const allFacts = [];
+    (0, plpgsql_parser_1.transformSync)(sql, (ctx) => {
+        const stmts = ctx.sql?.stmts ?? [];
+        for (const stmt of stmts) {
+            const stmtNode = stmt?.stmt;
+            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) {
+                facts.stmt = stmtNode;
+                (0, traverse_1.walkSqlAst)(stmtNode, createFactsVisitor(facts));
+            }
+            if (nodeTag === 'CreateFunctionStmt') {
+                collectSqlBodyReferences(node, facts);
+            }
+            allFacts.push(facts);
+        }
+        for (const fn of ctx.functions ?? []) {
+            const facts = allFacts[fn.stmtIndex];
+            if (!facts || !fn.plpgsql?.hydrated)
+                continue;
+            // Refs already found outside the body (signature types, defaults)
+            // constrain deploy order and are not body-only.
+            const outer = new Set(facts.references.map(r => `${r.schema ?? '?'}.${r.name}`));
+            (0, plpgsql_parser_1.walkPlpgsqlAst)(fn.plpgsql.hydrated, {
+                PLpgSQL_stmt_dynexecute: () => { facts.dynamicSql = true; },
+                PLpgSQL_stmt_dynfors: () => { facts.dynamicSql = true; }
+            }, {
+                walkSqlExpressions: true,
+                sqlVisitor: createFactsVisitor(facts, facts.bodyReferences)
+            });
+            facts.bodyReferences = facts.bodyReferences.filter(r => !outer.has(`${r.schema ?? '?'}.${r.name}`));
+        }
+    }, { hydrate: true });
+    for (const facts of allFacts) {
+        const selfRef = (r) => facts.creates.some(c => c.schema === r.schema && c.name === r.name);
+        facts.references = facts.references.filter(r => !selfRef(r));
+        facts.bodyReferences = facts.bodyReferences.filter(r => !selfRef(r));
+        facts.referencedSchemas = [...new Set(facts.references.map(r => r.schema).filter(Boolean))];
+    }
+    return allFacts;
+}

package/index.d.ts

@@ -0,0 +1,2 @@
+export type { ExtensionAction, ExtensionFact, QualifiedName, StatementFacts, StatementKind, StatementSpan, } from './facts';
+export { classifyStatements } from './facts';

package/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyStatements = void 0;
+var facts_1 = require("./facts");
+Object.defineProperty(exports, "classifyStatements", { enumerable: true, get: function () { return facts_1.classifyStatements; } });

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@pgsql/semantics",
+  "version": "18.1.0",
+  "author": "Constructive <developers@constructive.io>",
+  "description": "AST-derived semantic facts for PostgreSQL statements: what each statement creates, references, and touches",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "homepage": "https://github.com/constructive-io/pgsql-parser",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/pgsql-parser"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/pgsql-parser/issues"
+  },
+  "scripts": {
+    "copy": "makage assets",
+    "clean": "makage clean dist",
+    "prepublishOnly": "npm run build",
+    "build": "npm run clean && tsc && tsc -p tsconfig.esm.json && npm run copy",
+    "build:dev": "npm run clean && tsc --declarationMap && tsc -p tsconfig.esm.json && npm run copy",
+    "lint": "eslint . --fix",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "dependencies": {
+    "@pgsql/traverse": "18.7.1",
+    "plpgsql-parser": "18.5.1"
+  },
+  "devDependencies": {
+    "makage": "^0.1.8"
+  },
+  "keywords": [
+    "sql",
+    "postgres",
+    "postgresql",
+    "pg",
+    "ast",
+    "semantics",
+    "facts",
+    "classify",
+    "plpgsql"
+  ],
+  "gitHead": "0fba1b6faf8067bfd5f1591656c2a90f77c280b0"
+}