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);