@tikoci/centrs 0.1.9-next.22 → 0.1.9-next.24

package/src/explain/run-tokens.ts

@@ -0,0 +1,223 @@
+/**
+ * The leading path-token run of a statement, for `explain`.
+ *
+ * A leaf module (it imports only the leaf data tables) so that `segment.ts` and
+ * `scope-brace.ts` can ask the question `verbsplit.ts` asks — "does this run
+ * already name a command verb?" (#496) — without the import cycle
+ * `verbsplit.ts` → `segment.ts` would make.
+ * It is the one word scanner both use; a second one written beside it would be
+ * free to disagree with the boundary rule. `verbsplit.ts` re-exports the public
+ * names, so the Q6 surface is unchanged.
+ */
+
+import { commandVerbIndex } from "./catalog.ts";
+import type { Span } from "./pathresolve.ts";
+import { VERBS } from "./verbs.ts";
+
+const BARE_WORD = /^[A-Za-z][A-Za-z0-9._-]*$/;
+/**
+ * A word that ends the leading run: it carries `=` (V2) or opens a group /
+ * string / variable (V3). `:` is deliberately NOT here — RouterOS uses it only
+ * to start a scripting directive, not as a mid-statement opener, and a
+ * `:`-prefixed token is already rejected by `BARE_WORD` below, so it ends the
+ * run regardless.
+ */
+const RUN_TERMINATOR = /^[[({"$]/;
+
+export function isAsciiWhitespace(char: string | undefined): boolean {
+	return char === " " || char === "\t" || char === "\r" || char === "\n";
+}
+
+/** One whitespace-separated word, and where it sits in the text it came from. */
+export interface Word {
+	name: string;
+	/** offset of the word's first character, inclusive. */
+	start: number;
+	/** offset just past its last character, exclusive. */
+	end: number;
+	/** Source span of each character retained in `name`. */
+	chars: Span[];
+}
+
+/**
+ * The words of a statement, WITH their offsets (#202c).
+ *
+ * The one word scanner this module has. It replaced a
+ * `replace(/\\\r?\n/g,"").split(whitespace)` pair whose output could not be
+ * mapped back to the text it came from — and a second scanner written beside it
+ * for the offsets would be free to disagree with the boundary rule, which is the
+ * failure #202b hit three times in argument handling.
+ *
+ * H5 from the Q1 segmenter: a `\<newline>` is removed before RouterOS parses the
+ * continued line, so it JOINS the words either side of it rather than separating
+ * them (`na\<nl>me` is the single word `name`) and contributes no character to
+ * the name. That is why a word's `end - start` is not its `name.length`: the span
+ * covers the continuation bytes, the name does not. A caller taking an interior
+ * offset from a name is therefore wrong on continued statements, and
+ * {@link describeStatement} only ever publishes the run's END.
+ */
+export function* asciiWordSpans(text: string): Generator<Word> {
+	// Yielded ONE WORD AT A TIME rather than returned as a list. Both readers
+	// stop at the first word the leading run cannot take, and a statement's text
+	// carries its whole nested `do={…}` subtree — so building a word (and a span
+	// per character of it) for the rest of that subtree was work no caller ever
+	// looked at, once per enclosing level (#322). A word is complete when the
+	// next one starts, which is why the yield happens on the following boundary
+	// rather than at the point the word is opened.
+	let current: Word | null = null;
+	let i = 0;
+	while (i < text.length) {
+		const c = text[i] as string;
+		if (
+			c === "\\" &&
+			(text[i + 1] === "\n" || (text[i + 1] === "\r" && text[i + 2] === "\n"))
+		) {
+			// Inside a word this joins; between words it is whitespace that opens
+			// none — matching the removal-then-split the rule replaced.
+			i += text[i + 1] === "\r" ? 3 : 2;
+			if (current !== null) current.end = i;
+			continue;
+		}
+		if (isAsciiWhitespace(c)) {
+			if (current !== null) yield current;
+			current = null;
+			i++;
+			continue;
+		}
+		if (current === null) {
+			current = {
+				name: c,
+				start: i,
+				end: i + 1,
+				chars: [{ start: i, end: i + 1 }],
+			};
+		} else {
+			current.name += c;
+			current.end = i + 1;
+			current.chars.push({ start: i, end: i + 1 });
+		}
+		i++;
+	}
+	if (current !== null) yield current;
+}
+
+/** Separator that precedes a run token (V1). */
+export type Sep = "start" | "slash" | "space";
+
+/** One token of the leading path run, with the punctuation that introduced it. */
+export interface RunToken {
+	name: string;
+	sep: Sep;
+}
+
+/** A run token mapped back to the statement bytes that spell it. */
+export interface LocatedRunToken extends RunToken {
+	/** Name bytes, split where a `\<newline>` continuation interrupts them. */
+	nameSpans: Span[];
+	/** One valid `/` immediately before this token, if present. */
+	slashBefore?: Span;
+	/** One trailing `/` after this token, if present. */
+	slashAfter?: Span;
+}
+
+function coalesceChars(chars: readonly Span[]): Span[] {
+	const out: Span[] = [];
+	for (const char of chars) {
+		const last = out.at(-1);
+		if (last !== undefined && last.end === char.start) last.end = char.end;
+		else out.push({ start: char.start, end: char.end });
+	}
+	return out;
+}
+
+/**
+ * The leading path-token run WITH separators preserved (V1). Same stopping
+ * rules as `pathresolve`'s run (V2/V3), so the two stay comparable: a slash-
+ * joined word expands to several `slash`-separated tokens; a space-separated
+ * word is one `space` token. Stops at the first `=`/group/string/var word, and
+ * at any word carrying a non-`BARE_WORD` segment (a variable segment truncates
+ * the run before the verb).
+ */
+export function locatedRunTokens(text: string): LocatedRunToken[] {
+	const out: LocatedRunToken[] = [];
+	for (const word of asciiWordSpans(text)) {
+		if (word.name.includes("=") || RUN_TERMINATOR.test(word.name)) break;
+		const parts: {
+			name: string;
+			start: number;
+			end: number;
+			slashBefore?: Span;
+		}[] = [];
+		let start = 0;
+		for (let i = 0; i <= word.name.length; i++) {
+			if (i < word.name.length && word.name[i] !== "/") continue;
+			if (start < i) {
+				const slashRunStart = start;
+				let slashCount = 0;
+				while (
+					slashRunStart - slashCount - 1 >= 0 &&
+					word.name[slashRunStart - slashCount - 1] === "/"
+				)
+					slashCount++;
+				const slashIndex = slashCount === 1 ? slashRunStart - 1 : -1;
+				parts.push({
+					name: word.name.slice(start, i),
+					start,
+					end: i,
+					...(slashIndex < 0 ? {} : { slashBefore: word.chars[slashIndex] }),
+				});
+			}
+			start = i + 1;
+		}
+		if (parts.length === 0) continue;
+		if (!parts.every((p) => BARE_WORD.test(p.name))) break;
+		for (let i = 0; i < parts.length; i++) {
+			const part = parts[i] as (typeof parts)[number];
+			const leadingSlash = word.name.startsWith("/") && i === 0;
+			const trailingSlash =
+				i === parts.length - 1 &&
+				word.name.endsWith("/") &&
+				!word.name.endsWith("//")
+					? word.chars.at(-1)
+					: undefined;
+			out.push({
+				name: part.name,
+				sep:
+					out.length === 0
+						? "start"
+						: i > 0 || leadingSlash
+							? "slash"
+							: "space",
+				nameSpans: coalesceChars(word.chars.slice(part.start, part.end)),
+				...(part.slashBefore === undefined
+					? {}
+					: { slashBefore: part.slashBefore }),
+				...(trailingSlash === undefined ? {} : { slashAfter: trailingSlash }),
+			});
+		}
+	}
+	return out;
+}
+
+export function runTokens(text: string): RunToken[] {
+	return locatedRunTokens(text).map(({ name, sep }) => ({ name, sep }));
+}
+
+/**
+ * #496 — the run before a `{` already names a command, so the brace is that
+ * command's operand and not a `/menu { … }` container. `/system/script add
+ * name beep source { :beep }` is one `add` whose `source` is the body, and
+ * `/ip/route/print {1;2}` is a positional brace the device rejects (CHR
+ * 7.22.1/7.24.5 `:parse`); neither is a command followed by a menu body.
+ * `segment.ts` (H7) and `scope-brace.ts` each spelled the container rule
+ * lexically, and both ask here. The two tables are the ones `verbsplit`
+ * decides a verb with — the frozen vocabulary and the catalog's command axis —
+ * and both are floors: a run naming neither keeps the container reading
+ * (`/system script { print }`).
+ */
+export function runNamesCommand(prefix: string): boolean {
+	const names = runTokens(prefix).map((token) => token.name);
+	return (
+		names.some((name) => VERBS.has(name)) || commandVerbIndex(names) !== null
+	);
+}

package/src/explain/scope-brace.ts

@@ -7,7 +7,11 @@
  * gives comment masking, segmentation, and symbol resolution one rule.
  */
 
+import { commandVerbIndex } from "./catalog.ts";
+import { isKnownMenuPath } from "./is-known-menu.ts";
 import { scanQuotedString } from "./quoted-string.ts";
+import { runNamesCommand, runTokens } from "./run-tokens.ts";
+import { VERBS } from "./verbs.ts";
 
 /** Error-variable shape for `:onerror V { … }` — a bare/`$`-prefixed name. */
 const ERROR_VAR = /^\$?[A-Za-z][A-Za-z0-9._-]*$/;
@@ -58,8 +62,118 @@ export const DIRECTIVE_BODY: Record<string, string> = {
 	onerror: "in",
 };
 
-/** Script-valued attribute naming convention already used by the corpus census. */
-const SCRIPT_BODY_ARG = /^(?:source|script|on-.*)$/;
+/**
+ * Script-valued attribute naming convention, the corpus census's
+ * `SCRIPT_BEARING_KEY` shape (`scripts/explain-corpus-census.ts`).
+ *
+ * A shape, not a list. It decides a brace's ROLE (statement body or value) for
+ * every reader of {@link braceStartsStatements}: segmentation, the argument
+ * lexer, symbols and path resolution, as well as the `invalid-command-brace`
+ * exemption. A name inside the shape is read as a body; a name outside it as a
+ * value. The shape errs toward body because the other error is the worse one:
+ * reading a real `up-script={ :beep }` as an array hard-failed input the device
+ * accepts. The cost is the fail-open direction. An argument the command does
+ * not have, `zzz-script={ :beep }` or `on-zzz={ :beep }`, is a device
+ * `syntax error` on CHR 7.24.5 that offline does not report, because naming the
+ * command's arguments is schema. The `on-…` half of that predates #350.
+ * Which slots take a body is per-menu and per-version schema: on CHR 7.24.5
+ * `/tool/netwatch add … up-script={ :beep }` and `/ip/dhcp-server set 0
+ * lease-script={ :beep }` both parse, while 7.22.1 accepts the first and
+ * rejects the second; `comment={ :beep }` and `zzzscript={ :beep }` are
+ * `syntax error` on both (#350). The earlier `^(?:source|script|on-.*)$` missed
+ * every `…-script` argument and hard-failed the netwatch row the device accepts.
+ * The suffix keeps its hyphen, which is how RouterOS spells these names: a bare
+ * `…script` would take `:put myScript={#test}`, whose brace CHR 7.23.3 reads as
+ * an array (#245).
+ */
+const SCRIPT_BODY_ARG = /^(?:source|script|.+-script|on-.+)$/;
+
+/**
+ * An abbreviation the {@link SCRIPT_BODY_ARG} shape still pins down (#496).
+ * RouterOS takes any unique prefix of an argument name: on CHR 7.24.5 and
+ * 7.23.8, `sour { :beep }` and `s={ :beep }` lower to `source=`, `on`/`o=` to
+ * `on-event=`, and `down-scr`/`down-s=` to `down-script=`. These are the
+ * prefixes of `source` and `script`, of `on-`, and a name ending in `-` plus a
+ * prefix of `script`, so each can only abbreviate a script-valued name. Like
+ * the shape, it errs toward body: `sc { :beep }` is rejected on device and
+ * offline misses it.
+ *
+ * Abbreviating the FIRST segment (`down={ :beep }` for `down-script`, also
+ * accepted on device) stays outside the PROVEN shape. Every word is a prefix
+ * of `<word>-script`, so admitting it here would admit `comment={ :beep }` as
+ * a confident body. Telling them apart needs the command's argument list,
+ * which is schema — so a `name={` with a script-like body that reaches this
+ * far reads as a body for every reader (comments inside are comments) but is
+ * warned as a possible abbreviation instead of passing silently (#525,
+ * `args.ts` → `invalidCommandBraceOffsets`).
+ */
+const SCRIPT_BODY_ABBREVIATION =
+	/^(?:s(?:o(?:u(?:r(?:c)?)?)?)?|sc(?:r(?:i(?:p)?)?)?|on?|.+-(?:s(?:c(?:r(?:i(?:p)?)?)?)?)?)$/;
+
+/** Whether `name` is a proven script-body slot (full or pinned abbreviation). */
+export function isScriptBodyName(name: string): boolean {
+	return SCRIPT_BODY_ARG.test(name) || SCRIPT_BODY_ABBREVIATION.test(name);
+}
+
+function isAsciiLetter(char: string | undefined): boolean {
+	if (char === undefined) return false;
+	return (char >= "A" && char <= "Z") || (char >= "a" && char <= "z");
+}
+
+/**
+ * Whether the `{` at `open` holds a script-like body (#525). `end` is the
+ * exclusive brace end (or the text length when unclosed).
+ *
+ * A body opens with a directive, an absolute command, or one bare command
+ * word: `{ :beep }`, `{ /ip … }`, `{ beep }` and `{ # comment⏎:beep }` are
+ * all accepted on CHR 7.25. A bare word followed by a top-level `;` is array
+ * members, not commands — `.proplist={name;comment}` is device-rejected —
+ * so it keeps the error, as do `{1;2}`, `{"x"}`, `{}` and `$`-led values,
+ * which cannot open a command at all. The scan touches each byte between
+ * the braces once, skipping strings and `#`-to-end-of-line runs, so it is
+ * linear; it works on masked and unmasked text alike (a masked comment is
+ * already whitespace).
+ */
+export function braceBodyIsScriptLike(
+	text: string,
+	open: number,
+	end: number,
+): boolean {
+	let j = open + 1;
+	for (;;) {
+		if (j >= end) return false;
+		const c = text[j] as string;
+		if (c === " " || c === "\t" || c === "\r" || c === "\n") {
+			j++;
+			continue;
+		}
+		if (c === "#") {
+			while (j < end && text[j] !== "\n") j++;
+			continue;
+		}
+		if (c === ":" || c === "/") return true;
+		if (!isAsciiLetter(c)) return false;
+		break;
+	}
+	let depth = 0;
+	while (j < end) {
+		const c = text[j] as string;
+		if (c === '"') {
+			const scan = scanQuotedString(text, j);
+			j = Math.min(scan.end, end);
+			continue;
+		}
+		if (c === "#") {
+			while (j < end && text[j] !== "\n") j++;
+			continue;
+		}
+		if (c === "{" || c === "[" || c === "(") depth++;
+		else if ((c === "}" || c === "]" || c === ")") && depth > 0) depth--;
+		else if (c === ";" && depth === 0) return false;
+		j++;
+	}
+	return true;
+}
 
 /** Grounded scripting directives whose positional arity makes a later `#` fatal. */
 const DIRECTIVE_POSITIONAL_ARITY: Readonly<Record<string, number>> = {
@@ -75,6 +189,12 @@ interface StatementIndex {
 	boundaries: Int32Array;
 	firstContent: Int32Array;
 	lastForbidden: Int32Array;
+	/**
+	 * The innermost open delimiter at each nested `;`/newline boundary. Sparse,
+	 * because a per-offset array pushed a 540 KiB document past
+	 * `BOUNDARY_CACHE_BYTE_LIMIT` and made every probe rebuild the index.
+	 */
+	nestedSeparators: Map<number, number>;
 	matchingBrace: Map<number, number>;
 }
 
@@ -116,6 +236,7 @@ function boundaryCacheEntryBytes(text: string, index: StatementIndex): number {
 		index.boundaries.byteLength +
 		index.firstContent.byteLength +
 		index.lastForbidden.byteLength +
+		index.nestedSeparators.size * 32 +
 		index.matchingBrace.size * 32
 	);
 }
@@ -177,17 +298,34 @@ function statementIndex(text: string): StatementIndex {
 	firstContent.fill(-1);
 	const lastForbidden = new Int32Array(text.length + 1);
 	lastForbidden.fill(-1);
+	const nestedSeparators = new Map<number, number>();
 	const matchingBrace = new Map<number, number>();
 	const delimiters: { char: string; at: number }[] = [];
 	let boundary = -1;
 	let first = -1;
 	let forbidden = -1;
+	let comment = false;
 	let i = 0;
 	while (i < text.length) {
 		boundaries[i] = boundary;
 		firstContent[i] = first;
 		lastForbidden[i] = forbidden;
 		const c = text[i] as string;
+		// A statement-leading `#` runs to the line end, and a `{`, `}` or `"` in
+		// it is not structure: `/ip { # }⏎address { print {1;2} } }` is rejected
+		// at the inner `{` on CHR 7.24.5 and 7.23.8, so the `}` must not close
+		// `/ip {` (#351). Read raw, the bytes are blank, as `maskComments` makes
+		// them; read masked, they already are.
+		if (comment && c !== "\n") {
+			i++;
+			continue;
+		}
+		comment = false;
+		if (c === "#" && first === -1 && delimiters.at(-1)?.char !== "(") {
+			comment = true;
+			i++;
+			continue;
+		}
 		if (c === '"') {
 			const end = Math.min(scanQuotedString(text, i).end, text.length);
 			boundaries.fill(boundary, i + 1, end + 1);
@@ -209,6 +347,9 @@ function statementIndex(text: string): StatementIndex {
 		if (first === -1 && !isAsciiWhitespace(c)) first = i;
 		if (c === "=" || c === "[" || c === "(" || c === "$") forbidden = i;
 		if (c === "\n" || c === ";" || c === "{" || c === "[") {
+			const open = delimiters.at(-1);
+			if ((c === "\n" || c === ";") && open !== undefined)
+				nestedSeparators.set(i, open.at);
 			boundary = i;
 			first = -1;
 		}
@@ -221,6 +362,7 @@ function statementIndex(text: string): StatementIndex {
 		boundaries,
 		firstContent,
 		lastForbidden,
+		nestedSeparators,
 		matchingBrace,
 	};
 	if (cacheStatementIndex(text, index)) adoptBoundaryText(text, index);
@@ -270,6 +412,19 @@ function trailingBareScopeName(
 	text: string,
 	start: number,
 	end: number,
+): string | null {
+	const name = trailingBareArgumentName(text, start, end);
+	return name !== null && SCOPE_ARG_NAMES.has(name) ? name : null;
+}
+
+/**
+ * The bare word before a `{` when it can be an argument name: not the
+ * statement's leading word, and not a `:` directive. Lower-cased.
+ */
+function trailingBareArgumentName(
+	text: string,
+	start: number,
+	end: number,
 ): string | null {
 	let i = end - 1;
 	while (i >= start && isAsciiWhitespace(text[i])) i--;
@@ -278,7 +433,6 @@ function trailingBareScopeName(
 	const nameStart = i + 1;
 	if (nameStart === nameEnd) return null;
 	const name = text.slice(nameStart, nameEnd).toLowerCase();
-	if (!SCOPE_ARG_NAMES.has(name)) return null;
 	// A COLON makes it a directive, never an argument name, and the device is
 	// emphatic: `:if (1=1) :do { :put a }` is `expected end of command` on both
 	// 7.21.5 and 7.24.2, while the bare `:if (1=1) do { :put a }` parses. So the
@@ -404,24 +558,182 @@ export function scopeNameFromMasked(
  * Whether this brace begins a context in which statement-leading comments exist.
  *
  * `floor` bounds the lookback exactly as in {@link scopeNameFromMasked}.
+ * `unprovenName` decides the unproven `name={` guess below: `"body"` reads it
+ * as a body, `"value"` as a value. Only the script-like disjunct is gated —
+ * a proven slot stays a body either way. Readers that are themselves deciding
+ * an error AT this brace pass `"value"` where the slot cannot bear a body
+ * (`args.ts` for a root directive's slots and a `where` named comparison,
+ * `group-faults.ts` for the bracketed form), so the guess does not swallow
+ * their error; every other reader keeps `"body"`.
  */
 export function braceStartsStatements(
 	text: string,
 	open: number,
 	floor = 0,
+	unprovenName: "body" | "value" = "body",
 ): boolean {
 	if (scopeNameFromMasked(text, open, floor) !== null) return true;
 	const index = statementIndex(text);
 	const boundary = index.boundaries[open] ?? -1;
 	const start = Math.max(boundary + 1, floor);
 	const named = trailingName(text, start, open);
-	if (named !== null) return SCRIPT_BODY_ARG.test(named.toLowerCase());
+	if (named !== null) {
+		// A `name={` with a script-like body reads as a body for every
+		// reader, proven slot or not (#525): `down={ beep }` and
+		// `down={ # comment⏎:beep }` are accepted on CHR 7.25, and the `#`
+		// is only a comment when the brace bears statements. The warning
+		// that marks the unproven slot lives in `args.ts`, which checks
+		// ambiguity before this skip.
+		if (isScriptBodyName(named.toLowerCase())) return true;
+		if (unprovenName === "value") return false;
+		const close = matchingBraceEnd(text, open);
+		return braceBodyIsScriptLike(
+			text,
+			open,
+			close === undefined ? text.length : close + 1,
+		);
+	}
+	// `source { :beep }` — the same body with the `=` left out (#350). Every
+	// grounded spelling lowers to the `source=` IL on CHR 7.22.1 and 7.24.5:
+	// `/system/script add name=beep source { :beep }`, `/system/scheduler add
+	// name=x on-event { :beep }`, `/tool/netwatch add … down-script { :beep }`.
+	// The control is `comment { :beep }`, a `syntax error` on both. A
+	// declaration's operand is a variable name, not an argument, so
+	// `:local myscript {1;2}` keeps its brace an array.
+	const bare = trailingBareArgumentName(text, start, open);
+	if (bare !== null && isScriptBodyName(bare)) {
+		const head = index.firstContent[open] ?? -1;
+		const word =
+			head < start ? "" : (leadingWords(text, head, open, 1)[0] ?? "");
+		if (!/^:|^(?:local|global)$/i.test(word)) return true;
+	}
 
-	// H7's bare `{...}` and `/menu {...}` containers are statement bodies too.
+	// H7's bare `{...}` and `/menu {...}` containers are statement bodies too,
+	// but a run that already names a command makes the brace its operand (#496).
+	// `start` follows the last `{`, so each brace reads its own run: linear.
 	const first = index.firstContent[open] ?? -1;
+	if (first < start) return true;
+	if (text[first] === "/")
+		return (
+			(index.lastForbidden[open] ?? -1) < start &&
+			!runNamesCommand(text.slice(first, open))
+		);
+	return menuBlockPath(text, open, floor) !== null;
+}
+
+/** Nesting a {@link menuBlockPath} lookup follows before it abstains. */
+const MAX_MENU_BLOCK_DEPTH = 64;
+
+/**
+ * A relative run of bare path words, space- or slash-separated. Each word is
+ * `pathresolve`'s `BARE_WORD`: the resolver reads no digit-led word as a path,
+ * so admitting `6to4 {` here would flatten a block whose navigation it then
+ * ignores, resolving the body's `print` against `/interface`.
+ */
+const RELATIVE_MENU_RUN =
+	/^[A-Za-z][A-Za-z0-9._-]*(?:[ \t/]+[A-Za-z][A-Za-z0-9._-]*)*$/;
+
+/**
+ * The menu a `{` opens a statement block over, when the source alone says so
+ * (#351). Null means offline cannot tell, not that the brace is a value.
+ *
+ * On CHR 7.24.5 and 7.23.8 a brace right after a menu word is always a
+ * statement block, at any depth and whatever the body holds:
+ * `/ip { address { 1;2 } }` is `bad command name 1` at the `1`, and
+ * `/ip { address { a;b } }` reads `a` as `add`. A brace after a command word is
+ * always an error at the `{` (`/ip { address { print {1;2} } }`). The `/`-led
+ * spelling was already read as a block; the RELATIVE one (`address {` inside
+ * `/ip { … }`) was read as `/ip address` with a brace operand. That is what
+ * hard-failed the outer brace at depth three and hid every fault in the body.
+ *
+ * A relative run is a block only when the menu it names is known: the
+ * enclosing container's path, read the same way outward, plus the run, named by
+ * a shipped structure table. A miss abstains, so an unknown word keeps today's
+ * reading and the resolver says `unresolved`. The path is lexical: a
+ * navigation statement earlier in the same body (`/ip { firewall; address {`)
+ * is not followed, and the resolver checks the flattened run against the real
+ * context, so that residue can only abstain. Abbreviated menus (`addr {`) are
+ * not expanded, as R13 does not expand them.
+ *
+ * `floor` keeps the ranged-call contract of {@link scopeNameFromMasked}: no
+ * enclosing brace before it is consulted, so a range reads exactly as the same
+ * text taken alone.
+ */
+export function menuBlockPath(
+	text: string,
+	open: number,
+	floor = 0,
+): readonly string[] | null {
+	return blockPathAt(text, statementIndex(text), open, floor, 0);
+}
+
+function blockPathAt(
+	text: string,
+	index: StatementIndex,
+	open: number,
+	floor: number,
+	depth: number,
+): readonly string[] | null {
+	if (depth > MAX_MENU_BLOCK_DEPTH) return null;
+	const start = Math.max((index.boundaries[open] ?? -1) + 1, floor);
+	const first = index.firstContent[open] ?? -1;
+	if (first < start) return enclosingBlockPath(text, index, open, floor, depth);
+	if ((index.lastForbidden[open] ?? -1) >= start) return null;
+	const run = text.slice(first, open);
+	if (text[first] === "/") {
+		if (runNamesCommand(run)) return null;
+		return runTokens(run).map((token) => token.name);
+	}
+	const trimmed = run.trim();
+	if (!RELATIVE_MENU_RUN.test(trimmed)) return null;
+	const names = trimmed.split(/[\s/]+/);
+	if (names.some((name) => VERBS.has(name))) return null;
+	const parent = enclosingBlockPath(text, index, open, floor, depth);
+	if (parent === null) return null;
+	const path = [...parent, ...names];
+	if (commandVerbIndex(path) !== null || !isKnownMenuPath(path)) return null;
+	return path;
+}
+
+/**
+ * The path of the container `{` around the statement that holds `at`, when it
+ * is one. The statement starts after a boundary: an opening `{`/`[` is the
+ * enclosing delimiter itself, and a separator records it.
+ */
+function enclosingBlockPath(
+	text: string,
+	index: StatementIndex,
+	at: number,
+	floor: number,
+	depth: number,
+): readonly string[] | null {
+	const boundary = index.boundaries[at] ?? -1;
+	const outer =
+		boundary < 0 || text[boundary] === "{" || text[boundary] === "["
+			? boundary
+			: (index.nestedSeparators.get(boundary) ?? -1);
+	if (outer < floor || text[outer] !== "{") return null;
+	return blockPathAt(text, index, outer, floor, depth + 1);
+}
+
+/**
+ * Whether the `#` at `at` opens a comment line inside an array literal (#503).
+ *
+ * `frame` is the innermost open delimiter. CHR 7.24.5 and 7.22.1 agree: inside
+ * a `{…}` that is not a statement body, a `#` at column 0 comments out the
+ * rest of its line, at any nesting depth and in argument values too
+ * (`:local z {a=1;⏎# c⏎b=2}` → `value=a=1;b=2`, `:foreach i in={1;⏎# c⏎2}`).
+ * An indented `#` (space or tab), a `#` after a value or `;` on the same line,
+ * and a `#` directly inside `( … )` are still syntax errors. A comment-only
+ * array is rejected, but so is `{}`: that is the empty-array rule, not this one.
+ */
+export function startsArrayCommentLine(
+	text: string,
+	at: number,
+	frame: { char: string; statements: boolean } | undefined,
+): boolean {
 	return (
-		first < start ||
-		(text[first] === "/" && (index.lastForbidden[open] ?? -1) < start)
+		text[at - 1] === "\n" && frame?.char === "{" && frame.statements === false
 	);
 }