@tikoci/centrs 0.1.3 → 0.1.6

package/src/explain/blocks.ts

@@ -0,0 +1,175 @@
+/**
+ * Block / scope-brace classification for `explain` (centrs canonicalizer).
+ *
+ * Ratified by the phase-0 lab, question Q2 (#185) and promoted from the
+ * throwaway probe `.scratch/explain-lab-blocktree.ts`. Q2 asks: can an offline,
+ * schema-free brace tracker tell a `{…}` SCOPE (`do=`/`else=`/`on-error=`, which
+ * IL lowers to `name=;(evl …)`) from a `name={…}` LITERAL value (braces
+ * stripped, body kept as RAW text, never lowered)? Descending into a literal
+ * body as if it held statements is the prior-art bug (canonicalize-audit #8/H5).
+ *
+ * The source-visible scope set is a small CLOSED set harvested across the
+ * 913-script corpus, so the distinction is schema-free — it reads the argument
+ * name (and, for the one head-dependent case, the leading directive) off the
+ * statement itself.
+ *
+ * This module ships only the (single-pass, non-recursive) classification
+ * primitives the path resolver needs. The recursive block *tree* / topology
+ * surface stays in the lab until it can be promoted with a bounded, index-based
+ * traversal of its own.
+ *
+ * Every string skip here goes through `segment.ts`'s `scanQuotedString` rather
+ * than a local quote-to-quote loop, so this module and the segmenter cannot
+ * drift on where a string ends: a `}` inside the nested string of a `$[…]`
+ * substitution is not a brace, and reading it as one truncated the scope body
+ * (#199).
+ */
+
+import {
+	DIRECTIVE_BODY,
+	HEAD_SCOPED_ARG_NAMES,
+	matchingBraceEnd,
+	SCOPE_ARG_NAMES,
+	scopeNameFromMasked,
+} from "./scope-brace.ts";
+import {
+	documentRange,
+	type MaskedRange,
+	maskComments,
+	scanQuotedString,
+} from "./segment.ts";
+
+export { DIRECTIVE_BODY, HEAD_SCOPED_ARG_NAMES, SCOPE_ARG_NAMES };
+/** One depth-0 scope block found in a statement: its name and raw body text. */
+export interface ScopeBlock {
+	name: string;
+	body: string;
+	/**
+	 * Offset of `body`'s first character within the text `scopeBlocks` was given
+	 * — i.e. one past the opening `{`.
+	 *
+	 * Without it a caller that re-segments `body` gets BODY-RELATIVE offsets and
+	 * no way to rebase them, so a span or region found inside a `do={…}` cannot
+	 * be reported in document space. `pathresolve` is that caller.
+	 */
+	start: number;
+}
+
+/**
+ * The scope name for the `{` at `open`, or null when the brace is a value.
+ * Two shapes qualify: `<name>={` with name in the closed set (or head-scoped
+ * under the right leading directive), and a brace body directly following a
+ * body-taking directive (`:do {`, `:retry {`, `:onerror Err {`).
+ */
+export function scopeNameAt(text: string, open: number): string | null {
+	return scopeNameFromMasked(maskComments(text), open);
+}
+
+/** True when the `{` at `open` opens a scope rather than a literal value. */
+export function isScopeBrace(text: string, open: number): boolean {
+	return scopeNameAt(text, open) !== null;
+}
+
+/**
+ * {@link isScopeBrace} for a reader that already holds the document's mask,
+ * with `open` relative to `range` rather than to the whole document.
+ *
+ * The string form has to mask the text it is given, and a statement's text
+ * carries its whole nested `do={…}` subtree — so asking it this question once
+ * per brace re-derived a mask over that subtree once per enclosing level
+ * (#322). Same answer: the floor is what makes a ranged reading identical to
+ * the region read on its own (`scope-brace.ts` → `scopeNameFromMasked`).
+ */
+export function isScopeBraceIn(range: MaskedRange, open: number): boolean {
+	return (
+		scopeNameFromMasked(range.masked, range.start + open, range.start) !== null
+	);
+}
+
+/**
+ * The depth-0 scope `{…}` in a statement, with names and raw body text. A
+ * single left-to-right pass (no recursion): each scope's body is returned raw
+ * for the caller to segment/recurse under its own depth budget. Literal `{…}`
+ * values are skipped, not descended.
+ */
+export function scopeBlocks(text: string): ScopeBlock[] {
+	return scopeBlocksIn(documentRange(text));
+}
+
+/**
+ * The same scan over a RANGE of a document, reading the document's own mask.
+ *
+ * `ScopeBlock.start` stays relative to the range, which is what its contract
+ * already promises ("within the text `scopeBlocks` was given") and what a
+ * caller rebasing through `Loc` needs. Every other offset here is absolute.
+ */
+export function scopeBlocksIn(range: MaskedRange): ScopeBlock[] {
+	// Scan a comment-masked copy for structure so a `#`-comment `}`/`[` cannot
+	// truncate a body or shift depth; slice the ORIGINAL for the body text.
+	const { text, masked, start: lo, end: hi } = range;
+	const blocks: ScopeBlock[] = [];
+	let depth = 0;
+	for (let i = lo; i < hi; i++) {
+		const c = masked[i];
+		if (c === '"') {
+			i = scanQuotedString(masked, i, hi).end - 1;
+			continue;
+		}
+		if (c === "[" || c === "(") depth++;
+		else if (c === "]" || c === ")") {
+			if (depth > 0) depth--;
+		} else if (c === "{") {
+			const indexedEnd = range.coordinateIdentity
+				? matchingBraceEnd(masked, i)
+				: undefined;
+			const end =
+				indexedEnd !== undefined && indexedEnd < hi
+					? indexedEnd
+					: matchBraceInMasked(masked, i, hi);
+			if (depth === 0) {
+				const name = scopeNameFromMasked(masked, i, lo);
+				if (name !== null)
+					blocks.push({
+						name,
+						body: text.slice(i + 1, end),
+						start: i + 1 - lo,
+					});
+			}
+			i = end;
+		} else if (c === "}") {
+			if (depth > 0) depth--;
+		}
+	}
+	return blocks;
+}
+
+/** Bodies of the depth-0 scope `{…}` in a statement (for block recursion). */
+export function scopeBodies(text: string): string[] {
+	return scopeBlocks(text).map((b) => b.body);
+}
+
+function matchBraceInMasked(
+	masked: string,
+	open: number,
+	limit: number = masked.length,
+): number {
+	let depth = 0;
+	for (let i = open; i < limit; i++) {
+		const c = masked[i];
+		if (c === '"') {
+			i = scanQuotedString(masked, i, limit).end - 1;
+			continue;
+		}
+		if (c === "{") depth++;
+		else if (c === "}") {
+			depth--;
+			if (depth === 0) return i;
+		}
+	}
+	return limit;
+}
+
+/** Index of the `}` matching the `{` at `open`, honoring strings and comments. */
+export function matchBrace(text: string, open: number): number {
+	return matchBraceInMasked(maskComments(text), open);
+}

package/src/explain/brace-slots.ts

@@ -0,0 +1,143 @@
+/**
+ * Which root-directive value slots read a `{…}` as an ARRAY (#225, #257).
+ *
+ * `explain` used to gate brace arrays on the statement's resolved path: any
+ * `/` path allowed one, positionally or under `in=`. A device sweep showed that
+ * is wrong in both directions on CHR 7.23.3 — `:delay {1;2}`, `:beep {1;2}`,
+ * `:resolve {1;2}`, `:if condition={1;2}` and `:local name={1;2}` are syntax
+ * errors the path rule called arrays, while `:for from=`, `:execute script=`,
+ * `:local value=` and 50-odd more are accepted braces it refused.
+ *
+ * The real key is the SLOT, and a slot has four outcomes, not two:
+ *
+ *   - **array** — the content is EVALUATED: `:foreach i in={(1,2)} do={}`
+ *     lowers to `in=(, 1 2)`. Only these 72 belong here.
+ *   - **code** — the braces are a program. `:onerror e in={1;2} do={}` lowers
+ *     to `in=;(evl (<%% bad command name 1 …))`, so the SAME NAME is an array
+ *     on `:foreach` and a block on `:onerror`.
+ *   - **text** — the brace is accepted and its content taken VERBATIM as a
+ *     script: `:execute script={(1,2)}` lowers to `script=(1,2)`, not
+ *     `(, 1 2)`. This outcome is why `{1;2}` alone is not a sufficient probe —
+ *     `:local z {1;2}` and `:execute script={1;2}` both lower to `…=1;2`, and
+ *     reading only that put `:execute script=` in the array set, one step from
+ *     hinting `array` on a script body.
+ *   - **error** — `:parse` refuses the statement.
+ *
+ * A slot the sweep could not ask (30 of 222, mostly ones whose scalar control
+ * also fails) is absent from this table, which is the fail-closed direction:
+ * absent means the walk refuses to read the value, and a refusal costs nothing
+ * but coverage. Every brace array in the 948-script corpus lands on a slot
+ * listed here except one `:execute {…}` script body, which is `text`.
+ *
+ * A positional slot is keyed by its zero-based index among positionals, because
+ * position decides: `:local {1;2}` puts the literal in the NAME slot (a syntax
+ * error) while `:local z {1;2}` puts it in the VALUE slot.
+ *
+ * **The verb is matched VERBATIM, and that is the device's rule, not laziness.**
+ * `verbsplit.ts` keeps a run token's source casing, and RouterOS accepts only
+ * the lower-case spelling: `:LOCAL z {1;2}`, `:Local z {1;2}`, `:PUT {1;2}` and
+ * even `/IP/DNS/set servers=1.1.1.1` all draw `expected command name (line 1
+ * column 2)` on CHR 7.23.3, while an ARGUMENT's casing is free (`:local Z {1;2}`
+ * parses and binds `$Z`). Normalizing the verb here would open the gate on a
+ * statement the device refuses to parse — the exact fabrication this table
+ * exists to remove — so a differently-cased directive misses every entry and is
+ * refused, which is the same answer the device gives.
+ *
+ * The evidence is `test/fixtures/explain/values.json` →
+ * `interiorGrounding.braceSlots` (222 rows, CHR 7.23.3, `:parse` IL — NOT
+ * `highlight`, which accepts `{1;2,}` and `(1,)` that `:parse` rejects), and
+ * `explain-values.test.ts` asserts this table still equals the `array` rows of
+ * that block. Re-derive with `bun run explain:probe:brace-slots` (#186).
+ */
+const BRACE_ARRAY_SLOTS: ReadonlyMap<string, ReadonlySet<string>> = new Map(
+	(
+		[
+			[
+				"convert",
+				["#0", "from-scheme", "to-scheme", "transform-scheme", "value"],
+			],
+			["deserialize", ["#0", "value"]],
+			["error", ["#0", "message"]],
+			["find", ["#0", "#1", "from", "in", "key"]],
+			["for", ["from", "step", "to"]],
+			["foreach", ["in"]],
+			["global", ["#1", "value"]],
+			["len", ["#0", "value"]],
+			["local", ["#1", "value"]],
+			["parse", ["#0", "value"]],
+			["pick", ["#0", "#1", "begin", "counter", "end"]],
+			["put", ["#0", "message"]],
+			["range", ["#0", "#1", "from", "to"]],
+			["return", ["#0", "value"]],
+			["rndnum", ["#0", "#1", "from", "to"]],
+			["rndstr", ["#0", "#1", "from", "length"]],
+			["serialize", ["#0", "order", "value"]],
+			["set", ["#1", "value"]],
+			["toarray", ["#0", "value"]],
+			["tobool", ["#0", "value"]],
+			["toid", ["#0", "value"]],
+			["toip", ["#0", "value"]],
+			["toip6", ["#0", "value"]],
+			["tonsec", ["#0", "value"]],
+			["tonum", ["#0", "value"]],
+			["tostr", ["#0", "value"]],
+			["totime", ["#0", "value"]],
+			["typeof", ["#0", "value"]],
+		] as const
+	).map(([verb, slots]) => [verb, new Set<string>(slots)]),
+);
+
+/** Slots that accept a brace as code or verbatim script text, not as an array. */
+const BRACE_PROGRAM_SLOTS: ReadonlyMap<string, ReadonlySet<string>> = new Map(
+	(
+		[
+			["set", ["do"]],
+			["do", ["#0", "#1", "command", "on-error"]],
+			["execute", ["#0", "script"]],
+			["for", ["do", "on-error"]],
+			["foreach", ["do", "on-error"]],
+			["global", ["do"]],
+			["grep", ["#0", "script"]],
+			["if", ["do", "else"]],
+			["local", ["do"]],
+			["onerror", ["#1", "do", "in"]],
+			["retry", ["#0", "#1", "command", "on-error"]],
+			["time", ["#0", "#1", "command"]],
+			["while", ["do"]],
+		] as const
+	).map(([verb, slots]) => [verb, new Set<string>(slots)]),
+);
+
+/** The table as flat `verb slot` pairs, for the fixture-drift assertion. */
+export function braceArraySlotPairs(): string[] {
+	const pairs: string[] = [];
+	for (const [verb, slots] of BRACE_ARRAY_SLOTS)
+		for (const slot of slots) pairs.push(`${verb} ${slot}`);
+	return pairs.sort();
+}
+
+/** The code/text table as flat pairs, for the same fixture-drift assertion. */
+export function braceProgramSlotPairs(): string[] {
+	const pairs: string[] = [];
+	for (const [verb, slots] of BRACE_PROGRAM_SLOTS)
+		for (const slot of slots) pairs.push(`${verb} ${slot}`);
+	return pairs.sort();
+}
+
+/**
+ * Whether a `{…}` in this slot of this root directive is an array literal.
+ *
+ * `verb` is the resolved directive name without its colon; `slot` is the
+ * lowercase argument name, or `#<index>` for a positional.
+ */
+export function braceSlotTakesArray(verb: string, slot: string): boolean {
+	return BRACE_ARRAY_SLOTS.get(verb)?.has(slot) === true;
+}
+
+/** Whether the device sweep proved this root-directive slot accepts `{...}`. */
+export function braceSlotAcceptsBrace(verb: string, slot: string): boolean {
+	return (
+		braceSlotTakesArray(verb, slot) ||
+		BRACE_PROGRAM_SLOTS.get(verb)?.has(slot) === true
+	);
+}

package/src/explain/brace-tokens.ts

@@ -0,0 +1,39 @@
+/**
+ * B3 brace fill — claims brace delimiters on the residual.
+ *
+ * Value-anchored array literals are claimed as `value` leaves, but their outer
+ * delimiters remain unclassified (container excluded to avoid overlap). Scope
+ * braces (`do={...}` etc.) are never array values. Both families therefore
+ * appear on the residual after the `value` and `string` fills, so this fill
+ * claims every remaining `{` / `}` byte there as `brace`. #264 B5 kept scope
+ * and array delimiters in one class: `structure.blocks[]` already locates every
+ * scope block, and an array container is the `data.values.occurrences[]` entry
+ * that is some other occurrence's `parent`, so the distinction is a join away.
+ */
+
+import type { ExplainToken } from "../explain.ts";
+import { clipToResidual } from "./token-ranges.ts";
+
+/** Brace delimiter spans on the residual. */
+export function braceSpans(
+	analyzed: string,
+	residual: readonly { start: number; end: number }[],
+): ExplainToken[] {
+	const len = analyzed.length;
+	if (len === 0 || residual.length === 0) return [];
+	const out: ExplainToken[] = [];
+	for (let i = 0; i < analyzed.length; i++) {
+		const c = analyzed[i] as string;
+		if (c !== "{" && c !== "}") continue;
+		for (const r of clipToResidual(i, i + 1, residual)) {
+			out.push({
+				start: r.start,
+				end: r.end,
+				class: "brace" as const,
+				ev: "e14",
+			});
+		}
+	}
+	out.sort((a, b) => a.start - b.start || a.end - b.end);
+	return out;
+}