feat: add pydantic model and parser for lint flow config

Add Pydantic-based config parser separate from existing flow config
infrastructure to enable gradual migration to standalone components.

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

Author: machshev

src/dvsim/linting/config.py

@@ -0,0 +1,79 @@
+# Copyright lowRISC contributors (OpenTitan project).
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Pydantic models for lint flow configuration."""
+
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class MessageBucket(BaseModel):
+    """Message bucket configuration for categorizing lint messages."""
+
+    model_config = ConfigDict(frozen=True)
+
+    category: str = Field(..., description="Message category (e.g., 'flow', 'lint')")
+    severity: str = Field(..., description="Message severity (e.g., 'info', 'warning', 'error')")
+    label: str = Field(default="", description="Optional label for the bucket")
+
+
+class LintFlowConfig(BaseModel):
+    """Configuration for the lint flow.
+
+    This model represents the core lint flow configuration that can be parsed
+    from hjson files. It focuses on lint-specific fields and does not include
+    all the base flow configuration fields that are handled by the existing
+    FlowCfg class hierarchy.
+    """
+
+    # Flow identification
+    flow: str = Field(default="lint", description="Flow type identifier")
+    name: str = Field(..., description="Name of the lint configuration")
+
+    # Build configuration
+    build_dir: str = Field(default="", description="Build directory path")
+    build_log: str = Field(default="", description="Build log file path")
+    build_cmd: str = Field(default="", description="Build command")
+    build_opts: list[str] = Field(default_factory=list, description="Build options")
+
+    # FuseSoC configuration
+    fusesoc_core: str = Field(default="", description="FuseSoC core to use")
+    additional_fusesoc_argument: str = Field(
+        default="", description="Additional FuseSoC argument (e.g., mapping)"
+    )
+
+    # Lint-specific configuration
+    is_style_lint: bool = Field(default=False, description="Whether this is a style lint run")
+    report_severities: list[str] = Field(
+        default_factory=lambda: ["info", "warning", "error"],
+        description="Message severities to include in reports",
+    )
+    fail_severities: list[str] = Field(
+        default_factory=lambda: ["warning", "error"],
+        description="Message severities that cause the flow to fail",
+    )
+    message_buckets: list[MessageBucket] = Field(
+        default_factory=list, description="Message bucket configuration"
+    )
+
+    # Tool configuration
+    tool: str | None = Field(default=None, description="Lint tool to use")
+    dut: str = Field(default="", description="Design under test name")
+
+    # Directory paths
+    scratch_path: str = Field(default="", description="Scratch directory path")
+    rel_path: str = Field(default="", description="Relative path for results")
+
+    # Import and use configurations
+    import_cfgs: list[str] = Field(
+        default_factory=list, description="Configuration files to import"
+    )
+    use_cfgs: list[dict | str] = Field(
+        default_factory=list, description="Sub-configurations to use (for primary configs)"
+    )
+
+    model_config = ConfigDict(
+        frozen=True,  # Make the model immutable
+        extra="allow",  # Allow extra fields for forwards compatibility
+    )

src/dvsim/linting/parser.py

@@ -0,0 +1,97 @@
+# Copyright lowRISC contributors (OpenTitan project).
+# Licensed under the Apache License, Version 2.0, see LICENSE for details.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Parser for lint flow hjson configuration files."""
+
+from pathlib import Path
+
+import hjson
+from pydantic import ValidationError
+
+from dvsim.linting.config import LintFlowConfig, MessageBucket
+
+
+def parse_lint_flow_config(hjson_path: str | Path) -> LintFlowConfig:
+    """Parse a lint flow hjson configuration file.
+
+    This function loads an hjson file and validates it against the LintFlowConfig
+    pydantic model. This is a new parser specifically for lint flows and does not
+    modify the existing flow config parsing infrastructure.
+
+    Args:
+        hjson_path: Path to the hjson configuration file
+
+    Returns:
+        LintFlowConfig: Validated lint flow configuration
+
+    Raises:
+        FileNotFoundError: If the hjson file doesn't exist
+        ValidationError: If the hjson data doesn't match the expected schema
+        RuntimeError: If there are other errors parsing the hjson
+
+    Example:
+        >>> config = parse_lint_flow_config("path/to/lint_cfg.hjson")
+        >>> print(config.name)
+        >>> print(config.report_severities)
+
+    """
+    hjson_path = Path(hjson_path)
+
+    if not hjson_path.exists():
+        msg = f"Configuration file not found: {hjson_path}"
+        raise FileNotFoundError(msg)
+
+    # Parse the hjson file using hjson library directly
+    try:
+        with hjson_path.open() as f:
+            hjson_data = hjson.load(f, use_decimal=True)
+    except hjson.HjsonDecodeError as e:
+        msg = f"Failed to parse hjson file {hjson_path}: {e}"
+        raise RuntimeError(msg) from e
+    except OSError as e:
+        msg = f"Failed to read hjson file {hjson_path}: {e}"
+        raise RuntimeError(msg) from e
+
+    # Validate against the pydantic model
+    try:
+        # Convert message_buckets from list of dicts to list of MessageBucket objects
+        if "message_buckets" in hjson_data:
+            hjson_data["message_buckets"] = [
+                MessageBucket(**bucket) if isinstance(bucket, dict) else bucket
+                for bucket in hjson_data["message_buckets"]
+            ]
+
+        return LintFlowConfig(**hjson_data)
+    except ValidationError as e:
+        msg = f"Configuration validation failed for {hjson_path}:\n{e}"
+        raise RuntimeError(msg) from e
+
+
+def load_lint_config_from_dict(config_dict: dict) -> LintFlowConfig:
+    """Load a lint flow configuration from a dictionary.
+
+    This is useful for loading inline configurations or for testing.
+
+    Args:
+        config_dict: Dictionary containing lint flow configuration
+
+    Returns:
+        LintFlowConfig: Validated lint flow configuration
+
+    Raises:
+        ValidationError: If the dictionary doesn't match the expected schema
+
+    Example:
+        >>> config_dict = {"name": "test_lint", "flow": "lint"}
+        >>> config = load_lint_config_from_dict(config_dict)
+
+    """
+    # Convert message_buckets if present
+    if "message_buckets" in config_dict:
+        config_dict["message_buckets"] = [
+            MessageBucket(**bucket) if isinstance(bucket, dict) else bucket
+            for bucket in config_dict["message_buckets"]
+        ]
+
+    return LintFlowConfig(**config_dict)

tests/flow/__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 tests."""

tests/flow/fixtures/example_lint.hjson

@@ -0,0 +1,50 @@
+// Copyright lowRISC contributors (OpenTitan project).
+// Licensed under the Apache License, Version 2.0, see LICENSE for details.
+// SPDX-License-Identifier: Apache-2.0
+
+// Example lint flow configuration for integration testing
+{
+  name: aes_dv_lint
+  flow: lint
+
+  // Design under test
+  dut: aes
+
+  // FuseSoC configuration
+  fusesoc_core: lowrisc:dv:aes_sim
+  additional_fusesoc_argument: --mapping=lowrisc:systems:top_earlgrey:0.1
+
+  // Build configuration
+  build_dir: "{scratch_path}/{build_mode}"
+  build_log: "{build_dir}/{tool}.log"
+  build_cmd: fusesoc
+  build_opts: [
+    "--cores-root {proj_root}/hw"
+    "run"
+    "--target={flow}"
+    "--tool={tool}"
+    "--work-root={build_dir}/fusesoc-work"
+  ]
+
+  // Lint configuration
+  is_style_lint: false
+  report_severities: ["info", "warning", "error"]
+  fail_severities: ["warning", "error"]
+
+  // Message bucket configuration
+  message_buckets: [
+    {category: "flow", severity: "info",    label: "Flow Info"}
+    {category: "flow", severity: "warning", label: "Flow Warnings"}
+    {category: "flow", severity: "error",   label: "Flow Errors"}
+    {category: "lint", severity: "info",    label: "Lint Info"}
+    {category: "lint", severity: "warning", label: "Lint Warnings"}
+    {category: "lint", severity: "error",   label: "Lint Errors"}
+  ]
+
+  // Tool configuration
+  tool: ascentlint
+
+  // Paths
+  scratch_path: /tmp/dvsim/scratch
+  rel_path: hw/ip/aes/dv/lint/{tool}
+}