feat(semantics): extract statement-classification facts into @pgsql/semantics

.github/workflows/run-tests.yaml

@@ -24,6 +24,7 @@ jobs:
           - '@pgsql/quotes'
           - '@pgsql/transform-ast'
           - '@pgsql/traverse'
+          - '@pgsql/semantics'
           - '@pgsql/transform'
           - '@pgsql/scripts'
     steps:

packages/semantics/.gitignore

@@ -0,0 +1,29 @@
+
+
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+*.tsbuildinfo
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+
+# Coverage
+coverage/
+.nyc_output/
+
+# Temp files
+*.tmp
+*.temp
+.cache/

packages/semantics/README.md

@@ -0,0 +1,53 @@
+# @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`.

packages/semantics/jest.config.js

@@ -0,0 +1,10 @@
+module.exports = {
+  forceExit: true,
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.tsx?$': 'ts-jest'
+  },
+  testMatch: ['**/__tests__/**/*.test.ts'],
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  testTimeout: 30000
+};

packages/semantics/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@pgsql/semantics",
+  "version": "18.0.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": "workspace:*",
+    "plpgsql-parser": "workspace:*"
+  },
+  "devDependencies": {
+    "makage": "^0.1.8"
+  },
+  "keywords": [
+    "sql",
+    "postgres",
+    "postgresql",
+    "pg",
+    "ast",
+    "semantics",
+    "facts",
+    "classify",
+    "plpgsql"
+  ]
+}