From ec1cf3a9bd193371a599ae69b1bc6325b4624b14 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Mon, 16 Nov 2026 12:01:04 +0800 Subject: [PATCH] refactor(cli): render command help with REA's own help owner (#11683) * refactor(cli): render command help with REA's own help owner Add src/cli/help.ts and move the three incur Help.formatCommand callers (rea mcp add, rea mcp doctor, rea mcp --http) onto it. Option spelling and the unwrapped field type move to src/cli/optionFields.ts, which completion now reads instead of its own copies. A counted incur-import guard records the names still imported from incur so the list can only shrink. Refs #11654 * refactor(cli): share option spelling across CLI owners and count every incur import The argv parser, strict positionals, contract command projection and the command registry now read the flag spelling, declared field type and count marker from src/cli/optionFields.ts instead of their own copies. The incur-import guard also counts namespace, default, star, side-effect and dynamic imports, so `import * as Incur from "incur"` cannot bring a removed owner back. * refactor(cli): format and filter CLI output without incur (#11684) * refactor(cli): format and filter CLI output without incur formatCliOutput encodes TOON (@toon-format/toon), JSON, YAML and JSON Lines itself instead of calling incur's Formatter; YAML still loads on first use. src/cli/outputFilter.ts owns the --filter-output grammar and returns a Result: an unclosed slice is a parse failure, so output validation reads the parser instead of a second bracket scanner, and the parsed paths travel with the output arguments to the result writer and JSON Lines. @toon-format/toon moves from devDependencies to dependencies because REA now imports it at runtime. Refs #11654 * test(cli): pin output encodings and filter grammar with literal cases Literal expected outputs for empty values, TOON scalars, objects and rows, JSON-text re-indentation, nested BigInt values, JSON Lines rows and YAML, and literal parsed paths and unclosed-slice refusals for --filter-output, so a change to either owner fails without comparing against itself. --- package-lock.json | 2 +- package.json | 2 +- scripts/verify/architecture-guards.mjs | 16 +- scripts/verify/baselines/incur-import.json | 70 +++++++++ scripts/verify/incur-import-guard.d.mts | 1 + scripts/verify/incur-import-guard.mjs | 118 ++++++++++++--- src/cli/argvParser.ts | 38 +++-- src/cli/cliOutputFormatter.ts | 65 +++++++- src/cli/cliResultOutput.ts | 29 ++-- src/cli/commandRegistry.ts | 6 +- src/cli/completionProtocol.ts | 34 ++--- src/cli/contractCliDescription.ts | 16 +- src/cli/contractCommand.ts | 6 +- src/cli/help.ts | 139 ++++++++++++++++++ src/cli/jsonLines.ts | 7 +- src/cli/jsonLinesOutput.ts | 4 +- src/cli/mcpRegistration.ts | 6 +- src/cli/optionFields.ts | 28 ++++ src/cli/outputFilter.ts | 78 ++++++++++ src/cli/strictPositionals.ts | 22 +-- src/cliOutput.ts | 35 ++--- src/main/mcpHttpArguments.ts | 7 +- src/mcpDoctor.ts | 10 +- .../acceptance/cliFormattingCapacity.test.ts | 45 ++++-- .../cli/cliFullOutputTokenCount.test.ts | 4 +- tests/boundary/cli/cliOutputFormatter.test.ts | 48 ++++++ tests/boundary/cli/cliResultControls.test.ts | 5 +- .../boundary/cli/cliTokenWindowOutput.test.ts | 9 +- tests/boundary/cli/commandHelp.test.ts | 56 +++++++ .../boundary/cli/filteredArrayOutput.test.ts | 11 +- tests/boundary/cli/outputFilter.test.ts | 27 ++++ tests/evaluation/incurImportGuard.test.ts | 41 +++++- 32 files changed, 791 insertions(+), 194 deletions(-) create mode 100644 scripts/verify/baselines/incur-import.json create mode 100644 src/cli/help.ts create mode 100644 src/cli/optionFields.ts create mode 100644 src/cli/outputFilter.ts create mode 100644 tests/boundary/cli/commandHelp.test.ts create mode 100644 tests/boundary/cli/outputFilter.test.ts diff --git a/package-lock.json b/package-lock.json index 8b22f9c68c..4e951be9e9 100644 --- a/package-lock.json +++ b/package-lock.json @@ -18,6 +18,7 @@ "@modelcontextprotocol/client": "2.3.1", "@modelcontextprotocol/server": "2.3.1", "@msgpack/msgpack": "3.1.3", + "@toon-format/toon": "2.3.1", "@xmldom/xmldom": "0.9.12", "@xterm/addon-serialize": "0.14.0", "@xterm/headless": "6.0.0", @@ -62,7 +63,6 @@ "@stryker-mutator/core": "10.0.0", "@stryker-mutator/typescript-checker": "10.0.0", "@stryker-mutator/vitest-runner": "10.0.0", - "@toon-format/toon": "2.3.1", "@types/cross-spawn": "6.0.6", "@types/node": "26.6.4", "@types/semver": "7.7.1", diff --git a/package.json b/package.json index 4d791bacce..69e02a2f01 100644 --- a/package.json +++ b/package.json @@ -379,6 +379,7 @@ "@modelcontextprotocol/client": "2.3.1", "@modelcontextprotocol/server": "2.3.1", "@msgpack/msgpack": "3.1.3", + "@toon-format/toon": "2.3.1", "@xmldom/xmldom": "0.9.12", "@xterm/addon-serialize": "0.14.0", "@xterm/headless": "6.0.0", @@ -430,7 +431,6 @@ "@stryker-mutator/core": "10.0.0", "@stryker-mutator/typescript-checker": "10.0.0", "@stryker-mutator/vitest-runner": "10.0.0", - "@toon-format/toon": "2.3.1", "@types/cross-spawn": "6.0.6", "@types/node": "26.6.4", "@types/semver": "7.7.1", diff --git a/scripts/verify/architecture-guards.mjs b/scripts/verify/architecture-guards.mjs index 6a1264382e..4b236a0320 100644 --- a/scripts/verify/architecture-guards.mjs +++ b/scripts/verify/architecture-guards.mjs @@ -9,7 +9,10 @@ import { } from "./counted-baseline.mjs"; import { localCompletenessEnumCount } from "./completeness-enum-guard.mjs"; import { countKeyedFirstMatches } from "./keyed-first-match.mjs"; -import { incurZodImportCount } from "./incur-import-guard.mjs"; +import { + incurImportedNameCount, + incurZodImportCount, +} from "./incur-import-guard.mjs"; import { budgetArithmeticCount } from "./budget-arithmetic-guard.mjs"; import { localLimitErrorClassCount } from "./limit-class-guard.mjs"; import { countDefaultValidationClients } from "./mcp-client-validation.mjs"; @@ -971,6 +974,17 @@ checkCounted( ["src/cli/commandRegistry.ts"], ); +// REA is replacing incur with its own CLI owners (#11654). Each replacement +// removes the names it superseded; this counted list only shrinks until incur +// leaves package.json. +checkCounted( + "name imported from incur (use REA's CLI owner in src/cli)", + "incur-import", + [...files, ...testFiles], + (_content, file) => incurImportedNameCount(file.source ?? file.content), + [], +); + // `find` on a parsed section, program-header or load-command table silently // keeps the first of repeated declarations. Select keyed entries through // src/domain/keyedCollection (`uniqueKeyed`, `allKeyed`, or diff --git a/scripts/verify/baselines/incur-import.json b/scripts/verify/baselines/incur-import.json new file mode 100644 index 0000000000..07808a214e --- /dev/null +++ b/scripts/verify/baselines/incur-import.json @@ -0,0 +1,70 @@ +{ + "src/cli/applicationCommands.ts": 1, + "src/cli/argumentErrors.ts": 1, + "src/cli/browserAdvancedCommands.ts": 1, + "src/cli/browserCommands.ts": 1, + "src/cli/cliShell.ts": 1, + "src/cli/electronCommands.ts": 1, + "src/cli/explicitSensitiveArguments.ts": 2, + "src/cli/processCommands.ts": 1, + "src/cli/strictPositionals.ts": 1, + "src/cli/types.ts": 1, + "src/cli/visitRegisteredCommands.ts": 1, + "src/cli/webRuntimeCommands.ts": 1, + "tests/boundary/captures/captureProvider.test.ts": 1, + "tests/boundary/cli/analyzeFunctionDetail.test.ts": 1, + "tests/boundary/cli/browserScenarioSummaryCli.test.ts": 1, + "tests/boundary/cli/browserScenarioValidation.test.ts": 1, + "tests/boundary/cli/captureCleanup.test.ts": 1, + "tests/boundary/cli/cliContractCommandParity.test.ts": 1, + "tests/boundary/cli/cliContractSchemaParity.test.ts": 1, + "tests/boundary/cli/cliControlFlag.test.ts": 1, + "tests/boundary/cli/cliDecimalArguments.test.ts": 2, + "tests/boundary/cli/cliDomainFieldSchema.test.ts": 1, + "tests/boundary/cli/cliInputSchemaRequired.test.ts": 1, + "tests/boundary/cli/cliJsonCallerPath.test.ts": 1, + "tests/boundary/cli/cliLazyRegistration.test.ts": 1, + "tests/boundary/cli/cliOptionAliases.test.ts": 1, + "tests/boundary/cli/cliResultControls.test.ts": 1, + "tests/boundary/cli/cliTimingArguments.test.ts": 1, + "tests/boundary/cli/cliTokenWindowOutput.test.ts": 1, + "tests/boundary/cli/commandEvidenceDelivery.test.ts": 1, + "tests/boundary/cli/completions.test.ts": 1, + "tests/boundary/cli/contractCommandInputFields.test.ts": 1, + "tests/boundary/cli/contractCommandViewDelivery.test.ts": 1, + "tests/boundary/cli/contractJsonInputChecks.test.ts": 1, + "tests/boundary/cli/defaultAmpRegistration.test.ts": 1, + "tests/boundary/cli/directAnalysisStatus.test.ts": 1, + "tests/boundary/cli/emptyLocalTargetAdmission.test.ts": 1, + "tests/boundary/cli/filteredArrayOutput.test.ts": 1, + "tests/boundary/cli/filteredFailureOutput.test.ts": 1, + "tests/boundary/cli/formattingRecovery.test.ts": 1, + "tests/boundary/cli/javascriptApplicationPathAdmission.test.ts": 1, + "tests/boundary/cli/jebInputDiagnostics.test.ts": 1, + "tests/boundary/cli/jsonLinesOutput.test.ts": 1, + "tests/boundary/cli/jsonOutput.test.ts": 1, + "tests/boundary/cli/markdownArgumentErrors.test.ts": 2, + "tests/boundary/cli/markdownNestedFacts.test.ts": 1, + "tests/boundary/cli/nativeFeatureTraceDelivery.test.ts": 1, + "tests/boundary/cli/nativeLoadImageSummaryCli.test.ts": 1, + "tests/boundary/cli/overnightBatch1CliSchemas.test.ts": 1, + "tests/boundary/cli/procedureReferencesDelivery.test.ts": 1, + "tests/boundary/cli/reverseEngineeringCommands.test.ts": 1, + "tests/boundary/cli/routedCommand.test.ts": 1, + "tests/boundary/cli/scenarioManifestCoverage.test.ts": 1, + "tests/boundary/cli/searchBytesAdmission.test.ts": 1, + "tests/boundary/cli/signalCleanup.test.ts": 1, + "tests/boundary/cli/strictPositionals.test.ts": 1, + "tests/boundary/cli/traceNativeValuesCompletenessCli.test.ts": 1, + "tests/boundary/cli/traceNativeValuesEvidenceCli.test.ts": 1, + "tests/boundary/mcp/syntheticContractSurfaces.test.ts": 1, + "tests/boundary/signals/recordingProvider.test.ts": 1, + "tests/boundary/sqlite/sqliteDatabaseDescriptorCleanup.test.ts": 1, + "tests/process-global/browserScenarioCleanup.test.ts": 1, + "tests/process-global/commandFinalizationCancellation.test.ts": 1, + "tests/process-global/flutterCliCleanup.test.ts": 1, + "tests/process-global/javascriptRuntimeObservationCli.test.ts": 1, + "tests/process-global/oneShotSourceClosure.test.ts": 1, + "tests/support/cli/apktoolCli.ts": 1, + "tests/support/cli/processComparisonCli.ts": 1 +} diff --git a/scripts/verify/incur-import-guard.d.mts b/scripts/verify/incur-import-guard.d.mts index 47e912e1a0..fc95d91699 100644 --- a/scripts/verify/incur-import-guard.d.mts +++ b/scripts/verify/incur-import-guard.d.mts @@ -1 +1,2 @@ export function incurZodImportCount(source: string): number; +export function incurImportedNameCount(source: string): number; diff --git a/scripts/verify/incur-import-guard.mjs b/scripts/verify/incur-import-guard.mjs index 0f1adae1b5..13909980d5 100644 --- a/scripts/verify/incur-import-guard.mjs +++ b/scripts/verify/incur-import-guard.mjs @@ -1,7 +1,9 @@ -// Counts import and re-export declarations that take zod's `z` from incur -// (`import { z } from "incur"`, `import type { z as Zod } from 'incur'`, -// `export { z } from "incur"`). Declarations are read from code tokens, so the -// same text in a comment, string or template is not counted. +// Reads the bindings that import and re-export declarations take from incur: +// named (`import { Cli, type Help } from "incur"`, `export { z } from 'incur'`), +// default, namespace (`import * as Incur from "incur"`), star re-exports +// (`export * from "incur"`), side-effect imports and dynamic `import("incur")`. +// Declarations are read from code tokens, so the same text in a comment, +// string or template is not counted. import { tokenize } from "./source-tokens.mjs"; const isIncurSpecifier = (source, token) => @@ -9,10 +11,82 @@ const isIncurSpecifier = (source, token) => (source.startsWith('"incur"', token.start) || source.startsWith("'incur'", token.start)); -/** @param {string} source */ -export const incurZodImportCount = (source) => { +/** + * Read `{ a, type b, c as d }` starting at the `{` token. + * @returns {{ names: string[], end: number } | undefined} imported names and + * the index after `}` + */ +const namedBindings = (tokens, open) => { + const names = []; + let expectName = true; + let at = open + 1; + for (; at < tokens.length && tokens[at].text !== "}"; at += 1) { + const token = tokens[at]; + if (token.text === ",") expectName = true; + // In `{ z as zod }` the imported name is z; in `{ type Cli }`, Cli. + else if ( + expectName && + token.kind === "id" && + !(token.text === "type" && tokens[at + 1]?.kind === "id") + ) { + names.push(token.text); + expectName = false; + } + } + return at < tokens.length ? { names, end: at + 1 } : undefined; +}; + +/** + * The bindings of the declaration whose `import` or `export` keyword is at + * `index`, or undefined when it does not take anything from incur. + * @returns {string[] | undefined} + */ +const incurBindings = (source, tokens, index) => { + let at = index + 1; + // `import("incur")` and `import "incur"` bind nothing by name. + if (tokens[index].text === "import" && tokens[at]?.text === "(") + return isIncurSpecifier(source, tokens[at + 1]) ? ["import()"] : undefined; + if (tokens[index].text === "import" && tokens[at]?.kind === "string") + return isIncurSpecifier(source, tokens[at]) ? ["import"] : undefined; + if (tokens[at]?.kind === "id" && tokens[at].text === "type") at += 1; + const names = []; + // A default import may precede a named or namespace clause. + if ( + tokens[index].text === "import" && + tokens[at]?.kind === "id" && + tokens[at].text !== "from" + ) { + names.push("default"); + at += 1; + if (tokens[at]?.text !== ",") return finish(source, tokens, at, names); + at += 1; + } + if (tokens[at]?.text === "*") { + names.push("*"); + at += 1; + if (tokens[at]?.kind === "id" && tokens[at].text === "as") at += 2; + } else if (tokens[at]?.text === "{") { + const named = namedBindings(tokens, at); + if (named === undefined) return undefined; + names.push(...named.names); + at = named.end; + } else if (names.length === 0) return undefined; + return finish(source, tokens, at, names); +}; + +const finish = (source, tokens, at, names) => + tokens[at]?.text === "from" && isIncurSpecifier(source, tokens[at + 1]) + ? names + : undefined; + +/** + * The bindings of each declaration that takes something from incur. + * @param {string} source + * @returns {string[][]} + */ +const incurDeclarations = (source) => { const { tokens } = tokenize(source); - let count = 0; + const declarations = []; for (let index = 0; index < tokens.length; index += 1) { const keyword = tokens[index]; if ( @@ -20,21 +94,19 @@ export const incurZodImportCount = (source) => { (keyword.text !== "import" && keyword.text !== "export") ) continue; - let at = index + 1; - if (tokens[at]?.kind === "id" && tokens[at].text === "type") at += 1; - if (tokens[at]?.text !== "{") continue; - let importsZ = false; - for (at += 1; at < tokens.length && tokens[at].text !== "}"; at += 1) - // In `{ z as zod }` the imported name is z; in `{ zod as z }` it is not. - if (tokens[at].text === "z" && tokens[at - 1]?.text !== "as") - importsZ = true; - if ( - importsZ && - tokens[at + 1]?.text === "from" && - isIncurSpecifier(source, tokens[at + 2]) - ) - count += 1; - index = at; + const bindings = incurBindings(source, tokens, index); + if (bindings !== undefined) declarations.push(bindings); } - return count; + return declarations; }; + +/** Declarations that take zod's `z` from incur. @param {string} source */ +export const incurZodImportCount = (source) => + incurDeclarations(source).filter((names) => names.includes("z")).length; + +/** + * Bindings taken from incur: one per named binding, and one for each default, + * namespace, star, side-effect or dynamic import. @param {string} source + */ +export const incurImportedNameCount = (source) => + incurDeclarations(source).reduce((count, names) => count + names.length, 0); diff --git a/src/cli/argvParser.ts b/src/cli/argvParser.ts index 5edf535efc..484145daca 100644 --- a/src/cli/argvParser.ts +++ b/src/cli/argvParser.ts @@ -1,6 +1,11 @@ import { z } from "zod"; import { err, ok, type Result } from "../domain/result.js"; +import { + declaredOptionType, + isCountOption, + optionFlagName, +} from "./optionFields.js"; /** * REA's argv parser for one command: binds tokens to the command's @@ -55,21 +60,6 @@ export interface CliParsedArgv { readonly options: Record; } -const kebabCase = (key: string): string => - key.replaceAll(/[A-Z]/gu, (letter) => `-${letter.toLowerCase()}`); - -/** The declared type below optional, default, nullable and similar wrappers. */ -const declaredType = (field: z.ZodType): z.ZodType => { - let current = field; - for ( - let inner: unknown = Reflect.get(current.def, "innerType"); - inner instanceof z.ZodType; - inner = Reflect.get(current.def, "innerType") - ) - current = inner; - return current; -}; - const fieldOf = ( schema: z.ZodObject | undefined, name: string, @@ -80,23 +70,27 @@ const fieldOf = ( const isBoolean = (schema: z.ZodObject | undefined, name: string): boolean => { const field = fieldOf(schema, name); - return field !== undefined && declaredType(field) instanceof z.ZodBoolean; + return ( + field !== undefined && declaredOptionType(field) instanceof z.ZodBoolean + ); }; /** A count option (`.meta({ count: true })`) adds one per occurrence. */ -const isCount = (schema: z.ZodObject | undefined, name: string): boolean => - fieldOf(schema, name)?.meta()?.count === true; +const isCount = (schema: z.ZodObject | undefined, name: string): boolean => { + const field = fieldOf(schema, name); + return field !== undefined && isCountOption(field); +}; const isArray = (schema: z.ZodObject | undefined, name: string): boolean => { const field = fieldOf(schema, name); - return field !== undefined && declaredType(field) instanceof z.ZodArray; + return field !== undefined && declaredOptionType(field) instanceof z.ZodArray; }; /** Number and boolean options arrive as text; the schema validates the result. */ const coerce = (value: unknown, schema: z.ZodObject, name: string): unknown => { const field = fieldOf(schema, name); if (field === undefined || typeof value !== "string") return value; - const type = declaredType(field); + const type = declaredOptionType(field); if (type instanceof z.ZodNumber) return Number(value); if (type instanceof z.ZodBoolean) return value === "true"; return value; @@ -151,7 +145,9 @@ export const parseCliArgv = ( ); const camelOf = new Map( [...known].flatMap((name) => - kebabCase(name) === name ? [] : [[kebabCase(name), name] as const], + optionFlagName(name) === name + ? [] + : [[optionFlagName(name), name] as const], ), ); const optionName = (raw: string): string | undefined => { diff --git a/src/cli/cliOutputFormatter.ts b/src/cli/cliOutputFormatter.ts index 378051aed0..88267c04aa 100644 --- a/src/cli/cliOutputFormatter.ts +++ b/src/cli/cliOutputFormatter.ts @@ -1,5 +1,6 @@ /* - * Markdown output layout is adapted from Incur's Formatter. + * The TOON, JSON, YAML and JSON Lines encodings and the Markdown layout are + * adapted from Incur's Formatter. * Copyright (c) 2025-present weth, LLC * * Permission is hereby granted, free of charge, to any person obtaining a copy @@ -20,13 +21,18 @@ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS * IN THE SOFTWARE. */ -import { Formatter } from "incur"; +import { createRequire } from "node:module"; +import { encode as encodeToon } from "@toon-format/toon"; + +import type { CliOutputFormat } from "../cliOutput.js"; import { AnalysisInputError } from "../domain/analysisErrorCore.js"; import { projectAnalysisError } from "../domain/analysisErrorProjection.js"; import { err, ok, type Result } from "../domain/result.js"; import { isRecord } from "../kernel/isRecord.js"; +type Yaml = typeof import("yaml"); + export interface CliDelimitedOutputOptions { readonly fields: readonly string[]; readonly metadata: Readonly>; @@ -95,10 +101,10 @@ export interface PreparedDelimitedOutput { readonly format: "csv" | "tsv"; } -/** Keep REA's Markdown layout compatible with Incur while owning table safety. */ +/** Render one CLI result document in the selected output format. */ export const formatCliOutput = ( value: unknown, - format: Formatter.Format | "csv" | "tsv", + format: CliOutputFormat, delimited?: CliDelimitedOutputOptions, ): string => { if (format === "csv" || format === "tsv") { @@ -112,11 +118,58 @@ export const formatCliOutput = ( ); return prepared.ok ? [...formatDelimitedOutputParts(prepared.value)].join("") - : Formatter.format(projectAnalysisError(prepared.error), "json"); + : formatDocument(projectAnalysisError(prepared.error), "json"); } return format === "md" ? formatMarkdown(value) - : Formatter.format(value, format); + : formatDocument(value, format); +}; + +/** JSON with BigInt values written as decimal strings. */ +const stringifyJson = (value: unknown, indent?: number): string => + JSON.stringify( + value, + (_key, child: unknown) => + typeof child === "bigint" ? child.toString() : child, + indent, + ); + +/** YAML loads on first use, so runs that never select it skip its startup. */ +let yaml: Yaml | undefined; +const loadYaml = (): Yaml => + (yaml ??= createRequire(import.meta.url)("yaml") as Yaml); + +/** Text that already holds a JSON object or array is re-indented, not quoted. */ +const formatJson = (value: unknown): string => { + if (typeof value === "string") { + const trimmed = value.trim(); + if (trimmed.startsWith("{") || trimmed.startsWith("[")) + try { + return JSON.stringify(JSON.parse(value), null, 2); + } catch { + // Not JSON after all; encode it as a JSON string below. + } + } + return stringifyJson(value, 2); +}; + +const formatDocument = ( + value: unknown, + format: "toon" | "json" | "yaml" | "jsonl", +): string => { + if (value === null || value === undefined) return ""; + switch (format) { + case "json": + return formatJson(value); + case "yaml": + return loadYaml().stringify(value); + case "jsonl": + return Array.isArray(value) + ? value.map((item) => stringifyJson(item)).join("\n") + : stringifyJson(value); + case "toon": + return isScalar(value) ? String(value) : encodeToon(value); + } }; /** Validate a complete row page before the caller writes any output. */ diff --git a/src/cli/cliResultOutput.ts b/src/cli/cliResultOutput.ts index 3f8dc41443..619549969e 100644 --- a/src/cli/cliResultOutput.ts +++ b/src/cli/cliResultOutput.ts @@ -1,7 +1,6 @@ import { constants } from "node:buffer"; import type { Writable } from "node:stream"; -import { Filter } from "incur"; import { estimateTokenCount } from "tokenx"; import { analysisErrorProjectionSchema } from "../domain/analysisErrorProjectionSchema.js"; @@ -44,6 +43,7 @@ import { type CliResultControls, } from "./cliResultControls.js"; import { jsonLinesErrorRecord } from "./jsonLines.js"; +import type { OutputFilterPath } from "./outputFilter.js"; import { writeCliJsonLines } from "./jsonLinesOutput.js"; import { jsonOutputParts, @@ -459,8 +459,8 @@ export const createCliResultOutput = ( receipt: cliEvidencePublicationReceipt(), originalFailure: cliOperationFailureIdentity(value), }; - const filterPaths = options.filterOutput - ? Filter.parse(options.filterOutput) + const filterPaths = options.filterPaths?.ok + ? options.filterPaths.value : undefined; const operationFailure = metadata.failure ? value @@ -909,9 +909,6 @@ const fullFailureEnvelope = ( }; }; -type FilterPaths = ReturnType; -type FilterPath = FilterPaths[number]; - interface DelimitedRowsSelection { readonly rows: readonly unknown[]; readonly path: readonly string[]; @@ -920,7 +917,7 @@ interface DelimitedRowsSelection { const resolveDelimitedRows = ( source: unknown, - paths: FilterPaths | undefined, + paths: readonly OutputFilterPath[] | undefined, operation: string, ): Result => { const invalidSelection = (): Result => @@ -1015,7 +1012,7 @@ type FilterProjection = Result; const applyCliOutputFilter = ( value: unknown, - paths: FilterPaths, + paths: readonly OutputFilterPath[], ): FilterProjection => { if (paths.length === 0) return ok(value); if (Array.isArray(value)) { @@ -1064,8 +1061,8 @@ const applyCliOutputFilter = ( /** Preserve implicit traversal through every root-array layer before merging slices. */ const expandImplicitArrayPath = ( value: unknown, - path: FilterPath, -): FilterPaths => { + path: OutputFilterPath, +): readonly OutputFilterPath[] => { if (Array.isArray(value)) return value.flatMap((item, index) => expandImplicitArrayPath(item, path).map((tail) => [ @@ -1086,10 +1083,10 @@ const expandImplicitArrayPath = ( /** Build a fresh object projection; a path ending at a key selects its subtree. */ const projectObjectPaths = ( value: unknown, - paths: FilterPaths, + paths: readonly OutputFilterPath[], ): FilterProjection => { if (typeof value !== "object" || value === null) return ok({}); - const byKey = new Map(); + const byKey = new Map(); for (const path of paths) { const [segment, ...tail] = path; if (segment === undefined || !("key" in segment)) continue; @@ -1117,7 +1114,7 @@ const projectObjectPaths = ( /** Keep key-only array projections compatible; mixed projections use source indices. */ const projectChildPaths = ( value: unknown, - paths: FilterPaths, + paths: readonly OutputFilterPath[], ): FilterProjection => { if (typeof value !== "object" || value === null) return ok(undefined); return Array.isArray(value) && @@ -1129,10 +1126,10 @@ const projectChildPaths = ( /** Union sliced rows and explicit array indices, then emit them in source order. */ const projectArraySlices = ( source: readonly unknown[], - paths: readonly FilterPath[], + paths: readonly OutputFilterPath[], ): FilterProjection => { - const selected = new Map(); - const select = (index: number, tail: FilterPath): void => { + const selected = new Map(); + const select = (index: number, tail: OutputFilterPath): void => { const siblings = selected.get(index) ?? []; siblings.push(tail); selected.set(index, siblings); diff --git a/src/cli/commandRegistry.ts b/src/cli/commandRegistry.ts index e42dd15b19..25e75ebb3e 100644 --- a/src/cli/commandRegistry.ts +++ b/src/cli/commandRegistry.ts @@ -5,6 +5,7 @@ import type { ContractCliDocumentDescription, } from "./contractCliDescription.js"; import type { CliInstance } from "./types.js"; +import { optionFlagName } from "./optionFields.js"; /** One contract operation a command can run, with the flag of each field it takes. */ export interface CliCommandOperation { @@ -118,9 +119,6 @@ export const registerCliCommand = < export const cliCommands = (cli: CliInstance): readonly CliCommandEntry[] => registries.get(cli) ?? []; -const kebabCase = (key: string): string => - key.replaceAll(/[A-Z]/gu, (letter) => `-${letter.toLowerCase()}`); - /** * The operations one contract description runs: its own contract, the * contract that opens its session target, and the source of its Evidence @@ -147,7 +145,7 @@ export const contractDescriptionOperations = ( flags: Object.fromEntries( sessionTarget.options.map(({ field, key }) => [ field, - `--${kebabCase(key)}`, + `--${optionFlagName(key)}`, ]), ), }, diff --git a/src/cli/completionProtocol.ts b/src/cli/completionProtocol.ts index a131ea5f06..0a76572bee 100644 --- a/src/cli/completionProtocol.ts +++ b/src/cli/completionProtocol.ts @@ -1,5 +1,11 @@ import { z } from "zod"; +import { + declaredOptionType, + isCountOption, + optionFlagName, +} from "./optionFields.js"; + /** * REA's shell completion protocol: the hook script each shell sources, the * candidates for the words before the cursor, and their per-shell encoding. @@ -128,31 +134,11 @@ export const completionScript = ( } }; -const kebab = (key: string): string => - key.replace(/[A-Z]/gu, (character) => `-${character.toLowerCase()}`); - -/** Strip wrappers (optional, default, nullable, ...) to the declared value type. */ -const declaredType = (field: z.ZodType): z.ZodType => { - let current = field; - for ( - let inner = innerType(current); - inner !== undefined; - inner = innerType(current) - ) - current = inner; - return current; -}; - -const innerType = (field: z.ZodType): z.ZodType | undefined => { - const inner: unknown = Reflect.get(field._zod.def, "innerType"); - return inner instanceof z.ZodType ? inner : undefined; -}; - const isFlagOption = (field: z.ZodType): boolean => - field.meta()?.count === true || declaredType(field) instanceof z.ZodBoolean; + isCountOption(field) || declaredOptionType(field) instanceof z.ZodBoolean; const enumValues = (field: z.ZodType): readonly string[] | undefined => { - const type = declaredType(field); + const type = declaredOptionType(field); return type instanceof z.ZodEnum ? type.options.map((value) => String(value)) : undefined; @@ -168,7 +154,7 @@ const optionKey = ( if (token.startsWith("--")) { const raw = token.slice(2); return ( - keys.find((key) => kebab(key) === raw) ?? + keys.find((key) => optionFlagName(key) === raw) ?? (keys.includes(raw) ? raw : undefined) ); } @@ -191,7 +177,7 @@ const flagCandidates = ( ) candidates.push({ value, description: shape[key]?.description }); }; - for (const key of Object.keys(shape)) add(`--${kebab(key)}`, key); + for (const key of Object.keys(shape)) add(`--${optionFlagName(key)}`, key); for (const [key, short] of Object.entries(alias ?? {})) add(`-${short}`, key); }; diff --git a/src/cli/contractCliDescription.ts b/src/cli/contractCliDescription.ts index d6b2fc2aa2..78c90e79b4 100644 --- a/src/cli/contractCliDescription.ts +++ b/src/cli/contractCliDescription.ts @@ -25,6 +25,7 @@ import { selectCliAnalysisSelector, type CliSelectorKind, } from "./analysisSelector.js"; +import { optionFlagName } from "./optionFields.js"; /** * Framework-neutral CLI description of a tool contract. This module owns @@ -783,13 +784,6 @@ const describedThroughWrappers = (value: z.ZodType): string | undefined => { return current.description; }; -/** - * Accept only field forms argv can carry, so a new contract field cannot - * reach the CLI with an unreviewed spelling. - */ -const kebabCase = (key: string): string => - key.replaceAll(/[A-Z]/gu, (letter) => `-${letter.toLowerCase()}`); - /** * JSON text for a structured contract field. Argv carries text; the decoded * value is admitted by the contract field itself, so `--schema` advertises @@ -1535,7 +1529,7 @@ const describeEvidenceTargets = ( targets: described, options, sourceFlags: Object.fromEntries( - options.map(({ field, key }) => [field, `--${kebabCase(key)}`]), + options.map(({ field, key }) => [field, `--${optionFlagName(key)}`]), ), admitSource: (operation, values) => { let admitted: Result< @@ -1924,7 +1918,7 @@ export const describeContractCommand = < viewDelivery?.viewSelectsSummary === true ? analysisEvidenceDeliveryOptions.detail.unwrap().optional() : analysisEvidenceDeliveryOptions.detail; - else if (jsonText) schema = jsonTextField(declared, kebabCase(key)); + else if (jsonText) schema = jsonTextField(declared, optionFlagName(key)); else if (callerPath) { const admitted = core(declared) instanceof z.ZodArray @@ -2455,8 +2449,8 @@ export const describeContractCommand = < if (positional) return selectorOption === undefined ? [] - : [[field, `--${kebabCase(selectorOption.key)}`] as const]; - const flag = `--${kebabCase(key)}`; + : [[field, `--${optionFlagName(selectorOption.key)}`] as const]; + const flag = `--${optionFlagName(key)}`; // A field group's option supplies each of its contract fields. if (group !== undefined) return group.map((grouped) => [grouped, flag] as const); diff --git a/src/cli/contractCommand.ts b/src/cli/contractCommand.ts index 87354286be..f1a7f7fc59 100644 --- a/src/cli/contractCommand.ts +++ b/src/cli/contractCommand.ts @@ -66,6 +66,7 @@ import { } from "./commandRegistry.js"; import type { CliInstance } from "./types.js"; import { isRecord } from "../kernel/isRecord.js"; +import { optionFlagName } from "./optionFields.js"; /** * Incur adapter for contract commands. The command itself is described in @@ -985,7 +986,7 @@ export const registerRoutedCommand = ( refused.map((key) => ({ path: [key], reason: "invalid_value" as const, - message: `--${kebabCase(key)} requires ${owners.get(key)!.requirement}; the given input selects ${route.requirement}, which does not take it.`, + message: `--${optionFlagName(key)} requires ${owners.get(key)!.requirement}; the given input selects ${route.requirement}, which does not take it.`, })), ), ); @@ -1063,9 +1064,6 @@ const withCliOnlyDefaults = ( ), }); -const kebabCase = (key: string): string => - key.replaceAll(/[A-Z]/gu, (letter) => `-${letter.toLowerCase()}`); - /** What a JSON-document command's handler receives besides the document. */ export interface ContractDocumentContext< CliOptions extends Readonly> = Readonly< diff --git a/src/cli/help.ts b/src/cli/help.ts new file mode 100644 index 0000000000..1202ec0608 --- /dev/null +++ b/src/cli/help.ts @@ -0,0 +1,139 @@ +import { z } from "zod"; + +import { declaredOptionType, optionFlagName } from "./optionFields.js"; + +/** + * REA's command help text. The layout is the one the CLI has always printed: + * a `name — description` title, a usage line, aligned option rows with type + * placeholders and shown defaults, an optional hint, then the global options the + * entry accepts. + */ + +/** The global options block of an entry that accepts them. */ +export interface GlobalOptionsHelp { + /** The `--format` values this entry accepts, in display order. */ + readonly formats: readonly string[]; +} + +export interface CommandHelp { + readonly description?: string | undefined; + readonly options?: z.ZodObject | undefined; + /** Short alias by option key, such as `{ help: "h" }`. */ + readonly alias?: Readonly> | undefined; + /** A paragraph printed after the options. */ + readonly hint?: string | undefined; + /** Omitted for an entry that accepts only its own options. */ + readonly globalOptions?: GlobalOptionsHelp | undefined; +} + +interface Row { + readonly label: string; + readonly description: string; +} + +/** Two-column rows with the descriptions aligned after the longest label. */ +const alignedRows = (rows: readonly Row[]): string[] => { + const width = Math.max(...rows.map((row) => row.label.length)); + return rows.map( + (row) => + ` ${row.label}${" ".repeat(width - row.label.length)} ${row.description}`, + ); +}; + +/** The placeholder shown after a value-taking flag. */ +const typeName = (field: z.ZodType): string => { + const type = declaredOptionType(field); + if (type instanceof z.ZodString) return "string"; + if (type instanceof z.ZodNumber) return "number"; + if (type instanceof z.ZodBoolean) return "boolean"; + if (type instanceof z.ZodArray) return "array"; + if (type instanceof z.ZodEnum) + return type.options.map((value) => String(value)).join("|"); + if ( + type instanceof z.ZodUnion && + type.options.every((option) => option instanceof z.ZodLiteral) + ) + return type.options.map((option) => String(option.value)).join("|"); + return "value"; +}; + +/** A shown default; empty arrays and a `false` boolean default are not shown. */ +const shownDefault = (field: z.ZodType, type: string): unknown => { + const value = + field instanceof z.ZodDefault + ? (field.def.defaultValue as unknown) + : field instanceof z.ZodOptional + ? shownDefault(field.unwrap() as z.ZodType, type) + : undefined; + if (Array.isArray(value) && value.length === 0) return undefined; + if (type === "boolean" && value === false) return undefined; + return value; +}; + +const optionRows = ( + options: z.ZodObject, + alias: Readonly> | undefined, +): Row[] => + Object.entries(options.shape as Readonly>).map( + ([key, field]) => { + const type = typeName(field); + const short = alias?.[key]; + const value = type === "boolean" ? "" : ` <${type}>`; + const label = `--${optionFlagName(key)}${short === undefined ? "" : `, -${short}`}${value}`; + const defaultValue = shownDefault(field, type); + const description = field.description ?? ""; + return { + label, + description: + defaultValue === undefined + ? description + : `${description} (default: ${String(defaultValue)})`, + }; + }, + ); + +/** The global options every command entry accepts, sorted by flag. */ +const globalOptionRows = ({ formats }: GlobalOptionsHelp): Row[] => + [ + { + label: "--filter-output ", + description: "Filter output by key paths (e.g. foo,bar.baz,a[0,3])", + }, + { label: `--format <${formats.join("|")}>`, description: "Output format" }, + { label: "--help", description: "Show help" }, + { + label: "--llms, --llms-full", + description: "Print LLM-readable manifest", + }, + { label: "--schema", description: "Show JSON Schema for command" }, + { + label: "--token-count", + description: "Print token count of output (instead of output)", + }, + { label: "--token-limit ", description: "Limit output to n tokens" }, + { + label: "--token-offset ", + description: "Skip first n tokens of output", + }, + { label: "--full-output", description: "Show full output envelope" }, + ].sort((left, right) => left.label.localeCompare(right.label)); + +/** Render one command's help, without a trailing newline. */ +export const formatCommandHelp = (name: string, help: CommandHelp): string => { + const lines = [ + help.description === undefined ? name : `${name} — ${help.description}`, + "", + `Usage: ${name}${help.options === undefined ? "" : " [options]"}`, + ]; + const options = + help.options === undefined ? [] : optionRows(help.options, help.alias); + if (options.length > 0) lines.push("", "Options:", ...alignedRows(options)); + if (help.hint !== undefined) lines.push("", help.hint); + if (help.globalOptions !== undefined) + lines.push( + "", + "Global Options:", + ...alignedRows(globalOptionRows(help.globalOptions)), + ); + return lines.join("\n"); +}; diff --git a/src/cli/jsonLines.ts b/src/cli/jsonLines.ts index f0457b8cb4..09d0264a18 100644 --- a/src/cli/jsonLines.ts +++ b/src/cli/jsonLines.ts @@ -1,10 +1,9 @@ -import type { Filter } from "incur"; - import { err, ok, type Result } from "../domain/result.js"; import { AnalysisInputError } from "../domain/analysisErrorCore.js"; import { jsonParts } from "../domain/jsonSerialization.js"; import { isRecord } from "../kernel/isRecord.js"; +import type { OutputFilterPath } from "./outputFilter.js"; /** Reserved control-record marker, not an advertised external JSON Schema. */ export const JSON_LINES_PROTOCOL = "jsonl/v1"; @@ -147,7 +146,7 @@ const describe = ({ path, shape }: Observation): string => /** Caller-visible key paths, before any slice, selected by --filter-output. */ const selectionPaths = ( - paths: ReturnType | undefined, + paths: readonly OutputFilterPath[] | undefined, ): string[][] => { const selected = new Map(); for (const path of paths ?? []) { @@ -201,7 +200,7 @@ interface JsonLinesOptions { readonly source?: unknown; readonly filter?: string; /** Parsed --filter-output paths, used only to name the refused selection. */ - readonly filterPaths?: ReturnType; + readonly filterPaths?: readonly OutputFilterPath[]; readonly fullOutput?: boolean; } diff --git a/src/cli/jsonLinesOutput.ts b/src/cli/jsonLinesOutput.ts index 458cdc9f0b..9a04b5eb19 100644 --- a/src/cli/jsonLinesOutput.ts +++ b/src/cli/jsonLinesOutput.ts @@ -1,6 +1,5 @@ import { constants } from "node:buffer"; import type { Writable } from "node:stream"; -import type { Filter } from "incur"; import { estimateTokenCount } from "tokenx"; import { AnalysisResourceConstraintError } from "../domain/analysisErrorCore.js"; @@ -22,6 +21,7 @@ import { } from "./jsonOutput.js"; import { retainCliPublicationOnError } from "./cliEvidencePublication.js"; import type { CliResultControls } from "./cliResultControls.js"; +import type { OutputFilterPath } from "./outputFilter.js"; interface CliJsonLinesInput { readonly source: unknown; @@ -34,7 +34,7 @@ interface CliJsonLinesInput { readonly fullOutput: boolean; readonly tokenCount: boolean; readonly filterOutput: string | undefined; - readonly filterPaths: ReturnType | undefined; + readonly filterPaths: readonly OutputFilterPath[] | undefined; } /** Render one already classified result, sharing a plan for output and counting. */ diff --git a/src/cli/mcpRegistration.ts b/src/cli/mcpRegistration.ts index e07c5683a9..8e93024a83 100644 --- a/src/cli/mcpRegistration.ts +++ b/src/cli/mcpRegistration.ts @@ -1,7 +1,6 @@ import { HOST_PLATFORM } from "../platform/HostPlatform.js"; import { Writable } from "node:stream"; -import { Help } from "incur"; import { z } from "zod"; import { @@ -25,6 +24,7 @@ import { splitIncurBuiltinArguments, } from "../cliBuiltinArguments.js"; import { + CLI_DOCUMENT_OUTPUT_FORMATS, parseCliOutputArguments, renderCliDocument, renderCliOutputArgumentError, @@ -48,6 +48,7 @@ import { redactExplicitText } from "../domain/explicitSensitiveValues.js"; import { err, ok, type Result } from "../domain/result.js"; import { PRODUCT_IDENTITY } from "../identity.js"; import { createCliResultOutput } from "./cliResultOutput.js"; +import { formatCommandHelp } from "./help.js"; import { withCommandCancellation } from "./commandCancellation.js"; import type { CliInstance } from "./types.js"; import { ownCliProcessResource } from "./cliResources.js"; @@ -240,12 +241,13 @@ const serveRegistrationDiscovery = async ( ): Promise => { if (flags.has("--help") || flags.has("-h")) { presentation.write( - `${Help.formatCommand("rea mcp add", { + `${formatCommandHelp("rea mcp add", { description: "Register exact stdio launcher arguments in selected client settings, with backups and verified publication.", options: mcpRegistrationOptionsSchema, alias: { command: "c" }, hint: "No package acquisition or server execution. --no-global never writes global settings.", + globalOptions: { formats: CLI_DOCUMENT_OUTPUT_FORMATS }, })}\n`, ); return true; diff --git a/src/cli/optionFields.ts b/src/cli/optionFields.ts new file mode 100644 index 0000000000..0372a2b67c --- /dev/null +++ b/src/cli/optionFields.ts @@ -0,0 +1,28 @@ +import { z } from "zod"; + +/** + * How a command's option schema field is spelled and typed on the command + * line. Option keys are camelCase; each is spelled `--kebab-case`. Help, + * completion and argument parsing read fields through these helpers so the + * spelling and the unwrapped type have one owner. + */ + +/** The `--flag` spelling of an option key, without the dashes. */ +export const optionFlagName = (key: string): string => + key.replaceAll(/[A-Z]/gu, (letter) => `-${letter.toLowerCase()}`); + +/** The declared type below optional, default, nullable and similar wrappers. */ +export const declaredOptionType = (field: z.ZodType): z.ZodType => { + let current = field; + for ( + let inner: unknown = Reflect.get(current.def, "innerType"); + inner instanceof z.ZodType; + inner = Reflect.get(current.def, "innerType") + ) + current = inner; + return current; +}; + +/** A count option (`.meta({ count: true })`) adds one per occurrence. */ +export const isCountOption = (field: z.ZodType): boolean => + field.meta()?.count === true; diff --git a/src/cli/outputFilter.ts b/src/cli/outputFilter.ts new file mode 100644 index 0000000000..edb29977a7 --- /dev/null +++ b/src/cli/outputFilter.ts @@ -0,0 +1,78 @@ +/** + * The `--filter-output` path grammar: comma-separated paths of dot-separated + * keys, each optionally followed by a `[start,end]` array slice, such as + * `foo,bar.baz,a[0,3].name`. Commas inside brackets belong to the slice. + * Projection of a result through these paths is owned by the CLI result + * writer and the JSON Lines selector. + */ +import { err, ok, type Result } from "../domain/result.js"; + +/** One step of a filter path: an object key or an array slice. */ +export type OutputFilterSegment = + | { readonly key: string } + | { readonly start: number; readonly end: number }; + +export type OutputFilterPath = readonly OutputFilterSegment[]; + +/** A `[` with no later `]` in its path: the slice has no end. */ +export interface UnclosedOutputFilterSlice { + readonly kind: "unclosed_slice"; +} + +/** Split on commas outside `[...]`; an empty last path is dropped. */ +const splitPaths = (expression: string): string[] => { + const paths: string[] = []; + let current = ""; + let depth = 0; + for (const character of expression) { + if (character === "[") depth += 1; + else if (character === "]") depth -= 1; + if (character === "," && depth === 0) { + paths.push(current); + current = ""; + } else current += character; + } + if (current !== "") paths.push(current); + return paths; +}; + +const keySegments = (text: string): OutputFilterSegment[] => + text + .split(".") + .filter((key) => key !== "") + .map((key) => ({ key })); + +const parsePath = ( + text: string, +): Result => { + const segments: OutputFilterSegment[] = []; + let remaining = text; + while (remaining.length > 0) { + const open = remaining.indexOf("["); + if (open === -1) { + segments.push(...keySegments(remaining)); + break; + } + const close = remaining.indexOf("]", open); + if (close === -1) return err({ kind: "unclosed_slice" }); + segments.push(...keySegments(remaining.slice(0, open))); + const [start, end] = remaining.slice(open + 1, close).split(","); + segments.push({ start: Number(start), end: Number(end) }); + remaining = remaining.slice(close + 1); + if (remaining.startsWith(".")) remaining = remaining.slice(1); + } + return ok(segments); +}; + +/** Parse a `--filter-output` expression into its paths. */ +export const parseOutputFilter = ( + expression: string, +): Result => { + const paths: OutputFilterPath[] = []; + for (const text of splitPaths(expression)) { + const path = parsePath(text); + if (!path.ok) return path; + paths.push(path.value); + } + return ok(paths); +}; diff --git a/src/cli/strictPositionals.ts b/src/cli/strictPositionals.ts index 10c4feba52..72e3077813 100644 --- a/src/cli/strictPositionals.ts +++ b/src/cli/strictPositionals.ts @@ -7,20 +7,10 @@ import { splitIncurBuiltinArguments } from "../cliBuiltinArguments.js"; import { parseCliArgv } from "./argvParser.js"; import type { CliInstance } from "./types.js"; import { visitRegisteredCommands } from "./visitRegisteredCommands.js"; +import { declaredOptionType, isCountOption } from "./optionFields.js"; type ServeOptions = NonNullable[1]>; -/** Match the wrapper types the argv parser unwraps for token binding. */ -const tokenType = (field: z.ZodType): z.ZodType => { - let inner = field; - while ("innerType" in inner.def) { - const candidate = inner.def.innerType; - if (!(candidate instanceof z.ZodType)) break; - inner = candidate; - } - return inner; -}; - /** Preserve flag consumption without evaluating command defaults or transforms. */ const optionTokenShape = ( schema: z.ZodObject, @@ -29,7 +19,7 @@ const optionTokenShape = ( z.object( Object.fromEntries( Object.entries(schema.shape).map(([name, field]) => { - const inner = tokenType(field); + const inner = declaredOptionType(field); const token = inner instanceof z.ZodBoolean && !(strictDryRun && name === "dryRun") ? z.boolean().optional() @@ -38,7 +28,7 @@ const optionTokenShape = ( : z.unknown().optional(); return [ name, - field.meta()?.count === true ? token.meta({ count: true }) : token, + isCountOption(field) ? token.meta({ count: true }) : token, ]; }), ), @@ -67,10 +57,10 @@ export const validateCliArguments = ( const dryRunField = optionsSchema?.shape["dryRun"]; const strictDryRun = dryRunField !== undefined && - tokenType(dryRunField) instanceof z.ZodBoolean; + declaredOptionType(dryRunField) instanceof z.ZodBoolean; const final = entries.at(-1)?.[1]; const variadic = - final !== undefined && tokenType(final) instanceof z.ZodArray; + final !== undefined && declaredOptionType(final) instanceof z.ZodArray; // A final array consumes the tail, but must still admit dry-run literals. if (variadic && !strictDryRun) return; let tail = "__rea_unbound_positionals"; @@ -86,7 +76,7 @@ export const validateCliArguments = ( ...Object.fromEntries( entries.map(([name, field]) => [ name, - tokenType(field) instanceof z.ZodArray + declaredOptionType(field) instanceof z.ZodArray ? z.array(z.unknown()).optional() : z.unknown().optional(), ]), diff --git a/src/cliOutput.ts b/src/cliOutput.ts index 928961a39b..71f4ed47cf 100644 --- a/src/cliOutput.ts +++ b/src/cliOutput.ts @@ -4,6 +4,12 @@ import { } from "./cliBuiltinArguments.js"; import { redactExplicitText } from "./domain/explicitSensitiveValues.js"; import { formatCliOutput } from "./cli/cliOutputFormatter.js"; +import { + parseOutputFilter, + type OutputFilterPath, + type UnclosedOutputFilterSlice, +} from "./cli/outputFilter.js"; +import type { Result } from "./domain/result.js"; import { jsonOutputParts } from "./cli/jsonOutput.js"; import { jsonLinesErrorRecord } from "./cli/jsonLines.js"; @@ -94,6 +100,10 @@ export type CliOutputArgumentValidation = interface CliOutputControls { readonly filterOutput: string | undefined; + /** `--filter-output` parsed once; a parse failure fails validation. */ + readonly filterPaths: + | Result + | undefined; readonly columns: readonly string[] | undefined; readonly format: CliOutputFormat; /** Whether `--json` or `--format` selected the format, rather than the default. */ @@ -134,6 +144,10 @@ export const parseCliOutputArguments = ( const parseError = invalidValue !== undefined; const controls: CliOutputControls = { filterOutput, + filterPaths: + filterOutput === undefined + ? undefined + : parseOutputFilter(filterOutput), columns, format, formatExplicit, @@ -238,24 +252,6 @@ export const parseCliOutputArguments = ( return parsed(); }; -/** Reject slices that cannot advance within Incur's comma-delimited paths. */ -const hasUnclosedFilterSlice = (expression: string): boolean => { - let depth = 0; - let unclosed = false; - for (const character of expression) { - if (character === "[") { - depth += 1; - unclosed = true; - } else if (character === "]") { - depth -= 1; - // Incur consumes everything through the next closing bracket, including - // nested opening brackets. Do not impose a different filter grammar. - unclosed = false; - } else if (character === "," && depth === 0 && unclosed) return true; - } - return unclosed; -}; - /** Name a valued output flag that was given without a value. */ export const missingCliOutputValueMessage = (flag: string): string => `${flag} requires a value, as in ${flag} or ${flag}=.`; @@ -264,6 +260,7 @@ export const missingCliOutputValueMessage = (flag: string): string => const validateCliOutputControls = ( { filterOutput, + filterPaths, columns, format, missingValue, @@ -280,7 +277,7 @@ const validateCliOutputControls = ( code: "INVALID_OUTPUT_VALUE", message: invalidValue, }; - if (filterOutput !== undefined && hasUnclosedFilterSlice(filterOutput)) + if (filterPaths?.ok === false) return { ok: false, format: format === "yaml" || format === "jsonl" ? format : "json", diff --git a/src/main/mcpHttpArguments.ts b/src/main/mcpHttpArguments.ts index dd2566e789..8d6e612c87 100644 --- a/src/main/mcpHttpArguments.ts +++ b/src/main/mcpHttpArguments.ts @@ -1,4 +1,4 @@ -import { Help } from "incur"; +import { formatCommandHelp } from "../cli/help.js"; import { z } from "zod"; import type { HttpHostname } from "../domain/httpHostname.js"; @@ -46,11 +46,10 @@ const VALUED_FLAGS: ReadonlySet = new Set([ "--allowed-hosts", ]); -/** Render help for the dispatcher entry, which accepts no Incur global options. */ +/** Render help for the dispatcher entry, which accepts no global options. */ export const renderMcpHttpHelp = (): string => - Help.formatCommand(MCP_HTTP_COMMAND, { + formatCommandHelp(MCP_HTTP_COMMAND, { description: MCP_HTTP_DESCRIPTION, - hideGlobalOptions: true, options: MCP_HTTP_OPTIONS, alias: MCP_HTTP_ALIAS, hint: "This entry accepts only the options above. The bound URL is logged as one JSON line on stderr.", diff --git a/src/mcpDoctor.ts b/src/mcpDoctor.ts index 6b8f0fdbd2..30e04d83c8 100644 --- a/src/mcpDoctor.ts +++ b/src/mcpDoctor.ts @@ -1,6 +1,6 @@ import { Client, SdkError, SdkErrorCode } from "@modelcontextprotocol/client"; import { OwnedMcpClient } from "./process/OwnedMcpClient.js"; -import { Help } from "incur"; +import { formatCommandHelp } from "./cli/help.js"; import { performance } from "node:perf_hooks"; import { resolve } from "node:path"; import { StringDecoder } from "node:string_decoder"; @@ -54,14 +54,12 @@ const HELP_FLAGS: ReadonlySet = new Set(["--help", "-h"]); /** * Answer an advertised help request without starting a diagnostic session. - * Global options are hidden because this dispatcher entry accepts only the - * options above; the hint says so explicitly instead of implying full - * Incur parity. + * Global options are omitted because this dispatcher entry accepts only the + * options above; the hint says so explicitly. */ const renderMcpDoctorHelp = (): string => - Help.formatCommand(MCP_DOCTOR_COMMAND, { + formatCommandHelp(MCP_DOCTOR_COMMAND, { description: MCP_DOCTOR_DESCRIPTION, - hideGlobalOptions: true, options: MCP_DOCTOR_OPTIONS, alias: MCP_DOCTOR_ALIAS, hint: `${MCP_DOCTOR_SCOPE} This entry accepts only the options above.`, diff --git a/tests/acceptance/cliFormattingCapacity.test.ts b/tests/acceptance/cliFormattingCapacity.test.ts index 57ba5aa3d9..62f3963420 100644 --- a/tests/acceptance/cliFormattingCapacity.test.ts +++ b/tests/acceptance/cliFormattingCapacity.test.ts @@ -8,28 +8,41 @@ import { buildManagedPeFixture } from "../../src/dotnet/ManagedPe.fixture.js"; import { analysisErrorProjectionSchema } from "../../src/domain/analysisErrorProjectionSchema.js"; import { workspaceCliTest } from "../support/cli/workspaceCliFixture.js"; -// Exercise the real dispatcher and pinned formatter with an authored capacity -// failure. No engine-sized document or native target execution is needed. -const formatterFailure = ` - if (fmt !== "json" && fmt !== "jsonl" && - (value?.operation === "inspect_managed_artifact" || - value?.data?.operation === "inspect_managed_artifact" || - value?.code === "target_unavailable" || - value?.error?.code === "target_unavailable")) { +// Exercise the real dispatcher and the pinned TOON and YAML encoders with an +// authored capacity failure. No engine-sized document or native target +// execution is needed. +const encoderFailure = (value: string) => ` + if (${value}?.operation === "inspect_managed_artifact" || + ${value}?.data?.operation === "inspect_managed_artifact" || + ${value}?.code === "target_unavailable" || + ${value}?.error?.code === "target_unavailable") { process.stderr.write("REA_AUTHORED_FORMAT_CAPACITY\\n"); throw new RangeError("Invalid string length"); } `; -const incurCapacityHook = `data:text/javascript,${encodeURIComponent(` +const encoders = [ + { + file: "/@toon-format/toon/dist/index.mjs", + signature: "function encode(input, options) {", + failure: encoderFailure("input"), + }, + { + file: "/yaml/dist/public-api.js", + signature: "function stringify(value, replacer, options) {", + failure: encoderFailure("value"), + }, +]; +const encoderCapacityHook = `data:text/javascript,${encodeURIComponent(` import { registerHooks } from "node:module"; +const encoders = ${JSON.stringify(encoders)}; registerHooks({ load(url, context, next) { const loaded = next(url, context); - if (!url.endsWith("/incur/dist/Formatter.js")) return loaded; + const encoder = encoders.find(({ file }) => url.endsWith(file)); + if (encoder === undefined) return loaded; const source = String(loaded.source); - const signature = "export function format(value, fmt = 'toon') {"; - if (!source.includes(signature)) throw new Error("Pinned formatter boundary changed"); - return { ...loaded, source: source.replace(signature, signature + ${JSON.stringify(formatterFailure)}) }; + if (!source.includes(encoder.signature)) throw new Error("Pinned encoder boundary changed: " + encoder.file); + return { ...loaded, source: source.replace(encoder.signature, encoder.signature + encoder.failure) }; }, }); `)}`; @@ -107,7 +120,9 @@ for (const scenario of scenarios) ? `data:text/javascript,${encodeURIComponent('Object.defineProperty(process.stdout, "isTTY", { value: true });')}` : "data:text/javascript,", "--import", - scenario.format === "md" ? markdownCapacityHook : incurCapacityHook, + scenario.format === "md" + ? markdownCapacityHook + : encoderCapacityHook, resolve("scripts/rea.mjs"), "inspect-managed-artifact", target, @@ -161,7 +176,7 @@ workspaceCliTest.skipIf(process.platform === "win32")( process.execPath, [ "--import", - incurCapacityHook, + encoderCapacityHook, resolve("scripts/rea.mjs"), "inspect-managed-artifact", workspace.path("missing.dll"), diff --git a/tests/boundary/cli/cliFullOutputTokenCount.test.ts b/tests/boundary/cli/cliFullOutputTokenCount.test.ts index 6fd2628d30..38dda1f83e 100644 --- a/tests/boundary/cli/cliFullOutputTokenCount.test.ts +++ b/tests/boundary/cli/cliFullOutputTokenCount.test.ts @@ -1,9 +1,9 @@ import { Writable } from "node:stream"; -import { Formatter } from "incur"; import { estimateTokenCount } from "tokenx"; import { describe, expect, it } from "vitest"; +import { formatCliOutput } from "../../../src/cli/cliOutputFormatter.js"; import { parseCliOutputArguments } from "../../../src/cliOutput.js"; import { createCliResultOutput } from "../../../src/cli/cliResultOutput.js"; @@ -46,7 +46,7 @@ describe("full-output token counts for delegated formats", () => { expect(counted.handled).toBe(true); expect(counted.text).toBe( `${estimateTokenCount( - Formatter.format( + formatCliOutput( { ok: true, data: value, diff --git a/tests/boundary/cli/cliOutputFormatter.test.ts b/tests/boundary/cli/cliOutputFormatter.test.ts index d34a528962..eb1cb704a0 100644 --- a/tests/boundary/cli/cliOutputFormatter.test.ts +++ b/tests/boundary/cli/cliOutputFormatter.test.ts @@ -27,6 +27,54 @@ it.each([ }, ); +it.each<[string, unknown, "toon" | "json" | "yaml" | "jsonl", string]>([ + ["no value as TOON", null, "toon", ""], + ["no value as JSON", undefined, "json", ""], + ["no value as YAML", null, "yaml", ""], + ["a scalar as TOON", 12, "toon", "12"], + ["text as TOON", "text", "toon", "text"], + [ + "an object as TOON", + { a: 1, b: [1, 2], c: { d: "x" } }, + "toon", + "a: 1\nb[2]: 1,2\nc:\n d: x", + ], + [ + "rows as TOON", + [ + { id: 1, name: "a" }, + { id: 2, name: "b" }, + ], + "toon", + "[2]{id,name}:\n 1,a\n 2,b", + ], + ["JSON object text as JSON", ' {"a":1} ', "json", '{\n "a": 1\n}'], + ["JSON array text as JSON", "[1,2]", "json", "[\n 1,\n 2\n]"], + ["malformed JSON text as JSON", "{not json", "json", '"{not json"'], + ["plain text as JSON", "plain", "json", '"plain"'], + [ + "nested BigInt values as JSON", + { big: 9007199254740993n, nested: [1n, { x: 2n }] }, + "json", + '{\n "big": "9007199254740993",\n "nested": [\n "1",\n {\n "x": "2"\n }\n ]\n}', + ], + [ + "a BigInt value as JSON Lines", + { big: 9007199254740993n }, + "jsonl", + '{"big":"9007199254740993"}', + ], + ["rows as JSON Lines", [{ a: 1 }, { a: 2 }], "jsonl", '{"a":1}\n{"a":2}'], + [ + "an object as YAML", + { a: 1, b: [1, 2] }, + "yaml", + "a: 1\nb:\n - 1\n - 2\n", + ], +])("formats %s", (_name, value, format, expected) => { + expect(formatCliOutput(value, format)).toBe(expected); +}); + const parseDelimited = (source: string, delimiter: string): string[][] => { const records: string[][] = []; let record: string[] = []; diff --git a/tests/boundary/cli/cliResultControls.test.ts b/tests/boundary/cli/cliResultControls.test.ts index caee56b003..e85e3215c2 100644 --- a/tests/boundary/cli/cliResultControls.test.ts +++ b/tests/boundary/cli/cliResultControls.test.ts @@ -1,9 +1,10 @@ import { Writable } from "node:stream"; -import { Cli, Formatter } from "incur"; +import { Cli } from "incur"; import { expect, it, vi } from "vitest"; import { z } from "zod"; +import { formatCliOutput } from "../../../src/cli/cliOutputFormatter.js"; import { parseCliOutputArguments } from "../../../src/cliOutput.js"; import { registerContractCommand } from "../../../src/cli/contractCommand.js"; import { createCliResultOutput } from "../../../src/cli/cliResultOutput.js"; @@ -343,7 +344,7 @@ it.each(["yaml", "toon"] as const)( cliControls, ); expect(text).toBe( - `${Formatter.format( + `${formatCliOutput( { ok: true, data: partialResult(), diff --git a/tests/boundary/cli/cliTokenWindowOutput.test.ts b/tests/boundary/cli/cliTokenWindowOutput.test.ts index 09a9a9be38..bd35ee0531 100644 --- a/tests/boundary/cli/cliTokenWindowOutput.test.ts +++ b/tests/boundary/cli/cliTokenWindowOutput.test.ts @@ -1,9 +1,10 @@ import { Writable } from "node:stream"; -import { Cli, Formatter } from "incur"; +import { Cli } from "incur"; import { estimateTokenCount } from "tokenx"; import { describe, expect, it } from "vitest"; +import { formatCliOutput } from "../../../src/cli/cliOutputFormatter.js"; import { parseCliOutputArguments } from "../../../src/cliOutput.js"; import { createCliResultOutput, @@ -55,7 +56,7 @@ describe("successful CLI token windows", () => { const page = await renderWindow(value, 0, 1000, true); expect(page.handled).toBe(true); expect(page.text).toBe( - `${Formatter.format( + `${formatCliOutput( { ok: true, data: value, @@ -80,7 +81,7 @@ describe("successful CLI token windows", () => { const page = await renderWindow(value, 0, 1000, fullOutput); expect(page.handled).toBe(true); expect(page.text).toBe( - `${Formatter.format( + `${formatCliOutput( fullOutput ? { ok: true, @@ -126,7 +127,7 @@ describe("successful CLI token windows", () => { "6764c190e641f1c59c638f9bf32fee05f66992811c5605ebd25056156f21e221", text: "😀é".repeat(300), }; - const full = Formatter.format(value, "toon"); + const full = formatCliOutput(value, "toon"); const total = estimateTokenCount(full); const pages: string[] = []; for (let offset = 0; offset < total; offset += 10) { diff --git a/tests/boundary/cli/commandHelp.test.ts b/tests/boundary/cli/commandHelp.test.ts new file mode 100644 index 0000000000..57f372bd9f --- /dev/null +++ b/tests/boundary/cli/commandHelp.test.ts @@ -0,0 +1,56 @@ +import { expect, it } from "vitest"; +import { z } from "zod"; + +import { formatCommandHelp } from "../../../src/cli/help.js"; + +it("renders type placeholders, shown defaults and aliases", () => { + const options = z.object({ + limit: z.number().default(10).describe("Rows"), + mode: z.enum(["fast", "full"]).optional().describe("Mode"), + level: z + .union([z.literal("low"), z.literal("high")]) + .optional() + .describe("Level"), + names: z.array(z.string()).default([]).describe("Names"), + dryRun: z.boolean().default(false).describe("Dry run"), + yes: z.boolean().optional().describe("Assume yes"), + raw: z.unknown().optional().describe("Raw"), + }); + expect( + formatCommandHelp("rea sample", { + description: "Sample", + options, + alias: { yes: "y" }, + hint: "Hint.", + globalOptions: { formats: ["toon", "json", "csv"] }, + }), + ).toBe( + [ + "rea sample — Sample", + "", + "Usage: rea sample [options]", + "", + "Options:", + " --limit Rows (default: 10)", + " --mode Mode", + " --level Level", + " --names Names", + " --dry-run Dry run", + " --yes, -y Assume yes", + " --raw Raw", + "", + "Hint.", + "", + "Global Options:", + " --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3])", + " --format Output format", + " --full-output Show full output envelope", + " --help Show help", + " --llms, --llms-full Print LLM-readable manifest", + " --schema Show JSON Schema for command", + " --token-count Print token count of output (instead of output)", + " --token-limit Limit output to n tokens", + " --token-offset Skip first n tokens of output", + ].join("\n"), + ); +}); diff --git a/tests/boundary/cli/filteredArrayOutput.test.ts b/tests/boundary/cli/filteredArrayOutput.test.ts index 9d2b13aa90..77d42db646 100644 --- a/tests/boundary/cli/filteredArrayOutput.test.ts +++ b/tests/boundary/cli/filteredArrayOutput.test.ts @@ -1,9 +1,10 @@ import { Writable } from "node:stream"; -import { Cli, Formatter } from "incur"; +import { Cli } from "incur"; import { estimateTokenCount } from "tokenx"; import { expect, it } from "vitest"; +import { formatCliOutput } from "../../../src/cli/cliOutputFormatter.js"; import { parseCliOutputArguments, renderCliDocument, @@ -352,7 +353,7 @@ it.each(["json", "jsonl"] as const)( }, }); expect(Buffer.concat(chunks).toString()).toBe( - `${estimateTokenCount(Formatter.format([1, null, null], format))}\n`, + `${estimateTokenCount(formatCliOutput([1, null, null], format))}\n`, ); expect(fallback).toBe(""); }, @@ -530,7 +531,7 @@ it.each(["json", "jsonl", "yaml", "toon", "md"] as const)( ).toEqual(expected); else if (format === "md") expect(outputs[0]).toBe(renderCliDocument(expected, format, false)); - else expect(outputs[0]).toBe(`${Formatter.format(expected, format)}\n`); + else expect(outputs[0]).toBe(`${formatCliOutput(expected, format)}\n`); expect(projectionSource[0]?.rows[0]?.retained).toEqual([0, 10]); }, ); @@ -555,7 +556,7 @@ it.each(["json", "jsonl", "yaml", "toon", "md"] as const)( .map((line) => JSON.parse(line)), ).toEqual([1, null, null]); else if (format === "md") expect(output).toBe("\\[1,null,null\\]\n"); - else expect(output).toBe(`${Formatter.format(selected, format)}\n`); + else expect(output).toBe(`${formatCliOutput(selected, format)}\n`); expect(value).toEqual([{ selected: 1 }, {}, { selected: null }]); }, ); @@ -589,7 +590,7 @@ it.each(["json", "jsonl", "yaml", "toon", "md"] as const)( ).toEqual(expected); else if (format === "md") expect(outputs[0]).toBe(renderCliDocument(expected, format, false)); - else expect(outputs[0]).toBe(`${Formatter.format(expected, format)}\n`); + else expect(outputs[0]).toBe(`${formatCliOutput(expected, format)}\n`); expect(projectionSource).toEqual(before); }, ); diff --git a/tests/boundary/cli/outputFilter.test.ts b/tests/boundary/cli/outputFilter.test.ts new file mode 100644 index 0000000000..c46ba2f13a --- /dev/null +++ b/tests/boundary/cli/outputFilter.test.ts @@ -0,0 +1,27 @@ +import { expect, it } from "vitest"; + +import { parseOutputFilter } from "../../../src/cli/outputFilter.js"; + +it.each([ + ["a", [[{ key: "a" }]]], + ["a.b,c", [[{ key: "a" }, { key: "b" }], [{ key: "c" }]]], + [ + "rows[0,3].name", + [[{ key: "rows" }, { start: 0, end: 3 }, { key: "name" }]], + ], + ["a[1,2],b", [[{ key: "a" }, { start: 1, end: 2 }], [{ key: "b" }]]], + ["a..b.", [[{ key: "a" }, { key: "b" }]]], + ["a,,b,", [[{ key: "a" }], [], [{ key: "b" }]]], +])("parses %j", (expression, paths) => { + expect(parseOutputFilter(expression)).toEqual({ ok: true, value: paths }); +}); + +it.each(["a[0", "a[0,1", "a[0],b[", "]a,[0"])( + "refuses the unclosed slice in %j", + (expression) => { + expect(parseOutputFilter(expression)).toEqual({ + ok: false, + error: { kind: "unclosed_slice" }, + }); + }, +); diff --git a/tests/evaluation/incurImportGuard.test.ts b/tests/evaluation/incurImportGuard.test.ts index dea9e2ea22..900320f885 100644 --- a/tests/evaluation/incurImportGuard.test.ts +++ b/tests/evaluation/incurImportGuard.test.ts @@ -1,5 +1,44 @@ import { expect, it } from "vitest"; -import { incurZodImportCount } from "../../scripts/verify/incur-import-guard.mjs"; +import { + incurImportedNameCount, + incurZodImportCount, +} from "../../scripts/verify/incur-import-guard.mjs"; + +it("counts every name a declaration takes from incur", () => { + expect(incurImportedNameCount('import { Cli } from "incur";')).toBe(1); + expect( + incurImportedNameCount( + 'import { Errors, type MiddlewareHandler } from "incur";', + ), + ).toBe(2); + expect(incurImportedNameCount("import type { Cli as C } from 'incur';")).toBe( + 1, + ); + expect( + incurImportedNameCount( + 'import { Help } from "incur";\nexport { Filter } from "incur";', + ), + ).toBe(2); + expect(incurImportedNameCount('import { Help } from "./help.js";')).toBe(0); + expect(incurImportedNameCount('// import { Help } from "incur";')).toBe(0); +}); + +it("counts namespace, default, star, side-effect and dynamic imports", () => { + expect(incurImportedNameCount('import * as Incur from "incur";')).toBe(1); + expect(incurImportedNameCount('import type * as I from "incur";')).toBe(1); + expect(incurImportedNameCount('import incur from "incur";')).toBe(1); + expect(incurImportedNameCount('import incur, { Help } from "incur";')).toBe( + 2, + ); + expect(incurImportedNameCount('import incur, * as I from "incur";')).toBe(2); + expect(incurImportedNameCount('export * from "incur";')).toBe(1); + expect(incurImportedNameCount('export * as Incur from "incur";')).toBe(1); + expect(incurImportedNameCount('import "incur";')).toBe(1); + expect(incurImportedNameCount('const m = await import("incur");')).toBe(1); + expect(incurImportedNameCount('import * as Zod from "zod";')).toBe(0); + expect(incurImportedNameCount("export const from = 1;")).toBe(0); + expect(incurImportedNameCount('const u = import.meta.url; "incur";')).toBe(0); +}); it("counts declarations that take z from incur in every spelling", () => { expect(incurZodImportCount('import { z } from "incur";')).toBe(1);