Module simulate 

Structs

CycleBreakCandidate

One candidate edge whose removal would reduce the report’s cycle count.

SequenceError

Annotates a SimulateError with which step in a chain failed.

Enums

Action

One step in a what-if simulation chain. Each variant maps to a single-action helper in this module — simulate_sequence applies them in order. The JSON shape matches the MCP raysense_what_if tool: the discriminator key is action, and the field names align with the per-action MCP arguments.

SimulateError

Functions

add_edge

Add a local import edge from from_path to to_path. Returns EdgeAlreadyExists if the same local edge is already present.

break_cycle

Remove the local import edge from from_path to to_path and confirm the reduction lowers the report’s cycle count. Returns EdgeNotFound if the edge does not exist, or EdgeNotInCycle if removal does not break a cycle (i.e., the edge is not load-bearing for any cycle).

break_cycle_recommendations

Rank candidate local edges by how much each one’s removal reduces the report’s cycle count. Considers up to max_candidates distinct local edges (capped to avoid quadratic cost on large graphs); returns at most limit recommendations sorted by reduction (descending), then path. Returns an empty list when the report has no cycles.

move_file

Produce a ScanReport representing the codebase as if from_path had been moved to to_path. The file keeps its file_id (and so all imports/calls referencing it stay valid); only path, module, and the graph-derived metrics that depend on path/module change.

remove_edge

Remove the local import edge from from_path to to_path. Returns EdgeNotFound if no such local edge exists.

remove_file

Produce a ScanReport representing the codebase as if file_path did not exist. All facts referencing the file (and any functions defined in it) are dropped, and remaining file/function/call ids are renumbered so downstream consumers that index by id continue to work.

simulate_sequence

Apply a sequence of Actions in order, threading the mutated ScanReport through each step. Returns the first SimulateError encountered, indexed by action position so callers know which step failed. Filesystem state is never touched — every mutation is in-memory.