querylens 0.1.0

package/dist/src/engine/locks/lockManager.js

@@ -0,0 +1,46 @@
+/**
+ * Page-level locking, visual only (plan.md §7.7).
+ *
+ * What this models honestly: which pages a query holds a read lock on, and for
+ * how long. What it does NOT model: contention. v0 runs exactly one query, so
+ * no lock ever waits on another. The panel says so rather than implying that a
+ * lock icon means something is being protected from a rival.
+ *
+ * Real engines also distinguish a short *latch* on the buffer frame from a
+ * transaction-length *lock* on the data. We collapse the two into one
+ * page-level read lock held for the duration of the read.
+ */
+function key(pageId, mode) {
+    return `${String(pageId)}:${mode}`;
+}
+export function createLockManager(emit) {
+    const holding = new Map();
+    const stats = { acquired: 0, released: 0, maxHeldAtOnce: 0 };
+    return {
+        acquire(pageId, mode, why) {
+            const id = key(pageId, mode);
+            // Re-entrant on the same page and mode: one query cannot conflict with
+            // itself, so this is a no-op rather than a second lock.
+            if (holding.has(id))
+                return;
+            holding.set(id, { pageId, mode });
+            stats.acquired += 1;
+            stats.maxHeldAtOnce = Math.max(stats.maxHeldAtOnce, holding.size);
+            emit(why, { stage: 'lock', action: 'acquire', pageId, mode });
+        },
+        release(pageId, mode, why) {
+            const id = key(pageId, mode);
+            if (!holding.delete(id))
+                return;
+            stats.released += 1;
+            emit(why ?? `Release the ${mode} lock on page ${String(pageId)}.`, {
+                stage: 'lock',
+                action: 'release',
+                pageId,
+                mode,
+            });
+        },
+        held: () => [...holding.values()],
+        stats,
+    };
+}

package/dist/src/engine/parser/ast.js

@@ -0,0 +1,77 @@
+import { aggregateKeyOf, exprToSql } from "./print.js";
+export { aggregateKeyOf } from "./print.js";
+/** A qualified reference's row key — `authors.id` — or the bare name when unqualified. */
+export function columnKey(ref) {
+    return ref.table ? `${ref.table}.${ref.name}` : ref.name;
+}
+/** The row key an aggregate reads, or `null` for `COUNT(*)`. */
+export function selectItemArgColumn(item) {
+    return item.arg.kind === 'star' ? null : columnKey(item.arg);
+}
+/** Canonical display key for a SELECT item — its own name, or e.g. `COUNT(*)`, `SUM(age)`. */
+export function selectItemKey(item) {
+    if (item.kind === 'column')
+        return columnKey(item);
+    if (item.kind === 'expression')
+        return item.alias ?? exprToSql(item.expr);
+    return aggregateKeyOf(item.fn, item.arg);
+}
+/** The direct sub-expressions of a node, in source order. */
+export function childrenOf(expr) {
+    switch (expr.kind) {
+        case 'column':
+        case 'literal':
+        case 'aggregate':
+            return [];
+        case 'compare':
+        case 'and':
+        case 'or':
+        case 'arith':
+            return [expr.left, expr.right];
+        case 'not':
+        case 'isNull':
+        case 'neg':
+            return [expr.operand];
+        case 'in':
+            return [expr.operand, ...expr.items];
+        case 'like':
+            return [expr.operand, expr.pattern];
+    }
+}
+/** `expr` with `f` applied to each direct sub-expression — the rebuild half of `childrenOf`. */
+export function mapChildren(expr, f) {
+    switch (expr.kind) {
+        case 'column':
+        case 'literal':
+        case 'aggregate':
+            return expr;
+        case 'compare':
+        case 'and':
+        case 'or':
+        case 'arith':
+            return { ...expr, left: f(expr.left), right: f(expr.right) };
+        case 'not':
+        case 'isNull':
+        case 'neg':
+            return { ...expr, operand: f(expr.operand) };
+        case 'in':
+            return { ...expr, operand: f(expr.operand), items: expr.items.map(f) };
+        case 'like':
+            return { ...expr, operand: f(expr.operand), pattern: f(expr.pattern) };
+    }
+}
+/** Depth-first walk, parents before children. */
+export function walkExpr(expr, visit) {
+    visit(expr);
+    for (const child of childrenOf(expr))
+        walkExpr(child, visit);
+}
+/** Every column name referenced anywhere in a predicate. */
+export function columnsIn(expr) {
+    const names = [];
+    walkExpr(expr, (e) => {
+        if (e.kind === 'column')
+            names.push(e.name);
+    });
+    return names;
+}

package/dist/src/engine/parser/display.js

@@ -0,0 +1,404 @@
+/**
+ * Turns the typed AST into the display tree the UI renders, and emits the
+ * parse stage as a progressive reveal: SELECT list, then FROM, then WHERE.
+ *
+ * Node ids are stable across those steps so the tree animates as it grows
+ * instead of remounting on every event.
+ */
+import { selectItemKey } from "./ast.js";
+import { aggregateKeyOf, exprToSql } from "./print.js";
+function selectItemNode(item, id) {
+    if (item.kind === 'column')
+        return { id, kind: 'Column', label: item.name, span: item.span };
+    if (item.kind === 'expression') {
+        return {
+            id,
+            kind: 'Expression',
+            label: selectItemKey(item),
+            ...(item.alias === undefined ? {} : { detail: exprToSql(item.expr) }),
+            span: item.span,
+            children: [exprNode(item.expr, `${id}.e`)],
+        };
+    }
+    return { id, kind: 'Aggregate', label: selectItemKey(item), span: item.span };
+}
+function selectListNode(select, distinct = false) {
+    // `SELECT DISTINCT` (plan.md §25.4 B2) is a property of the whole list, so it is shown on the list's own node.
+    const prefix = distinct ? 'DISTINCT · ' : '';
+    if (select.kind === 'star') {
+        return {
+            id: 'select',
+            kind: 'SelectList',
+            label: distinct ? 'DISTINCT columns' : 'columns',
+            detail: `${prefix}every column`,
+            span: select.span,
+            children: [{ id: 'select.star', kind: 'Star', label: '*', span: select.span }],
+        };
+    }
+    return {
+        id: 'select',
+        kind: 'SelectList',
+        label: distinct ? 'DISTINCT columns' : 'columns',
+        detail: `${prefix}${select.items.length} named`,
+        span: select.span,
+        children: select.items.map((item, i) => selectItemNode(item, `select.col${i}`)),
+    };
+}
+function groupByNode(groupBy) {
+    return {
+        id: 'groupBy',
+        kind: 'GroupBy',
+        label: 'GROUP BY',
+        detail: groupBy.columns.map((c) => c.name).join(', '),
+        span: groupBy.span,
+        children: groupBy.columns.map((c, i) => ({
+            id: `groupBy.col${i}`,
+            kind: 'Column',
+            label: c.name,
+            span: c.span,
+        })),
+    };
+}
+function fromNode(from) {
+    return {
+        id: 'from',
+        kind: 'From',
+        label: 'FROM',
+        detail: from.name,
+        span: from.span,
+        children: [{ id: 'from.table', kind: 'Table', label: from.name, span: from.span }],
+    };
+}
+function exprNode(expr, id) {
+    switch (expr.kind) {
+        case 'column':
+            return { id, kind: 'Column', label: expr.name, span: expr.span };
+        case 'literal':
+            return { id, kind: 'Literal', label: expr.raw, span: expr.span };
+        case 'compare':
+            return {
+                id,
+                kind: 'Compare',
+                label: expr.op,
+                span: expr.span,
+                children: [exprNode(expr.left, `${id}.l`), exprNode(expr.right, `${id}.r`)],
+            };
+        case 'and':
+            return {
+                id,
+                kind: 'And',
+                label: 'AND',
+                span: expr.span,
+                children: [exprNode(expr.left, `${id}.l`), exprNode(expr.right, `${id}.r`)],
+            };
+        case 'or':
+            return {
+                id,
+                kind: 'Or',
+                label: 'OR',
+                span: expr.span,
+                children: [exprNode(expr.left, `${id}.l`), exprNode(expr.right, `${id}.r`)],
+            };
+        case 'not':
+            return { id, kind: 'Not', label: 'NOT', span: expr.span, children: [exprNode(expr.operand, `${id}.o`)] };
+        case 'isNull':
+            return {
+                id,
+                kind: 'IsNull',
+                label: expr.negated ? 'IS NOT NULL' : 'IS NULL',
+                span: expr.span,
+                children: [exprNode(expr.operand, `${id}.o`)],
+            };
+        case 'in':
+            return expr.subquery
+                ? {
+                    id,
+                    kind: 'In',
+                    label: expr.negated ? 'NOT IN' : 'IN',
+                    detail: `subquery — SELECT ${expr.subquery.column.name} FROM ${expr.subquery.from.name}`,
+                    span: expr.span,
+                    children: [exprNode(expr.operand, `${id}.o`)],
+                }
+                : {
+                    id,
+                    kind: 'In',
+                    label: expr.negated ? 'NOT IN' : 'IN',
+                    detail: `${expr.items.length} value${expr.items.length === 1 ? '' : 's'}`,
+                    span: expr.span,
+                    children: [
+                        exprNode(expr.operand, `${id}.o`),
+                        ...expr.items.map((item, i) => exprNode(item, `${id}.i${i}`)),
+                    ],
+                };
+        case 'aggregate':
+            return { id, kind: 'Aggregate', label: aggregateKeyOf(expr.fn, expr.arg), span: expr.span };
+        case 'arith':
+            return {
+                id,
+                kind: 'Arith',
+                label: expr.op,
+                span: expr.span,
+                children: [exprNode(expr.left, `${id}.l`), exprNode(expr.right, `${id}.r`)],
+            };
+        case 'neg':
+            return { id, kind: 'Arith', label: '−', detail: 'negate', span: expr.span, children: [exprNode(expr.operand, `${id}.o`)] };
+        case 'like':
+            return {
+                id,
+                kind: 'Like',
+                label: expr.negated ? 'NOT LIKE' : 'LIKE',
+                span: expr.span,
+                children: [exprNode(expr.operand, `${id}.o`), exprNode(expr.pattern, `${id}.p`)],
+            };
+    }
+}
+function whereNode(where) {
+    return {
+        id: 'where',
+        kind: 'Where',
+        label: 'WHERE',
+        span: where.span,
+        children: [exprNode(where, 'where.expr')],
+    };
+}
+function havingNode(having) {
+    return {
+        id: 'having',
+        kind: 'Having',
+        label: 'HAVING',
+        span: having.span,
+        children: [exprNode(having, 'having.expr')],
+    };
+}
+function orderByNode(orderBy) {
+    return {
+        id: 'orderBy',
+        kind: 'OrderBy',
+        label: 'ORDER BY',
+        detail: `${orderBy.column} ${orderBy.direction === 'asc' ? 'ASC' : 'DESC'}`,
+        span: orderBy.span,
+        children: [{ id: 'orderBy.col', kind: 'Column', label: orderBy.column, span: orderBy.span }],
+    };
+}
+function limitNode(limit) {
+    return {
+        id: 'limit',
+        kind: 'Limit',
+        label: 'LIMIT',
+        detail: limit.offset === undefined ? String(limit.value) : `${String(limit.value)} OFFSET ${String(limit.offset)}`,
+        span: limit.span,
+    };
+}
+function intoNode(into) {
+    return {
+        id: 'into',
+        kind: 'Into',
+        label: 'INTO',
+        detail: into.name,
+        span: into.span,
+        children: [{ id: 'into.table', kind: 'Table', label: into.name, span: into.span }],
+    };
+}
+function insertColumnsNode(columns) {
+    return {
+        id: 'columns',
+        kind: 'ColumnList',
+        label: 'columns',
+        detail: `${columns.names.length} named`,
+        span: columns.span,
+        children: columns.names.map((c, i) => ({
+            id: `columns.col${i}`,
+            kind: 'Column',
+            label: c.name,
+            span: c.span,
+        })),
+    };
+}
+function valuesNode(values) {
+    return {
+        id: 'values',
+        kind: 'Values',
+        label: 'VALUES',
+        detail: `${values.items.length} value${values.items.length === 1 ? '' : 's'}`,
+        span: values.span,
+        children: values.items.map((v, i) => exprNode(v, `values.v${i}`)),
+    };
+}
+function updateTableNode(table) {
+    return { id: 'table', kind: 'Table', label: table.name, span: table.span };
+}
+function assignmentNode(a, id) {
+    return {
+        id,
+        kind: 'Assignment',
+        label: a.column,
+        detail: `= ${exprToSql(a.value)}`,
+        span: { from: a.columnSpan.from, to: a.value.span.to },
+        // A literal is fully described by the detail; a computed value gets its own subtree.
+        ...(a.value.kind === 'literal' ? {} : { children: [exprNode(a.value, `${id}.v`)] }),
+    };
+}
+function setNode(set) {
+    return {
+        id: 'set',
+        kind: 'Set',
+        label: 'SET',
+        detail: `${set.assignments.length} assignment${set.assignments.length === 1 ? '' : 's'}`,
+        span: set.span,
+        children: set.assignments.map((a, i) => assignmentNode(a, `set.a${i}`)),
+    };
+}
+const ROOT_KIND = {
+    SELECT: 'SelectStatement',
+    DELETE: 'DeleteStatement',
+    INSERT: 'InsertStatement',
+    UPDATE: 'UpdateStatement',
+    ANALYZE: 'AnalyzeStatement',
+};
+function root(children, span, label = 'SELECT') {
+    return { id: 'select-stmt', kind: ROOT_KIND[label], label, span, children };
+}
+/** The complete display tree for a parsed statement. */
+export function toDisplayTree(ast) {
+    const children = [selectListNode(ast.select, ast.distinct), fromNode(ast.from)];
+    if (ast.where)
+        children.push(whereNode(ast.where));
+    if (ast.groupBy)
+        children.push(groupByNode(ast.groupBy));
+    if (ast.having)
+        children.push(havingNode(ast.having));
+    if (ast.orderBy)
+        children.push(orderByNode(ast.orderBy));
+    if (ast.limit)
+        children.push(limitNode(ast.limit));
+    return root(children, ast.span);
+}
+function countNodes(node) {
+    return 1 + (node.children ?? []).reduce((n, c) => n + countNodes(c), 0);
+}
+/** Emit the parse stage one clause at a time, so it can be stepped through. */
+export function emitParseEvents(emit, ast) {
+    const children = [];
+    const selectList = selectListNode(ast.select, ast.distinct);
+    children.push(selectList);
+    emit(ast.select.kind === 'star'
+        ? `Read the SELECT list: ${ast.distinct ? 'DISTINCT ' : ''}\`*\`, meaning every column of the table${ast.distinct ? ' — and each whole row is returned only once' : ''}.`
+        : `Read the SELECT list: ${ast.distinct ? 'DISTINCT ' : ''}${ast.select.items.map((item) => `\`${selectItemKey(item)}\``).join(', ')}${ast.distinct ? ' — each distinct combination is returned only once' : ''}.`, { stage: 'parse', ast: root([...children], ast.span), span: ast.select.span });
+    children.push(fromNode(ast.from));
+    emit(`Read the FROM clause: the query reads the \`${ast.from.name}\` table.`, {
+        stage: 'parse',
+        ast: root([...children], ast.span),
+        span: ast.from.span,
+    });
+    if (ast.where) {
+        children.push(whereNode(ast.where));
+        emit('Read the WHERE clause and build the predicate tree. Nothing has been executed yet — this is still only structure.', { stage: 'parse', ast: root([...children], ast.span), span: ast.where.span });
+    }
+    if (ast.groupBy) {
+        children.push(groupByNode(ast.groupBy));
+        emit(`Read the GROUP BY clause: rows are grouped by ${ast.groupBy.columns
+            .map((c) => `\`${c.name}\``)
+            .join(', ')}. Nothing has been computed yet — this is still only structure.`, { stage: 'parse', ast: root([...children], ast.span), span: ast.groupBy.span });
+    }
+    if (ast.having) {
+        children.push(havingNode(ast.having));
+        emit('Read the HAVING clause: a predicate over the *groups* — unlike WHERE it may test aggregates, because it runs after they are computed. Nothing has been computed yet — this is still only structure.', { stage: 'parse', ast: root([...children], ast.span), span: ast.having.span });
+    }
+    if (ast.orderBy) {
+        children.push(orderByNode(ast.orderBy));
+        emit(`Read the ORDER BY clause: sort by \`${ast.orderBy.column}\`, ${ast.orderBy.direction === 'asc' ? 'ascending' : 'descending'}.`, { stage: 'parse', ast: root([...children], ast.span), span: ast.orderBy.span });
+    }
+    if (ast.limit) {
+        children.push(limitNode(ast.limit));
+        emit(ast.limit.offset === undefined
+            ? `Read the LIMIT clause: cap the result at ${ast.limit.value}.`
+            : `Read the LIMIT clause: skip the first ${ast.limit.offset} rows, then cap the result at ${ast.limit.value}.`, { stage: 'parse', ast: root([...children], ast.span), span: ast.limit.span });
+    }
+    const tree = root([...children], ast.span);
+    emit(`Parsing is done: ${countNodes(tree)} AST nodes and no data touched. The planner turns this shape into a plan next.`, { stage: 'parse', ast: tree, span: ast.span });
+}
+/** The complete display tree for a parsed `DELETE`. */
+export function deleteDisplayTree(ast) {
+    const children = [fromNode(ast.from)];
+    if (ast.where)
+        children.push(whereNode(ast.where));
+    return root(children, ast.span, 'DELETE');
+}
+/** Emit the parse stage for a `DELETE`, one clause at a time — mirrors `emitParseEvents`. */
+export function emitDeleteParseEvents(emit, ast) {
+    const children = [fromNode(ast.from)];
+    emit(`Read the FROM clause: DELETE removes rows from the \`${ast.from.name}\` table.`, {
+        stage: 'parse',
+        ast: root([...children], ast.span, 'DELETE'),
+        span: ast.from.span,
+    });
+    if (ast.where) {
+        children.push(whereNode(ast.where));
+        emit('Read the WHERE clause and build the predicate tree. Nothing has been removed yet — this is still only structure.', { stage: 'parse', ast: root([...children], ast.span, 'DELETE'), span: ast.where.span });
+    }
+    const tree = root([...children], ast.span, 'DELETE');
+    emit(`Parsing is done: ${countNodes(tree)} AST nodes and no data touched. The planner turns this shape into a plan next.`, { stage: 'parse', ast: tree, span: ast.span });
+}
+/** The complete display tree for a parsed `INSERT`. */
+export function insertDisplayTree(ast) {
+    const children = [intoNode(ast.into)];
+    if (ast.columns)
+        children.push(insertColumnsNode(ast.columns));
+    children.push(valuesNode(ast.values));
+    return root(children, ast.span, 'INSERT');
+}
+/** Emit the parse stage for an `INSERT`, one clause at a time — mirrors `emitParseEvents`. */
+export function emitInsertParseEvents(emit, ast) {
+    const children = [intoNode(ast.into)];
+    emit(`Read the INTO clause: INSERT adds a row to the \`${ast.into.name}\` table.`, {
+        stage: 'parse',
+        ast: root([...children], ast.span, 'INSERT'),
+        span: ast.into.span,
+    });
+    if (ast.columns) {
+        children.push(insertColumnsNode(ast.columns));
+        emit(`Read the column list: ${ast.columns.names.map((c) => `\`${c.name}\``).join(', ')}.`, { stage: 'parse', ast: root([...children], ast.span, 'INSERT'), span: ast.columns.span });
+    }
+    children.push(valuesNode(ast.values));
+    emit(`Read the VALUES list: ${ast.values.items.length} value${ast.values.items.length === 1 ? '' : 's'}. Nothing has been written yet — this is still only structure.`, { stage: 'parse', ast: root([...children], ast.span, 'INSERT'), span: ast.values.span });
+    const tree = root([...children], ast.span, 'INSERT');
+    emit(`Parsing is done: ${countNodes(tree)} AST nodes and no data touched. There is nothing to plan or optimize — an INSERT with only literal values goes straight to execution.`, { stage: 'parse', ast: tree, span: ast.span });
+}
+/** The complete display tree for a parsed `UPDATE`. */
+export function updateDisplayTree(ast) {
+    const children = [updateTableNode(ast.table), setNode(ast.set)];
+    if (ast.where)
+        children.push(whereNode(ast.where));
+    return root(children, ast.span, 'UPDATE');
+}
+/** Emit the parse stage for an `UPDATE`, one clause at a time — mirrors `emitParseEvents`. */
+export function emitUpdateParseEvents(emit, ast) {
+    const children = [updateTableNode(ast.table)];
+    emit(`Read the table name: UPDATE modifies rows in \`${ast.table.name}\`.`, {
+        stage: 'parse',
+        ast: root([...children], ast.span, 'UPDATE'),
+        span: ast.table.span,
+    });
+    children.push(setNode(ast.set));
+    emit(`Read the SET clause: ${ast.set.assignments.map((a) => `\`${a.column}\` = ${exprToSql(a.value)}`).join(', ')}. Nothing has been written yet — this is still only structure.`, { stage: 'parse', ast: root([...children], ast.span, 'UPDATE'), span: ast.set.span });
+    if (ast.where) {
+        children.push(whereNode(ast.where));
+        emit('Read the WHERE clause and build the predicate tree. Nothing has been modified yet — this is still only structure.', { stage: 'parse', ast: root([...children], ast.span, 'UPDATE'), span: ast.where.span });
+    }
+    const tree = root([...children], ast.span, 'UPDATE');
+    emit(`Parsing is done: ${countNodes(tree)} AST nodes and no data touched. The planner turns the WHERE clause into a plan next — the SET clause has nothing to plan, it only takes effect once a row is found.`, { stage: 'parse', ast: tree, span: ast.span });
+}
+/** The complete display tree for a parsed `ANALYZE`. */
+export function analyzeDisplayTree(ast) {
+    return root([updateTableNode(ast.table)], ast.span, 'ANALYZE');
+}
+/** Emit the parse stage for an `ANALYZE` — one clause, so one step: mirrors `emitParseEvents`'s shape all the same. */
+export function emitAnalyzeParseEvents(emit, ast) {
+    const tree = root([updateTableNode(ast.table)], ast.span, 'ANALYZE');
+    emit(`Read the table name: ANALYZE scans \`${ast.table.name}\` to build its statistics.`, {
+        stage: 'parse',
+        ast: tree,
+        span: ast.table.span,
+    });
+    emit(`Parsing is done: ${countNodes(tree)} AST node${countNodes(tree) === 1 ? '' : 's'} and no data touched. There is nothing to plan or optimize — ANALYZE goes straight to a real scan.`, { stage: 'parse', ast: tree, span: ast.span });
+}

package/dist/src/engine/parser/index.js

@@ -0,0 +1,4 @@
+export { AGGREGATE_FNS, parse, parseStatement } from "./parser.js";
+export { tokenize, KEYWORDS, TokenizeError } from "./tokenizer.js";
+export { analyzeDisplayTree, deleteDisplayTree, emitAnalyzeParseEvents, emitDeleteParseEvents, emitInsertParseEvents, emitParseEvents, emitUpdateParseEvents, insertDisplayTree, toDisplayTree, updateDisplayTree, } from "./display.js";
+export { aggregateKeyOf, childrenOf, columnKey, columnsIn, mapChildren, selectItemArgColumn, selectItemKey, walkExpr } from "./ast.js";