tablewalk 0.0.1

package/dist/server/shapeonly.js

@@ -0,0 +1,91 @@
+/**
+ * A connection that hands out shape and never rows.
+ *
+ * The README's boundary — "rows entering an agent's context leave the
+ * machine, so point it at development databases" — was a sentence asking to
+ * be believed. `"rows": false` makes it a property of the connection: the
+ * catalog, the counts, the lint and the plans still answer, and every path
+ * that would return a value from a row refuses.
+ *
+ * Enforced by wrapping the adapter rather than by checking at each endpoint.
+ * There are eight endpoints and fifteen tools today and there will be more,
+ * and a rule spelled out in eighteen places is a rule with a hole in it. The
+ * wrapper is the choke point every read already goes through, so a feature
+ * added later inherits the boundary instead of having to remember it.
+ *
+ * What still answers is deliberate: shape is what an agent is here for. Which
+ * tables exist, what points at what, how many rows there are, how much of a
+ * column is null, what a statement's plan looks like. What it cannot have is
+ * a value out of a row — including the ones `profile` reports, since a
+ * minimum, a maximum and the most common values are row content however
+ * aggregated.
+ */
+import { Refusal } from '../adapters/adapter.js';
+const why = (name, what) => new Refusal(`"${name}" is shape-only: ${what} would return data out of its rows. `
+    + 'The catalog, row counts, null fractions, plans and lint still answer. '
+    + 'Remove "rows": false from its entry in your tablewalk.json to read rows from it.');
+/**
+ * The same adapter with every row-returning method refused.
+ *
+ * Methods are copied rather than proxied through a Proxy so that the optional
+ * ones stay honestly absent: an adapter with no `runSql` must still look like
+ * an adapter with no `runSql`, or callers that check for it before offering
+ * SQL start offering it and failing.
+ */
+export function shapeOnly(adapter, name) {
+    const wrapped = Object.create(Object.getPrototypeOf(adapter));
+    Object.assign(wrapped, adapter);
+    /* Bound to the original: the copies above are the original's methods, and
+       calling them on `wrapped` would work by accident on a plain object and
+       break on a class instance holding private state. */
+    const from = (key) => {
+        const method = adapter[key];
+        return typeof method === 'function'
+            ? method.bind(adapter)
+            : undefined;
+    };
+    wrapped.introspect = from('introspect');
+    wrapped.close = from('close');
+    wrapped.count = from('count');
+    wrapped.query = () => { throw why(name, 'reading rows'); };
+    if (adapter.runSql)
+        wrapped.runSql = () => { throw why(name, 'running SQL'); };
+    if (adapter.runView)
+        wrapped.runView = () => { throw why(name, 'running a view'); };
+    if (adapter.countView)
+        wrapped.countView = from('countView');
+    if (adapter.insert)
+        wrapped.insert = () => { throw why(name, 'inserting'); };
+    if (adapter.update)
+        wrapped.update = () => { throw why(name, 'updating'); };
+    if (adapter.remove)
+        wrapped.remove = () => { throw why(name, 'deleting'); };
+    /* A transaction hands out `insert` and `remove` of its own, from inside the
+       adapter, where the refusals above cannot reach them. Refused whole. */
+    if (adapter.transaction)
+        wrapped.transaction = () => { throw why(name, 'writing'); };
+    /* A breakdown's group keys *are* row values — `by status` answers with the
+       statuses. The counts beside them would be safe and are not worth the
+       surface: an answer with its labels blanked is not an answer. Counting the
+       groups is a cardinality fact and stays, for the same reason `profile`
+       keeps its distinct count. */
+    if (adapter.runBreakdown)
+        wrapped.runBreakdown = () => { throw why(name, 'grouping rows'); };
+    if (adapter.countBreakdown)
+        wrapped.countBreakdown = from('countBreakdown');
+    /* Profile keeps the numbers and loses the values. "52% null, 4,100
+       distinct" is the fact that decides a LEFT join and carries nothing out
+       of any row; a minimum, a maximum and the most common values carry rows. */
+    if (adapter.profile) {
+        const profile = from('profile');
+        wrapped.profile = async (table, limits) => {
+            const result = await profile(table, limits);
+            return {
+                ...result,
+                columns: result.columns.map(({ min, max, common, ...rest }) => rest),
+                redacted: 'Values withheld: this connection is shape-only.',
+            };
+        };
+    }
+    return wrapped;
+}

package/dist/shared/breakdown.js

@@ -0,0 +1,231 @@
+/**
+ * Counting things by something: GROUP BY, as a shape rather than as text.
+ *
+ * This was the last real hole in the query language. "How many invoices per
+ * month", "which countries have the most customers", "what does each status
+ * add up to" are the questions anybody asks of a database in the first ten
+ * minutes, and until now the only way to ask them here was to drop into `sql`
+ * — which means an agent leaves the checked path exactly where the question
+ * gets interesting, and a person leaves the tool.
+ *
+ * A breakdown is deliberately *not* a view with a `groupBy` bolted on. A view
+ * promises one row per base record, and every part of it — the correlated
+ * aggregates, the LEFT JOIN rule, the row-click that opens a record — leans on
+ * that promise. Grouping breaks it: the rows that come back are not records
+ * and cannot be opened, and a column that is neither a key nor an aggregate is
+ * a bug on two engines and a silent wrong answer on the third. So it is a
+ * sibling type with its own compiler, sharing the parts that are genuinely the
+ * same: path resolution, the join planner, and `buildWhere`.
+ *
+ *     invoice  count  by status
+ *     invoice  sum total  by month invoice_date
+ *     invoice  count, avg total  by customer_id.country_code.name  sort count desc
+ *
+ * Two rules the shape enforces, both of which SQL leaves to the author:
+ *
+ *   - **Every selected expression is a key or a measure.** There is nowhere to
+ *     put a third thing, so `SELECT status, name, COUNT(*) … GROUP BY status`
+ *     — which MySQL will happily answer with an arbitrary `name` — cannot be
+ *     written.
+ *   - **The result is bounded like every other read.** A breakdown over a
+ *     high-cardinality column is a million-row answer, and `sort count desc
+ *     limit 20` is what somebody meant anyway.
+ */
+import { buildWhere, clampLimit, clampOffset, } from '../adapters/adapter.js';
+import { findTable } from './schema.js';
+import { JoinPlan, PathError, qualifiedTable, resolvePath, sqlLiteral, } from './view.js';
+export const MEASURE_FUNCTIONS = ['count', 'sum', 'avg', 'min', 'max'];
+/** The periods a date key can be cut into. */
+export const DATE_UNITS = ['day', 'month', 'quarter', 'year'];
+/** How many group keys are worth having. */
+export const MAX_KEYS = 3;
+/**
+ * Is this column something a date bucket can be taken of?
+ *
+ * Read off the declared type rather than the values, because the answer has
+ * to be the same before and after the table has any rows in it. SQLite's
+ * `DATE` is a convention rather than a type, which is exactly why the check is
+ * on the declaration: a column somebody called `DATE` is one they intend to
+ * hold dates, and `strftime` over text that is not one returns null — a group
+ * of its own rather than an error, which is the honest outcome.
+ */
+const isDateish = (type) => /date|time/i.test(type ?? '');
+/**
+ * Compile a breakdown to one parameterised SELECT.
+ *
+ * The order of work matches `compileView`'s and for the same reason: keys,
+ * then measures, then the filter, then the sort — so aliases are handed out in
+ * first-use order and the same breakdown always compiles to the same text.
+ */
+export function compileBreakdown(schema, def, style, offset = 0) {
+    const base = findTable(schema, def.base);
+    if (!base) {
+        throw new PathError(`No table called "${def.base}" in this database, so there is nothing to break down.`, def.base, def.base, 0);
+    }
+    if (!def.by?.length) {
+        throw new PathError('A breakdown needs something to group by — `by status`, or `by month invoice_date`.', '', '', 0);
+    }
+    if (def.by.length > MAX_KEYS) {
+        /* A cap rather than a warning. Three keys is already a table nobody reads
+           across; the fourth is how a breakdown becomes the base table again, one
+           row per record, with the count column always saying 1. */
+        throw new PathError(`A breakdown groups by at most ${MAX_KEYS} things; this one names ${def.by.length}.`, def.by[MAX_KEYS].path, def.by[MAX_KEYS].path, 0);
+    }
+    if (!def.measures?.length) {
+        throw new PathError('A breakdown needs something to measure — `count`, or `sum total`.', '', '', 0);
+    }
+    const plan = new JoinPlan(schema, base, style);
+    const qualify = (path) => {
+        const resolved = resolvePath(schema, def.base, path);
+        let prefix = '';
+        for (let i = 0; i < resolved.hops.length; i++) {
+            prefix = prefix ? `${prefix}.${resolved.hopNames[i]}` : resolved.hopNames[i];
+            plan.record(prefix, resolved.hops[i]);
+        }
+        return plan.qualify(resolved);
+    };
+    const seen = new Map();
+    /** Output names are unique or the result set loses a column silently. */
+    const nameFor = (wanted) => {
+        const count = seen.get(wanted) ?? 0;
+        seen.set(wanted, count + 1);
+        return count ? `${wanted}_${count + 1}` : wanted;
+    };
+    const columns = [];
+    const select = [];
+    const grouping = [];
+    for (const key of def.by) {
+        const resolved = resolvePath(schema, def.base, key.path);
+        let sql = qualify(key.path);
+        if (key.bucket) {
+            if (!isDateish(resolved.column.type)) {
+                throw new PathError(`"${key.path}" is ${resolved.column.type || 'untyped'}, so it cannot be grouped by ${key.bucket}. `
+                    + 'Group by it directly, or pick a date column.', key.path, key.path, resolved.hops.length);
+            }
+            sql = style.dateBucket(sql, key.bucket);
+        }
+        const name = nameFor(key.alias?.trim() || (key.bucket ? `${key.bucket}(${resolved.path})` : resolved.path));
+        select.push(`${sql} AS ${style.quote(name)}`);
+        /* Grouped by the *expression*, not by the output name. Postgres and MySQL
+           would take the alias; SQLite would too — but a bucketed key aliased to
+           `month(invoice_date)` and grouped by that name is one identifier away
+           from grouping by a column that happens to share it. The expression is
+           never ambiguous. */
+        grouping.push(sql);
+        columns.push({
+            name,
+            kind: 'key',
+            path: resolved.path,
+            /* A bucket makes text out of whatever it was, and the interface should
+               render `2026-08` as the label it is rather than as a date it is not. */
+            type: key.bucket ? 'text' : resolved.column.type,
+            bucket: key.bucket,
+        });
+    }
+    for (const measure of def.measures) {
+        if (measure.fn === 'count') {
+            if (measure.distinct && !measure.path) {
+                throw new PathError('`count distinct` needs a column to count distinct values of.', '', '', 0);
+            }
+            /* COUNT(*) rather than COUNT(column) when no column is named: a column
+               count skips nulls, which turns "how many invoices" into "how many
+               invoices have a total" without saying so. Naming a column is how you
+               ask the other question, and then the skipping is the point. */
+            const expression = measure.path
+                ? `COUNT(${measure.distinct ? 'DISTINCT ' : ''}${qualify(measure.path)})`
+                : 'COUNT(*)';
+            const name = nameFor(measure.alias?.trim() || (measure.path ? `count(${measure.path})` : 'count'));
+            select.push(`${expression} AS ${style.quote(name)}`);
+            columns.push({ name, kind: 'measure', fn: 'count', path: measure.path, type: 'integer' });
+            continue;
+        }
+        if (!measure.path) {
+            throw new PathError(`\`${measure.fn}\` needs a column: \`${measure.fn} total\`.`, '', '', 0);
+        }
+        if (measure.distinct) {
+            throw new PathError(`\`distinct\` only means something with \`count\`, not with \`${measure.fn}\`.`, measure.path, measure.path, 0);
+        }
+        const resolved = resolvePath(schema, def.base, measure.path);
+        const name = nameFor(measure.alias?.trim() || `${measure.fn}(${resolved.path})`);
+        select.push(`${measure.fn.toUpperCase()}(${qualify(measure.path)}) AS ${style.quote(name)}`);
+        columns.push({
+            name,
+            kind: 'measure',
+            fn: measure.fn,
+            path: resolved.path,
+            /* `avg` is a fraction of whatever it averaged — an average of integers
+               is not an integer, and saying otherwise makes the interface round a
+               number the database did not. */
+            type: measure.fn === 'avg' ? 'numeric' : resolved.column.type,
+        });
+    }
+    const conditions = def.filter?.groups.length
+        ? {
+            groups: def.filter.groups.map((group) => group.map((c) => ({ column: c.path, op: c.op, value: c.value }))),
+        }
+        : undefined;
+    const where = buildWhere(conditions, style, 1, qualify);
+    /* Sorted by output name, and only by output name.
+  
+       Every column of a breakdown is either a key or a measure, and both are in
+       the SELECT list under a name — so there is nothing else it could sort by,
+       and ORDER BY runs late enough to see the aliases on all three engines.
+       Sorting by an expression instead would let `sort total desc` mean the
+       ungrouped column on a statement where that column no longer exists. */
+    const names = new Set(columns.map((c) => c.name));
+    const order = (def.orderBy ?? []).map((o) => {
+        if (!names.has(o.name)) {
+            throw new PathError(`Nothing called "${o.name}" is in this breakdown. It shows: ${[...names].join(', ')}.`, o.name, o.name, 0);
+        }
+        return `${style.quote(o.name)} ${o.direction === 'desc' ? 'DESC' : 'ASC'}`;
+    });
+    const limit = clampLimit(def.limit);
+    const skip = clampOffset(offset);
+    const n = where.params.length;
+    const lines = [
+        `SELECT ${select.join(',\n       ')}`,
+        `  FROM ${qualifiedTable(schema, base.id, style)} ${style.quote(plan.baseAlias)}`,
+        ...plan.clauses(),
+    ];
+    if (where.text)
+        lines.push(where.text);
+    lines.push(` GROUP BY ${grouping.join(', ')}`);
+    if (order.length)
+        lines.push(` ORDER BY ${order.join(', ')}`);
+    lines.push(` LIMIT ${style.placeholder(n + 1)} OFFSET ${style.placeholder(n + 2)}`);
+    return { text: lines.join('\n'), params: [...where.params, limit, skip], columns, limit };
+}
+/**
+ * How many groups there are, ignoring the page.
+ *
+ * `SELECT COUNT(*) FROM (the grouped statement)` — the only honest way to
+ * count groups, because the number is a property of the grouping rather than
+ * of the base table. Without the limit and offset, which is the whole point of
+ * asking.
+ */
+export function compileBreakdownCount(schema, def, style) {
+    const inner = compileBreakdown(schema, def, style);
+    /* The LIMIT/OFFSET line is the last one and carries the last two
+       parameters. Dropped by rebuilding rather than by string surgery would be
+       nicer; it is the last line by construction, and the test says so. */
+    const lines = inner.text.split('\n');
+    const body = lines.slice(0, -1).join('\n');
+    return {
+        text: `SELECT COUNT(*) AS n FROM (\n${body}\n) AS grouped`,
+        params: inner.params.slice(0, -2),
+    };
+}
+/**
+ * Render a breakdown as the SQL it will become, values inline.
+ *
+ * The exact counterpart of `explainView`, and here for the same reason: the
+ * SQL pane is how somebody learns what a line of the language did on their
+ * behalf, and a statement full of `?` teaches nothing about the filter that
+ * produced it. It also has to be a statement that runs, because the pane
+ * offers to open it in the SQL editor.
+ */
+export function explainBreakdown(schema, def, style, offset = 0) {
+    const compiled = compileBreakdown(schema, def, style, offset);
+    let i = 0;
+    return compiled.text.replace(/\$\d+|\?/g, () => sqlLiteral(compiled.params[i++]));
+}

package/dist/shared/breakdowntext.js

@@ -0,0 +1,257 @@
+/**
+ * A breakdown, written down.
+ *
+ * The same argument the view text form makes, and it applies harder here: a
+ * breakdown is the shape most likely to be pasted into a conversation, saved
+ * in a config file, or handed to an agent as a string. A grouping that can
+ * only be expressed as JSON is one nobody writes by hand.
+ *
+ *     invoice  count  by status
+ *     invoice  count, sum total as billed  by month invoice_date  sort billed desc  limit 12
+ *     invoice  where total > 100  count  by customer_id.country_code.name as country
+ *
+ * The grammar is the query language plus two clauses. Measures come first —
+ * `count`, `count distinct sold_by`, `sum total`, each optionally `as name` —
+ * then `by`, then the things to group by, each optionally cut down to a period
+ * (`by month invoice_date`) and optionally named. Everything else in the line
+ * is the ordinary language: `where`, `sort`, `limit`, parsed by
+ * `parseViewQuery` exactly as the composer's filter box parses it. Two parsers
+ * for one language is how a language starts disagreeing with itself.
+ *
+ * One deliberate asymmetry with a view: **`sort` names an output column**, not
+ * a path. Every column of a breakdown is a key or a measure and both are in
+ * the answer under a name, so there is nothing else it could mean — and `sort
+ * total desc` on a grouped statement, where `total` is no longer a column,
+ * should not quietly compile into something else.
+ */
+import { parseViewQuery, tryResolvePath } from './view.js';
+import { findTable } from './schema.js';
+import { DATE_UNITS, MEASURE_FUNCTIONS, } from './breakdown.js';
+/** Whether a line is asking for a breakdown at all. */
+export function looksLikeBreakdown(text) {
+    /* The `by` keyword, standing alone and not the tail of `order by`. That is
+       the whole tell: no other clause in the language uses it, which is why it
+       was available to mean this. */
+    return /(?<!\border\s)\bby\s+\S/i.test(String(text ?? ''));
+}
+const MEASURE_RE = new RegExp(String.raw `^(${MEASURE_FUNCTIONS.join('|')})` +
+    String.raw `(\s+distinct)?` +
+    String.raw `(?:\s+([\w.$+]+))?` +
+    String.raw `(?:\s+as\s+([\w$]+))?$`, 'i');
+const KEY_RE = new RegExp(String.raw `^(?:(${DATE_UNITS.join('|')})\s+)?([\w.$+]+)(?:\s+as\s+([\w$]+))?$`, 'i');
+/** Where the clauses after the group keys begin. */
+const TAIL_CLAUSE = /\b(sort|order\s+by|limit)\b/i;
+/**
+ * Split `a, b, c` on commas, dropping the empties a trailing comma leaves.
+ */
+const commas = (text) => text.split(',').map((part) => part.trim()).filter(Boolean);
+/**
+ * Find the `by` that pivots the line.
+ *
+ * The *first* standalone `by` not preceded by `order`, because a breakdown's
+ * `sort` clause comes after the keys and may legitimately be written `order
+ * by`. Searching from the front means `invoice count by status order by count`
+ * splits where it should.
+ */
+function pivot(text) {
+    for (const match of text.matchAll(/\bby\b/gi)) {
+        const at = match.index ?? 0;
+        if (/\border\s+$/i.test(text.slice(0, at)))
+            continue;
+        return at;
+    }
+    return -1;
+}
+export function textToBreakdown(schema, text, options = {}) {
+    const errors = [];
+    const body = String(text ?? '').trim();
+    if (!body)
+        return { errors: [{ message: 'Start with a table name.' }] };
+    const baseName = body.split(/\s+/)[0];
+    const base = findTable(schema, baseName) ?? schema.tables.find((t) => t.name === baseName);
+    if (!base) {
+        return { errors: [{ message: `No table called "${baseName}" in this database.`, at: 0 }] };
+    }
+    const rest = body.slice(baseName.length);
+    const at = pivot(rest);
+    if (at === -1) {
+        return {
+            errors: [{
+                    message: 'A breakdown needs `by` — try `count by status`, or `sum total by month invoice_date`.',
+                }],
+        };
+    }
+    const head = rest.slice(0, at);
+    const afterBy = rest.slice(at + 2);
+    /* The keys run to the first clause that is not a key. Split here rather
+       than by counting commas, because a key list and a sort clause are both
+       comma-separated and only a keyword tells them apart. */
+    const tailAt = afterBy.search(TAIL_CLAUSE);
+    const keyText = tailAt === -1 ? afterBy : afterBy.slice(0, tailAt);
+    const tail = tailAt === -1 ? '' : afterBy.slice(tailAt);
+    /* The measures are the longest suffix of `head` that reads as a list of
+       them; everything before that is the ordinary language, and is handed on
+       untouched. Found by trying each word boundary from the left and keeping
+       the first that works, which is what makes `invoice where total > 100
+       count by status` split correctly without this module knowing what `where`
+       means.
+  
+       Splitting on commas alone was the obvious version and it was wrong: `where
+       total > 100 count` holds no comma at all, so the whole clause read as one
+       piece, failed to match, and the line came back "nothing to measure" with
+       a `count` plainly in it. */
+    const words = [...head.matchAll(/\S+/g)].map((m) => ({ text: m[0], at: m.index ?? 0 }));
+    const measures = [];
+    let prefix = head;
+    for (const word of words) {
+        const candidate = head.slice(word.at);
+        const pieces = commas(candidate);
+        if (!pieces.length || !pieces.every((piece) => MEASURE_RE.test(piece)))
+            continue;
+        for (const piece of pieces) {
+            const [, fn, distinct, path, alias] = MEASURE_RE.exec(piece);
+            measures.push({
+                fn: fn.toLowerCase(),
+                path: path || undefined,
+                distinct: distinct ? true : undefined,
+                alias: alias || undefined,
+            });
+        }
+        prefix = head.slice(0, word.at);
+        break;
+    }
+    if (!measures.length) {
+        errors.push({
+            message: 'Nothing to measure before `by`. Try `count by …`, or `sum total by …`.',
+        });
+    }
+    for (const measure of measures) {
+        if (!measure.path)
+            continue;
+        const { error } = tryResolvePath(schema, base.id, measure.path);
+        if (error)
+            errors.push({ message: error.message });
+    }
+    const keys = [];
+    for (const piece of commas(keyText)) {
+        const match = KEY_RE.exec(piece);
+        if (!match) {
+            errors.push({
+                message: `"${piece}" is not something to group by. A column, a path like customer_id.name, `
+                    + `or a period like \`month invoice_date\`.`,
+            });
+            continue;
+        }
+        const [, unit, path, alias] = match;
+        /* Resolved here rather than left to the compiler. This runs on a
+           keystroke and the compiler runs on a request, so a path caught here is
+           a message under the caret and a path caught there is a failed call. */
+        const { error } = tryResolvePath(schema, base.id, path);
+        if (error) {
+            errors.push({ message: error.message });
+            continue;
+        }
+        keys.push({
+            path,
+            bucket: unit ? unit.toLowerCase() : undefined,
+            alias: alias || undefined,
+        });
+    }
+    if (!keys.length && !errors.length) {
+        errors.push({ message: '`by` needs something after it — a column, or `month <date column>`.' });
+    }
+    /* The names this breakdown will answer under, so `sort billed desc` parses.
+       Derived the same way the compiler derives them, because a sort that
+       validates against one spelling and compiles against another is a sort
+       that works until somebody adds an alias. */
+    const names = [
+        ...keys.map((k) => k.alias?.trim() || (k.bucket ? `${k.bucket}(${k.path})` : k.path)),
+        ...measures.map((m) => m.alias?.trim()
+            || (m.fn === 'count' ? (m.path ? `count(${m.path})` : 'count') : `${m.fn}(${m.path ?? ''})`)),
+    ];
+    const parsed = parseViewQuery(schema, base.id, `${prefix} ${tail}`.trim(), options.now, {
+        /* Every output name joins the synthetic table for the sort clause. A
+           breakdown has no `show`, so nothing else here can reach them. */
+        aggregateAliases: names,
+    });
+    errors.push(...parsed.errors);
+    if (parsed.columns.length) {
+        errors.push({
+            message: '`show` does not apply to a breakdown — its columns are the things it groups by and measures.',
+        });
+    }
+    const orderBy = parsed.orderBy.map((o) => ({ name: o.path, direction: o.direction }));
+    const breakdown = {
+        base: base.id,
+        by: keys,
+        measures,
+        filter: parsed.filter.groups.length ? parsed.filter : undefined,
+        orderBy: orderBy.length ? orderBy : undefined,
+        limit: parsed.limit,
+        text: body,
+    };
+    return { breakdown: errors.length ? undefined : breakdown, errors };
+}
+/**
+ * Render a breakdown as text — the inverse, and the round trip is tested.
+ *
+ * One line, unlike a view. A breakdown is a phrase: two measures and a key is
+ * the normal size of one, and the whole point of the form is that it fits in
+ * a query bar.
+ */
+export function breakdownToText(schema, def) {
+    const base = findTable(schema, def.base);
+    const parts = [base?.name ?? def.base];
+    const conditions = (def.filter?.groups ?? []).filter((g) => g.length);
+    if (conditions.length) {
+        parts.push('where');
+        parts.push(conditions
+            .map((group) => group.map(conditionToText).join(' and '))
+            .join(' or '));
+    }
+    parts.push(def.measures.map(measureToText).join(', '));
+    parts.push('by');
+    parts.push(def.by.map(keyToText).join(', '));
+    if (def.orderBy?.length) {
+        parts.push('sort');
+        parts.push(def.orderBy.map((o) => `${o.name}${o.direction === 'desc' ? ' desc' : ''}`).join(', '));
+    }
+    if (def.limit !== undefined)
+        parts.push(`limit ${def.limit}`);
+    return parts.join(' ');
+}
+const measureToText = (m) => {
+    const words = [m.fn];
+    if (m.distinct)
+        words.push('distinct');
+    if (m.path)
+        words.push(m.path);
+    if (m.alias)
+        words.push('as', m.alias);
+    return words.join(' ');
+};
+const keyToText = (k) => {
+    const words = [];
+    if (k.bucket)
+        words.push(k.bucket);
+    words.push(k.path);
+    if (k.alias)
+        words.push('as', k.alias);
+    return words.join(' ');
+};
+/**
+ * One condition, back in words.
+ *
+ * Deliberately small: the operators a breakdown's filter uses are the ones the
+ * query language spells the same way in both directions. Anything else is
+ * rendered by its own name, which round-trips because that is how it parses.
+ */
+function conditionToText(c) {
+    if (c.op === 'isNull')
+        return `${c.path} is null`;
+    if (c.op === 'isNotNull')
+        return `${c.path} is not null`;
+    const value = Array.isArray(c.value) ? c.value.join(', ') : String(c.value ?? '');
+    const spelled = c.op === '=' ? '=' : c.op;
+    return `${c.path} ${spelled} ${value}`;
+}