graphile-scoped-introspection 0.2.0

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Dan Lynch <pyramation@gmail.com>
+Copyright (c) 2025 Constructive <developers@constructive.io>
+Copyright (c) 2020-present, Interweb, Inc.
+
+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,141 @@
+# graphile-scoped-introspection
+
+An opt-in Graphile plugin that scopes PostgreSQL catalog introspection to the
+configured service schemas and their required dependency closure.
+
+```ts
+import { ScopedIntrospectionPreset } from 'graphile-scoped-introspection';
+
+const preset = {
+  extends: [ScopedIntrospectionPreset],
+  gather: {
+    pgScopedIntrospection: {
+      main: true,
+    },
+  },
+  pgServices: [
+    {
+      // standard Graphile PgService fields
+      name: 'main',
+      schemas: ['app_public'],
+    },
+  ],
+};
+```
+
+With `main: true`, the scoped query uses `catalogTypes: 'all'`: it retains the
+dependency closure needed by the selected schemas and all `pg_catalog` types.
+It does not expose every user schema or every catalog object. Services omitted
+from `gather.pgScopedIntrospection`, or mapped to `false`, use stock
+introspection.
+
+Use an options object when the dependency-only policy or extension capability
+metadata is needed:
+
+```ts
+gather: {
+  pgScopedIntrospection: {
+    main: {
+      catalogTypes: 'dependency-closure',
+      capabilityExtensions: ['pg_trgm'],
+    },
+  },
+},
+```
+
+The query follows real PostgreSQL dependencies across schemas automatically;
+there is no dependency-schema allowlist. `capabilityExtensions` records the
+requested extension capability metadata and does not add user schemas to the
+scope. Unknown service names fail validation even when mapped to `false`.
+
+The package atomically replaces `PgIntrospectionPlugin` only when its preset
+is installed. `true` enables scoped introspection with defaults; an options
+object selects the catalog type policy and optional extension capability
+metadata.
+
+The scoped SQL is CNC-owned and parameterized. It is adapted from the MIT
+licensed `pg-introspection@1.0.1` query and does not patch, import private
+subpaths from, or rewrite the installed upstream package.
+
+Use `makeSchemaScopedIntrospectionPlan` when the query result will be parsed
+and validated. It returns the normalized schema and option scope alongside the
+parameterized query; `makeSchemaScopedIntrospectionQuery` remains available for
+callers that only need the SQL.
+
+Database clients use the normal `@dataplan/pg` checkout lifecycle and return
+to the pool after each query. Applications remain responsible for calling
+`PgService.release()` during final shutdown.
+
+---
+
+## Education and Tutorials
+
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
+Get started with modular databases in minutes. Install prerequisites and deploy your first module.
+
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
+Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
+
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
+Master the workflow for adding, organizing, and managing database changes with pgpm.
+
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
+Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
+
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
+Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
+
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
+Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
+
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
+Common issues and solutions for pgpm, PostgreSQL, and testing.
+
+## Related Constructive Tooling
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pglite-test](https://github.com/constructive-io/constructive/tree/main/postgres/pglite-test): **🪶 Drop-in pgsql-test replacement backed by PGlite** — in-process Postgres, no server required, instance-per-suite isolation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+* [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
+
+### 🧠 Parsing & AST
+
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+### 📚 Documentation & Skills
+
+* [constructive-skills](https://github.com/constructive-io/constructive-skills): **📖 Platform documentation and AI agent skills** — feature catalog, blueprint reference, SDK guides (i18n, billing, limits, events, uploads, security, entities, search, AI), and deployment guides.
+
+Install skills for AI coding agents:
+
+```bash
+# All platform skills (security, blueprints, codegen, billing, etc.)
+npx skills add constructive-io/constructive-skills
+
+# Individual repo skills (pgpm, testing, CLI, search, etc.)
+npx skills add https://github.com/constructive-io/constructive --skill pgpm
+npx skills add https://github.com/constructive-io/constructive --skill constructive-testing
+```
+
+## Credits
+
+**🛠 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).**
+
+## 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 this 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 code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/esm/index.d.ts

@@ -0,0 +1,4 @@
+export type { PgScopedIntrospectionConfig, PgScopedIntrospectionServiceConfig, SchemaScopedIntrospectionOptions, ScopedCatalogTypes, } from './plugin';
+export { ConstructivePgIntrospectionPlugin, ScopedIntrospectionPreset, scopedIntrospectionUpstreamContract, } from './plugin';
+export type { SchemaScopedIntrospectionPlan, SchemaScopedIntrospectionQuery, SchemaScopedIntrospectionScope, } from './scoped-introspection-query';
+export { makeSchemaScopedIntrospectionPlan, makeSchemaScopedIntrospectionQuery, validateSchemaScopedIntrospection, } from './scoped-introspection-query';

package/esm/index.js

@@ -0,0 +1,2 @@
+export { ConstructivePgIntrospectionPlugin, ScopedIntrospectionPreset, scopedIntrospectionUpstreamContract, } from './plugin';
+export { makeSchemaScopedIntrospectionPlan, makeSchemaScopedIntrospectionQuery, validateSchemaScopedIntrospection, } from './scoped-introspection-query';

package/esm/plugin.d.ts

@@ -0,0 +1,21 @@
+import 'graphile-build';
+import type { GraphileConfig } from 'graphile-config';
+export type { PgScopedIntrospectionConfig, PgScopedIntrospectionServiceConfig, SchemaScopedIntrospectionOptions, ScopedCatalogTypes, } from '@constructive-io/graphql-types';
+/**
+ * CNC-owned atomic replacement for graphile-build-pg's introspection plugin.
+ * Stock-only configurations delegate to the upstream helper unchanged.
+ */
+export declare const ConstructivePgIntrospectionPlugin: GraphileConfig.Plugin;
+/** Disable upstream atomically before installing the CNC replacement. */
+export declare const ScopedIntrospectionPreset: GraphileConfig.Preset;
+export declare const scopedIntrospectionUpstreamContract: Readonly<{
+    package: "graphile-build-pg";
+    version: "5.1.3";
+    pluginName: keyof GraphileConfig.Plugins;
+    namespace: keyof GraphileConfig.GatherHelpers;
+    hasInitialCache: boolean;
+    hasInitialState: boolean;
+    hasWatch: boolean;
+    helperNames: string[];
+    hookNames: string[];
+}>;

package/esm/plugin.js

@@ -0,0 +1,212 @@
+import 'graphile-build';
+import { withPgClientFromPgService } from '@dataplan/pg';
+import { PgIntrospectionPlugin, version as graphileBuildPgVersion, } from 'graphile-build-pg';
+import { makeIntrospectionQuery, parseIntrospectionResults, } from 'pg-introspection';
+import { makeSchemaScopedIntrospectionPlan, validateSchemaScopedIntrospection, } from './scoped-introspection-query';
+const upstreamGather = PgIntrospectionPlugin.gather;
+const upstreamHelpers = upstreamGather?.helpers;
+const upstreamGetIntrospection = upstreamHelpers?.getIntrospection;
+const SUPPORTED_GRAPHILE_BUILD_PG_VERSION = '5.1.3';
+if (graphileBuildPgVersion !== SUPPORTED_GRAPHILE_BUILD_PG_VERSION) {
+    throw new Error(`Unsupported graphile-build-pg introspection contract: expected ${SUPPORTED_GRAPHILE_BUILD_PG_VERSION}, received ${graphileBuildPgVersion}`);
+}
+if (!upstreamGather || !upstreamHelpers || !upstreamGetIntrospection) {
+    throw new Error('graphile-build-pg PgIntrospectionPlugin no longer exposes the expected gather contract');
+}
+function getIntrospectionQuery(pgService, config) {
+    if (config === undefined || config === false) {
+        return {
+            query: { text: makeIntrospectionQuery() },
+            scopedPlan: null,
+        };
+    }
+    const options = config === true ? {} : config;
+    const scopedPlan = makeSchemaScopedIntrospectionPlan(pgService.schemas ?? [], options);
+    return {
+        query: scopedPlan.query,
+        scopedPlan,
+    };
+}
+function assertScopedIntrospectionServices(pgServices, options) {
+    if (options === undefined)
+        return;
+    if (options === null ||
+        typeof options !== 'object' ||
+        Array.isArray(options)) {
+        throw new Error('pgScopedIntrospection must be an object keyed by PostgreSQL service name');
+    }
+    const serviceNames = new Set((pgServices ?? []).map((pgService) => pgService.name));
+    const unknownServiceNames = Object.keys(options).filter((serviceName) => !serviceNames.has(serviceName));
+    if (unknownServiceNames.length > 0) {
+        throw new Error(`Schema-scoped introspection configured for unknown PostgreSQL service(s): ${unknownServiceNames.join(', ')}`);
+    }
+    for (const [serviceName, config] of Object.entries(options)) {
+        if (config !== true &&
+            config !== false &&
+            (config === null ||
+                typeof config !== 'object' ||
+                Array.isArray(config))) {
+            throw new Error(`Schema-scoped introspection configuration for service '${serviceName}' must be true, false, or an options object`);
+        }
+    }
+}
+// Adapted from graphile-build-pg@5.1.3
+// dist/plugins/PgIntrospectionPlugin.js. The upstream function is private, so
+// mixed/scoped services must retain this service validation/query seam locally.
+async function introspectPgServices(pgServices, scopedIntrospection) {
+    assertScopedIntrospectionServices(pgServices, scopedIntrospection);
+    if (!pgServices)
+        return [];
+    const seenNames = new Map();
+    const seenPgSettingsKeys = new Map();
+    const seenWithPgClientKeys = new Map();
+    return Promise.all(pgServices.map(async (pgService, i) => {
+        const { name, pgSettingsKey, withPgClientKey } = pgService;
+        if (!name)
+            throw new Error(`pgServices[${i}] has no name`);
+        if (!withPgClientKey) {
+            throw new Error(`pgServices[${i}] has no withPgClientKey`);
+        }
+        const duplicateName = seenNames.get(name);
+        if (duplicateName !== undefined) {
+            throw new Error(`pgServices[${i}] has the same name as pgServices[${duplicateName}] (${JSON.stringify(name)})`);
+        }
+        seenNames.set(name, i);
+        const duplicateClientKey = seenWithPgClientKeys.get(withPgClientKey);
+        if (duplicateClientKey !== undefined) {
+            throw new Error(`pgServices[${i}] has the same withPgClientKey as pgServices[${duplicateClientKey}] (${JSON.stringify(withPgClientKey)})`);
+        }
+        seenWithPgClientKeys.set(withPgClientKey, i);
+        if (pgSettingsKey) {
+            const duplicateSettingsKey = seenPgSettingsKeys.get(pgSettingsKey);
+            if (duplicateSettingsKey !== undefined) {
+                throw new Error(`pgServices[${i}] has the same pgSettingsKey as pgServices[${duplicateSettingsKey}] (${JSON.stringify(pgSettingsKey)})`);
+            }
+            seenPgSettingsKeys.set(pgSettingsKey, i);
+        }
+        const { query, scopedPlan } = getIntrospectionQuery(pgService, scopedIntrospection?.[name]);
+        const result = await withPgClientFromPgService(pgService, pgService.pgSettingsForIntrospection ?? null, (client) => client.query(query));
+        const [row] = result.rows;
+        if (!row)
+            throw new Error('Introspection failed');
+        return {
+            pgService,
+            introspectionText: row.introspection,
+            scopedPlan,
+        };
+    }));
+}
+async function announceIntrospection(info, introspections) {
+    await Promise.all(introspections.map(async ({ introspection, pgService }) => {
+        const announce = async (eventName, entities) => {
+            await Promise.all(entities.map((entity) => info.process(eventName, { entity, serviceName: pgService.name })));
+        };
+        await info.process('pgIntrospection_introspection', {
+            introspection,
+            serviceName: pgService.name,
+        });
+        await announce('pgIntrospection_namespace', introspection.namespaces);
+        await announce('pgIntrospection_class', introspection.classes);
+        await announce('pgIntrospection_attribute', introspection.attributes);
+        await announce('pgIntrospection_constraint', introspection.constraints);
+        await announce('pgIntrospection_proc', introspection.procs);
+        await announce('pgIntrospection_role', introspection.roles);
+        await announce('pgIntrospection_auth_member', introspection.auth_members);
+        await announce('pgIntrospection_type', introspection.types);
+        await announce('pgIntrospection_enum', introspection.enums);
+        await announce('pgIntrospection_extension', introspection.extensions);
+        await announce('pgIntrospection_index', introspection.indexes);
+        await announce('pgIntrospection_language', introspection.languages);
+        await announce('pgIntrospection_range', introspection.ranges);
+        await announce('pgIntrospection_depend', introspection.depends);
+        await announce('pgIntrospection_description', introspection.descriptions);
+    }));
+}
+// Adapted from graphile-build-pg@5.1.3
+// dist/plugins/PgIntrospectionPlugin.js. Upstream does not expose its
+// cache/parse/announcement flow independently from the stock query.
+function getConstructiveIntrospection(info) {
+    const pgServices = info.resolvedPreset.pgServices ?? [];
+    const scopedIntrospection = info.options.pgScopedIntrospection;
+    assertScopedIntrospectionServices(pgServices, scopedIntrospection);
+    const hasScopedService = Object.values(scopedIntrospection ?? {}).some((config) => config === true || (config !== false && config !== undefined));
+    if (!hasScopedService) {
+        return upstreamGetIntrospection(info);
+    }
+    return (info.state.getIntrospectionPromise ??
+        (info.state.getIntrospectionPromise = (async () => {
+            if (info.cache.dirty) {
+                info.cache.introspectionResultsPromise = null;
+                info.cache.dirty = false;
+            }
+            const introspectionPromise = info.cache.introspectionResultsPromise ??
+                (info.cache.introspectionResultsPromise =
+                    introspectPgServices(pgServices, scopedIntrospection));
+            introspectionPromise.then(null, () => {
+                info.cache.introspectionResultsPromise = null;
+            });
+            const rawIntrospections = await introspectionPromise;
+            // Keep the raw result promise for clean gathers. Parsed introspection is
+            // intentionally rebuilt because gather plugins may mutate their copy.
+            const introspections = rawIntrospections.map(({ pgService, introspectionText, scopedPlan }) => {
+                const introspection = parseIntrospectionResults(introspectionText);
+                if (scopedPlan) {
+                    try {
+                        validateSchemaScopedIntrospection(introspection, scopedPlan);
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        throw new Error(`Schema-scoped introspection validation failed for PostgreSQL service '${pgService.name}': ${message}`, { cause: error });
+                    }
+                }
+                return { pgService, introspection };
+            });
+            // Announcements may call back into getIntrospection, so expose the
+            // resolved gather-local value before broadcasting entities.
+            info.state.getIntrospectionPromise = introspections;
+            await announceIntrospection(info, introspections);
+            return introspections;
+        })()));
+}
+async function getRangeByType(info, serviceName, typeId) {
+    const introspections = await info.helpers.pgIntrospection.getIntrospection();
+    const relevant = introspections.find((result) => result.pgService.name === serviceName);
+    if (!relevant)
+        throw new Error(`Could not find database '${serviceName}'`);
+    return relevant.introspection.ranges.find((range) => range.rngtypid === typeId || range.rngmultitypid === typeId);
+}
+/**
+ * CNC-owned atomic replacement for graphile-build-pg's introspection plugin.
+ * Stock-only configurations delegate to the upstream helper unchanged.
+ */
+export const ConstructivePgIntrospectionPlugin = {
+    name: 'ConstructivePgIntrospectionPlugin',
+    description: 'Adds opt-in schema-scoped PostgreSQL introspection for Constructive',
+    version: PgIntrospectionPlugin.version,
+    provides: ['PgIntrospectionPlugin'],
+    before: ['PgRegistryPlugin'],
+    gather: {
+        ...upstreamGather,
+        helpers: {
+            ...upstreamHelpers,
+            getIntrospection: getConstructiveIntrospection,
+            getRangeByType,
+        },
+    },
+};
+/** Disable upstream atomically before installing the CNC replacement. */
+export const ScopedIntrospectionPreset = {
+    disablePlugins: ['PgIntrospectionPlugin'],
+    plugins: [ConstructivePgIntrospectionPlugin],
+};
+export const scopedIntrospectionUpstreamContract = Object.freeze({
+    package: 'graphile-build-pg',
+    version: SUPPORTED_GRAPHILE_BUILD_PG_VERSION,
+    pluginName: PgIntrospectionPlugin.name,
+    namespace: upstreamGather.namespace,
+    hasInitialCache: typeof upstreamGather.initialCache === 'function',
+    hasInitialState: typeof upstreamGather.initialState === 'function',
+    hasWatch: typeof upstreamGather.watch === 'function',
+    helperNames: Object.keys(upstreamHelpers).sort(),
+    hookNames: Object.keys(upstreamGather.hooks ?? {}).sort(),
+});

package/esm/scoped-introspection-query.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Scoped catalog SQL adapted from Graphile Crystal's
+ * utils/pg-introspection/src/scopedIntrospection.ts at commit
+ * 441cef73b0a12ed24343b7f38241af28b6454280, which is MIT licensed
+ * (Copyright © 2023 Benjie Gillam). This is a static, CNC-owned query
+ * generator: it does not inspect or rewrite the upstream query at runtime.
+ */
+import type { SchemaScopedIntrospectionOptions, ScopedCatalogTypes } from '@constructive-io/graphql-types';
+import type { Introspection } from 'pg-introspection';
+export type { SchemaScopedIntrospectionOptions, ScopedCatalogTypes, } from '@constructive-io/graphql-types';
+export interface SchemaScopedIntrospectionQuery {
+    text: string;
+    values: [string[], string[]];
+}
+export interface SchemaScopedIntrospectionScope {
+    schemas: readonly string[];
+    catalogTypes: ScopedCatalogTypes;
+    capabilityExtensions: readonly string[];
+}
+export interface SchemaScopedIntrospectionPlan {
+    query: SchemaScopedIntrospectionQuery;
+    scope: SchemaScopedIntrospectionScope;
+}
+/**
+ * Builds a parameterized introspection plan scoped to the requested schemas
+ * and the transitive object dependencies required by their objects.
+ */
+export declare const makeSchemaScopedIntrospectionPlan: (schemas: readonly string[], options?: SchemaScopedIntrospectionOptions) => SchemaScopedIntrospectionPlan;
+/**
+ * Builds only the query portion of a schema-scoped introspection plan.
+ *
+ * Prefer `makeSchemaScopedIntrospectionPlan()` when the results will be
+ * parsed and validated by this package.
+ */
+export declare const makeSchemaScopedIntrospectionQuery: (schemas: readonly string[], options?: SchemaScopedIntrospectionOptions) => SchemaScopedIntrospectionQuery;
+/** Validates that an introspection result satisfies its scoped query plan. */
+export declare function validateSchemaScopedIntrospection(introspection: Introspection, plan: SchemaScopedIntrospectionPlan): void;