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,76 @@
+# 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:
+        raise FlowCheckError(f"Failed to parse hjson: {e}") from e
+    except OSError as e:
+        raise FlowCheckError(f"Failed to read file: {e}") 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)
+            return True, f"Valid lint flow config: {config.name}", flow_type
+        except Exception as e:
+            return False, f"Invalid lint flow config: {e}", 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

@@ -76,5 +76,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: