@dforge-core/metadata 0.0.22 → 0.0.24

package/src/dsl/check.ts

@@ -0,0 +1,813 @@
+// Static checks for an action DSL body (`logic/actions/*.dsl`).
+//
+// Every rule here mirrors something the platform only tells you at pack or
+// install time — a slow, tenant-bound round trip. The point is to move that
+// feedback to where the script is written, and to the validator that runs
+// before a pack, from one implementation rather than two.
+//
+// The rules that need to know about the module take it through `DslContext`,
+// which is small on purpose: a module code, the action, and the columns of the
+// entity behind the record context. Anything a host can't resolve it simply
+// omits, and the rules that depend on it stand down. See ./types.
+
+import { BUILTIN_BY_NAME } from "./builtins";
+import { CONTROL_KEYWORDS, type Token } from "./lexer";
+import {
+	type BlockKind,
+	type DslDocument,
+	type Span,
+	blockLabelAt,
+	parseDsl,
+} from "./parse";
+import type { ColumnLookup, DslContext, DslIssue, DslSeverity } from "./types";
+
+/**
+ * Check a DSL body. Returns [] for a clean script.
+ *
+ * Issues come back in source-feature order (field reads, params, execution
+ * mode, block spelling, built-ins, top-level returns, inline assignments)
+ * rather than sorted by position — a host that wants them in file order can
+ * sort on `start`.
+ */
+export function checkDsl(text: string, ctx: DslContext = {}): DslIssue[] {
+	const parsed = parseDsl(text);
+	const out: DslIssue[] = [];
+	const positionAt = lineIndexer(text);
+
+	const add = (
+		span: Span,
+		message: string,
+		severity: DslSeverity,
+		rule: string,
+	) => {
+		const { line, column } = positionAt(span.start);
+		out.push({
+			rule,
+			severity,
+			message,
+			start: span.start,
+			end: span.end,
+			line,
+			column,
+		});
+	};
+
+	const action = ctx.action;
+	const entity = ctx.currentEntity ?? null;
+	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
+		// data rather than field reads: `schema:` is embedded as a JS object
+		// literal, and `params:` is read by RxParamDecl — whose trailing
+		// key=value pairs take a bracketed option list, `options=[cash]`.
+		if (ref.block === "schema" || ref.block === "params") continue;
+
+		// Single-hop is the DSL's own rewrite (`RxRefNav`), so the rule belongs
+		// to the blocks that go through it. canExecute: reaches the formula
+		// engine verbatim, and a formula walks a chain of any depth —
+		// `[vehicle].[depot].[city_name]` resolves there and is tested.
+		const isDslBlock = ref.block === "execute" || ref.block === "onBeforeStart";
+		// The compiler rewrites the first hop and then fails on a surviving
+		// `.[` — so it is the bracket, not the hop count, that marks a second
+		// reference. `[vehicle].plate.length` compiles to
+		// `__ref_vehicle.get('plate').length`: one hop, then JavaScript.
+		const secondRef = ref.navigation.findIndex((h, idx) => idx > 0 && h.bracketed);
+		if (isDslBlock && secondRef > 0) {
+			const first = ref.navigation[secondRef]!;
+			const last = ref.navigation[ref.navigation.length - 1]!;
+			add(
+				{ start: first.span.start, end: last.span.end },
+				`Ref navigation is single-hop in the DSL. Use getRecord() or select() to reach past "${ref.navigation[0]!.name}".`,
+				"error",
+				"dsl/multi-hop-nav",
+			);
+		}
+
+		// Batch execute: applies no `[field]` rewrite at all, so `[true]` stays
+		// the literal it is — and a keyword is never a column name anyway.
+		if (isBatch && ref.block === "execute" && LITERAL_NAMES.has(ref.name))
+			continue;
+
+		if (!entity) continue;
+		if (entity.columns.size === 0) continue;
+		if (hasColumn(ref.name)) continue;
+		// `var ids = [orderId]` is an array literal, not a field read. Only the
+		// name tells the two apart, so a name bound in this script stands down —
+		// the same fail-open the entity checks above use.
+		//
+		// Only the bare bracket is ambiguous. `r[stauts]` and
+		// `records[0][stauts]` name a column outright — the compiler rewrites
+		// each to `.get('stauts')` with the literal name — so a same-named
+		// local says nothing about them.
+		if (ref.isCurrentRecord && parsed.locals.has(ref.name)) continue;
+
+		add(
+			ref.span,
+			`"${ref.name}" is not a column on ${entity.qualified}. [field] names are checked at pack time — this is a compile error, not an empty read.`,
+			"error",
+			"dsl/unknown-column",
+		);
+	}
+
+	// `old[field]` names columns of the same entity — RxOldAccess feeds them
+	// into the very same check — so a typo there is a compile error too.
+	if (entity && entity.columns.size > 0) {
+		for (const ref of parsed.globalRefs) {
+			if (ref.global !== "old") continue;
+			if (ref.block !== "execute" && ref.block !== "onBeforeStart") continue;
+			if (hasColumn(ref.property)) continue;
+			add(
+				ref.span,
+				`"${ref.property}" is not a column on ${entity.qualified}. old[field] reads the pre-change value of a column, and the name is checked at pack time.`,
+				"error",
+				"dsl/unknown-column",
+			);
+		}
+	}
+
+	// ── params ───────────────────────────────────────────────────────
+	// `ValidateParamUsages` compares with OrdinalIgnoreCase, so `params[Qty]`
+	// against a declared `qty` compiles — flagging it would be a false error.
+	const declared = new Set(parsed.params.map((p) => p.name.toLowerCase()));
+	const hasParamsBlock = parsed.blocks.some((b) => b.kind === "params");
+	for (const ref of parsed.globalRefs) {
+		if (ref.global !== "params") continue;
+		if (!hasParamsBlock || declared.has(ref.property.toLowerCase())) continue;
+		add(
+			ref.span,
+			`"${ref.property}" is not declared in the params: block.`,
+			"error",
+			"dsl/unknown-param",
+		);
+	}
+
+	// ── execution mode ───────────────────────────────────────────────
+	if (action) {
+		const mode = action.executionMode ?? "single";
+		// `recordsRefs` covers both `records[x]` and the bare `for x in records`,
+		// and comes from the lexer, so the word inside a string or a comment
+		// does not count — nor does a script that binds its own `records`,
+		// which shadows the batch global and says nothing about the mode.
+		const recordsSpan = parsed.locals.has("records")
+			? undefined
+			: parsed.recordsRefs[0];
+		// execute: alone. `onBeforeStart:` is compiled by CompilePerRecordBlock
+		// whatever the mode — "always per-record (no batch form)" — so a bare
+		// field is exactly how it is meant to be written there.
+		//
+		// Batch mode never applies the `[field]` rewrite at all, which is why
+		// `var ids = [id]` survives as the array literal it looks like. Same
+		// disambiguation as the column rule: a name bound in this script is a
+		// local, not a column.
+		const bareFields = parsed.fieldRefs.filter(
+			(r) =>
+				r.block === "execute" &&
+				r.isCurrentRecord &&
+				!parsed.locals.has(r.name) &&
+				!LITERAL_NAMES.has(r.name),
+		);
+
+		if (mode === "batch") {
+			// Every one of them: an editor underlines what it is told to, and
+			// reporting only the first hides the rest behind a re-check.
+			for (const field of bareFields) {
+				add(
+					field.outerSpan,
+					`Action "${action.code}" runs in batch mode, which has no current record. Iterate instead: for x in records { x[${field.name}] }.`,
+					"error",
+					"dsl/batch-bare-field",
+				);
+			}
+		}
+		if (mode !== "batch" && recordsSpan) {
+			add(
+				recordsSpan,
+				`"records" only exists in batch mode; action "${action.code}" runs in "${mode}" mode.`,
+				"warning",
+				"dsl/records-outside-batch",
+			);
+		}
+	}
+
+	// ── block-specific spelling ──────────────────────────────────────
+	// canExecute is parsed by the formula engine, execute by the JavaScript
+	// compiler. They share more vocabulary than the docs suggest — NULL and
+	// lowercase booleans work in both, and shipped modules rely on that — so
+	// only the operators that genuinely have no formula spelling are flagged.
+	for (const token of parsed.tokens) {
+		if (blockOf(parsed, token.start) !== "canExecute") continue;
+		if (token.text !== "&&" && token.text !== "||") continue;
+		add(
+			{ start: token.start, end: token.end },
+			`canExecute is a formula, not JavaScript — write ${token.text === "&&" ? "AND" : "OR"}.`,
+			"warning",
+			"dsl/js-in-formula",
+		);
+	}
+
+	// ── built-in misuse ──────────────────────────────────────────────
+	for (const call of parsed.calls) {
+		if (call.name === "userId") {
+			add(
+				call.nameSpan,
+				"'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",
+			);
+			continue;
+		}
+
+		const builtin = BUILTIN_BY_NAME.get(call.name);
+		if (!builtin || builtin.entityArg === undefined) continue;
+		const arg = call.firstStringArg;
+		if (!arg) continue;
+
+		// A hyphenated module code can't be schema-qualified, so the rule is
+		// 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,
+			`Qualify the entity code as "${ctx.moduleCode ? `${ctx.moduleCode}.` : "<module>."}${arg.value}" — entity_cd is only unique per module, so a bare code can resolve to another module's entity.`,
+			"info",
+			"dsl/unqualified-entity",
+		);
+	}
+
+	// ── indented headers, and returns outside a function ─────────────
+	// An indented `params:` inside an object literal is an ordinary key, which
+	// is the whole reason the compiler anchors headers at column 0 rather than
+	// trusting the line — so that rule reads brace depth.
+	//
+	// `return` reads function scope instead. Both blocks compile to a bare
+	// script, and Esprima's ParseScript rejects a return outside a function
+	// wherever it sits: `if (x) { return }` and `if (x) return` fail exactly as
+	// a return on its own line does.
+	let depth = 0;
+	const functionDepths: number[] = [];
+	// Index of the `(` that the most recent `)` closed. Tracked with a stack
+	// because the nearest open paren is not the matching one: in `if (now()) {`
+	// it is `now`'s, and in `function f(x = (1)) {` it is the default value's.
+	const parenStack: number[] = [];
+	let matchingParenOpen = -1;
+	for (let i = 0; i < parsed.tokens.length; i++) {
+		const token = parsed.tokens[i]!;
+
+		if (token.text === "(") parenStack.push(i);
+		else if (token.text === ")") matchingParenOpen = parenStack.pop() ?? -1;
+
+		if (token.text === "{") {
+			depth++;
+			if (opensFunctionBody(parsed.tokens, i, matchingParenOpen))
+				functionDepths.push(depth);
+		} else if (token.text === "}") {
+			if (functionDepths[functionDepths.length - 1] === depth)
+				functionDepths.pop();
+			depth = Math.max(0, depth - 1);
+		}
+
+		if (depth === 0 && token.character > 0) {
+			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 (label && !isParamDecl) {
+				add(
+					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",
+				);
+			}
+		}
+
+		if (token.kind !== "ident" || token.text !== "return") continue;
+		// `return` is a reserved word, so it is a statement unless it is being
+		// used as a name: `result.return` reads a property, `{ return: 1 }`
+		// declares a key and `{ return() { … } }` declares a method. All three
+		// are legal JavaScript.
+		if (parsed.tokens[i - 1]?.text === ".") continue;
+		if (parsed.tokens[i + 1]?.text === ":") continue;
+		if (isMethodName(parsed.tokens, i)) continue;
+		if (functionDepths.length > 0) continue;
+		const block = blockOf(parsed, token.start);
+		if (block !== "execute" && block !== "onBeforeStart") continue;
+		add(
+			{ start: token.start, end: token.end },
+			`A return outside a function is a syntax error — ${block}: compiles to a bare script. Use exit(message, level) to stop early and keep the changes made so far.`,
+			"error",
+			"dsl/top-level-return",
+		);
+	}
+
+	// ── 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.
+	const declaredFunctions = new Set<string>();
+	for (let i = 0; i < parsed.tokens.length; i++) {
+		if (parsed.tokens[i]!.text !== "function") continue;
+		const name = parsed.tokens[i + 1];
+		if (name?.kind === "ident") declaredFunctions.add(name.text);
+	}
+	// `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" ||
+			declaredFunctions.has(name) ||
+			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}]` });
+		}
+		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;
+}
+
+/**
+ * Column matching is case-insensitive at the other end — `EntityColumnLookup`
+ * hands the compiler an OrdinalIgnoreCase set — but a host passes us whatever
+ * `Set` or `Map` it already holds, and a mixed-case column name is legal.
+ *
+ * So fold both sides: the names once per check when the lookup can enumerate
+ * them (`Set` and `Map` both can), and the reference on the way in. A lookup
+ * that can do neither falls back to trying the reference in lower case, which
+ * is all that is left to try.
+ */
+function columnMatcher(columns?: ColumnLookup): (name: string) => boolean {
+	if (!columns) return () => true;
+	if (typeof columns.keys !== "function")
+		return (name) => columns.has(name) || columns.has(name.toLowerCase());
+
+	const folded = new Set<string>();
+	for (const key of columns.keys()) folded.add(key.toLowerCase());
+	return (name) => folded.has(name.toLowerCase());
+}
+
+/**
+ * Whether the name at `i` heads a method shorthand — `return() { … }`, whose
+ * parameter list is followed by a body. `return (x + 1)` is a statement with a
+ * parenthesized expression and has no brace after the closing paren, so the
+ * two are told apart by what follows the parens rather than by what opens them.
+ */
+function isMethodName(tokens: Token[], i: number): boolean {
+	if (tokens[i + 1]?.text !== "(") return false;
+	let depth = 0;
+	for (let j = i + 1; j < tokens.length; j++) {
+		const text = tokens[j]!.text;
+		if (text === "(") depth++;
+		else if (text === ")") {
+			depth--;
+			if (depth === 0) return tokens[j + 1]?.text === "{";
+		}
+	}
+	return false;
+}
+
+/**
+ * Whether the `{` at `i` opens a function body — where a `return` is legal.
+ *
+ * `=> {` is one. So is `) {` when the name in front of the matching `(` is not
+ * a control keyword: that covers `function (x) {`, `function f(x) {` and the
+ * `f() {` method shorthand, while leaving `if (x) {` and `for (…) {` alone.
+ */
+function opensFunctionBody(
+	tokens: Token[],
+	i: number,
+	matchingParenOpen: number,
+): boolean {
+	const prev = tokens[i - 1];
+	if (prev?.text === "=>") return true;
+	if (prev?.text !== ")" || matchingParenOpen < 0) return false;
+	const head = tokens[matchingParenOpen - 1];
+	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
+ * JavaScript ones, and rewrites them to the latter.
+ */
+const LITERAL_NAMES = new Set([
+	"true",
+	"false",
+	"null",
+	"TRUE",
+	"FALSE",
+	"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)
+			?.kind ?? null
+	);
+}
+
+/**
+ * `if (…) { [field] = x }` on a single line mis-compiles — the assignment is
+ * rewritten in place and the setter call is lost. One assignment per line.
+ */
+function inlineAssignmentIssues(
+	parsed: DslDocument,
+	positionAt: (offset: number) => { line: number; column: number },
+): DslIssue[] {
+	const out: DslIssue[] = [];
+	for (const ref of parsed.fieldRefs) {
+		// `ref.endIndex` is where the parser stopped: a `.prop` hop is 2 tokens
+		// but a `.[prop]` hop is 4, so the count cannot be derived here.
+		const assign = parsed.tokens[ref.endIndex + 1];
+		if (!assign || assign.kind !== "punct" || assign.text !== "=") continue;
+
+		// Walk back over this line only, looking for a brace that opened here.
+		const line = parsed.tokens[ref.startIndex]!.line;
+		let openedHere = false;
+		for (let i = ref.startIndex - 1; i >= 0; i--) {
+			const t = parsed.tokens[i]!;
+			if (t.line !== line) break;
+			if (t.text === "{") {
+				openedHere = true;
+				break;
+			}
+		}
+		if (!openedHere) continue;
+
+		const pos = positionAt(ref.outerSpan.start);
+		out.push({
+			rule: "dsl/inline-assignment",
+			severity: "warning",
+			message:
+				"An assignment to a record field on the same line as the brace that opens its block mis-compiles. Put the assignment on its own line.",
+			start: ref.outerSpan.start,
+			end: ref.outerSpan.end,
+			line: pos.line,
+			column: pos.column,
+		});
+	}
+	return out;
+}
+
+/**
+ * Offset → 1-indexed line/column, over a line-start table built once per check.
+ * Scanning the prefix per issue is O(n) each, and a body with many issues is
+ * exactly the one where that shows.
+ */
+function lineIndexer(text: string): (offset: number) => { line: number; column: number } {
+	const starts = [0];
+	for (let i = 0; i < text.length; i++) {
+		if (text[i] === "\n") starts.push(i + 1);
+	}
+	return (offset: number) => {
+		// Binary search for the last line start at or before `offset`.
+		let lo = 0;
+		let hi = starts.length - 1;
+		while (lo < hi) {
+			const mid = (lo + hi + 1) >> 1;
+			if (starts[mid]! <= offset) lo = mid;
+			else hi = mid - 1;
+		}
+		return { line: lo + 1, column: offset - starts[lo]! + 1 };
+	};
+}