@omgbase/oqx 0.20.0 → 0.23.0

package/src/lexer.ts

@@ -10,7 +10,14 @@
 // alter the grammar — the prepared-statement / injection-safe property the
 // host-bindings design note calls for. (A consequence: `${x}` inside a string
 // literal does not interpolate — that fragment would be an unterminated string —
-// which is exactly the desired "interpolation is a value, never source text".)
+// which is exactly the desired "interpolation is a value, never source text".
+// The same holds for a backtick template literal (0.21): a fragment that ends
+// inside one is an unterminated literal, so a bound value never stands in one.)
+//
+// Template literals `` `text ${expr}` `` are lexed with a mode stack: the text
+// between the backticks is one `tmpl_text` token per run (decoded), a `${`
+// opens an interpolation whose tokens are ordinary source until the `}` that
+// balances it, and an interpolation may hold another template literal.
 //
 // Positions (`Token.pos` / `Token.end`, the `span` of every AST node, and the
 // offsets quoted in error messages) count Unicode CODE POINTS over the raw
@@ -37,15 +44,23 @@ export type TokType =
   | "caret" // ^ — one-scope lift marker
   | "dot"
   | "range" // `..` (inclusive) or `...` (exclusive end) — a Ruby-style range operator (value carries which)
-  | "op" // == != <= >= < > && || ! + - * / %  (value carries the operator)
+  | "op" // == != <= >= < > && || ! + - * / % ~ ~* !~ !~*  (value carries the operator)
   | "binding" // a ${…} interpolation; `index` names the value slot
+  // A template literal (since 0.21): the opening and closing backticks, a run of
+  // its decoded text, and the `${` / `}` around an interpolation — whose `}` is a
+  // token of its own, so a block's `}` inside the interpolation stays `rbrace`.
+  | "tmpl_start"
+  | "tmpl_text"
+  | "tmpl_interp_start"
+  | "tmpl_interp_end"
+  | "tmpl_end"
   | "eof";
 
 export interface Token {
   type: TokType;
   /** The source text of the token, except: a `string` token carries its decoded
-   * value (quotes stripped, escapes resolved); a `binding` carries the display
-   * marker `${N}`; `eof` carries `""`. */
+   * value (quotes stripped, escapes resolved), and so does a `tmpl_text` run; a
+   * `binding` carries the display marker `${N}`; `eof` carries `""`. */
   value: string;
   /** Code-point offset of the token's first character. */
   pos: number;
@@ -57,8 +72,12 @@ export interface Token {
 const KEYWORDS = new Set(["from", "where", "select", "is", "not", "and", "or"]);
 
 // Multi-char operators, longest first (the scanner tries these before singles).
-const MULTI_OPS = ["==", "!=", "<=", ">=", "&&", "||"];
-const SINGLE_OPS = new Set(["<", ">", "!", "+", "-", "*", "/", "%"]);
+// The regex operators (since 0.22) are among them: `!~*` is tried before `!~`,
+// which is tried before `!` — so `name!~"B"` is `name !~ "B"`, not a required
+// `name!` — and `~*` before `~`, so `x~*y` is `x ~* y`.
+const TRIPLE_OPS = ["!~*"];
+const MULTI_OPS = ["==", "!=", "<=", ">=", "&&", "||", "!~", "~*"];
+const SINGLE_OPS = new Set(["<", ">", "!", "+", "-", "*", "/", "%", "~"]);
 
 const isIdentStart = (c: string): boolean => /^[A-Za-z_$]$/.test(c);
 const isIdentPart = (c: string): boolean => /^[A-Za-z0-9_$]$/.test(c);
@@ -78,7 +97,16 @@ export function lexTemplate(fragments: readonly string[], values: number): Token
   const tokens: Token[] = [];
   let base = 0; // running offset across fragments + rendered `${…}` markers
   for (let f = 0; f < fragments.length; f++) {
-    lexFragment(fragments[f]!, base, tokens);
+    try {
+      lexFragment(fragments[f]!, base, tokens);
+    } catch (err) {
+      // A fragment ends inside a backtick literal: the bound value would have
+      // to stand inside it, and a bound value is never source text (GRAMMAR §1).
+      if (err instanceof OqxError && f < fragments.length - 1 && err.message.startsWith("unterminated template literal")) {
+        throw new OqxError(`${err.message} — a template literal must be complete within one fragment: a \${…} binding cannot stand inside a backtick literal (interpolate a name, or bind the whole string)`, "lex");
+      }
+      throw err;
+    }
     base += codePointLength(fragments[f]!);
     if (f < fragments.length - 1) {
       // account for the value's rendered width in the display source (see rawSource)
@@ -103,6 +131,14 @@ export function lexString(src: string): Token[] {
   return tokens;
 }
 
+// The lexer's mode inside a template literal (GRAMMAR §1, since 0.21): the text of
+// the literal, or a `${…}` interpolation, which is ordinary source again — with a
+// brace depth, so the `}` that closes the interpolation is told from a block's.
+// Nesting is a stack: an interpolation may hold another template literal.
+type Mode =
+  | { kind: "template"; start: number }
+  | { kind: "interp"; start: number; depth: number };
+
 function lexFragment(src: string, base: number, out: Token[]): void {
   // One entry per code point, so every index below is a code-point offset.
   const cps = Array.from(src);
@@ -113,16 +149,47 @@ function lexFragment(src: string, base: number, out: Token[]): void {
   const push = (type: TokType, value: string, start: number, end: number): void => {
     out.push({ type, value, pos: base + start, end: base + end });
   };
+  const modes: Mode[] = [];
 
   while (i < n) {
+    const mode = modes[modes.length - 1];
+
+    // Template text: everything up to the closing backtick or the `${` of an
+    // interpolation, decoded with the string escapes (`\<c>` is `<c>`, so `` \` ``
+    // and `\$` keep a backtick or a dollar literal). Newlines are kept verbatim.
+    if (mode?.kind === "template") {
+      const start = i;
+      let sval = "";
+      while (i < n) {
+        const c = cps[i]!;
+        if (c === "`" || (c === "$" && at(i + 1) === "{")) break;
+        if (c === "\\") { i++; sval += unescape(cps[i]); i++; continue; }
+        sval += c;
+        i++;
+      }
+      if (i > start) push("tmpl_text", sval, start, Math.min(i, n));
+      if (i >= n) break; // unterminated — reported below
+      if (cps[i] === "`") { push("tmpl_end", "`", i, i + 1); i++; modes.pop(); continue; }
+      push("tmpl_interp_start", "${", i, i + 2);
+      modes.push({ kind: "interp", start: i, depth: 0 });
+      i += 2;
+      continue;
+    }
+
     const c = cps[i]!;
 
     if (c === " " || c === "\t" || c === "\n" || c === "\r") { i++; continue; }
 
+    if (c === "`") { push("tmpl_start", c, i, i + 1); modes.push({ kind: "template", start: i }); i++; continue; }
     if (c === "(") { push("lparen", c, i, i + 1); i++; continue; }
     if (c === ")") { push("rparen", c, i, i + 1); i++; continue; }
-    if (c === "{") { push("lbrace", c, i, i + 1); i++; continue; }
-    if (c === "}") { push("rbrace", c, i, i + 1); i++; continue; }
+    if (c === "{") { if (mode) mode.depth++; push("lbrace", c, i, i + 1); i++; continue; }
+    if (c === "}") {
+      // Inside an interpolation a `}` at depth 0 closes it; deeper, it closes a block.
+      if (mode && mode.depth === 0) { push("tmpl_interp_end", c, i, i + 1); i++; modes.pop(); continue; }
+      if (mode) mode.depth--;
+      push("rbrace", c, i, i + 1); i++; continue;
+    }
     if (c === "[") { push("lbracket", c, i, i + 1); i++; continue; }
     if (c === "]") { push("rbracket", c, i, i + 1); i++; continue; }
     if (c === ",") { push("comma", c, i, i + 1); i++; continue; }
@@ -183,7 +250,9 @@ function lexFragment(src: string, base: number, out: Token[]): void {
       continue;
     }
 
-    // operators (multi-char first)
+    // operators (multi-char first, longest first)
+    const three = c + at(i + 1) + at(i + 2);
+    if (TRIPLE_OPS.includes(three)) { push("op", three, i, i + 3); i += 3; continue; }
     const two = c + at(i + 1);
     if (MULTI_OPS.includes(two)) { push("op", two, i, i + 2); i += 2; continue; }
     if (SINGLE_OPS.has(c)) { push("op", c, i, i + 1); i++; continue; }
@@ -200,6 +269,13 @@ function lexFragment(src: string, base: number, out: Token[]): void {
 
     throw new OqxError(`unexpected character ${JSON.stringify(c)} at ${base + i}`, "lex");
   }
+
+  // The end of the source inside a template literal.
+  const open = modes[modes.length - 1];
+  if (open?.kind === "template") throw new OqxError(`unterminated template literal at ${base + open.start}`, "lex");
+  if (open?.kind === "interp") {
+    throw new OqxError(`unterminated \${…} interpolation in a template literal at ${base + open.start} — expected '}'`, "lex");
+  }
 }
 
 // Scan a number whose first digit is at `i`; return the index just past it.

package/src/optimize/analysis.ts

@@ -16,6 +16,7 @@
 //     value into an enclosing scope (§19), observable by later conjuncts.
 
 import type { Expr, Follow, OpNode, SelectItem, Subquery, Where } from "../ast.ts";
+import { isRegexOp } from "../ast.ts";
 import type { RuleContext } from "./ir.ts";
 
 // ---- scope reads --------------------------------------------------------------
@@ -35,6 +36,7 @@ export function exprReadsScopeIn(e: Expr, at: number, upTo: number): boolean {
     case "binary": case "logical": case "in": return exprReadsScopeIn(e.left, at, upTo) || exprReadsScopeIn(e.right, at, upTo);
     case "range": return (e.lo !== null && exprReadsScopeIn(e.lo, at, upTo)) || (e.hi !== null && exprReadsScopeIn(e.hi, at, upTo));
     case "tuple": return e.items.some((x) => exprReadsScopeIn(x, at, upTo));
+    case "template": return e.parts.some((p) => typeof p !== "string" && exprReadsScopeIn(p, at, upTo));
   }
 }
 
@@ -98,9 +100,15 @@ export function exprRaiseFree(e: Expr, ctx: RuleContext): boolean {
     case "op": return opRaiseFree(e, ctx); // a value-position directive projects: never raise-free
     case "member": return exprRaiseFree(e.recv, ctx);
     case "unary": return exprRaiseFree(e.expr, ctx);
-    case "binary": case "logical": case "in": return exprRaiseFree(e.left, ctx) && exprRaiseFree(e.right, ctx);
+    // A regex operator (0.22) is a `matches` call in disguise: the pattern may
+    // be invalid, so it is never raise-free.
+    case "binary": return !isRegexOp(e.op) && exprRaiseFree(e.left, ctx) && exprRaiseFree(e.right, ctx);
+    case "logical": case "in": return exprRaiseFree(e.left, ctx) && exprRaiseFree(e.right, ctx);
     case "range": return (e.lo === null || exprRaiseFree(e.lo, ctx)) && (e.hi === null || exprRaiseFree(e.hi, ctx));
     case "tuple": return e.items.every((x) => exprRaiseFree(x, ctx));
+    // A template literal raises on a list or record interpolation (§7b), which
+    // only the data decides: with an interpolation it is never raise-free.
+    case "template": return e.parts.every((p) => typeof p === "string");
   }
 }
 

package/src/parser.ts

@@ -64,6 +64,11 @@
 // Tuples (0.20): `(e1, e2, …)` with two or more elements is a `tuple` node — a
 // value and a receiver; one expression in parentheses stays grouping.
 //
+// Template literals (0.21): `` `text ${expr} text` `` is a `template` node — a
+// primary value whose interpolations are full expressions read at the current
+// depth (`parseTemplateLiteral`); the lexer balances the braces, so an
+// interpolation may hold a `{ … }` block or another template literal.
+//
 // Principle of least surprise, applied to the grammar: a rule a careful user
 // would not predict is a bug. Hence `!` binds tighter than comparison in every
 // position (`!a == b` is `(!a) == b`, as in C); parentheses in `where` group a
@@ -78,7 +83,7 @@ import { lexTemplate, lexString } from "./lexer.ts";
 import { OqxError } from "./errors.ts";
 import type {
   Query, Where, Expr, OpNode, Subquery, SelectItem, OrderSpec, Follow, FollowDestination, Consumer, RelOp,
-  BinaryOp, Span,
+  BinaryOp, Span, TemplatePart,
 } from "./ast.ts";
 import { resolveSelect, resolveWhere } from "./resolve.ts";
 import { printTemplate } from "./print.ts";
@@ -104,7 +109,10 @@ const CLAUSE_WORDS = new Set<string>([
   "limit", "offset",
 ]);
 const RELOPS = new Set<string>(["==", "!=", "<", "<=", ">", ">="]);
-const CMP_OPS = new Set<string>(["==", "!=", "<", "<=", ">", ">="]);
+// The comparison level (GRAMMAR §4): the six relational operators and, since
+// 0.22, the four regex operators — sugar over `matches`, non-associative like
+// the rest of the level.
+const CMP_OPS = new Set<string>(["==", "!=", "<", "<=", ">", ">=", "~", "~*", "!~", "!~*"]);
 const ADD_OPS = new Set<string>(["+", "-"]);
 const MUL_OPS = new Set<string>(["*", "/", "%"]);
 // `true`/`false`/`null` are literals in every position, so they can never name a
@@ -194,7 +202,10 @@ class Parser {
     return t.type === "op" && t.value === value;
   }
   private fail(msg: string): never {
-    throw new OqxError(`${msg} (at offset ${this.peek().pos})`, "parse");
+    this.failAt(this.peek().pos, msg);
+  }
+  private failAt(pos: number, msg: string): never {
+    throw new OqxError(`${msg} (at offset ${pos})`, "parse");
   }
   /** Code-point offset of the next token (the start of a node about to be parsed). */
   private start(): number { return this.peek().pos; }
@@ -1042,7 +1053,7 @@ class Parser {
   // `recv first { where p }`; a trailing `!` makes the index required and the
   // predicate a `single` (required too, so that zero matches is an error).
   private parseBracket(recv: Expr): Expr {
-    if (recv.kind === "lit") this.fail(`\`${describe(recv)}\` is a literal, not a collection`);
+    if (recv.kind === "lit" || recv.kind === "template") this.fail(`\`${describe(recv)}\` is a literal, not a collection`);
     const start = recv.span[0];
     const lbracket = this.next().pos; // '['
     let index: Expr | null = null;
@@ -1170,7 +1181,7 @@ class Parser {
     if (!t) return false;
     if (t.type === "ident") return !CLAUSE_WORDS.has(t.value);
     if (t.type === "kw") return t.value === "is" || t.value === "not"; // the prefix operators
-    if (t.type === "number" || t.type === "string" ||
+    if (t.type === "number" || t.type === "string" || t.type === "tmpl_start" ||
         t.type === "binding" || t.type === "lparen" || t.type === "caret") return true;
     return t.type === "op" && (t.value === "-" || t.value === "!");
   }
@@ -1242,7 +1253,7 @@ class Parser {
         // { … }` (0.20: the receiver-block sugar stands wherever a value does,
         // `size(children { is checked })`). exists/none/count have no value form
         // and are left to the body's own error.
-        if (expr.kind === "lit") this.fail(`\`${describe(expr)}\` is a literal, not a collection`);
+        if (expr.kind === "lit" || expr.kind === "template") this.fail(`\`${describe(expr)}\` is a literal, not a collection`);
         expr = this.parseConsumerBlock(expr, this.atBlock()!, false);
       } else {
         break; // anything else ends the chain
@@ -1282,6 +1293,7 @@ class Parser {
     }
     if (t.type === "number") { this.next(); return { kind: "lit", span: [t.pos, t.end], value: Number(t.value) }; }
     if (t.type === "string") { this.next(); return { kind: "lit", span: [t.pos, t.end], value: t.value }; }
+    if (t.type === "tmpl_start") return this.parseTemplateLiteral();
     if (t.type === "binding") { this.next(); return this.bindingNode(t); }
     if (t.type === "lparen") {
       this.next();
@@ -1308,6 +1320,39 @@ class Parser {
     }
     this.fail(`unexpected ${this.tokDesc()} — expected a value`);
   }
+
+  // A template literal (GRAMMAR §4, since 0.21): the cursor is at the opening
+  // backtick. The lexer has already split the literal into text runs and `${ … }`
+  // interpolations (with balanced braces, so an interpolation may hold a block
+  // or another template literal); each interpolation holds one full value
+  // expression, read at the current scope depth. `parts` alternates strictly —
+  // text, expression, text, … — with a (possibly empty) text part first and last.
+  private parseTemplateLiteral(): Expr {
+    const open = this.next(); // the backtick
+    const parts: TemplatePart[] = [];
+    let text = "";
+    for (;;) {
+      const t = this.peek();
+      if (t.type === "tmpl_text") { this.next(); text += t.value; continue; }
+      if (t.type === "tmpl_end") { this.next(); break; }
+      if (t.type === "tmpl_interp_start") {
+        this.next();
+        if (this.at("tmpl_interp_end")) {
+          this.failAt(t.pos, "empty interpolation `${}` in a template literal — an interpolation holds an expression (`${name}`)");
+        }
+        const e = this.parseValueExpr();
+        if (!this.at("tmpl_interp_end")) this.fail("expected '}' to close the `${…}` interpolation of a template literal");
+        this.next();
+        parts.push(text, e);
+        text = "";
+        continue;
+      }
+      // Unreachable: the lexer closes every literal it opens or fails.
+      this.fail(`unexpected ${this.tokDesc()} in a template literal`);
+    }
+    parts.push(text);
+    return { kind: "template", span: [open.pos, this.end()], parts };
+  }
 }
 
 // The default key of an unaliased projection item: the last segment of a bare /

package/src/print.ts

@@ -66,9 +66,10 @@ const OR = 1, AND = 2, CMP = 3, RANGE = 4, ADD = 5, MUL = 6, UNARY = 7, POSTFIX
 
 function prec(e: Expr): number {
   switch (e.kind) {
-    case "lit": case "ident": case "outer": case "binding": case "tuple": return PRIMARY;
+    case "lit": case "ident": case "outer": case "binding": case "tuple": case "template": return PRIMARY;
     case "member": case "call": case "required": case "op": return POSTFIX;
     case "unary": return UNARY;
+    // Comparison, identity and the regex operators (0.22) share the cmp level.
     case "binary": return e.op === "+" || e.op === "-" ? ADD : e.op === "*" || e.op === "/" || e.op === "%" ? MUL : CMP;
     case "in": return CMP;
     case "range": return RANGE;
@@ -231,6 +232,10 @@ function expr(e: Expr): Out {
       return cat(e.lo ? operand(e.lo, ADD) : "", e.exclusiveEnd ? "..." : "..", e.hi ? operand(e.hi, ADD) : "");
     // A tuple is self-delimiting; its elements are full expressions.
     case "tuple": return cat("(", join(e.items.map(expr), ", "), ")");
+    // A template literal prints as one: its text with the GRAMMAR §1 escapes
+    // (`` \` ``, `\\`, `\$` before a `{`, and the control characters), each
+    // interpolation as `${…}` around the full expression.
+    case "template": return cat("`", ...e.parts.map((p) => (typeof p === "string" ? templateText(p) : cat("${", expr(p), "}"))), "`");
   }
 }
 
@@ -264,13 +269,35 @@ function quote(s: string): string {
   for (const ch of s) {
     switch (ch) {
       case '"': out += '\\"'; break;
-      case "\\": out += "\\\\"; break;
-      case "\n": out += "\\n"; break;
-      case "\t": out += "\\t"; break;
-      case "\r": out += "\\r"; break;
-      case "\0": out += "\\0"; break;
-      default: out += ch;
+      default: out += escapeChar(ch);
     }
   }
   return out + '"';
 }
+
+/** The text of a template literal part, escaped so it re-lexes to itself: the
+ * backtick and the backslash, the control characters as in a string, and a `$`
+ * that a `{` follows (which would otherwise open an interpolation). */
+function templateText(s: string): string {
+  const cps = Array.from(s);
+  let out = "";
+  for (let i = 0; i < cps.length; i++) {
+    const ch = cps[i]!;
+    if (ch === "`") out += "\\`";
+    else if (ch === "$" && cps[i + 1] === "{") out += "\\$";
+    else out += escapeChar(ch);
+  }
+  return out;
+}
+
+/** The escapes a string literal and a template literal share (GRAMMAR §1). */
+function escapeChar(ch: string): string {
+  switch (ch) {
+    case "\\": return "\\\\";
+    case "\n": return "\\n";
+    case "\t": return "\\t";
+    case "\r": return "\\r";
+    case "\0": return "\\0";
+    default: return ch;
+  }
+}

package/src/references.ts

@@ -0,0 +1,238 @@
+// The `references` static pass (spec/oqx/AST.md §5b, language 0.23): every
+// NAME a query reads from a row — a bare identifier, a dotted navigation headed
+// by one, an outer reference — with the clause it stands in and the SCOPE whose
+// rows it is read from, described as the chain of expressions that produce
+// those rows (the source, each `from` re-projection, each block receiver, each
+// `follow` walk). The pass knows no data: a host that knows what rows an
+// expression yields maps each scope to a row type and judges the name against
+// it (omgbase: "is `target` a field of links?"). Built on `visit`, so a future
+// node kind is walked here the day it is added to `CHILDREN`.
+//
+// What is a reference and what is not (the rules, pinned by
+// `cases/references.json`):
+//   • a bare `ident` is a reference to the current row's property, with the
+//     name as written; a `member` chain headed by an `ident` or `outer` is ONE
+//     reference whose name is the full dotted path (`doc.layer`, `meta.owner`);
+//     a chain headed by anything else (a call, a block, a literal, a tuple) is
+//     not — its head is walked and the trailing `.name`s are ignored, since the
+//     head's value is not a row of any scope;
+//   • an `outer` (`^name`, `N^name`) is a reference read in the scope `levels`
+//     out; `$it` as a head is the row itself (`$it.title` ≡ `title`,
+//     `^$it.title` ≡ `^title`) and `$it` alone is no reference;
+//   • `$`-names (`$key`, `$depth`, `$stop`, …) are the language's values, never
+//     references; a `binding` is a host value; a function or method NAME is
+//     not a reference, its receiver and arguments are walked
+//     (`target.contains("x")` references `target`); a name a nested block
+//     LIFTS onto a scope (`^open: value`, SEMANTICS §19) is a binding of that
+//     scope, so reading it there (`select open`, `^open` from deeper) is not a
+//     reference either;
+//   • a `select` alias is not a reference where the language resolves it
+//     (SEMANTICS §14): in the same body's `where`, and in the items to its
+//     right — a bare identifier naming such an alias, or a chain headed by it,
+//     is skipped; an alias's own name inside its own item is the row field and
+//     IS a reference; `order by`, `frontier`, `limit`/`offset`, `from` and
+//     `follow` are not rewritten against aliases, so a name there is a
+//     reference whatever the `select` says;
+//   • a name read at the ROOT scope — the head of the top-level `source`
+//     (`from people`: clause `source`), an outer reference with as many carets
+//     as there are enclosing scopes (`^docs` from a top-level row) — is
+//     reported with depth 0 and no steps: it names one of the host's roots,
+//     and the host decides what to make of it;
+//   • a `follow` destination that is a plain expression is a reference read
+//     on the frontier row (clause `follow.destination`), like a `from`.
+//
+// The scope: `{ depth, steps }`. `depth` is the scope depth the name is
+// evaluated at (`visit`'s depth; for an outer reference, that depth minus its
+// levels). `steps` are the expressions that produce the scope's rows, root
+// first, each with the depth of the rows it produces: the query's `source`
+// (depth 1), each `from` re-projection in turn (the same depth — a `from`
+// replaces the rows), a block's receiver (one deeper than where it is read),
+// then the block's own `from`s; a `follow` node is a step too — the walk's
+// frontier rows, at the body's depth, which the destinations are read on
+// (a destination block's receiver is then one deeper). A name read inside the
+// k-th `from` sees only the steps before it. For an outer reference the steps
+// are cut after the last step at its scope's depth. The empty list is the root
+// scope.
+
+import type { AstNode, Expr, Follow, Query, SelectItem, Span, Subquery } from "./ast.ts";
+import type { Clause } from "./walk.ts";
+import { visit } from "./walk.ts";
+
+/** One step of a scope's row chain: an expression (a source, a `from`, a block
+ * receiver, a plain destination) or a `follow` node (the walk's frontier rows),
+ * with the scope depth of the rows it produces. */
+export interface ReferenceStep {
+  readonly expr: Expr | Follow;
+  readonly depth: number;
+}
+
+export interface ReferenceScope {
+  /** The scope depth the name is read at (SEMANTICS §2; 0 = the root scope). */
+  readonly depth: number;
+  /** The row chain producing the scope's rows, root first. */
+  readonly steps: readonly ReferenceStep[];
+}
+
+export interface Reference {
+  /** The name as written — the full dotted path for a navigation (`doc.layer`), without a `$it.` head. */
+  readonly name: string;
+  readonly clause: Clause;
+  readonly scope: ReferenceScope;
+  /** The span of the whole reference (the chain, for a navigation). */
+  readonly span: Span;
+}
+
+/** A dotted name headed by an `ident` or `outer`: the head and the path after it. */
+function dottedName(e: Expr): { head: Expr & { kind: "ident" | "outer" }; path: string[] } | null {
+  if (e.kind === "ident" || e.kind === "outer") return { head: e, path: [] };
+  if (e.kind === "member") {
+    const inner = dottedName(e.recv);
+    return inner === null ? null : { head: inner.head, path: [...inner.path, e.name] };
+  }
+  return null;
+}
+
+/** The alias an item defines (SEMANTICS §14): a named `collect`, or a named non-lift field. */
+function aliasName(it: SelectItem): string | null {
+  if (it.kind === "collect") return it.name === "" ? null : it.name;
+  return it.lift === 0 && it.name !== "" ? it.name : null;
+}
+
+/** Every name a query (or block body) reads from a row, in canonical source order. */
+export function references(root: Query | Subquery): Reference[] {
+  const out: Reference[] = [];
+  const lifts = new Map<Query | Subquery, ReadonlySet<string>>();
+  visit(root, {
+    enter(node, ctx) {
+      const named = dottedName(node as Expr);
+      if (named === null) return;
+      const { head } = named;
+      // The head of a navigation is handled here, once, with the chain's full name.
+      let name = head.name;
+      let path = named.path;
+      if (name === "$it") {
+        if (path.length === 0) return false; // the row itself
+        name = path[0]!;
+        path = path.slice(1);
+      } else if (name.startsWith("$")) return false; // a language value
+      if (ctx.clause === null) return false; // unreachable: the root node is never a name
+      if (head.kind === "ident" && isResolvedAlias(name, ctx.path, ctx.clause)) return false;
+      const levels = head.kind === "outer" ? head.levels : 0;
+      const depth = ctx.depth - levels;
+      if (isLiftBound(name, depth, ctx.path, lifts)) return false;
+      const full = [name, ...path].join(".");
+      const steps = scopeSteps(ctx.path, node);
+      const scoped = levels === 0 ? steps : cutAt(steps, depth);
+      out.push({ name: full, clause: ctx.clause, scope: { depth, steps: scoped }, span: node.span });
+      return false;
+    },
+  });
+  return out;
+}
+
+/** Whether a bare `name` in this position is a `select` alias the language
+ * substitutes (so the name is the alias, not a row property): in the body's
+ * `where`, any alias; in a `select` item, an alias defined to its LEFT. */
+function isResolvedAlias(name: string, path: readonly AstNode[], clause: Clause): boolean {
+  if (clause !== "where" && clause !== "select") return false;
+  // The nearest body, and the item under it when we are inside its select.
+  for (let i = path.length - 1; i >= 0; i--) {
+    const a = path[i]!;
+    if (a.kind !== "query" && a.kind !== "subquery") continue;
+    const index = new Map<string, number>();
+    a.select.forEach((it, j) => { const n = aliasName(it); if (n !== null) index.set(n, j); });
+    const j = index.get(name);
+    if (j === undefined) return false;
+    if (clause === "where") return true;
+    const item = path[i + 1];
+    const at = item === undefined ? -1 : a.select.indexOf(item as SelectItem);
+    return at >= 0 && j < at;
+  }
+  return false;
+}
+
+/**
+ * Whether `name`, read at scope `depth`, is bound there by a lift (`^name: expr`
+ * in a nested block, SEMANTICS §19): the lifted value is appended to that
+ * scope's row record, so the name is a binding, not a row property. The body
+ * whose rows are at `depth` is the depth-th body on the path (every nested body
+ * is one scope deeper than the one around it).
+ */
+function isLiftBound(name: string, depth: number, path: readonly AstNode[], cache: Map<Query | Subquery, ReadonlySet<string>>): boolean {
+  if (depth < 1) return false;
+  const bodies = path.filter((a): a is Query | Subquery => a.kind === "query" || a.kind === "subquery");
+  const body = bodies[depth - 1];
+  if (body === undefined) return false;
+  let names = cache.get(body);
+  if (names === undefined) {
+    names = liftsLandingOn(body);
+    cache.set(body, names);
+  }
+  return names.has(name);
+}
+
+/** The names the nested blocks of `body` lift onto it: a `field` item with `lift` L in a block L scopes below it. */
+function liftsLandingOn(body: Query | Subquery): ReadonlySet<string> {
+  const names = new Set<string>();
+  const own = body.kind === "subquery" ? 1 : 0;
+  visit(body, {
+    enter(node, ctx) {
+      if (node.kind !== "field" || node.lift === 0) return;
+      const below = ctx.path.filter((a) => a.kind === "subquery").length - own;
+      if (node.lift === below) names.add(node.name);
+    },
+  });
+  return names;
+}
+
+/** The row chain of the scope a node is evaluated in, from its ancestors. */
+function scopeSteps(path: readonly AstNode[], node: AstNode): ReferenceStep[] {
+  const steps: ReferenceStep[] = [];
+  let depth = 0;
+  for (let i = 0; i < path.length; i++) {
+    const a = path[i]!;
+    const next: AstNode = path[i + 1] ?? node;
+    switch (a.kind) {
+      case "query": {
+        if (next === a.source || next === a.limit || next === a.offset) break; // read at the root scope
+        depth = 1;
+        steps.push({ expr: a.source, depth });
+        pushFroms(steps, a.from, next, depth);
+        break;
+      }
+      case "subquery": {
+        // The receiver step was pushed by the enclosing `op`; this body's rows
+        // are one deeper than where that receiver was read.
+        pushFroms(steps, a.from, next, depth);
+        break;
+      }
+      case "op": {
+        if (next !== a.sub) break; // inside the receiver: read where the block is read
+        depth += 1;
+        steps.push({ expr: a.receiver, depth });
+        break;
+      }
+      case "follow": {
+        // The destinations are read on the walk's frontier rows, at the body's depth.
+        steps.push({ expr: a, depth });
+        break;
+      }
+      default: break;
+    }
+  }
+  return steps;
+}
+
+/** The `from` re-projections that apply at `next`: all of them unless `next` is one of them, in which case those before it. */
+function pushFroms(steps: ReferenceStep[], from: readonly Expr[], next: AstNode, depth: number): void {
+  const at = from.indexOf(next as Expr);
+  const upto = at === -1 ? from.length : at;
+  for (let k = 0; k < upto; k++) steps.push({ expr: from[k]!, depth });
+}
+
+/** The steps up to and including the last one producing rows at `depth` (none for the root scope). */
+function cutAt(steps: readonly ReferenceStep[], depth: number): ReferenceStep[] {
+  let end = 0;
+  steps.forEach((s, i) => { if (s.depth === depth) end = i + 1; });
+  return steps.slice(0, end);
+}

package/src/resolve.ts

@@ -141,6 +141,10 @@ function mapExpr(e: Expr, f: (e: Expr) => Expr | null): Expr {
       const items = mapSame(e.items, go);
       return items === e.items ? e : { ...e, items };
     }
+    case "template": { // the text parts are strings; only the interpolations are expressions
+      const parts = mapSame(e.parts, (p) => (typeof p === "string" ? p : go(p)));
+      return parts === e.parts ? e : { ...e, parts };
+    }
     case "op": { // the receiver is read in this scope; the block is its own scope
       const receiver = go(e.receiver);
       return receiver === e.receiver ? e : { ...e, receiver };

package/src/version.ts

@@ -1,4 +1,4 @@
 /** The OQX language version (`spec/oqx/VERSION`, `major.minor`) this implementation
  * conforms to — distinct from the package's own semver, whose `major.minor` it
  * equals. Stamped on every `toJSON` document. */
-export const LANGUAGE_VERSION = "0.20";
+export const LANGUAGE_VERSION = "0.23";