@dforge-core/metadata 0.0.23 → 0.0.25

package/src/dsl/check.ts

@@ -12,7 +12,13 @@
 
 import { BUILTIN_BY_NAME } from "./builtins";
 import { CONTROL_KEYWORDS, type Token } from "./lexer";
-import { type DslDocument, type Span, blockLabelAt, parseDsl } from "./parse";
+import {
+	type BlockKind,
+	type DslDocument,
+	type Span,
+	blockLabelAt,
+	parseDsl,
+} from "./parse";
 import type { ColumnLookup, DslContext, DslIssue, DslSeverity } from "./types";
 
 /**
@@ -51,6 +57,94 @@ export function checkDsl(text: string, ctx: DslContext = {}): DslIssue[] {
 	const isBatch = (action?.executionMode ?? "single") === "batch";
 	const hasColumn = columnMatcher(entity?.columns);
 
+	// ── structure ────────────────────────────────────────────────────
+	// ActionDslCompiler.ParseBlocks reads the headers before anything else, so
+	// a file that loses a block here loses it wholesale: the body still looks
+	// like code, and nothing runs.
+	if (text.trim() === "") {
+		add(
+			{ start: 0, end: text.length },
+			"A DSL body needs at least an execute: block — an empty file installs an action that does nothing.",
+			"error",
+			"dsl/empty-script",
+		);
+		return out;
+	}
+
+	// A file with no headers at all has no label to point at, and a zero-width
+	// span renders as a caret before the first character — so fall back to the
+	// first token, which is where the reader is already looking.
+	const firstToken = parsed.tokens[0];
+	const firstLabel = parsed.blocks[0]?.label ??
+		(firstToken ? { start: firstToken.start, end: firstToken.end } : { start: 0, end: text.length });
+	if (!parsed.blocks.some((b) => b.kind === "execute")) {
+		add(
+			firstLabel,
+			"No execute: block — it is the only required block, and the compiler runs nothing without it.",
+			"error",
+			"dsl/missing-execute",
+		);
+	}
+
+	// `execute:` is matched as `(.*?)\z`, and its lookahead lists nothing — so it
+	// runs to the end of the file and takes every header below it with it. The
+	// block's own regex still finds it and it still runs; what breaks is
+	// execute:, whose body now holds a header line and a formula or a param
+	// list, parsed as JavaScript.
+	const executeBlock = parsed.blocks.find((b) => b.kind === "execute");
+	if (executeBlock) {
+		for (let i = 0; i < parsed.tokens.length; i++) {
+			const token = parsed.tokens[i]!;
+			if (token.start <= executeBlock.label.start) continue;
+			if (token.character !== 0) continue;
+			const label = blockLabelAt(parsed.tokens, i);
+			if (!label) continue;
+			// A second execute: cannot be moved above the first. findBlocks
+			// stops at the first one, so dsl/duplicate-block never sees this
+			// and the wording has to come from here.
+			add(
+				label.span,
+				label.kind === "execute"
+					? `"execute:" is declared more than once — the first one's body runs to the end of the file, so this header and everything under it are swallowed into it and parsed as JavaScript. Merge the two into one execute: block.`
+					: `"${label.kind}:" is below execute:, whose body runs to the end of the file — the header and everything under it are swallowed into the execute: script and parsed as JavaScript. Move it above execute:.`,
+				"error",
+				"dsl/block-after-execute",
+			);
+		}
+	}
+
+	const seenBlocks = new Set<string>();
+	for (let i = 0; i < parsed.blocks.length; i++) {
+		const block = parsed.blocks[i]!;
+		if (seenBlocks.has(block.kind)) {
+			add(
+				block.label,
+				`"${block.kind}:" is declared more than once — the compiler keeps one and silently drops the other.`,
+				"error",
+				"dsl/duplicate-block",
+			);
+			// No block's own lookahead lists itself, so the order rule below
+			// would read a duplicate as misplaced and tell the author to move
+			// it before itself.
+			continue;
+		}
+		seenBlocks.add(block.kind);
+
+		// Only the block immediately above can swallow this one: a block body
+		// ends at the first header its own lookahead lists, and the nearest
+		// header below it is this one. execute: is left to the rule above, which
+		// says the same thing about it in better words.
+		const prev = parsed.blocks[i - 1];
+		if (prev && prev.kind !== "execute" && !BLOCK_STOPS[prev.kind].has(block.kind)) {
+			add(
+				block.label,
+				`"${block.kind}:" must come before "${prev.kind}:" — the compiler reads ${prev.kind}: up to the next header it recognises, and ${block.kind}: is not one of them, so this header and its body end up inside the ${prev.kind}: body.`,
+				"error",
+				"dsl/block-order",
+			);
+		}
+	}
+
 	// ── record fields ────────────────────────────────────────────────
 	for (const ref of parsed.fieldRefs) {
 		// Neither block is rewritten by TransformLine, so brackets in them are
@@ -207,7 +301,8 @@ export function checkDsl(text: string, ctx: DslContext = {}): DslIssue[] {
 		if (call.name === "userId") {
 			add(
 				call.nameSpan,
-				"userId is a bare identifier — userId() is a compile error.",
+				"'userId' is a value, not a function — write userId without parentheses, or currentUserId(). " +
+					"The compiler's bare-identifier rewrite fires either way, so userId() reaches Jint as a call against a number.",
 				"error",
 				"dsl/user-id-call",
 			);
@@ -220,7 +315,9 @@ export function checkDsl(text: string, ctx: DslContext = {}): DslIssue[] {
 		if (!arg) continue;
 
 		// A hyphenated module code can't be schema-qualified, so the rule is
-		// skipped there rather than reported as unfixable.
+		// skipped there rather than reported as unfixable. Neither can a code
+		// half of which is spliced in at run time be read here.
+		if (arg.interpolated) continue;
 		if (arg.value.includes(".") || ctx.moduleCode?.includes("-")) continue;
 		add(
 			arg.span,
@@ -263,17 +360,17 @@ export function checkDsl(text: string, ctx: DslContext = {}): DslIssue[] {
 		}
 
 		if (depth === 0 && token.character > 0) {
-			const kind = blockLabelAt(parsed.tokens, i);
+			const label = blockLabelAt(parsed.tokens, i);
 			// `execute: number` inside params: declares a param called execute.
 			// RxParamDecl takes any `\w+`, so a block name is a legal param
 			// name — and a declaration the parser already read is not a header.
 			const isParamDecl = parsed.params.some(
 				(p) => p.nameSpan.start === token.start,
 			);
-			if (kind && !isParamDecl) {
+			if (label && !isParamDecl) {
 				add(
-					{ start: token.start, end: parsed.tokens[i + 1]!.end },
-					`Block headers start at column 0. Indented, "${kind}:" is body text — the compiler never opens the block, and it runs as if empty.`,
+					label.span,
+					`Block headers start at column 0. Indented, "${label.kind}:" is body text — the compiler never opens the block, and it runs as if empty.`,
 					"error",
 					"dsl/indented-block-header",
 				);
@@ -299,6 +396,182 @@ export function checkDsl(text: string, ctx: DslContext = {}): DslIssue[] {
 		);
 	}
 
+	// ── formula-only functions in a JavaScript block ─────────────────
+	// execute: and onBeforeStart: compile to a bare script and run on Jint;
+	// the rest of the DSL is the formula engine. Install rejects these with
+	// "'TODAY' is not defined".
+	for (const call of parsed.calls) {
+		const replacement = FORMULA_ONLY.get(call.name);
+		if (!replacement) continue;
+		if (call.block !== "execute" && call.block !== "onBeforeStart") continue;
+		add(
+			call.nameSpan,
+			`${call.name}() is formula-only — in ${call.block}: it is undefined and install fails with "'${call.name}' is not defined". Write ${replacement}.`,
+			"error",
+			"dsl/formula-only-function",
+		);
+	}
+
+	// Token position by start offset — the two rules below both need to read
+	// what sits next to a call, and a scan per call is a scan of the file.
+	const tokenAt = new Map(parsed.tokens.map((t, i) => [t.start, i]));
+
+	// ── SQL placeholders are @name, not :name ────────────────────────
+	for (const call of parsed.calls) {
+		if (call.name !== "query" && call.name !== "callProc") continue;
+		const arg = call.firstStringArg;
+		if (!arg) continue; // a variable or a built string — nothing to read
+
+		// `::text` is a Postgres cast and `a:b` inside a literal is not a
+		// placeholder either, so require a non-word, non-colon character before.
+		// Quoted data and comments are not SQL to bind against at all —
+		// `select ':draft' as status` names no placeholder.
+		//
+		// The leading character is captured rather than looked behind: lookbehind
+		// is ES2018, and an unsupported one is a SyntaxError for the whole module
+		// at parse time, not a failure of this rule.
+		const bad = /(^|[^:\w]):([a-z][a-z0-9_]*)/i.exec(stripSqlNoise(arg.value));
+		if (bad) {
+			const name = bad[2];
+			add(
+				arg.span,
+				`SQL binds @name, not :name — rewrite ':${name}' as '@${name}' and pass { ${name}: value } as the params argument.`,
+				"error",
+				"dsl/sql-placeholder",
+			);
+		}
+
+		// A `${…}` hole is the splice itself; a `+` after the literal is the
+		// same splice written the other way.
+		if (arg.interpolated || parsed.tokens[arg.endIndex + 1]?.text === "+") {
+			const built = arg.interpolated ? "${…} interpolation" : "concatenation";
+			add(
+				arg.span,
+				// callProc's first argument is the procedure name, and an
+				// identifier cannot be bound — the @placeholder advice cannot
+				// be followed there.
+				call.name === "callProc"
+					? `Procedure name built by ${built} — a name is an identifier, so it cannot be bound as a @placeholder. Choose between fixed names in the script rather than splicing a value into one.`
+					: `SQL built by ${built} — pass @placeholders and a params object instead, so values are bound rather than spliced into the statement.`,
+				"warning",
+				"dsl/sql-concat",
+			);
+		}
+	}
+
+	// ── unknown host functions ───────────────────────────────────────
+	// A warning, not an error: the catalog tracks the host's built-ins by hand,
+	// so a name missing from it is more likely our gap than the author's typo.
+	//
+	// JavaScript blocks only. The catalog is Jint's host surface; canExecute:
+	// is the formula engine, with a vocabulary of its own — and its infix
+	// operators bring parentheses with them, so `… AND (x OR y)` reads as a
+	// call to AND here and is no such thing.
+	//
+	// Declarations are block-scoped because the compiler is: execute: and
+	// onBeforeStart: are compiled to separate scripts and each gets its own
+	// `CheckUndefinedReferences` pass, so a helper declared in one is not
+	// defined in the other. A declaration above the first header belongs to no
+	// block and is left visible to both — nothing legal can sit there.
+	// Every block it is declared in, not the last one: a helper both blocks need
+	// has to be written out in both, which is the shape this scoping produces.
+	const declaredFunctions = new Map<string, Set<BlockKind | null>>();
+	for (let i = 0; i < parsed.tokens.length; i++) {
+		const token = parsed.tokens[i]!;
+		if (token.text !== "function") continue;
+		const name = parsed.tokens[i + 1];
+		if (name?.kind !== "ident") continue;
+		const blocks = declaredFunctions.get(name.text) ?? new Set();
+		blocks.add(blockOf(parsed, token.start));
+		declaredFunctions.set(name.text, blocks);
+	}
+	const isDeclaredIn = (name: string, block: BlockKind | null) => {
+		const blocks = declaredFunctions.get(name);
+		return blocks !== undefined && (blocks.has(null) || blocks.has(block));
+	};
+	// `parsed.calls` is every `name(` in the body, so a function's own
+	// declaration head looks like a call to it: `function f(x)` and the method
+	// shorthand `f(x) { … }` alike. Neither is an invocation of anything.
+	const reportedUnknown = new Set<string>();
+	for (const call of parsed.calls) {
+		if (call.block !== "execute" && call.block !== "onBeforeStart") continue;
+		const name = call.name;
+		const idx = tokenAt.get(call.nameSpan.start);
+		if (idx !== undefined) {
+			// `new Foo()` names a constructor, not a host function — the
+			// catalog never held one and has nothing to say about it.
+			const prev = parsed.tokens[idx - 1]?.text;
+			if (prev === "function" || prev === "new") continue;
+			if (isMethodName(parsed.tokens, idx)) continue;
+		}
+		if (
+			BUILTIN_BY_NAME.has(name) ||
+			CONTROL_KEYWORDS.has(name) ||
+			KEYWORDS_BEFORE_PAREN.has(name) ||
+			JS_GLOBALS.has(name) ||
+			FORMULA_ONLY.has(name) ||
+			// Its own rule reports this one, with better wording.
+			name === "userId" ||
+			isDeclaredIn(name, call.block) ||
+			parsed.locals.has(name) ||
+			reportedUnknown.has(name)
+		) {
+			continue;
+		}
+		reportedUnknown.add(name);
+		add(
+			call.nameSpan,
+			`"${name}()" is not a DSL host function, and nothing in this script declares it. Check it against the built-in catalog.`,
+			"warning",
+			"dsl/unknown-builtin",
+		);
+	}
+
+	// ── a job's action has no current record ─────────────────────────
+	if (ctx.action?.viaJob) {
+		// `JobRegistrar.RequiresRecordContext` reads the compiled script for
+		// three markers, not one: `__r.` from `[field]`, `__old.` from the
+		// trigger-only `old[field]`, and `__records.` from the batch record set.
+		// All three are rejected, so all three are reported.
+		const inScript = (block: BlockKind | null) =>
+			block === "execute" || block === "onBeforeStart";
+		const bound: Array<{ span: Span; read: string }> = [];
+
+		// Same disambiguation the column rule makes, on the same terms: `[id]`
+		// is an array literal when the script binds `id`, and `[true]` is one
+		// in batch execute:, where no `[field]` rewrite runs to claim it.
+		for (const ref of parsed.fieldRefs) {
+			if (!inScript(ref.block)) continue;
+			if (isBatch && ref.block === "execute" && LITERAL_NAMES.has(ref.name))
+				continue;
+			if (ref.isCurrentRecord && parsed.locals.has(ref.name)) continue;
+			bound.push({ span: ref.outerSpan, read: `[${ref.name}]` });
+		}
+		for (const ref of parsed.globalRefs) {
+			if (ref.global !== "old" || !inScript(ref.block)) continue;
+			bound.push({ span: ref.span, read: `old[${ref.property}]` });
+		}
+		// Shadowed exactly as the execution-mode rule reads it: a script that
+		// binds its own `records` is not touching the batch global — and
+		// `var records = select(…)` is the very refactor this rule asks for.
+		if (!parsed.locals.has("records")) {
+			for (const span of parsed.recordsRefs) {
+				if (!inScript(blockOf(parsed, span.start))) continue;
+				bound.push({ span, read: "records" });
+			}
+		}
+
+		const first = bound.sort((a, b) => a.span.start - b.span.start)[0];
+		if (first) {
+			add(
+				first.span,
+				`Action "${ctx.action.code}" is invoked by a scheduled job, which runs as the system user with no record bound — ${first.read} has nothing to read. Fetch rows with select() or query() instead.`,
+				"error",
+				"dsl/job-record-context",
+			);
+		}
+	}
+
 	out.push(...inlineAssignmentIssues(parsed, positionAt));
 	return out;
 }
@@ -362,6 +635,55 @@ function opensFunctionBody(
 	return head?.kind === "ident" && !CONTROL_KEYWORDS.has(head.text);
 }
 
+/**
+ * The headers each block's regex in `ParseBlocks` stops at — its body runs to
+ * the first of these below it, or to the end of the file.
+ *
+ * The sets are not the same, and none of them is "every other block": a block
+ * followed by one its own set omits swallows that block's text. `schema:`, the
+ * only one every other set lists, may therefore sit anywhere before `execute:`.
+ */
+const BLOCK_STOPS: Record<BlockKind, ReadonlySet<BlockKind>> = {
+	params: new Set(["schema", "canExecute", "onBeforeStart", "execute"]),
+	canExecute: new Set(["schema", "onBeforeStart", "execute"]),
+	schema: new Set(["params", "canExecute", "onBeforeStart", "execute"]),
+	onBeforeStart: new Set(["schema", "execute"]),
+	execute: new Set(),
+};
+
+/**
+ * Formula-engine functions that are undefined in a JavaScript block, mapped to
+ * the spelling that works there.
+ *
+ * A Map, not an object: the key is a name read out of the script, and on an
+ * object `toString` and `constructor` would answer from the prototype — a
+ * declared `function toString()` would be reported as formula-only, with the
+ * native function's source offered as the replacement.
+ */
+const FORMULA_ONLY = new Map<string, string>([
+	["TODAY", "now()"],
+	["NOW", "now()"],
+	["CURRENT_USER_ID", "currentUserId()"],
+]);
+
+/**
+ * Keywords a `(` may legally follow. `parsed.calls` is every `name(` in the
+ * body, so these arrive looking like calls — `return (x)`, `typeof (v)` and
+ * `for (x of (xs))` included — and are not calls to anything.
+ */
+const KEYWORDS_BEFORE_PAREN = new Set([
+	"function", "return", "typeof", "instanceof", "new", "delete", "void",
+	"in", "of", "do", "else", "try", "throw", "yield", "await",
+]);
+
+/** Globals Jint exposes. Real calls, and none of them ours to report. */
+const JS_GLOBALS = new Set([
+	"parseInt", "parseFloat", "isNaN", "isFinite", "encodeURI", "decodeURI",
+	"encodeURIComponent", "decodeURIComponent", "String", "Number", "Boolean",
+	"Array", "Object", "Date", "Math", "JSON", "RegExp", "Error", "Set", "Map",
+	"WeakSet", "WeakMap", "Promise", "Symbol", "BigInt",
+]);
+
 /**
  * Keyword literals, which `[…]` can only be holding as array elements. Both
  * spellings: the DSL takes SQL-style `NULL`/`TRUE`/`FALSE` as well as the
@@ -376,6 +698,68 @@ const LITERAL_NAMES = new Set([
 	"NULL",
 ]);
 
+/**
+ * SQL with its string literals and comments blanked out, so a scan for
+ * placeholders reads only the statement. Same length in, same length out.
+ *
+ * Quotes double to escape themselves in SQL (`'it''s'`), which is why this
+ * cannot be a regex the way the JavaScript lexer's strings can.
+ */
+function stripSqlNoise(sql: string): string {
+	let out = "";
+	let i = 0;
+	while (i < sql.length) {
+		const c = sql[i]!;
+
+		if (c === "'" || c === '"') {
+			const quote = c;
+			out += " ";
+			i++;
+			while (i < sql.length) {
+				if (sql[i] === quote && sql[i + 1] === quote) {
+					out += "  ";
+					i += 2;
+					continue;
+				}
+				if (sql[i] === quote) break;
+				out += sql[i] === "\n" ? "\n" : " ";
+				i++;
+			}
+			if (i < sql.length) {
+				out += " ";
+				i++;
+			}
+			continue;
+		}
+
+		if (c === "-" && sql[i + 1] === "-") {
+			while (i < sql.length && sql[i] !== "\n") {
+				out += " ";
+				i++;
+			}
+			continue;
+		}
+
+		if (c === "/" && sql[i + 1] === "*") {
+			out += "  ";
+			i += 2;
+			while (i < sql.length && !(sql[i] === "*" && sql[i + 1] === "/")) {
+				out += sql[i] === "\n" ? "\n" : " ";
+				i++;
+			}
+			if (i < sql.length) {
+				out += "  ";
+				i += 2;
+			}
+			continue;
+		}
+
+		out += c;
+		i++;
+	}
+	return out;
+}
+
 function blockOf(parsed: DslDocument, offset: number) {
 	return (
 		parsed.blocks.find((b) => offset >= b.body.start && offset < b.body.end)

package/src/dsl/index.ts

@@ -8,7 +8,7 @@
 // Consumers: the language server (diagnostics, completion, hover,
 // go-to-definition) and the module validator that runs before a pack.
 
-export { tokenize, stringValue } from "./lexer";
+export { tokenize, stringValue, templateChunkValue } from "./lexer";
 export type { Token, TokenKind } from "./lexer";
 
 export { parseDsl, BLOCK_KINDS } from "./parse";
@@ -21,6 +21,7 @@ export type {
 	FieldRef,
 	GlobalRef,
 	Span,
+	StringArg,
 } from "./parse";
 
 export { BUILTINS, BUILTIN_BY_NAME, BUILTIN_VALUES } from "./builtins";

package/src/dsl/lexer.ts

@@ -360,5 +360,35 @@ function scanRegex(text: string, start: number): number {
 export function stringValue(token: Token): string {
 	if (token.kind !== "string") return token.text;
 	const body = token.text.slice(1, token.text.endsWith(token.text[0]!) && token.text.length > 1 ? -1 : undefined);
-	return body.replace(/\\(.)/g, "$1");
+	return unescape(body);
+}
+
+/**
+ * The literal text of one template chunk, delimiters removed. A chunk opens on
+ * a backtick or on the `}` that closed the hole before it, and closes on a
+ * backtick, on the `${` of the next hole, or on the end of the file.
+ */
+export function templateChunkValue(token: Token): string {
+	if (token.kind !== "template") return token.text;
+	const body = token.text.slice(1);
+	if (body.endsWith("${")) return unescape(body.slice(0, -2));
+	if (body.endsWith("`")) return unescape(body.slice(0, -1));
+	return unescape(body);
+}
+
+// A switch, not a lookup table: the escaped character comes out of the script,
+// and an object would answer `\c` from Object.prototype.
+function unescape(body: string): string {
+	return body.replace(/\\(.)/g, (_, ch: string) => {
+		switch (ch) {
+			case "n":
+				return "\n";
+			case "t":
+				return "\t";
+			case "r":
+				return "\r";
+			default:
+				return ch;
+		}
+	});
 }

package/src/dsl/parse.ts

@@ -2,23 +2,30 @@
 // reads, ref navigation chains and built-in calls — everything the diagnostics,
 // completion, hover and definition features need, and nothing else.
 
-import { CONTROL_KEYWORDS, type Token, tokenize, stringValue } from "./lexer";
+import {
+	CONTROL_KEYWORDS,
+	type Token,
+	stringValue,
+	templateChunkValue,
+	tokenize,
+} from "./lexer";
 
-export type BlockKind =
-	| "params"
-	| "canExecute"
-	| "schema"
-	| "onBeforeStart"
-	| "execute";
-
-/** In the order `ActionDslCompiler.ParseBlocks` expects them in a file. */
-export const BLOCK_KINDS: BlockKind[] = [
+/**
+ * In the order `ActionDslCompiler.ParseBlocks` expects them in a file.
+ *
+ * `BlockKind` derives from this array rather than standing beside it, so the
+ * two cannot drift: the order check ranks a kind by its index here, and a kind
+ * the array does not list could not have been produced in the first place.
+ */
+export const BLOCK_KINDS = [
 	"params",
 	"canExecute",
 	"schema",
 	"onBeforeStart",
 	"execute",
-];
+] as const;
+
+export type BlockKind = (typeof BLOCK_KINDS)[number];
 
 const BLOCK_BY_LOWER = new Map(BLOCK_KINDS.map((k) => [k.toLowerCase(), k]));
 
@@ -88,11 +95,23 @@ export interface GlobalRef {
 export interface CallRef {
 	name: string;
 	nameSpan: Span;
-	/** First argument when it is a string literal — the entity code, usually. */
-	firstStringArg?: { value: string; span: Span };
+	/** First argument when it is a string or template literal — the entity code, usually. */
+	firstStringArg?: StringArg;
 	block: BlockKind | null;
 }
 
+export interface StringArg {
+	value: string;
+	span: Span;
+	/**
+	 * A template literal with `${…}` holes, which `value` holds a space in
+	 * place of: literal text to read, but not a constant.
+	 */
+	interpolated: boolean;
+	/** Index of the last token the literal consumes — its final chunk. */
+	endIndex: number;
+}
+
 export interface DslDocument {
 	blocks: DslBlock[];
 	params: DslParam[];
@@ -237,7 +256,11 @@ export function parseDsl(text: string): DslDocument {
 				call.firstStringArg = {
 					value: stringValue(firstArg),
 					span: { start: firstArg.start, end: firstArg.end },
+					interpolated: false,
+					endIndex: i + 2,
 				};
+			} else if (firstArg?.kind === "template" && firstArg.text.startsWith("`")) {
+				call.firstStringArg = templateArg(tokens, i + 2);
 			}
 			calls.push(call);
 		}
@@ -275,6 +298,53 @@ function isFieldAccessStart(text: string, start: number): boolean {
 	return start === 0 || !/\w/.test(text[start - 1]!);
 }
 
+/**
+ * A template literal, read back from the chunks the lexer split it into. The
+ * walk has to count nested templates, because one opened inside a `${…}` hole
+ * emits chunks of its own between ours.
+ *
+ * Each hole becomes a single space. The callers read the text as SQL, and a
+ * spliced value is not part of the statement they are reading — but the gap
+ * has to stay a gap, or the words either side of it would run together.
+ */
+function templateArg(tokens: Token[], start: number): StringArg {
+	const parts: string[] = [];
+	let depth = 0;
+	let interpolated = false;
+	let last = tokens[start]!;
+	let endIndex = start;
+
+	for (let j = start; j < tokens.length; j++) {
+		const t = tokens[j]!;
+		if (t.kind !== "template") continue;
+
+		const opens = t.text.startsWith("`");
+		if (opens) depth++;
+		if (depth === 1) {
+			if (!opens) parts.push(" ");
+			parts.push(templateChunkValue(t));
+			last = t;
+			endIndex = j;
+		}
+		if (t.text.endsWith("${")) {
+			if (depth === 1) interpolated = true;
+			continue;
+		}
+		// Anything else ends the template: a closing backtick, or the end of
+		// the file on an unterminated one.
+		depth--;
+		if (depth === 0) break;
+	}
+
+	return {
+		value: parts.join(""),
+		span: { start: tokens[start]!.start, end: last.end },
+		interpolated,
+		endIndex,
+	};
+}
+
+
 /**
  * The `[field]` half of a `records[n][field]` read starting at `i`, or null.
  *
@@ -533,13 +603,17 @@ function collectPattern(tokens: Token[], start: number, locals: Set<string>): nu
  * that reports an indented header — body text as far as the compiler is
  * concerned, leaving the block it meant to open empty.
  */
-export function blockLabelAt(tokens: Token[], i: number): BlockKind | null {
+export function blockLabelAt(
+	tokens: Token[],
+	i: number,
+): { kind: BlockKind; span: Span } | null {
 	const t = tokens[i];
 	if (!t || t.kind !== "ident" || !t.startsLine) return null;
 	const colon = tokens[i + 1];
 	// `params :` does not match `^params:` either.
 	if (colon?.text !== ":" || colon.start !== t.end) return null;
-	return BLOCK_BY_LOWER.get(t.text.toLowerCase()) ?? null;
+	const kind = BLOCK_BY_LOWER.get(t.text.toLowerCase());
+	return kind ? { kind, span: { start: t.start, end: colon.end } } : null;
 }
 
 function findBlocks(text: string, tokens: Token[]): DslBlock[] {
@@ -549,12 +623,12 @@ function findBlocks(text: string, tokens: Token[]): DslBlock[] {
 		// Column 0, like the compiler's `^`-anchored headers: an indented
 		// `params:` is an object key inside a block body, not a new block.
 		if (t.character !== 0) continue;
-		const kind = blockLabelAt(tokens, i);
-		if (!kind) continue;
-		labels.push({ kind, span: { start: t.start, end: tokens[i + 1]!.end } });
+		const label = blockLabelAt(tokens, i);
+		if (!label) continue;
+		labels.push(label);
 		// `execute:` is `(.*?)\z` — it runs to end-of-file, so a later header
 		// is body text.
-		if (kind === "execute") break;
+		if (label.kind === "execute") break;
 	}
 
 	return labels.map((l, idx) => ({