AST-extract constraints from case_validator.py for parameters.md

Move the AST analyzer (Rule, CaseValidatorAnalyzer, classify_message,
etc.) from gen_case_constraints_docs.py into a shared module at
params/ast_analyzer.py. Add f-string message extraction (106 previously
invisible rules now captured, 333 total), trigger-param detection via
method guards and condition analysis, and an analyze_case_validator()
convenience function.

docs_gen.py now reads constraints from AST-extracted rules instead of
the manually maintained DEPENDENCIES dict, populating 61% of table rows
with validator constraints. Parameter names in messages are wrapped in
backticks with word-boundary matching.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: sbryngelson

CMakeLists.txt

@@ -685,10 +685,12 @@ if (MFC_DOCUMENTATION)
     )
 
     # Generate parameters.md from parameter registry
+    # docs_gen.py now AST-parses case_validator.py, so it must be a dependency
     file(GLOB_RECURSE params_SRCs CONFIGURE_DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/toolchain/mfc/params/*.py")
     add_custom_command(
         OUTPUT  "${CMAKE_CURRENT_SOURCE_DIR}/docs/documentation/parameters.md"
         DEPENDS "${params_SRCs}"
+                "${CMAKE_CURRENT_SOURCE_DIR}/toolchain/mfc/case_validator.py"
         COMMAND "bash" "${CMAKE_CURRENT_SOURCE_DIR}/docs/gen_parameters.sh"
                        "${CMAKE_CURRENT_SOURCE_DIR}"
         COMMENT "Generating parameters.md"

toolchain/mfc/gen_case_constraints_docs.py

@@ -10,13 +10,12 @@
 
 from __future__ import annotations
 
-import ast
 import json
 import sys
 import subprocess
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from pathlib import Path
-from typing import Dict, List, Set, Iterable, Any
+from typing import Dict, List, Iterable, Any
 from collections import defaultdict
 
 HERE = Path(__file__).resolve().parent
@@ -30,291 +29,10 @@
     sys.path.insert(0, _toolchain_dir)
 
 from mfc.params import CONSTRAINTS, DEPENDENCIES, get_value_label  # noqa: E402  pylint: disable=wrong-import-position
-
-
-# ---------------------------------------------------------------------------
-# Data structures
-# ---------------------------------------------------------------------------
-
-@dataclass
-class Rule:
-    method: str                      # e.g. "check_igr_simulation"
-    lineno: int                      # line number of the prohibit call
-    params: List[str]                # case parameter names used in condition
-    message: str                     # user-friendly error message
-    stages: Set[str] = field(default_factory=set)  # e.g. {"simulation", "pre_process"}
-
-
-# ---------------------------------------------------------------------------
-# AST analysis: methods, call graph, rules
-# ---------------------------------------------------------------------------
-
-class CaseValidatorAnalyzer(ast.NodeVisitor):
-    """
-    Analyzes the CaseValidator class:
-
-    - collects all methods
-    - builds a call graph between methods
-    - extracts all self.prohibit(...) rules
-    """
-
-    def __init__(self):
-        super().__init__()
-        self.in_case_validator = False
-        self.current_method: str | None = None
-
-        self.methods: Dict[str, ast.FunctionDef] = {}
-        self.call_graph: Dict[str, Set[str]] = defaultdict(set)
-        self.rules: List[Rule] = []
-
-        # Stack of {local_name -> param_name} maps, one per method
-        self.local_param_stack: List[Dict[str, str]] = []
-
-    # --- top-level entrypoint ---
-
-    def visit_ClassDef(self, node: ast.ClassDef):
-        if node.name == "CaseValidator":
-            self.in_case_validator = True
-            # collect methods
-            for item in node.body:
-                if isinstance(item, ast.FunctionDef):
-                    self.methods[item.name] = item
-            # now analyze all methods
-            for method in self.methods.values():
-                self._analyze_method(method)
-            self.in_case_validator = False
-        else:
-            self.generic_visit(node)
-
-    # --- per-method analysis ---
-
-    def _analyze_method(self, func: ast.FunctionDef):
-        """Analyze a single method: local param mapping, call graph, rules."""
-        self.current_method = func.name
-        local_param_map = self._build_local_param_map(func)
-        self.local_param_stack.append(local_param_map)
-        self.generic_visit(func)
-        self.local_param_stack.pop()
-        self.current_method = None
-
-    def _build_local_param_map(self, func: ast.FunctionDef) -> Dict[str, str]:  # pylint: disable=too-many-nested-blocks
-        """
-        Look for assignments like:
-            igr = self.get('igr', 'F') == 'T'
-            model_eqns = self.get('model_eqns')
-        and record local_name -> 'param_name'.
-        """
-        m: Dict[str, str] = {}
-        for stmt in func.body:  # pylint: disable=too-many-nested-blocks
-            if isinstance(stmt, ast.Assign):
-                # Handle both direct calls and comparisons
-                value = stmt.value
-                # Unwrap comparisons like "self.get('igr', 'F') == 'T'"
-                if isinstance(value, ast.Compare):
-                    value = value.left
-
-                if isinstance(value, ast.Call):
-                    call = value
-                    if (  # pylint: disable=too-many-boolean-expressions
-                        isinstance(call.func, ast.Attribute)
-                        and isinstance(call.func.value, ast.Name)
-                        and call.func.value.id == "self"
-                        and call.func.attr == "get"
-                        and call.args
-                        and isinstance(call.args[0], ast.Constant)
-                        and isinstance(call.args[0].value, str)
-                    ):
-                        param_name = call.args[0].value
-                        for target in stmt.targets:
-                            if isinstance(target, ast.Name):
-                                m[target.id] = param_name
-        return m
-
-    # --- visit calls to build call graph + rules ---
-
-    def visit_Call(self, node: ast.Call):
-        # record method call edges: self.some_method(...)
-        if (
-            isinstance(node.func, ast.Attribute)
-            and isinstance(node.func.value, ast.Name)
-            and node.func.value.id == "self"
-            and isinstance(node.func.attr, str)
-        ):
-            callee = node.func.attr
-            if self.current_method is not None:
-                # method call on self
-                self.call_graph[self.current_method].add(callee)
-
-        # detect self.prohibit(<condition>, "<message>")
-        if (
-            isinstance(node.func, ast.Attribute)
-            and isinstance(node.func.value, ast.Name)
-            and node.func.value.id == "self"
-            and node.func.attr == "prohibit"
-            and len(node.args) >= 2
-        ):
-            condition, msg_node = node.args[0], node.args[1]
-            if isinstance(msg_node, ast.Constant) and isinstance(msg_node.value, str):
-                params = sorted(self._extract_params(condition))
-                rule = Rule(
-                    method=self.current_method or "<unknown>",
-                    lineno=node.lineno,
-                    params=params,
-                    message=msg_node.value,
-                )
-                self.rules.append(rule)
-
-        self.generic_visit(node)
-
-    def _extract_params(self, condition: ast.AST) -> Set[str]:
-        """
-        Collect parameter names used in the condition via:
-          - local variables mapped from self.get(...)
-          - direct self.get('param_name', ...) calls
-        """
-        params: Set[str] = set()
-        local_map = self.local_param_stack[-1] if self.local_param_stack else {}
-
-        for node in ast.walk(condition):
-            # local names
-            if isinstance(node, ast.Name) and node.id in local_map:
-                params.add(local_map[node.id])
-
-            # direct self.get('param_name')
-            if isinstance(node, ast.Call):
-                if (  # pylint: disable=too-many-boolean-expressions
-                    isinstance(node.func, ast.Attribute)
-                    and isinstance(node.func.value, ast.Name)
-                    and node.func.value.id == "self"
-                    and node.func.attr == "get"
-                    and node.args
-                    and isinstance(node.args[0], ast.Constant)
-                    and isinstance(node.args[0].value, str)
-                ):
-                    params.add(node.args[0].value)
-
-        return params
-
-
-# ---------------------------------------------------------------------------
-# Stage inference from validate_* roots and call graph
-# ---------------------------------------------------------------------------
-
-STAGE_ROOTS: Dict[str, List[str]] = {
-    "common": ["validate_common"],
-    "simulation": ["validate_simulation"],
-    "pre_process": ["validate_pre_process"],
-    "post_process": ["validate_post_process"],
-}
-
-
-def compute_method_stages(call_graph: Dict[str, Set[str]]) -> Dict[str, Set[str]]:
-    """
-    For each stage (simulation/pre_process/post_process/common), starting from
-    validate_* roots, walk the call graph and record which methods belong to which stages.
-    """
-    method_stages: Dict[str, Set[str]] = defaultdict(set)
-
-    def dfs(start: str, stage: str):
-        stack = [start]
-        visited: Set[str] = set()
-        while stack:
-            m = stack.pop()
-            if m in visited:
-                continue
-            visited.add(m)
-            method_stages[m].add(stage)
-            for nxt in call_graph.get(m, ()):
-                if nxt not in visited:
-                    stack.append(nxt)
-
-    for stage, roots in STAGE_ROOTS.items():
-        for root in roots:
-            dfs(root, stage)
-
-    return method_stages
-
-
-# ---------------------------------------------------------------------------
-# Classification of messages for nicer grouping
-# ---------------------------------------------------------------------------
-
-def classify_message(msg: str) -> str:
-    """
-    Roughly classify rule messages for nicer grouping.
-
-    Returns one of: "requirement", "incompatibility", "range", "other".
-    """
-    text = msg.lower()
-
-    if (  # pylint: disable=too-many-boolean-expressions
-        "not compatible" in text
-        or "does not support" in text
-        or "cannot be used" in text
-        or "must not" in text
-        or "is not supported" in text
-        or "incompatible" in text
-        or "untested" in text
-    ):
-        return "incompatibility"
-
-    if (  # pylint: disable=too-many-boolean-expressions
-        "requires" in text
-        or "must be set if" in text
-        or "must be specified" in text
-        or "must be set with" in text
-        or "can only be enabled if" in text
-        or "must be set for" in text
-    ):
-        return "requirement"
-
-    if (  # pylint: disable=too-many-boolean-expressions
-        "must be between" in text
-        or "must be positive" in text
-        or "must be non-negative" in text
-        or "must be greater than" in text
-        or "must be less than" in text
-        or "must be at least" in text
-        or "must be <=" in text
-        or "must be >=" in text
-        or "must be odd" in text
-        or "divisible by" in text
-    ):
-        return "range"
-
-    return "other"
-
-
-# Optional: nicer display names / categories (you can extend this)
-FEATURE_META = {
-    "igr": {"title": "Iterative Generalized Riemann (IGR)", "category": "solver"},
-    "bubbles_euler": {"title": "Euler–Euler Bubble Model", "category": "bubbles"},
-    "bubbles_lagrange": {"title": "Euler–Lagrange Bubble Model", "category": "bubbles"},
-    "qbmm": {"title": "Quadrature-Based Moment Method (QBMM)", "category": "bubbles"},
-    "polydisperse": {"title": "Polydisperse Bubble Dynamics", "category": "bubbles"},
-    "mhd": {"title": "Magnetohydrodynamics (MHD)", "category": "physics"},
-    "alt_soundspeed": {"title": "Alternative Sound Speed", "category": "physics"},
-    "surface_tension": {"title": "Surface Tension Model", "category": "physics"},
-    "hypoelasticity": {"title": "Hypoelasticity", "category": "physics"},
-    "hyperelasticity": {"title": "Hyperelasticity", "category": "physics"},
-    "relax": {"title": "Phase Change (Relaxation)", "category": "physics"},
-    "viscous": {"title": "Viscosity", "category": "physics"},
-    "acoustic_source": {"title": "Acoustic Sources", "category": "physics"},
-    "ib": {"title": "Immersed Boundaries", "category": "geometry"},
-    "cyl_coord": {"title": "Cylindrical Coordinates", "category": "geometry"},
-    "weno_order": {"title": "WENO Order", "category": "numerics"},
-    "muscl_order": {"title": "MUSCL Order", "category": "numerics"},
-    "riemann_solver": {"title": "Riemann Solver", "category": "numerics"},
-    "model_eqns": {"title": "Model Equations", "category": "fundamentals"},
-    "num_fluids": {"title": "Number of Fluids", "category": "fundamentals"},
-}
-
-
-def feature_title(param: str) -> str:
-    meta = FEATURE_META.get(param)
-    if meta and "title" in meta:
-        return meta["title"]
-    return param
+from mfc.params.ast_analyzer import (  # noqa: E402  pylint: disable=wrong-import-position
+    Rule, classify_message, feature_title,
+    analyze_case_validator,
+)
 
 
 # ---------------------------------------------------------------------------
@@ -1023,20 +741,8 @@ def _render_cond_parts(trigger_str, cond_dict):
 # ---------------------------------------------------------------------------
 
 def main() -> None:
-    src = CASE_VALIDATOR_PATH.read_text(encoding="utf-8")
-    tree = ast.parse(src, filename=str(CASE_VALIDATOR_PATH))
-
-    analyzer = CaseValidatorAnalyzer()
-    analyzer.visit(tree)
-
-    # Infer stages per method from call graph
-    method_stages = compute_method_stages(analyzer.call_graph)
-
-    # Attach stages to rules
-    for r in analyzer.rules:
-        r.stages = method_stages.get(r.method, set())
-
-    md = render_markdown(analyzer.rules)
+    analysis = analyze_case_validator(CASE_VALIDATOR_PATH)
+    md = render_markdown(analysis["rules"])
     print(md)