refactor: preserve planner behavior around deterministic targets

Author: xingxuling

aetherfusion/planner/fusion_planner.py

@@ -11,22 +11,42 @@ def generate_fusion_plan(
     map_path: Path,
     module_name: str,
 ) -> dict[str, Any]:
-    """Generate a detailed module-level fusion plan from a JSON project map."""
+    """Generate a detailed module-level fusion plan from a JSON project map.
+
+    Args:
+        map_path: Path to the JSON project map generated by ``aetherfusion scan --json``.
+        module_name: Name of the module to plan for (must exist in fusion_plan_candidates).
+
+    Returns:
+        Structured fusion plan dict.
+
+    Raises:
+        FileNotFoundError: If the map file does not exist.
+        ValueError: If the module is not found in fusion_plan_candidates.
+        json.JSONDecodeError: If the map file is not valid JSON.
+    """
     if not map_path.is_file():
         raise FileNotFoundError(f"JSON map not found: {map_path}")
 
     with open(map_path, "r", encoding="utf-8") as f:
         data = json.load(f)
 
+    # Find the module in fusion_plan_candidates
     candidates: list[dict[str, Any]] = data.get("fusion_plan_candidates", [])
-    candidate = next((c for c in candidates if c.get("module_name") == module_name), None)
+    candidate = None
+    for c in candidates:
+        if c.get("module_name") == module_name:
+            candidate = c
+            break
+
     if candidate is None:
         available = sorted([c.get("module_name", "?") for c in candidates])
         raise ValueError(
             f"Module '{module_name}' not found in fusion_plan_candidates. "
             f"Available modules: {', '.join(available) if available else '(none)'}"
         )
 
+    # Build the plan
     source_info = data.get("projects", {}).get("source", {})
     target_info = data.get("projects", {}).get("target", {})
     conflicts = data.get("conflicts", {})
@@ -35,8 +55,9 @@ def generate_fusion_plan(
     source_module_path = _pick_first(candidate.get("source_paths", []))
     target_match_path = _pick_first(candidate.get("target_paths", []))
 
-    # Source-only transfer modules need a deterministic destination so patch/apply
-    # can form a complete transaction rather than emitting an empty target path.
+    # Source-only transfer modules still need a deterministic destination.
+    # Use <target_project>/<module_name> rather than leaving the path empty;
+    # safe_apply will create the directory without overwriting existing files.
     source_only_transfer = (
         not target_match_path
         and bool(source_module_path)
@@ -83,12 +104,15 @@ def generate_fusion_plan(
             "do not make any network requests",
         ],
         "next_recommended_command": (
-            f"python -m aetherfusion plan --map {map_path} --module {module_name}"
+            f"python -m aetherfusion plan "
+            f"--map {map_path} "
+            f"--module {module_name}"
         ),
     }
 
 
 def _pick_first(paths: list[str]) -> str | None:
+    """Return the first path from a list or None."""
     return paths[0] if paths else None
 
 
@@ -97,68 +121,121 @@ def _build_ordered_steps(
     candidate: dict[str, Any],
     conflicts: dict[str, Any],
 ) -> list[dict[str, Any]]:
+    """Build the ordered steps for module fusion."""
+
     source_paths: list[str] = candidate.get("source_paths", [])
     target_paths: list[str] = candidate.get("target_paths", [])
     name_conflicts = {c.get("relative_path", "") for c in conflicts.get("name_conflicts", [])}
-    has_same_named = module_name in name_conflicts or bool(source_paths and target_paths)
 
-    return [
-        {
-            "step": 1,
-            "action": "inspect_same_named_files",
-            "description": f"Inspect files in module '{module_name}' for naming collisions between source and target projects.",
-            "details": {
-                "source_paths": source_paths,
-                "target_paths": target_paths,
-                "has_same_named_conflicts": has_same_named,
-                "recommended_tool": "Use aetherfusion scan to identify file-level conflicts, then manually diff conflicting files.",
-            },
-            "estimated_complexity": "medium" if has_same_named else "low",
+    steps: list[dict[str, Any]] = []
+
+    # Step 1: Inspect same-named files
+    has_same_named = module_name in name_conflicts or bool(source_paths and target_paths)
+    steps.append({
+        "step": 1,
+        "action": "inspect_same_named_files",
+        "description": (
+            f"Inspect files in module '{module_name}' for naming collisions between "
+            f"source and target projects."
+        ),
+        "details": {
+            "source_paths": source_paths,
+            "target_paths": target_paths,
+            "has_same_named_conflicts": has_same_named,
+            "recommended_tool": (
+                "Use aetherfusion scan to identify specific file-level conflicts, "
+                "then manually diff the conflicting files."
+            ),
         },
-        {
-            "step": 2,
-            "action": "copy_non_conflicting_files",
-            "description": f"Identify files in '{module_name}' that do not conflict with target files and prepare a copy plan.",
-            "details": {
-                "condition": "Only files not present in target should be copied in this step.",
-                "status": "BLOCKED — v0.2 is read-only; actual file copy is deferred to v0.3+.",
-                "note": "Human review is required before copying.",
-            },
-            "estimated_complexity": "low",
+        "estimated_complexity": "medium" if has_same_named else "low",
+    })
+
+    # Step 2: Copy non-conflicting files
+    steps.append({
+        "step": 2,
+        "action": "copy_non_conflicting_files",
+        "description": (
+            f"Identify files in '{module_name}' that do NOT conflict with "
+            f"target files, and prepare a copy plan."
+        ),
+        "details": {
+            "condition": "Only files NOT present in target should be copied in this step.",
+            "status": "BLOCKED — v0.2 is read-only; actual file copy is deferred to v0.3+.",
+            "note": (
+                "List candidate files here with their source paths. "
+                "Human review required before copying."
+            ),
         },
-        {
-            "step": 3,
-            "action": "review_import_dependencies",
-            "description": f"Review import/require statements within '{module_name}' so they resolve in the target project.",
-            "details": {
-                "target_dependencies": "Check whether imported modules are available in the target project.",
-                "relative_imports": "Verify relative paths remain valid after fusion.",
-                "status": "Requires manual review — automatic import rewriting is out of scope for v0.2.",
-            },
-            "estimated_complexity": "medium",
+        "estimated_complexity": "low",
+    })
+
+    # Step 3: Review import dependencies
+    steps.append({
+        "step": 3,
+        "action": "review_import_dependencies",
+        "description": (
+            f"Review all import/require statements within '{module_name}' files "
+            f"to ensure they resolve correctly in the target project."
+        ),
+        "details": {
+            "target_dependencies": (
+                "Check if imported modules are available in the target project. "
+                "If any are missing, add them to the target dependency list."
+            ),
+            "relative_imports": (
+                "If the module uses relative imports (e.g., '../utils'), verify "
+                "that the relative path is still valid after fusion."
+            ),
+            "status": "Requires manual review — automatic import rewriting is out of scope for v0.2.",
         },
-        {
-            "step": 4,
-            "action": "check_config_requirements",
-            "description": f"Check whether '{module_name}' requires target config changes.",
-            "details": {
-                "tsconfig_paths": "Check path aliases.",
-                "env_vars": "Document required environment variables.",
-                "build_config": "Review module-specific build settings.",
-            },
-            "estimated_complexity": "medium",
+        "estimated_complexity": "medium",
+    })
+
+    # Step 4: Check config requirements
+    steps.append({
+        "step": 4,
+        "action": "check_config_requirements",
+        "description": (
+            f"Check if '{module_name}' requires any config changes in the target "
+            f"project (e.g., new aliases, env vars, build config)."
+        ),
+        "details": {
+            "tsconfig_paths": (
+                "If the source project uses tsconfig path aliases (e.g., '@components/*'), "
+                "ensure the target tsconfig.json includes the same aliases."
+            ),
+            "env_vars": (
+                "Check for any environment variables used by the module "
+                "(e.g., API_URL, VITE_*) and document them for the target project."
+            ),
+            "build_config": (
+                "If using Vite/Webpack configs, check for any module-specific "
+                "settings that need to be merged."
+            ),
         },
-        {
-            "step": 5,
-            "action": "prepare_dry_run_patch",
-            "description": f"Generate a dry-run preview for fusing '{module_name}' into the target project.",
-            "details": {
-                "status": "BLOCKED — v0.2 is planning-only; patch generation is deferred to v0.3+.",
-                "planned_actions": "Produce create/copy/modify operations with before/after paths for review.",
-            },
-            "estimated_complexity": "low (planning only)",
+        "estimated_complexity": "medium",
+    })
+
+    # Step 5: Prepare dry-run patch
+    steps.append({
+        "step": 5,
+        "action": "prepare_dry_run_patch",
+        "description": (
+            f"Generate a dry-run preview of all changes that would be made "
+            f"when fusing '{module_name}' into the target project."
+        ),
+        "details": {
+            "status": "BLOCKED — v0.2 is planning-only; patch generation is deferred to v0.3+.",
+            "planned_actions": (
+                "This step will eventually produce a list of create/copy/modify "
+                "operations with before/after paths, enabling a human to review "
+                "the full impact before execution."
+            ),
         },
-    ]
+        "estimated_complexity": "low (planning only)",
+    })
+
+    return steps
 
 
 def _build_human_decisions(
@@ -167,66 +244,85 @@ def _build_human_decisions(
     conflicts: dict[str, Any],
     deps: dict[str, Any],
 ) -> list[dict[str, Any]]:
+    """Build the list of required human decisions for this fusion plan."""
+
     source_paths: list[str] = candidate.get("source_paths", [])
     target_paths: list[str] = candidate.get("target_paths", [])
     has_same_path = bool(source_paths and target_paths)
     ver_conflicts = deps.get("version_conflicts", [])
 
-    return [
-        {
-            "decision_id": "same_named_files",
-            "question": f"How should same-named files in module '{module_name}' be handled?",
-            "context": (
-                f"Source and target both contain a module named '{module_name}'. Files with identical names must be resolved."
-                if has_same_path
-                else f"No same-named file conflicts are currently detected for '{module_name}', but this should be confirmed."
-            ),
-            "options": [
-                {"value": "overwrite", "label": "Overwrite", "description": "Replace target files with source versions."},
-                {"value": "namespace", "label": "Namespace", "description": "Rename source files to avoid collisions."},
-                {"value": "skip", "label": "Skip", "description": "Skip conflicting files."},
-                {"value": "manual_merge", "label": "Manual Merge", "description": "Manually merge each conflicting file."},
-            ],
-            "is_blocking": True,
-        },
-        {
-            "decision_id": "dependency_updates",
-            "question": "Should dependency conflicts allow updating package.json / requirements.txt?",
-            "context": (
-                f"{len(ver_conflicts)} dependency version conflict(s) detected."
-                if ver_conflicts
-                else "No dependency version conflicts detected; confirm whether new dependencies are needed."
-            ),
-            "options": [
-                {"value": "allow", "label": "Allow Updates", "description": "Permit dependency file changes."},
-                {"value": "deny", "label": "Deny Updates", "description": "Resolve conflicts manually."},
-                {"value": "review", "label": "Review Each", "description": "Review each conflict individually."},
-            ],
-            "is_blocking": True,
-        },
-        {
-            "decision_id": "route_integration",
-            "question": "Should routing conflicts be resolved by integrating into target routes?",
-            "context": f"If '{module_name}' defines routes or entry points, decide whether to merge or isolate them.",
-            "options": [
-                {"value": "integrate", "label": "Integrate Routes", "description": "Merge into target routing."},
-                {"value": "isolate", "label": "Isolate Routes", "description": "Keep routes separate."},
-                {"value": "defer", "label": "Defer Decision", "description": "Revisit after initial fusion."},
-            ],
-            "is_blocking": False,
-        },
-        {
-            "decision_id": "preserve_structure",
-            "question": "Should the original source directory structure be preserved?",
-            "context": (
-                f"Source: {', '.join(source_paths) if source_paths else '(none)'}. "
-                f"Target: {', '.join(target_paths) if target_paths else '(none)'}."
-            ),
-            "options": [
-                {"value": "preserve", "label": "Preserve Structure", "description": "Keep the source layout."},
-                {"value": "flatten", "label": "Flatten Structure", "description": "Flatten into target structure."},
-                {"value": "adapt", "label": "Adapt to Target", "description": "Reorganize to target conventions."},
-            ],
-            "is_blocking": False,
-        },
-    ]
+    decisions: list[dict[str, Any]] = []
+
+    # Decision 1: How to handle same-named files
+    decisions.append({
+        "decision_id": "same_named_files",
+        "question": f"How should same-named files in module '{module_name}' be handled?",
+        "context": (
+            f"Source and target both contain a module named '{module_name}'. "
+            f"Files with identical names exist in both projects and must be resolved."
+        ) if has_same_path else (
+            f"Currently no same-named file conflicts detected for '{module_name}', "
+            f"but this should be confirmed before proceeding."
+        ),
+        "options": [
+            {"value": "overwrite", "label": "Overwrite", "description": "Replace target files with source versions."},
+            {"value": "namespace", "label": "Namespace", "description": "Rename source files to avoid collisions (e.g., add '_fusion' suffix)."},
+            {"value": "skip", "label": "Skip", "description": "Skip conflicting files; only copy non-conflicting ones."},
+            {"value": "manual_merge", "label": "Manual Merge", "description": "Manually review and merge each conflicting file."},
+        ],
+        "is_blocking": True,
+    })
+
+    # Decision 2: Dependency conflicts
+    decisions.append({
+        "decision_id": "dependency_updates",
+        "question": "Should dependency conflicts allow updating package.json / requirements.txt?",
+        "context": (
+            f"{len(ver_conflicts)} dependency version conflict(s) detected. "
+            f"Resolving these may require updating the target project's dependency files."
+        ) if ver_conflicts else (
+            "No dependency version conflicts detected for this module. "
+            "Confirm that no new dependencies need to be added to the target project."
+        ),
+        "options": [
+            {"value": "allow", "label": "Allow Updates", "description": "Permit modification of package.json / requirements.txt to resolve conflicts."},
+            {"value": "deny", "label": "Deny Updates", "description": "Do not modify dependency files; resolve conflicts manually."},
+            {"value": "review", "label": "Review Each", "description": "Review each dependency conflict individually before deciding."},
+        ],
+        "is_blocking": True,
+    })
+
+    # Decision 3: Route conflicts
+    decisions.append({
+        "decision_id": "route_integration",
+        "question": "Should routing conflicts be resolved by integrating into target routes?",
+        "context": (
+            f"If module '{module_name}' defines its own routes or entry points, "
+            f"decide whether to merge them into the target project's routing system "
+            f"or keep them separate."
+        ),
+        "options": [
+            {"value": "integrate", "label": "Integrate Routes", "description": "Merge source routes into the target project's routing system."},
+            {"value": "isolate", "label": "Isolate Routes", "description": "Keep source routes separate — may need a sub-path prefix."},
+            {"value": "defer", "label": "Defer Decision", "description": "Leave routing as-is and revisit after initial fusion."},
+        ],
+        "is_blocking": False,
+    })
+
+    # Decision 4: Source directory structure preservation
+    decisions.append({
+        "decision_id": "preserve_structure",
+        "question": "Should the original directory structure of the source module be preserved?",
+        "context": (
+            f"Module '{module_name}' at source path(s): {', '.join(source_paths) if source_paths else '(none)'}. "
+            f"Target path(s): {', '.join(target_paths) if target_paths else '(none)'} ."
+        ),
+        "options": [
+            {"value": "preserve", "label": "Preserve Structure", "description": "Keep the source module's original directory layout when copying to target."},
+            {"value": "flatten", "label": "Flatten Structure", "description": "Flatten the module files into the target's existing directory structure."},
+            {"value": "adapt", "label": "Adapt to Target", "description": "Reorganize to match the target project's conventions."},
+        ],
+        "is_blocking": False,
+    })
+
+    return decisions