@tikoci/centrs 0.1.4 → 0.1.7

package/src/explain/verbsplit.ts

@@ -60,6 +60,18 @@
  * its precedence over the punctuation guess, and the two places it deliberately
  * does not apply. `splitRun` is again untouched — both tables are consumed here.
  *
+ * **The other direction closes too (#324).** R9 kept `pathresolve` from
+ * claiming navigation where a verb was decided; the symmetric rule keeps
+ * `resolveVerb` from claiming a verb where the whole run names a known MENU
+ * and the segment it would promote is not in `VERBS`. `splitRun`'s punctuation
+ * fallback used to read `/ip/firewall/address-list name=ytkids` as verb
+ * `address-list` at `/ip/firewall` — a verb assembled from a path segment, on
+ * a statement whose verb is simply missing. It degrades to `ambiguous`. Priced
+ * on the frozen partition: 10 of 17,212 statements flip, every one of them a
+ * fabrication withdrawn (`commands/explain/README.md` → The menu path with
+ * arguments). Both tables stay floors — presence narrows, absence decides
+ * nothing.
+ *
  * Like `blocks.ts`, this ships only the boundary primitives. Argument parsing
  * (`k=v` / `?query` after the verb) belongs to the phase-1 canonical assembly,
  * not to the Q6 question. `resolveVerb(text, context)` takes the enclosing menu
@@ -67,7 +79,7 @@
  * resolver's context-certainty contract (#192).
  */
 
-import { scopeBodies } from "./blocks.ts";
+import { scopeBlocksIn } from "./blocks.ts";
 import { commandVerbIndex } from "./catalog.ts";
 import type { Defect } from "./defects.ts";
 import { isKnownMenuPath } from "./is-known-menu.ts";
@@ -76,6 +88,12 @@ import {
 	type Span,
 	type StatementAnalysis,
 } from "./pathresolve.ts";
+import {
+	documentRange,
+	type MaskedRange,
+	nestedRange,
+	rangeAt,
+} from "./segment.ts";
 import { SUBMENU_DIRECTIVES, VERBS } from "./verbs.ts";
 
 const BARE_WORD = /^[A-Za-z][A-Za-z0-9._-]*$/;
@@ -135,8 +153,14 @@ interface Word {
  * offset from a name is therefore wrong on continued statements, and
  * {@link describeStatement} only ever publishes the run's END.
  */
-function asciiWordSpans(text: string): Word[] {
-	const out: Word[] = [];
+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) {
@@ -152,6 +176,7 @@ function asciiWordSpans(text: string): Word[] {
 			continue;
 		}
 		if (isAsciiWhitespace(c)) {
+			if (current !== null) yield current;
 			current = null;
 			i++;
 			continue;
@@ -163,7 +188,6 @@ function asciiWordSpans(text: string): Word[] {
 				end: i + 1,
 				chars: [{ start: i, end: i + 1 }],
 			};
-			out.push(current);
 		} else {
 			current.name += c;
 			current.end = i + 1;
@@ -171,7 +195,7 @@ function asciiWordSpans(text: string): Word[] {
 		}
 		i++;
 	}
-	return out;
+	if (current !== null) yield current;
 }
 
 /**
@@ -284,14 +308,25 @@ export function runTokens(text: string): RunToken[] {
 }
 
 /** True when the statement is a scripting directive (`:x`, or a bare `x do={…}`). */
-export function isDirective(text: string): boolean {
+export function isDirective(text: string, range?: MaskedRange): boolean {
 	const t = trimAscii(text);
 	if (t.startsWith(":")) return true;
-	return !t.startsWith("/") && scopeBodies(t).length > 0;
+	if (t.startsWith("/")) return false;
+	const start = text.length - trimAsciiStart(text).length;
+	return (
+		scopeBlocksIn(
+			range === undefined
+				? documentRange(t)
+				: nestedRange(range, start, start + t.length),
+		).length > 0
+	);
 }
 
 /** Everything the boundary rule needs from one statement's text. */
-export function describeStatement(text: string): {
+export function describeStatement(
+	text: string,
+	range?: MaskedRange,
+): {
 	run: RunToken[];
 	directive: boolean;
 	whole: boolean;
@@ -331,20 +366,30 @@ export function describeStatement(text: string): {
 	// V4 — did the run consume every whitespace-separated word? A slash-joined
 	// word expands to several run tokens, so compare against the SOURCE words the
 	// run covers, not the run length.
-	const words = asciiWordSpans(body);
 	let covered = 0;
+	let words = 0;
 	let index = 0;
+	// A word the run cannot take is proof there is one more word than the run
+	// covered, which is the whole of V4's question — so the walk stops there
+	// instead of counting the rest of the statement.
+	let everyWordCovered = true;
 	const runEnds: (number | null)[] = run.map(() => null);
-	for (const word of words) {
+	for (const word of asciiWordSpans(body)) {
+		words++;
 		const parts = word.name.split("/").filter((p) => p.length > 0);
 		if (parts.length === 0) continue;
-		if (index + parts.length > run.length) break;
+		if (index + parts.length > run.length) {
+			everyWordCovered = false;
+			break;
+		}
 		if (
 			!parts.every(
 				(p, i) => (run[index + i] as RunToken | undefined)?.name === p,
 			)
-		)
+		) {
+			everyWordCovered = false;
 			break;
+		}
 		// Only the word's LAST part ends where the word does; an earlier part is
 		// followed by more path inside the same word.
 		runEnds[index + parts.length - 1] = base + word.end;
@@ -353,8 +398,8 @@ export function describeStatement(text: string): {
 	}
 	return {
 		run,
-		directive: isDirective(text),
-		whole: covered === words.length && run.length > 0,
+		directive: isDirective(text, range),
+		whole: everyWordCovered && covered === words && run.length > 0,
 		runEnds,
 	};
 }
@@ -586,6 +631,25 @@ function unknownSplit(why: string): VerbSplitRefusal {
 	};
 }
 
+/**
+ * What follows the leading run: an operand stream, a brace body, or unknown.
+ *
+ * Only the tail's FIRST byte is read, and only three answers come out of it, so
+ * this stays a shape test rather than a second parser. `"body"` is the `{` of a
+ * menu container or a scope block; `"argument"` is anything else that is there;
+ * `"none"` is a run with nothing after it (V4's bare path) or a tail whose
+ * offset `describeStatement` could not establish.
+ */
+function operandTail(
+	text: string,
+	runEnd: number | null,
+): "argument" | "body" | "none" {
+	if (runEnd === null) return "none";
+	const tail = trimAsciiStart(text.slice(runEnd));
+	if (tail.length === 0) return "none";
+	return tail.startsWith("{") ? "body" : "argument";
+}
+
 /**
  * Resolve one statement's verb/menu boundary, applying the enclosing menu
  * `context`. Mirrors `pathresolve`'s base rule: a `:`/bare directive and an
@@ -593,12 +657,16 @@ function unknownSplit(why: string): VerbSplitRefusal {
  * `context`. Substitution-headed and variable-segment statements are `unknown`
  * — offline refuses rather than guessing (the Q3/Q4/Q14 fail-closed floor).
  */
-export function resolveVerb(text: string, context: string): VerbSplit {
+export function resolveVerb(
+	text: string,
+	context: string,
+	range?: MaskedRange,
+): VerbSplit {
 	const t = trimAscii(text);
 	if (t.startsWith("$") || t.startsWith("[") || t.startsWith("("))
 		return unknownSplit("dynamic or substitution-headed statement");
 
-	const { run, directive, whole, runEnds } = describeStatement(text);
+	const { run, directive, whole, runEnds } = describeStatement(text, range);
 	if (run.length === 0) return unknownSplit("no leading path token");
 
 	// `directive` already folds in the bare-directive case (`isDirective`), so it
@@ -657,6 +725,58 @@ export function resolveVerb(text: string, context: string): VerbSplit {
 					ambiguous: false,
 					why: `published command \`${candidates[catalogAt]}\``,
 				};
+	// #324 — the symmetric half of R9. R9 made `pathresolve`'s `menuNavPath`
+	// consult `VERBS` so it could not claim navigation where a verb was decided;
+	// this stops the punctuation rule claiming a verb where the run names a
+	// known MENU and the token it would promote is not a console verb.
+	// `/ip/firewall/address-list name=ytkids` has no verb in it: the punctuation
+	// rule's "no space token, arguments follow — last segment" fallback promotes
+	// `address-list`, and the spaced spelling `/ip firewall address-list name=x`
+	// promotes `firewall`, one level higher still. Both premises are available
+	// offline and both say no, so the reading is a fabrication rather than a
+	// guess with a basis.
+	//
+	// Only the fail-closed direction: PRESENCE in the tables decides, absence
+	// decides nothing, so an unlisted menu spelled `…/address-list` keeps
+	// today's reading. The vocabulary hit is excluded by the `VERBS` test itself
+	// (a vocabulary split promotes a `VERBS` member by construction), the
+	// published-command axis by `catalogAt` — first-order evidence about that
+	// exact path outranks a container listing of its prefix — and directives by
+	// R10, which is measured.
+	//
+	// This abstains, it does not reject: offline knows it cannot name a verb
+	// here, which needs no device evidence. Whether RouterOS refuses the shape
+	// outright is a device claim and is deliberately not made (contrast #311's
+	// `error`, which is CHR-grounded).
+	//
+	// One shape is excluded by the tail rather than by a table: a `{` after the
+	// run is a menu CONTAINER body (`/system {identity print}`, H7), where the
+	// run legitimately names a menu and no verb is missing at all.
+	// `invalidCommandBraceDiagnostics` reads that statement's `argsAt` to find
+	// the brace, so abstaining here would drop a real `error` on the statement
+	// after it. A tail this cannot see (`runEnds` null) is not classified, and
+	// the guard stands down there too.
+	if (
+		!directive &&
+		catalogAt === null &&
+		!split.ambiguous &&
+		split.verbAt !== null &&
+		!VERBS.has((run[split.verbAt] as RunToken).name) &&
+		operandTail(text, runEnds[run.length - 1] ?? null) === "argument"
+	) {
+		const full = candidates[candidates.length - 1] as string;
+		if (isKnownMenuPath(full.split("/").filter(Boolean)))
+			return {
+				resolution: "ambiguous",
+				kind: null,
+				path: null,
+				verb: null,
+				verbAt: null,
+				argsAt: null,
+				candidates,
+				why: `\`${full}\` is a known RouterOS menu and \`${(run[split.verbAt] as RunToken).name}\` is not a console verb: this run names a menu and the verb is missing, so offline will not promote a path segment to one`,
+			};
+	}
 	if (split.ambiguous) {
 		// V4's bare path, the one case `proposed` refuses — and the one the baked
 		// container table can answer (#210). The lookup reads the LAST candidate,
@@ -791,19 +911,41 @@ export interface VerbAnalysis {
  * pair this array with `segmentStatements` by index.
  */
 export function resolveVerbs(text: string): VerbAnalysis {
-	return resolveVerbsFromStatements(resolveStatements(text));
+	const analysis = resolveStatements(text);
+	return resolveVerbsFromStatements(
+		analysis,
+		analysis.defects.some((d) => d.code === "bom" || d.code === "non-ascii")
+			? undefined
+			: documentRange(text, true),
+	);
 }
 
-/** Reuse an existing Q4 walk when a composed analysis already performed it. */
-export function resolveVerbsFromStatements({
-	statements,
-	defects,
-}: StatementAnalysis): VerbAnalysis {
+/**
+ * Reuse an existing Q4 walk when a composed analysis already performed it.
+ * `range`, if supplied, belongs to the same ASCII document as the analysis;
+ * statement spans are absolute document offsets, even within a partial range.
+ */
+export function resolveVerbsFromStatements(
+	{ statements, defects }: StatementAnalysis,
+	range?: MaskedRange,
+): VerbAnalysis {
 	return {
 		splits: statements.map((s) => ({
 			...(s.unresolved
 				? unknownSplit(s.unresolved)
-				: resolveVerb(s.text, s.context)),
+				: resolveVerb(
+						s.text,
+						s.context,
+						// The caller supplies a range only for ASCII input; widened
+						// fallback spans must still match the statement's own text.
+						range !== undefined &&
+							s.span.start >= range.start &&
+							s.span.end <= range.end &&
+							s.text.length === s.span.end - s.span.start &&
+							range.text.slice(s.span.start, s.span.end) === s.text
+							? rangeAt(range, s.span.start, s.span.end)
+							: undefined,
+					)),
 			span: s.span,
 			text: s.text,
 			contextCertain: s.contextCertain,

package/src/explain/write.ts

@@ -93,11 +93,13 @@ import { type Defect, hasStructuralDefect, mergeDefects } from "./defects.ts";
 import { isMenuPath } from "./menus.ts";
 import {
 	type DocumentAnalysis,
+	rangeForResolution,
 	resolveDocument,
 	resolveStatements,
 	type StatementAnalysis,
 	type StatementResolution,
 } from "./pathresolve.ts";
+import { documentRange, type MaskedRange, rangeAt } from "./segment.ts";
 import {
 	catalogVerbAt,
 	describeStatement,
@@ -603,12 +605,29 @@ function catalogVerbOf(
  * consumes this only as a rollup, so it cannot repeat that failure.
  */
 export function occurrences(text: string): Occurrence[] {
-	return collect(resolveStatements(text), resolveDocument(text));
+	const statements = resolveStatements(text);
+	return collect(
+		statements,
+		resolveDocument(text),
+		sourceRange(text, statements),
+	);
+}
+
+function sourceRange(
+	text: string,
+	analysis: StatementAnalysis,
+): MaskedRange | undefined {
+	return analysis.defects.some(
+		(d) => d.code === "bom" || d.code === "non-ascii",
+	)
+		? undefined
+		: documentRange(text, true);
 }
 
 function collect(
 	statements: StatementAnalysis,
 	brackets: DocumentAnalysis,
+	range?: MaskedRange,
 ): Occurrence[] {
 	const out: Occurrence[] = [];
 	const list = statements.statements;
@@ -627,7 +646,21 @@ function collect(
 		if (t.length === 0) continue;
 		// One parse per statement, threaded through every rule below: the Q6
 		// boundary reads the same run three or four times otherwise.
-		const described = describeStatement(t);
+		const trimStart = statement.text.length - statement.text.trimStart().length;
+		const described = describeStatement(
+			t,
+			range !== undefined &&
+				statement.span.start >= range.start &&
+				statement.span.end <= range.end &&
+				range.text.slice(statement.span.start, statement.span.end) ===
+					statement.text
+				? rangeAt(
+						range,
+						statement.span.start + trimStart,
+						statement.span.start + trimStart + t.length,
+					)
+				: undefined,
+		);
 		const catalogAt = catalogVerbOf(t, described, statement.context);
 		if (isDynamicForm(t, described)) {
 			out.push({
@@ -676,7 +709,8 @@ function collect(
 	for (const bracket of brackets.resolutions) {
 		const inner = bracket.inner.trim();
 		if (inner.length === 0) continue;
-		const described = describeStatement(inner);
+		const bracketRange = rangeForResolution(bracket) ?? documentRange(inner);
+		const described = describeStatement(inner, bracketRange);
 		if (isDynamicForm(inner, described)) {
 			out.push({
 				kind: "bracket",
@@ -774,18 +808,25 @@ export function containsWrite(text: string): WriteAnalysis {
 	// One resolution pass each for the statement walk (Q4) and the bracket walk
 	// (Q3); both are re-entrant over the same segmentation and neither is cheap
 	// on adversarial input, so they are not re-run for the defects.
+	const statements = resolveStatements(text);
 	return containsWriteFromAnalyses(
-		resolveStatements(text),
+		statements,
 		resolveDocument(text),
+		sourceRange(text, statements),
 	);
 }
 
-/** Reuse the Q3/Q4 walks when a composed analysis already performed them. */
+/**
+ * Reuse the Q3/Q4 walks when a composed analysis already performed them.
+ * `range`, if supplied, belongs to the same ASCII document as the analyses;
+ * statements outside that range keep their standalone reading.
+ */
 export function containsWriteFromAnalyses(
 	statements: StatementAnalysis,
 	brackets: DocumentAnalysis,
+	range?: MaskedRange,
 ): WriteAnalysis {
-	const found = collect(statements, brackets);
+	const found = collect(statements, brackets, range);
 	const defects = mergeDefects(statements.defects, brackets.defects);
 	const writes = found.filter((o) => o.klass === "write").length;
 	const blockers = found.filter((o) => BLOCKING.has(o.klass));