@intentius/chant-lexicon-sql 0.124.31 → 0.124.32

package/dist/token-source.js

@@ -0,0 +1,156 @@
+/**
+ * Short-lived database credentials (#3685): a profile's `password` can name a
+ * token source instead of an environment variable, and the token is minted
+ * when a connection needs it.
+ *
+ * ```ts
+ * profiles: {
+ *   prod: { url: "postgres://db.abc.us-east-1.rds.amazonaws.com:5432/shop", user: { env: "PG_USER" }, password: { token: "rds-iam" } },
+ *   ci: { url: "postgres://db.internal:5432/shop", password: { token: "command", command: ["./mint-token.sh"], ttlSeconds: 600 } },
+ * }
+ * ```
+ *
+ * Each cloud source runs that cloud's own command line, which reads the job's
+ * ambient identity (an OIDC-federated role in CI, a workload identity, a
+ * logged-in developer), so chant holds no cloud SDK and no long-lived secret:
+ *
+ * - `rds-iam`: `aws rds generate-db-auth-token`, for RDS and Aurora. The host
+ *   and port come from the profile's URL, the user from its `user`, the region
+ *   from `region`, else `AWS_REGION`, else the RDS host name.
+ * - `cloud-sql-iam`: `gcloud sql generate-login-token`.
+ * - `entra`: `az account get-access-token` for Azure Database for PostgreSQL.
+ * - `command`: any command that prints a password on its standard output.
+ *
+ * A token is reused until most of its lifetime has passed and minted again
+ * after, so a long apply, whose ClickHouse requests each carry the password
+ * and whose Postgres connections each authenticate when opened, never sends
+ * an expired one. A token is never written to a message, an outcome or a log.
+ */
+import { execFile } from "node:child_process";
+import { z } from "zod";
+const ttl = z.number().int().positive().optional();
+/** The token sources a profile's `password` can name. */
+export const tokenSourceSchema = z.discriminatedUnion("token", [
+    z.strictObject({
+        token: z.literal("rds-iam"),
+        /** The AWS region. `AWS_REGION`, `AWS_DEFAULT_REGION`, else the RDS host name's, when omitted. */
+        region: z.string().min(1).optional(),
+        /** How long a token is valid, in seconds. 900, the RDS lifetime, when omitted. */
+        ttlSeconds: ttl,
+    }),
+    z.strictObject({
+        token: z.literal("cloud-sql-iam"),
+        /** How long a token is valid, in seconds. 3600 when omitted. */
+        ttlSeconds: ttl,
+    }),
+    z.strictObject({
+        token: z.literal("entra"),
+        /** How long a token is valid, in seconds. 3600 when omitted. */
+        ttlSeconds: ttl,
+    }),
+    z.strictObject({
+        token: z.literal("command"),
+        /** The program and its arguments, run without a shell; its standard output, trimmed, is the password. */
+        command: z.array(z.string().min(1)).min(1),
+        /** How long a token is valid, in seconds. 300 when omitted. */
+        ttlSeconds: ttl,
+    }),
+]);
+/** The cloud sources, which mint for a Postgres server only. */
+export const POSTGRES_ONLY_TOKEN_SOURCES = new Set(["rds-iam", "cloud-sql-iam", "entra"]);
+const DEFAULT_TTL_SECONDS = {
+    "rds-iam": 900,
+    "cloud-sql-iam": 3600,
+    entra: 3600,
+    command: 300,
+};
+/** A token reused past this share of its lifetime is minted again. */
+const REUSE_FRACTION = 0.8;
+/** A token source that could not mint. The message names the source and the command, never what it printed. */
+export class TokenSourceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TokenSourceError";
+    }
+}
+const runCommand = (argv, env) => new Promise((resolve, reject) => {
+    execFile(argv[0], argv.slice(1), { env: env, timeout: 60000, maxBuffer: 1 << 20 }, (err, stdout) => {
+        if (err)
+            reject(err);
+        else
+            resolve(String(stdout));
+    });
+});
+/** The program a source runs. Pure, for tests. */
+export function tokenCommand(config, input) {
+    switch (config.token) {
+        case "command":
+            return config.command;
+        case "cloud-sql-iam":
+            return ["gcloud", "sql", "generate-login-token"];
+        case "entra":
+            return ["az", "account", "get-access-token", "--resource-type", "oss-rdbms", "--query", "accessToken", "--output", "tsv"];
+        case "rds-iam": {
+            const url = new URL(input.url);
+            if (input.user === undefined)
+                throw new TokenSourceError("rds-iam mints a token for one database user; the profile names no user");
+            const region = config.region ?? input.env.AWS_REGION ?? input.env.AWS_DEFAULT_REGION ?? /\.([a-z]{2}(?:-[a-z]+)+-\d+)\.rds\.amazonaws\.com$/.exec(url.hostname)?.[1];
+            return [
+                "aws",
+                "rds",
+                "generate-db-auth-token",
+                "--hostname",
+                url.hostname,
+                "--port",
+                url.port || "5432",
+                "--username",
+                input.user,
+                ...(region !== undefined ? ["--region", region] : []),
+            ];
+        }
+    }
+}
+/**
+ * A source that mints with `config` when asked. Nothing runs until `get()`.
+ * `now` and `run` are for tests.
+ */
+export function credentialSource(config, input) {
+    const run = input.run ?? runCommand;
+    const now = input.now ?? Date.now;
+    const lifetimeMs = (config.ttlSeconds ?? DEFAULT_TTL_SECONDS[config.token]) * 1000 * REUSE_FRACTION;
+    const source = `${input.source} (${config.token})`;
+    let cached;
+    let pending;
+    const mint = async () => {
+        const argv = tokenCommand(config, input);
+        let out;
+        try {
+            out = await run(argv, input.env);
+        }
+        catch (err) {
+            const e = err;
+            const why = e.code === "ENOENT" ? `${argv[0]} is not installed` : `it exited with ${String(e.code ?? "an error")}`;
+            throw new TokenSourceError(`${source} could not mint a token: \`${argv[0]}\` failed, ${why}`);
+        }
+        const token = out.trim();
+        if (token === "")
+            throw new TokenSourceError(`${source} could not mint a token: \`${argv[0]}\` printed nothing`);
+        cached = { token, until: now() + lifetimeMs };
+        return token;
+    };
+    return {
+        source,
+        async get() {
+            if (cached && now() < cached.until)
+                return cached.token;
+            // Requests that ask at once share one mint.
+            pending ?? (pending = mint().finally(() => {
+                pending = undefined;
+            }));
+            return pending;
+        },
+        invalidate() {
+            cached = undefined;
+        },
+    };
+}

package/dist/validate-cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env tsx
+import { printValidationResult } from "@intentius/chant/codegen/validate";
+import { validate } from "./validate.js";
+// printValidationResult throws when a check failed, so `npm run validate` (and prepack) exits non-zero.
+printValidationResult(await validate());

package/dist/validate.js

@@ -0,0 +1,151 @@
+/**
+ * Validate the sql lexicon's generated artifacts.
+ *
+ * The core checks (the registry parses, `index.d.ts` exists and compiles), plus
+ * the ClickHouse catalog's own: the generated tables exist, the committed
+ * snapshot is at the pin, and the names a schema leans on hardest are still
+ * in it. A pin move that drops one of those would otherwise surface as lint
+ * going quiet, not as a failure.
+ */
+import { existsSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { validateLexiconArtifacts } from "@intentius/chant/codegen/validate";
+import { CLICKHOUSE_VERSION } from "./spec/pin.js";
+import { parseCatalog } from "./spec/catalog.js";
+import { POSTGRES_PINS } from "./spec/postgres-pin.js";
+import { parseCatalog as parsePostgresCatalog } from "./spec/postgres-catalog.js";
+/** The entity kinds the registry must carry. */
+const REQUIRED_ENTITIES = [
+    "Database",
+    "Table",
+    "View",
+    "MaterializedView",
+    "Dictionary",
+    "Function",
+    "User",
+    "Role",
+    "RowPolicy",
+    "Grant",
+    "Quota",
+    "SettingsProfile",
+    "PostgresSchema",
+    "PostgresTable",
+    "PostgresIndex",
+    "PostgresView",
+    "PostgresMaterializedView",
+    "PostgresSequence",
+    "PostgresEnum",
+    "PostgresCompositeType",
+    "PostgresRangeType",
+    "PostgresDomain",
+    "PostgresAggregate",
+    "PostgresCollation",
+    "PostgresCast",
+    "PostgresEventTrigger",
+    "PostgresExtension",
+    "PostgresFunction",
+    "PostgresProcedure",
+    "PostgresTrigger",
+    "PostgresPolicy",
+    "PostgresRole",
+    "PostgresGrant",
+    "PostgresDefaultPrivileges",
+];
+/** Engines a ClickHouse schema declares most: the MergeTree family and the engines beside it. */
+const REQUIRED_ENGINES = [
+    "MergeTree",
+    "ReplacingMergeTree",
+    "SummingMergeTree",
+    "AggregatingMergeTree",
+    "CollapsingMergeTree",
+    "VersionedCollapsingMergeTree",
+    "ReplicatedMergeTree",
+    "ReplicatedReplacingMergeTree",
+    "Distributed",
+    "Buffer",
+    "Memory",
+    "Null",
+    "MaterializedView",
+    "View",
+];
+/** Column type families the parser and the sort-key rules reason about. */
+const REQUIRED_TYPE_FAMILIES = [
+    "String",
+    "UInt64",
+    "Int64",
+    "Float64",
+    "DateTime",
+    "DateTime64",
+    "Date",
+    "UUID",
+    "Decimal",
+    "Nullable",
+    "LowCardinality",
+    "Array",
+    "Map",
+    "Tuple",
+    "Enum8",
+    "AggregateFunction",
+    "SimpleAggregateFunction",
+];
+/** Codecs the codec overlay types parameters for. */
+const REQUIRED_CODECS = ["ZSTD", "LZ4", "LZ4HC", "Delta", "DoubleDelta", "Gorilla", "T64"];
+export async function validate(opts) {
+    const basePath = opts?.basePath ?? dirname(dirname(fileURLToPath(import.meta.url)));
+    const core = await validateLexiconArtifacts({
+        lexiconJsonFilename: "lexicon-sql.json",
+        requiredNames: REQUIRED_ENTITIES,
+        basePath,
+        // Generation reads the committed catalog snapshot, so the surface is deterministic: a pin move that
+        // changes it fails here until `chant dev surface-diff lexicons/sql --update-snapshot --bump` accepts it.
+        checkSurfaceSnapshot: "always",
+    });
+    const checks = [...core.checks];
+    const tables = join(basePath, "src", "generated", "clickhouse.ts");
+    checks.push(existsSync(tables)
+        ? { name: "clickhouse-tables-exist", ok: true }
+        : { name: "clickhouse-tables-exist", ok: false, error: "src/generated/clickhouse.ts not found; run npm run generate" });
+    try {
+        const catalog = parseCatalog(readFileSync(join(basePath, "src", "spec", "clickhouse-catalog.snapshot.json"), "utf-8"));
+        checks.push(catalog.version === CLICKHOUSE_VERSION
+            ? { name: "clickhouse-snapshot-at-pin", ok: true }
+            : {
+                name: "clickhouse-snapshot-at-pin",
+                ok: false,
+                error: `the snapshot is ${catalog.version}, the pin is ${CLICKHOUSE_VERSION}; run npm run generate to refresh it`,
+            });
+        const missing = (names, have) => {
+            const set = new Set(have);
+            return names.filter((n) => !set.has(n));
+        };
+        const gaps = [
+            ...missing(REQUIRED_ENGINES, catalog.tableEngines.map((e) => e.name)).map((n) => `engine ${n}`),
+            ...missing(REQUIRED_TYPE_FAMILIES, catalog.typeFamilies.map((t) => t.name)).map((n) => `type ${n}`),
+            ...missing(REQUIRED_CODECS, catalog.codecs.map((c) => c.name)).map((n) => `codec ${n}`),
+        ];
+        checks.push(gaps.length === 0
+            ? { name: "clickhouse-required-names", ok: true }
+            : { name: "clickhouse-required-names", ok: false, error: `missing at the pin: ${gaps.join(", ")}` });
+    }
+    catch (err) {
+        checks.push({
+            name: "clickhouse-snapshot-readable",
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+    try {
+        const behind = POSTGRES_PINS.flatMap((pin) => {
+            const snapshot = parsePostgresCatalog(readFileSync(join(basePath, "src", "spec", `postgres-catalog-${pin.major}.snapshot.json`), "utf-8"));
+            return snapshot.version === pin.version ? [] : [`${pin.major}: snapshot ${snapshot.version}, pin ${pin.version}`];
+        });
+        checks.push(behind.length === 0
+            ? { name: "postgres-snapshots-at-pins", ok: true }
+            : { name: "postgres-snapshots-at-pins", ok: false, error: `${behind.join("; ")}; run npm run generate to refresh` });
+    }
+    catch (err) {
+        checks.push({ name: "postgres-snapshots-readable", ok: false, error: err instanceof Error ? err.message : String(err) });
+    }
+    return { success: checks.every((c) => c.ok), checks };
+}

package/dist/workspace-outputs.js

@@ -0,0 +1,191 @@
+/**
+ * The workspace outputs a sql member exposes (#3931): each table and view,
+ * and each of their columns, as names another member's link may target.
+ *
+ * | Dialect | Relation | Column |
+ * |---|---|---|
+ * | Postgres | `<schema>.<table>` | `<schema>.<table>.<column>` |
+ * | ClickHouse | `<database>.<table>` | `<database>.<table>.<column>` |
+ *
+ * The schema is `public` when the DDL does not qualify the name, and the
+ * database `default`. Views and materialized views are relations too.
+ *
+ * Names are the declared ones, read from the entities the member's source
+ * folds to, never an environment's or a profile's rendering: a member that
+ * renames its database per environment or tenant at deploy time exposes the
+ * same outputs everywhere.
+ *
+ * Identifiers are written unquoted, in the case the dialect keeps:
+ *
+ * - Postgres folds an unquoted identifier to lower case and keeps a quoted
+ *   one exactly, so `CREATE TABLE Orders` is `public.orders` and `CREATE
+ *   TABLE "Orders"` is `public.Orders`, a different output;
+ * - ClickHouse is case-sensitive, so a name is kept as written, quoted or not.
+ *
+ * A link's near-name hint compares names case-insensitively, so a link to
+ * `public.orders` when only `public.Orders` exists is pointed at it.
+ *
+ * A view's columns are its declared column list, or else the names of its
+ * select list (an alias, or the column a bare reference reads). A select
+ * list item with no name chant can derive, or a `*`, leaves the view's
+ * columns incomplete: that is a gap, so a link to one of them is unresolved
+ * rather than missing.
+ *
+ * A `-- previously: <old>` rename hint, on a column's line or before the
+ * CREATE, is reported as the output's previous name, so a link to the old
+ * name says where it went.
+ */
+import { CLICKHOUSE_ENTITY_TYPES, isClickHouseObject } from "./clickhouse/entities.js";
+import { canonicalObject } from "./clickhouse/plan/normalize.js";
+import { isPostgresObject, POSTGRES_ENTITY_TYPES } from "./postgres/entities.js";
+import { renameHints } from "./postgres/plan/schema.js";
+/** The schema an unqualified Postgres name is created in. */
+export const POSTGRES_DEFAULT_SCHEMA = "public";
+/** The database an unqualified ClickHouse name is created in. */
+export const CLICKHOUSE_DEFAULT_DATABASE = "default";
+/** A module the sql lexicon's declarations import from. */
+const SQL_MODULE = /from\s+["']@intentius\/chant-lexicon-sql(\/(postgres|clickhouse|sql-files))?["']/;
+function add(c, name, entity, previously = []) {
+    const prev = c.outputs.get(name);
+    const before = [...new Set([...(prev?.previously ?? []), ...previously.filter((p) => p !== name)])].sort();
+    c.outputs.set(name, { name, entity: prev?.entity ?? entity, ...(before.length ? { previously: before } : {}) });
+}
+/** A relation and its columns, with the rename hints that apply. */
+function addRelation(c, key, qualifier, name, columns, hints) {
+    const relation = `${qualifier}.${name}`;
+    // A relation's hint names its old name, bare or qualified.
+    const oldRelation = hints.previously ? (hints.previously.includes(".") ? hints.previously : `${qualifier}.${hints.previously}`) : undefined;
+    add(c, relation, key, oldRelation ? [oldRelation] : []);
+    for (const col of columns) {
+        const prevCol = hints.columns[col];
+        const previously = [
+            ...(prevCol ? [`${relation}.${prevCol}`] : []),
+            ...(oldRelation ? [`${oldRelation}.${col}`, ...(prevCol ? [`${oldRelation}.${prevCol}`] : [])] : []),
+        ];
+        add(c, `${relation}.${col}`, key, previously);
+    }
+}
+/** A view's output columns from its select list, and whether they are all known. */
+function lineageColumns(lineage, unnamed) {
+    const columns = [];
+    let complete = true;
+    lineage.forEach((e, i) => {
+        if (/(^|\.)\s*\*$/.test(e.expr.trim()) || unnamed(e.output, i + 1))
+            complete = false;
+        else
+            columns.push(e.output);
+    });
+    return { columns, complete };
+}
+function postgres(c, key, e) {
+    const type = e.entityType;
+    if (type === POSTGRES_ENTITY_TYPES.table) {
+        const props = e.props;
+        const schema = props.schema ?? POSTGRES_DEFAULT_SCHEMA;
+        const columns = props.columns.map((col) => col.name);
+        const inherited = (parent) => isPostgresObject(parent) && parent.entityType === POSTGRES_ENTITY_TYPES.table ? parent.props.columns.map((col) => col.name) : undefined;
+        // A partition takes its parent's columns; INHERITS adds the parents'.
+        if (props.partitionOf !== undefined) {
+            const fromParent = inherited(props.partitionOf);
+            if (fromParent)
+                columns.push(...fromParent.filter((n) => !columns.includes(n)));
+            else
+                c.gaps.push(`table ${schema}.${props.name} (${key}) is a partition of ${String(props.partitionOf)}, which this member does not declare, so its columns are not known`);
+        }
+        for (const parent of props.inherits) {
+            const fromParent = inherited(parent);
+            if (fromParent)
+                columns.push(...fromParent.filter((n) => !columns.includes(n)));
+            else
+                c.gaps.push(`table ${schema}.${props.name} (${key}) inherits ${String(parent)}, which this member does not declare, so its columns are not all known`);
+        }
+        if (props.ofType !== undefined) {
+            const attrs = isPostgresObject(props.ofType) ? props.ofType.props.attributes : undefined;
+            if (attrs)
+                columns.push(...attrs.map((a) => a.name).filter((n) => !columns.includes(n)));
+            else
+                c.gaps.push(`table ${schema}.${props.name} (${key}) is OF ${String(props.ofType)}, which this member does not declare, so its columns are not known`);
+        }
+        if (props.like.length > 0)
+            c.gaps.push(`table ${schema}.${props.name} (${key}) copies columns with LIKE, which are not read`);
+        addRelation(c, key, schema, props.name, columns, renameHints(props.ddl));
+        return;
+    }
+    if (type === POSTGRES_ENTITY_TYPES.view || type === POSTGRES_ENTITY_TYPES.materializedView) {
+        const props = e.props;
+        const schema = props.schema ?? POSTGRES_DEFAULT_SCHEMA;
+        let columns = [...props.columns];
+        if (columns.length === 0) {
+            const derived = lineageColumns(props.lineage, (output) => output === "?column?");
+            columns = derived.columns;
+            if (!derived.complete)
+                c.gaps.push(`view ${schema}.${props.name} (${key}) has a select list item whose name can't be read without a server (a * or an unnamed expression), so its columns are not all known`);
+        }
+        addRelation(c, key, schema, props.name, columns, renameHints(props.ddl));
+    }
+}
+function clickhouseHints(ddl) {
+    try {
+        const o = canonicalObject(ddl, CLICKHOUSE_DEFAULT_DATABASE);
+        const columns = {};
+        for (const col of o.columns)
+            if (col.previously)
+                columns[col.name] = col.previously;
+        return { ...(o.previously ? { previously: o.previously } : {}), columns };
+    }
+    catch {
+        return { columns: {} };
+    }
+}
+function clickhouse(c, key, e) {
+    const type = e.entityType;
+    if (type === CLICKHOUSE_ENTITY_TYPES.table) {
+        const props = e.props;
+        const database = props.database ?? CLICKHOUSE_DEFAULT_DATABASE;
+        if (props.columns.length === 0)
+            c.gaps.push(`table ${database}.${props.name} (${key}) declares no columns, so the server's are not known`);
+        addRelation(c, key, database, props.name, props.columns.map((col) => col.name), clickhouseHints(props.ddl));
+        return;
+    }
+    if (type === CLICKHOUSE_ENTITY_TYPES.view || type === CLICKHOUSE_ENTITY_TYPES.materializedView) {
+        const props = e.props;
+        const database = props.database ?? CLICKHOUSE_DEFAULT_DATABASE;
+        let columns = props.columns.map((col) => col.name);
+        if (columns.length === 0) {
+            const derived = lineageColumns(props.lineage, (output, n) => output === `_${n}`);
+            columns = derived.columns;
+            if (!derived.complete)
+                c.gaps.push(`view ${database}.${props.name} (${key}) has a select list item whose name can't be read without a server (a * or an unaliased expression), so its columns are not all known`);
+        }
+        addRelation(c, key, database, props.name, columns, clickhouseHints(props.ddl));
+    }
+}
+/**
+ * The `workspaceOutputs` hook: every table and view the entities declare,
+ * and their columns. `unread` names the member's files that did not fold;
+ * one that imports the sql lexicon may declare tables, so it is a gap.
+ */
+export function sqlWorkspaceOutputs(entities, unread = []) {
+    const c = { outputs: new Map(), gaps: [] };
+    let any = false;
+    for (const [key, e] of entities) {
+        if (isPostgresObject(e)) {
+            any = true;
+            postgres(c, key, e);
+        }
+        else if (isClickHouseObject(e)) {
+            any = true;
+            clickhouse(c, key, e);
+        }
+    }
+    for (const u of unread) {
+        if (!SQL_MODULE.test(u.text))
+            continue;
+        any = true;
+        c.gaps.push(`${u.file} imports the sql lexicon and does not fold, so the tables it declares were not read: ${u.reason}`);
+    }
+    if (!any)
+        return undefined;
+    const outputs = [...c.outputs.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    return { outputs, ...(c.gaps.length ? { gaps: c.gaps } : {}) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-sql",
-  "version": "0.124.31",
+  "version": "0.124.32",
   "description": "SQL lexicon for chant — database schema as typed declarations, one dialect at a time; ClickHouse first, with types read from a pinned server's catalog",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -31,23 +31,23 @@
     ".": {
       "development": "./src/index.ts",
       "types": "./dist/index.d.ts",
-      "default": "./src/index.ts"
+      "default": "./dist/index.js"
     },
     "./workspace-kinds": "./workspace-kinds.json",
     "./*": {
       "development": "./src/*.ts",
       "types": "./dist/*.d.ts",
-      "default": "./src/*.ts"
+      "default": "./dist/*.js"
     },
     "./op/activities": {
       "development": "./src/op/activities/index.ts",
       "types": "./dist/op/activities/index.d.ts",
-      "default": "./src/op/activities/index.ts"
+      "default": "./dist/op/activities/index.js"
     },
     "./lint/post-synth": {
       "development": "./src/lint/post-synth/index.ts",
       "types": "./dist/lint/post-synth/index.d.ts",
-      "default": "./src/lint/post-synth/index.ts"
+      "default": "./dist/lint/post-synth/index.js"
     },
     "./manifest": "./dist/manifest.json",
     "./meta": "./dist/meta.json",
@@ -59,7 +59,7 @@
     "validate": "tsx src/validate-cli.ts",
     "docs": "tsx src/codegen/docs-cli.ts",
     "prepack": "npm run generate && npm run bundle && npm run validate && npm run build",
-    "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && find dist -type f \\( -name \"*.js\" -o -name \"*.js.map\" \\) -delete"
+    "build": "tsc -p tsconfig.build.json --sourceMap false && tsc-alias -p tsconfig.build.json"
   },
   "dependencies": {
     "pg": "^8.23.1",
@@ -72,6 +72,6 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.124.31"
+    "@intentius/chant": "^0.124.32"
   }
 }

package/src/codegen/package.ts

@@ -4,14 +4,14 @@
 
 import { readFileSync } from "fs";
 import { join, dirname } from "path";
-import { fileURLToPath } from "url";
+import { moduleSourceDir } from "@intentius/chant/module-source";
 import { packagePipeline, type PackageOptions, type PackageResult } from "@intentius/chant/codegen/package";
 import { generate } from "./generate";
 
 export type { PackageOptions, PackageResult };
 
 // src/codegen/package.ts -> src/
-const srcDir = dirname(dirname(fileURLToPath(import.meta.url)));
+const srcDir = dirname(moduleSourceDir(import.meta.url));
 
 export async function packageLexicon(opts: PackageOptions = {}): Promise<PackageResult> {
   const pkgJson = JSON.parse(readFileSync(join(srcDir, "..", "package.json"), "utf-8"));

package/src/lint/rules/typescript-7.test.ts

@@ -88,7 +88,8 @@ describe.skipIf(!ready)("sql lint rules in a TypeScript 7 project (#3864)", () =
 
   test("no rule throws, and the lexicon really sees TypeScript 7", () => {
     for (const dir of examples) expect(readdirSync(dir).length).toBeGreaterThan(0);
-    const out = execFileSync(process.execPath, ["--import", `file://${tsxLoader}`, join(project, "run.mts"), JSON.stringify(examples), lexiconPackageJson], {
+    // The copy carries src/ only, so the lexicon resolves through its `development` export (#3981).
+    const out = execFileSync(process.execPath, ["--conditions=development", "--import", `file://${tsxLoader}`, join(project, "run.mts"), JSON.stringify(examples), lexiconPackageJson], {
       cwd: project,
       encoding: "utf-8",
       env: { ...process.env, TSX_DISABLE_CACHE: "1" },

package/src/lsp/catalog.ts

@@ -6,10 +6,10 @@
 
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
-import { fileURLToPath } from "url";
+import { moduleSourceDir } from "@intentius/chant/module-source";
 import { parseCatalog, type ClickHouseCatalog, type SettingRow } from "../spec/catalog";
 
-const SNAPSHOT = join(dirname(fileURLToPath(import.meta.url)), "..", "spec", "clickhouse-catalog.snapshot.json");
+const SNAPSHOT = join(moduleSourceDir(import.meta.url), "..", "spec", "clickhouse-catalog.snapshot.json");
 
 export interface CatalogIndex {
   catalog: ClickHouseCatalog;

package/src/lsp/postgres-catalog.ts

@@ -10,12 +10,12 @@
 
 import { existsSync, readFileSync } from "fs";
 import { dirname, join, resolve } from "path";
-import { fileURLToPath } from "url";
+import { moduleSourceDir } from "@intentius/chant/module-source";
 import { parseCatalog, type PostgresCatalog } from "../spec/postgres-catalog";
 import { POSTGRES_LATEST_MAJOR, POSTGRES_MAJORS } from "../spec/postgres-pin";
 import { STORAGE_PARAMETER_TYPES } from "../postgres/overlays/storage";
 
-const SPEC = join(dirname(fileURLToPath(import.meta.url)), "..", "spec");
+const SPEC = join(moduleSourceDir(import.meta.url), "..", "spec");
 
 let cached: Map<number, PostgresCatalog> | null = null;
 

package/src/lsp/registry.ts

@@ -1,7 +1,8 @@
 import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
 import { LexiconIndex, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
 
-const require = createRequire(import.meta.url);
+const require = createRequire(moduleSourceUrl(import.meta.url));
 
 let cached: LexiconIndex | null = null;
 

package/src/mcp/index.ts

@@ -8,6 +8,7 @@
 
 import type { McpResourceContribution, McpToolContribution } from "@intentius/chant/mcp/types";
 import { createCatalogResource, createDiffTool } from "@intentius/chant/lexicon-plugin-helpers";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
 import { sqlSerializer } from "../serializer";
 import { catalogIndex } from "../lsp/catalog";
 import { database, dictionary, func, grant, policy, quota, role, settingsProfile, table, user, view } from "../clickhouse/entities";
@@ -272,9 +273,10 @@ const need = () => {
 /** The resources the sql lexicon contributes. */
 export function sqlMcpResources(): McpResourceContribution[] {
   return [
-    // `generated/` sits beside plugin.ts, which is where the helper looks.
+    // `generated/` sits beside plugin.ts, which is where the helper looks. The
+    // source URL, so a compiled module names src/plugin.ts too (#3981).
     createCatalogResource(
-      new URL("../plugin.ts", import.meta.url).href,
+      new URL("../plugin.ts", moduleSourceUrl(import.meta.url)).href,
       "SQL Entity Catalog",
       "The entity kinds the sql lexicon declares (database, table, view, materialized view, dictionary, function, user, role, row policy, grant)",
       "lexicon-sql.json",

package/src/spec/fetch.ts

@@ -19,13 +19,13 @@
 
 import { readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { moduleSourceDir } from "@intentius/chant/module-source";
 import { CLICKHOUSE_VERSION, clickhouseImage } from "./pin";
 import { parseCatalog, readCatalog, stringifyCatalog, type ClickHouseCatalog } from "./catalog";
 import { startScratchServer } from "../clickhouse/container";
 import type { ClickHouseEndpoint } from "../clickhouse/http";
 
-export const SNAPSHOT_FILE = join(dirname(fileURLToPath(import.meta.url)), "clickhouse-catalog.snapshot.json");
+export const SNAPSHOT_FILE = join(moduleSourceDir(import.meta.url), "clickhouse-catalog.snapshot.json");
 
 /** The key the single catalog document is filed under in the pipeline's schema map. */
 export const CATALOG_KEY = "ClickHouse::Catalog";