feat(move): graph-aware move of a module-level definition (#1534)

codebase_rag/cli.py

@@ -2317,6 +2317,75 @@ def rename_command(
         raise typer.Exit(code=1)
 
 
+@app.command(
+    name=ch.CLICommandName.MOVE,
+    help=ch.CMD_MOVE,
+    short_help=ch.CMD_MOVE,
+    epilog=ch.EXAMPLES_MOVE,
+    rich_help_panel=ch.PANEL_USE,
+)
+def move_command(
+    qualified_name: str = typer.Argument(..., help=ch.HELP_MOVE_QN),
+    target_module: str = typer.Argument(..., help=ch.HELP_MOVE_TARGET),
+    repo_path: Path = typer.Option(
+        Path(cs.MCP_DEFAULT_DIRECTORY),
+        "--repo-path",
+        exists=True,
+        file_okay=False,
+        help=ch.HELP_GRAPH_REPO_PATH,
+    ),
+    project: str | None = typer.Option(None, "--project", help=ch.HELP_GRAPH_PROJECT),
+    keep_alias: bool = typer.Option(
+        False, "--keep-alias", help=ch.HELP_MOVE_KEEP_ALIAS
+    ),
+    dry_run: bool = typer.Option(False, "--dry-run", help=ch.HELP_MOVE_DRY_RUN),
+) -> None:
+    from .editing.move import MoveRefused, move
+    from .graph_cli import _project_and_fetch
+    from .graph_query import source_root_for
+
+    name, fetch_all, ingestor = _project_and_fetch(project, repo_path)
+    with ingestor:
+        # An explicit --project may name a graph indexed from another
+        # checkout; its repo-relative paths must not be edited under this one.
+        if source_root_for(fetch_all, name, repo_path) is None:
+            typer.echo(
+                cs.MOVE_CLI_WRONG_ROOT.format(project=name, root=repo_path.resolve()),
+                err=True,
+            )
+            raise typer.Exit(code=1)
+        parsers, queries = load_parsers()
+        from .graph_updater import GraphUpdater
+
+        updater = GraphUpdater(
+            ingestor=ingestor,
+            repo_path=repo_path.resolve(),
+            parsers=parsers,
+            queries=queries,
+            project_name=name,
+        )
+        try:
+            report = move(
+                repo_path.resolve(),
+                fetch_all,
+                name,
+                qualified_name,
+                target_module,
+                keep_alias=keep_alias,
+                dry_run=dry_run,
+                reingest=updater.reingest,
+            )
+        except MoveRefused as refused:
+            typer.echo(str(refused), err=True)
+            raise typer.Exit(code=1) from refused
+    payload = dict(report._asdict())
+    if report.verdict is not None:
+        payload[cs.KEY_VERDICT] = report.verdict._asdict()
+    typer.echo(json.dumps(payload, indent=cs.MCP_JSON_INDENT, sort_keys=True))
+    if not report.applied and not dry_run:
+        raise typer.Exit(code=1)
+
+
 @app.command(
     name=ch.CLICommandName.CHANGE_SIGNATURE,
     help=ch.CMD_CHANGE_SIGNATURE,

codebase_rag/cli_help.py

@@ -23,6 +23,7 @@ class CLICommandName(StrEnum):
     CHECK = "check"
     RENAME = "rename"
     CHANGE_SIGNATURE = "change-signature"
+    MOVE = "move"
     CONTEXT = "context"
     PORT = "port"
     STOP = "stop"
@@ -223,6 +224,22 @@ class CLICommandName(StrEnum):
     "a trace as well, instead of listing them as unmapped."
 )
 HELP_CHANGE_SIGNATURE_DRY_RUN = "Print the plan and diff without writing anything."
+CMD_MOVE = (
+    "Move a module-level definition to another module: importers rewritten, "
+    "needed imports carried, refused when it would create an import cycle."
+)
+EXAMPLES_MOVE = (
+    "Examples:\n  cgr move myproj.pkg.util.helper pkg.core --dry-run\n"
+    "  cgr move myproj.pkg.util.helper pkg/core.py --keep-alias"
+)
+HELP_MOVE_QN = "Qualified name of the module-level definition to move."
+HELP_MOVE_DRY_RUN = (
+    "Print the plan (files, importers, copied imports) without writing anything."
+)
+HELP_MOVE_TARGET = "Destination module: dotted name (pkg.core) or repo-relative path."
+HELP_MOVE_KEEP_ALIAS = (
+    "Leave a re-export at the old location so the old import path still works."
+)
 CMD_CONTEXT = (
     "Print a graph-ranked context slice for a symbol, location or task within "
     "a token budget: source, caller lines, callee signatures, types, tests, docs."
@@ -742,6 +759,7 @@ class CLICommandName(StrEnum):
     CLICommandName.CHECK: CMD_CHECK,
     CLICommandName.RENAME: CMD_RENAME,
     CLICommandName.CHANGE_SIGNATURE: CMD_CHANGE_SIGNATURE,
+    CLICommandName.MOVE: CMD_MOVE,
     CLICommandName.CONTEXT: CMD_CONTEXT,
     CLICommandName.PORT: CMD_PORT,
     CLICommandName.WORKSPACE: CMD_WORKSPACE,

codebase_rag/constants/ast_nodes.py

@@ -111,6 +111,7 @@
 FIELD_PROPERTY = "property"
 FIELD_NAME = "name"
 FIELD_ALIAS = "alias"
+FIELD_SOURCE = "source"
 FIELD_MODULE_NAME = "module_name"
 FIELD_ARGUMENTS = "arguments"
 FIELD_BODY = "body"

codebase_rag/constants/cli.py

@@ -1112,6 +1112,72 @@ class DiffMarker:
 CONTEXT_WHY_TEST = "test reaching it at depth {depth} through {through}"
 CONTEXT_WHY_DOC = "documentation section whose file links to it"
 CONTEXT_UNRESOLVED = "Nothing in the graph matches {target}"
+# move (issue #1534).
+MOVE_UNKNOWN = "No definition named {qn} in the graph"
+MOVE_METHOD = "{qn} is a method; move its class instead"
+MOVE_SAME_MODULE = "{path} already holds the definition"
+MOVE_NO_GRAMMAR = "No grammar for {path}; the definition cannot be moved"
+MOVE_NO_DEFINITION_TOKEN = "Could not locate the definition of {qn} in {path}"
+MOVE_CYCLE = "Refusing to move: it would create the import cycle {cycle}"
+MOVE_IMPORT_COLLISION = (
+    "{path} already binds {name}; the import the moved definition needs would rebind it"
+)
+MOVE_MAYBE_UNBOUND = (
+    "{names} may be unbound in {path}: it is set under a module-level if, "
+    "try or loop that does not bind it on every path, so the moved "
+    "definition cannot import it safely"
+)
+MOVE_SPLIT_GLOBAL = (
+    "{names} is a variable of {path} rebound through a global statement; "
+    "the destination would import it as a separate copy, so the moved "
+    "definition and {path} would stop seeing each other's updates"
+)
+MOVE_ASSIGNS_IMPORT = (
+    "{names} is a variable of {path} that the moved definition assigns; "
+    "imported into the destination it is a read-only binding, so the "
+    "assignment would throw"
+)
+MOVE_WILDCARD_IMPORTER = (
+    "{importers} import(s) everything from {path} with *, and would no "
+    "longer get {name} from it; pass keep_alias to keep {path} exporting it"
+)
+MOVE_STAR_PROVIDED = (
+    "{names} reaches {path} only through a star import from {modules}; "
+    "the destination would not bind it, so the moved definition would "
+    "raise NameError; import it by name in {path} first"
+)
+MOVE_FUTURE_ANNOTATIONS = (
+    "{enabled} enables from __future__ import annotations and {disabled} "
+    "does not; the move would change how the annotations in {changed} "
+    "evaluate"
+)
+MOVE_RELATIVE_IMPORT_ESCAPES = (
+    "{statement} in {qn} climbs above the top-level package of {path}, so "
+    "the move cannot respell it for the destination"
+)
+MOVE_PLANNED = "{importers} importer(s) would be rewritten, {unchanged} left unchanged"
+MOVE_PARSE_FAILED = "Move rolled back: {files} would no longer parse"
+MOVE_SOURCE_CHANGED = (
+    "Cannot stage the move: {files} changed on disk after the move was "
+    "planned; retry once the tree is settled"
+)
+MOVE_CONTRACT_FAILED = "Move rolled back, postcondition failed: {reasons}"
+MOVE_CONTRACT_UNMEASURED = (
+    "Move applied, but its postcondition could not be measured: {error}"
+)
+MOVE_ROLLBACK_UNMEASURED = (
+    "Move rolled back after its postcondition failed ({reasons}), but the "
+    "graph could not be re-ingested afterwards ({error}); rebuild the graph "
+    "before the next graph-backed operation"
+)
+MOVE_WRONG_ROOT = (
+    "Project {project} was not indexed from this server's repository; "
+    "move from the MCP server rooted at its source tree"
+)
+MOVE_CLI_WRONG_ROOT = (
+    "Project {project} was not indexed from {root}; "
+    "pass the --repo-path it was indexed from"
+)
 # Postcondition contract (issue #1531).
 CONTRACT_OP_RENAME = "rename"
 CONTRACT_OP_CHANGE_SIGNATURE = "change_signature"

codebase_rag/constants/graph.py

@@ -123,6 +123,7 @@ class (and, uncertain, other calls in files naming the class or
 KEY_UNMAPPED = "unmapped"
 KEY_VERDICT = "verdict"
 KEY_STRUCTURAL_DELTA = "structural_delta"
+KEY_CYCLE = "cycle"
 KEY_DISPATCH_LITERAL = "dispatch_literal"
 
 

codebase_rag/constants/mcp.py

@@ -28,6 +28,7 @@ class MCPToolName(StrEnum):
     # Graph-driven edit operations (issues #1532, #1533).
     RENAME = "rename"
     CHANGE_SIGNATURE = "change_signature"
+    MOVE = "move"
     CONTEXT = "context"
     QUERY_CODE_GRAPH = "query_code_graph"
     GET_CODE_SNIPPET = "get_code_snippet"
@@ -126,6 +127,8 @@ class MCPParamName(StrEnum):
     ALLOW_HEURISTIC = "allow_heuristic"
     NEW_PARAMS = "new_params"
     MAPPING = "mapping"
+    TARGET_MODULE = "target_module"
+    KEEP_ALIAS = "keep_alias"
     BUDGET_TOKENS = "budget_tokens"
 
 

codebase_rag/cypher_queries.py

@@ -1633,7 +1633,7 @@ def build_missing_rel_endpoints_query(
 RETURN labels(n)[0] AS label, n.qualified_name AS qualified_name, n.name AS name,
        n.path AS path, n.start_line AS start_line, n.end_line AS end_line,
        n.decorators AS decorators"""
-CYPHER_DELTA_MODULE_IMPORTS = """MATCH (m:Module)-[:IMPORTS]->(t:Module)
+CYPHER_DELTA_MODULE_IMPORTS = """MATCH (m:Module)-[r:IMPORTS]->(t:Module)
 WHERE m.qualified_name STARTS WITH $project_prefix
   AND t.qualified_name STARTS WITH $project_prefix
   AND ALL(longer_project IN $longer_project_prefixes
@@ -1643,7 +1643,7 @@ def build_missing_rel_endpoints_query(
           WHERE t.qualified_name <> longer_project
             AND NOT t.qualified_name STARTS WITH (longer_project + '.'))
 RETURN DISTINCT m.qualified_name AS from_qn, m.path AS from_path,
-       t.qualified_name AS to_qn"""
+       t.qualified_name AS to_qn, r.imported_name AS imported_name"""
 # The import statements that bind a symbol BY NAME into or out of the
 # touched files (issue #2516), one row per bound name: an importer of a
 # touched module still naming a symbol the edit removed, and a touched
@@ -1707,6 +1707,12 @@ def build_missing_rel_endpoints_query(
 MATCH (doc)-[:CONTAINS_SECTION]->(s:Section)
 RETURN doc.qualified_name AS from_qn, s.qualified_name AS qualified_name, s.name AS name,
        s.path AS path, s.start_line AS start_line, s.end_line AS end_line"""
+# What one module imports, with each statement's site (issue #1534).
+CYPHER_GRAPH_IMPORTS_OF = """MATCH (m:Module)-[r:IMPORTS]->(target)
+WHERE m.qualified_name = $qn AND m.qualified_name STARTS WITH $project_prefix
+RETURN target.qualified_name AS to_qn, r.line AS line, r.col AS col,
+       r.end_line AS end_line, r.end_col AS end_col, r.alias AS alias,
+       r.imported_name AS imported_name"""
 CYPHER_GRAPH_IMPORTERS = """MATCH (m:Module)-[r:IMPORTS]->(target)
 WHERE target.qualified_name = $qn AND m.qualified_name STARTS WITH $project_prefix
 RETURN m.qualified_name AS qualified_name, m.path AS path, r.line AS line,

codebase_rag/editing/contract.py

@@ -382,13 +382,16 @@ def measure(
     files: Iterable[str],
     reingest: Reingest,
     declared_renames: Iterable[tuple[str, str]] = (),
+    reshaped_renames: Iterable[tuple[str, str]] = (),
 ) -> StructuralDelta:
     """The delta of files an operation just wrote, through the re-ingest.
 
     `declared_renames` are the pairs the operation APPLIED. The delta infers
     renames from the snapshots, which cannot be done for an empty container
     (no fingerprint, no members, and the name is what changed), so an
     operation that knows says so rather than leaving it to a guess.
+    `reshaped_renames` are those whose body the operation also rewrote, so
+    the snapshots cannot pair them by shape either.
     """
     paths = sorted(set(files))
     return observe(
@@ -398,4 +401,5 @@ def measure(
         lambda: reingest(paths),
         repo_root=repo_root,
         declared_renames=frozenset(declared_renames),
+        reshaped_renames=frozenset(reshaped_renames),
     )