tablewalk 0.0.1

package/dist/shared/page.js

@@ -0,0 +1,932 @@
+/**
+ * Pages: a record layout with a front door.
+ *
+ * A record template lays out a row you have already found. A page starts one
+ * step earlier — it asks *which* customer, and then shows everything that
+ * customer is: their own fields, how many orders they have placed, what those
+ * orders were, and the lines inside those orders. One screen assembled from
+ * one root, instead of a walk you have to remember the way back through.
+ *
+ * The content model is deliberately the record template's, extended rather
+ * than replaced. Two systems that both lay out sections keyed by foreign
+ * key would drift within a month, and the second one would be the one that
+ * forgot composite keys. What pages add is:
+ *
+ *   - **metric** sections — one number, from an aggregate over a relationship
+ *   - **lists that reach further than one hop**, via a path rather than a
+ *     single constraint, so "the lines of this customer's orders" is a
+ *     section rather than two clicks
+ *   - **a filter on a list**, so "recent open orders" is a section and not
+ *     the whole of them
+ *   - **a width**, so three counts sit in a row instead of stacked
+ *
+ * Everything here is pure: parsing, validating, and turning a page plus a
+ * root key into the requests its sections need. Nothing fetches. That is what
+ * lets the hard part — path resolution against a real schema, which is where
+ * the mistakes live — be tested without a browser or a database.
+ */
+import { findTable, labelColumn, primaryKey, referencesTo, } from './schema.js';
+import { MAX_PATH_DEPTH, parseViewQuery } from './view.js';
+import { quoteValue } from './query.js';
+export const WIDTHS = ['full', 'half', 'third'];
+export const OFFSETS = ['quarter', 'third', 'half', 'two-thirds'];
+export const FIELD_COLUMNS = [1, 2, 3];
+/** Rows a list section shows before it needs a page of its own. */
+export const DEFAULT_PAGE_LIST_LIMIT = 10;
+/** Sections a page may hold. A page is a screen, not a report. */
+export const MAX_SECTIONS = 24;
+/* How a suggested page divides the relationships pointing at its root: the
+   first few as lists, the next few as counts, the rest not shown. A page that
+   listed all twelve things pointing at `customer` would be a report. */
+const LISTED = 2;
+const COUNTED = 3;
+/**
+ * Follow `a.b.c` from a table, hop by hop, and say where it lands.
+ *
+ * Each segment names a foreign key *on the current table* — by constraint
+ * name when one is given, otherwise by its column. Constraint name first,
+ * because a table can point at the same parent twice and `parent_id` and
+ * `supersedes_id` are two different paths that a column-only lookup would
+ * happily confuse.
+ */
+export function resolvePath(schema, from, path) {
+    const segments = path.split('.').map((s) => s.trim()).filter(Boolean);
+    if (!segments.length)
+        return { error: 'A path cannot be empty.' };
+    if (segments.length > MAX_PATH_DEPTH) {
+        return { error: `"${path}" follows more than ${MAX_PATH_DEPTH} references.` };
+    }
+    let current = from;
+    const hops = [];
+    for (const segment of segments) {
+        const table = findTable(schema, current);
+        if (!table)
+            return { error: `"${current}" is not a table on this connection.` };
+        const outgoing = schema.foreignKeys.filter((fk) => fk.from.table === table.id);
+        const hop = outgoing.find((fk) => fk.name === segment)
+            ?? outgoing.find((fk) => fk.from.columns.length === 1 && fk.from.columns[0] === segment)
+            ?? outgoing.find((fk) => fk.from.columns.join(',') === segment);
+        if (!hop) {
+            return {
+                error: `"${table.name}" has no reference called "${segment}".`
+                    + (outgoing.length
+                        ? ` It points at: ${outgoing.map((fk) => fk.from.columns.join('+')).join(', ')}.`
+                        : ' It points at nothing.'),
+            };
+        }
+        hops.push(hop);
+        current = hop.to.table;
+    }
+    return { path: { hops, endsAt: current } };
+}
+/**
+ * The filter that ties a section to one root record.
+ *
+ * Built as a structured `ViewFilter` rather than as text, for the reason the
+ * whole tool is built that way: a key value that happens to contain a quote
+ * or the word `and` is a value, and text would make it grammar.
+ *
+ * The path is written into the column, so the compiler does the joining —
+ * `invoice_id.customer_id` is a path it already knows how to walk, and the
+ * one place that knows how to join is better than a second one here.
+ */
+export function rootFilter(path, key, resolved) {
+    const last = resolved.hops[resolved.hops.length - 1];
+    const prefix = path.split('.').slice(0, -1).join('.');
+    /* Every column of the root's key, compared through the same path. A
+       composite key compared on one column matches every row that shares it,
+       which on `invoice_line` is most of the table. */
+    const conditions = last.to.columns.map((rootColumn, i) => {
+        const childColumn = last.from.columns[i] ?? last.from.columns[0];
+        return {
+            path: prefix ? `${prefix}.${childColumn}` : childColumn,
+            op: '=',
+            value: key[rootColumn],
+        };
+    });
+    return { groups: [conditions] };
+}
+/**
+ * Resolve a section's `of` — the forward reference naming which record the
+ * section is about.
+ *
+ * One hop, deliberately. `of: 'site_id.address_id'` is expressible in the
+ * type and refused here: each extra hop is another row the planner must read
+ * before any section can run, and nobody has yet asked for a section about
+ * the address of the site of the record they are looking at. The error says
+ * the limit rather than pretending the path is malformed.
+ */
+export function resolveOf(schema, baseId, of) {
+    const resolved = resolvePath(schema, baseId, of);
+    if (resolved.error)
+        return { error: resolved.error };
+    if (resolved.path.hops.length !== 1) {
+        return { error: `"of" reaches one reference from ${baseId}; "${of}" is ${resolved.path.hops.length} hops.` };
+    }
+    const fk = resolved.path.hops[0];
+    const table = findTable(schema, resolved.path.endsAt);
+    if (!table)
+        return { error: `"${of}" leads to a table this connection does not have.` };
+    return { fk, table };
+}
+/**
+ * The section's own narrowing, ANDed onto the root's.
+ *
+ * `filter` has been in the model and in the config parser since the start and
+ * was never applied: a page saying `"filter": "status = open"` listed every
+ * order, silently. Documented, accepted, ignored — the worst shape a bug can
+ * take, because the file says the behaviour is there.
+ *
+ * Written in the query language and parsed against the *child*, which is what
+ * "recent open orders" means: the condition is about the order, not about the
+ * customer the page is on. Errors come back rather than throwing, so a
+ * mistyped filter names its section instead of blanking the page.
+ */
+function withSectionFilter(schema, from, root, filter, now) {
+    if (!filter)
+        return { filter: root };
+    const parsed = parseViewQuery(schema, from, filter, now);
+    if (parsed.errors.length)
+        return { error: parsed.errors[0].message };
+    const extra = parsed.filter.groups;
+    if (!extra.length)
+        return { filter: root };
+    /* ANDed into every root group rather than appended as another group: groups
+       are OR-ed, so appending would have widened the result instead of
+       narrowing it — a filter that added rows. With one root group, which is
+       what `rootFilter` always builds, this is the ordinary case of "and also".
+    
+       A filter with its own OR becomes a product, which is what AND-of-ORs
+       means when both sides have alternatives. */
+    const groups = [];
+    for (const rootGroup of root.groups) {
+        for (const extraGroup of extra)
+            groups.push([...rootGroup, ...extraGroup]);
+    }
+    return { filter: { groups } };
+}
+/**
+ * What a list section needs to run, as a view the existing compiler can take.
+ *
+ * A page adds no query machinery of its own. Every section is a view — that
+ * is the point of having built one — so a page is an arrangement of views
+ * around a shared root rather than a second way to ask a database questions.
+ */
+export function listView(schema, page, section, key, index, now, ofKeys) {
+    const root = sectionRoot(schema, page, section, key, ofKeys);
+    if (root.error)
+        return { error: root.error };
+    if (root.empty)
+        return { empty: true };
+    const resolved = resolvePath(schema, section.from, section.path);
+    if (resolved.error)
+        return { error: resolved.error };
+    if (resolved.path.endsAt !== root.table) {
+        return {
+            error: `"${section.path}" leads from ${section.from} to `
+                + `${resolved.path.endsAt}, not to ${root.table}.`,
+        };
+    }
+    const table = findTable(schema, section.from);
+    if (!table)
+        return { error: `"${section.from}" is not a table on this connection.` };
+    const columns = (section.columns?.length
+        ? section.columns
+        : defaultColumns(table, section.path, resolved.path)).map((p) => ({ path: p }));
+    const narrowed = withSectionFilter(schema, table.id, rootFilter(section.path, root.key, resolved.path), section.filter, now);
+    if (narrowed.error)
+        return { error: narrowed.error };
+    return {
+        view: {
+            id: `page:${page.id}:${index}`,
+            name: section.title ?? table.name,
+            base: table.id,
+            columns,
+            filter: narrowed.filter,
+            orderBy: section.orderBy?.map((o) => ({ path: o.column, direction: o.direction })),
+            limit: section.limit ?? DEFAULT_PAGE_LIST_LIMIT,
+        },
+    };
+}
+/**
+ * The record a section is actually about: the root, or — through `of` — a
+ * record the root points at, whose key the planner has already read.
+ */
+function sectionRoot(schema, page, section, key, ofKeys) {
+    if (!section.of)
+        return { table: page.base, key };
+    const of = resolveOf(schema, page.base, section.of);
+    if (of.error)
+        return { error: of.error };
+    const referenced = ofKeys?.[section.of];
+    if (referenced === undefined) {
+        /* The planner read the root row before building sections, so a missing
+           entry is the caller's bug, not the page's. Said as what it is. */
+        return { error: `The key for "${section.of}" was not resolved before planning.` };
+    }
+    if (referenced === null)
+        return { empty: true };
+    return { table: of.table.id, key: referenced };
+}
+/**
+ * What a metric section needs to run.
+ *
+ * Expressed as a one-row view over the *root* table with a single aggregate,
+ * rather than as a count over the child: the aggregate machinery already
+ * guarantees that two counts over different children cannot inflate each
+ * other, and doing it any other way here would give up that guarantee for a
+ * number nobody would think to check.
+ */
+/**
+ * How the query bar would say what a section shows — when it can say it.
+ *
+ * A count on a page is a number, and a number you cannot get behind is a
+ * number you have to take on trust. Clicking one should open the rows it
+ * counted, narrowed the same way — and for a long time it opened the child
+ * table with no filter at all, because the plan carried no query and the
+ * client fell back to the table's own name. The count said 3 and the grid
+ * said 20.
+ *
+ * The query language has no dotted paths: `invoice_line invoice_id.customer_id
+ * = 4` is not a thing it can parse, and a page two hops out produces exactly
+ * that. So this answers `undefined` rather than something that will not run —
+ * the caller opens the composer on the view itself in that case, which can
+ * say it. The distinction is deliberate: it is better to be told the language
+ * cannot express this than to be shown a filter that quietly is not the one.
+ *
+ * `is empty` for a null test, because that is the grammar's spelling; `in` is
+ * left out, since a list needs bracket syntax the parser writes differently
+ * from how it reads it.
+ */
+const QUERY_OPS = {
+    '=': '=',
+    '!=': '!=',
+    '<': '<',
+    '<=': '<=',
+    '>': '>',
+    '>=': '>=',
+    contains: 'contains',
+    startsWith: 'startswith',
+    endsWith: 'endswith',
+};
+export function sectionQuery(view) {
+    if (!view?.base)
+        return undefined;
+    const groups = view.filter?.groups?.filter((g) => g.length) ?? [];
+    if (!groups.length)
+        return view.base;
+    const parts = [];
+    for (const group of groups) {
+        const conditions = [];
+        for (const c of group) {
+            /* A path, not a column: the language filters the table in front of it
+               and nothing further out. */
+            if (!c.path || c.path.includes('.'))
+                return undefined;
+            if (c.op === 'isNull' || c.op === 'isNotNull') {
+                conditions.push(`${c.path} is ${c.op === 'isNull' ? '' : 'not '}empty`);
+                continue;
+            }
+            const op = QUERY_OPS[c.op];
+            if (!op || c.value === undefined || c.value === null || Array.isArray(c.value))
+                return undefined;
+            conditions.push(`${c.path} ${op} ${quoteValue(c.value)}`);
+        }
+        parts.push(conditions.join(' and '));
+    }
+    return `${view.base} ${parts.join(' or ')}`;
+}
+export function metricView(schema, page, section, key, index, now, ofKeys) {
+    const root = sectionRoot(schema, page, section, key, ofKeys);
+    if (root.error)
+        return { error: root.error };
+    if (root.empty)
+        return { empty: true, counts: section.fn === 'count' };
+    const resolved = resolvePath(schema, section.from, section.path);
+    if (resolved.error)
+        return { error: resolved.error };
+    if (resolved.path.endsAt !== root.table) {
+        return {
+            error: `"${section.path}" leads from ${section.from} to `
+                + `${resolved.path.endsAt}, not to ${root.table}.`,
+        };
+    }
+    if (section.fn !== 'count' && !section.column) {
+        return { error: `"${section.fn}" needs a column to ${section.fn}.` };
+    }
+    const table = findTable(schema, section.from);
+    if (!table)
+        return { error: `"${section.from}" is not a table on this connection.` };
+    if (section.column && !table.columns.some((c) => c.name === section.column)) {
+        return { error: `"${table.name}" has no column called "${section.column}".` };
+    }
+    /* The record this section is about — the page's base, or the table `of`
+       reaches. The aggregate view below anchors on it, so a sum "of its site"
+       is a one-row view over site exactly as a sum over the root is one over
+       the root. */
+    const base = findTable(schema, root.table);
+    if (!base)
+        return { error: `"${root.table}" is not a table on this connection.` };
+    /**
+     * A count is a filtered count of the child, not an aggregate on the root.
+     *
+     * It used to be an aggregate, with `via` taken from the *first* hop — which
+     * is the right constraint only when there is one. For anything further out
+     * the first hop names a key that does not point at the root at all: on a
+     * customer page, `invoice_line via invoice_id.customer_id` handed the
+     * aggregate `line_invoice_fk`, which joins lines to invoices and knows
+     * nothing about customers. The number that came back was not the number
+     * asked for, and looked like one.
+     *
+     * Counting the child directly is correct at any depth, and it is what the
+     * list beside it already does — so a count and the list it summarises can
+     * no longer disagree. The view returns one row and its `total`, which is
+     * exact: a view only ever joins to-one, so counting it is counting the
+     * table it started from.
+     */
+    if (section.fn === 'count') {
+        const narrowed = withSectionFilter(schema, table.id, rootFilter(section.path, root.key, resolved.path), section.filter, now);
+        if (narrowed.error)
+            return { error: narrowed.error };
+        return {
+            counts: true,
+            view: {
+                id: `page:${page.id}:${index}`,
+                name: section.title ?? table.name,
+                base: table.id,
+                columns: (primaryKey(table)[0] ? [primaryKey(table)[0]] : [table.columns[0].name])
+                    .map((path) => ({ path })),
+                filter: narrowed.filter,
+                limit: 1,
+            },
+        };
+    }
+    /* `sum`, `avg`, `min` and `max` still go through the aggregate compiler,
+       which is the only thing that can produce them — and which reaches exactly
+       one hop. Refused rather than answered wrongly: a sum over a relationship
+       it cannot express would be a number with no way to tell it was the wrong
+       one. */
+    if (resolved.path.hops.length > 1) {
+        return {
+            error: `"${section.fn}" only works on something that points straight at `
+                + `${base.name}. ${table.name} is ${resolved.path.hops.length} references away — `
+                + 'count it instead, or add the column to the table in between.',
+        };
+    }
+    if (section.filter) {
+        /* The aggregate compiler takes no filter of its own, and quietly dropping
+           one would be the bug this whole change is about. */
+        return {
+            error: `A "${section.fn}" cannot be narrowed by a filter. `
+                + 'Count it instead, or make a list and read the total.',
+        };
+    }
+    return {
+        view: {
+            id: `page:${page.id}:${index}`,
+            name: section.title ?? `${section.fn} of ${table.name}`,
+            base: base.id,
+            columns: primaryKey(base).map((c) => ({ path: c })),
+            aggregates: [{
+                    fn: section.fn,
+                    via: resolved.path.hops[0].name,
+                    column: section.column,
+                    alias: 'value',
+                }],
+            filter: { groups: [primaryKey(base).map((c) => ({ path: c, op: '=', value: root.key[c] }))] },
+            limit: 1,
+        },
+    };
+}
+/**
+ * Columns worth showing in a list nobody has configured.
+ *
+ * The path back to the root is dropped: every row in the section has the same
+ * value for it, so a column of forty identical numbers is the one column that
+ * cannot tell two rows apart. The key and the label come first, because they
+ * are what a row is called.
+ */
+export function defaultColumns(table, path, resolved) {
+    /* The columns the first hop actually uses, not the segment that named it.
+    
+       A path segment can be a constraint name — which is how a suggested page
+       writes it, and the only way to name a composite hop — so splitting the
+       path for a column name found `address_country_fk`, matched nothing, and
+       left `country_code` in the table: a column reading NZ on every row of a
+       section that is *about* NZ. The one column that cannot tell two rows
+       apart, kept in the one place it is guaranteed useless. */
+    const pathHead = resolved
+        ? resolved.hops[0].from.columns
+        : [path.split('.')[0]];
+    const key = primaryKey(table);
+    const label = labelColumn(table);
+    const ordered = [
+        ...key,
+        ...(label && !key.includes(label) ? [label] : []),
+        ...table.columns.map((c) => c.name).filter((n) => !key.includes(n) && n !== label),
+    ];
+    return ordered.filter((name) => !pathHead.includes(name)).slice(0, 6);
+}
+/**
+ * Check a page against a real schema, and say what is wrong with it.
+ *
+ * Returns the page with an `error` rather than throwing, because a page that
+ * names a table this connection does not have is still a page — it belongs
+ * in the list, greyed, with its reason. A config file shared by a team will
+ * always describe some connection someone is not on.
+ */
+export function validatePage(schema, page) {
+    const base = findTable(schema, page.base);
+    if (!base)
+        return { ...page, error: `"${page.base}" is not a table on this connection.` };
+    if (!primaryKey(base).length) {
+        return {
+            ...page,
+            error: `"${base.name}" has no primary key, so a single record cannot be identified.`,
+        };
+    }
+    for (const [i, section] of page.sections.entries()) {
+        const at = section.title ? `"${section.title}"` : `section ${i + 1}`;
+        if (section.kind === 'fields')
+            continue;
+        let rootTable = page.base;
+        if (section.of) {
+            const of = resolveOf(schema, page.base, section.of);
+            if (of.error)
+                return { ...page, error: `${at}: ${of.error}` };
+            rootTable = of.table.id;
+        }
+        const resolved = resolvePath(schema, section.from, section.path);
+        if (resolved.error)
+            return { ...page, error: `${at}: ${resolved.error}` };
+        if (resolved.path.endsAt !== rootTable) {
+            return {
+                ...page,
+                error: `${at}: "${section.path}" leads from ${section.from} to `
+                    + `${resolved.path.endsAt}, not to ${rootTable}.`,
+            };
+        }
+        if (section.kind === 'metric' && section.fn !== 'count' && !section.column) {
+            return { ...page, error: `${at}: "${section.fn}" needs a column to ${section.fn}.` };
+        }
+    }
+    return { ...page, error: undefined };
+}
+/**
+ * A page for a table nobody has written one for.
+ *
+ * Not a placeholder: it is the page most people would have built by hand —
+ * the record, a count of each thing that points at it, and the two biggest of
+ * those as lists. Offering it means a page exists for every table on the
+ * first run, which is the difference between a feature people try and a
+ * feature people configure first.
+ */
+export function suggestPage(schema, baseId) {
+    const base = findTable(schema, baseId);
+    if (!base || !primaryKey(base).length)
+        return null;
+    const incoming = referencesTo(schema, base.id);
+    const sections = [{ kind: 'fields', width: 'full' }];
+    /* Lists for the first few, counts for the rest — never both for the same
+       relationship.
+    
+       A count above a list of the rows it counted says nothing the list does
+       not: `ROOM 2` over a table of two rooms is a number and its own proof,
+       taking a card to do it. The count belongs *on* the list, where it says
+       how many there are beyond the ones shown; a card earns its place only for
+       a relationship you cannot see, which is what the ones past the listed
+       few are. Show the big ones, count the rest. */
+    const listed = incoming.slice(0, LISTED);
+    const counted = incoming.slice(LISTED, LISTED + COUNTED);
+    for (const fk of counted) {
+        const child = findTable(schema, fk.from.table);
+        if (!child)
+            continue;
+        sections.push({
+            kind: 'metric',
+            fn: 'count',
+            from: child.id,
+            path: fk.name,
+            title: metricTitle(counted, fk, child.name, base.id),
+            width: 'third',
+        });
+    }
+    for (const fk of listed) {
+        const child = findTable(schema, fk.from.table);
+        if (!child)
+            continue;
+        sections.push({
+            kind: 'list',
+            from: child.id,
+            path: fk.name,
+            title: metricTitle(listed, fk, child.name, base.id),
+            limit: DEFAULT_PAGE_LIST_LIMIT,
+            width: listed.length > 1 ? 'half' : 'full',
+        });
+    }
+    return {
+        id: `suggested:${base.id}`,
+        name: base.name,
+        base: base.id,
+        sections,
+        source: 'suggested',
+    };
+}
+/**
+ * What to call a count.
+ *
+ * The child's name, which is what someone reading a summary expects — until
+ * that is not enough to tell two counts apart. A table pointing at the same
+ * parent twice gives two counts both labelled `work_order`, and a
+ * self-reference gives a count labelled with the table you are already on:
+ * `employee` on an employee page, which is the count of their reports and
+ * says nothing of the sort. Both cases are named by their foreign key
+ * instead, which is the thing that actually differs.
+ */
+function metricTitle(chosen, fk, childName, baseId) {
+    const ambiguous = chosen.filter((other) => other.from.table === fk.from.table).length > 1;
+    const selfReference = fk.from.table === baseId;
+    return ambiguous || selfReference ? `${childName} via ${fk.from.columns.join(', ')}` : childName;
+}
+/**
+ * Every way a table could reach this root, within a couple of hops.
+ *
+ * The one field nobody guesses when writing a page by hand is the path —
+ * `invoice_id.customer_id` is obvious only once you already know it. So it is
+ * not typed: the schema is asked what actually points here, directly and one
+ * table further out, and each answer comes back with the path already
+ * written.
+ *
+ * Two hops rather than the full depth limit. Three is a real relationship and
+ * a list nobody can read: on a schema of this size it runs to hundreds of
+ * entries, most of them routes no one would choose, and a menu that long is a
+ * menu people close.
+ */
+export function relationsTo(schema, baseId, maxHops = 2) {
+    const base = findTable(schema, baseId);
+    if (!base)
+        return [];
+    const found = [];
+    const seen = new Set();
+    /** Every spelling of each path already built, so deeper hops can extend them. */
+    const aliasesOf = new Map([['', ['']]]);
+    const walk = (targetId, path, via, hops) => {
+        if (hops > maxHops)
+            return;
+        for (const fk of schema.foreignKeys) {
+            if (fk.to.table !== targetId)
+                continue;
+            const child = findTable(schema, fk.from.table);
+            if (!child)
+                continue;
+            /* Named by the constraint, always. A column name is shorter and works
+               until a table points at the same parent twice, or points at it with
+               two columns — and both are common enough that the readable spelling
+               is the one that breaks. */
+            const next = [fk.name, ...path];
+            const route = next.join('.');
+            const id = `${child.id}|${route}`;
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            const target = findTable(schema, targetId);
+            /* Both spellings of this hop, crossed with every spelling of the rest.
+               Bounded: two names per hop and two hops is four, and the depth cap
+               keeps it there. A composite key has only its constraint name, since
+               no single column identifies it. */
+            const hopNames = [fk.name];
+            if (fk.from.columns.length === 1)
+                hopNames.push(fk.from.columns[0]);
+            const tailAliases = aliasesOf.get(path.join('.')) ?? [path.join('.')];
+            const aliases = hopNames.flatMap((name) => tailAliases.map((tail) => (tail ? `${name}.${tail}` : name)));
+            aliasesOf.set(route, aliases);
+            found.push({
+                from: child.id,
+                path: route,
+                aliases,
+                label: child.name,
+                hops: hops + 1,
+                /* The route in the words on the screen: table names and the columns
+                   that join them. A constraint name is the only reliable *identifier*
+                   for a hop, which is why the path is written in them — and it is the
+                   one thing nobody recognises, which is why it is not what is shown.
+                   Innermost first, so it reads outward from the root. */
+                via: [`${child.name}.${fk.from.columns.join(', ')} \u2192 ${target?.name ?? targetId}`, ...via],
+            });
+            /* Not through the root, and not through itself. A self-referencing key
+               is a real relationship at one hop and an infinite regress past it. */
+            if (child.id !== baseId && child.id !== targetId) {
+                walk(child.id, next, [`${child.name}.${fk.from.columns.join(', ')} \u2192 ${findTable(schema, targetId)?.name ?? targetId}`, ...via], hops + 1);
+            }
+        }
+    };
+    walk(base.id, [], [], 0);
+    /* Disambiguated after the fact rather than while walking, because whether
+       `invoice` needs qualifying depends on whether a *second* invoice route
+       turned up later.
+    
+       Qualified by the columns, not by the path: `invoice via sold_by` is a
+       sentence someone can check against the schema in their head, where
+       `invoice via invoice_fk_2` is a string only the database has ever seen. */
+    /* Qualified only as far as it takes, and as far as it takes.
+    
+       One pass was not enough. `work_log through ticket` was three entries on
+       the employee page — work_log reaches employee through ticket by
+       `assigned_to`, by `raised_by` and by `closed_by` — and all three were
+       rendered with the same words and the same detail line underneath. Three
+       identical rows in a menu is a menu you cannot use: whichever is picked,
+       nobody can tell which was picked.
+    
+       So each name is refined until it is unique, one step at a time, and only
+       the ones that collide take the next step. `invoice` stays `invoice` where
+       nothing else is called that. */
+    const steps = new Map(found.map((r) => [r, 0]));
+    for (let pass = 0; pass < 4; pass += 1) {
+        const groups = new Map();
+        for (const r of found) {
+            const label = qualify(r, steps.get(r) ?? 0);
+            const group = groups.get(label);
+            if (group)
+                group.push(r);
+            else
+                groups.set(label, [r]);
+        }
+        let refined = false;
+        for (const group of groups.values()) {
+            if (group.length < 2)
+                continue;
+            for (const r of group) {
+                steps.set(r, (steps.get(r) ?? 0) + 1);
+                refined = true;
+            }
+        }
+        if (!refined)
+            break;
+    }
+    for (const r of found)
+        r.label = qualify(r, steps.get(r) ?? 0);
+    return found.sort((a, b) => a.hops - b.hops || a.label.localeCompare(b.label));
+}
+/**
+ * The columns of one hop, out of the sentence it is written as.
+ *
+ * A `via` entry reads `work_log.ticket_id \u2192 ticket`, which is the form the
+ * screen wants; this is the one place that takes it apart again.
+ */
+const hopColumns = (via) => via?.split(' \u2192 ')[0]?.split('.').slice(1).join('.') ?? '';
+const hopTarget = (via) => via?.split('\u2192 ')[1] ?? '\u2026';
+/**
+ * A relationship's name at a given degree of qualification.
+ *
+ * Step 0 is the child table's name, which is right whenever nothing else on
+ * the page is called that. Each step after it adds the next thing that could
+ * tell two of them apart, in the order a reader would ask: which column, then
+ * which table in the middle, then which column *that* one reaches the root
+ * by. The last step falls back to the path — unreadable, and unique by
+ * construction, which is what a last step is for.
+ */
+function qualify(r, step) {
+    const name = r.label.split(' via ')[0].split(' through ')[0];
+    if (step <= 0)
+        return name;
+    if (r.hops === 1) {
+        return step === 1 ? `${name} via ${hopColumns(r.via[0])}` : `${name} (${r.path})`;
+    }
+    /* Two hops are told apart by the table in the middle — `contract_line
+       through contract` and `contract_line through asset` are two genuinely
+       different lists. Naming the root instead would label both of them
+       "through customer", which is the thing they have in common. */
+    if (step === 1)
+        return `${name} through ${hopTarget(r.via[0])}`;
+    /* And where the middle table is the same, by how *it* reaches the root:
+       `work_log through ticket.assigned_to` against `\u2026 through
+       ticket.raised_by`. `via` runs innermost first, so the hop that lands on
+       the root is the last one. */
+    if (step === 2 && r.hops === 2) {
+        /* Only at exactly two hops, where the table in the middle is also the one
+           holding the column that reaches the root. Three hops out they are
+           different tables, and `work_log through ticket.lead_employee_id` would
+           name a column that is on `team` — a sentence that reads as fact and is
+           not one. Those go straight to the full spelling below. */
+        return `${name} through ${hopTarget(r.via[0])}.${hopColumns(r.via[r.via.length - 1])}`;
+    }
+    if (step === 2 || step === 3) {
+        return `${name} through ${r.via.map((v) => hopColumns(v)).join(' \u2192 ')}`;
+    }
+    return `${name} (${r.path})`;
+}
+/** Columns of a table that a metric could summarise. `count` needs none. */
+export function metricColumns(schema, tableId) {
+    const table = findTable(schema, tableId);
+    if (!table)
+        return [];
+    /* Only the numeric ones. `sum` of a name is not a question, and offering it
+       produces a page that fails at run time for a reason the builder knew at
+       build time. */
+    return table.columns
+        .filter((c) => /int|numeric|decimal|real|double|float|money|serial/i.test(c.type))
+        .map((c) => c.name);
+}
+/* ---------- config ---------- */
+const slug = (name) => name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'page';
+/**
+ * Read the `pages` section of a tablewalk.json.
+ *
+ * Throws on a malformed file rather than skipping the bad entry: a page that
+ * silently did not appear is a bug report that starts "I definitely wrote
+ * it". Everything a config file can get wrong is named with the page it is
+ * in and, where there is one, the fix.
+ */
+export function parsePagesConfig(raw, where) {
+    const pages = raw?.pages;
+    if (pages === undefined)
+        return [];
+    if (!Array.isArray(pages))
+        throw new Error(`${where}: "pages" must be an array.`);
+    const seen = new Set();
+    return pages.map((entry, i) => {
+        const at = `${where}: page ${i + 1}`;
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            throw new Error(`${at} is not an object.`);
+        }
+        const p = entry;
+        if (typeof p.name !== 'string' || !p.name.trim())
+            throw new Error(`${at} has no "name".`);
+        const name = p.name.trim();
+        if (typeof p.base !== 'string' || !p.base.trim()) {
+            throw new Error(`${at} ("${name}") has no "base" table.`);
+        }
+        const id = p.id === undefined ? `config-${slug(name)}` : String(p.id);
+        if (p.id !== undefined && (typeof p.id !== 'string' || !p.id.trim())) {
+            throw new Error(`${at} ("${name}") has an "id" that is not a non-empty string.`);
+        }
+        if (seen.has(id))
+            throw new Error(`${at} ("${name}") repeats the id "${id}".`);
+        seen.add(id);
+        if (p.connection !== undefined && typeof p.connection !== 'string') {
+            throw new Error(`${at} ("${name}") has a "connection" that is not a string.`);
+        }
+        /* Refused rather than coerced, like every other boolean in this file:
+           `"listTabs": "false"` is a truthy string. */
+        if (p.listTabs !== undefined && typeof p.listTabs !== 'boolean') {
+            throw new Error(`${at} ("${name}") has "listTabs": ${JSON.stringify(p.listTabs)}. It must be true or false, without quotes.`);
+        }
+        return {
+            id,
+            name,
+            base: p.base.trim(),
+            sections: parseSections(p.sections, at, name),
+            connection: p.connection,
+            /* Stored only when it is `false`, since `true` is the default and a
+               file full of `"listTabs": true` suggests the flag is doing
+               something. */
+            ...(p.listTabs === false ? { listTabs: false } : {}),
+            source: 'config',
+        };
+    });
+}
+function parseSections(raw, at, name) {
+    if (raw === undefined)
+        return [{ kind: 'fields', width: 'full' }];
+    if (!Array.isArray(raw))
+        throw new Error(`${at} ("${name}") has "sections" that are not an array.`);
+    if (raw.length > MAX_SECTIONS) {
+        throw new Error(`${at} ("${name}") has more than ${MAX_SECTIONS} sections.`);
+    }
+    return raw.map((entry, i) => parseSection(entry, `${at} ("${name}") section ${i + 1}`));
+}
+/**
+ * A column count, refused rather than clamped.
+ *
+ * Clamping `"columns": 7` to 3 would render a layout nobody asked for and say
+ * nothing about it; the file is the thing being edited, so the file is where
+ * the mistake belongs.
+ */
+function parseFieldColumns(value, at) {
+    if (value === undefined || value === null)
+        return undefined;
+    const n = Number(value);
+    if (!FIELD_COLUMNS.includes(n)) {
+        throw new Error(`${at} has "columns" of ${JSON.stringify(value)}. Use 1, 2 or 3.`);
+    }
+    return n;
+}
+function parseSection(entry, at) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+        throw new Error(`${at} is not an object.`);
+    }
+    const s = entry;
+    const kind = s.kind === undefined ? 'fields' : String(s.kind);
+    const width = parseWidth(s.width, at);
+    const offsetLeft = parseOffset(s.offsetLeft, at, 'offsetLeft');
+    const offsetRight = parseOffset(s.offsetRight, at, 'offsetRight');
+    const title = s.title === undefined ? undefined : String(s.title);
+    const hidden = s.hidden === undefined ? undefined : Boolean(s.hidden) || undefined;
+    if (kind === 'fields') {
+        if (s.paths !== undefined && !Array.isArray(s.paths)) {
+            throw new Error(`${at} has "paths" that are not an array.`);
+        }
+        return {
+            kind: 'fields',
+            title,
+            width,
+            offsetLeft,
+            offsetRight,
+            hidden,
+            paths: s.paths?.map(String),
+            columns: parseFieldColumns(s.columns, at),
+            collapsed: s.collapsed === undefined ? undefined : Boolean(s.collapsed) || undefined,
+        };
+    }
+    if (kind !== 'metric' && kind !== 'list') {
+        throw new Error(`${at} has an unknown kind "${kind}". Use "fields", "metric" or "list".`);
+    }
+    const from = typeof s.from === 'string' ? s.from.trim() : '';
+    if (!from)
+        throw new Error(`${at} has no "from" table.`);
+    const path = typeof s.path === 'string' ? s.path.trim() : '';
+    if (!path) {
+        throw new Error(`${at} has no "path" saying how ${from} reaches the page's record — `
+            + 'e.g. "customer_id", or "invoice_id.customer_id" for something two references away.');
+    }
+    const filter = s.filter === undefined ? undefined : String(s.filter).trim() || undefined;
+    if (kind === 'metric') {
+        const fn = String(s.fn ?? 'count');
+        if (!['count', 'sum', 'min', 'max', 'avg'].includes(fn)) {
+            throw new Error(`${at} has an unknown "fn" of "${fn}".`);
+        }
+        if (fn !== 'count' && (typeof s.column !== 'string' || !s.column.trim())) {
+            throw new Error(`${at} is a "${fn}" with no "column" to ${fn}.`);
+        }
+        return {
+            kind: 'metric',
+            title,
+            width,
+            offsetLeft,
+            offsetRight,
+            hidden,
+            fn: fn,
+            from,
+            path,
+            column: s.column === undefined ? undefined : String(s.column).trim(),
+            filter,
+        };
+    }
+    if (s.limit !== undefined && (typeof s.limit !== 'number' || !Number.isInteger(s.limit) || s.limit < 1)) {
+        throw new Error(`${at} has a "limit" that is not a positive whole number.`);
+    }
+    if (s.columns !== undefined && !Array.isArray(s.columns)) {
+        throw new Error(`${at} has "columns" that are not an array.`);
+    }
+    return {
+        kind: 'list',
+        title,
+        width,
+        offsetLeft,
+        offsetRight,
+        hidden,
+        from,
+        path,
+        columns: s.columns?.map(String),
+        filter,
+        limit: s.limit,
+        orderBy: parseOrderBy(s.orderBy, at),
+    };
+}
+function parseWidth(raw, at) {
+    if (raw === undefined)
+        return undefined;
+    const width = String(raw);
+    if (!WIDTHS.includes(width)) {
+        throw new Error(`${at} has a "width" of "${width}". Use ${WIDTHS.join(', ')}.`);
+    }
+    return width;
+}
+function parseOffset(raw, at, side) {
+    if (raw === undefined)
+        return undefined;
+    const offset = String(raw);
+    if (!OFFSETS.includes(offset)) {
+        throw new Error(`${at} has an "${side}" of "${offset}". Use ${OFFSETS.join(', ')}.`);
+    }
+    return offset;
+}
+function parseOrderBy(raw, at) {
+    if (raw === undefined)
+        return undefined;
+    if (!Array.isArray(raw))
+        throw new Error(`${at} has an "orderBy" that is not an array.`);
+    return raw.map((entry) => {
+        if (!entry || typeof entry !== 'object')
+            throw new Error(`${at} has an "orderBy" entry that is not an object.`);
+        const o = entry;
+        if (typeof o.column !== 'string' || !o.column.trim()) {
+            throw new Error(`${at} has an "orderBy" entry with no "column".`);
+        }
+        const direction = o.direction === undefined ? 'asc' : String(o.direction).toLowerCase();
+        if (direction !== 'asc' && direction !== 'desc') {
+            throw new Error(`${at} has an "orderBy" direction of "${direction}". Use asc or desc.`);
+        }
+        return { column: o.column.trim(), direction: direction };
+    });
+}