@tikoci/centrs 0.1.4 → 0.1.6

package/src/explain/quoted-string.ts

@@ -9,7 +9,7 @@
 import { type Defect, defectAt } from "./defects.ts";
 
 /** Analyzer resource bound, not a RouterOS grammar limit. */
-const MAX_STRING_FRAME_DEPTH = 256;
+export const MAX_STRING_FRAME_DEPTH = 256;
 
 /** Where a double-quoted string ends, and whether it was closed at all. */
 export interface QuotedStringScan {
@@ -18,6 +18,13 @@ export interface QuotedStringScan {
 	closed: boolean;
 }
 
+type InterpolationEnd = (
+	text: string,
+	open: number,
+	limit: number,
+	frameDepth: number,
+) => number;
+
 /**
  * Valid single-char escapes after `\` inside a RouterOS string.
  *
@@ -97,7 +104,7 @@ function escapeLength(text: string, at: number): 2 | 3 {
 // ---------------------------------------------------------------------------
 // Single source of truth for the frame grammar (#253).
 //
-// Both `scanQuotedString` and `collectStringEscapeDefects` walk the same
+// Both `scanQuotedString` and `walkStringEscapes` walk the same
 // nesting: a `"` frame is string phase, anything else is code phase where
 // `$[`/`$(` inside a string push a bracket frame and brackets nest until
 // matched. The helpers below own the transitions, the depth guard, and the
@@ -117,8 +124,9 @@ function stepFrame(
 	i: number,
 	frames: string[],
 	onStringEscape: (at: number) => number | Defect,
+	maxFrameDepth: number = MAX_STRING_FRAME_DEPTH,
 ): number | Defect {
-	if (frames.length > MAX_STRING_FRAME_DEPTH) return 0;
+	if (frames.length > maxFrameDepth) return 0;
 	const top = frames[frames.length - 1] as string | undefined;
 	const c = text[i] as string;
 	if (top === '"') {
@@ -186,33 +194,98 @@ function stringEscapeValidated(text: string, at: number): number | Defect {
  *
  * A `$[…]` or `$(…)` substitution inside a string is code and may contain
  * nested strings, so the next quote is not necessarily the outer close.
+ *
+ * `limit` is the end of the region the caller is reading, defaulting to the
+ * whole text. A reader working on a RANGE of a larger document must pass it:
+ * a string left unterminated inside the range would otherwise be closed by a
+ * quote belonging to later text, which is not the answer the same reader gets
+ * from the range taken as a string of its own (#322). Lookahead past `limit`
+ * cannot change the result — every advance that reads ahead is at least one
+ * byte, so it can only overshoot an end that is reported clamped either way.
  */
-export function scanQuotedString(text: string, open: number): QuotedStringScan {
+export function scanQuotedString(
+	text: string,
+	open: number,
+	limit: number = text.length,
+	interpolationEnd?: InterpolationEnd,
+	maxFrameDepth: number = MAX_STRING_FRAME_DEPTH,
+): QuotedStringScan {
+	if (maxFrameDepth < 1) return { end: limit, closed: false };
 	const frames: string[] = ['"'];
 	let i = open + 1;
-	while (i < text.length) {
-		const res = stepFrame(text, i, frames, (at) => stringEscapeSkip(text, at));
+	while (i < limit) {
+		if (
+			frames.at(-1) === '"' &&
+			text[i] === "$" &&
+			text[i + 1] === "[" &&
+			interpolationEnd !== undefined
+		) {
+			const end = interpolationEnd(text, i + 1, limit, frames.length);
+			if (end >= limit) return { end: limit, closed: false };
+			i = end + 1;
+			continue;
+		}
+		const res = stepFrame(
+			text,
+			i,
+			frames,
+			(at) => stringEscapeSkip(text, at),
+			maxFrameDepth,
+		);
 		if (typeof res !== "number") break;
 		if (res === 0) break;
 		i += res;
 		if (frames.length === 0) return { end: i, closed: true };
 	}
-	return { end: text.length, closed: false };
+	return { end: limit, closed: false };
+}
+
+/** One string-internal escape: `[start, end)` over the `\` and what it escapes. */
+export interface StringEscapeSpan {
+	start: number;
+	end: number;
 }
 
 /**
- * Collect the first invalid string-internal escape in `text`, if any.
+ * What one document-wide escape walk found: the valid escapes, and the first
+ * invalid one if the walk hit one.
+ */
+export interface StringEscapeWalk {
+	/** Valid escapes in document order, up to (not including) the first invalid one. */
+	escapes: StringEscapeSpan[];
+	/** At most one defect, at the first invalid escape. */
+	defects: Defect[];
+}
+
+/**
+ * Walk every string-internal escape in `text`, once.
  *
- * Walks the entire document with the same frame model as `scanQuotedString`,
- * but validates each `\` inside a string frame against the documented escape
- * table (capital hex, truncated, unknown). Returns an array with at most one
- * defect at the first invalid escape. Comment spans are skipped: a `"` inside
- * a comment is not a string.
+ * Same frame model as `scanQuotedString`, validating each `\` inside a string
+ * frame against the documented escape table (capital hex, truncated, unknown).
+ * Comment spans are skipped: a `"` inside a comment is not a string.
+ *
+ * The walk yields BOTH answers because they are the same reading (#264): a
+ * valid escape becomes an `escaped` token and an invalid one becomes a
+ * `bad-string-escape` diagnostic, and deriving them from two walks would let
+ * the token stream and the diagnostics disagree about which bytes are an
+ * escape. It stops at the first invalid escape, so the escapes list is the
+ * prefix the validator actually vouched for — past a malformed escape the
+ * string boundaries themselves are in doubt, and painting `escaped` there
+ * would be a claim this walk cannot support.
+ *
+ * `collectEscapes: false` validates without retaining the valid spans. The
+ * default `explainCommand` path consumes only `defects`, and materializing a
+ * span per escape for a caller that never asked for `data.tokens` is the kind
+ * of cost #313/#317/#320 were about — work nobody requested. Validation is identical
+ * either way — only the retention differs, so the two callers cannot diverge
+ * on what counts as an escape.
  */
-export function collectStringEscapeDefects(
+export function walkStringEscapes(
 	text: string,
 	comments: readonly { start: number; end: number }[] = [],
-): Defect[] {
+	collectEscapes = true,
+): StringEscapeWalk {
+	const escapes: StringEscapeSpan[] = [];
 	const frames: string[] = [];
 	let i = 0;
 	let ci = 0;
@@ -230,12 +303,29 @@ export function collectStringEscapeDefects(
 				continue;
 			}
 		}
-		const res = stepFrame(text, i, frames, (at) =>
-			stringEscapeValidated(text, at),
-		);
-		if (typeof res !== "number") return [res];
+		const res = stepFrame(text, i, frames, (at) => {
+			const step = stringEscapeValidated(text, at);
+			if (collectEscapes && typeof step === "number")
+				escapes.push({ start: at, end: at + step });
+			return step;
+		});
+		if (typeof res !== "number") return { escapes, defects: [res] };
 		if (res === 0) break;
 		i += res;
 	}
-	return [];
+	return { escapes, defects: [] };
+}
+
+/**
+ * Collect the first invalid string-internal escape in `text`, if any.
+ *
+ * The defect half of {@link walkStringEscapes}, retaining no escape spans.
+ * Callers that also need the valid escapes should call the walk directly
+ * rather than walking twice.
+ */
+export function collectStringEscapeDefects(
+	text: string,
+	comments: readonly { start: number; end: number }[] = [],
+): Defect[] {
+	return walkStringEscapes(text, comments, false).defects;
 }

package/src/explain/scope-brace.ts

@@ -75,15 +75,39 @@ 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 without retaining anything outside the bounded cache.
+// 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.
@@ -91,11 +115,21 @@ function boundaryCacheEntryBytes(text: string, index: StatementIndex): number {
 		text.length * 2 +
 		index.boundaries.byteLength +
 		index.firstContent.byteLength +
-		index.lastForbidden.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;
 
@@ -119,12 +153,21 @@ function cacheStatementIndex(text: string, index: StatementIndex): boolean {
 
 /** Statement-boundary and prefix facts for every source offset, in one pass. */
 function statementIndex(text: string): StatementIndex {
-	if (recentBoundaryText === text && recentBoundaryIndex !== undefined)
-		return recentBoundaryIndex;
+	if (recentBoundaryText === text && recentBoundaryIndex !== undefined) {
+		const hit = recentBoundaryIndex;
+		adoptBoundaryText(text, hit);
+		return hit;
+	}
 	const cached = boundaryCache.get(text);
 	if (cached !== undefined) {
-		recentBoundaryText = text;
-		recentBoundaryIndex = cached;
+		// 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;
 	}
 
@@ -134,6 +177,8 @@ function statementIndex(text: string): StatementIndex {
 	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;
@@ -153,6 +198,14 @@ function statementIndex(text: string): StatementIndex {
 			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 === "[") {
@@ -164,15 +217,78 @@ function statementIndex(text: string): StatementIndex {
 	boundaries[text.length] = boundary;
 	firstContent[text.length] = first;
 	lastForbidden[text.length] = forbidden;
-
-	const index = { boundaries, firstContent, lastForbidden };
-	if (cacheStatementIndex(text, index)) {
-		recentBoundaryText = text;
-		recentBoundaryIndex = index;
-	}
+	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--;
@@ -220,13 +336,34 @@ function leadingWords(
 	return words;
 }
 
-/** Scope name for an already comment-masked source view. */
+/**
+ * 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 = (index.boundaries[open] ?? -1) + 1;
+	const start = Math.max((index.boundaries[open] ?? -1) + 1, floor);
 	const named = trailingName(masked, start, open);
 	if (named !== null) {
 		const name = named.toLowerCase();
@@ -242,6 +379,11 @@ export function scopeNameFromMasked(
 		}
 		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.
@@ -258,12 +400,20 @@ export function scopeNameFromMasked(
 	return null;
 }
 
-/** Whether this brace begins a context in which statement-leading comments exist. */
-export function braceStartsStatements(text: string, open: number): boolean {
-	if (scopeNameFromMasked(text, open) !== null) return true;
+/**
+ * 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 = boundary + 1;
+	const start = Math.max(boundary + 1, floor);
 	const named = trailingName(text, start, open);
 	if (named !== null) return SCRIPT_BODY_ARG.test(named.toLowerCase());
 
@@ -288,16 +438,19 @@ export function hashStartsHardError(
 	text: string,
 	at: number,
 	inExpression: boolean,
+	floor = 0,
 ): boolean {
 	if (inExpression) return true;
-	if (at <= 0 || !isAsciiWhitespace(text[at - 1])) return false;
+	if (at <= floor || !isAsciiWhitespace(text[at - 1])) return false;
 
 	let previous = at - 1;
-	while (previous >= 0 && isAsciiWhitespace(text[previous])) previous--;
-	if (text[previous] === "}") return true;
+	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 = (index.boundaries[at] ?? -1) + 1;
+	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();