spec-ep/.github/workflows/ci-python.yml at main · structural-explainability/spec-ep · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
# ============================================================
# .github/workflows/ci-python.yml (Continuous Integration)
# ============================================================
# Updated: 2026-05-15 SPEC VARIANT
#
# WHY-FILE: Validate repository hygiene, specification consistency,
# generated artifacts, and Python correctness.
#
# === COVERAGE ===
#
# This workflow validates the repository through the same broad gates
# used by Python-backed specification repositories.
#
# Hygiene checks are kept early so structural, formatting, and syntax issues
# fail before deeper validation runs.
#
# Specification checks verify that human-authored sources and generated
# machine-readable artifacts remain aligned.
#
# Python checks verify implementation correctness for local validation tools.
#
# NOT INCLUDED IN THIS SPEC VARIANT:
#   - formal proof checking
#   - documentation site builds

name: CI (Python)

on:
  push:
    branches: [main] # WHY: Validate committed changes on the primary branch.
  pull_request:
    branches: [main] # WHY: Validate proposed changes before merge.
  workflow_dispatch: # WHY: Allow manual validation from the Actions tab.

permissions:
  contents: read # WHY: CI only needs read access.

env:
  PYTHONUNBUFFERED: "1" # WHY: Keep logs visible while commands run.
  PYTHONIOENCODING: "utf-8" # WHY: Keep text handling consistent.
  PYTHON_VERSION: "3.15"
  UV_PYTHON: "3.15"

jobs:
  ci:
    name: Repository / Python checks
    runs-on: ubuntu-latest
    timeout-minutes: 30

    steps:
      # ============================================================
      # A) ASSEMBLE: Checkout code and set up environment
      # ============================================================

      - name: A1) Checkout repository code
        uses: actions/checkout@v6

      - name: A2) Install uv with caching
        uses: astral-sh/setup-uv@v7
        with:
          enable-cache: true
          cache-dependency-glob: "uv.lock"

      - name: A3) Install Python
        run: uv python install ${{ env.PYTHON_VERSION }}

      - name: A4) Install project dependencies
        run: uv sync --extra dev --extra docs --upgrade

      - name: A5) Show tool versions
        run: |
          uv --version
          uv run python --version

      # ============================================================
      # B) HYGIENE: Repository hygiene checks
      # ============================================================

      - name: B1) Run configured repository hygiene checks
        run: uv tool run pre-commit run --all-files

      - name: B2) Run configured YAML checks
        uses: ibiqlik/action-yamllint@v3
        with:
          config_file: .github/.yamllint.yml
          file_or_dir: .
          no_warnings: true

      # ============================================================
      # C) SPEC: Specification consistency and generated artifacts
      # ============================================================

      - name: C1) Validate specification consistency
        run: uv run se-validate

      - name: C2) Generate machine-readable artifacts
        run: uv run se-ref-export

      - name: C3) Check generated artifacts
        run: uv run se-ref-export --check

      - name: C4) Validate generated artifacts
        run: uv run se-ref-validate

      - name: C5) Run strict validation
        run: uv run se-validate --strict

      - name: C6) Ensure generated artifacts are committed
        run: |
          git diff --exit-code || {
            echo "Generated artifacts are out of date. Regenerate and commit them."
            exit 1
          }

      # ============================================================
      # D) PYTHON: Type checks and tests
      # ============================================================

      - name: D1) Run type checks
        run: uv run python -m pyright

      - name: D2) Run tests
        run: uv run python -m pytest