@bockit/sequel 0.0.0-stage → 0.1.0

package/dist/db/shadow.js

@@ -0,0 +1,68 @@
+import { randomBytes } from 'node:crypto';
+import path from 'node:path';
+import { SequelError } from '../errors.js';
+import { databaseName, quoteIdent, redactUrl, withClient, withDatabaseName } from './connection.js';
+// TECH-SPEC §8: every code path that wipes or drops a database checks its name first.
+export function assertShadowName(name) {
+    if (!name.endsWith('_shadow')) {
+        throw new SequelError(`Refusing to wipe the database \`${name}\`: sequel only wipes shadow databases, whose names end in \`_shadow\`.`);
+    }
+}
+// Where a command's shadow database comes from: the fixed one if the config names it, else one
+// of its own on the test database's server.
+export function shadowOptions(config) {
+    const { shadow, test } = config.databases;
+    if (shadow !== undefined)
+        return { fixedUrl: shadow };
+    if (test !== undefined)
+        return { testUrl: test };
+    throw new SequelError(`${path.basename(config.configFile)}: sequel needs a shadow database, and neither \`databases.test\` nor \`databases.shadow\` is set. Set \`databases.test\`, and sequel creates one on its server for each run, or set \`databases.shadow\` to a database whose name ends in \`_shadow\`.`);
+}
+// Runs `fn` with an empty shadow database. By default it is a new `sequel_<random>_shadow` on
+// the test database's server, dropped afterwards, even on failure or interruption.
+export async function withShadowDatabase(options, fn) {
+    if ('fixedUrl' in options) {
+        await wipeShadowDatabase(options.fixedUrl);
+        return fn(options.fixedUrl);
+    }
+    const name = `sequel_${randomBytes(6).toString('hex')}_shadow`;
+    try {
+        await withClient(options.testUrl, (client) => client.query(`CREATE DATABASE ${quoteIdent(name)}`));
+    }
+    catch (error) {
+        throw new SequelError(`Could not create a shadow database on the test database's server (${redactUrl(options.testUrl)}): ${error.message}\nThe test database's role needs CREATEDB. Where it can't have it, set \`databases.shadow\` to a fixed database whose name ends in \`_shadow\`.`);
+    }
+    const drop = () => dropShadowDatabase(options.testUrl, name);
+    const onSignal = (signal) => {
+        void drop().finally(() => process.exit(signal === 'SIGINT' ? 130 : 143));
+    };
+    process.once('SIGINT', onSignal);
+    process.once('SIGTERM', onSignal);
+    try {
+        return await fn(withDatabaseName(options.testUrl, name));
+    }
+    finally {
+        process.off('SIGINT', onSignal);
+        process.off('SIGTERM', onSignal);
+        await drop();
+    }
+}
+// Drops a shadow database through a connection to another database on its server.
+export async function dropShadowDatabase(serverUrl, name) {
+    assertShadowName(name);
+    await withClient(serverUrl, (client) => client.query(`DROP DATABASE IF EXISTS ${quoteIdent(name)} WITH (FORCE)`));
+}
+// Empties a fixed shadow database in place, for a role that can't create databases: every
+// schema but Postgres's own is dropped, extensions with it, and `public` is recreated.
+export async function wipeShadowDatabase(url) {
+    assertShadowName(databaseName(url));
+    await withClient(url, async (client) => {
+        const { rows } = await client.query(`SELECT nspname FROM pg_namespace
+       WHERE nspname NOT LIKE 'pg\\_%' AND nspname <> 'information_schema'
+       ORDER BY nspname`);
+        for (const { nspname } of rows) {
+            await client.query(`DROP SCHEMA ${quoteIdent(nspname)} CASCADE`);
+        }
+        await client.query('CREATE SCHEMA public');
+    });
+}

package/dist/engine/client.d.ts

@@ -0,0 +1,24 @@
+export type EngineCall<T> = {
+    result: T;
+    printed: string[];
+};
+export type Engine = {
+    request<T>(method: string, params: unknown): Promise<EngineCall<T>>;
+    close(): Promise<void>;
+};
+export declare class EngineError extends Error {
+    name: string;
+    readonly code: number;
+    readonly data: {
+        error_code?: string;
+        message?: string;
+        is_panic?: boolean;
+    } | undefined;
+    constructor(code: number, message: string, data: EngineError['data']);
+}
+export declare function startSchemaEngine(binary: string, cwd: string): Engine;
+export declare function startEngine(options: {
+    command: string;
+    args: string[];
+    cwd: string;
+}): Engine;

package/dist/engine/client.js

@@ -0,0 +1,123 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+// A JSON-RPC error from the engine. `data` carries the engine's own error, such as
+// `{ error_code: 'P1003', message: 'Database … does not exist' }`.
+export class EngineError extends Error {
+    name = 'EngineError';
+    code;
+    data;
+    constructor(code, message, data) {
+        super(data?.message ?? message);
+        this.code = code;
+        this.data = data;
+    }
+}
+// Spawns the native schema engine. The 7.x engine won't start without `--datasource`; the
+// connection travels in each request, so the flag is always `{}`, and `ps` never shows a URL.
+export function startSchemaEngine(binary, cwd) {
+    return startEngine({ command: binary, args: ['--datasource', '{}'], cwd });
+}
+export function startEngine(options) {
+    const child = spawn(options.command, options.args, {
+        cwd: options.cwd,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    let stderr = '';
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk) => {
+        stderr += chunk;
+    });
+    // A write after the engine has gone fails here, and the call is rejected by `gone` instead.
+    child.stdin.on('error', () => { });
+    let nextId = 1;
+    let current;
+    let ended;
+    const send = (message) => child.stdin.write(`${JSON.stringify(message)}\n`);
+    const gone = (reason) => {
+        if (ended !== undefined)
+            return;
+        ended = new Error(`The schema engine ${reason}.${stderr.trim() === '' ? '' : `\nIts stderr:\n${stderr.trim()}`}`);
+        current?.reject(ended);
+        current = undefined;
+    };
+    child.on('error', (error) => gone(`could not run: ${error.message}`));
+    child.on('exit', (code, signal) => gone(`exited${signal ? ` on ${signal}` : ` with code ${code}`}`));
+    const lines = createInterface({ input: child.stdout });
+    lines.on('close', () => gone('closed its output'));
+    lines.on('line', (line) => {
+        if (line.trim() === '')
+            return;
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            stderr += `${line}\n`;
+            return;
+        }
+        if (typeof message.method === 'string') {
+            // A request from the engine. A notification, with no id, needs no answer.
+            if (message.id === undefined || message.id === null)
+                return;
+            if (message.method === 'print') {
+                if (typeof message.params?.content === 'string') {
+                    current?.printed.push(message.params.content);
+                }
+                send({ id: message.id, jsonrpc: '2.0', result: {} });
+            }
+            else {
+                send({
+                    id: message.id,
+                    jsonrpc: '2.0',
+                    error: { code: -32601, message: `sequel does not handle ${message.method}` },
+                });
+            }
+            return;
+        }
+        if (current !== undefined && message.id === current.id)
+            current.resolve(message);
+    });
+    let queue = Promise.resolve();
+    const call = (method, params) => new Promise((resolve, reject) => {
+        if (ended !== undefined) {
+            reject(ended);
+            return;
+        }
+        const id = nextId++;
+        const printed = [];
+        current = {
+            id,
+            printed,
+            resolve: (message) => {
+                current = undefined;
+                if (message.error !== undefined) {
+                    const { code, message: text, data } = message.error;
+                    reject(new EngineError(code, text, data));
+                }
+                else {
+                    resolve({ result: message.result, printed });
+                }
+            },
+            reject,
+        };
+        send({ jsonrpc: '2.0', id, method, params });
+    });
+    return {
+        request(method, params) {
+            const next = queue.then(() => call(method, params));
+            queue = next.catch(() => { });
+            return next;
+        },
+        async close() {
+            ended ??= new Error('The schema engine was closed.');
+            if (child.exitCode !== null || child.signalCode !== null)
+                return;
+            const exited = new Promise((resolve) => child.once('exit', () => resolve()));
+            child.stdin.end();
+            const timer = setTimeout(() => child.kill('SIGKILL'), 2_000);
+            child.kill('SIGTERM');
+            await exited;
+            clearTimeout(timer);
+        },
+    };
+}

package/dist/engine/diff.d.ts

@@ -0,0 +1,12 @@
+import type { SchemaFile } from '../schema/schema.ts';
+import { type Engine } from './client.ts';
+export type DiffResult = {
+    changed: boolean;
+    sql: string;
+};
+export type DiffFrom = {
+    url: string;
+    historySchema: string;
+} | 'empty';
+export declare function diffToSchema(engine: Engine, from: DiffFrom, files: SchemaFile[]): Promise<DiffResult>;
+export declare function engineUrl(url: string): string;

package/dist/engine/diff.js

@@ -0,0 +1,51 @@
+import pg from 'pg';
+import { databaseName, redactUrl } from '../db/connection.js';
+import { SequelError } from '../errors.js';
+import { HISTORY_TABLE } from '../migrate/history.js';
+import { EngineError } from './client.js';
+// TECH-SPEC §7: the engine's `diff`, from a database (a shadow with the migrations replayed
+// into it), or from nothing, to the schema folder.
+export async function diffToSchema(engine, from, files) {
+    const params = {
+        from: from === 'empty' ? { tag: 'empty' } : { tag: 'url', url: engineUrl(from.url) },
+        to: {
+            tag: 'schemaDatamodel',
+            files: files.map((file) => ({ path: file.relative, content: file.content })),
+        },
+        script: true,
+        exitCode: true,
+        filters: {
+            // The engine ignores only `_prisma_migrations`, so it would drop sequel's history as drift.
+            externalTables: from === 'empty' ? [] : [`${from.historySchema}.${HISTORY_TABLE}`],
+            externalEnums: [],
+        },
+    };
+    try {
+        const { result, printed } = await engine.request('diff', params);
+        return {
+            changed: result.exitCode === 2,
+            sql: printed.map((content) => `${content}\n`).join(''),
+        };
+    }
+    catch (error) {
+        const source = from === 'empty' ? 'an empty database' : databaseName(from.url);
+        if (error instanceof EngineError) {
+            const code = error.data?.error_code;
+            throw new SequelError(`The schema engine could not diff ${source} against the schema folder: ${code === undefined ? '' : `${code}: `}${error.message}`);
+        }
+        throw new SequelError(`The schema engine failed while diffing ${source} against the schema folder: ${error.message}`);
+    }
+}
+// The engine doesn't default the user as `pg` does, so a URL without one gets `pg`'s default,
+// such as the OS user, before the engine sees it.
+export function engineUrl(url) {
+    const parsed = new URL(url);
+    if (parsed.username === '') {
+        const user = process.env.PGUSER || pg.defaults.user;
+        if (user === undefined || user === '') {
+            throw new SequelError(`${redactUrl(url)} names no user, and there is no default to fill in. Put the user in the URL.`);
+        }
+        parsed.username = encodeURIComponent(user);
+    }
+    return parsed.toString();
+}

package/dist/errors.d.ts

@@ -0,0 +1,3 @@
+export declare class SequelError extends Error {
+    name: string;
+}

package/dist/errors.js

@@ -0,0 +1,5 @@
+// An expected failure: the CLI prints its message, with no stack, and exits 1.
+// The message names the file, query or statement, and what to do about it.
+export class SequelError extends Error {
+    name = 'SequelError';
+}

package/dist/extras/snapshot.d.ts

@@ -0,0 +1,3 @@
+import type pg from 'pg';
+export declare function readExtrasSnapshot(url: string): Promise<string>;
+export declare function extrasSnapshot(client: pg.Client): Promise<string>;

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;
+    }
+}