@tikoci/centrs 0.1.2 → 0.1.4

package/src/explain/string-tokens.ts

@@ -0,0 +1,67 @@
+/**
+ * B3 string fill — claims quoted-string spans on the residual.
+ *
+ * Every RouterOS double-quoted string is a lexical unit the device highlights
+ * (even when its value is not a literal, the delimiters are). `data.values`
+ * already claims argument value strings (quotes included), so this fill runs
+ * **after** `value` and sees only the residual: quoted declaration names
+ * (`:global "set-dns"`), quoted variable references (`$"set-dns"`), and
+ * string content inside substitutions that value anchoring did not locate.
+ *
+ * All quoted runs are produced by the single shared scanner
+ * `src/explain/quoted-string.ts` (`scanQuotedString`), the same primitive the
+ * segmenter and symbol resolver use, so boundaries cannot drift.
+ *
+ * Vocabulary is provisional until #264 B5: one `string` class for every quoted
+ * run (delimiters included), regardless of whether the string is a literal
+ * value, a name, or code. Whether escapes or interpolations later deserve a
+ * distinct class is B5 and does not move byte coverage.
+ */
+
+import type { ExplainToken } from "../explain.ts";
+import { scanQuotedString } from "./quoted-string.ts";
+import { clipToResidual } from "./token-ranges.ts";
+
+/** Quoted-string spans on the residual. */
+export function stringSpans(
+	analyzed: string,
+	residual: readonly { start: number; end: number }[],
+): ExplainToken[] {
+	const len = analyzed.length;
+	if (len === 0 || residual.length === 0) return [];
+	const raw: { start: number; end: number }[] = [];
+	for (let i = 0; i < analyzed.length; i++) {
+		if (analyzed[i] !== '"') continue;
+		// Earlier fills own semantic regions. In particular, a quote inside a
+		// comment must not open a string that paints later statements when that
+		// comment has no matching quote. A real residual string always has its
+		// opening delimiter on the residual; already-owned strings need no fill.
+		if (clipToResidual(i, i + 1, residual).length === 0) continue;
+		const scan = scanQuotedString(analyzed, i);
+		if (!scan.closed) {
+			// Unterminated strings are already a defect; claim from opener to
+			// end so the residual does not stay gap-filled as unclassified
+			// while the diagnostic says the same bytes are defective.
+			raw.push({ start: i, end: analyzed.length });
+			break;
+		}
+		raw.push({ start: i, end: scan.end });
+		i = scan.end - 1;
+	}
+	if (raw.length === 0) return [];
+	const out: ExplainToken[] = [];
+	for (const { start, end } of raw) {
+		if (!Number.isInteger(start) || !Number.isInteger(end)) continue;
+		if (start < 0 || end <= start || end > len) continue;
+		for (const r of clipToResidual(start, end, residual)) {
+			out.push({
+				start: r.start,
+				end: r.end,
+				class: "string" as const,
+				ev: "e13",
+			});
+		}
+	}
+	out.sort((a, b) => a.start - b.start || a.end - b.end);
+	return out;
+}

package/src/explain/symbol-values.ts

@@ -0,0 +1,520 @@
+/**
+ * Flow-sensitive symbol → value-facts for `explain` (#239 S2).
+ *
+ * S1 surfaced `data.symbols` as the semantic Q13 projection: name/span/class/
+ * role/bindingIds per occurrence. S2 connects those occurrences to
+ * `data.values` occurrences without executing user code.
+ *
+ * - A declaration/binding/assignment with a literal RHS gets a `valueId` that
+ *   points at the `ExplainValueOccurrence` that spells it. No RHS evaluation:
+ *   `$x`, `[...]` or an expression yields no `valueId` and later references
+ *   become `unknown` for that binding.
+ * - A reference gets the *reaching* literal ids at that program point. Linear
+ *   code is last-write-wins; a branch merge becomes a set; a loop merge or a
+ *   non-literal assignment becomes `unknown`. This is deliberately
+ *   conservative and schema-free — the same branch that would need a schema to
+ *   decide `variable-undefined` is the one that forces a set here.
+ *
+ * The analysis never runs user input (`runtimeAcceptance` stays `not-proven`).
+ * It reuses the same statement splits and value anchors the diagnostic/value
+ * surfaces already gate on, so a def never points outside its own statement.
+ */
+
+import type {
+	ExplainSymbolOccurrence,
+	ExplainValueOccurrence,
+} from "../explain.ts";
+import { scopeBlocks } from "./blocks.ts";
+import type { SymbolOccurrence } from "./symbols.ts";
+import type { DocumentVerbSplit } from "./verbsplit.ts";
+
+interface BlockInfo {
+	start: number;
+	end: number;
+	isLoop: boolean;
+	branchGroup?: number;
+	branchArm?: "do" | "else";
+}
+
+type BindingState = {
+	valueIds: Set<string>;
+	unknown: boolean;
+};
+
+function cloneStateMap(
+	source: Map<string, BindingState>,
+): Map<string, BindingState> {
+	const out = new Map<string, BindingState>();
+	for (const [k, v] of source)
+		out.set(k, { valueIds: new Set(v.valueIds), unknown: v.unknown });
+	return out;
+}
+
+function setsEqual(a: Set<string>, b: Set<string>): boolean {
+	if (a.size !== b.size) return false;
+	for (const v of a) if (!b.has(v)) return false;
+	return true;
+}
+
+function mergeExhaustiveBranches(
+	left: Map<string, BindingState>,
+	right: Map<string, BindingState>,
+): Map<string, BindingState> {
+	const merged = new Map<string, BindingState>();
+	const allIds = new Set<string>([...left.keys(), ...right.keys()]);
+	for (const id of allIds) {
+		const a = left.get(id);
+		const b = right.get(id);
+		if (a === undefined || b === undefined) {
+			const present = a ?? b;
+			if (present !== undefined)
+				merged.set(id, {
+					valueIds: new Set(present.valueIds),
+					unknown: true,
+				});
+			continue;
+		}
+		merged.set(id, {
+			valueIds: new Set([...a.valueIds, ...b.valueIds]),
+			unknown: a.unknown || b.unknown,
+		});
+	}
+	return merged;
+}
+
+/**
+ * Collect all scope blocks in `text`, rebased to `base`, recursively.
+ *
+ * `splits` are the flattened statement splits for the same document; they are
+ * used to decide whether a `do={...}` body belongs to a loop verb (`foreach`,
+ * `for`, `while`) or to a branch (`if`, `do`, `else`, `on-error`).
+ */
+function collectBlocks(
+	text: string,
+	base: number,
+	analyzed: string,
+	splits: readonly DocumentVerbSplit[],
+): BlockInfo[] {
+	const out: BlockInfo[] = [];
+	const blocks = scopeBlocks(text).map((block) => {
+		const start = base + block.start;
+		const bracePos = start - 1;
+		const ownerIndex = owningSplitIndex(
+			analyzed,
+			splits,
+			bracePos,
+			bracePos + 1,
+		);
+		return {
+			block,
+			ownerIndex,
+			owner: ownerIndex === undefined ? undefined : splits[ownerIndex],
+		};
+	});
+	const exhaustiveGroups = new Set<number>();
+	for (const candidate of blocks) {
+		if (candidate.ownerIndex === undefined) continue;
+		if (candidate.owner?.verb?.toLowerCase() !== "if") continue;
+		const siblings = blocks.filter(
+			(other) => other.ownerIndex === candidate.ownerIndex,
+		);
+		const doBlocks = siblings.filter(
+			(other) => other.block.name.toLowerCase() === "do",
+		);
+		const elseBlocks = siblings.filter(
+			(other) => other.block.name.toLowerCase() === "else",
+		);
+		if (
+			doBlocks.length === 1 &&
+			elseBlocks.length === 1 &&
+			(doBlocks[0]?.block.start ?? Number.POSITIVE_INFINITY) <
+				(elseBlocks[0]?.block.start ?? Number.NEGATIVE_INFINITY)
+		)
+			exhaustiveGroups.add(candidate.ownerIndex);
+	}
+
+	for (const { block: b, ownerIndex, owner } of blocks) {
+		const start = base + b.start;
+		const end = start + b.body.length;
+		// If source mapping cannot identify the owning statement, use loop-like
+		// merging: an incomplete reaching set is safer than treating an unknown
+		// repeated body as a one-shot branch. Otherwise the resolved verb, not a
+		// nearby word or string, decides loop semantics.
+		const isLoop =
+			owner === undefined ||
+			(owner.verb !== null &&
+				["foreach", "for", "while"].includes(owner.verb.toLowerCase()));
+		const arm = b.name.toLowerCase();
+		const branchArm = arm === "do" || arm === "else" ? arm : undefined;
+		out.push({
+			start,
+			end,
+			isLoop,
+			...(ownerIndex !== undefined &&
+			exhaustiveGroups.has(ownerIndex) &&
+			branchArm !== undefined
+				? { branchGroup: ownerIndex, branchArm }
+				: {}),
+		});
+		out.push(...collectBlocks(b.body, start, analyzed, splits));
+	}
+	return out;
+}
+
+/**
+ * Find the literal value that a defining occurrence establishes, if any.
+ *
+ * The declaration's RHS is the first *positional* value anchor in the same
+ * statement whose start is after the symbol's end. Attribute values (`name=`)
+ * and `element` members are not considered — `:foreach i in={...}` must not
+ * link `i` to the `in` attribute. Only the same statement's values are
+ * candidates, which also prevents cross-statement mis-linking.
+ */
+function owningSplitIndex(
+	analyzed: string,
+	splits: readonly DocumentVerbSplit[],
+	start: number,
+	end: number,
+): number | undefined {
+	let owner: number | undefined;
+	let ownerLength = Number.POSITIVE_INFINITY;
+	for (let i = 0; i < splits.length; i++) {
+		const split = splits[i] as DocumentVerbSplit;
+		if (split.span.start > start || end > split.span.end) continue;
+		// A widened fallback span cannot prove statement ownership. Match the
+		// same addressability gate used by `valuesOf`/`argumentsOf`.
+		if (analyzed.slice(split.span.start, split.span.end) !== split.text)
+			continue;
+		const length = split.span.end - split.span.start;
+		if (length < ownerLength) {
+			owner = i;
+			ownerLength = length;
+		}
+	}
+	return owner;
+}
+
+function defValueId(
+	occurrence: SymbolOccurrence,
+	splitIndex: number | undefined,
+	values: readonly ExplainValueOccurrence[],
+	valueSplitIndexes: readonly (number | undefined)[],
+): string | undefined {
+	if (
+		occurrence.role !== "declaration" &&
+		occurrence.role !== "binding" &&
+		occurrence.role !== "assignment"
+	)
+		return undefined;
+	if (occurrence.bindingIds.length === 0) return undefined;
+	// Only locals/globals have a literal RHS that is a positional value.
+	// `auto` (loop var) is initialized by the loop machinery, not by a
+	// literal in the same statement, so skip it.
+	if (occurrence.cls !== "local" && occurrence.cls !== "global")
+		return undefined;
+
+	if (splitIndex === undefined) return undefined;
+
+	let best: ExplainValueOccurrence | undefined;
+	let bestDist = Number.POSITIVE_INFINITY;
+	for (let i = 0; i < values.length; i++) {
+		const value = values[i] as ExplainValueOccurrence;
+		// Parent statement spans include their scope bodies. Requiring the
+		// innermost addressable statement to match prevents `:local f do={:put
+		// 1}` from claiming the body's `1`, and prevents one branch from lending
+		// a literal to a non-literal definition in another branch.
+		if (valueSplitIndexes[i] !== splitIndex) continue;
+		if (value.kind === "element") continue;
+		if (value.span.start <= occurrence.start) continue;
+		// RouterOS declaration/assignment RHS syntax is positional. Attribute
+		// values in the same statement belong to the directive, not this symbol.
+		if (value.kind !== "positional") continue;
+		const dist = value.span.start - occurrence.end;
+		if (dist < 0 || dist >= bestDist) continue;
+		bestDist = dist;
+		best = value;
+	}
+	return best?.id;
+}
+
+/**
+ * Augment the existing symbol/value surfaces with flow-sensitive refs.
+ *
+ * Returns new `ExplainSymbolOccurrence` rows that carry `valueId` on
+ * definitions and `reachingValueIds`/`reachingUnknown` on references. The
+ * underlying `SymbolOccurrence`/`ExplainValueOccurrence` inputs are not
+ * mutated.
+ */
+export function augmentSymbolOccurrences(
+	analyzed: string,
+	symbols: readonly SymbolOccurrence[],
+	values: readonly ExplainValueOccurrence[],
+	splits: readonly DocumentVerbSplit[],
+): ExplainSymbolOccurrence[] {
+	const augmented: ExplainSymbolOccurrence[] = [];
+	const symbolSplitIndexes = symbols.map((occ) =>
+		owningSplitIndex(analyzed, splits, occ.start, occ.end),
+	);
+	const valueSplitIndexes = values.map((value) =>
+		owningSplitIndex(analyzed, splits, value.span.start, value.span.end),
+	);
+	const valueOrder = new Map(values.map((value, index) => [value.id, index]));
+	// Map from occurrence index -> valueId for quick lookup during flow pass
+	const defMap = new Map<number, string>();
+	for (let i = 0; i < symbols.length; i++) {
+		const occ = symbols[i] as SymbolOccurrence;
+		const vid = defValueId(
+			occ,
+			symbolSplitIndexes[i],
+			values,
+			valueSplitIndexes,
+		);
+		if (vid !== undefined) defMap.set(i, vid);
+	}
+
+	const blocks = collectBlocks(analyzed, 0, analyzed, splits);
+	type FlowEvent =
+		| {
+				offset: number;
+				type: "enter" | "exit";
+				isLoop: boolean;
+				branchGroup?: number;
+				branchArm?: "do" | "else";
+		  }
+		| { offset: number; type: "unknown-definition"; bindingIds: string[] };
+	const events: FlowEvent[] = [];
+	for (const b of blocks) {
+		const branch =
+			b.branchGroup === undefined || b.branchArm === undefined
+				? {}
+				: { branchGroup: b.branchGroup, branchArm: b.branchArm };
+		events.push({
+			offset: b.start,
+			type: "enter",
+			isLoop: b.isLoop,
+			...branch,
+		});
+		events.push({
+			offset: b.end,
+			type: "exit",
+			isLoop: b.isLoop,
+			...branch,
+		});
+	}
+	const deferredDefinitions = new Set<number>();
+	for (let i = 0; i < symbols.length; i++) {
+		const occ = symbols[i] as SymbolOccurrence;
+		if (defMap.has(i) || occ.bindingIds.length === 0) continue;
+		if (
+			occ.role !== "declaration" &&
+			occ.role !== "binding" &&
+			occ.role !== "assignment"
+		)
+			continue;
+		const splitIndex = symbolSplitIndexes[i];
+		if (splitIndex === undefined) continue;
+		deferredDefinitions.add(i);
+		events.push({
+			offset: (splits[splitIndex] as DocumentVerbSplit).span.end,
+			type: "unknown-definition",
+			bindingIds: [...occ.bindingIds],
+		});
+	}
+	events.sort((a, b) => {
+		if (a.offset !== b.offset) return a.offset - b.offset;
+		// Enter the block first, then apply a statement-final definition, then
+		// exit/merge the block. This keeps a definition ending at a block edge
+		// inside that block's final state.
+		const priority = { enter: 0, "unknown-definition": 1, exit: 2 } as const;
+		return priority[a.type] - priority[b.type];
+	});
+
+	// Occurrences are already sorted by start
+	const ordered = symbols.map((occ, index) => ({ occ, index }));
+	// Flow state
+	let current = new Map<string, BindingState>();
+	const stack: {
+		snapshot: Map<string, BindingState>;
+		isLoop: boolean;
+		branchGroup?: number;
+		branchArm?: "do" | "else";
+	}[] = [];
+	const branchGroups = new Map<
+		number,
+		{ doFinal: Map<string, BindingState> }
+	>();
+	let eventIdx = 0;
+	const processEventsUpTo = (pos: number): void => {
+		while (eventIdx < events.length) {
+			const ev = events[eventIdx] as FlowEvent;
+			if (ev.offset > pos) break;
+			eventIdx++;
+			if (ev.type === "unknown-definition") {
+				for (const bid of ev.bindingIds)
+					current.set(bid, { valueIds: new Set(), unknown: true });
+				continue;
+			}
+			if (ev.type === "enter") {
+				stack.push({
+					snapshot: cloneStateMap(current),
+					isLoop: ev.isLoop,
+					...(ev.branchGroup === undefined || ev.branchArm === undefined
+						? {}
+						: { branchGroup: ev.branchGroup, branchArm: ev.branchArm }),
+				});
+			} else {
+				const top = stack.pop();
+				if (top === undefined) continue;
+				const snapshot = top.snapshot;
+				const isLoop = top.isLoop;
+				if (top.branchGroup !== undefined && top.branchArm === "do") {
+					branchGroups.set(top.branchGroup, {
+						doFinal: cloneStateMap(current),
+					});
+					current = cloneStateMap(snapshot);
+					continue;
+				}
+				if (top.branchGroup !== undefined && top.branchArm === "else") {
+					const group = branchGroups.get(top.branchGroup);
+					if (group !== undefined) {
+						current = mergeExhaustiveBranches(group.doFinal, current);
+						branchGroups.delete(top.branchGroup);
+						continue;
+					}
+				}
+				const merged = cloneStateMap(snapshot);
+				const allIds = new Set<string>([...snapshot.keys(), ...current.keys()]);
+				for (const id of allIds) {
+					const snap = snapshot.get(id);
+					const cur = current.get(id);
+					if (snap === undefined && cur !== undefined) {
+						// Defined inside block only — after block it may not have run
+						merged.set(id, {
+							valueIds: new Set(cur.valueIds),
+							unknown: true,
+						});
+					} else if (snap !== undefined && cur !== undefined) {
+						const equal =
+							!snap.unknown &&
+							!cur.unknown &&
+							setsEqual(snap.valueIds, cur.valueIds);
+						if (!equal) {
+							const union = new Set<string>([
+								...snap.valueIds,
+								...cur.valueIds,
+							]);
+							const unknown = snap.unknown || cur.unknown || isLoop;
+							merged.set(id, { valueIds: union, unknown });
+						} else if (snap.unknown || cur.unknown) {
+							merged.set(id, {
+								valueIds: new Set(snap.valueIds),
+								unknown: true,
+							});
+						}
+					}
+				}
+				// Loops make every variable assigned inside unknown after exit,
+				// even if the pre/post sets happen to match (e.g. same literal)
+				if (isLoop) {
+					for (const id of current.keys()) {
+						const snap = snapshot.get(id);
+						const cur = current.get(id);
+						if (cur === undefined) continue;
+						if (snap === undefined) {
+							const m = merged.get(id);
+							if (m !== undefined) m.unknown = true;
+						} else if (!setsEqual(snap.valueIds, cur.valueIds)) {
+							const m = merged.get(id);
+							if (m !== undefined) m.unknown = true;
+						}
+					}
+				}
+				current = merged;
+			}
+		}
+	};
+
+	for (const { occ, index } of ordered) {
+		processEventsUpTo(occ.start);
+		const ev = "e7" as const;
+		const base: ExplainSymbolOccurrence = {
+			name: occ.name,
+			span: { start: occ.start, end: occ.end },
+			class: occ.cls === "undefined" ? null : occ.cls,
+			role: occ.role as ExplainSymbolOccurrence["role"],
+			bindingIds: [...occ.bindingIds],
+			sigil: occ.sigil,
+			...(occ.note === undefined ? {} : { note: occ.note }),
+			ev,
+		} as ExplainSymbolOccurrence;
+
+		const vid = defMap.get(index);
+		if (vid !== undefined) {
+			(base as { valueId?: string }).valueId = vid;
+			// Update flow state for this binding
+			for (const bid of occ.bindingIds) {
+				current.set(bid, { valueIds: new Set([vid]), unknown: false });
+			}
+		} else if (
+			occ.role === "declaration" ||
+			occ.role === "binding" ||
+			occ.role === "assignment"
+		) {
+			// Defining occurrence with no literal RHS — introduces unknown
+			if (occ.bindingIds.length > 0 && !deferredDefinitions.has(index)) {
+				for (const bid of occ.bindingIds) {
+					current.set(bid, { valueIds: new Set(), unknown: true });
+				}
+			}
+		} else if (occ.role === "reference" || occ.role === "field") {
+			if (occ.bindingIds.length > 0) {
+				// Union across multiple bindingIds (e.g. :onerror)
+				const unionIds = new Set<string>();
+				let unknown = false;
+				let anyDefined = false;
+				for (const bid of occ.bindingIds) {
+					const state = current.get(bid);
+					if (state !== undefined) {
+						anyDefined = true;
+						for (const v of state.valueIds) unionIds.add(v);
+						if (state.unknown) unknown = true;
+					} else {
+						// No prior definition for this binding — reaching is unknown
+						// (closure or pre-declaration reference)
+						unknown = true;
+					}
+				}
+				// For a single binding with no prior assignment yet but a
+				// visible declaration later? Q13's lookup already ensures we only
+				// query after declaration, so undefined here is truly unknown.
+				if (!anyDefined) unknown = true;
+				const ids = [...unionIds].sort(
+					(a, b) =>
+						(valueOrder.get(a) ?? Number.POSITIVE_INFINITY) -
+						(valueOrder.get(b) ?? Number.POSITIVE_INFINITY),
+				);
+				(
+					base as {
+						reachingValueIds?: string[];
+						reachingUnknown?: boolean;
+					}
+				).reachingValueIds = ids;
+				(base as { reachingUnknown?: boolean }).reachingUnknown = unknown
+					? true
+					: undefined;
+				// Only emit reachingValueIds when we have a concrete set or unknown;
+				// for parameter refs (no bindingIds) we omit.
+				// Normalize: keep empty array when unknown with no ids.
+				if (ids.length === 0 && !unknown) {
+					delete (base as { reachingValueIds?: string[] }).reachingValueIds;
+					delete (base as { reachingUnknown?: boolean }).reachingUnknown;
+				}
+			}
+		}
+		augmented.push(base);
+	}
+	// Process trailing block exits after last occurrence
+	processEventsUpTo(analyzed.length);
+
+	return augmented;
+}