Files
reverse-engineering-anything/src/contracts/toolEffects.test.ts
T
morluto 717333ce9b refactor(contracts): declare each tool's effect audit on its contract (#11305)
* refactor(contracts): declare each tool's effect audit on its contract

Every public tool's effects lived in a 255-entry TOOL_EFFECT_AUDIT table in
toolEffects.ts, keyed by name and looked up again by toolContractMetadata,
the capability inventory (toolSessionEffects) and tests (TOOL_EFFECTS).

toolContractMetadata(name, audit) now takes the audit from the contract
declaration, and the contract carries both the provider-wide effects and
the session effects. The inventory reads contract.sessionEffects. The
table, TOOL_EFFECTS and toolSessionEffects are removed; toolEffects.ts
keeps the effect type, the shared presets and annotation derivation.

Effects, session effects, annotations and titles are byte-identical for all
255 contracts.

* test(contracts): read focused effect expectations from their contract family
2026-11-16 03:50:32 +08:00

192 lines
5.9 KiB
TypeScript

import { readFileSync } from "node:fs";
import { describe, expect, it } from "vitest";
import { TOOL_CONTRACTS } from "./toolContracts.js";
import { annotationsFromEffects, type ToolEffects } from "./toolEffects.js";
/**
* Reviewed tools whose audited effects make them destructive. The derived set
* may grow without an edit here, but a tool leaves only by removing its name
* from this sorted file, so a dropped destructive effect is a deliberate,
* reviewed change rather than a silent loss of the client's confirmation.
*/
const REVIEWED_DESTRUCTIVE_TOOLS = JSON.parse(
readFileSync(
new URL("./destructiveTools.baseline.json", import.meta.url),
"utf8",
),
) as readonly string[];
const contractNamed = (name: string) =>
TOOL_CONTRACTS.find((contract) => contract.name === name);
describe("tool effects", () => {
it("keeps every reviewed destructive tool destructive", () => {
expect(REVIEWED_DESTRUCTIVE_TOOLS).toEqual(
[...new Set(REVIEWED_DESTRUCTIVE_TOOLS)].sort(),
);
const contracts = new Map<string, (typeof TOOL_CONTRACTS)[number]>(
TOOL_CONTRACTS.map((contract) => [contract.name, contract]),
);
for (const name of REVIEWED_DESTRUCTIVE_TOOLS) {
const contract = contracts.get(name);
expect(contract, `${name} has no contract`).toBeDefined();
expect(annotationsFromEffects(contract!.effects), name).toMatchObject({
readOnlyHint: false,
destructiveHint: true,
});
expect(contract!.annotations, name).toMatchObject({
readOnlyHint: false,
destructiveHint: true,
});
}
});
it("declares the web bundle worker's private file and child process effects", () => {
const contract = TOOL_CONTRACTS.find(
({ name }) => name === "analyze_web_bundle",
);
expect(contract?.effects).toMatchObject({
mutatesSession: true,
accessesNetwork: true,
launchesProcess: true,
writesFilesystem: true,
executesForeignCode: false,
mutatesTarget: false,
});
});
it("derives destructiveHint from each destructive effect alone", () => {
// Keep annotation algebra independent of any operation's audited effects.
const base: ToolEffects = {
mutatesTarget: false,
mutatesSession: false,
writesFilesystem: false,
launchesProcess: false,
accessesNetwork: false,
changesUiState: false,
mayDiscardData: false,
executesForeignCode: false,
mutatesDevice: false,
idempotent: true,
};
expect(annotationsFromEffects(base)).toEqual({
readOnlyHint: true,
destructiveHint: false,
idempotentHint: true,
openWorldHint: false,
});
for (const flag of [
"mayDiscardData",
"executesForeignCode",
"mutatesDevice",
] as const)
expect(annotationsFromEffects({ ...base, [flag]: true }), flag).toEqual({
readOnlyHint: false,
destructiveHint: true,
idempotentHint: true,
openWorldHint: false,
});
});
it("marks automatic GDB detach as destructive target execution", () => {
const effects = contractNamed("close_gdb_session")?.effects;
if (effects === undefined)
throw new Error("close_gdb_session is unaudited");
expect(effects).toMatchObject({
mutatesTarget: true,
executesForeignCode: true,
});
expect(annotationsFromEffects(effects).destructiveHint).toBe(true);
});
it("publishes the advertised annotations derived from canonical effects", () => {
for (const contract of TOOL_CONTRACTS)
expect(contract.annotations, contract.name).toEqual(
annotationsFromEffects(contract.effects),
);
});
});
it("advertises IDA provider effects while retaining session bases", () => {
for (const name of [
"procedure_pseudo_code",
"procedure_assembly",
"read_function_instructions",
"analyze_function",
]) {
expect(contractNamed(name)?.effects, name).toMatchObject({
mutatesSession: true,
changesUiState: true,
accessesNetwork: true,
});
expect(contractNamed(name)?.sessionEffects, name).toMatchObject({
mutatesSession: true,
changesUiState: false,
accessesNetwork: false,
});
const contract = TOOL_CONTRACTS.find(
(candidate) => candidate.name === name,
);
expect(contract?.annotations, name).toMatchObject({
readOnlyHint: false,
destructiveHint: false,
openWorldHint: true,
});
}
for (const name of [
"batch_decompile",
"decompile_all",
"trace_native_values",
"inspect_native_api",
]) {
expect(contractNamed(name)?.effects, name).toMatchObject({
changesUiState: true,
accessesNetwork: true,
});
expect(contractNamed(name)?.sessionEffects, name).toMatchObject({
changesUiState: false,
accessesNetwork: false,
});
}
});
it("audits network access during lifecycle cleanup across provider changes", () => {
for (const name of [
"open_binary",
"open_bundle_resources",
"close_binary",
"reset_investigation",
"start_rizin_debug_session",
"close_rizin_debug_session",
"close_gdb_session",
]) {
expect(contractNamed(name)?.sessionEffects.accessesNetwork, name).toBe(
true,
);
expect(contractNamed(name)?.effects.accessesNetwork, name).toBe(true);
expect(
TOOL_CONTRACTS.find((contract) => contract.name === name)?.annotations
.openWorldHint,
name,
).toBe(true);
}
});
it("advertises signature inspection's temporary snapshot filesystem writes", () => {
expect(contractNamed("inspect_signature")?.effects).toMatchObject({
writesFilesystem: true,
mutatesTarget: false,
launchesProcess: true,
});
});
it("advertises inspect_macho's temporary private operand filesystem writes", () => {
expect(contractNamed("inspect_macho")?.effects).toMatchObject({
writesFilesystem: true,
mutatesTarget: false,
launchesProcess: true,
});
});