mirror of
https://github.com/morluto/rea.git
synced 2026-11-17 04:04:25 +00:00
* fix(cli): record the caller's --join-path spelling in Apple IPS Evidence * refactor(cli): project CLI-only options for release exposure and IL2CPP from contracts (#10635) * refactor(cli): project CLI-only options for release exposure and IL2CPP from contracts The contract command description gains CLI-only options whose effect the handler owns, plus their dependentRequired entries. audit-release-exposure keeps --fail_on (exit status 3) and inspect-il2cpp-metadata keeps --ghidra-seeds/--seed-base; their hand-written options and input spreads are deleted. * refactor(cli): project GPU, signal and capture inspectors from their contracts (#10643) The contract command description gains JSON options decoded when the command runs, admitted with the delivery by the contract input, and bare flags that spell a nullable limit's null. inspect-gpu-code-objects, inspect-signal-decoders, decode-signal-recording, inspect-packet-fields and inspect-packet-capture are derived from their contracts; their hand-written options, superRefine blocks and CLI-only option schemas are deleted.
246 lines
8.4 KiB
TypeScript
246 lines
8.4 KiB
TypeScript
import { z } from "incur";
|
|
import type { Logger } from "pino";
|
|
|
|
import { logCliCommand } from "../cliLogging.js";
|
|
import type { AnalysisError } from "../domain/analysisErrorBase.js";
|
|
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
|
|
import type { CallerInputPaths, Evidence } from "../domain/evidence.js";
|
|
import type { Result } from "../domain/result.js";
|
|
import { deliverCliAnalysisEvidence } from "./analysisEvidenceDelivery.js";
|
|
import { finishCliEvidenceCommand } from "./cliEvidenceCallerPath.js";
|
|
import { finishAnalysisCommand } from "./finishAnalysisCommand.js";
|
|
import { withCommandCancellation } from "./commandCancellation.js";
|
|
import {
|
|
describeContractCommand,
|
|
type CliContractProjection,
|
|
type CliEvidenceDeliveryChoice,
|
|
type CliOptionShape,
|
|
type CliOptionValues,
|
|
type ContractCliDescription,
|
|
type ContractField,
|
|
type ProjectedContract,
|
|
} from "./contractCliDescription.js";
|
|
import { projectCliAnalysisResult } from "./projectCliAnalysisResult.js";
|
|
import type { CliInstance } from "./types.js";
|
|
|
|
/**
|
|
* Incur adapter for contract commands. The command itself is described in
|
|
* `contractCliDescription.ts`; this module only renders that description as
|
|
* Incur args and options and runs the handler.
|
|
*/
|
|
|
|
/** What a contract command's handler receives besides the contract input. */
|
|
export interface ContractCommandContext<
|
|
CliOptions extends Readonly<Record<string, unknown>> = Readonly<
|
|
Record<string, unknown>
|
|
>,
|
|
> {
|
|
readonly signal: AbortSignal;
|
|
/** The contract name, which is the canonical operation. */
|
|
readonly operation: string;
|
|
/** Each caller-path field as the caller spelled it, before resolution. */
|
|
readonly callerInputs: Readonly<Record<string, string>>;
|
|
/** The admitted delivery, for a projection with `evidenceDelivery`. */
|
|
readonly delivery: CliEvidenceDeliveryChoice | undefined;
|
|
/** The projection's CLI-only options, whose effect the handler owns. */
|
|
readonly cliOptions: CliOptions;
|
|
}
|
|
|
|
/** A closeable one-shot service that inspects one contract input. */
|
|
export interface EvidenceInspectionService {
|
|
inspect(
|
|
input: unknown,
|
|
options: { readonly signal: AbortSignal },
|
|
): Promise<Result<Evidence, AnalysisError>>;
|
|
close(): Promise<void>;
|
|
}
|
|
|
|
/**
|
|
* The caller's spelling of `path`, and of each other caller-path field keyed
|
|
* by its contract field name.
|
|
*/
|
|
const callerSpellings = ({
|
|
operation,
|
|
callerInputs,
|
|
}: ContractCommandContext): {
|
|
readonly path: string;
|
|
readonly others: CallerInputPaths | undefined;
|
|
} => {
|
|
const { path, ...others } = callerInputs;
|
|
if (path === undefined)
|
|
throw new Error(`${operation} has no caller path field named path`);
|
|
return {
|
|
path,
|
|
others: Object.keys(others).length === 0 ? undefined : others,
|
|
};
|
|
};
|
|
|
|
/**
|
|
* Inspect through a closeable service, finish its cleanup, and record the
|
|
* caller's spelling of each selected path in the Evidence.
|
|
*/
|
|
export const inspectWithService =
|
|
(service: () => EvidenceInspectionService, providerId: string) =>
|
|
(input: unknown, context: ContractCommandContext) => {
|
|
const spellings = callerSpellings(context);
|
|
const owned = service();
|
|
return finishCliEvidenceCommand(
|
|
spellings.path,
|
|
() => owned.inspect(input, { signal: context.signal }),
|
|
owned,
|
|
providerId,
|
|
context.operation,
|
|
context.signal,
|
|
spellings.others,
|
|
).then(projectCliAnalysisResult);
|
|
};
|
|
|
|
/**
|
|
* Run an analysis that selects no target path through a closeable service
|
|
* and finish its cleanup.
|
|
*/
|
|
export const analyzeWithService =
|
|
(service: () => EvidenceInspectionService, providerId: string) =>
|
|
(input: unknown, context: ContractCommandContext) => {
|
|
if (Object.keys(context.callerInputs).length > 0)
|
|
throw new Error(`${context.operation} selects a caller path`);
|
|
const owned = service();
|
|
return finishAnalysisCommand(
|
|
() => owned.inspect(input, { signal: context.signal }),
|
|
owned,
|
|
providerId,
|
|
context.operation,
|
|
context.signal,
|
|
).then(projectCliAnalysisResult);
|
|
};
|
|
|
|
/**
|
|
* Inspect through a closeable service, then deliver complete Evidence or a
|
|
* summary with its bundle, recording the caller's spelling of each selected
|
|
* path.
|
|
*/
|
|
export const deliverWithService =
|
|
(service: () => EvidenceInspectionService, providerId: string) =>
|
|
(input: unknown, context: ContractCommandContext) => {
|
|
const spellings = callerSpellings(context);
|
|
const { delivery } = context;
|
|
if (delivery === undefined)
|
|
throw new Error(`${context.operation} does not declare evidenceDelivery`);
|
|
const owned = service();
|
|
return deliverCliAnalysisEvidence({
|
|
callerInputPath: spellings.path,
|
|
...(spellings.others === undefined
|
|
? {}
|
|
: { callerInputPaths: spellings.others }),
|
|
run: () => owned.inspect(input, { signal: context.signal }),
|
|
service: owned,
|
|
providerId,
|
|
operation: context.operation,
|
|
signal: context.signal,
|
|
detail: delivery.detail,
|
|
evidenceOutput: delivery.evidenceOutput,
|
|
...(delivery.view === undefined ? {} : { view: delivery.view }),
|
|
});
|
|
};
|
|
|
|
const descriptions = new WeakMap<CliInstance, ContractCliDescription[]>();
|
|
|
|
/** Commands registered on this CLI through `registerContractCommand`. */
|
|
export const contractCommandDescriptions = (
|
|
cli: CliInstance,
|
|
): readonly ContractCliDescription[] => descriptions.get(cli) ?? [];
|
|
|
|
const incurOptions = (description: ContractCliDescription): z.ZodType => {
|
|
const object = z.object(
|
|
Object.fromEntries([
|
|
...description.parameters
|
|
.filter(({ positional }) => !positional)
|
|
.map(({ key, schema }) => [key, schema] as const),
|
|
...description.cliOnlyOptions.map(
|
|
({ key, schema }) => [key, schema] as const,
|
|
),
|
|
]),
|
|
);
|
|
const constrained =
|
|
description.optionConstraints === undefined
|
|
? object
|
|
: object.meta(description.optionConstraints);
|
|
const { checkOptions } = description;
|
|
return checkOptions === undefined
|
|
? constrained
|
|
: constrained.superRefine((parsed, context) => {
|
|
for (const { path, issue } of checkOptions(parsed))
|
|
context.addIssue({ ...issue, path: [...path] } as never);
|
|
});
|
|
};
|
|
|
|
/**
|
|
* Register one CLI command described from a tool contract. The handler
|
|
* receives the contract input, with caller paths made absolute.
|
|
*/
|
|
export const registerContractCommand = <
|
|
Contract extends ProjectedContract,
|
|
Value,
|
|
CliOptions extends CliOptionShape = Record<never, z.ZodType>,
|
|
>(
|
|
cli: CliInstance,
|
|
logger: Logger,
|
|
contract: Contract,
|
|
projection: CliContractProjection<ContractField<Contract>, CliOptions>,
|
|
run: (
|
|
input: z.input<Contract["inputSchema"]>,
|
|
context: ContractCommandContext<CliOptionValues<CliOptions>>,
|
|
) => Promise<Value>,
|
|
): void => {
|
|
const description = describeContractCommand(contract, projection);
|
|
const positionals = description.parameters.filter(
|
|
({ positional }) => positional,
|
|
);
|
|
const alias = Object.fromEntries(
|
|
description.parameters.flatMap(({ key, alias: short, positional }) =>
|
|
short === undefined || positional ? [] : [[key, short]],
|
|
),
|
|
);
|
|
cli.command(description.command, {
|
|
description: description.description,
|
|
...(positionals.length === 0
|
|
? {}
|
|
: {
|
|
args: z.object(
|
|
Object.fromEntries(
|
|
positionals.map(({ key, schema }) => [key, schema]),
|
|
),
|
|
),
|
|
}),
|
|
options: incurOptions(description),
|
|
...(Object.keys(alias).length === 0 ? {} : { alias }),
|
|
run: ({
|
|
args,
|
|
options,
|
|
}: {
|
|
readonly args?: Readonly<Record<string, unknown>>;
|
|
readonly options: Readonly<Record<string, unknown>>;
|
|
}) => {
|
|
const values = { ...options, ...args };
|
|
return withCommandCancellation((signal) =>
|
|
logCliCommand(logger, description.command, async () => {
|
|
const admitted = description.admit(values);
|
|
if (!admitted.ok) return projectAnalysisError(admitted.error);
|
|
return run(admitted.value.input as z.input<Contract["inputSchema"]>, {
|
|
signal,
|
|
operation: contract.name,
|
|
callerInputs: description.callerInputs(values),
|
|
delivery: admitted.value.delivery,
|
|
cliOptions: description.cliOptionValues(
|
|
values,
|
|
) as CliOptionValues<CliOptions>,
|
|
});
|
|
}),
|
|
);
|
|
},
|
|
} as never);
|
|
const registered = descriptions.get(cli) ?? [];
|
|
registered.push(description);
|
|
descriptions.set(cli, registered);
|
|
};
|