@tikoci/centrs 0.1.3 → 0.1.6

package/src/explain/scope-brace.ts

@@ -0,0 +1,461 @@
+/**
+ * Source-visible brace roles shared by the explain walkers.
+ *
+ * RouterOS does not make every `{` a statement body. `do={...}` and stored
+ * script attributes do, while `name={...}` is ordinarily an array literal.
+ * Keeping this decision below `segment.ts` avoids a cycle with `blocks.ts` and
+ * gives comment masking, segmentation, and symbol resolution one rule.
+ */
+
+import { scanQuotedString } from "./quoted-string.ts";
+
+/** Error-variable shape for `:onerror V { … }` — a bare/`$`-prefixed name. */
+const ERROR_VAR = /^\$?[A-Za-z][A-Za-z0-9._-]*$/;
+
+function isAsciiWhitespace(char: string | undefined): boolean {
+	return char === " " || char === "\t" || char === "\r" || char === "\n";
+}
+
+/**
+ * Source-visible argument names whose `{…}` is a scope. Closed set, harvested
+ * from every projected corpus capture (`do` 5623, `else` 720, `command` 177,
+ * `on-error` 132).
+ *
+ * `command` is here because users DO write it explicitly:
+ * `:retry delay=1s max=3 on-error={…} command={…}`
+ * (topic-169237/post-0021-snippet-01 @ 7.22.1).
+ *
+ * `in` is deliberately NOT here even though IL lowers `:onerror V { … }` under
+ * that name — in SOURCE, `in={…}` is always an array literal
+ * (`:foreach Type in={ "p12"; "pem" }` → `in=p12;pem`,
+ * eworm/check-certificates.rsc @ 7.22.1). The IL name and the source name
+ * collide; only the source spelling governs offline.
+ */
+export const SCOPE_ARG_NAMES: ReadonlySet<string> = new Set([
+	"do",
+	"else",
+	"on-error",
+	"command",
+]);
+
+/** Argument names that are scopes only under a specific head directive. */
+export const HEAD_SCOPED_ARG_NAMES: Record<string, ReadonlySet<string>> = {
+	in: new Set([":onerror", "onerror"]),
+};
+
+/**
+ * Directives whose brace body attaches to the directive itself, with the IL
+ * name the body is lowered under. The colon is optional in practice: `do {`
+ * opens a body the same way `:do {` does (topic-142687/post-0010-snippet-01 @
+ * 7.22.1).
+ */
+export const DIRECTIVE_BODY: Record<string, string> = {
+	":do": "command",
+	":retry": "command",
+	":onerror": "in",
+	do: "command",
+	retry: "command",
+	onerror: "in",
+};
+
+/** Script-valued attribute naming convention already used by the corpus census. */
+const SCRIPT_BODY_ARG = /^(?:source|script|on-.*)$/;
+
+/** Grounded scripting directives whose positional arity makes a later `#` fatal. */
+const DIRECTIVE_POSITIONAL_ARITY: Readonly<Record<string, number>> = {
+	local: 2,
+	global: 2,
+	set: 2,
+	put: 1,
+};
+
+const BOUNDARY_CACHE_LIMIT = 4;
+const BOUNDARY_CACHE_BYTE_LIMIT = 8 * 1024 * 1024;
+interface StatementIndex {
+	boundaries: Int32Array;
+	firstContent: Int32Array;
+	lastForbidden: Int32Array;
+	matchingBrace: Map<number, number>;
+}
+
+const boundaryCache = new Map<string, StatementIndex>();
+let boundaryCacheBytes = 0;
+// Most probes in one walk ask about the same document. Bypass Map's string-key
+// lookup for that hot path. The slot holds ONE string reference, which may be a
+// content-equal twin of a cache key rather than the key itself (see
+// `adoptBoundaryText`), so retention is the bounded cache plus that one string.
+let recentBoundaryText: string | undefined;
+let recentBoundaryIndex: StatementIndex | undefined;
+
+/**
+ * Adopt `text` as the single-slot key.
+ *
+ * A walk asks about several string objects with IDENTICAL content — the
+ * `analyzed` surface, the raw input, and a comment mask with nothing to mask
+ * are equal strings built by different steps. JavaScript cannot compare string
+ * identity, so `recentBoundaryText === text` across two such objects is a full
+ * content comparison: measured at 10 us per hit on a 64 KiB document versus
+ * 0.01 us when the slot already holds that object. Leaving the slot pointing at
+ * the first object made every later probe pay that comparison — a per-call cost
+ * that grows with the document, which is the shape #313 saw as superlinear
+ * growth through the public entry. Adopting the object on a hit pays it once.
+ *
+ * Sound because the index is a pure function of content: an index built for one
+ * string describes every string equal to it.
+ */
+function adoptBoundaryText(text: string, index: StatementIndex): void {
+	recentBoundaryText = text;
+	recentBoundaryIndex = index;
+}
+
+function boundaryCacheEntryBytes(text: string, index: StatementIndex): number {
+	// JavaScript strings use at most two bytes per UTF-16 code unit. Include the
+	// key as well as the typed array so unusually large sources cannot be retained.
+	return (
+		text.length * 2 +
+		index.boundaries.byteLength +
+		index.firstContent.byteLength +
+		index.lastForbidden.byteLength +
+		index.matchingBrace.size * 32
+	);
+}
+
+/** Whether one statement index fits the bounded cache's per-entry ceiling. */
+export function canRetainStatementIndex(text: string): boolean {
+	return (
+		text.length * 2 + (text.length + 1) * Int32Array.BYTES_PER_ELEMENT * 3 <=
+		BOUNDARY_CACHE_BYTE_LIMIT
+	);
+}
+
+function cacheStatementIndex(text: string, index: StatementIndex): boolean {
+	if (!canRetainStatementIndex(text)) return false;
+	const entryBytes = boundaryCacheEntryBytes(text, index);
+	if (entryBytes > BOUNDARY_CACHE_BYTE_LIMIT) return false;
+
+	while (
+		boundaryCache.size >= BOUNDARY_CACHE_LIMIT ||
+		boundaryCacheBytes + entryBytes > BOUNDARY_CACHE_BYTE_LIMIT
+	) {
+		const oldest = boundaryCache.entries().next().value;
+		if (oldest === undefined) break;
+		boundaryCache.delete(oldest[0]);
+		boundaryCacheBytes -= boundaryCacheEntryBytes(oldest[0], oldest[1]);
+		if (recentBoundaryText === oldest[0]) {
+			recentBoundaryText = undefined;
+			recentBoundaryIndex = undefined;
+		}
+	}
+	boundaryCache.set(text, index);
+	boundaryCacheBytes += entryBytes;
+	return true;
+}
+
+/** Statement-boundary and prefix facts for every source offset, in one pass. */
+function statementIndex(text: string): StatementIndex {
+	if (recentBoundaryText === text && recentBoundaryIndex !== undefined) {
+		const hit = recentBoundaryIndex;
+		adoptBoundaryText(text, hit);
+		return hit;
+	}
+	const cached = boundaryCache.get(text);
+	if (cached !== undefined) {
+		// Move to the most-recent end. Eviction walks the Map in INSERTION order,
+		// so without this the cache is FIFO: the document-wide index every ranged
+		// reader shares is re-read constantly but never re-inserted, and a stream
+		// of one-off statement indices ages it out and makes the next reader
+		// rebuild it over the whole document (#322).
+		boundaryCache.delete(text);
+		boundaryCache.set(text, cached);
+		adoptBoundaryText(text, cached);
+		return cached;
+	}
+
+	const boundaries = new Int32Array(text.length + 1);
+	boundaries.fill(-1);
+	const firstContent = new Int32Array(text.length + 1);
+	firstContent.fill(-1);
+	const lastForbidden = new Int32Array(text.length + 1);
+	lastForbidden.fill(-1);
+	const matchingBrace = new Map<number, number>();
+	const delimiters: { char: string; at: number }[] = [];
+	let boundary = -1;
+	let first = -1;
+	let forbidden = -1;
+	let i = 0;
+	while (i < text.length) {
+		boundaries[i] = boundary;
+		firstContent[i] = first;
+		lastForbidden[i] = forbidden;
+		const c = text[i] as string;
+		if (c === '"') {
+			const end = Math.min(scanQuotedString(text, i).end, text.length);
+			boundaries.fill(boundary, i + 1, end + 1);
+			firstContent.fill(first === -1 ? i : first, i + 1, end + 1);
+			lastForbidden.fill(i, i + 1, end + 1);
+			if (first === -1) first = i;
+			forbidden = i;
+			i = end;
+			continue;
+		}
+		if (c === "{" || c === "[" || c === "(") {
+			delimiters.push({ char: c, at: i });
+		} else if (c === "}" || c === "]" || c === ")") {
+			const want = c === "}" ? "{" : c === "]" ? "[" : "(";
+			const delimiter = delimiters.pop();
+			if (delimiter?.char === want && c === "}")
+				matchingBrace.set(delimiter.at, i);
+		}
+		if (first === -1 && !isAsciiWhitespace(c)) first = i;
+		if (c === "=" || c === "[" || c === "(" || c === "$") forbidden = i;
+		if (c === "\n" || c === ";" || c === "{" || c === "[") {
+			boundary = i;
+			first = -1;
+		}
+		i++;
+	}
+	boundaries[text.length] = boundary;
+	firstContent[text.length] = first;
+	lastForbidden[text.length] = forbidden;
+	const index = {
+		boundaries,
+		firstContent,
+		lastForbidden,
+		matchingBrace,
+	};
+	if (cacheStatementIndex(text, index)) adoptBoundaryText(text, index);
+	return index;
+}
+
+/** Closing `}` paired with `open`, outside strings/comments, when one exists. */
+export function matchingBraceEnd(
+	text: string,
+	open: number,
+): number | undefined {
+	return statementIndex(text).matchingBrace.get(open);
+}
+
+/**
+ * Whether the index itself starts a fresh statement at `start`.
+ *
+ * Most readers index a comment mask, but segmentation must retain the raw
+ * comments. A quote in an earlier comment can make that raw index skip a real
+ * body opener as string content. Such a body must build its own local index:
+ * clamping lookback alone cannot restore boundaries the outer index skipped.
+ */
+export function isIndexedStatementStart(text: string, start: number): boolean {
+	return start === 0 || statementIndex(text).boundaries[start] === start - 1;
+}
+
+/**
+ * The bare scope-slot word before a `{`, when the `=` is simply omitted (#347).
+ *
+ * The device settles this: `:if (1=1) do={…} else={…}`,
+ * `:if (1=1) do={…} else {…}` and `:if (1=1) do {…} else {…}` all lower to
+ * BYTE-IDENTICAL IL (`…;do=;(evl …);else=;(evl …)`) on 7.21.5, 7.23.5, 7.24.2
+ * and 7.25beta3, with `:if (1=1) do={…} elsy {…}` rejected on all four as the
+ * control. The `=` is optional punctuation, not part of the slot.
+ *
+ * Deliberately narrower than {@link trailingName} in two ways, because a bare
+ * word is far weaker evidence than `name=`:
+ *
+ *   - the word must already be a {@link SCOPE_ARG_NAMES} member, so a positional
+ *     never becomes a slot — `:local z {1;2}` keeps `z` a positional and its
+ *     brace an array;
+ *   - it may not be the statement's own leading directive. `:do {` reads its
+ *     body through {@link DIRECTIVE_BODY} (as `command`, the IL name), and
+ *     letting the head word match here would rename that slot to `do`.
+ */
+function trailingBareScopeName(
+	text: string,
+	start: number,
+	end: number,
+): string | null {
+	let i = end - 1;
+	while (i >= start && isAsciiWhitespace(text[i])) i--;
+	const nameEnd = i + 1;
+	while (i >= start && /[A-Za-z0-9.-]/.test(text[i] as string)) i--;
+	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
+	// colon form is refused here and left to the `DIRECTIVE_BODY` branch below,
+	// which is what legitimately reads a statement-head `:do { … }`.
+	if (text[nameStart - 1] === ":") return null;
+	if (leadingWords(text, start, nameStart, 1).length === 0) return null;
+	return name;
+}
+
+function trailingName(text: string, start: number, end: number): string | null {
+	let i = end - 1;
+	while (i >= start && isAsciiWhitespace(text[i])) i--;
+	if (text[i] !== "=") return null;
+	i--;
+	const nameEnd = i + 1;
+	while (i >= start && /[A-Za-z0-9.-]/.test(text[i] as string)) i--;
+	let nameStart = i + 1;
+	while (nameStart < nameEnd && !/[A-Za-z]/.test(text[nameStart] as string))
+		nameStart++;
+	if (nameStart === nameEnd || !/[A-Za-z]/.test(text[nameStart] as string))
+		return null;
+	return text.slice(nameStart, nameEnd);
+}
+
+function leadingWords(
+	text: string,
+	start: number,
+	end: number,
+	limit: number,
+	removeContinuations = false,
+): string[] {
+	const words: string[] = [];
+	let word = "";
+	for (let i = start; i < end && words.length < limit; i++) {
+		if (
+			removeContinuations &&
+			text[i] === "\\" &&
+			(text[i + 1] === "\n" || (text[i + 1] === "\r" && text[i + 2] === "\n"))
+		) {
+			i += text[i + 1] === "\r" ? 2 : 1;
+			continue;
+		}
+		const c = text[i] as string;
+		if (isAsciiWhitespace(c)) {
+			if (word.length > 0) {
+				words.push(word);
+				word = "";
+			}
+		} else {
+			word += c;
+		}
+	}
+	if (word.length > 0 && words.length < limit) words.push(word);
+	return words;
+}
+
+/**
+ * Scope name for an already comment-masked source view.
+ *
+ * `floor` is the start of the region the caller is reading, defaulting to the
+ * whole view. Clamping the statement start to it makes an answer read off a
+ * RANGE of a document identical to the same answer read off that range taken as
+ * a string of its own: a fresh call cannot see before index 0, so a ranged call
+ * must not see before `floor` (#322).
+ *
+ * It is a guard, not a correction. The clamp does fire on ordinary input —
+ * 7,448 times over the 948-script corpus, where a region begins somewhere the
+ * preceding boundary character does not — but removing it leaves every one of
+ * those 948 results byte-identical, because the extra bytes a wider lookback
+ * sees do not spell a scope name. What it buys is that the equality holds by
+ * CONSTRUCTION rather than by a property of where today's ranges happen to
+ * start, which is what the next reader to take a range will rely on.
+ *
+ * Nothing else needs clamping — `firstContent` and `lastForbidden` are only
+ * ever compared against `start`, so a value from before the floor is already
+ * excluded by being less than it.
+ */
+export function scopeNameFromMasked(
+	masked: string,
+	open: number,
+	floor = 0,
+): string | null {
+	const index = statementIndex(masked);
+	const start = Math.max((index.boundaries[open] ?? -1) + 1, floor);
+	const named = trailingName(masked, start, open);
+	if (named !== null) {
+		const name = named.toLowerCase();
+		if (SCOPE_ARG_NAMES.has(name)) return name;
+		const heads = HEAD_SCOPED_ARG_NAMES[name];
+		if (heads !== undefined) {
+			const first = index.firstContent[open] ?? -1;
+			const head =
+				first < start
+					? ""
+					: (leadingWords(masked, first, open, 1)[0] ?? "").toLowerCase();
+			return heads.has(head) ? name : null;
+		}
+		return null;
+	}
+	// `else {` / `do {` / `on-error {` — the same slot with the `=` left off.
+	// Checked before the directive-body branch so the ARGUMENT reading wins over
+	// the head reading for a word that can be either.
+	const bare = trailingBareScopeName(masked, start, open);
+	if (bare !== null) return bare;
+	// `:do {`, `:retry {`, `:onerror Err {` — the directive may carry ONE bare
+	// error-variable word before the brace. A second token that is not an
+	// identifier (`:onerror [find] {`) is not this form, so the brace is a value.
+	const firstContentOffset = index.firstContent[open] ?? -1;
+	const words =
+		firstContentOffset < start
+			? []
+			: leadingWords(masked, firstContentOffset, open, 3);
+	const firstWord = (words[0] ?? "").toLowerCase();
+	const body = DIRECTIVE_BODY[firstWord];
+	if (body === undefined) return null;
+	if (words.length === 1) return body;
+	if (words.length === 2 && ERROR_VAR.test(words[1] as string)) return body;
+	return null;
+}
+
+/**
+ * Whether this brace begins a context in which statement-leading comments exist.
+ *
+ * `floor` bounds the lookback exactly as in {@link scopeNameFromMasked}.
+ */
+export function braceStartsStatements(
+	text: string,
+	open: number,
+	floor = 0,
+): 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());
+
+	// H7's bare `{...}` and `/menu {...}` containers are statement bodies too.
+	const first = index.firstContent[open] ?? -1;
+	return (
+		first < start ||
+		(text[first] === "/" && (index.lastForbidden[open] ?? -1) < start)
+	);
+}
+
+/**
+ * Whether an unquoted, non-comment `#` is a device hard error (#245).
+ *
+ * `inExpression` is the caller's already-known delimiter role: arrays and
+ * parenthesized expressions reject every unquoted hash. Outside them, a hash
+ * joined to a value (`comment=a#b`) stays content. A whitespace-led hash is
+ * rejected only where CHR proves the statement has already consumed the fixed
+ * positional operands of a scripting directive, or after a closing scope.
+ */
+export function hashStartsHardError(
+	text: string,
+	at: number,
+	inExpression: boolean,
+	floor = 0,
+): boolean {
+	if (inExpression) return true;
+	if (at <= floor || !isAsciiWhitespace(text[at - 1])) return false;
+
+	let previous = at - 1;
+	while (previous >= floor && isAsciiWhitespace(text[previous])) previous--;
+	// The `}` must be inside the region: a fresh call on the region alone runs
+	// off index 0 and finds nothing, so a ranged call must stop at `floor`.
+	if (previous >= floor && text[previous] === "}") return true;
+
+	const index = statementIndex(text);
+	const start = Math.max((index.boundaries[at] ?? -1) + 1, floor);
+	const first = index.firstContent[at] ?? -1;
+	const words = first < start ? [] : leadingWords(text, first, at, 3, true);
+	const rawHead = (words[0] ?? "").toLowerCase();
+	if (!rawHead.startsWith(":") && !rawHead.startsWith("/")) return false;
+	const head = rawHead.slice(1);
+	const arity = DIRECTIVE_POSITIONAL_ARITY[head];
+	return arity !== undefined && words.length - 1 >= arity;
+}