mirror of
https://github.com/morluto/rea.git
synced 2026-11-16 11:43:20 +00:00
The last raw JSON Schema keywords in CLI .meta() calls move to src/domain/schemaConstraints helpers: requirePresence gains requiresValue (the --outline-depth rule) and jsonDocumentText declares JSON document arguments. contractCliDescription reads the root discriminator from its typed annotation; since #10693 the x-rea-root-discriminator keyword no longer reached .meta(), so the check that the discriminator is the delivery's was dead. The raw-json-schema-meta baseline is now empty.
1983 lines
67 KiB
TypeScript
1983 lines
67 KiB
TypeScript
import { Parser, z } from "incur";
|
|
import { describe, expect, it } from "vitest";
|
|
|
|
import { createCli } from "../../../src/cli.js";
|
|
import {
|
|
contractNamed,
|
|
describeContractCommand,
|
|
describeOperationChoices,
|
|
describeContractDocumentCommand,
|
|
type ContractCliDescription,
|
|
type ContractCliParameter,
|
|
} from "../../../src/cli/contractCliDescription.js";
|
|
import { BROWSER_TOOL_CONTRACTS } from "../../../src/contracts/browserToolContracts.js";
|
|
import { passiveNetworkCapture } from "../../fixtures/passiveNetworkCapture.js";
|
|
import {
|
|
contractCommandDescriptions,
|
|
contractInputBranch,
|
|
contractDocumentCommandDescriptions,
|
|
routedCommandDescriptions,
|
|
} from "../../../src/cli/contractCommand.js";
|
|
import { jsonInputContentSchema } from "../../../src/cli/jsonInputArgument.js";
|
|
import {
|
|
visitRegisteredCommands,
|
|
type RegisteredCommand,
|
|
} from "../../../src/cli/visitRegisteredCommands.js";
|
|
import { absoluteCallerPath } from "../../../src/filesystem/callerPath.js";
|
|
import { presentRootDiscriminator } from "../../../src/domain/schemaAnnotations.js";
|
|
import {
|
|
TOOL_CONTRACTS,
|
|
toolContract,
|
|
} from "../../../src/contracts/toolContracts.js";
|
|
|
|
const DECIMAL_TOKEN = /^[0-9]+$/u;
|
|
|
|
const cli = createCli({});
|
|
const registered = new Map<string, RegisteredCommand>();
|
|
visitRegisteredCommands(cli, (command, path) => {
|
|
registered.set(path, command);
|
|
});
|
|
// A routed command contributes one description per contract it runs.
|
|
const descriptions = [
|
|
...contractCommandDescriptions(cli),
|
|
...routedCommandDescriptions(cli),
|
|
];
|
|
|
|
const inputJsonSchema = (field: z.ZodType): Record<string, unknown> =>
|
|
z.toJSONSchema(field, { io: "input", unrepresentable: "any" });
|
|
|
|
/** Values at and around each advertised bound, plus spellings argv can carry. */
|
|
const probes = (field: z.ZodType): readonly unknown[] => {
|
|
const json = inputJsonSchema(field);
|
|
const values: unknown[] = [
|
|
undefined,
|
|
null,
|
|
"",
|
|
"\0",
|
|
"a\0b",
|
|
"\uD800",
|
|
"x",
|
|
"rel/x",
|
|
"/abs/x",
|
|
true,
|
|
false,
|
|
-1,
|
|
0,
|
|
1,
|
|
1.5,
|
|
64,
|
|
4096,
|
|
2 ** 31,
|
|
2 ** 53,
|
|
[],
|
|
["x"],
|
|
[""],
|
|
["a\0b"],
|
|
"0",
|
|
"1",
|
|
"010",
|
|
"0x10",
|
|
"1e3",
|
|
"+1",
|
|
" 1",
|
|
"-1",
|
|
"1.5",
|
|
"{}",
|
|
"[]",
|
|
"null",
|
|
"{",
|
|
'{"input_bytes":1}',
|
|
'{"input_bytes":0}',
|
|
'{"unknown":1}',
|
|
];
|
|
for (const bound of ["minimum", "maximum", "minLength", "maxLength"]) {
|
|
const value = json[bound];
|
|
if (typeof value !== "number") continue;
|
|
const near = [value - 1, value, value + 1];
|
|
values.push(...near, ...near.filter((n) => n >= 0).map(String));
|
|
if (bound.endsWith("Length"))
|
|
values.push(...near.filter((n) => n >= 0).map((n) => "x".repeat(n)));
|
|
}
|
|
if (Array.isArray(json.enum)) values.push(...json.enum, `${json.enum[0]}!`);
|
|
return values;
|
|
};
|
|
|
|
/** The field admits a number, possibly alongside null. */
|
|
const isNumeric = (field: z.ZodType): boolean => {
|
|
const json = inputJsonSchema(field);
|
|
const branches = Array.isArray(json.anyOf)
|
|
? (json.anyOf as Record<string, unknown>[])
|
|
: [json];
|
|
return branches.some(({ type }) => type === "integer" || type === "number");
|
|
};
|
|
|
|
/** Argv omission is an absent key, never an explicit undefined. */
|
|
const admits = (field: z.ZodType, value: unknown): boolean =>
|
|
value === undefined
|
|
? z.object({ value: field }).safeParse({}).success
|
|
: field.safeParse(value).success;
|
|
|
|
/** What the contract admits for one value the caller typed on the CLI. */
|
|
const expectedAdmission = (
|
|
parameter: ContractCliParameter,
|
|
contractField: z.ZodType,
|
|
value: unknown,
|
|
): boolean => {
|
|
// The named option may supply a selector in place of the positional.
|
|
if (parameter.selectorOption !== undefined && value === undefined)
|
|
return true;
|
|
// An omitted option takes its CLI default, which the contract admits.
|
|
if (parameter.cliDefault !== undefined && value === undefined) return true;
|
|
if (parameter.jsonText) {
|
|
// JSON text is decoded once, then the contract field admits the value.
|
|
if (typeof value !== "string")
|
|
return admits(contractField, value) && value === undefined;
|
|
let decoded: unknown;
|
|
try {
|
|
decoded = JSON.parse(value);
|
|
} catch {
|
|
return false;
|
|
}
|
|
return admits(contractField, decoded) && decoded !== undefined;
|
|
}
|
|
if (parameter.nullFlag !== undefined && value === null)
|
|
// Null is spelled by the bare flag, never by the limit option.
|
|
return false;
|
|
if (parameter.callerPath) {
|
|
// A caller path is validated as typed: an empty value never becomes the
|
|
// working directory. A nonempty value is resolved, then the contract rules.
|
|
if (Array.isArray(value))
|
|
return (
|
|
value.every((path) => typeof path === "string" && path !== "") &&
|
|
admits(
|
|
contractField,
|
|
value.map((path: string) => absoluteCallerPath(path)),
|
|
)
|
|
);
|
|
if (typeof value !== "string") return admits(contractField, value);
|
|
return value !== "" && admits(contractField, absoluteCallerPath(value));
|
|
}
|
|
if (typeof value === "string" && isNumeric(contractField))
|
|
return DECIMAL_TOKEN.test(value) && admits(contractField, Number(value));
|
|
return admits(contractField, value);
|
|
};
|
|
|
|
const registeredField = (
|
|
description: ContractCliDescription,
|
|
parameter: ContractCliParameter,
|
|
): z.ZodType => {
|
|
const command = registered.get(description.command)!;
|
|
const group = (
|
|
parameter.positional ? command.args : command.options
|
|
) as z.ZodObject;
|
|
return group.shape[parameter.key] as z.ZodType;
|
|
};
|
|
|
|
const contractShape = (description: ContractCliDescription) =>
|
|
description.fields;
|
|
|
|
/**
|
|
* Contract fields the handler supplies: each Evidence target's from its
|
|
* source, and each handler field from CLI-only values.
|
|
*/
|
|
const handlerSuppliedFields = (
|
|
description: ContractCliDescription,
|
|
): string[] => [
|
|
...(description.evidenceTargets?.targets ?? []).map(({ field }) => field),
|
|
...description.handlerFields,
|
|
];
|
|
|
|
/**
|
|
* The contract schema one parameter supplies: a field, a flattened member,
|
|
* or a field group's optional object of its fields.
|
|
*/
|
|
const suppliedField = (
|
|
description: ContractCliDescription,
|
|
parameter: ContractCliParameter,
|
|
): z.ZodType => {
|
|
const shape = contractShape(description);
|
|
if (parameter.group !== undefined)
|
|
return z
|
|
.strictObject(
|
|
Object.fromEntries(
|
|
parameter.group.map((field) => [field, shape[field]!]),
|
|
),
|
|
)
|
|
.optional();
|
|
const field = shape[parameter.field]!;
|
|
if (parameter.member === undefined) return field;
|
|
// A member is omittable when it or any enclosing object is.
|
|
let supplied: z.ZodType = field;
|
|
let omittable = false;
|
|
for (const member of parameter.member) {
|
|
omittable ||= admits(supplied, undefined);
|
|
while (
|
|
supplied instanceof z.ZodOptional ||
|
|
supplied instanceof z.ZodExactOptional
|
|
)
|
|
supplied = supplied.unwrap() as z.ZodType;
|
|
supplied = (supplied as z.ZodObject).shape[member] as z.ZodType;
|
|
}
|
|
return omittable ? supplied.optional() : supplied;
|
|
};
|
|
|
|
/**
|
|
* Argv takes a transformed field's inbound text, as tools/list advertises
|
|
* it; the contract transforms it on admission. CLI help may word the field
|
|
* differently, and the contract applies its own default.
|
|
*/
|
|
const expectInboundView = (
|
|
key: string,
|
|
cliField: z.ZodType,
|
|
contractField: z.ZodType,
|
|
): void => {
|
|
const inbound = (schema: z.ZodType) => {
|
|
const {
|
|
default: _default,
|
|
description: _description,
|
|
...view
|
|
} = z.toJSONSchema(schema, { io: "input" }) as Record<string, unknown>;
|
|
return view;
|
|
};
|
|
expect(inbound(cliField), key).toEqual(inbound(contractField));
|
|
expect(admits(cliField, undefined), key).toBe(
|
|
admits(contractField, undefined),
|
|
);
|
|
};
|
|
|
|
/** Each positional caller path is resolved, and kept as typed in callerInputs. */
|
|
const expectResolvedPositionalPaths = (
|
|
description: ContractCliDescription,
|
|
values: Readonly<Record<string, unknown>>,
|
|
input: Readonly<Record<string, unknown>>,
|
|
): void => {
|
|
for (const parameter of description.parameters) {
|
|
if (!parameter.callerPath || !parameter.positional) continue;
|
|
// A flattened member is resolved inside its object.
|
|
const path = [parameter.field, ...(parameter.member ?? [])];
|
|
const resolved = path.reduce<unknown>(
|
|
(value, key) => (value as Record<string, unknown>)[key],
|
|
input,
|
|
);
|
|
expect(resolved).toBe(absoluteCallerPath("rel/target"));
|
|
expect(description.callerInputs(values)[path.join(".")]).toBe("rel/target");
|
|
}
|
|
};
|
|
|
|
/** A caller-relative target, or the first probe the argument admits. */
|
|
const requiredValue = (
|
|
description: ContractCliDescription,
|
|
parameter: ContractCliParameter,
|
|
): unknown =>
|
|
parameter.callerPath
|
|
? "rel/target"
|
|
: probes(suppliedField(description, parameter)).find(
|
|
(value) =>
|
|
value !== undefined &&
|
|
admits(registeredField(description, parameter), value),
|
|
);
|
|
|
|
/** Parsed option values plus admitted positionals and required options. */
|
|
const argvValues = (
|
|
description: ContractCliDescription,
|
|
options: Readonly<Record<string, unknown>>,
|
|
): Record<string, unknown> => {
|
|
const positional: ReadonlySet<string> = new Set(
|
|
description.parameters
|
|
.filter((parameter) => parameter.positional)
|
|
.map(({ key }) => key),
|
|
);
|
|
// A required selector is supplied positionally.
|
|
const required = description.parameters.filter(
|
|
(parameter) =>
|
|
(parameter.selectorOption === undefined
|
|
? !admits(registeredField(description, parameter), undefined)
|
|
: parameter.selectorOption.required) &&
|
|
!Object.hasOwn(options, parameter.key),
|
|
);
|
|
const filled = Object.fromEntries(
|
|
required.map((parameter) => [
|
|
parameter.key,
|
|
requiredValue(description, parameter),
|
|
]),
|
|
);
|
|
return {
|
|
...Object.fromEntries(
|
|
Object.entries(options).filter(([key]) => positional.has(key)),
|
|
),
|
|
...(registered.get(description.command)!.options as z.ZodObject).parse({
|
|
...Object.fromEntries(
|
|
Object.entries(options).filter(([key]) => !positional.has(key)),
|
|
),
|
|
...Object.fromEntries(
|
|
required
|
|
.filter(({ positional }) => !positional)
|
|
.map(({ key }) => [key, filled[key]]),
|
|
),
|
|
}),
|
|
...Object.fromEntries(
|
|
required
|
|
.filter(({ positional }) => positional)
|
|
.map(({ key }) => [key, filled[key]]),
|
|
),
|
|
};
|
|
};
|
|
|
|
const processComparisonExample = toolContract("compare_process_captures")
|
|
.examples[0]!.input as { readonly left: unknown; readonly right: unknown };
|
|
const screenshotExample = toolContract("compare_web_screenshots").examples[0]!
|
|
.input as { readonly before: unknown; readonly after: unknown };
|
|
|
|
const captureDiff = contractNamed(
|
|
BROWSER_TOOL_CONTRACTS,
|
|
"compare_web_captures",
|
|
);
|
|
const scenarioExample = captureDiff.examples[0]!.input as {
|
|
readonly before_scenario: unknown;
|
|
readonly after_scenario: unknown;
|
|
};
|
|
|
|
/**
|
|
* Argv for each input shape of a command routed by document content, keyed
|
|
* by the shape its route projects; a passive capture and a scenario capture
|
|
* cannot both satisfy one fixture.
|
|
*/
|
|
const ROUTE_ARGV: ReadonlyMap<
|
|
unknown,
|
|
Readonly<Record<string, unknown>>
|
|
> = new Map<unknown, Readonly<Record<string, unknown>>>([
|
|
[
|
|
contractInputBranch(captureDiff, "before").inputSchema,
|
|
{
|
|
beforeJson: JSON.stringify({ inspection: passiveNetworkCapture() }),
|
|
afterJson: JSON.stringify({ inspection: passiveNetworkCapture() }),
|
|
},
|
|
],
|
|
[
|
|
contractInputBranch(captureDiff, "before_scenario").inputSchema,
|
|
{
|
|
beforeJson: JSON.stringify(scenarioExample.before_scenario),
|
|
afterJson: JSON.stringify(scenarioExample.after_scenario),
|
|
},
|
|
],
|
|
]);
|
|
|
|
/**
|
|
* Argv for commands whose contract rules need more than one value per
|
|
* required field: a selector choice, a pattern grammar or a change to make.
|
|
*/
|
|
const ARGV_SATISFYING_RULES: Readonly<
|
|
Record<string, Readonly<Record<string, unknown>>>
|
|
> = {
|
|
"annotate-native-function": { name: "renamed" },
|
|
"search-bytes": { pattern: "41 ??" },
|
|
"cutter-command": { sessionId: "00000000-0000-4000-8000-000000000001" },
|
|
"inspect-native-data-type": { type: "/struct" },
|
|
"capture-native-ui-scenario": {
|
|
steps: '[{"kind":"wait","milliseconds":0}]',
|
|
},
|
|
// The handler selects the local device when the caller selects none.
|
|
"list-frida-processes": { deviceId: "local" },
|
|
// The contract transforms the endpoint text it admits.
|
|
"list-browser-targets": { endpoint: "http://127.0.0.1:9222" },
|
|
"observe-web-session": { endpoint: "http://127.0.0.1:9222" },
|
|
"inspect-web-page": { endpoint: "http://127.0.0.1:9222" },
|
|
"list-electron-targets": { endpoint: "http://127.0.0.1:9222" },
|
|
"inspect-electron-page": { endpoint: "http://127.0.0.1:9222" },
|
|
"discover-webmcp-tools": { endpoint: "http://127.0.0.1:9222" },
|
|
"capture-web-screenshot": { endpoint: "http://127.0.0.1:9222" },
|
|
"observe-web-execution": { endpoint: "http://127.0.0.1:9222" },
|
|
"inspect-web-event-listeners": { endpoint: "http://127.0.0.1:9222" },
|
|
"analyze-web-bundle": { endpoint: "http://127.0.0.1:9222" },
|
|
"list-javascript-runtime-targets": { endpoint: "http://127.0.0.1:9229" },
|
|
"observe-javascript-runtime": { endpoint: "http://127.0.0.1:9229" },
|
|
// Each side must be a self-verifying screenshot artifact.
|
|
"compare-web-screenshots": {
|
|
beforeJson: JSON.stringify(screenshotExample.before),
|
|
afterJson: JSON.stringify(screenshotExample.after),
|
|
},
|
|
// Each side must be process capture Evidence.
|
|
"compare-process-captures": {
|
|
left: JSON.stringify(processComparisonExample.left),
|
|
right: JSON.stringify(processComparisonExample.right),
|
|
},
|
|
};
|
|
|
|
const each = descriptions.map(
|
|
(description) => [description.command, description] as const,
|
|
);
|
|
|
|
/** Every command the contract builders registered, from their registry. */
|
|
const contractBuilt: ReadonlySet<string> = new Set(
|
|
[...descriptions, ...contractDocumentCommandDescriptions(cli)].map(
|
|
({ command }) => command,
|
|
),
|
|
);
|
|
|
|
/** Contract-built commands whose name differs from their contract's. */
|
|
const RENAMED_CONTRACT_COMMANDS = [
|
|
"analyze",
|
|
"decompile",
|
|
"function",
|
|
"inspect",
|
|
"instructions",
|
|
"list-objdump-architectures",
|
|
"search",
|
|
"trace",
|
|
"validate-browser-scenario",
|
|
];
|
|
|
|
const commandName = (contract: string): string => contract.replaceAll("_", "-");
|
|
|
|
// Derived from the registries, so a command that stops registering through a
|
|
// contract builder fails here rather than silently leaving the parity cases.
|
|
it("builds every contract-named command from its contract", () => {
|
|
const named = new Set(TOOL_CONTRACTS.map(({ name }) => commandName(name)));
|
|
expect(
|
|
[...named]
|
|
.filter((name) => registered.has(name) && !contractBuilt.has(name))
|
|
.toSorted(),
|
|
).toEqual([]);
|
|
expect(
|
|
[...contractBuilt].filter((name) => !named.has(name)).toSorted(),
|
|
).toEqual(RENAMED_CONTRACT_COMMANDS);
|
|
});
|
|
|
|
// The CLI resolves a relative caller path against the working directory, so
|
|
// its help must not inherit an MCP description that requires an absolute one.
|
|
it("describes every caller path without requiring an absolute path", () => {
|
|
expect(
|
|
descriptions.flatMap(({ command, parameters }) =>
|
|
parameters
|
|
.filter(
|
|
({ callerPath, description }) =>
|
|
callerPath && /\babsolute\b/iu.test(description ?? ""),
|
|
)
|
|
.map(({ key }) => `${command} ${key}`),
|
|
),
|
|
).toEqual([]);
|
|
});
|
|
|
|
// An argv fixture names a contract-built command, so it cannot outlive its registration.
|
|
it("keeps every argv fixture on a contract-built command", () => {
|
|
expect(
|
|
Object.keys(ARGV_SATISFYING_RULES).filter(
|
|
(name) => !contractBuilt.has(name),
|
|
),
|
|
).toEqual([]);
|
|
});
|
|
|
|
describe("CLI commands projected from tool contracts", () => {
|
|
it.each(each)(
|
|
"%s exposes every contract field or declares its omission",
|
|
(_command, description) => {
|
|
expect(
|
|
[
|
|
...new Set(
|
|
description.parameters.flatMap(
|
|
({ field, group }) => group ?? [field],
|
|
),
|
|
),
|
|
...Object.keys(description.omitted),
|
|
...Object.keys(description.fixedFields),
|
|
...handlerSuppliedFields(description),
|
|
]
|
|
.toSorted()
|
|
.join(),
|
|
).toBe(Object.keys(contractShape(description)).toSorted().join());
|
|
const command = registered.get(description.command)!;
|
|
const argKeys = Object.keys(
|
|
(command.args as z.ZodObject | undefined)?.shape ?? {},
|
|
);
|
|
const optionKeys = Object.keys(
|
|
(command.options as z.ZodObject | undefined)?.shape ?? {},
|
|
);
|
|
expect(argKeys).toEqual([
|
|
...(description.sessionTarget === undefined
|
|
? []
|
|
: [description.sessionTarget.key]),
|
|
...(description.evidenceTargets?.targets ?? []).map(({ key }) => key),
|
|
...description.parameters
|
|
.filter(({ positional }) => positional)
|
|
.map(({ key }) => key),
|
|
...description.cliPositionals.map(({ key }) => key),
|
|
]);
|
|
// A routed command takes the union of its routes' options.
|
|
const routes = descriptions.filter(
|
|
({ command: name }) => name === description.command,
|
|
);
|
|
expect(optionKeys.toSorted()).toEqual(
|
|
[
|
|
...new Set(
|
|
routes.flatMap((route) => [
|
|
...route.parameters
|
|
.filter(({ positional }) => !positional)
|
|
.map(({ key }) => key),
|
|
...(route.sessionTarget?.options ?? []).map(({ key }) => key),
|
|
...(route.evidenceTargets?.options ?? []).map(({ key }) => key),
|
|
...route.cliOnlyOptions.map(({ key }) => key),
|
|
...route.parameters.flatMap(({ selectorOption }) =>
|
|
[selectorOption, selectorOption?.alternative].flatMap(
|
|
(option) => (option === undefined ? [] : [option.key]),
|
|
),
|
|
),
|
|
]),
|
|
),
|
|
].toSorted(),
|
|
);
|
|
},
|
|
);
|
|
|
|
it.each(each)(
|
|
"%s admits exactly what its contract admits",
|
|
(_command, description) => {
|
|
const mismatches: string[] = [];
|
|
for (const parameter of description.parameters) {
|
|
const cliField = registeredField(description, parameter);
|
|
const contractField = suppliedField(description, parameter);
|
|
// Incur's help reads flag and choice types only through `optional`.
|
|
expect(cliField, parameter.key).not.toBeInstanceOf(z.ZodExactOptional);
|
|
if (parameter.callerPath) {
|
|
// Only the absolute-path rule is relaxed, and only by resolution.
|
|
const spelled = (path: string) =>
|
|
parameter.repeatable ? [path] : path;
|
|
expect(admits(contractField, spelled("rel/x")), parameter.field).toBe(
|
|
false,
|
|
);
|
|
expect(
|
|
admits(contractField, spelled(absoluteCallerPath("rel/x"))),
|
|
).toBe(true);
|
|
}
|
|
if (parameter.inbound) {
|
|
expectInboundView(parameter.key, cliField, contractField);
|
|
continue;
|
|
}
|
|
if (parameter.runtimeJson !== undefined) {
|
|
// JSON text decoded when the command runs; see below. Argv
|
|
// requires the text of a required field.
|
|
expect(admits(cliField, undefined), parameter.key).toBe(
|
|
admits(contractField, undefined),
|
|
);
|
|
for (const value of ["{", "{}"])
|
|
expect(admits(cliField, value), parameter.key).toBe(true);
|
|
// Empty text is neither JSON nor a JSON input's file path.
|
|
expect(admits(cliField, ""), parameter.key).toBe(
|
|
!parameter.jsonInput,
|
|
);
|
|
continue;
|
|
}
|
|
for (const value of probes(contractField)) {
|
|
const expected = expectedAdmission(parameter, contractField, value);
|
|
if (admits(cliField, value) !== expected)
|
|
mismatches.push(
|
|
`${parameter.key}=${JSON.stringify(value)} expected ${String(expected)}`,
|
|
);
|
|
}
|
|
}
|
|
expect(mismatches).toEqual([]);
|
|
},
|
|
);
|
|
|
|
it.each(each)(
|
|
"%s takes each boolean contract field as a bare flag",
|
|
(_command, description) => {
|
|
for (const parameter of description.parameters) {
|
|
if (parameter.positional || !parameter.booleanFlag) continue;
|
|
const options = z.object({
|
|
[parameter.key]: registeredField(description, parameter),
|
|
});
|
|
const flag = `--${parameter.key.replaceAll(/[A-Z]/gu, (c) => `-${c.toLowerCase()}`)}`;
|
|
expect(Parser.parse([flag], { options }).options, flag).toEqual({
|
|
[parameter.key]: true,
|
|
});
|
|
}
|
|
},
|
|
);
|
|
|
|
it.each(each)(
|
|
"%s maps parsed argv to an admitted contract input",
|
|
(command, description) => {
|
|
const values = argvValues(
|
|
description,
|
|
ROUTE_ARGV.get(description.contract.inputSchema) ??
|
|
ARGV_SATISFYING_RULES[command] ??
|
|
{},
|
|
);
|
|
// Runtime JSON text is decoded as admission does.
|
|
for (const { key, runtimeJson } of description.parameters)
|
|
if (runtimeJson !== undefined && typeof values[key] === "string")
|
|
values[key] = JSON.parse(values[key]) as unknown;
|
|
const input = description.toContractInput(values);
|
|
const targets = new Set(handlerSuppliedFields(description));
|
|
const admitted =
|
|
targets.size === 0
|
|
? description.contract.inputSchema
|
|
: z.object(
|
|
Object.fromEntries(
|
|
Object.entries(contractShape(description)).filter(
|
|
([field]) => !targets.has(field),
|
|
),
|
|
),
|
|
);
|
|
expect(admitted.safeParse(input).error).toBe(undefined);
|
|
expectResolvedPositionalPaths(description, values, input);
|
|
},
|
|
);
|
|
});
|
|
|
|
describe("Registration refusals of contract commands", () => {
|
|
it.each([
|
|
["an object", z.object({ value: z.string() }).optional()],
|
|
["a record", z.record(z.string(), z.string()).optional()],
|
|
["a union", z.union([z.string(), z.boolean()]).optional()],
|
|
["a pipe", z.string().pipe(z.string()).optional()],
|
|
["an array of objects", z.array(z.object({})).optional()],
|
|
["an array of booleans", z.array(z.boolean()).optional()],
|
|
["a tuple", z.tuple([z.string()]).optional()],
|
|
])("refuses to describe a field that is %s", (_kind, field) => {
|
|
expect(() =>
|
|
describeContractCommand(
|
|
{ name: "probe", inputSchema: z.object({ field }) },
|
|
{ command: "probe", description: "Probe" },
|
|
),
|
|
).toThrow("probe.field has no argv projection");
|
|
});
|
|
|
|
it("takes an array of numbers as repeated decimal tokens within its bounds", () => {
|
|
const [parameter] = describeContractCommand(
|
|
{
|
|
name: "probe",
|
|
inputSchema: z.object({
|
|
ordinals: z.array(z.int().nonnegative()).min(1).max(2).optional(),
|
|
}),
|
|
},
|
|
{ command: "probe", description: "Probe" },
|
|
).parameters;
|
|
const schema = parameter!.schema;
|
|
expect(parameter!.repeatable).toBe(true);
|
|
expect(schema.parse(["0", "7"])).toEqual([0, 7]);
|
|
expect(schema.parse(undefined)).toBeUndefined();
|
|
for (const refused of [["0x1"], ["-1"], [], ["1", "2", "3"]])
|
|
expect(schema.safeParse(refused).success, String(refused)).toBe(false);
|
|
});
|
|
|
|
it("refuses an input constraint the CLI schema cannot carry", () => {
|
|
expect(() =>
|
|
describeContractCommand(
|
|
{
|
|
name: "probe",
|
|
inputSchema: z
|
|
.object({ value: z.string().optional() })
|
|
.meta({ not: { required: ["value"] } }),
|
|
},
|
|
{ command: "probe", description: "Probe" },
|
|
),
|
|
).toThrow("probe input keyword not has no CLI projection");
|
|
});
|
|
});
|
|
|
|
describe("CLI-only options of contract commands", () => {
|
|
it.each(each)(
|
|
"%s keeps its CLI-only options out of the contract input",
|
|
(_command, description) => {
|
|
const cliKeys = description.cliOnlyOptions.map(({ key }) => key);
|
|
const values = Object.fromEntries(cliKeys.map((key) => [key, "set"]));
|
|
const input = description.toContractInput(values);
|
|
for (const key of cliKeys) {
|
|
expect(Object.values(input), key).not.toContain("set");
|
|
expect(Object.keys(description.fields), key).not.toContain(key);
|
|
}
|
|
},
|
|
);
|
|
|
|
it("takes CLI-only positionals after the contract's and leaves handler fields to the handler", () => {
|
|
const contract = {
|
|
name: "probe",
|
|
inputSchema: z.object({
|
|
mode: z.enum(["a", "b"]),
|
|
id: z.number().optional(),
|
|
kind: z.enum(["x", "y"]),
|
|
value: z.string().optional(),
|
|
}),
|
|
};
|
|
const described = describeContractCommand(contract, {
|
|
command: "probe",
|
|
description: "Probe",
|
|
positionals: ["mode"],
|
|
cliOptions: { target: z.string().min(1) },
|
|
cliPositionals: ["target"],
|
|
handlerFields: ["id", "kind"],
|
|
});
|
|
expect(described.parameters.map(({ field }) => field)).toEqual([
|
|
"mode",
|
|
"value",
|
|
]);
|
|
expect(described.cliPositionals.map(({ key }) => key)).toEqual(["target"]);
|
|
expect(described.cliOnlyOptions).toEqual([]);
|
|
expect(described.handlerFields).toEqual(["id", "kind"]);
|
|
expect(
|
|
described.toContractInput({ mode: "a", target: "7", value: "v" }),
|
|
).toEqual({ mode: "a", value: "v" });
|
|
expect(described.cliOptionValues({ mode: "a", target: "7" })).toEqual({
|
|
target: "7",
|
|
});
|
|
expect(() =>
|
|
describeContractCommand(contract, {
|
|
command: "probe",
|
|
description: "Probe",
|
|
cliPositionals: ["missing" as never],
|
|
}),
|
|
).toThrow("probe has no CLI option missing");
|
|
expect(() =>
|
|
describeContractCommand(contract, {
|
|
command: "probe",
|
|
description: "Probe",
|
|
handlerFields: ["kind"],
|
|
fields: { kind: { name: "k" } },
|
|
}),
|
|
).toThrow("probe.kind is filled by the handler");
|
|
expect(() =>
|
|
describeContractCommand(contract, {
|
|
command: "probe",
|
|
description: "Probe",
|
|
handlerFields: ["absent" as never],
|
|
}),
|
|
).toThrow("probe has no input field absent");
|
|
});
|
|
|
|
it("refuses CLI-only options that collide with or depend on unknown keys", () => {
|
|
const contract = {
|
|
name: "probe",
|
|
inputSchema: z.object({ value: z.string().optional() }),
|
|
};
|
|
expect(() =>
|
|
describeContractCommand(contract, {
|
|
command: "probe",
|
|
description: "Probe",
|
|
cliOptions: { value: z.string().optional() },
|
|
}),
|
|
).toThrow("probe projects two fields to one CLI key");
|
|
expect(() =>
|
|
describeContractCommand(contract, {
|
|
command: "probe",
|
|
description: "Probe",
|
|
cliOptions: { extra: z.string().optional() },
|
|
cliOptionDependencies: { extra: ["missing"] },
|
|
}),
|
|
).toThrow("probe has no CLI option missing");
|
|
const described = describeContractCommand(contract, {
|
|
command: "probe",
|
|
description: "Probe",
|
|
cliOptions: { extra: z.string().optional() },
|
|
cliOptionDependencies: { extra: ["value"] },
|
|
});
|
|
expect(described.optionConstraints).toEqual({
|
|
dependentRequired: { extra: ["value"] },
|
|
});
|
|
expect(described.cliOptionValues({ value: "a", extra: "b" })).toEqual({
|
|
extra: "b",
|
|
});
|
|
expect(described.toContractInput({ value: "a", extra: "b" })).toEqual({
|
|
value: "a",
|
|
});
|
|
});
|
|
});
|
|
|
|
const decodingAtRunTime = each.filter(([, description]) =>
|
|
description.parameters.some(({ runtimeJson }) => runtimeJson !== undefined),
|
|
);
|
|
|
|
describe("JSON decoded when contract commands run", () => {
|
|
it.each(decodingAtRunTime)(
|
|
"%s refuses text that is not JSON before analysis",
|
|
(_command, description) => {
|
|
for (const parameter of description.parameters) {
|
|
// The command reads a JSON input before admission and refuses it
|
|
// there; the CLI tests cover that refusal.
|
|
if (parameter.runtimeJson === undefined || parameter.jsonInput)
|
|
continue;
|
|
const malformed = description.admit(
|
|
argvValues(description, {
|
|
detail: "summary",
|
|
evidence_output: "out.json",
|
|
[parameter.key]: "{",
|
|
}),
|
|
);
|
|
expect(malformed.ok, parameter.key).toBe(false);
|
|
if (!malformed.ok)
|
|
expect(malformed.error.issues).toEqual([
|
|
expect.objectContaining({
|
|
path: [parameter.key],
|
|
reason: "invalid_format",
|
|
message: parameter.runtimeJson,
|
|
}),
|
|
]);
|
|
}
|
|
},
|
|
);
|
|
|
|
it.each(decodingAtRunTime)(
|
|
"%s admits what its contract admits once decoded",
|
|
(_command, description) => {
|
|
const mismatches: string[] = [];
|
|
const details = description.evidenceDelivery
|
|
? (["complete", "summary"] as const)
|
|
: [undefined];
|
|
for (const parameter of description.parameters) {
|
|
if (parameter.runtimeJson === undefined) continue;
|
|
for (const detail of details)
|
|
for (const text of ["{}", "[]", "null", '{"unknown":1}', '["x"]']) {
|
|
const values = argvValues(description, {
|
|
...(detail === undefined
|
|
? {}
|
|
: { detail, evidence_output: "out.json" }),
|
|
[parameter.key]: text,
|
|
});
|
|
// The command hands admission a JSON input already decoded.
|
|
if (parameter.jsonInput)
|
|
values[parameter.key] = JSON.parse(text) as unknown;
|
|
const decoded = JSON.parse(text) as unknown;
|
|
const { group } = parameter;
|
|
// A field group supplies the members of a JSON object, each one
|
|
// of its fields; other JSON is refused before the contract.
|
|
const supplied =
|
|
group === undefined
|
|
? { [parameter.field]: decoded }
|
|
: typeof decoded === "object" &&
|
|
decoded !== null &&
|
|
!Array.isArray(decoded) &&
|
|
Object.keys(decoded).every((key) => group.includes(key))
|
|
? decoded
|
|
: undefined;
|
|
const expected =
|
|
supplied !== undefined &&
|
|
description.contract.inputSchema.safeParse({
|
|
...description.toContractInput({
|
|
...values,
|
|
[parameter.key]: undefined,
|
|
}),
|
|
...(detail === undefined ? {} : { detail }),
|
|
...supplied,
|
|
}).success;
|
|
const admitted = description.admit(values).ok;
|
|
// A checked JSON input is admitted by its check, which the
|
|
// command runs as soon as the input is read, and may be
|
|
// stricter than the contract; the contract admits the rest.
|
|
const check = parameter.checkJsonInput?.(decoded);
|
|
const refusedByCheck = check !== undefined && !check.ok;
|
|
if (expected ? !admitted : admitted && !refusedByCheck)
|
|
mismatches.push(
|
|
`${parameter.key} ${String(detail)} ${text} expected ${String(expected)}`,
|
|
);
|
|
}
|
|
}
|
|
expect(mismatches).toEqual([]);
|
|
},
|
|
);
|
|
});
|
|
|
|
const nullFlagged = each.filter(([, description]) =>
|
|
description.parameters.some(({ nullFlag }) => nullFlag !== undefined),
|
|
);
|
|
|
|
describe("Null-limit flags of contract commands", () => {
|
|
it.each(nullFlagged)(
|
|
"%s spells null with its flag and refuses the flag with a limit",
|
|
(_command, description) => {
|
|
const parameter = description.parameters.find(
|
|
({ nullFlag }) => nullFlag !== undefined,
|
|
)!;
|
|
const flag = parameter.nullFlag!;
|
|
expect(description.cliOnlyOptions.map(({ key }) => key)).toContain(flag);
|
|
expect(admits(contractShape(description)[parameter.field]!, null)).toBe(
|
|
true,
|
|
);
|
|
const all = argvValues(description, { [flag]: true });
|
|
expect(description.toContractInput(all)[parameter.field]).toBeNull();
|
|
expect(
|
|
description.contract.inputSchema.safeParse(
|
|
description.toContractInput(all),
|
|
).error,
|
|
).toBe(undefined);
|
|
expect(description.checkOptions?.(all)).toEqual([]);
|
|
const both = { ...all, [parameter.key]: 1 };
|
|
expect(description.checkOptions?.(both)).toEqual([
|
|
expect.objectContaining({
|
|
path: [flag],
|
|
message: `${flag} and ${parameter.key} are mutually exclusive`,
|
|
}),
|
|
]);
|
|
expect(description.optionConstraints?.not).toEqual({
|
|
required: [flag, parameter.key],
|
|
properties: { [flag]: { const: true } },
|
|
});
|
|
const bounded = argvValues(description, { [parameter.key]: 1 });
|
|
expect(description.toContractInput(bounded)[parameter.field]).toBe(1);
|
|
},
|
|
);
|
|
});
|
|
|
|
const flattening = each.filter(([, description]) =>
|
|
description.parameters.some(({ member }) => member !== undefined),
|
|
);
|
|
|
|
describe("Flattened object fields of contract commands", () => {
|
|
it.each(flattening)(
|
|
"%s supplies the object with only the given members",
|
|
(_command, description) => {
|
|
// A required object is always supplied, so only optional ones apply.
|
|
const fields = new Set(
|
|
description.parameters.flatMap(({ field, member }) =>
|
|
member === undefined ||
|
|
!contractShape(description)[field]!.safeParse(undefined).success
|
|
? []
|
|
: [field],
|
|
),
|
|
);
|
|
for (const field of fields) {
|
|
const members = description.parameters.filter(
|
|
(parameter) =>
|
|
parameter.field === field && parameter.member !== undefined,
|
|
);
|
|
expect(
|
|
field in description.toContractInput(argvValues(description, {})),
|
|
).toBe(false);
|
|
for (const given of members) {
|
|
const value = requiredValue(description, given);
|
|
const input = description.toContractInput(
|
|
argvValues(description, { [given.key]: value }),
|
|
);
|
|
// An omitted member stays omitted, never an explicit undefined;
|
|
// a nested member supplies each enclosing object with only itself.
|
|
let object = input[field] as Record<string, unknown>;
|
|
for (const member of given.member!.slice(0, -1)) {
|
|
expect(Object.keys(object)).toEqual([member]);
|
|
object = object[member] as Record<string, unknown>;
|
|
}
|
|
expect(Object.keys(object)).toEqual([given.member!.at(-1)]);
|
|
expect(object[given.member!.at(-1)!]).toEqual(
|
|
given.callerPath ? absoluteCallerPath(value as string) : value,
|
|
);
|
|
}
|
|
}
|
|
},
|
|
);
|
|
|
|
it("refuses to flatten part of an object or a non-object field", () => {
|
|
const contract = {
|
|
name: "probe",
|
|
inputSchema: z.object({
|
|
range: z.object({ a: z.number(), b: z.number() }).optional(),
|
|
value: z.string().optional(),
|
|
}),
|
|
};
|
|
expect(() =>
|
|
describeContractCommand(contract, {
|
|
command: "probe",
|
|
description: "Probe",
|
|
flatten: { range: { a: {} } },
|
|
}),
|
|
).toThrow("probe.range flattens other members");
|
|
expect(() =>
|
|
describeContractCommand(contract, {
|
|
command: "probe",
|
|
description: "Probe",
|
|
flatten: { range: { a: {}, b: {} }, value: { a: {} } },
|
|
}),
|
|
).toThrow("probe.value is not an object");
|
|
});
|
|
|
|
it("takes a required object's members as positionals in member order", () => {
|
|
const inputSchema = z.strictObject({
|
|
name: z.string(),
|
|
position: z.strictObject({ line: z.int(), column: z.int() }),
|
|
limits: z.strictObject({ bytes: z.int().optional() }).optional(),
|
|
});
|
|
const described = describeContractCommand(
|
|
{ name: "probe", inputSchema },
|
|
{
|
|
command: "probe",
|
|
description: "Probe",
|
|
positionals: ["name", "position"],
|
|
flatten: {
|
|
position: { line: {}, column: { name: "col" } },
|
|
limits: { bytes: {} },
|
|
},
|
|
},
|
|
);
|
|
expect(
|
|
described.parameters.map(({ key, positional }) => [key, positional]),
|
|
).toEqual([
|
|
["name", true],
|
|
["line", true],
|
|
["col", true],
|
|
["bytes", false],
|
|
]);
|
|
const [, line] = described.parameters;
|
|
expect(line!.schema.safeParse(undefined).success).toBe(false);
|
|
expect(line!.schema.safeParse("2").success).toBe(true);
|
|
expect(described.toContractInput({ name: "n", line: 2, col: 0 })).toEqual({
|
|
name: "n",
|
|
position: { line: 2, column: 0 },
|
|
});
|
|
expect(() =>
|
|
describeContractCommand(
|
|
{ name: "probe", inputSchema },
|
|
{
|
|
command: "probe",
|
|
description: "Probe",
|
|
positionals: ["limits"],
|
|
flatten: { limits: { bytes: {} } },
|
|
},
|
|
),
|
|
).toThrow("probe.limits is an optional positional object");
|
|
expect(() =>
|
|
describeContractCommand(
|
|
{
|
|
name: "probe",
|
|
inputSchema: z.strictObject({
|
|
position: z.strictObject({ line: z.int().optional() }),
|
|
}),
|
|
},
|
|
{
|
|
command: "probe",
|
|
description: "Probe",
|
|
positionals: ["position"],
|
|
flatten: { position: { line: {} } },
|
|
},
|
|
),
|
|
).toThrow("probe.position.line is an optional positional");
|
|
// Omitting every member would drop a required object argv cannot spell.
|
|
expect(() =>
|
|
describeContractCommand(
|
|
{
|
|
name: "probe",
|
|
inputSchema: z.strictObject({
|
|
limits: z.strictObject({ bytes: z.int().optional() }),
|
|
}),
|
|
},
|
|
{
|
|
command: "probe",
|
|
description: "Probe",
|
|
flatten: { limits: { bytes: {} } },
|
|
},
|
|
),
|
|
).toThrow("probe.limits has no required member");
|
|
});
|
|
});
|
|
|
|
const sessionTargeted = each.filter(
|
|
([, description]) => description.sessionTarget !== undefined,
|
|
);
|
|
|
|
describe("Session targets of contract commands", () => {
|
|
it.each(sessionTargeted)(
|
|
"%s takes the session target first and keeps it out of the contract input",
|
|
(_command, description) => {
|
|
const target = description.sessionTarget!;
|
|
const command = registered.get(description.command)!;
|
|
const args = (command.args as z.ZodObject).shape;
|
|
expect(Object.keys(args)[0]).toBe(target.key);
|
|
for (const value of ["rel/app", "/abs/app"])
|
|
expect(admits(args[target.key] as z.ZodType, value)).toBe(true);
|
|
for (const value of [undefined, "", "a\0b"])
|
|
expect(admits(args[target.key] as z.ZodType, value)).toBe(false);
|
|
const values = {
|
|
...argvValues(description, {}),
|
|
[target.key]: "rel/app",
|
|
};
|
|
expect(Object.values(description.toContractInput(values))).not.toContain(
|
|
"rel/app",
|
|
);
|
|
expect(
|
|
Object.values(description.callerInputs(values)).flat(),
|
|
).not.toContain("rel/app");
|
|
},
|
|
);
|
|
|
|
it.each(sessionTargeted)(
|
|
"%s names each renamed contract field by its CLI key in input issues",
|
|
(_command, description) => {
|
|
expect(description.inputBinding.operation).toBe(
|
|
description.contract.name,
|
|
);
|
|
// A selector field is named by its own option, which selection
|
|
// issues already use; its positional may share another key.
|
|
for (const {
|
|
field,
|
|
key,
|
|
member,
|
|
selectorOption,
|
|
} of description.parameters)
|
|
if (member === undefined) {
|
|
const named = selectorOption?.key ?? key;
|
|
expect(description.inputBinding.fields[field]).toBe(
|
|
named === field ? undefined : named,
|
|
);
|
|
}
|
|
},
|
|
);
|
|
|
|
it("refuses a root discriminator the projection neither delivers, omits nor selects", () => {
|
|
const mode = z.string();
|
|
const inputSchema = presentRootDiscriminator(
|
|
z.union([z.strictObject({ mode }), z.strictObject({ mode })]),
|
|
"mode",
|
|
);
|
|
expect(() =>
|
|
describeContractCommand(
|
|
// A root union of objects, as delivery-discriminated contracts are.
|
|
{ name: "probe", inputSchema } as never,
|
|
{
|
|
command: "probe",
|
|
description: "Probe",
|
|
},
|
|
),
|
|
).toThrow("probe root discriminator mode has no CLI projection");
|
|
});
|
|
|
|
it("refuses a session target beside a contract field keyed path", () => {
|
|
expect(() =>
|
|
describeContractCommand(
|
|
{ name: "probe", inputSchema: z.object({ path: z.string() }) },
|
|
{
|
|
command: "probe",
|
|
description: "Probe",
|
|
sessionTarget: { description: "Target" },
|
|
},
|
|
),
|
|
).toThrow("probe projects two fields to one CLI key");
|
|
});
|
|
});
|
|
|
|
const openingKeys = (description: ContractCliDescription) =>
|
|
description.sessionTarget!.options.map(({ key }) => key);
|
|
|
|
describe("Opening options of session-targeted contract commands", () => {
|
|
it.each(
|
|
sessionTargeted.filter(
|
|
([, description]) => description.sessionTarget!.options.length > 0,
|
|
),
|
|
)(
|
|
"%s keeps opening options out of the contract input",
|
|
(_command, description) => {
|
|
for (const key of openingKeys(description))
|
|
expect(Object.keys(description.fields), key).not.toContain(key);
|
|
expect(
|
|
description.sessionTarget!.admitOpening(description.contract.name, {}),
|
|
).toEqual({ ok: true, value: {} });
|
|
},
|
|
);
|
|
|
|
it.each(
|
|
sessionTargeted.filter(([, description]) =>
|
|
openingKeys(description).includes("entry-point"),
|
|
),
|
|
)(
|
|
"%s admits a native target interpretation with open_binary",
|
|
(_command, description) => {
|
|
const target = description.sessionTarget!;
|
|
const snapshot = openingKeys(description).includes("snapshot");
|
|
const values = {
|
|
...argvValues(
|
|
description,
|
|
ARGV_SATISFYING_RULES[description.command] ?? {},
|
|
),
|
|
[target.key]: "rel/app",
|
|
"target-format": "raw-binary",
|
|
architecture: "x86",
|
|
"entry-point": "0x100",
|
|
provider: "ghidra",
|
|
...(snapshot ? { snapshot: "rel/snapshot.json" } : {}),
|
|
};
|
|
expect(Object.values(description.toContractInput(values))).not.toContain(
|
|
"0x100",
|
|
);
|
|
// The snapshot is admitted resolved and passed on as typed.
|
|
expect(target.admitOpening(description.contract.name, values)).toEqual({
|
|
ok: true,
|
|
value: {
|
|
format: "raw-binary",
|
|
architecture: "x86",
|
|
entry_point: "0x100",
|
|
provider_id: "ghidra",
|
|
...(snapshot ? { snapshot_path: "rel/snapshot.json" } : {}),
|
|
},
|
|
});
|
|
// The pairing rule refuses before the target opens and names CLI keys.
|
|
const unpaired = target.admitOpening(description.contract.name, {
|
|
[target.key]: "rel/app",
|
|
"target-format": "raw-binary",
|
|
architecture: "x86",
|
|
});
|
|
expect(unpaired.ok).toBe(false);
|
|
if (!unpaired.ok)
|
|
expect(unpaired.error.issues).toEqual([
|
|
expect.objectContaining({
|
|
path: ["entry-point"],
|
|
message: expect.stringMatching(/requires architecture/u),
|
|
}),
|
|
]);
|
|
const format = target.options.find(({ key }) => key === "target-format")!;
|
|
expect(admits(format.schema, "raw-binary")).toBe(true);
|
|
expect(admits(format.schema, "esp-flash-image")).toBe(false);
|
|
},
|
|
);
|
|
|
|
it.each(
|
|
sessionTargeted.filter(([, description]) =>
|
|
openingKeys(description).includes("flashOffset"),
|
|
),
|
|
)(
|
|
"%s admits ESP flash options with the opening contract and keeps them out of the contract input",
|
|
(_command, description) => {
|
|
const target = description.sessionTarget!;
|
|
const values = {
|
|
...argvValues(description, {}),
|
|
[target.key]: "rel/app",
|
|
targetFormat: "esp-flash-image",
|
|
flashOffset: "0x1000",
|
|
};
|
|
for (const { key } of target.options)
|
|
expect(Object.keys(description.fields), key).not.toContain(key);
|
|
expect(Object.values(description.toContractInput(values))).not.toContain(
|
|
"0x1000",
|
|
);
|
|
expect(target.admitOpening(description.contract.name, values)).toEqual({
|
|
ok: true,
|
|
value: { format: "esp-flash-image", flash_offset: "0x1000" },
|
|
});
|
|
expect(target.admitOpening(description.contract.name, {})).toEqual({
|
|
ok: true,
|
|
value: {},
|
|
});
|
|
// The opening contract's pairing rule names the CLI key.
|
|
const unpaired = target.admitOpening(description.contract.name, {
|
|
[target.key]: "rel/app",
|
|
flashOffset: "0x1000",
|
|
});
|
|
expect(unpaired.ok).toBe(false);
|
|
if (!unpaired.ok)
|
|
expect(unpaired.error.issues).toEqual([
|
|
expect.objectContaining({
|
|
path: ["flashOffset"],
|
|
message: expect.stringMatching(/only with format=esp-flash-image/u),
|
|
}),
|
|
]);
|
|
// Only the projected values of an opening field are admitted.
|
|
const format = target.options.find(({ key }) => key === "targetFormat")!;
|
|
expect(admits(format.schema, "esp-flash-image")).toBe(true);
|
|
expect(admits(format.schema, "raw-binary")).toBe(false);
|
|
},
|
|
);
|
|
});
|
|
|
|
describe("Opening fields a session target projects", () => {
|
|
it("refuses opening fields the opening contract cannot supply", () => {
|
|
const opening = {
|
|
name: "open",
|
|
inputSchema: z.object({
|
|
path: z.string(),
|
|
mode: z.enum(["a", "b"]).optional(),
|
|
required: z.string(),
|
|
}),
|
|
};
|
|
const describeOpening = (
|
|
fields: Record<string, { values?: [string]; callerPath?: true }>,
|
|
) =>
|
|
describeContractCommand(
|
|
{ name: "probe", inputSchema: z.object({}) },
|
|
{
|
|
command: "probe",
|
|
description: "Probe",
|
|
sessionTarget: {
|
|
description: "Target",
|
|
open: { contract: opening, fields },
|
|
},
|
|
},
|
|
);
|
|
expect(() => describeOpening({ missing: {} })).toThrow(
|
|
"open has no option field missing",
|
|
);
|
|
expect(() => describeOpening({ path: {} })).toThrow(
|
|
"open has no option field path",
|
|
);
|
|
expect(() => describeOpening({ required: {} })).toThrow(
|
|
"open.required is required",
|
|
);
|
|
expect(() => describeOpening({ mode: { values: ["c"] } })).toThrow(
|
|
"open.mode does not admit c",
|
|
);
|
|
expect(() => describeOpening({ mode: { callerPath: true } })).toThrow(
|
|
"open.mode is not a path",
|
|
);
|
|
});
|
|
});
|
|
|
|
/** Summary selections for contracts whose summary requires a view. */
|
|
const SUMMARY_SELECTIONS: Readonly<
|
|
Record<string, Readonly<Record<string, unknown>>>
|
|
> = {
|
|
"analyze-web-bundle": {
|
|
view: '{"kind":"web-bundle","collection":"endpoints"}',
|
|
},
|
|
};
|
|
|
|
const delivering = each.filter(
|
|
([, description]) => description.evidenceDelivery,
|
|
);
|
|
|
|
describe("Evidence delivery of contract commands", () => {
|
|
it.each(delivering)(
|
|
"%s refuses summary delivery without --evidence_output before analysis",
|
|
(command, description) => {
|
|
const satisfying = {
|
|
...ARGV_SATISFYING_RULES[command],
|
|
...SUMMARY_SELECTIONS[command],
|
|
};
|
|
const refused = description.admit(
|
|
argvValues(description, { ...satisfying, detail: "summary" }),
|
|
);
|
|
expect(refused.ok).toBe(false);
|
|
if (!refused.ok)
|
|
expect(refused.error.issues.map(({ path }) => path)).toEqual([
|
|
["evidence_output"],
|
|
]);
|
|
expect(
|
|
description.admit(
|
|
argvValues(description, {
|
|
...satisfying,
|
|
detail: "summary",
|
|
evidence_output: "out.json",
|
|
}),
|
|
).ok,
|
|
).toBe(true);
|
|
},
|
|
);
|
|
|
|
it("refuses a union input whose branches differ outside the delivery", () => {
|
|
const inputSchema = z.discriminatedUnion("detail", [
|
|
z.object({
|
|
detail: z.literal("complete").optional(),
|
|
limit: z.number().optional(),
|
|
}),
|
|
z.object({
|
|
detail: z.literal("summary"),
|
|
limit: z.number().max(1).optional(),
|
|
}),
|
|
]);
|
|
expect(() =>
|
|
describeContractCommand(
|
|
{ name: "probe", inputSchema },
|
|
{ command: "probe", description: "Probe", evidenceDelivery: true },
|
|
),
|
|
).toThrow("probe.limit differs between input branches");
|
|
expect(() =>
|
|
describeContractCommand(
|
|
{ name: "probe", inputSchema },
|
|
{ command: "probe", description: "Probe" },
|
|
),
|
|
).toThrow("probe.limit differs between input branches");
|
|
});
|
|
|
|
it("selects an input branch with a literal in one branch and an enum in another", () => {
|
|
const inputSchema = z.union([
|
|
z.strictObject({ format: z.literal("json").default("json") }),
|
|
z.strictObject({ format: z.enum(["sdl", "graphql"]) }),
|
|
]);
|
|
const [format] = describeContractCommand(
|
|
{ name: "probe", inputSchema },
|
|
{ command: "probe", description: "Probe" },
|
|
).parameters;
|
|
expect(format!.schema.parse(undefined)).toBe("json");
|
|
expect(format!.schema.safeParse("graphql").success).toBe(true);
|
|
expect(format!.schema.safeParse("xml").success).toBe(false);
|
|
});
|
|
|
|
it("takes the input branches a command selects and fixes a single selected value", () => {
|
|
const path = z.string();
|
|
const inputSchema = z.discriminatedUnion("operation", [
|
|
z.strictObject({ operation: z.enum(["a", "b"]), path }),
|
|
z.strictObject({
|
|
operation: z.literal("c"),
|
|
path,
|
|
symbol: z.string().optional(),
|
|
}),
|
|
z.strictObject({ operation: z.literal("d") }),
|
|
]);
|
|
const describe = (values: readonly [string, ...string[]]) =>
|
|
describeContractCommand(
|
|
{ name: "probe", inputSchema },
|
|
{
|
|
command: "probe",
|
|
description: "Probe",
|
|
inputBranches: { field: "operation", values },
|
|
},
|
|
);
|
|
const artifact = describe(["a", "b", "c"]);
|
|
expect(artifact.parameters.map(({ key }) => key)).toEqual([
|
|
"operation",
|
|
"path",
|
|
"symbol",
|
|
]);
|
|
const operation = artifact.parameters[0]!.schema;
|
|
expect(operation.safeParse("c").success).toBe(true);
|
|
expect(operation.safeParse("d").success).toBe(false);
|
|
expect(artifact.parameters[1]!.schema.safeParse(undefined).success).toBe(
|
|
false,
|
|
);
|
|
const fixed = describe(["d"]);
|
|
expect(fixed.parameters).toEqual([]);
|
|
expect(fixed.toContractInput({})).toEqual({ operation: "d" });
|
|
expect(inputSchema.safeParse(fixed.toContractInput({})).success).toBe(true);
|
|
expect(() => describe(["a"])).toThrow(
|
|
"probe.operation would narrow an input branch",
|
|
);
|
|
expect(() => describe(["e"])).toThrow(
|
|
"probe.operation selects no branch for a value",
|
|
);
|
|
expect(() =>
|
|
describeContractCommand(
|
|
{ name: "probe", inputSchema: z.object({ operation: z.string() }) },
|
|
{
|
|
command: "probe",
|
|
description: "Probe",
|
|
inputBranches: { field: "operation", values: ["a"] },
|
|
},
|
|
),
|
|
).toThrow("probe has one input branch");
|
|
});
|
|
});
|
|
|
|
const documents = contractDocumentCommandDescriptions(cli).map(
|
|
(description) => [description.command, description] as const,
|
|
);
|
|
|
|
/** The JSON Schemas a property path can reach, through unions. */
|
|
const reachable = (
|
|
schema: Record<string, unknown>,
|
|
path: readonly string[],
|
|
): Record<string, unknown>[] => {
|
|
// A typed schema keeps its own type; `allOf` there only adds constraints.
|
|
const branches =
|
|
schema.type !== undefined
|
|
? []
|
|
: ["anyOf", "oneOf", "allOf"].flatMap((keyword) =>
|
|
Array.isArray(schema[keyword])
|
|
? (schema[keyword] as Record<string, unknown>[])
|
|
: [],
|
|
);
|
|
if (branches.length > 0)
|
|
return branches.flatMap((branch) => reachable(branch, path));
|
|
const [head, ...rest] = path;
|
|
if (head === undefined) return [schema];
|
|
const properties = schema.properties as
|
|
| Record<string, Record<string, unknown>>
|
|
| undefined;
|
|
const next = properties?.[head];
|
|
return next === undefined ? [] : reachable(next, rest);
|
|
};
|
|
|
|
describe("JSON-document contract commands", () => {
|
|
it.each(documents)(
|
|
"%s takes one JSON document whose --schema is its contract input",
|
|
(_command, description) => {
|
|
const command = registered.get(description.command)!;
|
|
const args = (command.args as z.ZodObject).shape;
|
|
expect(Object.keys(args)).toEqual([
|
|
...(description.sessionTarget === undefined
|
|
? []
|
|
: [description.sessionTarget.key]),
|
|
description.key,
|
|
]);
|
|
const advertised = (args[description.key] as z.ZodType).meta();
|
|
expect(advertised?.contentMediaType).toBe("application/json");
|
|
const content = advertised?.contentSchema as Record<string, unknown>;
|
|
expect(content).toEqual(jsonInputContentSchema(description.content));
|
|
// Every contract field reaches the document unless omitted with a
|
|
// reason or taken as an option beside it.
|
|
const input = inputJsonSchema(description.contract.inputSchema);
|
|
const fields = new Set(
|
|
reachable(input, []).flatMap((branch) =>
|
|
Object.keys(
|
|
(branch.properties as Record<string, unknown> | undefined) ?? {},
|
|
),
|
|
),
|
|
);
|
|
for (const field of fields)
|
|
expect(
|
|
reachable(content, [field]).length > 0 ||
|
|
Object.hasOwn(description.omitted, field) ||
|
|
Object.hasOwn(description.flagged, field),
|
|
field,
|
|
).toBe(true);
|
|
for (const field of [
|
|
...Object.keys(description.omitted),
|
|
...Object.keys(description.flagged),
|
|
])
|
|
expect(reachable(content, [field]), field).toEqual([]);
|
|
const options = [
|
|
...description.deliveryOptions,
|
|
...description.cliOnlyOptions,
|
|
].map(({ key }) => key);
|
|
for (const key of Object.values(description.flagged))
|
|
expect(options, key).toContain(key);
|
|
expect(
|
|
Object.keys(
|
|
(command.options as z.ZodObject | undefined)?.shape ?? {},
|
|
).toSorted(),
|
|
).toEqual(options.toSorted());
|
|
},
|
|
);
|
|
|
|
it.each(documents.filter(([, { callerPaths }]) => callerPaths.length > 0))(
|
|
"%s resolves only caller paths its contract declares as strings",
|
|
(_command, description) => {
|
|
const input = inputJsonSchema(description.contract.inputSchema);
|
|
for (const path of description.callerPaths) {
|
|
const targets = reachable(input, path);
|
|
expect(targets.length, path.join(".")).toBeGreaterThan(0);
|
|
for (const target of targets)
|
|
expect(target.type, path.join(".")).toBe("string");
|
|
}
|
|
},
|
|
);
|
|
|
|
it("refuses omissions the document cannot make and options that shadow it", () => {
|
|
const contract = {
|
|
name: "probe",
|
|
inputSchema: z.object({
|
|
required: z.string(),
|
|
optional: z.string().optional(),
|
|
}),
|
|
};
|
|
const projection = {
|
|
command: "probe",
|
|
description: "Probe",
|
|
document: "Probe JSON",
|
|
};
|
|
expect(() =>
|
|
describeContractDocumentCommand(contract, {
|
|
...projection,
|
|
omit: { required: "never" },
|
|
}),
|
|
).toThrow("probe.required is not an optional field");
|
|
expect(() =>
|
|
describeContractDocumentCommand(
|
|
{
|
|
name: "probe",
|
|
inputSchema: z.union([
|
|
z.object({ a: z.string().optional() }),
|
|
z.object({ b: z.string() }),
|
|
]),
|
|
},
|
|
{ ...projection, omit: { a: "never" } },
|
|
),
|
|
).toThrow("probe omits fields from a union input");
|
|
expect(() =>
|
|
describeContractDocumentCommand(contract, {
|
|
...projection,
|
|
cliOptions: { inputJson: z.string().optional() },
|
|
}),
|
|
).toThrow("probe projects two fields to one CLI key");
|
|
const described = describeContractDocumentCommand(contract, {
|
|
...projection,
|
|
omit: { optional: "Not one-shot" },
|
|
});
|
|
expect(
|
|
Object.keys(inputJsonSchema(described.content).properties as object),
|
|
).toEqual(["required"]);
|
|
});
|
|
});
|
|
|
|
describe("JSON-document delivery options", () => {
|
|
const contract = {
|
|
name: "probe",
|
|
inputSchema: z.object({
|
|
required: z.string(),
|
|
optional: z.string().optional(),
|
|
}),
|
|
};
|
|
const projection = {
|
|
command: "probe",
|
|
description: "Probe",
|
|
document: "Probe JSON",
|
|
};
|
|
|
|
it("takes detail and view beside the document and admits them before the handler", () => {
|
|
expect(() =>
|
|
describeContractDocumentCommand(contract, {
|
|
...projection,
|
|
evidenceDelivery: true,
|
|
}),
|
|
).toThrow("probe.detail is not an optional field");
|
|
const delivered = {
|
|
name: "probe",
|
|
inputSchema: contract.inputSchema.extend({
|
|
detail: z.enum(["complete", "summary"]).default("complete"),
|
|
view: z.object({ offset: z.number() }).optional(),
|
|
}),
|
|
};
|
|
expect(() =>
|
|
describeContractDocumentCommand(delivered, {
|
|
...projection,
|
|
viewDelivery: { invalidJson: "view must be JSON" },
|
|
}),
|
|
).toThrow("probe view delivery requires evidenceDelivery");
|
|
expect(() =>
|
|
describeContractDocumentCommand(delivered, {
|
|
...projection,
|
|
evidenceDelivery: true,
|
|
omit: { detail: "never" },
|
|
}),
|
|
).toThrow("probe.detail is both omitted and an option");
|
|
expect(() =>
|
|
describeContractDocumentCommand(delivered, {
|
|
...projection,
|
|
evidenceDelivery: true,
|
|
cliOptions: { evidence_output: z.string().optional() },
|
|
}),
|
|
).toThrow("probe projects two fields to one CLI key");
|
|
const flagged = describeContractDocumentCommand(delivered, {
|
|
...projection,
|
|
evidenceDelivery: true,
|
|
viewDelivery: { invalidJson: "view must be JSON" },
|
|
});
|
|
expect(
|
|
Object.keys(inputJsonSchema(flagged.content).properties as object),
|
|
).toEqual(["required", "optional"]);
|
|
expect(flagged.admitDelivery({ detail: "complete" })).toEqual({
|
|
ok: true,
|
|
value: { detail: "complete", evidenceOutput: undefined },
|
|
});
|
|
expect(
|
|
flagged.admitDelivery({
|
|
detail: "summary",
|
|
evidence_output: "out.json",
|
|
view: '{"offset":2}',
|
|
}),
|
|
).toEqual({
|
|
ok: true,
|
|
value: {
|
|
detail: "summary",
|
|
evidenceOutput: "out.json",
|
|
view: { offset: 2 },
|
|
},
|
|
});
|
|
for (const values of [
|
|
{ detail: "complete", view: '{"offset":2}' },
|
|
{ detail: "summary", evidence_output: "out.json", view: "{" },
|
|
{
|
|
detail: "summary",
|
|
evidence_output: "out.json",
|
|
view: '{"offset":"2"}',
|
|
},
|
|
{ detail: "summary" },
|
|
])
|
|
expect(flagged.admitDelivery(values).ok, JSON.stringify(values)).toBe(
|
|
false,
|
|
);
|
|
});
|
|
});
|
|
|
|
const selecting = each.flatMap(([command, description]) =>
|
|
description.parameters.flatMap((parameter) =>
|
|
parameter.selectorOption === undefined
|
|
? []
|
|
: [[command, description, parameter, parameter.selectorOption] as const],
|
|
),
|
|
);
|
|
|
|
describe("Positional selectors with a named option", () => {
|
|
it.each(selecting)(
|
|
"%s takes its selector positionally or by its named option",
|
|
(_command, description, parameter, option) => {
|
|
const command = registered.get(description.command)!;
|
|
const named = (command.options as z.ZodObject).shape[option.key];
|
|
expect(admits(named as z.ZodType, undefined)).toBe(true);
|
|
expect(admits(named as z.ZodType, "-dash")).toBe(true);
|
|
// A required selector is refused when neither spelling is given,
|
|
// including where only the CLI requires it.
|
|
expect(option.required).toBe(
|
|
option.required ||
|
|
!admits(description.fields[parameter.field]!, undefined),
|
|
);
|
|
const { required } = option;
|
|
const admit = (values: Record<string, unknown>) =>
|
|
description.admit({
|
|
[description.sessionTarget?.key ?? "path"]: "rel/app",
|
|
...values,
|
|
});
|
|
const selected = (values: Record<string, unknown>) => {
|
|
const result = admit(values);
|
|
return result.ok ? result.value.input[parameter.field] : result.error;
|
|
};
|
|
expect(selected({ [parameter.key]: "main" })).toBe("main");
|
|
expect(selected({ [option.valueKey]: "-main" })).toBe("-main");
|
|
expect(selected({ [parameter.key]: "m", [option.valueKey]: "m" })).toBe(
|
|
"m",
|
|
);
|
|
const issues = (values: Record<string, unknown>) => {
|
|
const result = admit(values);
|
|
return result.ok ? [] : result.error.issues;
|
|
};
|
|
expect(issues({ [parameter.key]: "a", [option.valueKey]: "b" })).toEqual([
|
|
expect.objectContaining({
|
|
path: [option.key],
|
|
reason: "invalid_value",
|
|
}),
|
|
]);
|
|
if (required)
|
|
expect(issues({})).toEqual([
|
|
expect.objectContaining({
|
|
path: [option.key],
|
|
reason: "missing_argument",
|
|
}),
|
|
]);
|
|
if (option.kind === "native")
|
|
// The named spelling is kept when both name one native address.
|
|
expect(
|
|
selected({ [parameter.key]: "0x1a", [option.valueKey]: "0x1A" }),
|
|
).toBe("0x1A");
|
|
},
|
|
);
|
|
|
|
const alternatives = selecting.flatMap(
|
|
([command, description, parameter, option]) =>
|
|
option.alternative === undefined
|
|
? []
|
|
: [[command, description, parameter, option.alternative] as const],
|
|
);
|
|
it.each(alternatives)(
|
|
"%s maps its alternative selector option onto the same field",
|
|
(_command, description, parameter, alternative) => {
|
|
const option = parameter.selectorOption!;
|
|
const admit = (values: Record<string, unknown>) =>
|
|
description.admit({
|
|
[description.sessionTarget?.key ?? "path"]: "rel/app",
|
|
...values,
|
|
});
|
|
const alone = admit({ [alternative.valueKey]: "0x10" });
|
|
expect(alone.ok && alone.value.input[parameter.field]).toBe(
|
|
alternative.selects("0x10"),
|
|
);
|
|
const agreeing = admit({
|
|
[alternative.valueKey]: "0x10",
|
|
[option.valueKey]: alternative.selects("0x10"),
|
|
});
|
|
expect(agreeing.ok).toBe(true);
|
|
for (const conflicting of [
|
|
{ [alternative.valueKey]: "0x10", [parameter.key]: "main" },
|
|
{ [alternative.valueKey]: "0x10", [option.valueKey]: "main" },
|
|
]) {
|
|
const result = admit(conflicting);
|
|
expect(result.ok ? [] : result.error.issues).toEqual([
|
|
expect.objectContaining({
|
|
path: [alternative.key],
|
|
reason: "invalid_value",
|
|
}),
|
|
]);
|
|
}
|
|
},
|
|
);
|
|
|
|
it("refuses a selector whose contract admits an empty value", () => {
|
|
expect(() =>
|
|
describeContractCommand(
|
|
{ name: "probe", inputSchema: z.object({ text: z.string() }) },
|
|
{
|
|
command: "probe",
|
|
description: "Probe",
|
|
positionals: ["text"],
|
|
selectorOptions: { text: { name: "text", description: "Text" } },
|
|
},
|
|
),
|
|
).toThrow("probe.text admits an empty selector");
|
|
});
|
|
|
|
it("refuses a selector option on a field that is not a positional text selector", () => {
|
|
const describeSelector = (
|
|
positionals: readonly ("text" | "count")[],
|
|
field: "text" | "count",
|
|
) =>
|
|
describeContractCommand(
|
|
{
|
|
name: "probe",
|
|
inputSchema: z.object({ text: z.string(), count: z.number() }),
|
|
},
|
|
{
|
|
command: "probe",
|
|
description: "Probe",
|
|
positionals,
|
|
selectorOptions: { [field]: { name: "named", description: "Named" } },
|
|
},
|
|
);
|
|
expect(() => describeSelector([], "text")).toThrow(
|
|
"probe.text is not a positional selector",
|
|
);
|
|
expect(() => describeSelector(["count"], "count")).toThrow(
|
|
"probe.count is not a text selector",
|
|
);
|
|
});
|
|
});
|
|
|
|
describe("Operation choices selected by an option", () => {
|
|
it("refuses an operation choice whose contract projects other options", () => {
|
|
const projection = {
|
|
command: "probe",
|
|
description: "Probe",
|
|
operationBy: {
|
|
option: "kind",
|
|
contracts: {
|
|
other: {
|
|
name: "other",
|
|
inputSchema: z.object({ text: z.string(), extra: z.string() }),
|
|
},
|
|
},
|
|
},
|
|
};
|
|
const base = describeContractCommand(
|
|
{ name: "probe", inputSchema: z.object({ text: z.string() }) },
|
|
projection,
|
|
);
|
|
expect(() => describeOperationChoices(base, projection)).toThrow(
|
|
"other does not project to probe's options",
|
|
);
|
|
});
|
|
|
|
it("refuses an operation choice whose contract projects other option rules", () => {
|
|
const projection = {
|
|
command: "probe",
|
|
description: "Probe",
|
|
operationBy: {
|
|
option: "kind",
|
|
contracts: {
|
|
other: {
|
|
name: "other",
|
|
inputSchema: z
|
|
.object({ text: z.string(), limit: z.number().optional() })
|
|
.meta({ dependentRequired: { limit: ["text"] } }),
|
|
},
|
|
},
|
|
},
|
|
};
|
|
const base = describeContractCommand(
|
|
{
|
|
name: "probe",
|
|
inputSchema: z.object({
|
|
text: z.string(),
|
|
limit: z.number().optional(),
|
|
}),
|
|
},
|
|
projection,
|
|
);
|
|
expect(() => describeOperationChoices(base, projection)).toThrow(
|
|
"other does not project to probe's options",
|
|
);
|
|
});
|
|
});
|
|
|
|
describe("Contract command field groups", () => {
|
|
const contract = {
|
|
name: "group_probe",
|
|
inputSchema: z.strictObject({
|
|
path: z.string(),
|
|
name: z.string().optional(),
|
|
tags: z.array(z.string()).optional(),
|
|
}),
|
|
};
|
|
const grouped = (
|
|
fields: readonly [
|
|
"name" | "tags" | "path",
|
|
...("name" | "tags" | "path")[],
|
|
],
|
|
) =>
|
|
describeContractCommand(contract, {
|
|
command: "group-probe",
|
|
description: "Probe",
|
|
positionals: ["path"],
|
|
fieldGroups: {
|
|
query: {
|
|
fields,
|
|
description: "JSON selection",
|
|
invalidJson: "query must be a JSON selection object.",
|
|
},
|
|
},
|
|
});
|
|
|
|
it("supplies each member of one JSON object option as its contract field", () => {
|
|
const description = grouped(["name", "tags"]);
|
|
expect(description.parameters.map(({ key }) => key)).toEqual([
|
|
"path",
|
|
"query",
|
|
]);
|
|
const admitted = description.admit({
|
|
path: "/x",
|
|
query: '{"name":"a","tags":["b"]}',
|
|
});
|
|
expect(admitted.ok && admitted.value.input).toEqual({
|
|
path: "/x",
|
|
name: "a",
|
|
tags: ["b"],
|
|
});
|
|
expect(description.admit({ path: "/x" }).ok).toBe(true);
|
|
});
|
|
|
|
it.each([
|
|
["[]", ["query"], "invalid_format"],
|
|
['{"path":"/y"}', ["query", "path"], undefined],
|
|
['{"name":1}', ["name"], undefined],
|
|
])("refuses the group %s", (text, path, reason) => {
|
|
const admitted = grouped(["name", "tags"]).admit({
|
|
path: "/x",
|
|
query: text,
|
|
});
|
|
expect(admitted.ok).toBe(false);
|
|
if (admitted.ok) return;
|
|
expect(admitted.error.issues[0]).toMatchObject({
|
|
path,
|
|
...(reason === undefined ? {} : { reason }),
|
|
});
|
|
});
|
|
|
|
it("refuses a group member an object rule names", () => {
|
|
expect(() =>
|
|
describeContractCommand(
|
|
{
|
|
name: "group_probe",
|
|
inputSchema: contract.inputSchema.meta({
|
|
dependentRequired: { name: ["tags"] },
|
|
}),
|
|
},
|
|
{
|
|
command: "group-probe",
|
|
description: "Probe",
|
|
positionals: ["path"],
|
|
fieldGroups: {
|
|
query: {
|
|
fields: ["name", "tags"],
|
|
description: "x",
|
|
invalidJson: "x",
|
|
},
|
|
},
|
|
},
|
|
),
|
|
).toThrow("group_probe.name is grouped but named by an input rule");
|
|
});
|
|
|
|
it("refuses a required or twice-projected group member", () => {
|
|
expect(() => grouped(["path"])).toThrow(
|
|
"group_probe.path is projected twice",
|
|
);
|
|
expect(() =>
|
|
describeContractCommand(contract, {
|
|
command: "group-probe",
|
|
description: "Probe",
|
|
fieldGroups: {
|
|
query: { fields: ["path"], description: "x", invalidJson: "x" },
|
|
},
|
|
}),
|
|
).toThrow("group_probe.path is a required group member");
|
|
});
|
|
});
|