ci.yml

name: CI

on:
  push:
    branches: [main, master]
  pull_request:
    branches: [main, master]
  workflow_dispatch:

# Cancel in-progress runs on the same branch when a new push lands.
concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

jobs:
  # ── 0. Version sync guard ──────────────────────────────────────────
  # Catches stale generated HDL constants before any other job wastes minutes.
  version-sync:
    name: VERSION and HDL constants in sync
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Verify HDL version constants are regenerated from VERSION
        run: python tools/sync_version.py --check

  # ── 1. Python lint ────────────────────────────────────────────────
  lint-python:
    name: Python lint (ruff)
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Install ruff
        run: pip install "ruff>=0.4.0,<0.13"
      - name: ruff check (whole repo)
        run: ruff check .

  # ── 2. Package install + import smoke test ────────────────────────
  install-smoke:
    name: pip install -e . + import fcapz
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Editable install
        run: pip install -e ".[dev]"
      - name: Verify top-level fcapz package resolves
        run: |
          python -c "
          import fcapz
          from fcapz import (
              Analyzer, CaptureConfig, TriggerConfig, ProbeSpec, SequencerStage,
              CaptureResult, Transport, OpenOcdTransport, XilinxHwServerTransport,
              VendorStubTransport,
              find_edges, find_rising_edges, find_falling_edges, find_bursts,
              frequency_estimate, summarize, ProbeDefinition,
              EioController, EjtagAxiController, AXIError, EjtagUartController,
          )
          print('all top-level fcapz exports importable')
          "
      - name: Verify fcapz CLI entry point is on PATH
        run: |
          fcapz --help | head -5

  # ── 3. Host unit tests (full suite, all tests/) ───────────────────
  test-host:
    name: Host unit tests (pytest)
    runs-on: ubuntu-latest
    env:
      QT_QPA_PLATFORM: offscreen
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Install system packages (iverilog + Qt runtime libs)
        run: |
          sudo apt-get update
          sudo apt-get install -y iverilog libegl1 libgl1
      - name: Install package (dev + GUI deps for mocked Qt tests)
        run: pip install -e ".[dev,gui]"
      - name: Run full unit test suite
        run: pytest tests/ -v --tb=short
      - name: Run JTAG readback pipeline regression tests
        run: |
          pytest \
            tests/test_transport.py::XilinxHwServerConnectFailureTests::test_parse_block_bits_can_skip_priming_word \
            tests/test_transport.py::XilinxHwServerConnectFailureTests::test_parse_burst_bits_can_skip_priming_scan \
            tests/test_transport.py::XilinxHwServerConnectFailureTests::test_read_block_burst_primes_user2_before_returned_scans \
            tests/test_transport.py::XilinxHwServerConnectFailureTests::test_user1_block_read_has_idle_before_each_capture \
            tests/test_host_stack.py::AnalyzerTests::test_capture_reads_32_bit_timestamps_via_burst_block \
            -v --tb=short

  # ── 4. Strict RTL lint (Verilator) ───────────────────────────────
  lint-rtl:
    name: Strict RTL lint (Verilator)
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - name: Install Verilator
        run: sudo apt-get install -y verilator
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Run strict Verilator RTL lint
        run: python sim/run_verilator_lint.py --self-test

  # -- 5. Verilog/VHDL static parity gate ------------------------------------
  hdl-parity:
    name: HDL static parity
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Run static HDL parity checks
        run: python sim/run_hdl_parity.py
      - name: Verify formal parity manifests
        run: python sim/run_formal_hdl_parity.py --interface-only

  # -- 6. Manual formal Verilog/VHDL equivalence proof -----------------------
  hdl-formal-parity:
    name: HDL formal parity (manual)
    if: github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install formal HDL tools
        run: |
          sudo apt-get update
          sudo apt-get install -y ghdl yosys
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Run formal Verilog/VHDL parity proofs
        run: python sim/run_formal_hdl_parity.py

  # -- 7. RTL simulation (cocotb + Icarus/GHDL) ---------------------
  # Sharded so the 16-target ELA suite runs in parallel with the protocol
  # benches, and runs the same cocotb stimulus against Verilog and VHDL.
  sim:
    name: RTL simulation (cocotb ${{ matrix.hdl }}) [${{ matrix.shard }}]
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shard: [protocol, ela]
        hdl: [verilog, vhdl]
    steps:
      - uses: actions/checkout@v4
      - name: Install HDL simulators
        run: |
          sudo apt-get update
          sudo apt-get install -y iverilog ghdl
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
          cache: pip
          cache-dependency-path: pyproject.toml
      - name: Install cocotb dependencies
        run: pip install -e ".[hdl]"
      - name: Run cocotb RTL regression (protocol shard)
        if: matrix.shard == 'protocol'
        run: python sim/run_cocotb.py --runner native --hdl ${{ matrix.hdl }} --clean --skip-ela --require-protocol-coverage
      - name: Run cocotb RTL regression (ELA shard)
        if: matrix.shard == 'ela'
        run: python sim/run_cocotb.py --runner native --hdl ${{ matrix.hdl }} --clean ela