feat: hotspot → top symbols drill-down, writable decision linkage (#191)

Hotspot table now expands each row into the importance-ranked top symbols
in that file (server gains a `file_path` filter on /api/symbols); clicking
a symbol opens the existing SymbolDrawer.

Decision detail page replaces the read-only affected-files block with a
ModuleLinkEditor — module-path autocomplete pulls from /modules/health.
PATCH /decisions/{id} now accepts optional `affected_modules` /
`affected_files` alongside `status` so the editor can persist without
forcing a status change.

Author: RaghavChamadiya

packages/core/src/repowise/core/persistence/crud.py

@@ -1054,6 +1054,30 @@ async def list_decisions(
     return list(result.scalars().all())
 
 
+async def update_decision_metadata(
+    session: AsyncSession,
+    decision_id: str,
+    *,
+    affected_modules: list[str] | None = None,
+    affected_files: list[str] | None = None,
+) -> DecisionRecord | None:
+    """Patch the module/file linkage on a decision record.
+
+    Each argument left as ``None`` is preserved. Pass an empty list to clear.
+    Returns the updated record, or ``None`` if the id was not found.
+    """
+    rec = await session.get(DecisionRecord, decision_id)
+    if rec is None:
+        return None
+    if affected_modules is not None:
+        rec.affected_modules_json = json.dumps(affected_modules)
+    if affected_files is not None:
+        rec.affected_files_json = json.dumps(affected_files)
+    rec.updated_at = _now_utc()
+    await session.flush()
+    return rec
+
+
 async def update_decision_status(
     session: AsyncSession,
     decision_id: str,

packages/server/src/repowise/server/routers/decisions.py

@@ -124,18 +124,43 @@ async def patch_decision(
     body: DecisionStatusUpdate,
     session: AsyncSession = Depends(get_db_session),  # noqa: B008
 ) -> DecisionRecordResponse:
-    """Update the status of a decision record (confirm, deprecate, supersede)."""
-    try:
-        rec = await crud.update_decision_status(
+    """Update a decision record.
+
+    Accepts status transitions (confirm / deprecate / supersede) and / or
+    governance edits (``affected_modules``, ``affected_files``). Any field
+    left as ``None`` in the body is preserved.
+    """
+    rec = await crud.get_decision(session, decision_id)
+    if rec is None or rec.repository_id != repo_id:
+        raise HTTPException(status_code=404, detail="Decision not found")
+
+    if body.status is not None:
+        try:
+            rec = await crud.update_decision_status(
+                session,
+                decision_id,
+                body.status,
+                superseded_by=body.superseded_by,
+            )
+        except ValueError as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+        if rec is None:
+            raise HTTPException(status_code=404, detail="Decision not found")
+    elif body.superseded_by is not None:
+        raise HTTPException(
+            status_code=400,
+            detail="superseded_by requires status='superseded'",
+        )
+
+    if body.affected_modules is not None or body.affected_files is not None:
+        rec = await crud.update_decision_metadata(
             session,
             decision_id,
-            body.status,
-            superseded_by=body.superseded_by,
+            affected_modules=body.affected_modules,
+            affected_files=body.affected_files,
         )
-    except ValueError as exc:
-        raise HTTPException(status_code=400, detail=str(exc)) from exc
-    if rec is None:
-        raise HTTPException(status_code=404, detail="Decision not found")
-    if rec.repository_id != repo_id:
-        raise HTTPException(status_code=404, detail="Decision not found")
+        if rec is None:
+            raise HTTPException(status_code=404, detail="Decision not found")
+
+    assert rec is not None
     return DecisionRecordResponse.from_orm(rec)

packages/server/src/repowise/server/routers/symbols.py

@@ -96,6 +96,9 @@ async def search_symbols(
     kind: str | None = Query(None, description="Filter by symbol kind"),
     language: str | None = Query(None, description="Filter by language"),
     visibility: str | None = Query(None, description="Filter by visibility"),
+    file_path: str | None = Query(
+        None, description="Filter by exact source file path (for hotspot drill-down)"
+    ),
     in_hot_files: bool = Query(False, description="Only symbols whose file is a hotspot"),
     in_entry_points: bool = Query(False, description="Only symbols in entry-point files"),
     sort: SortKey = Query("importance", description="Sort key"),
@@ -120,6 +123,8 @@ async def search_symbols(
         base = base.where(WikiSymbol.language == language)
     if visibility:
         base = base.where(WikiSymbol.visibility == visibility)
+    if file_path:
+        base = base.where(WikiSymbol.file_path == file_path)
 
     # Optional file-level filters require resolving file paths up front.
     if in_hot_files or in_entry_points:

packages/server/src/repowise/server/schemas.py

@@ -941,8 +941,17 @@ class DecisionCreate(BaseModel):
 
 
 class DecisionStatusUpdate(BaseModel):
-    status: str
+    """PATCH body for /decisions/{id}.
+
+    All fields are optional — clients can update status alone (the historical
+    contract), the linked modules / files alone (governance editor), or both
+    in a single request. Fields left at ``None`` are preserved.
+    """
+
+    status: str | None = None
     superseded_by: str | None = None
+    affected_modules: list[str] | None = None
+    affected_files: list[str] | None = None
 
 
 # ---------------------------------------------------------------------------

packages/types/src/decisions.ts

@@ -56,9 +56,15 @@ export interface DecisionCreateInput {
   tags?: string[];
 }
 
+/**
+ * PATCH body for /api/repos/{id}/decisions/{decision_id}. All fields are
+ * optional — clients can update just the status, just the linkage, or both.
+ */
 export interface DecisionStatusUpdate {
-  status: DecisionStatus;
+  status?: DecisionStatus;
   superseded_by?: string;
+  affected_modules?: string[];
+  affected_files?: string[];
 }
 
 export interface DecisionHealth {

packages/ui/src/decisions/index.ts

@@ -1,2 +1,3 @@
 export * from "./decision-health-widget.js";
 export * from "./decisions-table.js";
+export * from "./module-link-editor.js";