mirror of
https://github.com/morluto/rea.git
synced 2026-11-19 05:02:40 +00:00
feat(errors): carry related parameters and operations and derive CLI flags and commands (#11777)
* feat(errors): carry related parameters and operations and derive CLI flags and commands * fix(cli,errors): preserve operation-selector flags in CLI hints and clarify snapshot load/save
This commit is contained in:
1 parent
ddd0d6d4a4
commit
d5a942177f
25 files changed
+679
-68
No files matched your search
@@ -1,5 +1,6 @@
|
||||
import type { z } from "zod";
|
||||
|
||||
import { cliCommandFor } from "../contracts/cliCommandNames.js";
|
||||
import type {
|
||||
ContractCliDescription,
|
||||
ContractCliDocumentDescription,
|
||||
@@ -17,6 +18,11 @@ export interface CliCommandOperation {
|
||||
* delivery fields have no flag.
|
||||
*/
|
||||
readonly flags: Readonly<Record<string, string>>;
|
||||
/**
|
||||
* The CLI selector option and value that chooses this operation when the
|
||||
* command defaults to another contract, such as `"--kind procedures"`.
|
||||
*/
|
||||
readonly selector?: string | undefined;
|
||||
}
|
||||
|
||||
type Inputs<Schema extends z.ZodObject | undefined> = Schema extends z.ZodObject
|
||||
@@ -132,12 +138,14 @@ export const contractDescriptionOperations = (
|
||||
readonly contract: { readonly name: string };
|
||||
readonly evidenceTargets?: ContractCliDescription["evidenceTargets"];
|
||||
},
|
||||
options: { readonly selector?: string | undefined } = {},
|
||||
): readonly CliCommandOperation[] => {
|
||||
const { sessionTarget, evidenceTargets } = description;
|
||||
return [
|
||||
{
|
||||
name: description.contract.name,
|
||||
flags: description.inputBinding?.flags ?? {},
|
||||
...(options.selector === undefined ? {} : { selector: options.selector }),
|
||||
},
|
||||
...(sessionTarget?.opening === undefined
|
||||
? []
|
||||
@@ -193,3 +201,45 @@ export const commandOwnOperations = (
|
||||
}
|
||||
return operations;
|
||||
};
|
||||
|
||||
/**
|
||||
* The CLI command spelling (`rea <command>`) that runs a contract operation,
|
||||
* or undefined when no CLI command answers it. Prefers the canonical
|
||||
* single-contract command, then a contract command whose own operations start
|
||||
* with or include it, then any other registered command whose own operations
|
||||
* include it.
|
||||
*/
|
||||
export const cliCommandForOperation = (
|
||||
operation: string,
|
||||
entries: readonly CliCommandEntry[],
|
||||
cliName: string,
|
||||
recordedCommands?: Readonly<Record<string, string>>,
|
||||
): string | undefined => {
|
||||
const canonical = cliCommandFor(operation);
|
||||
let contractPrimary: string | undefined;
|
||||
let contractSecondary: string | undefined;
|
||||
let otherMatch: string | undefined;
|
||||
for (const entry of entries) {
|
||||
const own = commandOwnOperations(entry);
|
||||
const matched = own.find(({ name }) => name === operation);
|
||||
if (matched === undefined) continue;
|
||||
const command =
|
||||
matched.selector === undefined
|
||||
? entry.name
|
||||
: `${entry.name} ${matched.selector}`;
|
||||
if (entry.name === canonical) return `${cliName} ${command}`;
|
||||
if (entry.source.kind === "contract") {
|
||||
if (own[0]?.name === operation) contractPrimary ??= command;
|
||||
else contractSecondary ??= command;
|
||||
} else {
|
||||
otherMatch ??= command;
|
||||
}
|
||||
}
|
||||
if (
|
||||
recordedCommands !== undefined &&
|
||||
Object.hasOwn(recordedCommands, canonical)
|
||||
)
|
||||
return `${cliName} ${canonical}`;
|
||||
const selected = contractPrimary ?? contractSecondary ?? otherMatch;
|
||||
return selected === undefined ? undefined : `${cliName} ${selected}`;
|
||||
};
|
||||
@@ -686,11 +686,13 @@ export const registerContractCommand = <
|
||||
if (!opening.ok) return projectAnalysisError(opening.error);
|
||||
// A composed command also takes its sources' options; a control
|
||||
// its result records from a source is set by that option.
|
||||
const operations = contractDescriptionOperations(selected);
|
||||
const resultBinding =
|
||||
description.evidenceTargets === undefined
|
||||
? selected.inputBinding
|
||||
? { ...selected.inputBinding, operations }
|
||||
: {
|
||||
...selected.inputBinding,
|
||||
operations,
|
||||
flags: {
|
||||
...description.evidenceTargets.sourceFlags,
|
||||
...selected.inputBinding.flags,
|
||||
@@ -746,11 +748,14 @@ export const registerContractCommand = <
|
||||
},
|
||||
} as never,
|
||||
{
|
||||
operations: distinctOperations(
|
||||
[description, ...chosen.values()].flatMap(
|
||||
contractDescriptionOperations,
|
||||
operations: distinctOperations([
|
||||
...contractDescriptionOperations(description),
|
||||
...[...chosen.entries()].flatMap(([value, choice]) =>
|
||||
contractDescriptionOperations(choice, {
|
||||
selector: `--${optionFlagName(projection.operationBy!.option)} ${String(value)}`,
|
||||
}),
|
||||
),
|
||||
),
|
||||
]),
|
||||
source: { kind: "contract", description },
|
||||
},
|
||||
);
|
||||
@@ -1027,7 +1032,10 @@ export const registerRoutedCommand = (
|
||||
),
|
||||
}),
|
||||
description.contract.outputSchema,
|
||||
description.inputBinding,
|
||||
{
|
||||
...description.inputBinding,
|
||||
operations: contractDescriptionOperations(description),
|
||||
},
|
||||
);
|
||||
}),
|
||||
);
|
||||
|
||||
@@ -3,12 +3,31 @@ import type { z } from "zod";
|
||||
import { recordedControlSchemas } from "../domain/analysisSettingDefinitions.js";
|
||||
import type { JsonValue } from "../domain/jsonValue.js";
|
||||
import type { Result } from "../domain/result.js";
|
||||
import {
|
||||
cliCommandForOperation,
|
||||
type CliCommandEntry,
|
||||
type CliCommandOperation,
|
||||
} from "./commandRegistry.js";
|
||||
|
||||
interface CliInputFieldBinding {
|
||||
readonly operation: string;
|
||||
readonly fields: Readonly<Record<string, string>>;
|
||||
/** Each contract field, or `field.member`, the command takes as a flag. */
|
||||
readonly flags: Readonly<Record<string, string>>;
|
||||
/**
|
||||
* Operations the selected command route runs, including its session-target
|
||||
* opener and Evidence-target source. When supplied, recovery flags fall back
|
||||
* across these operations when an error omits `details.operation` or names
|
||||
* its opener.
|
||||
*/
|
||||
readonly operations?: readonly CliCommandOperation[] | undefined;
|
||||
}
|
||||
|
||||
export interface CliCommandOutputProjectionContext {
|
||||
readonly operations: readonly CliCommandOperation[];
|
||||
readonly commands: readonly CliCommandEntry[];
|
||||
readonly cliName?: string | undefined;
|
||||
readonly recordedCommands?: Readonly<Record<string, string>> | undefined;
|
||||
}
|
||||
|
||||
/** Flatten a finalized outcome only when returning the command's JSON output. */
|
||||
@@ -21,6 +40,20 @@ export const isObject = (
|
||||
): value is Record<string, JsonValue> =>
|
||||
value !== null && typeof value === "object" && !Array.isArray(value);
|
||||
|
||||
const orderedOperations = (
|
||||
operations: readonly CliCommandOperation[],
|
||||
errorOperation: JsonValue | undefined,
|
||||
): readonly CliCommandOperation[] => {
|
||||
if (typeof errorOperation !== "string" || operations.length <= 1)
|
||||
return operations;
|
||||
const matching = operations.filter(({ name }) => name === errorOperation);
|
||||
if (matching.length === 0) return operations;
|
||||
return [
|
||||
...matching,
|
||||
...operations.filter(({ name }) => name !== errorOperation),
|
||||
];
|
||||
};
|
||||
|
||||
/**
|
||||
* Name a contract command's input fields by their CLI spelling in its
|
||||
* output: a direct failure, a delivered failure or a refused publication.
|
||||
@@ -36,10 +69,23 @@ export const projectCliInputFields = <Output>(
|
||||
binding: CliInputFieldBinding,
|
||||
): Output => {
|
||||
const error = output as JsonValue;
|
||||
if (!isObject(error) || !isObject(error.details)) return output;
|
||||
if (
|
||||
!isObject(error) ||
|
||||
typeof error.code !== "string" ||
|
||||
!isObject(error.details)
|
||||
)
|
||||
return output;
|
||||
const operations =
|
||||
binding.operations === undefined
|
||||
? [{ name: binding.operation, flags: binding.flags }]
|
||||
: orderedOperations(binding.operations, error.details.operation);
|
||||
const issues = renamedIssues(error, error.details, binding);
|
||||
const limit = flaggedLimit(error.details.limit, binding);
|
||||
const relatedFlags = relatedCliFlags(error.details, binding);
|
||||
const limit = flaggedLimit(error.details.limit, operations);
|
||||
const relatedFlags =
|
||||
binding.operations === undefined &&
|
||||
error.details.operation !== binding.operation
|
||||
? undefined
|
||||
: relatedCliFlagsFromOperations(error.details, operations);
|
||||
if (issues === undefined && limit === undefined && relatedFlags === undefined)
|
||||
return output;
|
||||
return {
|
||||
@@ -56,28 +102,132 @@ export const projectCliInputFields = <Output>(
|
||||
};
|
||||
|
||||
/**
|
||||
* The option of each field this command's failure names for its recovery,
|
||||
* keyed by contract field, or undefined when it takes none of them. Fields
|
||||
* of another operation are that command's to render.
|
||||
* Render `cli_flag`, `related_cli_flags`, and `related_cli_commands` on any
|
||||
* CLI command's error output from its registered operations and the CLI's
|
||||
* command registry. Preserves existing route-specific bindings and untouched
|
||||
* references.
|
||||
*/
|
||||
const relatedCliFlags = (
|
||||
details: Record<string, JsonValue>,
|
||||
binding: CliInputFieldBinding,
|
||||
): Record<string, JsonValue> | undefined => {
|
||||
export const projectCliCommandOutput = <Output>(
|
||||
output: Output,
|
||||
context: CliCommandOutputProjectionContext,
|
||||
): Output => {
|
||||
const candidate = output as JsonValue;
|
||||
if (!isObject(candidate)) return output;
|
||||
if (typeof candidate.code === "string" && isObject(candidate.details))
|
||||
return projectErrorRecord(candidate, context) as Output;
|
||||
if (
|
||||
details.operation !== binding.operation ||
|
||||
!Array.isArray(details.related_parameters)
|
||||
isObject(candidate.error) &&
|
||||
typeof candidate.error.code === "string" &&
|
||||
isObject(candidate.error.details)
|
||||
) {
|
||||
const nested = projectErrorRecord(candidate.error, context);
|
||||
return nested === candidate.error
|
||||
? output
|
||||
: ({ ...candidate, error: nested } as Output);
|
||||
}
|
||||
return output;
|
||||
};
|
||||
|
||||
const projectErrorRecord = (
|
||||
error: Record<string, JsonValue>,
|
||||
context: CliCommandOutputProjectionContext,
|
||||
): Record<string, JsonValue> => {
|
||||
const { details } = error;
|
||||
if (!isObject(details)) return error;
|
||||
const operations = orderedOperations(context.operations, details.operation);
|
||||
const limit =
|
||||
isObject(details.limit) && Object.hasOwn(details.limit, "cli_flag")
|
||||
? undefined
|
||||
: flaggedLimit(details.limit, operations);
|
||||
const relatedFlags = Object.hasOwn(details, "related_cli_flags")
|
||||
? undefined
|
||||
: relatedCliFlagsFromOperations(details, operations);
|
||||
const relatedCommands = Object.hasOwn(details, "related_cli_commands")
|
||||
? undefined
|
||||
: relatedCliCommands(details, context);
|
||||
const secondaryFailures = projectedSecondaryFailures(
|
||||
details.secondary_failures,
|
||||
context,
|
||||
);
|
||||
if (
|
||||
limit === undefined &&
|
||||
relatedFlags === undefined &&
|
||||
relatedCommands === undefined &&
|
||||
secondaryFailures === undefined
|
||||
)
|
||||
return error;
|
||||
return {
|
||||
...error,
|
||||
details: {
|
||||
...details,
|
||||
...(limit === undefined ? {} : { limit }),
|
||||
...(relatedFlags === undefined
|
||||
? {}
|
||||
: { related_cli_flags: relatedFlags }),
|
||||
...(relatedCommands === undefined
|
||||
? {}
|
||||
: { related_cli_commands: relatedCommands }),
|
||||
...(secondaryFailures === undefined
|
||||
? {}
|
||||
: { secondary_failures: secondaryFailures }),
|
||||
},
|
||||
};
|
||||
};
|
||||
|
||||
const projectedSecondaryFailures = (
|
||||
secondary: JsonValue | undefined,
|
||||
context: CliCommandOutputProjectionContext,
|
||||
): JsonValue[] | undefined => {
|
||||
if (!Array.isArray(secondary) || secondary.length === 0) return undefined;
|
||||
let changed = false;
|
||||
const mapped = secondary.map((item) => {
|
||||
if (!isObject(item) || typeof item.code !== "string") return item;
|
||||
const next = projectErrorRecord(item, context);
|
||||
if (next !== item) changed = true;
|
||||
return next;
|
||||
});
|
||||
return changed ? mapped : undefined;
|
||||
};
|
||||
|
||||
/**
|
||||
* The option of each field a failure names for its recovery, keyed by contract
|
||||
* field, or undefined when the command takes none of them.
|
||||
*/
|
||||
const relatedCliFlagsFromOperations = (
|
||||
details: Record<string, JsonValue>,
|
||||
operations: readonly CliCommandOperation[],
|
||||
): Record<string, JsonValue> | undefined => {
|
||||
if (!Array.isArray(details.related_parameters) || operations.length === 0)
|
||||
return undefined;
|
||||
const flags: Record<string, JsonValue> = {};
|
||||
for (const parameter of details.related_parameters) {
|
||||
if (typeof parameter !== "string") continue;
|
||||
const flag = cliFlagFor(parameter, binding);
|
||||
const flag = cliFlagForOperations(parameter, operations);
|
||||
if (flag !== undefined) flags[parameter] = flag;
|
||||
}
|
||||
return Object.keys(flags).length === 0 ? undefined : flags;
|
||||
};
|
||||
|
||||
const relatedCliCommands = (
|
||||
details: Record<string, JsonValue>,
|
||||
context: CliCommandOutputProjectionContext,
|
||||
): Record<string, JsonValue> | undefined => {
|
||||
if (!Array.isArray(details.related_operations)) return undefined;
|
||||
const cliName = context.cliName ?? "rea";
|
||||
const commands: Record<string, JsonValue> = {};
|
||||
for (const operation of details.related_operations) {
|
||||
if (typeof operation !== "string") continue;
|
||||
const command = cliCommandForOperation(
|
||||
operation,
|
||||
context.commands,
|
||||
cliName,
|
||||
context.recordedCommands,
|
||||
);
|
||||
if (command !== undefined) commands[operation] = command;
|
||||
}
|
||||
return Object.keys(commands).length === 0 ? undefined : commands;
|
||||
};
|
||||
|
||||
/** Issue paths renamed to CLI keys, or undefined when none changes. */
|
||||
const renamedIssues = (
|
||||
error: Record<string, JsonValue>,
|
||||
@@ -128,13 +278,29 @@ const limitParameter = (limit: JsonValue | undefined): string | undefined =>
|
||||
* parameter path names the flag: a flattened member option, else the option
|
||||
* of the whole field (such as `--producer-limits` JSON).
|
||||
*/
|
||||
const cliFlagFor = (
|
||||
const cliFlagForFlags = (
|
||||
parameter: string,
|
||||
binding: CliInputFieldBinding,
|
||||
flags: Readonly<Record<string, string>>,
|
||||
): string | undefined => {
|
||||
const segments = parameter.split(".");
|
||||
for (let length = segments.length; length > 0; length -= 1) {
|
||||
const flag = binding.flags[segments.slice(0, length).join(".")];
|
||||
const flag = flags[segments.slice(0, length).join(".")];
|
||||
if (flag !== undefined) return flag;
|
||||
}
|
||||
return undefined;
|
||||
};
|
||||
|
||||
const cliFlagFor = (
|
||||
parameter: string,
|
||||
binding: Pick<CliInputFieldBinding, "flags">,
|
||||
): string | undefined => cliFlagForFlags(parameter, binding.flags);
|
||||
|
||||
const cliFlagForOperations = (
|
||||
parameter: string,
|
||||
operations: readonly CliCommandOperation[],
|
||||
): string | undefined => {
|
||||
for (const operation of operations) {
|
||||
const flag = cliFlagForFlags(parameter, operation.flags);
|
||||
if (flag !== undefined) return flag;
|
||||
}
|
||||
return undefined;
|
||||
@@ -143,11 +309,13 @@ const cliFlagFor = (
|
||||
/** The reported per-call control with the flag that sets it. */
|
||||
const flaggedLimit = (
|
||||
limit: JsonValue | undefined,
|
||||
binding: CliInputFieldBinding,
|
||||
operations: readonly CliCommandOperation[],
|
||||
): Record<string, JsonValue> | undefined => {
|
||||
const parameter = limitParameter(limit);
|
||||
const flag =
|
||||
parameter === undefined ? undefined : cliFlagFor(parameter, binding);
|
||||
parameter === undefined
|
||||
? undefined
|
||||
: cliFlagForOperations(parameter, operations);
|
||||
return flag === undefined || !isObject(limit)
|
||||
? undefined
|
||||
: { ...limit, cli_flag: flag };
|
||||
|
||||
@@ -17,8 +17,11 @@ import {
|
||||
type CliCommandFailure,
|
||||
} from "./argumentErrors.js";
|
||||
import { parseCliArgv } from "./argvParser.js";
|
||||
import { cliCommand } from "./commandRegistry.js";
|
||||
import { cliCommand, cliCommands } from "./commandRegistry.js";
|
||||
import { withCliEvidencePublication } from "./cliEvidencePublication.js";
|
||||
import { rebindLoggedCliFailure } from "../cliLogging.js";
|
||||
import { RECORDED_CLI_COMMAND_REGISTRATIONS } from "../recordedCliCommandRegistrations.js";
|
||||
import { projectCliCommandOutput } from "./projectCliAnalysisResult.js";
|
||||
import {
|
||||
cliResultControls,
|
||||
withCliResultControls,
|
||||
@@ -122,10 +125,17 @@ export const runCliCommand = async (
|
||||
}
|
||||
await withCliEvidencePublication(() =>
|
||||
withCliResultControls(async () => {
|
||||
const value = await entry.definition.run({
|
||||
const rawValue = await entry.definition.run({
|
||||
...parsed.value,
|
||||
formatExplicit: controls.formatExplicit,
|
||||
});
|
||||
const value = projectCliCommandOutput(rawValue, {
|
||||
operations: entry.operations,
|
||||
commands: cliCommands(cli),
|
||||
cliName: cli.name,
|
||||
recordedCommands: RECORDED_CLI_COMMAND_REGISTRATIONS,
|
||||
});
|
||||
rebindLoggedCliFailure(rawValue, value);
|
||||
if (!output.handled)
|
||||
await output.write(value, {
|
||||
command: entry.name,
|
||||
|
||||
Reference in new issue
Block a user