@dforge-core/metadata 0.0.20 → 0.0.23

package/src/dsl/builtins.ts

@@ -0,0 +1,210 @@
+// The DSL's platform globals. Signatures and prose track
+// dforge-mcp/skills/dforge-mcp-author/references/action-dsl.md — that file is
+// the source of truth; re-sync when it changes.
+
+export interface Builtin {
+	name: string;
+	signature: string;
+	returns: string;
+	doc: string;
+	/**
+	 * Index of the argument that names an entity, when the built-in takes one.
+	 * Drives entity-code completion and the qualify-your-codes diagnostic.
+	 */
+	entityArg?: number;
+}
+
+export const BUILTINS: Builtin[] = [
+	// Data operations
+	{
+		name: "insert",
+		signature: "insert(entity, fields)",
+		returns: "object",
+		entityArg: 0,
+		doc: "Insert a new record. Returns the full row including auto-filled columns (PK, audit, number sequences).",
+	},
+	{
+		name: "select",
+		signature: "select(entity, opts?)",
+		returns: "object[]",
+		entityArg: 0,
+		doc: "Structured multi-row read. `opts` = `{columns, filter, orderBy, limit, offset}`. Prefer over `query()` for row-shaped reads.",
+	},
+	{
+		name: "update",
+		signature: "update(entity, key, fields)",
+		returns: "number",
+		entityArg: 0,
+		doc: "Update the row(s) matched by `key`; returns rows affected. A value may be `{ inc: n }` to add to the column's current value — use that for every counter, balance and quantity.",
+	},
+	{
+		name: "delete",
+		signature: "delete(entity, key)",
+		returns: "number",
+		entityArg: 0,
+		doc: "Delete the row(s) matched by `key`; returns rows affected.",
+	},
+	{
+		name: "query",
+		signature: "query(sql, args?)",
+		returns: "object[]",
+		doc: "Execute parameterized SQL with `@argName` placeholders and schema-qualified table names. Escape hatch — prefer `select()` / `update()` / `delete()` when the structured shape fits.",
+	},
+	{
+		name: "getRecord",
+		signature: "getRecord(entity, key)",
+		returns: "object",
+		entityArg: 0,
+		doc: "Fetch a single record by key. **Throws** a localized not-found error when absent.",
+	},
+	{
+		name: "getRecordOrNull",
+		signature: "getRecordOrNull(entity, key)",
+		returns: "object | null",
+		entityArg: 0,
+		doc: "Like `getRecord`, but returns `null` instead of throwing — for an expected absence, guarded with `if (rec == null)`.",
+	},
+	{
+		name: "preloadRef",
+		signature: "preloadRef(fkColumn)",
+		returns: "object",
+		doc: "Load the referenced record for a FK column. Read its fields with `ref.get('field')`.",
+	},
+
+	// Messaging
+	{
+		name: "error",
+		signature: "error(message)",
+		returns: "never",
+		doc: "Abort the action and show an error. Rolls back all changes.",
+	},
+	{ name: "warn", signature: "warn(message)", returns: "void", doc: "Show a warning and continue." },
+	{
+		name: "info",
+		signature: "info(message)",
+		returns: "void",
+		doc: "Show an informational message — a receipt for work the action did, not a way to publish a computed value.",
+	},
+	{
+		name: "exit",
+		signature: "exit(message?, level?)",
+		returns: "never",
+		doc: "Stop the script early **without** error, keeping changes made so far. Level `'info'` (default) or `'warn'`. This is the DSL's early return — the block compiles to a bare script, so a `return` outside a function is a syntax error wherever it sits.",
+	},
+	{
+		name: "notify",
+		signature: "notify(userId, message)",
+		returns: "void",
+		doc: "Send an in-app notification to a specific user.",
+	},
+	{
+		name: "sendEmail",
+		signature: "sendEmail(to, subjectOrTemplate, dataOrBody?)",
+		returns: "void",
+		doc: "Queue an outbound email. Three arguments, and the **second** picks the mode: `sendEmail(to, 'order.shipped', { ref: [code] })` sends a template, `sendEmail(to, 'Your order shipped', '<p>…</p>')` sends raw HTML. A second argument with no spaces that contains `.` or `_` is read as a template code — so a raw subject like `'Shipped.'` silently becomes one; give a raw subject spaces. There is no fourth argument.",
+	},
+
+	// External calls
+	{
+		name: "callApi",
+		signature: "callApi(url, method, headers?, body?)",
+		returns: "string",
+		doc: "HTTP request to an external API; returns the body as a string. Max 10 calls per script, 120s timeout, 5MB response.",
+	},
+	{
+		name: "callService",
+		signature: "callService(name, args)",
+		returns: "any",
+		doc: "Invoke a registered host service.",
+	},
+	{
+		name: "callProc",
+		signature: "callProc(procName, args)",
+		returns: "any",
+		doc: "Call a stored procedure with named parameters.",
+	},
+
+	// Files, settings, extraction
+	{
+		name: "getFileBase64",
+		signature: "getFileBase64(fileField)",
+		returns: "string",
+		doc: "Read a file from storage as base64. Use with `callApi()` to send files to external APIs. Max 10 MB.",
+	},
+	{
+		name: "getFileUrl",
+		signature: "getFileUrl(fileField)",
+		returns: "string",
+		doc: "Temporary signed download URL (relative path) for a file field — for emails and notifications, not for `callApi()`.",
+	},
+	{ name: "getFileInfo", signature: "getFileInfo(fileField)", returns: "object | null", doc: "File metadata for a file field." },
+	{
+		name: "download",
+		signature: "download(url, fileName?)",
+		returns: "void",
+		doc: "Set a download URL on the action result; the browser opens it when the action returns. It fetches nothing and stores nothing — the URL must already serve the bytes, e.g. the `/api/temp-file/{token}` a service handed back. To put a remote file INTO storage, fetch it with `callApi()` and write it to a file column.",
+	},
+	{
+		name: "getSetting",
+		signature: "getSetting(settingCd)",
+		returns: "any",
+		doc: "Read a module setting, resolved through the folder chain (current folder → parents → module default).",
+	},
+	{
+		name: "getSecret",
+		signature: "getSecret(secretCd)",
+		returns: "string",
+		doc: "Retrieve a decrypted secret (API key, token). Managed in the admin UI.",
+	},
+	{
+		name: "ocrExtract",
+		signature: "ocrExtract(fileField, endpointBaseUrl, schema?, opts?)",
+		returns: "string (v1) | object (v2)",
+		doc: "Run OCR extraction against a document. **The return type follows the mode, and only `opts.mode` selects it** — a third argument alone never does. Without `opts.mode` (v1) the third argument is forwarded as `hints` and the result is the raw bundle as a JSON **string**: `JSON.parse()` it, or every property read is `undefined`. With `{ mode: 'extract' }` the third argument is a schema object and the result is already parsed — `{ fields, confidence?, unmatched, raw_text, meta }`. `{ mode: 'summary' }` needs no schema and returns `{ summary, raw_text, meta }` parsed. `{ profile: 'module_cd.profile_cd' }` uses a registered extraction profile, implies mode `extract`, and cannot be combined with an inline schema. The OCR host must be on `Dsl:Limits:AllowedHosts`.",
+	},
+	{
+		name: "detectDocument",
+		signature: "detectDocument(rawText)",
+		returns: "object | null",
+		doc: "Score text against reachable extraction profiles; returns the best match `{ profile, docType, score }` or `null`.",
+	},
+	{
+		name: "applyProfile",
+		signature: "applyProfile(json, profile)",
+		returns: "object",
+		doc: "Map already-extracted JSON to target fields and return the mapped object — it never writes, so the `insert()` / `update()` stays yours. `json` is the parsed extractor output (`JSON.parse(ocrExtract(...))`). `profile` must be an **inline object**, `{ map: { target: { from, transform?, pick? } }, lines?: { from, map, key? } }` — passing a profile code throws, as profile-by-code is a later slice. `from` is a path into the extraction; `transform` is one of `firstValid:<basis>`, `lookupRef:<entity.matchField>>returnField>`, `matchCatalog:<same>`, `parseMoney` or `parseDate`. Header targets come back at the top level and the 1:N block under its `key` (default `lines`); a missing source path omits the target. Not the same thing as `ocrExtract`'s registered `opts.profile` code.",
+	},
+
+	// Utilities
+	{ name: "now", signature: "now()", returns: "datetime", doc: "Current date/time. Lowercase — this is the execute-block date function." },
+	{ name: "addDays", signature: "addDays(date, n)", returns: "date", doc: "Add `n` days to a date." },
+	{ name: "addMinutes", signature: "addMinutes(date, n)", returns: "datetime", doc: "Add `n` minutes." },
+	{ name: "addSeconds", signature: "addSeconds(date, n)", returns: "datetime", doc: "Add `n` seconds." },
+	{ name: "currentUserId", signature: "currentUserId()", returns: "long", doc: "The acting user's tenant user ID." },
+	{ name: "flush", signature: "flush()", returns: "void", doc: "Flush pending writes so a following read sees them." },
+	{ name: "tryParseJson", signature: "tryParseJson(value)", returns: "any | null", doc: "Parse JSON, returning `null` on failure instead of throwing." },
+	{
+		name: "nextNumber",
+		signature: "nextNumber(entity)",
+		returns: "string",
+		entityArg: 0,
+		doc: "Generate the next value from a number sequence. Usually unnecessary — the platform auto-fills on `insert()`.",
+	},
+	{
+		name: "entityLink",
+		signature: "entityLink(entityCd, record, description?)",
+		returns: "link",
+		entityArg: 0,
+		doc: "Build a clickable link to a record, for an `entitylink` column. Always pass a **qualified** code — `entity_cd` is only unique per module.",
+	},
+];
+
+export const BUILTIN_BY_NAME = new Map(BUILTINS.map((b) => [b.name, b]));
+
+/** Bare identifiers the runtime injects — no parentheses. */
+export const BUILTIN_VALUES: Record<string, string> = {
+	userId: "The acting user's tenant user ID. A bare identifier — `userId()` is a compile error.",
+	records: "The selected records, in a `batch` action. Iterate with `for x in records { … }`.",
+	params: "Declared action parameters — read with `params[name]`.",
+	old: "Pre-change values, in a trigger-invoked action — read with `old[field]`. Read-only.",
+};

package/src/dsl/check.ts

@@ -0,0 +1,450 @@
+// 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 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);
+
+	// ── 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 bare identifier — userId() is a compile error.",
+				"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.
+		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 kind = 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) {
+				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.`,
+					"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",
+		);
+	}
+
+	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);
+}
+
+/**
+ * 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",
+]);
+
+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 };
+	};
+}