@bockit/sequel 0.0.0-stage → 0.2.0

package/dist/extras/snapshot.js

@@ -0,0 +1,99 @@
+import { withClient } from '../db/connection.js';
+// TECH-SPEC §11: the Postgres features the schema language can't express, read from the
+// catalog of the `public` schema. The committed snapshot is a record for review: never run.
+// Excludes objects that belong to an extension, such as pgvector's functions.
+const NOT_FROM_EXTENSION = (catalog, oid) => `NOT EXISTS (
+  SELECT 1 FROM pg_depend d
+  WHERE d.classid = '${catalog}'::regclass AND d.objid = ${oid} AND d.deptype = 'e')`;
+const SECTIONS = [
+    {
+        title: 'Extensions',
+        query: `SELECT format('CREATE EXTENSION %I', extname) AS def
+      FROM pg_extension WHERE extname <> 'plpgsql'`,
+    },
+    {
+        title: 'Database settings',
+        query: `SELECT format('ALTER DATABASE … SET %s', setting) AS def
+      FROM pg_db_role_setting, unnest(setconfig) AS setting
+      WHERE setrole = 0
+        AND setdatabase = (SELECT oid FROM pg_database WHERE datname = current_database())`,
+    },
+    {
+        title: 'Functions',
+        // Aggregates and window functions have no `pg_get_functiondef`.
+        query: `SELECT pg_get_functiondef(p.oid) AS def FROM pg_proc p
+      WHERE p.pronamespace = 'public'::regnamespace AND p.prokind IN ('f', 'p')
+        AND ${NOT_FROM_EXTENSION('pg_proc', 'p.oid')}`,
+    },
+    {
+        title: 'Triggers',
+        query: `SELECT pg_get_triggerdef(t.oid) AS def
+      FROM pg_trigger t JOIN pg_class c ON c.oid = t.tgrelid
+      WHERE NOT t.tgisinternal AND c.relnamespace = 'public'::regnamespace`,
+    },
+    {
+        title: 'CHECK, exclusion and deferrable constraints',
+        query: `SELECT format('ALTER TABLE %I ADD CONSTRAINT %I %s', c.relname, con.conname, pg_get_constraintdef(con.oid)) AS def
+      FROM pg_constraint con JOIN pg_class c ON c.oid = con.conrelid
+      WHERE con.connamespace = 'public'::regnamespace
+        AND (con.contype IN ('c', 'x') OR con.condeferrable)`,
+    },
+    {
+        title: 'Partial, expression and non-btree indexes',
+        query: `SELECT pg_get_indexdef(i.indexrelid) AS def
+      FROM pg_index i
+        JOIN pg_class ic ON ic.oid = i.indexrelid
+        JOIN pg_am am ON am.oid = ic.relam
+      WHERE ic.relnamespace = 'public'::regnamespace
+        AND (i.indpred IS NOT NULL OR i.indexprs IS NOT NULL OR am.amname <> 'btree')`,
+    },
+    {
+        title: 'Generated columns',
+        query: `SELECT format('%I.%I GENERATED ALWAYS AS (%s) %s', c.relname, a.attname,
+        pg_get_expr(ad.adbin, ad.adrelid),
+        CASE a.attgenerated WHEN 's' THEN 'STORED' ELSE 'VIRTUAL' END) AS def
+      FROM pg_attribute a
+        JOIN pg_class c ON c.oid = a.attrelid
+        JOIN pg_attrdef ad ON ad.adrelid = a.attrelid AND ad.adnum = a.attnum
+      WHERE c.relnamespace = 'public'::regnamespace
+        AND a.attgenerated <> '' AND NOT a.attisdropped`,
+    },
+    {
+        title: 'Views',
+        query: `SELECT format('CREATE %sVIEW %I AS %s',
+        CASE c.relkind WHEN 'm' THEN 'MATERIALIZED ' ELSE '' END, c.relname, pg_get_viewdef(c.oid)) AS def
+      FROM pg_class c
+      WHERE c.relnamespace = 'public'::regnamespace AND c.relkind IN ('v', 'm')
+        AND ${NOT_FROM_EXTENSION('pg_class', 'c.oid')}`,
+    },
+    {
+        title: 'Column collations',
+        // A column whose collation isn't its type's default.
+        query: `SELECT format('%I.%I COLLATE %s', c.relname, a.attname, a.attcollation::regcollation) AS def
+      FROM pg_attribute a
+        JOIN pg_class c ON c.oid = a.attrelid
+        JOIN pg_type t ON t.oid = a.atttypid
+      WHERE c.relnamespace = 'public'::regnamespace AND c.relkind IN ('r', 'p')
+        AND a.attnum > 0 AND NOT a.attisdropped
+        AND a.attcollation <> 0 AND a.attcollation <> t.typcollation`,
+    },
+];
+const HEADER = [
+    "-- Postgres features outside Prisma's schema language, as the test database has them.",
+    '-- Written by `sequel extras`. A record for review: it is never run.',
+].join('\n');
+// The snapshot of the database `url` names.
+export function readExtrasSnapshot(url) {
+    return withClient(url, extrasSnapshot);
+}
+export async function extrasSnapshot(client) {
+    const sections = [HEADER];
+    for (const { title, query } of SECTIONS) {
+        const { rows } = await client.query(query);
+        const defs = rows
+            .map((row) => `${row.def.trim().replace(/;$/, '')};`)
+            .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+        sections.push([`-- ${title}`, ...(defs.length > 0 ? defs : ['-- (none)'])].join('\n'));
+    }
+    return `${sections.join('\n\n')}\n`;
+}

package/dist/files.d.ts

@@ -0,0 +1 @@
+export declare function writeAtomically(file: string, contents: string): Promise<void>;

package/dist/files.js

@@ -0,0 +1,15 @@
+import { randomBytes } from 'node:crypto';
+import { rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+// Writes beside the target, then renames over it, so a reader never sees half a file.
+export async function writeAtomically(file, contents) {
+    const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${randomBytes(6).toString('hex')}.tmp`);
+    try {
+        await writeFile(temporary, contents);
+        await rename(temporary, file);
+    }
+    catch (error) {
+        await rm(temporary, { force: true });
+        throw error;
+    }
+}

package/dist/generate/generate-modules.d.ts

@@ -0,0 +1,17 @@
+import type { BigintMode } from '../config/define-config.ts';
+import { type InstallResult, type ModuleCheck, type Rendered } from './modules.ts';
+export type GenerateOptions = {
+    sqlc: string;
+    databaseUrl: string;
+    folders: string[];
+    bigint?: BigintMode;
+    root?: string;
+    pgDump?: string;
+};
+export declare function generateModules(options: GenerateOptions): Promise<InstallResult>;
+export declare function checkModules(options: GenerateOptions): Promise<ModuleCheck>;
+export declare function sqlcDiff(options: GenerateOptions): Promise<{
+    clean: boolean;
+    output: string;
+}>;
+export declare function renderModules(options: GenerateOptions): Promise<Rendered>;

package/dist/generate/generate-modules.js

@@ -0,0 +1,97 @@
+import { mkdir, mkdtemp, readdir, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { SequelError } from '../errors.js';
+import { compareModules, hasNamedQueries, installModules, } from './modules.js';
+import { dumpSchema } from './pg-dump.js';
+import { writePluginWrapper } from './plugin-wrapper.js';
+import { readFailures, runSqlc, sqlcConfig, writeSqlcConfig } from './sqlc.js';
+// Steps 2–4 of TECH-SPEC §9 for `generate`: dumps the test database's schema, runs sqlc
+// into temporary folders, and only when every block succeeds puts the modules in place and
+// deletes orphans. Any failure throws, listing every failure, and changes nothing.
+export async function generateModules(options) {
+    const rendered = await renderModules(options);
+    return installModules(rendered, options.folders);
+}
+// For `check`: the same run, compared byte for byte with the modules in place.
+export async function checkModules(options) {
+    const rendered = await renderModules(options);
+    return compareModules(rendered, options.folders);
+}
+// `sqlc diff` with each block's `out` set to its own folder. sqlc prints a unified diff for a
+// stale module, but exits 1 silently for a missing one, and doesn't see orphans.
+export async function sqlcDiff(options) {
+    return withRun(options, async (run) => {
+        const blocks = await blocksFor(options.folders, () => '');
+        if (blocks.length === 0)
+            return { clean: true, output: '' };
+        const result = await run(blocks.map((block) => ({ ...block, out: block.queries })), 'diff');
+        return { clean: result.exitCode === 0, output: result.stdout + result.stderr };
+    });
+}
+// Runs sqlc generate with each block's `out` in a temporary folder, and returns what it wrote.
+export async function renderModules(options) {
+    return withRun(options, async (run, workDir) => {
+        const blocks = await blocksFor(options.folders, (i) => path.join(workDir, 'out', String(i)));
+        const rendered = new Map();
+        if (blocks.length === 0)
+            return rendered;
+        for (const block of blocks)
+            await mkdir(block.out, { recursive: true });
+        const result = await run(blocks, 'generate');
+        const configDir = path.join(workDir, 'config');
+        if (result.exitCode !== 0) {
+            const failures = readFailures(result.stderr + result.stdout, {
+                configDir,
+                blocks,
+                root: options.root ?? process.cwd(),
+            });
+            throw new SequelError(`sqlc could not generate the query modules, so nothing was written:\n${failures.join('\n')}`);
+        }
+        for (const block of blocks) {
+            const modules = new Map();
+            for (const name of (await readdir(block.out)).sort()) {
+                modules.set(name, await readFile(path.join(block.out, name), 'utf8'));
+            }
+            rendered.set(block.queries, modules);
+        }
+        return rendered;
+    });
+}
+async function blocksFor(folders, out) {
+    const blocks = [];
+    for (const folder of folders) {
+        if (await hasNamedQueries(folder))
+            blocks.push({ queries: folder, out: out(blocks.length) });
+    }
+    return blocks;
+}
+// A temporary folder holding the dump, the wrapper and the config, removed afterwards.
+async function withRun(options, body) {
+    const workDir = await mkdtemp(path.join(tmpdir(), 'sequel-generate-'));
+    try {
+        const configDir = path.join(workDir, 'config');
+        await mkdir(configDir);
+        let prepared;
+        const run = async (blocks, command) => {
+            if (prepared === undefined) {
+                const schema = path.join(workDir, 'schema.sql');
+                await dumpSchema(options.databaseUrl, schema, options.pgDump);
+                prepared = { schema, wrapper: await writePluginWrapper(workDir) };
+            }
+            const configFile = path.join(configDir, 'sqlc.json');
+            await writeSqlcConfig(configFile, sqlcConfig({
+                configDir,
+                schema: prepared.schema,
+                blocks,
+                wrapper: prepared.wrapper,
+                bigint: options.bigint ?? 'string',
+            }));
+            return runSqlc(options.sqlc, command, configFile, options.databaseUrl);
+        };
+        return await body(run, workDir);
+    }
+    finally {
+        await rm(workDir, { recursive: true, force: true });
+    }
+}

package/dist/generate/modules.d.ts

@@ -0,0 +1,16 @@
+export declare function isGeneratedModule(text: string): boolean;
+export declare function findQueryFolders(patterns: string[]): Promise<string[]>;
+export declare function hasNamedQueries(folder: string): Promise<boolean>;
+export type Rendered = Map<string, Map<string, string>>;
+export type InstallResult = {
+    written: string[];
+    unchanged: string[];
+    deleted: string[];
+};
+export declare function installModules(rendered: Rendered, folders: string[]): Promise<InstallResult>;
+export type ModuleCheck = {
+    stale: string[];
+    missing: string[];
+    orphaned: string[];
+};
+export declare function compareModules(rendered: Rendered, folders: string[]): Promise<ModuleCheck>;

package/dist/generate/modules.js

@@ -0,0 +1,118 @@
+import { glob, readdir, readFile, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { SequelError } from '../errors.js';
+import { writeAtomically } from '../files.js';
+// R11: the first line of every generated module. sequel recognises its modules, and their
+// orphans, by it (TECH-SPEC §9).
+const HEADER = /^\/\/ Generated by sequel from .+\. Do not edit\.$/;
+export function isGeneratedModule(text) {
+    const newline = text.indexOf('\n');
+    return HEADER.test(newline === -1 ? text : text.slice(0, newline));
+}
+// Every folder a query glob matches, sorted. Each `.sql` file directly inside one is a query
+// file; sqlc doesn't read subfolders, so each folder is its own block.
+export async function findQueryFolders(patterns) {
+    const folders = new Set();
+    for (const pattern of patterns) {
+        for await (const match of glob(pattern, {
+            exclude: (name) => {
+                const base = path.basename(name);
+                return base === 'node_modules' || base === '.git';
+            },
+        })) {
+            const full = path.resolve(match);
+            if ((await stat(full)).isDirectory())
+                folders.add(full);
+        }
+    }
+    return [...folders].sort();
+}
+// Whether a folder has a query sqlc will see. A folder of `.sql` files with no named query
+// makes sqlc fail ("no queries contained in paths"), so it gets no block.
+export async function hasNamedQueries(folder) {
+    for (const name of await sqlFiles(folder)) {
+        const text = await readFile(path.join(folder, name), 'utf8');
+        if (/^\s*--\s*name:/m.test(text))
+            return true;
+    }
+    return false;
+}
+async function sqlFiles(folder) {
+    const entries = await readdir(folder, { withFileTypes: true });
+    return entries.filter((e) => e.isFile() && e.name.endsWith('.sql')).map((e) => e.name);
+}
+// TECH-SPEC §9: puts a successful run's modules in place, and deletes generated modules the
+// run didn't produce, because their query file is gone or has no named queries.
+// It refuses, changing nothing, to overwrite a `.ts` file sequel didn't generate.
+export async function installModules(rendered, folders) {
+    const plan = await planModules(rendered, folders);
+    const clobbered = plan.changed.filter((change) => change.existing !== undefined && !isGeneratedModule(change.existing));
+    if (clobbered.length > 0) {
+        throw new SequelError(clobbered
+            .map(({ file }) => `${file} was not generated by sequel, and generating would overwrite it. Rename its query file, or move ${path.basename(file)} out of the query folder.`)
+            .join('\n'));
+    }
+    for (const { file, contents } of plan.changed)
+        await writeAtomically(file, contents);
+    for (const file of plan.orphaned)
+        await rm(file, { force: true });
+    return {
+        written: plan.changed.map((change) => change.file),
+        unchanged: plan.unchanged,
+        deleted: plan.orphaned,
+    };
+}
+// For `check`: compares a run's modules with those in place, byte for byte, writing nothing.
+export async function compareModules(rendered, folders) {
+    const plan = await planModules(rendered, folders);
+    return {
+        stale: plan.changed.filter((c) => c.existing !== undefined).map((c) => c.file),
+        missing: plan.changed.filter((c) => c.existing === undefined).map((c) => c.file),
+        orphaned: plan.orphaned,
+    };
+}
+async function planModules(rendered, folders) {
+    const plan = { changed: [], unchanged: [], orphaned: [] };
+    const allFolders = [...new Set([...folders, ...rendered.keys()])].sort();
+    for (const folder of allFolders) {
+        const modules = rendered.get(folder) ?? new Map();
+        for (const name of [...modules.keys()].sort()) {
+            const file = path.join(folder, name);
+            const contents = modules.get(name);
+            const existing = await readIfExists(file);
+            if (existing === contents)
+                plan.unchanged.push(file);
+            else
+                plan.changed.push({ file, contents, existing });
+        }
+        let entries;
+        try {
+            entries = (await readdir(folder, { withFileTypes: true }))
+                .filter((e) => e.isFile() && e.name.endsWith('.ts'))
+                .map((e) => e.name)
+                .sort();
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            if (modules.has(name))
+                continue;
+            const file = path.join(folder, name);
+            const text = await readIfExists(file);
+            if (text !== undefined && isGeneratedModule(text))
+                plan.orphaned.push(file);
+        }
+    }
+    return plan;
+}
+async function readIfExists(file) {
+    try {
+        return await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}

package/dist/generate/pg-dump.d.ts

@@ -0,0 +1,8 @@
+export declare function pgDumpMajor(versionOutput: string): number | null;
+export declare function checkPgDump(serverMajor: number, pgDump?: string): Promise<void>;
+export declare function serverMajor(databaseUrl: string): Promise<number>;
+export declare function dumpSchema(databaseUrl: string, file: string, pgDump?: string): Promise<void>;
+export declare function withoutPassword(databaseUrl: string): {
+    url: string;
+    password: string | undefined;
+};

package/dist/generate/pg-dump.js

@@ -0,0 +1,66 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import pg from 'pg';
+import { SequelError } from '../errors.js';
+const run = promisify(execFile);
+// The major version in `pg_dump --version`, such as 18 from `pg_dump (PostgreSQL) 18.6`.
+export function pgDumpMajor(versionOutput) {
+    const match = /\(PostgreSQL\)\s+(\d+)/.exec(versionOutput) ?? /\b(\d+)(?:\.\d+)?\b/.exec(versionOutput);
+    return match?.[1] === undefined ? null : Number(match[1]);
+}
+// TECH-SPEC §1: `pg_dump` must be on PATH, at the server's major version or newer.
+export async function checkPgDump(serverMajor, pgDump = 'pg_dump') {
+    let stdout;
+    try {
+        ;
+        ({ stdout } = await run(pgDump, ['--version']));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new SequelError(`pg_dump was not found on PATH. sequel needs it to read the test database's schema. Install the Postgres ${serverMajor} client tools, or newer, and put pg_dump on PATH.`);
+        }
+        throw error;
+    }
+    const major = pgDumpMajor(stdout);
+    if (major === null) {
+        throw new SequelError(`Could not read pg_dump's version from "${stdout.trim()}". Check that pg_dump on PATH is Postgres's.`);
+    }
+    if (major < serverMajor) {
+        throw new SequelError(`pg_dump on PATH is version ${major}, but the test database's server is Postgres ${serverMajor}. Install pg_dump ${serverMajor} or newer and put it first on PATH.`);
+    }
+}
+export async function serverMajor(databaseUrl) {
+    const client = new pg.Client({ connectionString: databaseUrl });
+    await client.connect();
+    try {
+        const result = await client.query('SHOW server_version_num');
+        return Math.floor(Number(result.rows[0]?.server_version_num) / 10_000);
+    }
+    finally {
+        await client.end();
+    }
+}
+// TECH-SPEC §9: `pg_dump --schema-only --no-owner --no-privileges` of the test database into
+// `file`. The password travels in `PGPASSWORD`, so `ps` never shows it.
+export async function dumpSchema(databaseUrl, file, pgDump = 'pg_dump') {
+    await checkPgDump(await serverMajor(databaseUrl), pgDump);
+    const { url, password } = withoutPassword(databaseUrl);
+    const env = { ...process.env };
+    if (password !== undefined)
+        env.PGPASSWORD = password;
+    try {
+        await run(pgDump, ['--schema-only', '--no-owner', '--no-privileges', '--file', file, '--dbname', url], { env, maxBuffer: 64 * 1024 * 1024 });
+    }
+    catch (error) {
+        const stderr = String(error.stderr ?? '').trim();
+        throw new SequelError(`pg_dump could not dump the test database's schema: ${stderr || error.message}`);
+    }
+}
+export function withoutPassword(databaseUrl) {
+    const parsed = new URL(databaseUrl);
+    if (parsed.password === '')
+        return { url: databaseUrl, password: undefined };
+    const password = decodeURIComponent(parsed.password);
+    parsed.password = '';
+    return { url: parsed.toString(), password };
+}

package/dist/generate/plugin-wrapper.d.ts

@@ -0,0 +1,3 @@
+export declare function generatorEntry(): string;
+export declare function writePluginWrapper(dir: string, node?: string, entry?: string): Promise<string>;
+export declare function shellQuote(value: string): string;

package/dist/generate/plugin-wrapper.js

@@ -0,0 +1,20 @@
+import { chmod, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+// The generator's entry: `main.ts` from source, `main.js` from the published `dist/`.
+export function generatorEntry() {
+    const here = fileURLToPath(import.meta.url);
+    return path.join(path.dirname(here), '..', 'generator', `main${path.extname(here)}`);
+}
+// sqlc runs a process plugin with no `PATH`, so `#!/usr/bin/env node` can't start. Each run
+// writes a `#!/bin/sh` wrapper that `exec`s this Node on the generator's entry (TECH-SPEC §9,
+// R1), and points the plugin's `cmd` at it.
+export async function writePluginWrapper(dir, node = process.execPath, entry = generatorEntry()) {
+    const file = path.join(dir, 'sequel-generator.sh');
+    await writeFile(file, `#!/bin/sh\nexec ${shellQuote(node)} ${shellQuote(entry)} "$@"\n`);
+    await chmod(file, 0o755);
+    return file;
+}
+export function shellQuote(value) {
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}

package/dist/generate/sqlc.d.ts

@@ -0,0 +1,27 @@
+import type { BigintMode } from '../config/define-config.ts';
+export type Block = {
+    queries: string;
+    out: string;
+};
+export declare const DATABASE_URL_VARIABLE = "SEQUEL_SQLC_DATABASE_URL";
+export declare function pluginName(index: number): string;
+export declare function sqlcConfig(options: {
+    configDir: string;
+    schema: string;
+    blocks: Block[];
+    wrapper: string;
+    bigint: BigintMode;
+}): object;
+export declare function writeSqlcConfig(file: string, config: object): Promise<void>;
+export type SqlcRun = {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+};
+export declare function runSqlc(sqlc: string, command: 'generate' | 'diff', configFile: string, databaseUrl: string): Promise<SqlcRun>;
+export declare function readFailures(output: string, options: {
+    configDir: string;
+    blocks: Block[];
+    root: string;
+}): string[];
+export declare function nameLine(file: string, query: string): number | undefined;

package/dist/generate/sqlc.js

@@ -0,0 +1,113 @@
+import { execFile } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import path from 'node:path';
+// sqlc reads the test database's URL from this variable, through `${…}` in `database.uri`,
+// so the URL, and any password in it, is never written to disk.
+export const DATABASE_URL_VARIABLE = 'SEQUEL_SQLC_DATABASE_URL';
+// The plugin entry for block `i`. sqlc heads each block's failures with
+// `# package <plugin>`, so a plugin per block tells failures apart by folder.
+export function pluginName(index) {
+    return `sequel-${index}`;
+}
+// TECH-SPEC §9: sqlc's config, one `sql` block per folder of query files, typed by the
+// database analyzer against the test database. sqlc joins every path onto the config's own
+// folder, even an absolute one, so paths are written relative to `configDir`.
+export function sqlcConfig(options) {
+    const relative = (to) => path.relative(options.configDir, to) || '.';
+    return {
+        version: '2',
+        plugins: options.blocks.map((_, i) => ({
+            name: pluginName(i),
+            process: { cmd: options.wrapper, format: 'json' },
+        })),
+        sql: options.blocks.map((block, i) => ({
+            engine: 'postgresql',
+            schema: relative(options.schema),
+            queries: relative(block.queries),
+            database: { uri: `\${${DATABASE_URL_VARIABLE}}` },
+            analyzer: { database: true },
+            codegen: [
+                { plugin: pluginName(i), out: relative(block.out), options: { bigint: options.bigint } },
+            ],
+        })),
+    };
+}
+export async function writeSqlcConfig(file, config) {
+    await writeFile(file, `${JSON.stringify(config, null, 2)}\n`);
+}
+// Runs `sqlc generate` or `sqlc diff` on a config, with the test database's URL in the
+// environment.
+export function runSqlc(sqlc, command, configFile, databaseUrl) {
+    return new Promise((resolve, reject) => {
+        execFile(sqlc, [command, '-f', configFile], {
+            cwd: path.dirname(configFile),
+            env: { ...process.env, [DATABASE_URL_VARIABLE]: databaseUrl },
+            maxBuffer: 64 * 1024 * 1024,
+        }, (error, stdout, stderr) => {
+            if (error !== null && typeof error.code !== 'number') {
+                reject(error);
+                return;
+            }
+            resolve({ exitCode: error === null ? 0 : error.code, stdout, stderr });
+        });
+    });
+}
+const PLUGIN_PREFIX = 'error generating code: process: error running command ';
+// Turns sqlc's failure output into one line per failure, each naming its file, relative to
+// `root`, and line. sqlc's own errors carry `path:line:col`. The generator's carry only
+// `<file>: <query>`, so the line is that of the query's `-- name:` comment (R57).
+export function readFailures(output, options) {
+    const failures = [];
+    let block;
+    for (const raw of output.split('\n')) {
+        const header = /^# package (.*)$/.exec(raw);
+        if (header !== null) {
+            block = options.blocks.find((_, i) => pluginName(i) === header[1]);
+            continue;
+        }
+        const line = raw.startsWith(PLUGIN_PREFIX) ? raw.slice(PLUGIN_PREFIX.length) : raw;
+        if (line.trim() === '')
+            continue;
+        const own = /^(.+?\.sql):(\d+):(\d+): (.*)$/.exec(line);
+        if (own !== null) {
+            const [, file = '', row, column, message] = own;
+            const shown = path.relative(options.root, path.resolve(options.configDir, file));
+            failures.push(`${shown}:${row}:${column}: ${message}`);
+            continue;
+        }
+        const fileOnly = /^([^:]+): (query file name must end in \.sql)$/.exec(line);
+        if (fileOnly !== null && block !== undefined) {
+            const shown = path.relative(options.root, path.join(block.queries, fileOnly[1] ?? ''));
+            failures.push(`${shown}: ${fileOnly[2]}`);
+            continue;
+        }
+        const generator = /^([^:]+\.sql): ([^\s:]+): (.*)$/.exec(line);
+        if (generator !== null && block !== undefined) {
+            const [, file = '', query = '', message] = generator;
+            const full = path.join(block.queries, file);
+            const lineNumber = nameLine(full, query);
+            const shown = path.relative(options.root, full);
+            failures.push(`${shown}${lineNumber === undefined ? '' : `:${lineNumber}`}: ${query}: ${message}`);
+            continue;
+        }
+        failures.push(line);
+    }
+    return failures;
+}
+// The 1-based line of `-- name: <query>` in `file`.
+export function nameLine(file, query) {
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    const pattern = new RegExp(`^\\s*--\\s*name:\\s*${escapeRegExp(query)}(\\s|$)`);
+    const index = text.split('\n').findIndex((line) => pattern.test(line));
+    return index === -1 ? undefined : index + 1;
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/generate/watch.d.ts

@@ -0,0 +1,16 @@
+export declare function createRerunScheduler(options: {
+    run: () => Promise<void>;
+    onError: (error: unknown) => void;
+    debounceMs?: number;
+}): {
+    trigger: () => void;
+    settled(): Promise<void>;
+    stop(): void;
+};
+export declare function watchAndRerun(options: {
+    folders: string[];
+    run: () => Promise<void>;
+    onError: (error: unknown) => void;
+    signal: AbortSignal;
+    debounceMs?: number;
+}): Promise<void>;