Pre-Commit Quality Gate

This document describes the automated quality checks that run before every git commit in a RouteRTL project.

Installation

# CLI (recommended)
routertl workspace install-hooks

# Make (equivalent)
make install-hooks

Flow Diagram

flowchart TD
    COMMIT["git commit"]
    LOCAL["hooks/pre-commit.local"]
    MDCHECK{"All staged files .md?"}
    SDK["Locate SDK Tools"]
    YAML["Parse project.yml"]
    FROZEN["Frozen Directory Guard"]
    YAMLCHK["YAML Validity Check"]
    LINKS["Markdown Link Validation"]
    LINKRUN["check_links.py"]
    MKDOCS["MkDocs Build (strict)"]
    LINT["Smart HDL Linting"]
    REGR["Full Regression Suite"]
    TESTS["Selected Test Suite"]
    PASS["✅ Commit Accepted"]
    FAIL["❌ Commit Aborted"]

    COMMIT --> LOCAL
    LOCAL -->|"if exists"| MDCHECK
    COMMIT -->|"no local hook"| MDCHECK

    MDCHECK -->|"yes: MD_ONLY=true"| SDK
    MDCHECK -->|"no: MD_ONLY=false"| SDK

    SDK -->|"vendor/routertl/ OR ROUTERTL_ROOT OR tools/"| YAML
    SDK -->|"SDK not found"| PASS

    YAML -->|"hooks.pre_commit.enabled = false"| PASS
    YAML -->|"enabled = true"| FROZEN

    FROZEN -->|"staged files in frozen dir"| FAIL
    FROZEN -->|"clean"| YAMLCHK

    YAMLCHK --> LINKS
    LINKS -->|"check_links: true"| LINKRUN
    LINKS -->|"check_links: false"| MKDOCS
    LINKRUN -->|"broken links"| FAIL
    LINKRUN -->|"all pass"| MKDOCS

    MKDOCS -->|"MD_ONLY=true"| PASS
    MKDOCS -->|"MD_ONLY=false"| LINT

    LINT -->|"lint: true"| LINTRUN["make linting"]
    LINT -->|"lint: false"| REGR

    LINTRUN -->|"hierarchies fail"| FAIL
    LINTRUN -->|"all pass"| REGR

    REGR -->|"run_regression: true"| REGRRUN["make regression"]
    REGR -->|"run_regression: false"| TESTS

    REGRRUN -->|"any failure"| FAIL
    REGRRUN -->|"all pass"| TESTS

    TESTS -->|"tests: list defined"| TESTRUN["make simulation<br/>consolidated patterns"]
    TESTS -->|"no tests defined"| PASS

    TESTRUN -->|"any failure"| FAIL
    TESTRUN -->|"all pass"| PASS

    style COMMIT fill:#2d5016,stroke:#4a8c2a,color:#fff
    style PASS fill:#1a5c3a,stroke:#2da36b,color:#fff
    style FAIL fill:#8c1a1a,stroke:#c43c3c,color:#fff
    style MDCHECK fill:#0d4a4a,stroke:#1a9a8a,color:#fff
    style SDK fill:#1a3a5c,stroke:#2d6da3,color:#fff
    style YAML fill:#1a3a5c,stroke:#2d6da3,color:#fff
    style FROZEN fill:#5c4a1a,stroke:#a3832d,color:#fff
    style LINT fill:#3a1a5c,stroke:#6d2da3,color:#fff
    style LINTRUN fill:#3a1a5c,stroke:#6d2da3,color:#fff
    style REGR fill:#5c1a3a,stroke:#a32d6d,color:#fff
    style REGRRUN fill:#5c1a3a,stroke:#a32d6d,color:#fff
    style TESTS fill:#5c1a3a,stroke:#a32d6d,color:#fff
    style TESTRUN fill:#5c1a3a,stroke:#a32d6d,color:#fff
    style YAMLCHK fill:#1a3a5c,stroke:#2d6da3,color:#fff
    style LOCAL fill:#1a3a5c,stroke:#2d6da3,color:#fff
    style LINKS fill:#2d5016,stroke:#4a8c2a,color:#fff
    style LINKRUN fill:#2d5016,stroke:#4a8c2a,color:#fff
    style MKDOCS fill:#1a3a5c,stroke:#2d6da3,color:#fff

Gate Details

1. Local Extensions

Sourced from hooks/pre-commit.local if present. Allows project-specific hooks without modifying the SDK.

1.5. Markdown-Only Detection

Inspects the staged file list via git diff --cached --name-only --diff-filter=ACMR. If every staged file has a .md extension, sets the MD_ONLY flag. Downstream stages 4–6 (Python lint, HDL lint, regression, simulation) check this flag and skip when MD_ONLY=true. Documentation stages (link validation, MkDocs build) always run regardless of the flag.

2. Markdown Link Validation (check_links: true)

• Scans docs/ for internal markdown links
• Verifies that target files exist on disk
• Supports exclusions via exclude.docs in project.yml
• Prevents broken documentation cross-references from reaching main

3. Smart HDL Linting (lint: true)

• Auto-detects all top-level hierarchies via forest analysis
• Compiles each hierarchy with GHDL --std=08 -fsynopsys
• Incremental — only re-lints files that changed since last run
• Configurable exclusions via exclude_lint in project.yml

3. Full Regression (run_regression: true)

Runs make regression which executes the project-manager test suite (unit tests for SDK tools, Linux bindings, dependency resolution, etc.).

4. Selected Tests (tests: list)

Runs Cocotb simulations for each listed test pattern:

• Unit tests — RTL component verification (edge detector, FIFO, CDC, etc.)
• Driver tests — Protocol BFM verification (AXI-Lite, SPI, UART, bridge adapters)
• Consolidated into a single make simulation call for efficiency
• Individual tests can be excluded via exclude_tests

5. Frozen Directory Guard

Prevents accidental modifications to protected directories (e.g., libs/, vendor IP).

Configuration Reference

# project.yml
hooks:
  pre_commit:
    enabled: true          # Master switch
    lint: true             # Smart HDL Linting
    check_yaml: true       # YAML validity
    run_regression: true   # SDK regression suite
    frozen_dirs:           # Protected directories
      - libs/xpm_vhdl
    exclude_lint:          # Skip linting these files
      - legacy_wrapper.vhd
    tests:                 # Cocotb tests to run
      - tests.units.test_edge_detector
      - tests.drivers.test_axi_lite
    exclude_tests:         # Skip these tests
      - tests.slow.test_soak