@dforge-core/metadata 0.0.22 → 0.0.23

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 };
+	};
+}

package/src/dsl/index.ts

@@ -0,0 +1,36 @@
+// @dforge-core/metadata/dsl — the action-DSL analyzer.
+//
+// A separate entry point, not part of the root barrel: this is a lexer, a
+// parser and a rule engine, while the root export is registries and types that
+// the web app and the VS Code webview pull into a browser bundle. Importing
+// `@dforge-core/metadata` must not drag a tokenizer in behind it.
+//
+// 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 type { Token, TokenKind } from "./lexer";
+
+export { parseDsl, BLOCK_KINDS } from "./parse";
+export type {
+	BlockKind,
+	CallRef,
+	DslBlock,
+	DslDocument,
+	DslParam,
+	FieldRef,
+	GlobalRef,
+	Span,
+} from "./parse";
+
+export { BUILTINS, BUILTIN_BY_NAME, BUILTIN_VALUES } from "./builtins";
+export type { Builtin } from "./builtins";
+
+export { checkDsl } from "./check";
+export type {
+	ColumnLookup,
+	DslContext,
+	DslIssue,
+	DslSeverity,
+	EntityShape,
+} from "./types";