feat: add dvsim-admin check command for flow configs

Add 'dvsim-admin check' subcommand to validate flow configuration files.
The check subsystem detects the flow type and validates the config using
the appropriate parser. Currently supports lint flows with extensibility
for other flow types.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Signed-off-by: James McCorrie <james.mccorrie@lowrisc.org>

Author: machshev

src/dvsim/check/__init__.py

@@ -0,0 +1,5 @@
+# Copyright lowRISC contributors (OpenTitan project).
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Flow configuration checking."""

src/dvsim/check/flow.py

@@ -0,0 +1,81 @@
+# Copyright lowRISC contributors (OpenTitan project).
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Check flow configuration files for validity."""
+
+from pathlib import Path
+
+import hjson
+
+from dvsim.linting.parser import parse_lint_flow_config
+
+
+class FlowCheckError(Exception):
+    """Error checking flow configuration."""
+
+
+def detect_flow_type(hjson_path: Path) -> str | None:
+    """Detect the flow type from an hjson file.
+
+    Args:
+        hjson_path: Path to the hjson configuration file
+
+    Returns:
+        Flow type string (e.g., "lint", "sim") or None if not detected
+
+    Raises:
+        FlowCheckError: If the file cannot be read or parsed
+
+    """
+    try:
+        with hjson_path.open() as f:
+            data = hjson.load(f, use_decimal=True)
+    except hjson.HjsonDecodeError as e:
+        msg = f"Failed to parse hjson: {e}"
+        raise FlowCheckError(msg) from e
+    except OSError as e:
+        msg = f"Failed to read file: {e}"
+        raise FlowCheckError(msg) from e
+
+    return data.get("flow")
+
+
+def check_flow_config(hjson_path: Path) -> tuple[bool, str, str | None]:
+    """Check a flow configuration file for validity.
+
+    Args:
+        hjson_path: Path to the hjson configuration file
+
+    Returns:
+        Tuple of (success, message, flow_type):
+        - success: True if config is valid, False otherwise
+        - message: Human-readable message describing the result
+        - flow_type: The detected flow type or None
+
+    """
+    hjson_path = Path(hjson_path)
+
+    if not hjson_path.exists():
+        return False, f"File not found: {hjson_path}", None
+
+    # Detect flow type
+    try:
+        flow_type = detect_flow_type(hjson_path)
+    except FlowCheckError as e:
+        return False, str(e), None
+
+    if flow_type is None:
+        return False, "No 'flow' field found in configuration", None
+
+    # Check based on flow type
+    if flow_type == "lint":
+        try:
+            config = parse_lint_flow_config(hjson_path)
+        except (FileNotFoundError, RuntimeError) as e:
+            return False, f"Invalid lint flow config: {e}", flow_type
+        else:
+            return True, f"Valid lint flow config: {config.name}", flow_type
+
+    # Other flow types not yet supported
+    return False, f"Flow type '{flow_type}' checking not yet implemented", flow_type

src/dvsim/cli/admin.py

@@ -60,6 +60,28 @@ def dashboard_gen(json_path: Path, output_dir: Path, base_url: str | None) -> No
     )
 
 
+@cli.command()
+@click.argument(
+    "hjson_file",
+    type=click.Path(exists=True, file_okay=True, dir_okay=False, path_type=Path),
+)
+def check(hjson_file: Path) -> None:
+    """Check a flow configuration file for validity."""
+    from dvsim.check.flow import check_flow_config  # noqa: PLC0415
+
+    success, message, flow_type = check_flow_config(hjson_file)
+
+    if flow_type:
+        click.echo(f"Flow type: {flow_type}")
+
+    if success:
+        click.secho(f"✓ {message}", fg="green")
+        sys.exit(0)
+    else:
+        click.secho(f"✗ {message}", fg="red")
+        sys.exit(1)
+
+
 @cli.group()
 def report() -> None:
     """Reporting helper commands."""

src/dvsim/linting/config.py

@@ -4,7 +4,6 @@
 
 """Pydantic models for lint flow configuration."""
 
-
 from pydantic import BaseModel, ConfigDict, Field
 
 
@@ -75,5 +74,5 @@ class LintFlowConfig(BaseModel):
 
     model_config = ConfigDict(
         frozen=True,  # Make the model immutable
-        extra="allow",  # Allow extra fields for forwards compatibility
+        extra="forbid",  # Forbid extra fields to catch configuration errors
     )

tests/check/__init__.py

@@ -0,0 +1,5 @@
+# Copyright lowRISC contributors (OpenTitan project).
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Check tests."""

tests/check/test_flow.py

@@ -0,0 +1,113 @@
+# Copyright lowRISC contributors (OpenTitan project).
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Test flow configuration checking."""
+
+from pathlib import Path
+
+import hjson
+from hamcrest import assert_that, equal_to
+
+from dvsim.check.flow import check_flow_config, detect_flow_type
+
+
+def test_check_valid_lint_config() -> None:
+    """Test checking a valid lint flow configuration."""
+    fixtures_dir = Path(__file__).parent.parent / "flow" / "fixtures"
+    config_file = fixtures_dir / "example_lint.hjson"
+
+    success, message, flow_type = check_flow_config(config_file)
+
+    assert_that(success, equal_to(True))
+    assert_that(flow_type, equal_to("lint"))
+    assert_that("aes_dv_lint" in message, equal_to(True))
+
+
+def test_check_invalid_lint_config(tmp_path: Path) -> None:
+    """Test checking an invalid lint flow configuration."""
+    config_file = tmp_path / "invalid_lint.hjson"
+    config_data = {
+        "flow": "lint",
+        # Missing required 'name' field
+    }
+    config_file.write_text(hjson.dumps(config_data))
+
+    success, message, flow_type = check_flow_config(config_file)
+
+    assert_that(success, equal_to(False))
+    assert_that(flow_type, equal_to("lint"))
+    assert_that("Invalid" in message, equal_to(True))
+
+
+def test_check_missing_flow_field(tmp_path: Path) -> None:
+    """Test checking a config without a flow field."""
+    config_file = tmp_path / "no_flow.hjson"
+    config_data = {"name": "test"}
+    config_file.write_text(hjson.dumps(config_data))
+
+    success, message, flow_type = check_flow_config(config_file)
+
+    assert_that(success, equal_to(False))
+    assert_that(flow_type, equal_to(None))
+    assert_that("No 'flow' field" in message, equal_to(True))
+
+
+def test_check_nonexistent_file(tmp_path: Path) -> None:
+    """Test checking a file that doesn't exist."""
+    config_file = tmp_path / "nonexistent.hjson"
+
+    success, message, flow_type = check_flow_config(config_file)
+
+    assert_that(success, equal_to(False))
+    assert_that(flow_type, equal_to(None))
+    assert_that("not found" in message.lower(), equal_to(True))
+
+
+def test_check_invalid_hjson(tmp_path: Path) -> None:
+    """Test checking a file with invalid hjson syntax."""
+    config_file = tmp_path / "invalid.hjson"
+    config_file.write_text("{invalid hjson content")
+
+    success, message, flow_type = check_flow_config(config_file)
+
+    assert_that(success, equal_to(False))
+    assert_that(flow_type, equal_to(None))
+    assert_that("parse" in message.lower(), equal_to(True))
+
+
+def test_check_unsupported_flow_type(tmp_path: Path) -> None:
+    """Test checking a config with an unsupported flow type."""
+    config_file = tmp_path / "sim.hjson"
+    config_data = {
+        "name": "test_sim",
+        "flow": "sim",
+    }
+    config_file.write_text(hjson.dumps(config_data))
+
+    success, message, flow_type = check_flow_config(config_file)
+
+    assert_that(success, equal_to(False))
+    assert_that(flow_type, equal_to("sim"))
+    assert_that("not yet implemented" in message, equal_to(True))
+
+
+def test_detect_flow_type() -> None:
+    """Test detecting flow type from config file."""
+    fixtures_dir = Path(__file__).parent.parent / "flow" / "fixtures"
+    config_file = fixtures_dir / "example_lint.hjson"
+
+    flow_type = detect_flow_type(config_file)
+
+    assert_that(flow_type, equal_to("lint"))
+
+
+def test_detect_flow_type_missing(tmp_path: Path) -> None:
+    """Test detecting flow type when field is missing."""
+    config_file = tmp_path / "no_flow.hjson"
+    config_data = {"name": "test"}
+    config_file.write_text(hjson.dumps(config_data))
+
+    flow_type = detect_flow_type(config_file)
+
+    assert_that(flow_type, equal_to(None))

tests/flow/test_lint_parser.py

@@ -164,20 +164,20 @@ def test_missing_required_field_raises() -> None:
     assert "name" in str(exc_info.value)
 
 
-def test_extra_fields_allowed() -> None:
-    """Test that extra fields are allowed in the configuration."""
+def test_extra_fields_forbidden() -> None:
+    """Test that extra fields are forbidden in the configuration."""
     config_dict = {
         "name": "test",
         "flow": "lint",
         "custom_field": "custom_value",
-        "another_field": 123,
     }
 
-    config = load_lint_config_from_dict(config_dict)
+    # Should raise ValidationError for unknown fields
+    with pytest.raises(ValidationError) as exc_info:
+        load_lint_config_from_dict(config_dict)
 
-    assert_that(config.name, equal_to("test"))
-    # Extra fields should be accessible via model_extra or __dict__
-    assert hasattr(config, "custom_field") or "custom_field" in config.model_extra
+    # Verify the error mentions the unexpected field
+    assert "custom_field" in str(exc_info.value)
 
 
 def test_integration_with_example_hjson() -> None: