foundry-mcp 0.3.3__py3-none-any.whl → 0.8.10__py3-none-any.whl

foundry_mcp/core/validation.py

@@ -8,6 +8,7 @@ Security Note:
 """
 
 from dataclasses import dataclass, field
+from difflib import get_close_matches
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Callable
 import json
@@ -109,7 +110,7 @@ class SpecStats:
 # Constants
 
 STATUS_FIELDS = {"pending", "in_progress", "completed", "blocked"}
-VALID_NODE_TYPES = {"spec", "phase", "group", "task", "subtask", "verify"}
+VALID_NODE_TYPES = {"spec", "phase", "group", "task", "subtask", "verify", "research"}
 VALID_STATUSES = {"pending", "in_progress", "completed", "blocked"}
 VALID_TASK_CATEGORIES = {
     "investigation",
@@ -118,12 +119,73 @@ VALID_TASK_CATEGORIES = {
     "decision",
     "research",
 }
-VALID_VERIFICATION_TYPES = {"test", "fidelity"}
+VALID_VERIFICATION_TYPES = {"run-tests", "fidelity", "manual"}
+
+# Legacy to canonical verification type mapping
+VERIFICATION_TYPE_MAPPING = {
+    "test": "run-tests",
+    "auto": "run-tests",
+}
+
+# Research node constants
+VALID_RESEARCH_TYPES = {"chat", "consensus", "thinkdeep", "ideate", "deep-research"}
+VALID_RESEARCH_RESULTS = {"completed", "inconclusive", "blocked", "cancelled"}
+RESEARCH_BLOCKING_MODES = {"none", "soft", "hard"}
+
+# Common field name typos/alternatives
+FIELD_NAME_SUGGESTIONS = {
+    "category": "task_category",
+    "type": "node type or verification_type",
+    "desc": "description",
+    "details": "description",
+}
+
+
+def _suggest_value(value: str, valid_values: set, n: int = 1) -> Optional[str]:
+    """
+    Suggest a close match for an invalid value.
+
+    Args:
+        value: The invalid value provided
+        valid_values: Set of valid values to match against
+        n: Number of suggestions to return (default 1)
+
+    Returns:
+        Suggestion string like "did you mean 'X'?" or None if no close match
+    """
+    if not value:
+        return None
+    matches = get_close_matches(value.lower(), [v.lower() for v in valid_values], n=n, cutoff=0.6)
+    if matches:
+        # Find the original-case version of the match
+        for v in valid_values:
+            if v.lower() == matches[0]:
+                return f"did you mean '{v}'?"
+        return f"did you mean '{matches[0]}'?"
+    return None
 
 
 # Validation functions
 
 
+def _requires_rich_task_fields(spec_data: Dict[str, Any]) -> bool:
+    """Check if spec requires rich task fields based on explicit complexity metadata."""
+    metadata = spec_data.get("metadata", {})
+    if not isinstance(metadata, dict):
+        return False
+
+    # Only check explicit complexity metadata (template no longer indicates complexity)
+    complexity = metadata.get("complexity")
+    if isinstance(complexity, str) and complexity.strip().lower() in {
+        "medium",
+        "complex",
+        "high",
+    }:
+        return True
+
+    return False
+
+
 def validate_spec_input(
     raw_input: str | bytes,
     *,
@@ -247,7 +309,7 @@ def validate_spec(spec_data: Dict[str, Any]) -> ValidationResult:
         _validate_nodes(hierarchy, result)
         _validate_task_counts(hierarchy, result)
         _validate_dependencies(hierarchy, result)
-        _validate_metadata(hierarchy, result)
+        _validate_metadata(spec_data, hierarchy, result)
 
     # Count diagnostics by severity
     for diag in result.diagnostics:
@@ -413,6 +475,22 @@ def _validate_structure(spec_data: Dict[str, Any], result: ValidationResult) ->
                 )
             )
 
+    if _requires_rich_task_fields(spec_data):
+        metadata = spec_data.get("metadata", {})
+        mission = metadata.get("mission") if isinstance(metadata, dict) else None
+        if not isinstance(mission, str) or not mission.strip():
+            result.diagnostics.append(
+                Diagnostic(
+                    code="MISSING_MISSION",
+                    message="Spec metadata.mission is required when complexity is medium/complex/high",
+                    severity="error",
+                    category="metadata",
+                    location="metadata.mission",
+                    suggested_fix="Set metadata.mission to a concise goal statement",
+                    auto_fixable=False,
+                )
+            )
+
     # Check hierarchy is dict
     hierarchy = spec_data.get("hierarchy")
     if hierarchy is not None and not isinstance(hierarchy, dict):
@@ -458,6 +536,8 @@ def _validate_hierarchy(hierarchy: Dict[str, Any], result: ValidationResult) ->
                 severity="error",
                 category="hierarchy",
                 location="spec-root",
+                suggested_fix="Set spec-root parent to null",
+                auto_fixable=True,
             )
         )
 
@@ -619,14 +699,18 @@ def _validate_nodes(hierarchy: Dict[str, Any], result: ValidationResult) -> None
         # Validate type
         node_type = node.get("type")
         if node_type and node_type not in VALID_NODE_TYPES:
+            hint = _suggest_value(node_type, VALID_NODE_TYPES)
+            msg = f"Node '{node_id}' has invalid type '{node_type}'"
+            if hint:
+                msg += f"; {hint}"
             result.diagnostics.append(
                 Diagnostic(
                     code="INVALID_NODE_TYPE",
-                    message=f"Node '{node_id}' has invalid type '{node_type}'",
+                    message=msg,
                     severity="error",
                     category="node",
                     location=node_id,
-                    suggested_fix="Normalize node type to valid value",
+                    suggested_fix=f"Valid types: {', '.join(sorted(VALID_NODE_TYPES))}",
                     auto_fixable=True,
                 )
             )
@@ -634,14 +718,18 @@ def _validate_nodes(hierarchy: Dict[str, Any], result: ValidationResult) -> None
         # Validate status
         status = node.get("status")
         if status and status not in VALID_STATUSES:
+            hint = _suggest_value(status, VALID_STATUSES)
+            msg = f"Node '{node_id}' has invalid status '{status}'"
+            if hint:
+                msg += f"; {hint}"
             result.diagnostics.append(
                 Diagnostic(
                     code="INVALID_STATUS",
-                    message=f"Node '{node_id}' has invalid status '{status}'",
+                    message=msg,
                     severity="error",
                     category="node",
                     location=node_id,
-                    suggested_fix="Normalize status to pending/in_progress/completed/blocked",
+                    suggested_fix=f"Valid statuses: {', '.join(sorted(VALID_STATUSES))}",
                     auto_fixable=True,
                 )
             )
@@ -830,8 +918,27 @@ def _validate_dependencies(hierarchy: Dict[str, Any], result: ValidationResult)
                         )
 
 
-def _validate_metadata(hierarchy: Dict[str, Any], result: ValidationResult) -> None:
+def _validate_metadata(
+    spec_data: Dict[str, Any],
+    hierarchy: Dict[str, Any],
+    result: ValidationResult,
+) -> None:
     """Validate type-specific metadata requirements."""
+    requires_rich_tasks = _requires_rich_task_fields(spec_data)
+
+    def _nonempty_string(value: Any) -> bool:
+        return isinstance(value, str) and bool(value.strip())
+
+    def _has_description(metadata: Dict[str, Any]) -> bool:
+        if _nonempty_string(metadata.get("description")):
+            return True
+        details = metadata.get("details")
+        if _nonempty_string(details):
+            return True
+        if isinstance(details, list):
+            return any(_nonempty_string(item) for item in details)
+        return False
+
     for node_id, node in _iter_valid_nodes(hierarchy, result, report_invalid=False):
         node_type = node.get("type")
         metadata = node.get("metadata", {})
@@ -860,53 +967,175 @@ def _validate_metadata(hierarchy: Dict[str, Any], result: ValidationResult) -> N
                         severity="error",
                         category="metadata",
                         location=node_id,
-                        suggested_fix="Set verification_type to 'test' or 'fidelity'",
+                        suggested_fix="Set verification_type to 'run-tests', 'fidelity', or 'manual'",
                         auto_fixable=True,
                     )
                 )
             elif verification_type not in VALID_VERIFICATION_TYPES:
+                hint = _suggest_value(verification_type, VALID_VERIFICATION_TYPES)
+                msg = f"Verify node '{node_id}' has invalid verification_type '{verification_type}'"
+                if hint:
+                    msg += f"; {hint}"
                 result.diagnostics.append(
                     Diagnostic(
                         code="INVALID_VERIFICATION_TYPE",
-                        message=f"Verify node '{node_id}' verification_type must be 'test' or 'fidelity'",
+                        message=msg,
                         severity="error",
                         category="metadata",
                         location=node_id,
+                        suggested_fix=f"Valid types: {', '.join(sorted(VALID_VERIFICATION_TYPES))}",
+                        auto_fixable=True,
                     )
                 )
 
         # Task nodes
         if node_type == "task":
-            task_category = metadata.get("task_category", "implementation")
+            raw_task_category = metadata.get("task_category")
+            task_category = None
+            if isinstance(raw_task_category, str) and raw_task_category.strip():
+                task_category = raw_task_category.strip().lower()
+
+            # Check for common field name typo: 'category' instead of 'task_category'
+            if task_category is None and "category" in metadata and "task_category" not in metadata:
+                result.diagnostics.append(
+                    Diagnostic(
+                        code="UNKNOWN_FIELD",
+                        message=f"Task node '{node_id}' has unknown field 'category'; did you mean 'task_category'?",
+                        severity="warning",
+                        category="metadata",
+                        location=node_id,
+                        suggested_fix="Rename 'category' to 'task_category'",
+                        auto_fixable=False,
+                    )
+                )
 
-            if (
-                "task_category" in metadata
-                and task_category not in VALID_TASK_CATEGORIES
-            ):
+            if task_category is not None and task_category not in VALID_TASK_CATEGORIES:
+                hint = _suggest_value(task_category, VALID_TASK_CATEGORIES)
+                msg = f"Task node '{node_id}' has invalid task_category '{task_category}'"
+                if hint:
+                    msg += f"; {hint}"
                 result.diagnostics.append(
                     Diagnostic(
                         code="INVALID_TASK_CATEGORY",
-                        message=f"Task node '{node_id}' has invalid task_category '{task_category}'",
+                        message=msg,
                         severity="error",
                         category="metadata",
                         location=node_id,
-                        suggested_fix=f"Set task_category to one of: {', '.join(VALID_TASK_CATEGORIES)}",
-                        auto_fixable=True,
+                        suggested_fix=f"Valid categories: {', '.join(sorted(VALID_TASK_CATEGORIES))}",
+                        auto_fixable=False,  # Disabled: manual fix required
+                    )
+                )
+
+            if requires_rich_tasks and task_category is None:
+                result.diagnostics.append(
+                    Diagnostic(
+                        code="MISSING_TASK_CATEGORY",
+                        message=f"Task node '{node_id}' missing metadata.task_category",
+                        severity="error",
+                        category="metadata",
+                        location=node_id,
+                        suggested_fix="Set metadata.task_category to a valid category",
+                        auto_fixable=False,
                     )
                 )
 
-            # file_path required for implementation and refactoring
-            if task_category in ["implementation", "refactoring"]:
-                if "file_path" not in metadata:
+            if requires_rich_tasks and not _has_description(metadata):
+                result.diagnostics.append(
+                    Diagnostic(
+                        code="MISSING_TASK_DESCRIPTION",
+                        message=f"Task node '{node_id}' missing metadata.description",
+                        severity="error",
+                        category="metadata",
+                        location=node_id,
+                        suggested_fix="Provide metadata.description (or details) for the task",
+                        auto_fixable=False,
+                    )
+                )
+
+            if requires_rich_tasks:
+                acceptance_criteria = metadata.get("acceptance_criteria")
+                if acceptance_criteria is None:
+                    result.diagnostics.append(
+                        Diagnostic(
+                            code="MISSING_ACCEPTANCE_CRITERIA",
+                            message=f"Task node '{node_id}' missing metadata.acceptance_criteria",
+                            severity="error",
+                            category="metadata",
+                            location=node_id,
+                            suggested_fix="Provide a non-empty acceptance_criteria list",
+                            auto_fixable=False,
+                        )
+                    )
+                elif not isinstance(acceptance_criteria, list):
+                    result.diagnostics.append(
+                        Diagnostic(
+                            code="INVALID_ACCEPTANCE_CRITERIA",
+                            message=(
+                                f"Task node '{node_id}' metadata.acceptance_criteria must be a list of strings"
+                            ),
+                            severity="error",
+                            category="metadata",
+                            location=node_id,
+                            suggested_fix="Provide acceptance_criteria as an array of strings",
+                            auto_fixable=False,
+                        )
+                    )
+                elif not acceptance_criteria:
+                    result.diagnostics.append(
+                        Diagnostic(
+                            code="MISSING_ACCEPTANCE_CRITERIA",
+                            message=f"Task node '{node_id}' must include at least one acceptance criterion",
+                            severity="error",
+                            category="metadata",
+                            location=node_id,
+                            suggested_fix="Add at least one acceptance criterion",
+                            auto_fixable=False,
+                        )
+                    )
+                else:
+                    invalid_items = [
+                        idx
+                        for idx, item in enumerate(acceptance_criteria)
+                        if not _nonempty_string(item)
+                    ]
+                    if invalid_items:
+                        result.diagnostics.append(
+                            Diagnostic(
+                                code="INVALID_ACCEPTANCE_CRITERIA",
+                                message=(
+                                    f"Task node '{node_id}' has invalid acceptance_criteria entries"
+                                ),
+                                severity="error",
+                                category="metadata",
+                                location=node_id,
+                                suggested_fix="Ensure acceptance_criteria contains non-empty strings",
+                                auto_fixable=False,
+                            )
+                        )
+
+            category_for_file_path = task_category
+            if category_for_file_path is None:
+                legacy_category = metadata.get("category")
+                if isinstance(legacy_category, str) and legacy_category.strip():
+                    category_for_file_path = legacy_category.strip().lower()
+
+            # file_path required for implementation and refactoring.
+            # Do not auto-generate placeholder paths; the authoring agent/user must
+            # provide a real path in the target codebase.
+            if category_for_file_path in ["implementation", "refactoring"]:
+                file_path = metadata.get("file_path")
+                if not _nonempty_string(file_path):
                     result.diagnostics.append(
                         Diagnostic(
                             code="MISSING_FILE_PATH",
-                            message=f"Task node '{node_id}' with category '{task_category}' missing metadata.file_path",
+                            message=f"Task node '{node_id}' with category '{category_for_file_path}' missing metadata.file_path",
                             severity="error",
                             category="metadata",
                             location=node_id,
-                            suggested_fix="Add metadata.file_path for implementation tasks",
-                            auto_fixable=True,
+                            suggested_fix=(
+                                "Set metadata.file_path to the real repo-relative path of the primary file impacted"
+                            ),
+                            auto_fixable=False,
                         )
                     )
 
@@ -958,6 +1187,9 @@ def _build_fix_action(
     if code == "ORPHANED_NODES":
         return _build_orphan_fix(diag, hierarchy)
 
+    if code == "INVALID_ROOT_PARENT":
+        return _build_root_parent_fix(diag, hierarchy)
+
     if code == "MISSING_NODE_FIELD":
         return _build_missing_fields_fix(diag, hierarchy)
 
@@ -987,11 +1219,12 @@ def _build_fix_action(
     if code == "MISSING_VERIFICATION_TYPE":
         return _build_verification_type_fix(diag, hierarchy)
 
-    if code == "MISSING_FILE_PATH":
-        return _build_file_path_fix(diag, hierarchy)
+    if code == "INVALID_VERIFICATION_TYPE":
+        return _build_invalid_verification_type_fix(diag, hierarchy)
 
-    if code == "INVALID_TASK_CATEGORY":
-        return _build_task_category_fix(diag, hierarchy)
+    # INVALID_TASK_CATEGORY auto-fix disabled - manual correction required
+    # if code == "INVALID_TASK_CATEGORY":
+    #     return _build_task_category_fix(diag, hierarchy)
 
     return None
 
@@ -1087,6 +1320,28 @@ def _build_orphan_fix(
     )
 
 
+def _build_root_parent_fix(
+    diag: Diagnostic, hierarchy: Dict[str, Any]
+) -> Optional[FixAction]:
+    """Build fix for spec-root having non-null parent."""
+
+    def apply(data: Dict[str, Any]) -> None:
+        hier = data.get("hierarchy", {})
+        spec_root = hier.get("spec-root")
+        if spec_root:
+            spec_root["parent"] = None
+
+    return FixAction(
+        id="hierarchy.fix_root_parent",
+        description="Set spec-root parent to null",
+        category="hierarchy",
+        severity=diag.severity,
+        auto_apply=True,
+        preview="Set spec-root parent to null",
+        apply=apply,
+    )
+
+
 def _build_missing_fields_fix(
     diag: Diagnostic, hierarchy: Dict[str, Any]
 ) -> Optional[FixAction]:
@@ -1108,7 +1363,18 @@ def _build_missing_fields_fix(
         if "status" not in node:
             node["status"] = "pending"
         if "parent" not in node:
-            node["parent"] = "spec-root"
+            # Find actual parent by checking which node lists this node as a child
+            # This prevents regression where we set parent="spec-root" but the node
+            # is actually in another node's children list (causing PARENT_CHILD_MISMATCH)
+            actual_parent = "spec-root"  # fallback if not found in any children list
+            for other_id, other_node in hier.items():
+                if not isinstance(other_node, dict):
+                    continue
+                children = other_node.get("children", [])
+                if isinstance(children, list) and node_id in children:
+                    actual_parent = other_id
+                    break
+            node["parent"] = actual_parent
         if "children" not in node:
             node["children"] = []
         if "total_tasks" not in node:
@@ -1262,9 +1528,9 @@ def _build_bidirectional_fix(
         blocked_deps = blocked["dependencies"]
 
         # Ensure all fields exist
-        for field in ["blocks", "blocked_by", "depends"]:
-            blocker_deps.setdefault(field, [])
-            blocked_deps.setdefault(field, [])
+        for dep_key in ["blocks", "blocked_by", "depends"]:
+            blocker_deps.setdefault(dep_key, [])
+            blocked_deps.setdefault(dep_key, [])
 
         # Sync relationship
         if blocked_id not in blocker_deps["blocks"]:
@@ -1325,23 +1591,23 @@ def _build_verification_type_fix(
             return
         metadata = node.setdefault("metadata", {})
         if "verification_type" not in metadata:
-            metadata["verification_type"] = "test"
+            metadata["verification_type"] = "run-tests"
 
     return FixAction(
         id=f"metadata.fix_verification_type:{node_id}",
-        description=f"Set verification_type to 'test' for {node_id}",
+        description=f"Set verification_type to 'run-tests' for {node_id}",
         category="metadata",
         severity=diag.severity,
         auto_apply=True,
-        preview=f"Set verification_type to 'test' for {node_id}",
+        preview=f"Set verification_type to 'run-tests' for {node_id}",
         apply=apply,
     )
 
 
-def _build_file_path_fix(
+def _build_invalid_verification_type_fix(
     diag: Diagnostic, hierarchy: Dict[str, Any]
 ) -> Optional[FixAction]:
-    """Build fix for missing file path."""
+    """Build fix for invalid verification type by mapping to canonical value."""
     node_id = diag.location
     if not node_id:
         return None
@@ -1351,21 +1617,31 @@ def _build_file_path_fix(
         node = hier.get(node_id)
         if not node:
             return
-        metadata = node.setdefault("metadata", {})
-        if "file_path" not in metadata:
-            metadata["file_path"] = f"{node_id}.py"  # Default placeholder
+        metadata = node.get("metadata", {})
+        current_type = metadata.get("verification_type", "")
+
+        # Map legacy values to canonical
+        mapped_type = VERIFICATION_TYPE_MAPPING.get(current_type)
+        if mapped_type:
+            metadata["verification_type"] = mapped_type
+        elif current_type not in VALID_VERIFICATION_TYPES:
+            metadata["verification_type"] = "manual"  # safe fallback for unknown values
 
     return FixAction(
-        id=f"metadata.add_file_path:{node_id}",
-        description=f"Add placeholder file_path for {node_id}",
+        id=f"metadata.fix_invalid_verification_type:{node_id}",
+        description=f"Map verification_type to canonical value for {node_id}",
         category="metadata",
         severity=diag.severity,
         auto_apply=True,
-        preview=f"Add placeholder file_path for {node_id}",
+        preview=f"Map legacy verification_type to canonical value for {node_id}",
         apply=apply,
     )
 
 
+# NOTE: We intentionally do not auto-fix missing `metadata.file_path`.
+# It must be a real repo-relative path in the target workspace.
+
+
 def _build_task_category_fix(
     diag: Diagnostic, hierarchy: Dict[str, Any]
 ) -> Optional[FixAction]:

foundry_mcp/dashboard/components/charts.py

@@ -36,63 +36,6 @@ def _check_deps():
     return True
 
 
-def line_chart(
-    df: "pd.DataFrame",
-    x: str,
-    y: str,
-    title: Optional[str] = None,
-    color: Optional[str] = None,
-    height: int = 400,
-) -> None:
-    """Render an interactive line chart.
-
-    Args:
-        df: DataFrame with data
-        x: Column name for x-axis
-        y: Column name for y-axis
-        title: Optional chart title
-        color: Optional column for color grouping
-        height: Chart height in pixels
-    """
-    if not _check_deps():
-        return
-
-    if df is None or df.empty:
-        st.info("No data to display")
-        return
-
-    fig = px.line(
-        df,
-        x=x,
-        y=y,
-        title=title,
-        color=color,
-    )
-
-    # Configure layout for dark theme
-    fig.update_layout(
-        template="plotly_dark",
-        height=height,
-        margin=dict(l=20, r=20, t=40, b=20),
-        xaxis=dict(
-            rangeselector=dict(
-                buttons=list(
-                    [
-                        dict(count=1, label="1h", step="hour", stepmode="backward"),
-                        dict(count=6, label="6h", step="hour", stepmode="backward"),
-                        dict(count=24, label="24h", step="hour", stepmode="backward"),
-                        dict(step="all", label="All"),
-                    ]
-                )
-            ),
-            rangeslider=dict(visible=True),
-            type="date",
-        ),
-    )
-
-    st.plotly_chart(fig, use_container_width=True)
-
-
 def bar_chart(
     df: "pd.DataFrame",
     x: str,

foundry_mcp/dashboard/launcher.py

@@ -126,6 +126,17 @@ def launch_dashboard(
         "FOUNDRY_MCP_DASHBOARD_MODE": "1",
     }
 
+    # Pass config file path to dashboard subprocess so it can find error/metrics storage
+    # If FOUNDRY_MCP_CONFIG_FILE is already set, it will be inherited from os.environ
+    # Otherwise, find and pass the config file path explicitly
+    if "FOUNDRY_MCP_CONFIG_FILE" not in env:
+        for config_name in ["foundry-mcp.toml", ".foundry-mcp.toml"]:
+            config_path = Path(config_name).resolve()
+            if config_path.exists():
+                env["FOUNDRY_MCP_CONFIG_FILE"] = str(config_path)
+                logger.debug("Passing config file to dashboard: %s", config_path)
+                break
+
     try:
         # Start subprocess
         _dashboard_process = subprocess.Popen(