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.
This commit is contained in:
morluto authored and GitHub committed 2026-11-16 12:01:04 +08:00
1 parent 4c8e616029
commit ec1cf3a9bd
32 files changed
+791 -194

No files matched your search

+13 -16
View File
@@ -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<typeof Filter.parse>;
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<DelimitedRowsSelection, AnalysisInputError> => {
const invalidSelection = (): Result<never, AnalysisInputError> =>
@@ -1015,7 +1012,7 @@ type FilterProjection = Result<unknown, string>;
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<string, FilterPath[]>();
const byKey = new Map<string, OutputFilterPath[]>();
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<number, FilterPath[]>();
const select = (index: number, tail: FilterPath): void => {
const selected = new Map<number, OutputFilterPath[]>();
const select = (index: number, tail: OutputFilterPath): void => {
const siblings = selected.get(index) ?? [];
siblings.push(tail);
selected.set(index, siblings);