@dforge-core/metadata 0.0.22 → 0.0.23

package/src/dsl/parse.ts

@@ -0,0 +1,639 @@
+// Structural scan of a .dsl file: blocks, param declarations, record-field
+// 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";
+
+export type BlockKind =
+	| "params"
+	| "canExecute"
+	| "schema"
+	| "onBeforeStart"
+	| "execute";
+
+/** In the order `ActionDslCompiler.ParseBlocks` expects them in a file. */
+export const BLOCK_KINDS: BlockKind[] = [
+	"params",
+	"canExecute",
+	"schema",
+	"onBeforeStart",
+	"execute",
+];
+
+const BLOCK_BY_LOWER = new Map(BLOCK_KINDS.map((k) => [k.toLowerCase(), k]));
+
+export interface Span {
+	start: number;
+	end: number;
+}
+
+export interface DslBlock {
+	kind: BlockKind;
+	label: Span;
+	/** Span of the block body — label end to the next label (or EOF). */
+	body: Span;
+}
+
+export interface DslParam {
+	name: string;
+	nameSpan: Span;
+	/** fieldTypeCd, or the referenced entity code when `isRef`. */
+	type: string;
+	typeSpan: Span;
+	isRef: boolean;
+	required: boolean;
+	label?: string;
+}
+
+/**
+ * A `[field]` read. `navigation` holds the property hops that follow it, each
+ * remembering whether it was written `.[target]` or `.target`: the compiler
+ * rewrites the FIRST hop either way, and then only a surviving `.[` is the
+ * multi-hop compile error. A dotted tail is plain JavaScript on the value the
+ * hop returned, so `[customer].[code]`, `[a].b.c` and `[plate].length` all
+ * compile.
+ */
+export interface FieldRef {
+	name: string;
+	span: Span;
+	/** Span including the brackets. */
+	outerSpan: Span;
+	navigation: Array<{ name: string; span: Span; bracketed: boolean }>;
+	block: BlockKind | null;
+	/**
+	 * False when the read is bound to a numbered record rather than the current
+	 * one — `records[0][status]`, which `RxRecordsFieldRead` rewrites ahead of
+	 * the generic `[field]` pass. The name is still a column of the entity, so
+	 * the column rules apply; the batch-mode rule does not.
+	 */
+	isCurrentRecord: boolean;
+	/** Index of the token that opens this read — the `[`. */
+	startIndex: number;
+	/**
+	 * Index of the last token this read consumes, navigation included. A hop is
+	 * 2 tokens as `.prop` but 4 as `.[prop]`, so callers that need the token
+	 * after the read cannot compute it from `navigation.length`.
+	 */
+	endIndex: number;
+}
+
+/** `params[x]` / `old[x]` — subscript reads off a DSL global. */
+export interface GlobalRef {
+	global: "params" | "old" | "records";
+	property: string;
+	span: Span;
+	block: BlockKind | null;
+}
+
+export interface CallRef {
+	name: string;
+	nameSpan: Span;
+	/** First argument when it is a string literal — the entity code, usually. */
+	firstStringArg?: { value: string; span: Span };
+	block: BlockKind | null;
+}
+
+export interface DslDocument {
+	blocks: DslBlock[];
+	params: DslParam[];
+	fieldRefs: FieldRef[];
+	globalRefs: GlobalRef[];
+	calls: CallRef[];
+	tokens: Token[];
+	/**
+	 * Every mention of `records`, subscript (`records[x]`) or bare
+	 * (`for x in records`). `globalRefs` only holds the subscript form, so a
+	 * rule that needs to point at the batch loop has nothing to anchor to.
+	 */
+	recordsRefs: Span[];
+	/** Names bound by `var`/`let`/`const` or a `for` head, plus declared params. */
+	locals: Set<string>;
+	/**
+	 * Loop variables bound by `for x in records {` — `RxForLoop` and nothing
+	 * else, so an ordinary `for (var x of xs)` is not one. Their `x[field]`
+	 * subscripts read the entity's columns, which is why they come back as
+	 * field reads.
+	 */
+	recordsLoopVars: Set<string>;
+}
+
+const GLOBALS = new Set(["params", "old", "records"]);
+
+export function parseDsl(text: string): DslDocument {
+	const all = tokenize(text);
+	const tokens = all.filter((t) => t.kind !== "comment");
+
+	const blocks = findBlocks(text, tokens);
+	const blockAt = (offset: number): BlockKind | null =>
+		blocks.find((b) => offset >= b.body.start && offset < b.body.end)?.kind ??
+		null;
+
+	const params = parseParams(tokens, blocks);
+	const fieldRefs: FieldRef[] = [];
+	const globalRefs: GlobalRef[] = [];
+	const calls: CallRef[] = [];
+	const recordsRefs: Span[] = [];
+	const locals = collectLocals(tokens, params);
+	const recordsLoopVars = collectRecordsLoopVars(tokens);
+
+	for (let i = 0; i < tokens.length; i++) {
+		const t = tokens[i]!;
+
+		if (t.kind === "punct" && t.text === "[" && isFieldAccessStart(text, t.start)) {
+			const name = tokens[i + 1];
+			const close = tokens[i + 2];
+			if (name?.kind === "ident" && close?.text === "]") {
+				const ref: FieldRef = {
+					name: name.text,
+					span: { start: name.start, end: name.end },
+					outerSpan: { start: t.start, end: close.end },
+					navigation: [],
+					block: blockAt(t.start),
+					isCurrentRecord: true,
+					startIndex: i,
+					endIndex: i + 2,
+				};
+				ref.endIndex = collectNavigation(tokens, i + 2, ref);
+				i = ref.endIndex;
+				fieldRefs.push(ref);
+				continue;
+			}
+		}
+
+		// `x.records` is a property, not the batch global.
+		if (t.kind === "ident" && t.text === "records" && tokens[i - 1]?.text !== ".") {
+			recordsRefs.push({ start: t.start, end: t.end });
+
+			// `records[0][status]` is one read of a numbered record. Taken
+			// apart, its tail looks exactly like a current-record read — which
+			// is why the compiler rewrites this form first.
+			const field = indexedRecordField(tokens, i);
+			if (field) {
+				fieldRefs.push({
+					name: field.name.text,
+					span: { start: field.name.start, end: field.name.end },
+					outerSpan: { start: field.open.start, end: field.close.end },
+					navigation: [],
+					block: blockAt(t.start),
+					isCurrentRecord: false,
+					startIndex: field.openIndex,
+					endIndex: field.openIndex + 2,
+				});
+				i = field.openIndex + 2;
+				continue;
+			}
+		}
+
+		// `x[field]` on a batch loop variable. The compiler rewrites it to
+		// `x.get('field')` and checks the name against the entity's columns
+		// exactly as it checks a bare `[field]`.
+		if (t.kind === "ident" && recordsLoopVars.has(t.text)) {
+			const open = tokens[i + 1];
+			const name = tokens[i + 2];
+			const close = tokens[i + 3];
+			if (open?.text === "[" && name?.kind === "ident" && close?.text === "]") {
+				fieldRefs.push({
+					name: name.text,
+					span: { start: name.start, end: name.end },
+					outerSpan: { start: open.start, end: close.end },
+					navigation: [],
+					block: blockAt(t.start),
+					isCurrentRecord: false,
+					startIndex: i + 1,
+					endIndex: i + 3,
+				});
+				i += 3;
+				continue;
+			}
+		}
+
+		if (t.kind === "ident" && GLOBALS.has(t.text)) {
+			const open = tokens[i + 1];
+			const prop = tokens[i + 2];
+			const close = tokens[i + 3];
+			if (open?.text === "[" && prop?.kind === "ident" && close?.text === "]") {
+				globalRefs.push({
+					global: t.text as GlobalRef["global"],
+					property: prop.text,
+					span: { start: prop.start, end: prop.end },
+					block: blockAt(t.start),
+				});
+				i += 3;
+				continue;
+			}
+		}
+
+		if (t.kind === "ident" && tokens[i + 1]?.text === "(") {
+			const prev = tokens[i - 1];
+			// `.method(` is a call on a value, not a DSL built-in.
+			if (prev?.text === ".") continue;
+			const call: CallRef = {
+				name: t.text,
+				nameSpan: { start: t.start, end: t.end },
+				block: blockAt(t.start),
+			};
+			const firstArg = tokens[i + 2];
+			if (firstArg?.kind === "string") {
+				call.firstStringArg = {
+					value: stringValue(firstArg),
+					span: { start: firstArg.start, end: firstArg.end },
+				};
+			}
+			calls.push(call);
+		}
+	}
+
+	return {
+		blocks,
+		params,
+		fieldRefs,
+		globalRefs,
+		calls,
+		tokens,
+		recordsRefs,
+		locals,
+		recordsLoopVars,
+	};
+}
+
+/**
+ * `[` opens a record-field read unless a word character sits immediately
+ * before it — the compiler's `(?<!\w)\[(\w+)\]`, character for character.
+ *
+ * It has to be the character and not the previous token: the lookbehind does
+ * not skip whitespace, so `rec[qty]` is a subscript but `[qty]` opening a line
+ * is a read however the line above ended. The same lookbehind is what keeps
+ * `params[x]` and `old[x]` out of the field reads.
+ *
+ * A single-element array literal (`var ids = [orderId]`) is genuinely
+ * ambiguous with a field read at this level: both are `[ident]` in expression
+ * position, and `var total = [qty]` is a real field read. The disambiguation
+ * needs to know whether the name is a column or a local, so it happens in the
+ * diagnostics layer against `locals` rather than here.
+ */
+function isFieldAccessStart(text: string, start: number): boolean {
+	return start === 0 || !/\w/.test(text[start - 1]!);
+}
+
+/**
+ * The `[field]` half of a `records[n][field]` read starting at `i`, or null.
+ *
+ * Mirrors `RxRecordsFieldRead`'s `\brecords\[(\d+)\]\[(\w+)\]`: a literal
+ * digit index only. `records[i][x]` with a variable index is not this form for
+ * the compiler either — it leaves `records[i]` alone and then rewrites the tail
+ * as a current-record read.
+ */
+function indexedRecordField(
+	tokens: Token[],
+	i: number,
+): { name: Token; open: Token; close: Token; openIndex: number } | null {
+	const index = tokens[i + 2];
+	if (tokens[i + 1]?.text !== "[") return null;
+	if (index?.kind !== "number" || !/^\d+$/.test(index.text)) return null;
+	if (tokens[i + 3]?.text !== "]") return null;
+
+	const open = tokens[i + 4];
+	const name = tokens[i + 5];
+	const close = tokens[i + 6];
+	if (open?.text !== "[" || name?.kind !== "ident" || close?.text !== "]")
+		return null;
+	return { name, open, close, openIndex: i + 4 };
+}
+
+/** Walk `.prop` / `.[prop]` hops after a field read. Returns the last index consumed. */
+function collectNavigation(tokens: Token[], closeIdx: number, ref: FieldRef): number {
+	let i = closeIdx;
+	for (;;) {
+		const dot = tokens[i + 1];
+		if (dot?.text !== ".") return i;
+		const next = tokens[i + 2];
+		if (next?.kind === "ident") {
+			// A method call is not navigation — `[items].length` is, `[x].trim()` isn't.
+			if (tokens[i + 3]?.text === "(") return i;
+			ref.navigation.push({
+				name: next.text,
+				span: { start: next.start, end: next.end },
+				bracketed: false,
+			});
+			i += 2;
+			continue;
+		}
+		if (next?.text === "[") {
+			const name = tokens[i + 3];
+			const close = tokens[i + 4];
+			if (name?.kind === "ident" && close?.text === "]") {
+				ref.navigation.push({
+					name: name.text,
+					span: { start: name.start, end: name.end },
+					bracketed: true,
+				});
+				i += 4;
+				continue;
+			}
+		}
+		return i;
+	}
+}
+
+/**
+ * `for x in records {` — `RxForLoop`'s shape, brace included. A loop written
+ * any other way is not a batch loop to the compiler either, and its variable
+ * does not carry record fields.
+ */
+function collectRecordsLoopVars(tokens: Token[]): Set<string> {
+	const vars = new Set<string>();
+	for (let i = 0; i < tokens.length - 4; i++) {
+		if (tokens[i]!.text !== "for" || tokens[i]!.kind !== "ident") continue;
+		const name = tokens[i + 1]!;
+		if (name.kind !== "ident") continue;
+		if (tokens[i + 2]!.text !== "in" || tokens[i + 3]!.text !== "records") continue;
+		if (tokens[i + 4]!.text !== "{") continue;
+		vars.add(name.text);
+	}
+	return vars;
+}
+
+const DECLARATORS = new Set(["var", "let", "const"]);
+
+/**
+ * Names bound in the script itself. Used to tell `var ids = [orderId]` (an
+ * array literal holding a local) from `[qty]` (a record-field read) — the two
+ * are indistinguishable by token shape alone.
+ */
+function collectLocals(tokens: Token[], params: DslParam[]): Set<string> {
+	const locals = new Set<string>(params.map((p) => p.name));
+	collectFunctionParams(tokens, locals);
+	for (let i = 0; i < tokens.length; i++) {
+		const t = tokens[i]!;
+		if (t.kind !== "ident") continue;
+
+		if (DECLARATORS.has(t.text)) {
+			collectDeclarations(tokens, i + 1, locals);
+			continue;
+		}
+
+		// `for x in records` / `for (var x of xs)` — the loop variable.
+		if (t.text === "for") {
+			let j = i + 1;
+			if (tokens[j]?.text === "(") j++;
+			if (tokens[j]?.kind === "ident" && DECLARATORS.has(tokens[j]!.text)) j++;
+			const name = tokens[j];
+			if (name?.kind === "ident" && !DECLARATORS.has(name.text)) locals.add(name.text);
+		}
+	}
+	return locals;
+}
+
+/**
+ * Parameter names of every function in the script — declarations, expressions,
+ * arrows and method shorthand. They bind names exactly as `var` does, so
+ * `function wrap(value) { return [value] }` holds an array literal rather than
+ * a field read.
+ */
+function collectFunctionParams(tokens: Token[], locals: Set<string>): void {
+	for (let i = 0; i < tokens.length; i++) {
+		const t = tokens[i]!;
+
+		if (t.kind === "ident" && t.text === "function") {
+			let j = i + 1;
+			if (tokens[j]?.kind === "ident") j++; // the name, when it has one
+			if (tokens[j]?.text === "(") collectParenIdents(tokens, j, locals);
+			continue;
+		}
+
+		if (t.text === "=>") {
+			const prev = tokens[i - 1];
+			// `x => …` binds one name; `(x, y) => …` binds the list.
+			if (prev?.kind === "ident") locals.add(prev.text);
+			else if (prev?.text === ")") {
+				const open = matchingOpenParen(tokens, i - 1);
+				if (open >= 0) collectParenIdents(tokens, open, locals);
+			}
+			continue;
+		}
+
+		// Method shorthand `f(a, b) { … }`. The body brace is what tells it from
+		// a call, and a control keyword's `(…)` is a condition, not a list.
+		if (
+			t.kind === "ident" &&
+			!CONTROL_KEYWORDS.has(t.text) &&
+			tokens[i + 1]?.text === "("
+		) {
+			const close = matchingCloseParen(tokens, i + 1);
+			if (close >= 0 && tokens[close + 1]?.text === "{")
+				collectParenIdents(tokens, i + 1, locals);
+		}
+	}
+}
+
+/**
+ * Every ident between the `(` at `openIndex` and its match. Over-collects a
+ * default value's names (`f(x = y)`), which only ever suppresses a diagnostic —
+ * the same fail-open trade `collectPattern` makes.
+ */
+function collectParenIdents(
+	tokens: Token[],
+	openIndex: number,
+	locals: Set<string>,
+): void {
+	let depth = 0;
+	for (let i = openIndex; i < tokens.length; i++) {
+		const t = tokens[i]!;
+		if (t.text === "(") depth++;
+		else if (t.text === ")") {
+			depth--;
+			if (depth === 0) return;
+		} else if (t.kind === "ident") locals.add(t.text);
+	}
+}
+
+function matchingCloseParen(tokens: Token[], openIndex: number): number {
+	let depth = 0;
+	for (let i = openIndex; i < tokens.length; i++) {
+		if (tokens[i]!.text === "(") depth++;
+		else if (tokens[i]!.text === ")" && --depth === 0) return i;
+	}
+	return -1;
+}
+
+function matchingOpenParen(tokens: Token[], closeIndex: number): number {
+	let depth = 0;
+	for (let i = closeIndex; i >= 0; i--) {
+		if (tokens[i]!.text === ")") depth++;
+		else if (tokens[i]!.text === "(" && --depth === 0) return i;
+	}
+	return -1;
+}
+
+/**
+ * The binding list after a declarator: `a = 1, b = 2`, where each binding is
+ * either a name or a destructuring pattern. Scans ahead without moving the
+ * caller's cursor, so a `var` nested in an initializer is still visited.
+ */
+function collectDeclarations(tokens: Token[], start: number, locals: Set<string>): void {
+	let j = start;
+	for (;;) {
+		const head = tokens[j];
+		if (!head) return;
+
+		if (head.text === "{" || head.text === "[") {
+			j = collectPattern(tokens, j, locals);
+		} else if (head.kind === "ident" && !DECLARATORS.has(head.text)) {
+			locals.add(head.text);
+			j++;
+		} else return;
+
+		// Skip this binding's initializer and stop at the comma opening the
+		// next one. Commas inside the initializer sit at depth 1+ (`f(x, y)`),
+		// which is what keeps its arguments out of `locals`.
+		let depth = 0;
+		for (; j < tokens.length; j++) {
+			const n = tokens[j]!;
+			if (n.text === "(" || n.text === "[" || n.text === "{") depth++;
+			else if (n.text === ")" || n.text === "]" || n.text === "}") depth--;
+			if (depth < 0) return;
+			if (depth > 0) continue;
+			if (n.text === ";") return;
+			if (n.text === ",") break;
+			// A new line at depth 0 ends the statement; the alternative is
+			// running to end-of-file on a declaration with no terminator.
+			if (n.startsLine) return;
+		}
+		if (j >= tokens.length) return;
+		j++;
+	}
+}
+
+/**
+ * Every ident inside a `{…}` / `[…]` binding pattern; returns the index after
+ * it. The names of a pattern sit at depth 1+, out of reach of the comma rule
+ * in `collectDeclarations`. This over-collects — the `a` of `{ a: b }` binds
+ * nothing — but a name in `locals` only ever suppresses a diagnostic, so the
+ * error is in the fail-open direction.
+ */
+function collectPattern(tokens: Token[], start: number, locals: Set<string>): number {
+	let depth = 0;
+	let i = start;
+	for (; i < tokens.length; i++) {
+		const t = tokens[i]!;
+		if (t.text === "{" || t.text === "[") depth++;
+		else if (t.text === "}" || t.text === "]") {
+			depth--;
+			if (depth === 0) return i + 1;
+		} else if (t.kind === "ident") locals.add(t.text);
+	}
+	return i;
+}
+
+/**
+ * The block kind labelled at `i`, wherever on the line it sits.
+ *
+ * `findBlocks` additionally requires column 0, which is what the compiler's
+ * `^execute:` anchor means. The un-anchored form exists for the diagnostic
+ * 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 {
+	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;
+}
+
+function findBlocks(text: string, tokens: Token[]): DslBlock[] {
+	const labels: Array<{ kind: BlockKind; span: Span }> = [];
+	for (let i = 0; i < tokens.length; i++) {
+		const t = tokens[i]!;
+		// 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 } });
+		// `execute:` is `(.*?)\z` — it runs to end-of-file, so a later header
+		// is body text.
+		if (kind === "execute") break;
+	}
+
+	return labels.map((l, idx) => ({
+		kind: l.kind,
+		label: l.span,
+		body: {
+			start: l.span.end,
+			end: labels[idx + 1]?.span.start ?? text.length,
+		},
+	}));
+}
+
+function parseParams(tokens: Token[], blocks: DslBlock[]): DslParam[] {
+	const block = blocks.find((b) => b.kind === "params");
+	if (!block) return [];
+
+	const inBlock = tokens.filter(
+		(t) => t.start >= block.body.start && t.start < block.body.end,
+	);
+	const params: DslParam[] = [];
+
+	for (let i = 0; i < inBlock.length; i++) {
+		const name = inBlock[i]!;
+		// One declaration per line — and `^params:\s*` swallows the newline, so
+		// the header's own line counts: `params: qty: number required` declares
+		// qty exactly as an indented line below would.
+		if ((!name.startsLine && i !== 0) || name.kind !== "ident") continue;
+		if (inBlock[i + 1]?.text !== ":") continue;
+
+		let j = i + 2;
+		let isRef = false;
+		if (inBlock[j]?.kind === "ident" && inBlock[j]!.text === "ref") {
+			isRef = true;
+			j++;
+		}
+		const type = inBlock[j];
+		if (!type || type.kind !== "ident") continue;
+		// RxParamDecl matches one trimmed line, so the type shares the name's
+		// line. Without this a bare `execute:` swallows the next line's first
+		// word as its type and passes for a declaration.
+		if (type.line !== name.line) continue;
+
+		// A `ref` target may be qualified and hyphenated: `ref fin-ch.invoice`.
+		// The lexer splits on `-` and `.`, so glue back any pieces that are
+		// physically adjacent — a space means the name ended.
+		let typeEnd = type.end;
+		let typeText = type.text;
+		if (isRef) {
+			while (
+				inBlock[j + 1] &&
+				(inBlock[j + 1]!.text === "-" || inBlock[j + 1]!.text === ".") &&
+				inBlock[j + 2]?.kind === "ident" &&
+				inBlock[j + 1]!.start === typeEnd &&
+				inBlock[j + 2]!.start === inBlock[j + 1]!.end
+			) {
+				typeText += inBlock[j + 1]!.text + inBlock[j + 2]!.text;
+				typeEnd = inBlock[j + 2]!.end;
+				j += 2;
+			}
+		}
+
+		let required = false;
+		let label: string | undefined;
+		for (let k = j + 1; k < inBlock.length && !inBlock[k]!.startsLine; k++) {
+			const t = inBlock[k]!;
+			if (t.kind === "ident" && t.text === "required") required = true;
+			if (t.kind === "string" && label === undefined) label = stringValue(t);
+		}
+
+		params.push({
+			name: name.text,
+			nameSpan: { start: name.start, end: name.end },
+			type: typeText,
+			typeSpan: { start: type.start, end: typeEnd },
+			isRef,
+			required,
+			label,
+		});
+	}
+
+	return params;
+}