@tikoci/centrs 0.1.3 → 0.1.4

package/src/index.ts

@@ -118,6 +118,24 @@ export {
 	isCommandNode,
 	pathTokens,
 } from "./core/inspect.ts";
+export {
+	assertCapability,
+	type CapabilityRequirement,
+	checkCapability,
+	compareRouterOsVersion,
+	type DeviceVersion,
+	type DeviceVersionSource,
+	type PreflightState,
+	type PreflightVerdict,
+	parseRouterOsVersion,
+	probeDeviceVersion,
+	type RouterOsVersionParts,
+	type RouterOsVersionRange,
+	renderSupportedRanges,
+	routerOsVersionAtLeast,
+	versionFactFromComment,
+	versionInRange,
+} from "./core/preflight.ts";
 export {
 	encodeMndpPacket,
 	MNDP_BROADCAST_ADDRESS,
@@ -276,6 +294,190 @@ export {
 	executeFanout,
 	renderExecuteFanoutEnvelope,
 } from "./execute-fanout.ts";
+// The lexer's own names are module-scoped and read naturally there; at the
+// package root they need the `Explain` prefix every other explain export
+// carries — a bare `Argument` says nothing about which of centrs's surfaces it
+// belongs to. Aliasing at the re-export is the existing pattern here (see
+// `occurrences as explainOccurrences` below).
+//
+// `ExplainArgument` and `ExplainArgumentToken` are the same SHAPE in two
+// coordinate spaces: this one is what `lexArguments` returns, with spans
+// relative to the statement it was handed; the `Token` is that rebased into
+// document space by `explainCommand`. A consumer reading `explainCommand`'s
+// result wants the latter.
+export {
+	type Argument as ExplainArgument,
+	type ArgumentKind as ExplainArgumentKind,
+	type ArgumentReading as ExplainArgumentReading,
+	type ArgumentsRead as ExplainArgumentsRead,
+	type ArgumentsUnread as ExplainArgumentsUnread,
+	lexArguments as lexExplainArguments,
+	lexValueAnchors as lexExplainValueAnchors,
+	type ValueAnchor as ExplainValueAnchor,
+	type ValueAnchorKind as ExplainValueAnchorKind,
+	type ValueAnchorReading as ExplainValueAnchorReading,
+} from "./explain/args.ts";
+export {
+	DIRECTIVE_BODY,
+	HEAD_SCOPED_ARG_NAMES,
+	isScopeBrace,
+	matchBrace,
+	SCOPE_ARG_NAMES,
+	type ScopeBlock,
+	scopeBlocks,
+	scopeBodies,
+	scopeNameAt,
+} from "./explain/blocks.ts";
+export {
+	analyzeCoordinates,
+	byteSpanToRange,
+	byteToPosition,
+	type CharRun,
+	type CoordinateAnalysis,
+	coordinateDefects,
+	type Position,
+	positionToByte,
+	type Range,
+	runAtByte,
+	SUB,
+} from "./explain/coordinates.ts";
+export {
+	type Defect,
+	type DefectCode,
+	defectAt,
+	hasStructuralDefect,
+	isPositionalFact,
+	mergeDefects,
+	rebaseDefects,
+} from "./explain/defects.ts";
+export {
+	type DocumentAnalysis,
+	type Resolution,
+	resolveDocument,
+	resolveStatements,
+	type Span,
+	type StatementAnalysis,
+	type StatementResolution,
+} from "./explain/pathresolve.ts";
+export {
+	maskComments,
+	type QuotedStringScan,
+	type Segment,
+	type SegmentResult,
+	scanQuotedString,
+	segmentStatements,
+} from "./explain/segment.ts";
+export {
+	HIGHLIGHT_CLASS,
+	resolveSymbols,
+	type SymbolAnalysis,
+	type SymbolClass,
+	type SymbolOccurrence,
+	type SymbolRole,
+} from "./explain/symbols.ts";
+export type {
+	ExplainApiCandidateTransport,
+	ExplainExecuteTransport,
+	ExplainRestMethod,
+	ExplainRestRequest,
+	ExplainTransport,
+	ExplainTransportClassification,
+	ExplainUnknownTransport,
+} from "./explain/transport.ts";
+export {
+	VALUE_SHAPES,
+	type ValueContext as ExplainValueContext,
+	type ValueShape as ExplainValueShape,
+	type ValueShapeOptions as ExplainValueShapeOptions,
+	valueShapeHints as explainValueShapeHints,
+} from "./explain/values.ts";
+export {
+	type DocumentVerbSplit,
+	describeStatement,
+	isDirective,
+	type RunToken,
+	resolveVerb,
+	resolveVerbs,
+	runTokens,
+	type Sep,
+	type Split,
+	SUBMENU_DIRECTIVES,
+	splitRun,
+	VERBS,
+	type VerbAnalysis,
+	type VerbResolution,
+	type VerbSplit,
+	type VerbSplitCommandReading,
+	type VerbSplitMenuReading,
+	type VerbSplitRefusal,
+} from "./explain/verbsplit.ts";
+export {
+	classifyVerb,
+	containsWrite,
+	type Occurrence,
+	type OccurrenceClass,
+	// `occurrences` is too generic for the library root; the module-local name
+	// stays short because inside `write.ts` there is only one kind.
+	occurrences as explainOccurrences,
+	READ_VERBS,
+	ROOT_CMDS,
+	ROOT_DYNAMIC,
+	ROOT_WRITE,
+	WRITE_VERBS,
+	type WriteAnalysis,
+	type WriteVerdict,
+} from "./explain/write.ts";
+export {
+	buildExplainErrorEnvelope,
+	buildExplainFacetTip,
+	type ExplainArguments,
+	type ExplainArgumentToken,
+	type ExplainBlock,
+	type ExplainCanonical,
+	type ExplainCommandOptions,
+	type ExplainCommandReading,
+	type ExplainData,
+	type ExplainDiagnostic,
+	type ExplainEnvelope,
+	type ExplainEnvelopeOptions,
+	type ExplainErrorEnvelope,
+	type ExplainEvidence,
+	type ExplainFailOn,
+	type ExplainInput,
+	type ExplainMenuReading,
+	type ExplainOperationMeta,
+	type ExplainOutputFormat,
+	type ExplainPositionMapEntry,
+	type ExplainReading,
+	type ExplainRefusal,
+	type ExplainResolution,
+	type ExplainSeverity,
+	type ExplainSpan,
+	type ExplainSpanClass,
+	type ExplainSpanRange,
+	type ExplainStatement,
+	type ExplainStatementFacts,
+	type ExplainStructure,
+	type ExplainSubcommand,
+	type ExplainSubcommandFacts,
+	type ExplainSymbolClass,
+	type ExplainSymbolOccurrence,
+	type ExplainSymbols,
+	type ExplainToken,
+	type ExplainTokenClass,
+	type ExplainValueFacts,
+	type ExplainValueOccurrence,
+	type ExplainValueShapeFact,
+	type ExplainValues,
+	type ExplainValueTypeFact,
+	type ExplainVerdict,
+	explainCommand,
+	explainEnvelope,
+	explainExitCode,
+	explainFailOnLevels,
+	explainOutputFormats,
+	renderExplainEnvelope,
+} from "./explain.ts";
 export {
 	type ApiVerb,
 	createProtocolAdapter,
@@ -304,9 +506,6 @@ export {
 	type CdbGroupTarget,
 	type CdbResolution,
 	type CdbResolveInput,
-	type CdbSelectionExpansion,
-	type CdbSelectionMember,
-	type CdbSelectionResolveInput,
 	type CommentKvGeoKey,
 	type CommentKvKey,
 	type CommentKvLayer,
@@ -323,7 +522,7 @@ export {
 	defaultPortForScheme,
 	deviceLocation,
 	expandCdbGroup,
-	expandCdbSelection,
+	expandSelection,
 	isDefaultRecordTarget,
 	type NearPredicate,
 	type ParsedGpsTuple,
@@ -351,6 +550,9 @@ export {
 	resolveOptionalIntegerSetting,
 	resolveStringSetting,
 	resolveTarget,
+	type SelectionExpansion,
+	type SelectionMember,
+	type SelectionResolveInput,
 	type SelectionWhereClause,
 	type TargetResolveInput,
 	type TargetSelection,

package/src/protocols/mac-telnet-console.ts

@@ -39,10 +39,11 @@
  *     scraped for: `(evl …)` = ok, `syntax error (line …)` = malformed, and
  *     `bad parameter <name> (line …)` = unknown attribute. A single console
  *     `:parse` therefore covers both the syntax and the unknown-attribute
- *     (semantic) gate — no `/console/inspect` table parsing needed.
+ *     (name-level) gate — no `/console/inspect` table parsing needed.
  */
 
 import { parseRouterOsPosition } from "../core/routeros-errors.ts";
+import { routerOsStringLiteral } from "../core/routeros-string.ts";
 import { CentrsError } from "../errors.ts";
 import {
 	type MacAddress,
@@ -323,8 +324,11 @@ export class MacTelnetConsole {
 	 * Validate a command without running it, using a single console `:parse`.
 	 * Throws `validation/syntax` for malformed CLI and
 	 * `validation/unknown-attribute` for a rejected parameter; returns the parsed
-	 * form on success. One gate covers both because the console's `:parse`
-	 * reports `bad parameter <name>` as well as `syntax error`.
+	 * form on success. One gate covers both because the console prints the
+	 * `:parse` return value, which carries `bad parameter <name>` as well as the
+	 * `(<%%` / `(line N column M)` syntax diagnostics — see
+	 * {@link classifyParseResult} for the full grammar and why the matcher is
+	 * anchored to the diagnostic shape rather than to bare words.
 	 */
 	async parseGate(cli: string): Promise<string> {
 		const { output } = await this.run(parseScriptFor(cli));
@@ -604,17 +608,61 @@ export function parseScriptFor(cli: string): string {
 	return `:put [:parse ${routerOsStringLiteral(cli)}]`;
 }
 
+/*
+ * The `:parse` diagnostic grammar, anchored to where RouterOS actually emits
+ * each shape. Anchoring is load-bearing, not cosmetic: an *accepted* return
+ * echoes the script body, so `:put "bad parameter x"` comes back as
+ * `(evl /putmessage=bad parameter x)`. An unanchored search reads that echoed
+ * content as a verdict and refuses to run a valid command (GH#230).
+ *
+ * Two shapes, both corpus-verified against lsp-routeros-ts
+ * `parseil_results.il_text` (2736 rows, RouterOS 7.20.8/7.22.1/7.23rc1):
+ *
+ *   1. WRAPPED — the diagnostic sits inside the returned value, marked by the
+ *      `(evl ` / `(<%%` wrapper. It can appear mid-return, because a
+ *      multi-statement script reports the offending statement in place. Every
+ *      corpus `bad parameter` (8/8) follows `(evl `, and every `bad command
+ *      name` (135/135) follows `(<%%`.
+ *   2. BARE — the diagnostic *is* the whole return, printed on its own line
+ *      with RouterOS's position suffix. All 425 corpus rows of this shape are
+ *      the entire return; none appear embedded. Requiring both line-start and
+ *      the `(line N column M)` suffix is what separates a real verdict from
+ *      echoed body text.
+ */
+const WRAPPED_BAD_PARAMETER = /\(evl\s+bad parameter\s+(\S+)/i;
+const WRAPPED_BAD_COMMAND = /\(<%%\s*bad command name\b/i;
+const BARE_BAD_PARAMETER =
+	/^[ \t]*bad parameter\s+(\S+)[^\n]*\(line \d+ column \d+\)/im;
+const BARE_SYNTAX =
+	/^[ \t]*(?:syntax error|bad command name|expected [a-z]+(?: [a-z]+)*)[^\n]*\(line \d+ column \d+\)/im;
+
 /**
- * Classify the output of a console `:put [:parse "<cli>"]`. A single console
- * `:parse` reports both forms (grounded on CHR 7.23.1): `bad parameter <name>`
- * for an unknown attribute and `syntax error` / `bad command name` for malformed
- * CLI. Throws the matching `validation/*` error; returns on a clean parse.
+ * Classify the printed value of `:put [:parse "<cli>"]`. Grounded on CHR 7.23.3
+ * (see GH#230): `:parse` *never* throws — it returns a value whose text carries
+ * the verdict. For a bare menu path the accepted form is `(evl /canonical/path)`
+ * (abbreviations expanded); for script-shaped input the accepted return echoes
+ * the statement body and may contain arbitrary text — including text that looks
+ * like a diagnostic. Rejections are therefore matched only in the positions
+ * RouterOS emits them (see the grammar note above): wrapped as
+ * `(evl bad parameter <name> (line N column M) /path)` /
+ * `(<%% bad command name <name> (line N column M) a;b;c)`, or bare and
+ * line-initial as `expected … (line N column M)` / `syntax error (line N column
+ * M)`. A single `:parse` covers both the syntax and the unknown-attribute
+ * (name-level) gate on every transport — REST and native API expose the same text
+ * in the `ret` value (HTTP 200 / `as-string`), the console transports print it.
+ *
+ * Throws the matching `validation/*` error; returns on a clean parse.
  */
-export function classifyParseResult(output: string, cli: string): void {
-	// The console `:parse` rejection carries RouterOS's authoritative byte offset
+export function classifyParseResult(
+	output: string,
+	cli: string,
+	via: string = "mac-telnet",
+): void {
+	// The `:parse` rejection carries RouterOS's authoritative byte offset
 	// (`… (line N column M)`); surface it as the structured `error.position`.
 	const position = parseRouterOsPosition(output);
-	const unknown = output.match(/bad parameter\s+(\S+)/i);
+	const unknown =
+		output.match(WRAPPED_BAD_PARAMETER) ?? output.match(BARE_BAD_PARAMETER);
 	if (unknown) {
 		throw new CentrsError({
 			code: "validation/unknown-attribute",
@@ -624,13 +672,13 @@ export function classifyParseResult(output: string, cli: string): void {
 			context: {
 				command: cli,
 				parameter: cleanToken(unknown[1] ?? ""),
-				validationSource: ":put [:parse ...] over mac-telnet",
+				validationSource: `:put [:parse ...] over ${via}`,
 				detail: output,
 			},
 			...(position ? { position } : {}),
 		});
 	}
-	if (/syntax error|bad command name|expected\b/i.test(output)) {
+	if (WRAPPED_BAD_COMMAND.test(output) || BARE_SYNTAX.test(output)) {
 		throw new CentrsError({
 			code: "validation/syntax",
 			summary: "RouterOS rejected the command syntax while parsing it.",
@@ -638,7 +686,7 @@ export function classifyParseResult(output: string, cli: string): void {
 				"Fix the RouterOS CLI syntax (quotes, brackets, attribute form), then retry.",
 			context: {
 				command: cli,
-				validationSource: ":put [:parse ...] over mac-telnet",
+				validationSource: `:put [:parse ...] over ${via}`,
 				detail: output,
 			},
 			...(position ? { position } : {}),
@@ -646,10 +694,6 @@ export function classifyParseResult(output: string, cli: string): void {
 	}
 }
 
-function routerOsStringLiteral(value: string): string {
-	return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
-}
-
 function cleanToken(token: string): string {
 	return token.replace(/^["'`]+|["'`.,;:)]+$/g, "");
 }

package/src/resolver/facts.ts

@@ -1,6 +1,6 @@
 /**
  * Device-class fact extraction + selector matching, shared by the fan-out
- * resolver ({@link ../resolver/selection.ts | expandCdbSelection}) and
+ * resolver ({@link ../resolver/selection.ts | expandSelection}) and
  * `devices list` (`src/devices.ts`) so **both surfaces match `--where` /
  * `--near` / `--bbox` against identical semantics**.
  *

package/src/resolver/index.ts

@@ -88,14 +88,33 @@ export {
 	unresolvedMacError,
 } from "./mac.ts";
 export {
-	type CdbSelectionExpansion,
-	type CdbSelectionMember,
-	type CdbSelectionResolveInput,
-	expandCdbSelection,
+	assertNoQuickchrOverrideConflict,
+	type QuickchrConnection,
+	type QuickchrResolution,
+	quickchrConnection,
+	resolveQuickchrTarget,
+	SUPPORTED_DESCRIPTOR_VERSION,
+} from "./quickchr-provider.ts";
+export {
+	expandSelection,
 	isDefaultRecordTarget,
+	type SelectionExpansion,
+	type SelectionMember,
+	type SelectionResolveInput,
 	type SelectionWhereClause,
 	type TargetSelection,
 } from "./selection.ts";
+export {
+	type AnyServiceEndpoint,
+	isEndpointAvailable,
+	type ServiceEndpoint,
+	type ServiceEndpointAuth,
+	type ServiceEndpointMap,
+	type ServiceEndpointSource,
+	type SshEndpointAuth,
+	type SshServiceEndpoint,
+	type UnavailableEndpoint,
+} from "./service-endpoint.ts";
 export {
 	type CommentKvLayer,
 	parseBoolean,