se-codeowners/.github/workflows/ci-python-zensical.yml at main · structural-explainability/se-codeowners · 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-zensical.yml (Continuous Integration)
# ============================================================
# Updated: 2026-06-01 (pypi ci)
#
# WHY-FILE: Validate repository hygiene, Python correctness, and documentation builds.
#
# === COVERAGE ===
#
# COVERED BY PRE-COMMIT - not repeated as explicit steps:
#   - ruff-check (lint with autofix)
#   - ruff-format (formatting)
#   - trailing whitespace, line endings, JSON/TOML/YAML syntax, large files
#
# WHY SEPARATE: These tools are slower, require the full environment,
# or produce output worth seeing in CI logs independently.

name: CI (Python + Zensical)

on:
  push:
    branches: [main]       # WHY: Validate every push to main.
  pull_request:
    branches: [main]       # WHY: Validate PRs before merge.
  workflow_dispatch:        # WHY: Allow manual trigger from Actions tab.

permissions:
  contents: read            # WHY: Least privilege; CI only reads, never writes.

env:
  PYTHONUNBUFFERED: "1"    # WHY: Real-time log output in CI.
  PYTHONIOENCODING: "utf-8" # WHY: Consistent encoding across platforms.
  PYTHON_VERSION: "3.14"


jobs:
  ci:
    name: Repository / Python checks and Zensical build
    runs-on: ubuntu-latest  # WHY: Linux matches most production deployments.
    timeout-minutes: 30     # WHY: Fail fast if a step hangs unexpectedly.

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

      - name: A1) Checkout repository code
        uses: actions/checkout@v6
        # WHY: Required so all subsequent steps can access repo files.

      - name: A2) Install uv (with caching)
        uses: astral-sh/setup-uv@v7
        with:
          enable-cache: true
          # WHY: Cache the uv tool itself for faster subsequent runs.
          cache-dependency-glob: "uv.lock"
          # WHY: Invalidate cache only when locked dependencies change.

      - name: A3) Install Python ${{ env.PYTHON_VERSION }}
        run: uv python install ${{ env.PYTHON_VERSION }}
        # WHY: Ensures the pinned Python version is available in CI.
        # OBS: Does not modify the repo; uv manages the interpreter locally.

      - name: A4) Sync all dependencies (without upgrading)
        run: uv sync --extra dev --extra docs
        # WHY: Install dev and docs extras so all check and build tools are available.

      - name: A5) Show tool versions
        run: |
          uv --version
          uv run python --version
          uv run python -m ruff --version
          uv run python -m pyright --version
          if [ -f "zensical.toml" ]; then
            uv run python -m zensical --version
          fi

      - name: A6) Run pre-commit on all files
        run: uvx pre-commit run --all-files

      # ============================================================
      # B) BASELINE CHECKS: Tools not covered by pre-commit
      # ============================================================
      - name: B1) Run Pyright type checker
        run: uv run python -m pyright

      # ============================================================
      # C) COVERAGE & TESTING: Python tests (pytest)
      # ============================================================

      - name: C1) Run pytest
        run: uv run python -m pytest

      # ============================================================
      # D) Docs build (no deployment)
      # ============================================================

      - name: D1) Build documentation with Zensical
        run: |
          if [ -f "zensical.toml" ]; then
            uv run python -m zensical build
          else
            echo "No zensical.toml found; skipping docs build."
          fi

      # ============================================================
      # E) Execute local cli commands for additional checks
      # ============================================================

      - name: E1) Validate repository manifest against schema
        run: uvx se-manifest-schema validate-manifest --path SE_MANIFEST.toml --strict

      - name: E2) Confirm se-codeowners command surface
        run: |
          uv run se-codeowners --help
          uv run se-codeowners generate --help
          uv run se-codeowners check --help

      - name: E3) Check generated CODEOWNERS is current
        run: uv run se-codeowners check --strict

      - name: E4) Check import layers
        run: uvx --with-editable . --from import-linter lint-imports --config .github/.importlinter