@mistriwork/engine 0.0.0 → 1.0.0-rc.10

package/dist/shared/mount.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Where a server's Apps are mounted, and the path it is served under: the one
+ * rule every address passes through on its way in and out.
+ *
+ * Inside tablewalk an App's address is always `/{app}/…` — the walk, the
+ * address book (appAddress.ts), the route table and every link the client
+ * builds say it so. What the browser shows is decided here, once:
+ *
+ *   - a server serving one App serves it at the root: `/leases/12`;
+ *   - several Apps each keep `/{app}`, and one of them may be the main App at
+ *     the root (`--mount main=/`), the others under their own segment;
+ *   - an explicit mount (`--mount lintel=/lintel`, config `"mount"`)
+ *     overrides either default;
+ *   - and the whole server may sit under a prefix a reverse proxy serves it
+ *     at (`--base-path /tools`): `https://host/tools/leases/12`.
+ *
+ * `outward` turns an inside address into the one the browser shows, and
+ * `inward` reads one back. The server reads every request through `inward`
+ * and writes every address it sends (a redirect, a canonical link, a mail's
+ * link, a cookie's path) through `outward`; the client does the same at the
+ * address bar, its links and its fetches (client addressMount.js). There are no
+ * aliases: whichever form applies is the only spelling, and an address in
+ * another form names nothing.
+ *
+ * The standalone database browser mounts nothing, so every address is its
+ * own — only a base path, when one is given, is added and taken off.
+ *
+ * Pure and dependency-free, so the server, the client and `mistri check`
+ * cannot disagree.
+ */
+export interface AddressMount {
+    /** The path the server is served under: '' or `/tools`, never a trailing slash. */
+    base: string;
+    /** Each served App's mount, by id: '' at the root, else its one segment. */
+    apps: Readonly<Record<string, string>>;
+}
+/** No Apps and no prefix: every address is its own. */
+export declare const NO_MOUNT: AddressMount;
+/**
+ * First segments the server answers at its root whatever it serves: the API,
+ * the built client's files, `_mistri` — the custom components' host
+ * modules and tablewalk's own tools, the dev observer among them — and an
+ * orchestrator's `healthz` and `readyz` probes, and a crawler's `robots.txt`
+ * and `sitemap.xml` (http/sitemap.ts). No App is mounted at one, and
+ * an App at the root cannot route to one.
+ */
+export declare const SERVER_SEGMENTS: readonly string[];
+/**
+ * A base path as written — `/tools`, `/tools/`, `tools`, `/a/b` — made
+ * canonical (`/tools`), or a refusal that names the fix. '' and '/' are no
+ * base at all.
+ */
+export declare function parseBasePath(value: string, at?: string): string;
+/**
+ * One App's mount as written — `/` for the root, `/billing` (or `billing`)
+ * for a segment — into its stored form ('' or `billing`).
+ */
+export declare function parseMountPath(value: string, at: string): string;
+/**
+ * The mounts of the Apps a server serves: one App at the root, several each
+ * under its id, and whatever `explicit` says over either. Throws, naming the
+ * App, on a mount that names no served App, two Apps at one place, or an
+ * App id the server's own paths already hold.
+ */
+export declare function appMounts(ids: readonly string[], explicit?: {
+    base?: string;
+    mounts?: Readonly<Record<string, string>>;
+}): AddressMount;
+/**
+ * The mounts as a deployment writes them — `--mount`/`--base-path` over the
+ * config's `"mount"`/`"basePath"` — for these Apps. The server, `check
+ * --routes` and `shot` all start here, so they read one deployment alike.
+ */
+export declare function settingsMount(ids: readonly string[], flags: {
+    mounts?: Readonly<Record<string, string>>;
+    basePath?: string;
+}, config?: {
+    mount?: Readonly<Record<string, string>>;
+    basePath?: string;
+}): AddressMount;
+/** The App mounted at the root, if any. */
+export declare function rootApp(mount: AddressMount): string | undefined;
+/**
+ * The words an App at the root cannot route to beyond its own reserved ones:
+ * every other App's segment, by its id, which the server reads first.
+ */
+export declare function segmentsTakenFrom(mount: AddressMount, app: string): Record<string, string>;
+/** An App's home as the browser shows it: `/`, `/billing`, `/tools/`, `/tools/billing`. */
+export declare function appHome(mount: AddressMount, app: string): string;
+/**
+ * An inside address as the browser shows it. `/lintel/leases/12` is
+ * `/leases/12` with Lintel at the root, `/tools/leases/12` under a base; a
+ * server path (`/api/…`) only gains the base. Any `?search` and `#hash` ride
+ * along untouched.
+ */
+export declare function outward(mount: AddressMount, internal: string): string;
+/**
+ * An address as the browser sent it, read back to the inside form; undefined
+ * for one outside the base path or naming an App the way it is not mounted —
+ * the spelling that applies is the only one.
+ */
+export declare function inward(mount: AddressMount, external: string): string | undefined;
+/** A server path (`/api/…`, `/_mistri/…`) under the base. */
+export declare const serverPath: (mount: AddressMount, path: string) => string;
+/** A Set-Cookie value with its `Path=/…` said under the base, so the browser sends it back where the proxy serves the server. */
+export declare const cookieUnder: (base: string, cookie: string) => string;
+/** The mount as a page carries it to the client (client addressMount.js): compact, and nothing but these two. */
+export declare function mountJson(mount: AddressMount): string;
+/** A page's mount, read back; anything malformed is no mount, which is how a page with none behaves. */
+export declare function readMountJson(text: string | null | undefined): AddressMount;
+/**
+ * The public URL (MISTRI_PUBLIC_URL) as the root every outward address is
+ * appended to: no trailing slash, and without the base path where it was
+ * written with it. A link adds the base itself, so `https://host/desk` with
+ * `--base-path /desk` became `/desk/desk` — sign-in answered 404 and looped.
+ * Both spellings name the one place; a URL that is not one is left as given.
+ */
+export declare function publicRoot(url: string, base: string): string;

package/dist/shared/mount.js

@@ -0,0 +1,248 @@
+/**
+ * Where a server's Apps are mounted, and the path it is served under: the one
+ * rule every address passes through on its way in and out.
+ *
+ * Inside tablewalk an App's address is always `/{app}/…` — the walk, the
+ * address book (appAddress.ts), the route table and every link the client
+ * builds say it so. What the browser shows is decided here, once:
+ *
+ *   - a server serving one App serves it at the root: `/leases/12`;
+ *   - several Apps each keep `/{app}`, and one of them may be the main App at
+ *     the root (`--mount main=/`), the others under their own segment;
+ *   - an explicit mount (`--mount lintel=/lintel`, config `"mount"`)
+ *     overrides either default;
+ *   - and the whole server may sit under a prefix a reverse proxy serves it
+ *     at (`--base-path /tools`): `https://host/tools/leases/12`.
+ *
+ * `outward` turns an inside address into the one the browser shows, and
+ * `inward` reads one back. The server reads every request through `inward`
+ * and writes every address it sends (a redirect, a canonical link, a mail's
+ * link, a cookie's path) through `outward`; the client does the same at the
+ * address bar, its links and its fetches (client addressMount.js). There are no
+ * aliases: whichever form applies is the only spelling, and an address in
+ * another form names nothing.
+ *
+ * The standalone database browser mounts nothing, so every address is its
+ * own — only a base path, when one is given, is added and taken off.
+ *
+ * Pure and dependency-free, so the server, the client and `mistri check`
+ * cannot disagree.
+ */
+/** No Apps and no prefix: every address is its own. */
+export const NO_MOUNT = Object.freeze({ base: '', apps: Object.freeze({}) });
+/**
+ * First segments the server answers at its root whatever it serves: the API,
+ * the built client's files, `_mistri` — the custom components' host
+ * modules and tablewalk's own tools, the dev observer among them — and an
+ * orchestrator's `healthz` and `readyz` probes, and a crawler's `robots.txt`
+ * and `sitemap.xml` (http/sitemap.ts). No App is mounted at one, and
+ * an App at the root cannot route to one.
+ */
+export const SERVER_SEGMENTS = ['api', 'assets', '_mistri', 'healthz', 'readyz', 'robots.txt', 'sitemap.xml'];
+/** One mount segment: the letters an App id and a route path allow. */
+const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+/**
+ * A base path as written — `/tools`, `/tools/`, `tools`, `/a/b` — made
+ * canonical (`/tools`), or a refusal that names the fix. '' and '/' are no
+ * base at all.
+ */
+export function parseBasePath(value, at = 'the base path') {
+    const trimmed = value.trim();
+    if (trimmed === '' || trimmed === '/')
+        return '';
+    const segments = trimmed.replace(/^\/+/, '').replace(/\/+$/, '').split('/');
+    if (segments.some((segment) => !SEGMENT.test(segment))) {
+        throw new Error(`${at}: "${value}" must be a path like /tools — segments of letters, digits, hyphens and underscores.`);
+    }
+    return `/${segments.join('/')}`;
+}
+/**
+ * One App's mount as written — `/` for the root, `/billing` (or `billing`)
+ * for a segment — into its stored form ('' or `billing`).
+ */
+export function parseMountPath(value, at) {
+    const trimmed = value.trim();
+    if (trimmed === '/')
+        return '';
+    const segment = trimmed.replace(/^\/+/, '').replace(/\/+$/, '');
+    if (!SEGMENT.test(segment))
+        throw new Error(`${at}: "${value}" must be "/" (the root) or one segment, like "/billing".`);
+    if (SERVER_SEGMENTS.includes(segment))
+        throw new Error(`${at}: "${value}" is the server's own (${SERVER_SEGMENTS.join(', ')}); mount the App elsewhere.`);
+    return segment;
+}
+/**
+ * The mounts of the Apps a server serves: one App at the root, several each
+ * under its id, and whatever `explicit` says over either. Throws, naming the
+ * App, on a mount that names no served App, two Apps at one place, or an
+ * App id the server's own paths already hold.
+ */
+export function appMounts(ids, explicit = {}) {
+    const base = explicit.base ?? '';
+    const mounts = explicit.mounts ?? {};
+    for (const id of Object.keys(mounts)) {
+        if (!ids.includes(id))
+            throw new Error(`--mount names "${id}", which is not an App this server serves${ids.length ? ` (${ids.join(', ')})` : ''}.`);
+    }
+    const apps = {};
+    for (const id of ids) {
+        apps[id] = Object.hasOwn(mounts, id) ? mounts[id] : ids.length === 1 ? '' : id;
+        if (apps[id] !== '' && SERVER_SEGMENTS.includes(apps[id])) {
+            throw new Error(`The App "${id}" would be mounted at /${apps[id]}, which is the server's own; mount it elsewhere with --mount ${id}=/<segment>.`);
+        }
+    }
+    const held = new Map();
+    for (const [id, at] of Object.entries(apps)) {
+        const other = held.get(at);
+        if (other !== undefined) {
+            throw new Error(at === ''
+                ? `The Apps "${other}" and "${id}" are both mounted at the root; only one App can be the main App.`
+                : `The Apps "${other}" and "${id}" are both mounted at /${at}; give one of them another --mount.`);
+        }
+        held.set(at, id);
+    }
+    return { base, apps };
+}
+/**
+ * The mounts as a deployment writes them — `--mount`/`--base-path` over the
+ * config's `"mount"`/`"basePath"` — for these Apps. The server, `check
+ * --routes` and `shot` all start here, so they read one deployment alike.
+ */
+export function settingsMount(ids, flags, config = {}) {
+    const written = { ...config.mount, ...flags.mounts };
+    const mounts = Object.fromEntries(Object.entries(written).map(([id, at]) => [id, parseMountPath(at, `--mount ${id}`)]));
+    return appMounts(ids, { base: parseBasePath(flags.basePath ?? config.basePath ?? '', '--base-path'), mounts });
+}
+/** The App mounted at the root, if any. */
+export function rootApp(mount) {
+    return Object.entries(mount.apps).find(([, at]) => at === '')?.[0];
+}
+/**
+ * The words an App at the root cannot route to beyond its own reserved ones:
+ * every other App's segment, by its id, which the server reads first.
+ */
+export function segmentsTakenFrom(mount, app) {
+    if (mount.apps[app] !== '')
+        return {};
+    return Object.fromEntries(Object.entries(mount.apps).filter(([id, at]) => id !== app && at !== ''));
+}
+const splitTail = (path) => {
+    const at = path.search(/[?#]/);
+    return at < 0 ? [path, ''] : [path.slice(0, at), path.slice(at)];
+};
+const decoded = (segment) => {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return undefined;
+    }
+};
+/** An App's home as the browser shows it: `/`, `/billing`, `/tools/`, `/tools/billing`. */
+export function appHome(mount, app) {
+    return outward(mount, `/${encodeURIComponent(app)}`);
+}
+/**
+ * An inside address as the browser shows it. `/lintel/leases/12` is
+ * `/leases/12` with Lintel at the root, `/tools/leases/12` under a base; a
+ * server path (`/api/…`) only gains the base. Any `?search` and `#hash` ride
+ * along untouched.
+ */
+export function outward(mount, internal) {
+    const [path, tail] = splitTail(internal);
+    const first = path.split('/')[1] ?? '';
+    const app = first ? decoded(first) : undefined;
+    if (app !== undefined && path.startsWith('/') && Object.hasOwn(mount.apps, app)) {
+        const rest = path.slice(1 + first.length);
+        const at = mount.apps[app];
+        const said = `${at ? `/${encodeURIComponent(at)}` : ''}${rest}`;
+        return `${mount.base}${said || '/'}${tail}`;
+    }
+    return `${mount.base}${path}${tail}`;
+}
+/**
+ * An address as the browser sent it, read back to the inside form; undefined
+ * for one outside the base path or naming an App the way it is not mounted —
+ * the spelling that applies is the only one.
+ */
+export function inward(mount, external) {
+    const [whole, tail] = splitTail(external);
+    let path = whole;
+    if (mount.base) {
+        if (path !== mount.base && !path.startsWith(`${mount.base}/`))
+            return undefined;
+        path = path.slice(mount.base.length) || '/';
+    }
+    const ids = Object.keys(mount.apps);
+    if (!ids.length)
+        return path + tail;
+    const first = path.split('/')[1] ?? '';
+    const segment = first ? decoded(first) : undefined;
+    const rest = path.slice(1 + first.length);
+    if (segment !== undefined && SERVER_SEGMENTS.includes(segment))
+        return path + tail;
+    if (segment !== undefined && segment !== '') {
+        const mounted = ids.find((id) => mount.apps[id] === segment);
+        if (mounted !== undefined)
+            return `/${encodeURIComponent(mounted)}${rest}${tail}`;
+    }
+    const root = rootApp(mount);
+    if (root !== undefined)
+        return `/${encodeURIComponent(root)}${path === '/' ? '' : path}${tail}`;
+    // An App's id where it is mounted under another name is no address of it.
+    if (segment !== undefined && ids.includes(segment))
+        return undefined;
+    return path + tail;
+}
+/** A server path (`/api/…`, `/_mistri/…`) under the base. */
+export const serverPath = (mount, path) => `${mount.base}${path}`;
+/** A Set-Cookie value with its `Path=/…` said under the base, so the browser sends it back where the proxy serves the server. */
+export const cookieUnder = (base, cookie) => (base ? cookie.replace(/(;\s*Path=)\//i, `$1${base}/`) : cookie);
+/** The mount as a page carries it to the client (client addressMount.js): compact, and nothing but these two. */
+export function mountJson(mount) {
+    return JSON.stringify({ base: mount.base, apps: mount.apps });
+}
+/** A page's mount, read back; anything malformed is no mount, which is how a page with none behaves. */
+export function readMountJson(text) {
+    if (!text)
+        return NO_MOUNT;
+    try {
+        const value = JSON.parse(text);
+        // Internal hosts such as Console live under the reserved /_mistri
+        // segment, optionally below a suite base. Preserve their server-owned base.
+        const base = typeof value.base === 'string' && (value.base === '' || /^(\/(?:[A-Za-z0-9][A-Za-z0-9_-]*|_mistri))+$/.test(value.base))
+            ? value.base
+            : '';
+        const apps = {};
+        if (value.apps && typeof value.apps === 'object') {
+            for (const [id, at] of Object.entries(value.apps))
+                if (typeof at === 'string')
+                    apps[id] = at;
+        }
+        return { base, apps };
+    }
+    catch {
+        return NO_MOUNT;
+    }
+}
+/**
+ * The public URL (MISTRI_PUBLIC_URL) as the root every outward address is
+ * appended to: no trailing slash, and without the base path where it was
+ * written with it. A link adds the base itself, so `https://host/desk` with
+ * `--base-path /desk` became `/desk/desk` — sign-in answered 404 and looped.
+ * Both spellings name the one place; a URL that is not one is left as given.
+ */
+export function publicRoot(url, base) {
+    const trimmed = url.replace(/\/+$/, '');
+    if (!base)
+        return trimmed;
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        return trimmed;
+    }
+    const path = parsed.pathname.replace(/\/+$/, '');
+    return path === base || path.endsWith(base) ? `${parsed.origin}${path.slice(0, -base.length)}` : trimmed;
+}

package/dist/shared/niceTicks.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The levels an axis is ruled at: round numbers that cover the figures. An
+ * axis ruled at its own minimum, middle and maximum said "$0 / $2,039.50 /
+ * $4,079" — exact, and unreadable at a glance; a reader takes in "$0 / $2K /
+ * $4K" without reading it. The step is a one, two or five of a power of ten,
+ * chosen for about `intervals` steps across the range (the 1-2-5 rule, after
+ * d3's `ticks`), and the scale is widened to the step's multiples on either
+ * side, so the highest figure never stands over the top rule.
+ */
+interface NiceScale {
+    /** The scale's low end: a multiple of the step at or under the smallest figure. */
+    min: number;
+    /** The scale's high end: a multiple of the step at or over the largest figure. */
+    max: number;
+    step: number;
+    /** Every level from `min` to `max`, a step apart. */
+    levels: number[];
+}
+/** The round steps of a time taken, in seconds: a minute, five, a quarter hour, half, an hour, two, three, six,
+    twelve, a day, two, three, a week, two, thirty days. A duration axis is ruled at "2d / 4d / 6d", not at
+    the decimal 1-2-5 steps of its seconds ("2d 7h"). */
+export declare const DURATION_STEPS: readonly number[];
+/** Round levels over `[low, high]`; a flat range is given a step of room above it. `steps`, where given, are the
+    only steps an axis may take (DURATION_STEPS), the one covering the range most closely in two to four. */
+export declare function niceScale(low: number, high: number, intervals?: number, steps?: readonly number[]): NiceScale;
+export {};

package/dist/shared/niceTicks.js

@@ -0,0 +1,50 @@
+function niceStep(span, intervals = 2) {
+    const raw = span / Math.max(1, intervals);
+    if (!(raw > 0) || !Number.isFinite(raw))
+        return 1;
+    const power = 10 ** Math.floor(Math.log10(raw));
+    const error = raw / power;
+    return power * (error >= Math.sqrt(50) ? 10 : error >= Math.sqrt(10) ? 5 : error >= Math.sqrt(2) ? 2 : 1);
+}
+/** The round steps of a time taken, in seconds: a minute, five, a quarter hour, half, an hour, two, three, six,
+    twelve, a day, two, three, a week, two, thirty days. A duration axis is ruled at "2d / 4d / 6d", not at
+    the decimal 1-2-5 steps of its seconds ("2d 7h"). */
+export const DURATION_STEPS = [
+    60, 300, 900, 1800, 3600, 7200, 10800, 21600, 43200, 86400, 172800, 259200, 604800, 1209600, 2592000,
+];
+/** Round levels over `[low, high]`; a flat range is given a step of room above it. `steps`, where given, are the
+    only steps an axis may take (DURATION_STEPS), the one covering the range most closely in two to four. */
+export function niceScale(low, high, intervals = 2, steps) {
+    if (steps?.length && Number.isFinite(low) && Number.isFinite(high) && high > low) {
+        let best;
+        for (const step of steps) {
+            const min = Math.floor(low / step) * step, max = Math.ceil(high / step) * step;
+            const count = Math.round((max - min) / step);
+            if (count < 2 || count > 4)
+                continue;
+            if (!best || max - min < best.max - best.min)
+                best = { min, max, step, levels: Array.from({ length: count + 1 }, (_, i) => min + i * step) };
+        }
+        if (best)
+            return best;
+    }
+    let min = Math.min(low, high), max = Math.max(low, high);
+    if (!Number.isFinite(min) || !Number.isFinite(max))
+        return { min: 0, max: 1, step: 1, levels: [0, 1] };
+    if (min === max) {
+        if (max === 0)
+            return { min: 0, max: 1, step: 1, levels: [0, 1] };
+        const step = niceStep(Math.abs(max), 1);
+        return niceScale(Math.min(0, min), Math.max(0, max) + (max > 0 ? 0 : step), intervals);
+    }
+    const step = niceStep(max - min, intervals);
+    /* A step's own decimals, so 0.1 + 0.2 is said 0.3 and not 0.30000000000000004. */
+    const places = Math.max(0, -Math.floor(Math.log10(step)) + 1);
+    const round = (v) => Number(v.toFixed(places));
+    min = round(Math.floor(min / step) * step);
+    max = round(Math.ceil(max / step) * step);
+    const levels = [];
+    for (let v = min, i = 0; v <= max + step / 2 && i < 50; v = round(min + step * ++i))
+        levels.push(v);
+    return { min, max, step, levels };
+}

package/dist/shared/order.d.ts

@@ -0,0 +1,59 @@
+/**
+ * What has to exist first, and what comes apart in which order.
+ *
+ * Every foreign key is a statement about time: a row cannot point at a row
+ * that is not there yet, and a row that is pointed at cannot leave before the
+ * rows pointing at it. Building test data means knowing that order, and
+ * deriving it by hand from a catalog is exactly the work this tool already
+ * did to draw the graph.
+ *
+ * A topological sort, with the two things a topological sort usually leaves
+ * out said out loud:
+ *
+ *   - **Cycles.** Two tables that point at each other have no order. Rather
+ *     than picking one and pretending, the cycle is named — and where one of
+ *     its edges is nullable, the way through is named too: insert with the
+ *     column null, then update it once the other row exists.
+ *   - **Self-references.** `work_order.parent_id → work_order` is not a
+ *     cycle between tables and does not affect the order at all, but it does
+ *     mean the rows inside that table have an order of their own. Reported
+ *     separately, because it is a different problem with a different answer.
+ *
+ * Ties break alphabetically. A stable answer is worth more than a marginally
+ * shorter one: an order that changes between runs makes a fixture that
+ * "sometimes works", which is the failure this exists to prevent.
+ */
+import { type DatabaseSchema } from './schema.js';
+interface Requirement {
+    /** The table that must have the row already. */
+    table: string;
+    /** The columns pointing at it. */
+    via: string[];
+    /**
+     * Whether every one of those columns may be null.
+     *
+     * A nullable reference is a requirement you can postpone: insert the row
+     * without it, then update. That is the only way out of a cycle, so it is
+     * worth saying even where the order came out fine.
+     */
+    optional: boolean;
+}
+interface OrderPlan {
+    /** Parents first: insert in this order and no reference dangles. */
+    insert: string[];
+    /** Children first: the reverse, which is what teardown needs. */
+    remove: string[];
+    /** Per table, what must exist before it. */
+    requires: Record<string, Requirement[]>;
+    /** Tables whose order could not be decided, grouped by the cycle they are in. */
+    cycles: string[][];
+    /** Tables that point at themselves: an order *within* the table. */
+    selfReferencing: string[];
+}
+/**
+ * @param tables The tables to order. Omitted means every table in the schema.
+ *   Names are resolved through `findTable`, so a bare name works where the
+ *   schema qualifies it.
+ */
+export declare function insertOrder(schema: DatabaseSchema, tables?: string[]): OrderPlan;
+export {};

package/dist/shared/order.js

@@ -0,0 +1,133 @@
+/**
+ * What has to exist first, and what comes apart in which order.
+ *
+ * Every foreign key is a statement about time: a row cannot point at a row
+ * that is not there yet, and a row that is pointed at cannot leave before the
+ * rows pointing at it. Building test data means knowing that order, and
+ * deriving it by hand from a catalog is exactly the work this tool already
+ * did to draw the graph.
+ *
+ * A topological sort, with the two things a topological sort usually leaves
+ * out said out loud:
+ *
+ *   - **Cycles.** Two tables that point at each other have no order. Rather
+ *     than picking one and pretending, the cycle is named — and where one of
+ *     its edges is nullable, the way through is named too: insert with the
+ *     column null, then update it once the other row exists.
+ *   - **Self-references.** `work_order.parent_id → work_order` is not a
+ *     cycle between tables and does not affect the order at all, but it does
+ *     mean the rows inside that table have an order of their own. Reported
+ *     separately, because it is a different problem with a different answer.
+ *
+ * Ties break alphabetically. A stable answer is worth more than a marginally
+ * shorter one: an order that changes between runs makes a fixture that
+ * "sometimes works", which is the failure this exists to prevent.
+ */
+import { findTable } from './schema.js';
+/**
+ * @param tables The tables to order. Omitted means every table in the schema.
+ *   Names are resolved through `findTable`, so a bare name works where the
+ *   schema qualifies it.
+ */
+export function insertOrder(schema, tables) {
+    const wanted = tables?.length
+        ? tables.map((name) => findTable(schema, name)?.id ?? name)
+        : schema.tables.filter((t) => !t.isView).map((t) => t.id);
+    const inSet = new Set(wanted);
+    const requires = {};
+    const selfReferencing = [];
+    /* `after.get(a)` holds the tables that must come *after* a — the edges of
+       the sort, pointing the way an insert travels. */
+    const after = new Map(wanted.map((id) => [id, new Set()]));
+    const waitingOn = new Map(wanted.map((id) => [id, 0]));
+    for (const fk of schema.foreignKeys) {
+        const from = fk.from.table;
+        const to = fk.to.table;
+        if (!inSet.has(from))
+            continue;
+        if (from === to) {
+            if (!selfReferencing.includes(from))
+                selfReferencing.push(from);
+            continue;
+        }
+        /* A reference out of the set is still a requirement — the row it points
+           at has to exist — but it cannot be ordered, because it is not part of
+           what was asked about. It belongs in `requires` and not in the sort. */
+        const columns = findTable(schema, from)?.columns ?? [];
+        const optional = fk.from.columns.every((name) => columns.find((c) => c.name === name)?.nullable !== false);
+        (requires[from] ??= []).push({ table: to, via: fk.from.columns, optional });
+        if (!inSet.has(to))
+            continue;
+        if (after.get(to).has(from))
+            continue;
+        after.get(to).add(from);
+        waitingOn.set(from, (waitingOn.get(from) ?? 0) + 1);
+    }
+    const insert = [];
+    const ready = wanted.filter((id) => !waitingOn.get(id)).sort();
+    while (ready.length) {
+        const id = ready.shift();
+        insert.push(id);
+        /* Sorted on the way in, so the answer does not depend on the order the
+           catalog happened to list the keys in. */
+        for (const next of [...after.get(id)].sort()) {
+            const left = (waitingOn.get(next) ?? 0) - 1;
+            waitingOn.set(next, left);
+            if (left === 0) {
+                ready.push(next);
+                ready.sort();
+            }
+        }
+    }
+    /* Whatever is left is in a cycle, or behind one. Grouped so the answer
+       names the knot rather than listing its members. */
+    const stuck = wanted.filter((id) => !insert.includes(id));
+    const cycles = groupCycles(stuck, after);
+    for (const list of Object.values(requires)) {
+        list.sort((a, b) => a.table.localeCompare(b.table));
+    }
+    return {
+        insert,
+        remove: [...insert].reverse(),
+        requires,
+        cycles,
+        selfReferencing: selfReferencing.sort(),
+    };
+}
+/**
+ * The knots, as knots.
+ *
+ * Two tables pointing at each other and a third waiting behind them are one
+ * problem with one fix, and three lines saying "could not be ordered" is
+ * three problems to work out are the same one.
+ */
+function groupCycles(stuck, after) {
+    const left = new Set(stuck);
+    const groups = [];
+    while (left.size) {
+        const start = [...left].sort()[0];
+        const group = new Set([start]);
+        const queue = [start];
+        while (queue.length) {
+            const id = queue.shift();
+            for (const next of after.get(id) ?? []) {
+                if (!left.has(next) || group.has(next))
+                    continue;
+                group.add(next);
+                queue.push(next);
+            }
+            /* Both directions: a cycle is only visible if the walk can go back the
+               way the arrows came. */
+            for (const [other, targets] of after) {
+                if (!left.has(other) || group.has(other) || !targets.has(id))
+                    continue;
+                group.add(other);
+                queue.push(other);
+            }
+        }
+        for (const id of group)
+            left.delete(id);
+        groups.push([...group].sort());
+    }
+    return groups;
+}