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

package/src/execute.ts

@@ -27,6 +27,7 @@ import { buildTip, notReachedReason } from "./core/envelope.ts";
 import {
 	type CanonicalExecuteCommand,
 	canonicalizeExecuteCommand,
+	isBareMenuPathCommand,
 	isWriteShaped,
 } from "./core/execute-command.ts";
 import { sentWriteWarnings } from "./core/fanout.ts";
@@ -40,6 +41,7 @@ import {
 	SYNTAX_REJECTED_REMEDIATION,
 	serializeCentrsError,
 } from "./errors.ts";
+import { countExecutableStatements } from "./explain/segment.ts";
 import {
 	assertOfflineSyntax,
 	isOfflineGateRejection,
@@ -162,6 +164,7 @@ export type ExecuteErrorEnvelope = CentrsErrorEnvelope<ExecuteOperationMeta>;
 export {
 	type CanonicalExecuteCommand,
 	canonicalizeExecuteCommand,
+	isBareMenuPathCommand,
 	isWriteShaped,
 };
 
@@ -608,6 +611,22 @@ export function buildExecuteErrorEnvelope(
 	};
 }
 
+/**
+ * Whether the dispatch carried more than one statement (#549). Mirrors
+ * `runCommand`: the consoles run the raw CLI text whatever the canonical mode,
+ * while REST/native run structured input as one path-POST/talk sentence — a
+ * `;` inside a structured value never separates there, so the refusal means
+ * nothing ran. Executed control scopes count too: `:if … do={ A; B }` applies
+ * A before a refused B, while stored bodies never run at dispatch.
+ */
+function isMultiStatementDispatch(resolved: ResolvedExecuteRequest): boolean {
+	const runsRawText =
+		resolved.via.value === "mac-telnet" ||
+		resolved.via.value === "ssh" ||
+		resolved.canonical.mode === "script";
+	return runsRawText && countExecutableStatements(resolved.command) > 1;
+}
+
 export function buildExecuteErrorEnvelopeFromResolved(
 	resolved: ResolvedExecuteRequest,
 	error: unknown,
@@ -633,6 +652,7 @@ export function buildExecuteErrorEnvelopeFromResolved(
 				isWriteShaped(resolved.canonical),
 				centrsError,
 				trace,
+				isMultiStatementDispatch(resolved),
 			),
 		],
 		tips: resolvedExecuteTips(resolved),
@@ -664,20 +684,15 @@ function failedValidationMeta(
 	}
 	const deviceSource = deviceStageSource(resolved);
 	const structured = resolved.canonical.mode === "structured";
-	// A flat summary is present only when its check gave a verdict (GH#435).
-	// Script-shaped input has no semantic half at all: `not-applicable`. For
-	// structured input, a syntax rejection means the name-level check was
-	// never asked, so `semantic` is left out rather than reported `false`.
-	const semanticNotReached = structured
-		? {}
-		: { semantic: "not-applicable" as const };
+	// A flat summary is present only when a stage gave that verdict (#535). A
+	// syntax rejection means the name-level check was never asked, so
+	// `semantic` is left out rather than reported `false`.
 	if (isOfflineGateRejection(error)) {
 		return {
 			enabled: true,
 			source: OFFLINE_GATE_SOURCE,
 			result: "failed",
 			syntax: false,
-			...semanticNotReached,
 			stages: [
 				{ stage: "offline", source: OFFLINE_GATE_SOURCE, result: "failed" },
 				{
@@ -705,9 +720,7 @@ function failedValidationMeta(
 			enabled: true,
 			source: deviceSource,
 			result: "failed",
-			...(nameRejected
-				? { syntax: true, semantic: false }
-				: { syntax: false, ...semanticNotReached }),
+			...(nameRejected ? { syntax: true, semantic: false } : { syntax: false }),
 			stages: [
 				offlineStagePassed(trace?.offlineVerdict),
 				{ stage: "device", source: deviceSource, result: "failed" },
@@ -781,15 +794,14 @@ export function offlineStagePassed(
  * `validate=false`. Both stages are listed as `skipped` rather than omitted:
  * the constitution's rule is that a gated surface always reports each stage, so
  * a consumer reading `stages` never has to special-case the disabled shape.
- * `reason` is left off — `enabled: false` already says why.
+ * `reason` is left off — `enabled: false` already says why. No stage answered,
+ * so there is no `syntax` / `semantic` summary (#535).
  */
 export function disabledValidationMeta(): EnvelopeValidationMeta {
 	return {
 		enabled: false,
 		source: "disabled",
 		result: "skipped",
-		syntax: false,
-		semantic: false,
 		stages: [
 			{ stage: "offline", source: OFFLINE_GATE_SOURCE, result: "skipped" },
 			{ stage: "device", source: "device preflight", result: "skipped" },
@@ -862,7 +874,6 @@ async function validateExecuteCommand(
 			source: ":put [:parse]",
 			result: "passed",
 			syntax: true,
-			semantic: "not-applicable",
 			stages: passedStages(offline, ":put [:parse]"),
 		};
 	}
@@ -929,8 +940,7 @@ async function validateConsoleParseCommand(
 		source: `:put [:parse ...] over ${resolved.via.value}`,
 		result: "passed",
 		syntax: true,
-		semantic:
-			resolved.canonical.mode === "structured" ? true : "not-applicable",
+		...(resolved.canonical.mode === "structured" ? { semantic: true } : {}),
 		stages: passedStages(
 			offline,
 			`:put [:parse ...] over ${resolved.via.value}`,
@@ -1452,20 +1462,38 @@ function executeRequestSummary(
  * downstream auth error.
  */
 export function resolvedExecuteTips(resolved: ResolvedExecuteRequest): Tip[] {
+	const tips: Tip[] = [];
 	if (
 		resolved.via.value === "mac-telnet" &&
 		resolved.auth.username === undefined &&
 		!resolved.auth.passwordProvided
 	) {
-		return [
+		tips.push(
 			buildTip(
 				"tip/mac-telnet-no-credentials",
 				"No username or password was resolved for this mac-telnet target.",
 				"mac-telnet logs in with RouterOS credentials over MTWEI (MD5 is refused): pass --username/--password, set CENTRS_USERNAME/CENTRS_PASSWORD, or add a CDB record for this device.",
 			),
-		];
+		);
+	}
+	// A bare menu path runs — the write gate no longer stops it — but it
+	// answers nothing: consoles navigate silently and the APIs refuse it with
+	// `no such command`. Name the read that does answer. `canonical` is
+	// always resolved in production; the guard keeps hermetic stubs total.
+	if (
+		resolved.canonical !== undefined &&
+		isBareMenuPathCommand(resolved.canonical)
+	) {
+		const menu = `${resolved.canonical.path}/${resolved.canonical.verb}`;
+		tips.push(
+			buildTip(
+				"tip/execute-bare-menu-path",
+				`"${menu}" is a menu path, not a command: consoles navigate to it (no output) and the APIs refuse it with "no such command".`,
+				`Append a verb such as "${menu}/print", or read rows with "centrs retrieve <router> ${menu}".`,
+			),
+		);
 	}
-	return [];
+	return tips;
 }
 
 function dataFromResult(result: ProtocolExecuteResult): unknown {

package/src/explain/args.ts

@@ -78,7 +78,12 @@
 
 import { isScopeBrace, isScopeBraceIn } from "./blocks.ts";
 import { braceSlotAcceptsBrace, braceSlotTakesArray } from "./brace-slots.ts";
-import { braceStartsStatements } from "./scope-brace.ts";
+import {
+	braceBodyIsScriptLike,
+	braceStartsStatements,
+	isScriptBodyName,
+	scopeNameFromMasked,
+} from "./scope-brace.ts";
 import {
 	type MaskedRange,
 	maskComments,
@@ -87,7 +92,7 @@ import {
 } from "./segment.ts";
 
 /** A RouterOS argument name: bare word, optionally dotted (`.id`, `.proplist`). */
-const ARGUMENT_NAME = /^\.?[A-Za-z][A-Za-z0-9._-]*$/;
+export const ARGUMENT_NAME = /^\.?[A-Za-z][A-Za-z0-9._-]*$/;
 
 /** What one argument token is. */
 export type ArgumentKind = "attribute" | "positional" | "query";
@@ -327,6 +332,12 @@ interface WalkOptions {
 	 * see {@link braceSlotTakesArray}.
 	 */
 	directiveVerb?: string;
+	/**
+	 * Where a command's top-level `where` positional ends, set by the walk itself
+	 * once it reads one. From there on a brace is an expression value
+	 * (see {@link comparesNamedValue}).
+	 */
+	whereAt?: number;
 }
 
 /** How deep member scanning descends before it stops and keeps only the shape. */
@@ -347,6 +358,34 @@ function braceValueOwner(
 	return ARGUMENT_NAME.test(name) ? name.toLowerCase() : undefined;
 }
 
+/**
+ * The `name` of a `name= {…}` brace: the token before the gap ends in a glued
+ * `name=` run (#554).
+ *
+ * {@link braceValueOwner} only sees the `=` glued to the brace (`down={`). A
+ * space after the `=` starts a new token, so the brace reads as positional
+ * there — but on CHR 7.25 `down= { :beep }` lowers to `down-script=` exactly
+ * like the glued spelling, while `comment= {1;2}` is a `syntax error` at the
+ * `{`. Only spaces and tabs span the gap: a newline there is a statement
+ * boundary, not a gap, and the name run must start its token, so `=down= {`
+ * and `down = {` own nothing.
+ */
+function spacedBraceOwner(text: string, at: number): string | undefined {
+	let j = at - 1;
+	let gap = 0;
+	while (text[j] === " " || text[j] === "\t") {
+		j--;
+		gap++;
+	}
+	if (gap === 0 || text[j] !== "=") return undefined;
+	const nameEnd = j;
+	j--;
+	while (j >= 0 && /[A-Za-z0-9.-]/.test(text[j] as string)) j--;
+	if (j >= 0 && !/[\s([]/.test(text[j] as string)) return undefined;
+	const name = text.slice(j + 1, nameEnd);
+	return ARGUMENT_NAME.test(name) ? name.toLowerCase() : undefined;
+}
+
 /**
  * Whether a `{` at `at` may open an array literal in this statement.
  *
@@ -363,7 +402,11 @@ function braceOpensArray(
 	options: WalkOptions,
 ): boolean {
 	const verb = options.directiveVerb;
-	if (verb === undefined) return false;
+	if (verb === undefined)
+		return (
+			options.whereAt !== undefined &&
+			!comparesNamedValue(text, at, options.whereAt)
+		);
 	const owner = braceValueOwner(text, tokenStart, at);
 	if (owner === undefined) return false;
 	return braceSlotTakesArray(
@@ -390,6 +433,7 @@ function* walkArguments(
 	let i = Math.max(0, from);
 	// How many positionals have been read, which is the NEXT positional's index.
 	let positionals = 0;
+	let walk = options;
 	while (i < text.length) {
 		// The MASKED view decides whitespace, because `maskComments` blanks a
 		// continuation comment that `text` still spells with a `#`. Reading `text`
@@ -412,7 +456,7 @@ function* walkArguments(
 			i += continuation;
 			continue;
 		}
-		const token = scanToken(text, structural, i, positionals, options);
+		const token = scanToken(text, structural, i, positionals, walk);
 		if (typeof token === "string") {
 			yield token;
 			return;
@@ -430,7 +474,7 @@ function* walkArguments(
 		// the refusal exists to prevent. Shape only, never a value.
 		const read =
 			token.why === undefined
-				? readToken(text, structural, i, token.end, options)
+				? readToken(text, structural, i, token.end, walk)
 				: undecidedToken(text, i, token.end, token.why);
 		if (typeof read === "string") {
 			if (options.tolerant !== true) {
@@ -446,6 +490,13 @@ function* walkArguments(
 			continue;
 		}
 		if (read.kind === "positional") positionals++;
+		if (
+			read.kind === "positional" &&
+			read.text === "where" &&
+			walk.directiveVerb === undefined &&
+			walk.whereAt === undefined
+		)
+			walk = { ...walk, whereAt: token.end };
 		yield read;
 		i = token.end;
 	}
@@ -1661,26 +1712,87 @@ export function lexValueAnchors(
 	return { complete: true, anchors };
 }
 
+/**
+ * Whether the brace at `at` is the right side of a `where` comparison that
+ * RouterOS reads with the named property's own value parser (#502).
+ *
+ * A `where` clause is expression context, so a brace there is an array value —
+ * except straight after `<name>=`, `<name>!=` or `<name>==`, spaced or not.
+ * On CHR 7.24.5 and 7.23.8, `:parse` rejects `/ip/route/print where
+ * comment={1;2}` with `expected comment value`, and `where disabled={…}` with
+ * `expected yes or no`. It accepts the brace after `in`, `~`, `<`, `>`, `<=`
+ * and `>=`, on the left of `=`, and after `!interface=`, `$x=` and `"a"=`.
+ *
+ * Only a property name the menu KNOWS is read this way: `where foo-bar={…}` is
+ * accepted. Offline has no per-menu property list (decision 3), so every bare
+ * name counts, and an unknown one is a pinned over-strict reading.
+ *
+ * The name may open a group, `where (interface={"x"})` and `or(comment={…})`,
+ * which `group-faults.ts` asks about (#509).
+ */
+export function comparesNamedValue(
+	text: string,
+	at: number,
+	floor: number,
+): boolean {
+	let j = at - 1;
+	while (j > floor && /\s/.test(text[j] as string)) j--;
+	if (text[j] !== "=") return false;
+	while (j > floor && text[j] === "=") j--;
+	if (text[j] === "<" || text[j] === ">") return false;
+	if (text[j] === "!") j--;
+	while (j > floor && /\s/.test(text[j] as string)) j--;
+	const nameEnd = j + 1;
+	while (j > floor && /[A-Za-z0-9._-]/.test(text[j] as string)) j--;
+	const name = text.slice(j + 1, nameEnd);
+	return /^[A-Za-z.]/.test(name) && /[\s(]/.test(text[j] as string);
+}
+
+/** One top-level `{` in command arguments that is not a proven body. */
+export interface CommandBraceFinding {
+	/** Offset of the `{` in the text passed to the lexer. */
+	at: number;
+	/**
+	 * True when `name={` with a script-like body on a non-root command outside
+	 * `where`, where `name` is not a proven script-body slot (#525). The brace
+	 * may abbreviate one (`down=` for `down-script=`), but telling it from
+	 * `comment=` needs the command's argument list, which is schema — so the
+	 * caller warns instead of rejecting, and the device decides.
+	 */
+	ambiguous: boolean;
+	/** The `name` of `name=`, lower-cased, when `ambiguous` is true. */
+	name?: string;
+}
+
 /**
  * Locate top-level `{...}` values that RouterOS rejects in command arguments.
  *
  * Parentheses and substitutions restore expression context, where a brace
- * literal is legal. Stored-script attributes are also excluded: their brace is
- * a script body, not an array. The caller applies this only to non-root
- * commands; root scripting directives use the `(verb, slot)` table instead.
+ * literal is legal, and so does a `where` clause, apart from the comparisons
+ * {@link comparesNamedValue} names. Stored-script attributes are also
+ * excluded: their brace is a script body, not an array. The caller applies
+ * this only to non-root commands; root scripting directives use the
+ * `(verb, slot)` table instead.
+ *
+ * A `name={` with a script-like body that is not a proven slot is returned
+ * with `ambiguous: true` rather than as an error (#525), and so is the spaced
+ * `name= {…}` spelling (`down= { :beep }` lowers to `down-script=` on CHR
+ * 7.25). Array-content braces (`comment={1;2}`), positional braces, `where`
+ * comparisons and root slots keep their rejection.
  */
 export function invalidCommandBraceOffsets(
 	text: string,
 	from: number,
 	directiveVerb?: string,
 	range?: MaskedRange,
-): number[] {
+): CommandBraceFinding[] {
 	const structural = maskOf(range) ?? maskComments(text);
-	const offsets: number[] = [];
+	const offsets: CommandBraceFinding[] = [];
 	const stack: string[] = [];
 	let i = Math.max(0, from);
 	let tokenStart: number | null = null;
 	let positionals = 0;
+	let whereAt: number | null = null;
 	while (i < structural.length) {
 		const c = structural[i] as string;
 		if (
@@ -1689,6 +1801,7 @@ export function invalidCommandBraceOffsets(
 		) {
 			if (tokenStart !== null) {
 				const token = structural.slice(tokenStart, i);
+				if (whereAt === null && token === "where") whereAt = i;
 				if (
 					!token.startsWith("?") &&
 					unquotedEquals(token, 0, token.length) === null
@@ -1725,7 +1838,54 @@ export function invalidCommandBraceOffsets(
 			tokenStart === null
 				? undefined
 				: braceValueOwner(structural, tokenStart, i);
-		const slot = owner === null ? `#${positionals}` : owner;
+		// A space after the `=` owns the brace the same way the glued `=`
+		// does (#554), so the slot attributes the spaced owner before
+		// falling back to positional: `:put x= { :beep }` reads slot `x`,
+		// not `#0` (which `put` accepts, swallowing the error).
+		const spacedOwner =
+			typeof owner === "string" ? undefined : spacedBraceOwner(structural, i);
+		const slot = owner === null ? (spacedOwner ?? `#${positionals}`) : owner;
+		// A `where` named comparison reads the brace with the property's own
+		// parser and rejects it (`expected <name> value`), so the #525 body
+		// guess must not shield it below — `gateway={ :beep }` included.
+		const inWhereComparison =
+			directiveVerb === undefined &&
+			whereAt !== null &&
+			comparesNamedValue(structural, i, whereAt);
+		// The ambiguity check comes first: `braceStartsStatements` reads an
+		// unproven `name={` with a script-like body as a body too (#525), so
+		// reaching that skip would swallow the warning that marks the guess.
+		// Control scopes (`do={` on a monitor, `:retry … command={`) are not
+		// guesses — the scope table already proves them — so they stay out.
+		// A space after the `=` owns the brace the same way the glued `=`
+		// does (`down= { :beep }` lowers to `down-script=` on CHR 7.25), so
+		// the spaced owner warns under the same gates.
+		const scopeName =
+			directiveVerb === undefined && whereAt === null
+				? range === undefined
+					? scopeNameFromMasked(structural, i)
+					: scopeNameFromMasked(range.masked, range.start + i, range.start)
+				: null;
+		const ambiguousOwner = typeof owner === "string" ? owner : spacedOwner;
+		if (
+			directiveVerb === undefined &&
+			whereAt === null &&
+			scopeName === null &&
+			typeof ambiguousOwner === "string" &&
+			!isScriptBodyName(ambiguousOwner) &&
+			braceBodyIsScriptLike(structural, i, end ?? structural.length)
+		) {
+			offsets.push({ at: i, ambiguous: true, name: ambiguousOwner });
+			i = end ?? i + 1;
+			continue;
+		}
+		// A root directive's slots and a `where` named comparison never take
+		// a script body through an unproven name: `:put x={ :beep }` and
+		// `where gateway={ :beep }` are device rejections, so the brace reads
+		// as a VALUE for the body check and the error below stands (#554).
+		// Proven slots still skip — the gate is only the unproven disjunct.
+		const unprovenName =
+			directiveVerb !== undefined || inWhereComparison ? "value" : "body";
 		if (
 			// Asked of the DOCUMENT when the caller anchored this statement, so the
 			// statement index behind it is the document's one index rather than a
@@ -1733,16 +1893,22 @@ export function invalidCommandBraceOffsets(
 			// subtree, and so was rebuilt once per enclosing level (#322). The floor
 			// makes the two readings the same answer (`scope-brace.ts`).
 			(range === undefined
-				? braceStartsStatements(structural, i)
-				: braceStartsStatements(range.masked, range.start + i, range.start)) ||
+				? braceStartsStatements(structural, i, 0, unprovenName)
+				: braceStartsStatements(
+						range.masked,
+						range.start + i,
+						range.start,
+						unprovenName,
+					)) ||
 			(directiveVerb !== undefined &&
 				slot !== undefined &&
-				braceSlotAcceptsBrace(directiveVerb, slot))
+				braceSlotAcceptsBrace(directiveVerb, slot)) ||
+			(directiveVerb === undefined && whereAt !== null && !inWhereComparison)
 		) {
 			i = end ?? structural.length;
 			continue;
 		}
-		offsets.push(i);
+		offsets.push({ at: i, ambiguous: false });
 		i = end ?? i + 1;
 	}
 	return offsets;

package/src/explain/blocks.ts

@@ -13,10 +13,9 @@
  * name (and, for the one head-dependent case, the leading directive) off the
  * statement itself.
  *
- * This module ships only the (single-pass, non-recursive) classification
- * primitives the path resolver needs. The recursive block *tree* / topology
- * surface stays in the lab until it can be promoted with a bounded, index-based
- * traversal of its own.
+ * This module ships the single-pass, non-recursive classification primitives
+ * the path resolver needs. `explain.ts` publishes source ownership from that
+ * resolver's existing bounded traversal; `scopeBlocks` remains a shallow scan.
  *
  * Every string skip here goes through `segment.ts`'s `scanQuotedString` rather
  * than a local quote-to-quote loop, so this module and the segmenter cannot

package/src/explain/brace-slots.ts

@@ -134,6 +134,11 @@ export function braceSlotTakesArray(verb: string, slot: string): boolean {
 	return BRACE_ARRAY_SLOTS.get(verb)?.has(slot) === true;
 }
 
+/** Whether a `{…}` in this root-directive slot is code or script text. */
+export function braceSlotTakesProgram(verb: string, slot: string): boolean {
+	return BRACE_PROGRAM_SLOTS.get(verb)?.has(slot) === true;
+}
+
 /** Whether the device sweep proved this root-directive slot accepts `{...}`. */
 export function braceSlotAcceptsBrace(verb: string, slot: string): boolean {
 	return (

package/src/explain/catalog.ts

@@ -1317,6 +1317,11 @@ export function lookupPath(
 	return PATH_CATALOG.get(`/${segments.join("/").toLowerCase()}`);
 }
 
+/** Segments in the deepest catalog path; no lookup past it can match. */
+const MAX_PATH_DEPTH = Math.max(
+	...Array.from(PATH_CATALOG.keys(), (path) => path.split("/").length - 1),
+);
+
 /**
  * Where a published COMMAND ends inside a path run: the index of the run
  * segment that is the VERB, or `null` when no prefix of `segments` is one.
@@ -1340,12 +1345,14 @@ export function lookupPath(
  * question; what the segment IS is not.
  */
 export function commandVerbIndex(segments: readonly string[]): number | null {
-	for (let depth = 1; depth <= segments.length; depth++)
-		if (
-			PATH_CATALOG.get(`/${segments.slice(0, depth).join("/").toLowerCase()}`)
-				?.kind === "command"
-		)
-			return depth - 1;
+	// Bounded by the deepest row and built incrementally: a run of thousands of
+	// bare words would otherwise re-join every prefix (#496).
+	const limit = Math.min(segments.length, MAX_PATH_DEPTH);
+	let path = "";
+	for (let depth = 0; depth < limit; depth++) {
+		path += `/${(segments[depth] as string).toLowerCase()}`;
+		if (PATH_CATALOG.get(path)?.kind === "command") return depth;
+	}
 	return null;
 }
 

package/src/explain/defects.ts

@@ -99,6 +99,7 @@ export type DefectCode =
 	| "over-depth"
 	| "bad-escape"
 	| "bad-string-escape"
+	| "bad-string-variable"
 	| "bad-sigil"
 	| "invalid-hash"
 	| "invalid-apostrophe"