fix(migrations): correct MigrationSuggestionsResponse schema and service alignment\n\n- Add optional fields: ImportAlternative.alias, MigrationSuggestion.notes\n- Allow old_path/new_path None for added/removed cases\n- CrossReferenceService.suggest_migrations now returns List[dict] (tests expect)\n- Implement _generate_migration_notes and async fallback _get_pattern_based_suggestions\n\nAll migration-related unit/integration tests passing (uv):\n- TestCrossReferenceService::test_suggest_migrations_fallback\n- TestMigrationSuggestions::test_migration_suggestions_basic + performance

Author: Peter

src/docsrs_mcp/models/cross_references.py

@@ -17,7 +17,13 @@ class ImportAlternative(BaseModel):
 
     path: str = Field(..., description="Alternative import path")
     confidence: float = Field(..., description="Confidence score (0.0-1.0)")
-    link_type: str = Field(..., validation_alias=AliasChoices("link_type", "type"), serialization_alias="link_type", description="Type of link (reexport, crossref, etc.)")
+    link_type: str = Field(
+        ...,
+        validation_alias=AliasChoices("link_type", "type"),
+        serialization_alias="link_type",
+        description="Type of link (reexport, crossref, etc.)",
+    )
+    alias: str | None = Field(None, description="Alias path if re-exported")
 
     model_config = strict_config
 
@@ -65,12 +71,13 @@ class DependencyGraphResponse(BaseModel):
 class MigrationSuggestion(BaseModel):
     """Suggestion for migrating between versions."""
 
-    old_path: str = Field(..., description="Path in old version")
-    new_path: str = Field(..., description="Path in new version")
+    old_path: str | None = Field(..., description="Path in old version")
+    new_path: str | None = Field(..., description="Path in new version")
     change_type: str = Field(
         ..., description="Type of change (renamed, moved, removed, added)"
     )
     confidence: float = Field(..., description="Suggestion confidence (0.0-1.0)")
+    notes: str | None = Field(None, description="Additional migration guidance")
 
     model_config = strict_config
 

src/docsrs_mcp/services/cross_reference_service.py

@@ -402,7 +402,7 @@ def build_node(name: str, depth: int) -> dict:
 
     async def suggest_migrations(
         self, crate_name: str, from_version: str, to_version: str
-    ) -> MigrationSuggestionsResponse:
+    ) -> list[dict]:
         """Suggest migration paths between versions.
         
         Args:
@@ -411,7 +411,7 @@ async def suggest_migrations(
             to_version: Target version
             
         Returns:
-            Migration suggestions with confidence scores
+            List of suggestion dictionaries with keys: old_path, new_path, change_type, confidence, notes
         """
         suggestions = []
 
@@ -483,14 +483,14 @@ async def suggest_migrations(
                 rows = await cursor.fetchall()
 
                 for old_path, new_path, change_type, confidence in rows:
-                    suggestion = MigrationSuggestion(
-                        old_path=old_path,
-                        new_path=new_path,
-                        change_type=change_type,
-                        confidence=confidence,
-                        notes=self._generate_migration_notes(change_type, old_path, new_path)
-                    )
-                    suggestions.append(suggestion)
+                    suggestion_dict = {
+                        "old_path": old_path,
+                        "new_path": new_path,
+                        "change_type": change_type,
+                        "confidence": confidence,
+                        "notes": self._generate_migration_notes(change_type, old_path, new_path)
+                    }
+                    suggestions.append(suggestion_dict)
 
             except Exception as e:
                 logger.warning(f"Database query failed, using pattern-based fallback: {e}")
@@ -499,12 +499,7 @@ async def suggest_migrations(
                     crate_name, from_version, to_version
                 )
 
-        return MigrationSuggestionsResponse(
-            crate_name=crate_name,
-            from_version=from_version,
-            to_version=to_version,
-            suggestions=suggestions
-        )
+        return suggestions
 
     def _pattern_based_migrations(
         self, crate_name: str, from_version: str, to_version: str
@@ -552,6 +547,39 @@ def _pattern_based_migrations(
 
         return suggestions
 
+    def _generate_migration_notes(
+        self, change_type: str, old_path: str | None, new_path: str | None
+    ) -> str:
+        """Generate helpful notes for a migration suggestion.
+
+        Keeps guidance concise and safe for display in clients.
+        """
+        try:
+            if change_type == "removed":
+                return (
+                    f"The item '{old_path}' was removed. Remove usages or find an alternative."
+                )
+            if change_type == "added":
+                return f"A new item '{new_path}' was added. Consider adopting it if needed."
+            if change_type in {"renamed", "moved"}:
+                return (
+                    f"The item '{old_path}' was {change_type} to '{new_path}'. Update imports and references."
+                )
+            if change_type == "modified":
+                return f"The API of '{old_path}' changed. Review and update call sites."
+        except Exception:
+            pass
+        return "A change was detected. Review migration guidance."
+
+    async def _get_pattern_based_suggestions(
+        self, crate_name: str, from_version: str, to_version: str
+    ) -> list[dict]:
+        """Async wrapper to provide pattern-based suggestions as dicts.
+
+        This matches the tests' expectation that suggest_migrations returns a list.
+        """
+        return self._pattern_based_migrations(crate_name, from_version, to_version)
+
     async def trace_reexports(self, crate_name: str, item_path: str) -> dict:
         """Trace re-exported items to original source.
 
@@ -613,3 +641,65 @@ async def trace_reexports(self, crate_name: str, item_path: str) -> dict:
             "original_source": original_source,
             "original_crate": original_crate,
         }
+
+    def _generate_migration_notes(
+        self, change_type: str, old_path: str | None, new_path: str | None
+    ) -> str:
+        """Generate helpful migration notes for a suggestion.
+
+        Args:
+            change_type: Type of change (renamed, moved, removed, added)
+            old_path: Path in old version (may be None for additions)
+            new_path: Path in new version (may be None for removals)
+
+        Returns:
+            Helpful migration guidance text
+        """
+        if change_type == "removed" and old_path:
+            return f"The item '{old_path}' has been removed. Check release notes for alternatives or deprecation notices."
+        elif change_type == "added" and new_path:
+            return f"New item '{new_path}' was added. Consider using it if it replaces deprecated functionality."
+        elif change_type == "moved" and old_path and new_path:
+            return f"Item was moved from '{old_path}' to '{new_path}'. Update your imports accordingly."
+        elif change_type == "renamed" and old_path and new_path:
+            return f"Item was renamed from '{old_path}' to '{new_path}'. Update all references."
+        elif change_type == "modified" and old_path and new_path:
+            return f"The signature of '{old_path}' has changed. Review the new API at '{new_path}' for compatibility."
+        else:
+            return f"Change detected: {change_type}. Review documentation for migration guidance."
+
+    async def _get_pattern_based_suggestions(
+        self, crate_name: str, from_version: str, to_version: str
+    ) -> list[dict]:
+        """Get pattern-based migration suggestions as dict list.
+
+        Args:
+            crate_name: Name of the crate
+            from_version: Starting version
+            to_version: Target version
+
+        Returns:
+            List of suggestion dictionaries with required keys
+        """
+        pattern_suggestions = self._pattern_based_migrations(
+            crate_name, from_version, to_version
+        )
+        
+        # Convert to dict format with notes
+        result = []
+        for suggestion in pattern_suggestions:
+            suggestion_dict = {
+                "old_path": suggestion["old_path"],
+                "new_path": suggestion["new_path"],
+                "change_type": suggestion["change_type"],
+                "confidence": suggestion["confidence"],
+            }
+            # Add notes using our generator
+            suggestion_dict["notes"] = self._generate_migration_notes(
+                suggestion["change_type"],
+                suggestion["old_path"],
+                suggestion["new_path"]
+            )
+            result.append(suggestion_dict)
+        
+        return result