mirror of
https://github.com/morluto/rea.git
synced 2026-11-15 19:23:24 +00:00
* refactor(cli): project observe-native-calls onto a session target and its contract document * refactor(cli): project endpoint comparison and browser scenario documents with delivery options (#10711) * refactor(cli): carry document command delivery as options and project endpoint and browser scenario commands A JSON-document projection can now take the contract's detail and view fields as --detail, --evidence_output and --view beside the document. The document refuses those fields with the option to use, and the delivery is admitted by the contract's own view schema before the document is read. compare-static-and-observed-endpoints, capture-browser-scenario and validate-browser-scenario now register from their contracts; validation projects the capture contract without detail. * fix(cli): admit the endpoint comparison document before reading its Evidence bundle The document command context carries the document's transport frame, so a handler that reads an Evidence bundle first can refuse a malformed document beforehand, as the hand-written command did. * refactor(cli): pass only object documents to the document field refusal * refactor(cli): project inspect-artifact and extract-artifact with open_binary target options (#10722) * refactor(cli): project inspect-artifact and extract-artifact with open_binary target options A declared session target can now take fields of the contract an MCP client opens the target with as options. They are admitted by that contract, with the target as its path, before the target is opened, and the projection can narrow an enum to the values the command supports. inspect-artifact and extract-artifact are derived from their contracts with open_binary's format and ESP flash fields. MCP open_binary and the CLI share one mapping from those fields to the target selection. extract-artifact now runs under the command's cancellation signal. * fix(cli): read open_binary from its session contract so startup stays lazy * build(lint): refuse value imports of the complete tool catalog in CLI startup modules
520 lines
16 KiB
TypeScript
520 lines
16 KiB
TypeScript
import { beforeAll, expect, it } from "vitest";
|
|
import { Ajv2020 } from "ajv/dist/2020.js";
|
|
import type { AnySchema } from "ajv";
|
|
import { z } from "zod";
|
|
|
|
import { createCli } from "../../../src/cli.js";
|
|
import { CLI_COMMANDS } from "../../../src/cliCommandNames.js";
|
|
import { artifactComparisonInputSchema } from "../../../src/contracts/artifactComparisonContracts.js";
|
|
import {
|
|
compareApplicationVersionsRequestSchema,
|
|
compareJavaScriptExportShapesRequestSchema,
|
|
compareSourceToBundleRequestSchema,
|
|
compareStaticObservedEndpointsFactsSchema,
|
|
reconcileJavaScriptRuntimeRequestSchema,
|
|
traceApplicationFeatureRequestSchema,
|
|
traceJavaScriptSemanticsRequestSchema,
|
|
} from "../../../src/contracts/javascript/applicationWorkflowInputContracts.js";
|
|
import {
|
|
getEvidenceBundleInputSchema,
|
|
importEvidenceBundleInputSchema,
|
|
} from "../../../src/contracts/sessionToolSchemas.js";
|
|
import { reconstructionCoverageEvaluationInputSchema } from "../../../src/domain/reconstructionCoverageInput.js";
|
|
import { reconstructionObligationLedgerInputSchema } from "../../../src/domain/reconstructionObligationLedgerSchemas.js";
|
|
import { inspectAnalysisViewInputSchema } from "../../../src/domain/analysisView/analysisViewRequest.js";
|
|
import { browserScenarioSchema } from "../../../src/domain/browserScenario.js";
|
|
import { getEvidenceInputContract } from "../../../src/domain/evidenceInputContract.js";
|
|
import { electronActiveObservationInputSchema } from "../../../src/domain/javascript/electronActiveObservation.js";
|
|
import { applicationInventoryProjectionInputSchema } from "../../../src/domain/mobileApplicationGraphProjection.js";
|
|
import { managedApplicationGraphReferenceInputSchema } from "../../../src/domain/managed/managedApplicationGraph.js";
|
|
import { managedNativeVerificationRequestSchema } from "../../../src/domain/managed/managedNativeVerificationSchemas.js";
|
|
import { managedReconstructionImportRequestSchema } from "../../../src/domain/managed/managedReconstruction.js";
|
|
import { nativeCallObservationInputSchema } from "../../../src/domain/native/nativeCallObservation.js";
|
|
import { matchNativeFunctionsInputSchema } from "../../../src/contracts/native/functionMatchingContracts.js";
|
|
import { COMPARE_WASM_INTERFACES_CONTRACT } from "../../../src/contracts/wasm/wasmComparisonContracts.js";
|
|
import {
|
|
jsonInputArgument,
|
|
jsonInputContentSchema,
|
|
} from "../../../src/cli/jsonInputArgument.js";
|
|
import { cliJsonCallerPathSchema } from "../../../src/cliJsonInput.js";
|
|
import { visitRegisteredCommands } from "../../../src/cli/visitRegisteredCommands.js";
|
|
import type { CliInstance } from "../../../src/cli/types.js";
|
|
|
|
const frame = (schema: z.ZodType): z.ZodType =>
|
|
getEvidenceInputContract(schema).frameSchema;
|
|
|
|
const inspectEvidenceBundleCliInputSchema =
|
|
getEvidenceBundleInputSchema.safeExtend({
|
|
path: importEvidenceBundleInputSchema.shape.path,
|
|
});
|
|
const inventoryDocumentSchema = frame(
|
|
applicationInventoryProjectionInputSchema,
|
|
);
|
|
|
|
/** Every positional JSON document and the schema its handler parses. */
|
|
const documents: readonly {
|
|
readonly command: string;
|
|
readonly schema: z.ZodType;
|
|
/** Fields the CLI resolves against the working directory before parsing. */
|
|
readonly callerPaths?: readonly (readonly string[])[];
|
|
}[] = [
|
|
{
|
|
command: CLI_COMMANDS.traceApplicationFeature,
|
|
schema: frame(traceApplicationFeatureRequestSchema),
|
|
},
|
|
{
|
|
command: CLI_COMMANDS.traceJavaScriptSemantics,
|
|
schema: frame(traceJavaScriptSemanticsRequestSchema),
|
|
},
|
|
{
|
|
command: CLI_COMMANDS.compareApplicationVersions,
|
|
schema: frame(compareApplicationVersionsRequestSchema),
|
|
},
|
|
{
|
|
command: CLI_COMMANDS.compareStaticAndObservedEndpoints,
|
|
schema: frame(compareStaticObservedEndpointsFactsSchema),
|
|
},
|
|
{
|
|
command: CLI_COMMANDS.compareSourceToBundle,
|
|
schema: frame(compareSourceToBundleRequestSchema.omit({ view: true })),
|
|
callerPaths: [["reference", "path"]],
|
|
},
|
|
{
|
|
command: CLI_COMMANDS.compareJavaScriptExportShapes,
|
|
schema: frame(compareJavaScriptExportShapesRequestSchema),
|
|
},
|
|
{
|
|
command: CLI_COMMANDS.buildReconstructionObligationLedger,
|
|
schema: reconstructionObligationLedgerInputSchema,
|
|
},
|
|
{
|
|
command: CLI_COMMANDS.evaluateReconstructionCoverage,
|
|
schema: reconstructionCoverageEvaluationInputSchema,
|
|
},
|
|
{
|
|
command: CLI_COMMANDS.projectAndroidApplicationGraph,
|
|
schema: inventoryDocumentSchema,
|
|
},
|
|
{
|
|
command: CLI_COMMANDS.projectAppleApplicationGraph,
|
|
schema: inventoryDocumentSchema,
|
|
},
|
|
{
|
|
command: CLI_COMMANDS.projectHarmonyApplicationGraph,
|
|
schema: inventoryDocumentSchema,
|
|
},
|
|
{
|
|
command: CLI_COMMANDS.inspectEvidenceBundle,
|
|
schema: inspectEvidenceBundleCliInputSchema,
|
|
},
|
|
{
|
|
command: CLI_COMMANDS.inspectAnalysisView,
|
|
schema: inspectAnalysisViewInputSchema,
|
|
callerPaths: [["source", "path"]],
|
|
},
|
|
{
|
|
command: CLI_COMMANDS.captureElectronScenario,
|
|
schema: electronActiveObservationInputSchema,
|
|
callerPaths: [
|
|
["executable_path"],
|
|
["application_path"],
|
|
["application_root"],
|
|
],
|
|
},
|
|
{
|
|
command: CLI_COMMANDS.reconcileJavaScriptRuntime,
|
|
schema: frame(reconcileJavaScriptRuntimeRequestSchema),
|
|
},
|
|
{
|
|
command: CLI_COMMANDS.observeNativeCalls,
|
|
schema: nativeCallObservationInputSchema,
|
|
},
|
|
{
|
|
command: CLI_COMMANDS.importManagedReconstruction,
|
|
schema: frame(managedReconstructionImportRequestSchema),
|
|
},
|
|
{
|
|
command: CLI_COMMANDS.verifyManagedNativeBoundaries,
|
|
schema: frame(managedNativeVerificationRequestSchema),
|
|
},
|
|
{
|
|
command: CLI_COMMANDS.projectManagedApplicationGraph,
|
|
schema: frame(managedApplicationGraphReferenceInputSchema),
|
|
},
|
|
{
|
|
command: CLI_COMMANDS.compareArtifacts,
|
|
schema: artifactComparisonInputSchema,
|
|
callerPaths: [
|
|
["left", "path"],
|
|
["right", "path"],
|
|
],
|
|
},
|
|
{
|
|
command: CLI_COMMANDS.compareWasmInterfaces,
|
|
schema: frame(COMPARE_WASM_INTERFACES_CONTRACT.inputSchema),
|
|
},
|
|
{
|
|
command: CLI_COMMANDS.matchNativeFunctions,
|
|
schema: frame(matchNativeFunctionsInputSchema),
|
|
},
|
|
{
|
|
command: CLI_COMMANDS.captureBrowserScenario,
|
|
schema: browserScenarioSchema,
|
|
callerPaths: [["browser", "executable_path"]],
|
|
},
|
|
{
|
|
command: CLI_COMMANDS.validateBrowserScenario,
|
|
schema: browserScenarioSchema,
|
|
callerPaths: [["browser", "executable_path"]],
|
|
},
|
|
] as const;
|
|
|
|
interface InputJsonSchema {
|
|
readonly type?: unknown;
|
|
readonly description?: unknown;
|
|
readonly contentMediaType?: unknown;
|
|
readonly contentSchema?: {
|
|
readonly properties?: Readonly<Record<string, unknown>>;
|
|
readonly required?: readonly string[];
|
|
};
|
|
}
|
|
|
|
const jsonInputCommands = (cli: CliInstance): string[] => {
|
|
const names: string[] = [];
|
|
visitRegisteredCommands(cli, (command, path) => {
|
|
if (
|
|
command.args instanceof z.ZodObject &&
|
|
Object.hasOwn(command.args.shape, "inputJson")
|
|
)
|
|
names.push(path);
|
|
});
|
|
return names;
|
|
};
|
|
|
|
let cli: ReturnType<typeof createCli>;
|
|
|
|
beforeAll(() => {
|
|
cli = createCli({});
|
|
});
|
|
|
|
const serve = async (argv: readonly string[]) => {
|
|
let stdout = "";
|
|
let exitCode = 0;
|
|
await cli.serve([...argv], {
|
|
env: {},
|
|
exit: (code) => {
|
|
exitCode = code;
|
|
},
|
|
stdout: (text) => {
|
|
stdout += text;
|
|
},
|
|
});
|
|
return { stdout, exitCode };
|
|
};
|
|
|
|
const advertisedInput = (stdout: string): InputJsonSchema => {
|
|
const document = JSON.parse(stdout) as {
|
|
args?: {
|
|
properties?: { inputJson?: InputJsonSchema };
|
|
required?: readonly string[];
|
|
};
|
|
};
|
|
expect(document.args?.required).toContain("inputJson");
|
|
const inputJson = document.args?.properties?.inputJson;
|
|
expect(inputJson).toMatchObject({
|
|
type: "string",
|
|
contentMediaType: "application/json",
|
|
});
|
|
expect(typeof inputJson?.description).toBe("string");
|
|
return inputJson as InputJsonSchema;
|
|
};
|
|
|
|
type JsonSchemaNode = Record<string, unknown>;
|
|
|
|
const cliCallerPath = jsonInputContentSchema(
|
|
cliJsonCallerPathSchema,
|
|
) as JsonSchemaNode;
|
|
|
|
/** Expect a caller path as the CLI admits it: any nonempty local spelling. */
|
|
const admitRelativePath = (
|
|
schema: JsonSchemaNode,
|
|
path: readonly string[],
|
|
): JsonSchemaNode => {
|
|
const [head, ...tail] = path;
|
|
if (head === undefined) {
|
|
const { allOf: _patterns, pattern: _pattern, ...rest } = schema;
|
|
return { ...rest, ...cliCallerPath };
|
|
}
|
|
const branches = (["anyOf", "oneOf"] as const).flatMap((keyword) =>
|
|
Array.isArray(schema[keyword])
|
|
? [
|
|
[
|
|
keyword,
|
|
(schema[keyword] as JsonSchemaNode[]).map((branch) =>
|
|
admitRelativePath(branch, path),
|
|
),
|
|
] as const,
|
|
]
|
|
: [],
|
|
);
|
|
const properties = schema.properties as
|
|
| Record<string, JsonSchemaNode>
|
|
| undefined;
|
|
return {
|
|
...schema,
|
|
...Object.fromEntries(branches),
|
|
...(properties?.[head] === undefined
|
|
? {}
|
|
: {
|
|
properties: {
|
|
...properties,
|
|
[head]: admitRelativePath(properties[head], tail),
|
|
},
|
|
}),
|
|
};
|
|
};
|
|
|
|
it("advertises the parsed document for every JSON-input command", async () => {
|
|
const ajv = new Ajv2020({ strict: false, validateFormats: false });
|
|
expect(jsonInputCommands(cli).sort()).toEqual(
|
|
documents.map(({ command }) => command).sort(),
|
|
);
|
|
for (const { command, schema, callerPaths = [] } of documents) {
|
|
const served = await serve([command, "--schema", "--json"]);
|
|
expect(served.exitCode, served.stdout).toBe(0);
|
|
const inputJson = advertisedInput(served.stdout);
|
|
expect(inputJson.contentSchema, command).toBeDefined();
|
|
expect(inputJson.contentSchema, command).toEqual(
|
|
callerPaths.reduce(
|
|
admitRelativePath,
|
|
jsonInputContentSchema(schema) as JsonSchemaNode,
|
|
),
|
|
);
|
|
expect(inputJson.contentSchema, command).not.toEqual({});
|
|
expect(
|
|
() => ajv.compile(inputJson.contentSchema as AnySchema),
|
|
command,
|
|
).not.toThrow();
|
|
}
|
|
});
|
|
|
|
it("advertises caller paths as local spellings the CLI resolves, not URLs", async () => {
|
|
const input = advertisedInput(
|
|
(await serve([CLI_COMMANDS.compareSourceToBundle, "--schema", "--json"]))
|
|
.stdout,
|
|
);
|
|
const validate = new Ajv2020({
|
|
strict: false,
|
|
validateFormats: false,
|
|
}).compile(input.contentSchema as AnySchema);
|
|
const document = (path: string) => ({
|
|
reference: { kind: "file", path },
|
|
application: {},
|
|
});
|
|
for (const path of ["ref.json", "./file:ref.json", "C:\\ref.json"])
|
|
expect(validate(document(path)), path).toBe(true);
|
|
for (const path of ["file:ref.json", "FILE:ref.json", "https://x/ref.json"])
|
|
expect(validate(document(path)), path).toBe(false);
|
|
});
|
|
|
|
it("validates representative parsed documents with the advertised schema", async () => {
|
|
const input = advertisedInput(
|
|
(
|
|
await serve([
|
|
CLI_COMMANDS.evaluateReconstructionCoverage,
|
|
"--schema",
|
|
"--json",
|
|
])
|
|
).stdout,
|
|
);
|
|
const validate = new Ajv2020({
|
|
strict: false,
|
|
validateFormats: false,
|
|
}).compile(input.contentSchema as AnySchema);
|
|
const evidence_bundle = {
|
|
evidence_format: 1,
|
|
artifacts: [],
|
|
providers: [],
|
|
environments: [],
|
|
scenarios: [],
|
|
captures: [],
|
|
unknowns: [],
|
|
records: [],
|
|
};
|
|
const coverage = {
|
|
evidence_bundle,
|
|
artifacts: [],
|
|
surfaces: [],
|
|
owners: [],
|
|
claims: [],
|
|
verifier_contracts: [],
|
|
verifier_results: [],
|
|
residual_unknown_ids: [],
|
|
contradictions: [],
|
|
package_proofs: [],
|
|
boundaries: [],
|
|
};
|
|
const accepted = { coverage, boundary_id: "main" };
|
|
const rejected = [
|
|
{ coverage, boundary_id: "" },
|
|
{ coverage },
|
|
{ coverage, boundary_id: "main", extra: true },
|
|
{ coverage: { arbitrary: true }, boundary_id: "main" },
|
|
{
|
|
coverage: { ...coverage, evidence_bundle: { records: [] } },
|
|
boundary_id: "main",
|
|
},
|
|
];
|
|
const contract = reconstructionCoverageEvaluationInputSchema;
|
|
expect(contract.safeParse(accepted).success).toBe(true);
|
|
expect(validate(accepted)).toBe(true);
|
|
for (const document of rejected) {
|
|
expect(contract.safeParse(document).success).toBe(false);
|
|
expect(validate(document)).toBe(false);
|
|
}
|
|
});
|
|
|
|
it("names the feature-trace, semantic-query, and browser-scenario fields", async () => {
|
|
const trace = advertisedInput(
|
|
(await serve([CLI_COMMANDS.traceApplicationFeature, "--schema", "--json"]))
|
|
.stdout,
|
|
);
|
|
expect(trace.description).toBe("Inline workflow JSON or JSON file path");
|
|
expect(Object.keys(trace.contentSchema?.properties ?? {})).toEqual([
|
|
"native_observations",
|
|
"seed",
|
|
"semantic_page",
|
|
"direction",
|
|
"application",
|
|
]);
|
|
expect(trace.contentSchema?.required).toEqual(["seed", "application"]);
|
|
|
|
const semantic = advertisedInput(
|
|
(await serve([CLI_COMMANDS.traceJavaScriptSemantics, "--schema", "--json"]))
|
|
.stdout,
|
|
);
|
|
expect(Object.keys(semantic.contentSchema?.properties ?? {})).toEqual([
|
|
"application",
|
|
"query",
|
|
]);
|
|
expect(semantic.contentSchema?.required).toEqual(["application", "query"]);
|
|
|
|
const browser = advertisedInput(
|
|
(await serve([CLI_COMMANDS.captureBrowserScenario, "--schema", "--json"]))
|
|
.stdout,
|
|
);
|
|
expect(browser.description).toBe(
|
|
"Inline browser scenario JSON, JSON file path, or '-' for stdin",
|
|
);
|
|
expect(browser.contentSchema?.properties).toEqual(
|
|
expect.objectContaining({
|
|
browser: expect.any(Object),
|
|
start_url: expect.any(Object),
|
|
actions: expect.any(Object),
|
|
}),
|
|
);
|
|
expect(browser.contentSchema?.required).toEqual(
|
|
expect.arrayContaining(["browser", "start_url", "actions"]),
|
|
);
|
|
});
|
|
|
|
it("advertises the reconstruction documents their readers admit", async () => {
|
|
const coverage = advertisedInput(
|
|
(
|
|
await serve([
|
|
CLI_COMMANDS.evaluateReconstructionCoverage,
|
|
"--schema",
|
|
"--json",
|
|
])
|
|
).stdout,
|
|
);
|
|
// The reader authenticates the embedded bundle, but --schema still shows
|
|
// the document it admits, as the MCP contract does.
|
|
expect(coverage.contentSchema?.properties?.coverage).toMatchObject({
|
|
type: "object",
|
|
required: expect.arrayContaining(["evidence_bundle", "boundaries"]),
|
|
});
|
|
// boundary_id is a stable identifier (#9919), so its pattern is advertised.
|
|
expect(coverage.contentSchema?.properties?.boundary_id).toMatchObject({
|
|
type: "string",
|
|
pattern: expect.any(String),
|
|
});
|
|
expect(coverage.contentSchema?.required).toEqual(["coverage", "boundary_id"]);
|
|
|
|
const ledger = advertisedInput(
|
|
(
|
|
await serve([
|
|
CLI_COMMANDS.buildReconstructionObligationLedger,
|
|
"--schema",
|
|
"--json",
|
|
])
|
|
).stdout,
|
|
);
|
|
expect(ledger.contentSchema?.properties?.evidence_bundle).toMatchObject({
|
|
type: "object",
|
|
required: expect.arrayContaining(["artifacts", "records"]),
|
|
});
|
|
expect(ledger.contentSchema?.required).toEqual(
|
|
expect.arrayContaining([
|
|
"evidence_bundle",
|
|
"reviewed_obligations",
|
|
"manifest",
|
|
]),
|
|
);
|
|
});
|
|
|
|
it("prints the nested document in the default schema format", async () => {
|
|
const served = await serve([
|
|
CLI_COMMANDS.traceApplicationFeature,
|
|
"--schema",
|
|
]);
|
|
expect(served.exitCode, served.stdout).toBe(0);
|
|
expect(served.stdout).toContain("contentMediaType: application/json");
|
|
expect(served.stdout).toContain("contentSchema:");
|
|
expect(served.stdout).toContain("seed:");
|
|
expect(served.stdout).toContain("application:");
|
|
});
|
|
|
|
it("uses an empty schema only for unknown or any documents", () => {
|
|
expect(jsonInputContentSchema(z.unknown())).toEqual({});
|
|
expect(jsonInputContentSchema(z.any())).toEqual({});
|
|
expect(jsonInputContentSchema(z.unknown().nonoptional())).toEqual({});
|
|
|
|
const custom = z.custom<string>();
|
|
expect(jsonInputContentSchema(custom)).toBeUndefined();
|
|
const omitted = z.toJSONSchema(jsonInputArgument("payload", custom));
|
|
expect(omitted).toMatchObject({
|
|
type: "string",
|
|
description: "payload",
|
|
contentMediaType: "application/json",
|
|
});
|
|
expect(omitted).not.toHaveProperty("contentSchema");
|
|
|
|
const exploding = z.object({ value: z.string() });
|
|
exploding._zod.toJSONSchema = () => {
|
|
throw new Error("unconvertible");
|
|
};
|
|
expect(jsonInputContentSchema(exploding)).toBeUndefined();
|
|
expect(() =>
|
|
z.toJSONSchema(jsonInputArgument("payload", exploding)),
|
|
).not.toThrow();
|
|
|
|
const query = z.toJSONSchema(
|
|
jsonInputArgument(
|
|
"Inline workflow JSON or JSON file path",
|
|
z.strictObject({ query: z.string() }),
|
|
),
|
|
);
|
|
expect(query).toMatchObject({
|
|
type: "string",
|
|
description: "Inline workflow JSON or JSON file path",
|
|
contentMediaType: "application/json",
|
|
contentSchema: {
|
|
type: "object",
|
|
properties: { query: { type: "string" } },
|
|
required: ["query"],
|
|
additionalProperties: false,
|
|
},
|
|
});
|
|
});
|