FabledCurator/.forgejo/workflows/ci.yml

name: CI

# CI lanes per FabledRulebook/forgejo.md "CI philosophy":
#   - lint: ruff only, no dep install — fast-fail for the common lint bounce.
#   - extension-version: the derived version resolves and is a shape AMO takes.
#   - backend-lint-and-test: `pytest -m "not integration"`, no service containers.
#   - frontend-build: vitest unit + vite build.
#   - integration: pgvector + redis service containers; alembic + `pytest -m integration`.

on:
  push:
    branches: [dev, main]
  # Renovate opens PRs from `renovate/*` branches into `dev`. Those branches
  # never push to dev/main, so the push trigger above gives them NO pre-merge
  # CI — a bump could only be validated after it was already merged. This
  # pull_request trigger (base `dev` only) validates Renovate PRs before merge.
  # It deliberately does NOT fire on dev→main PRs (base `main`), which still
  # rely on the dev push run — so no duplicate runs. FC has no fork PRs
  # (single-operator Forgejo repo), so secrets-on-PR is not a concern.
  pull_request:
    branches: [dev]

jobs:
  # Fast-fail lint lane. ruff is pre-installed in the ci-python image, so
  # this runs with NO dependency install and surfaces the most common bounce
  # class (lint: I001 / UP037 / ASYNC109 / W293 …) in seconds — instead of
  # after the backend job's ~30-60s wheel install. ruff is static analysis,
  # so no DB/secret env is needed.
  lint:
    runs-on: python-ci
    container:
      image: git.fabledsword.com/bvandeusen/ci-python:3.14
    steps:
      - uses: actions/checkout@v4
      - name: Ruff lint
        # agent/ included so the GPU-agent is linted before its image is built
        # (build.yml only `docker build`s it — this is where it gets checked).
        # scripts/ likewise: release_notes.py runs only on a tag push, so a
        # syntax or import error there would otherwise surface at the one
        # moment nobody wants to debug a workflow.
        run: ruff check backend/ tests/ alembic/ agent/ scripts/
      - name: Agent syntax check
        # The agent's runtime deps (torch/transformers/ultralytics) aren't in the
        # CI image, so we can't import it — but compileall parses every module,
        # catching syntax errors before the image build.
        run: python -m compileall -q agent/fc_agent

  # The extension version is DERIVED, not hand-maintained (milestone 271 step
  # 4): build.yml computes it from the commit TIME of the newest packaged
  # extension change and stamps it into manifest.json / package.json at build
  # time. The guard that used to live here — "packaged files changed but nobody
  # bumped the version" — was therefore checking a fact that had stopped
  # existing. Worse than useless: it would have failed this lane on every real
  # extension change, demanding a bump that decides nothing. Retired 2026-08-27
  # rather than left running beside the new mechanism (rule 22).
  #
  # Two things are still worth asserting, and this is the only lane that can:
  # the extension.yml suite runs on node:24-slim, which is exactly why
  # version.spec.js sticks to packaging.sh's git-free subcommands.
  #   1. the derivation actually resolves on this commit
  #   2. the derived string is one AMO will accept, checked against Mozilla's
  #      own published grammar rather than a loose "digits and dots"
  #
  # The MAJOR.MINOR-agreement check that used to be (2) is gone with milestone
  # 318 step 8: the committed version no longer seeds anything, so there is no
  # hand-set part left for the two files to disagree about.
  #
  # Deliberately NOT checked here: that the derived value beats what has already
  # been signed. That guard belongs in build.yml, where it compares against the
  # real ext-* releases. Comparing against origin/main here would be wrong —
  # dev legitimately derives a LOWER value whenever main is ahead on the
  # extension, and a lane that fails for being behind is a lane people learn to
  # ignore.
  extension-version:
    runs-on: python-ci
    container:
      image: git.fabledsword.com/bvandeusen/ci-python:3.14
    steps:
      - uses: actions/checkout@v4
        with:
          # The derivation needs real history: a depth-1 clone sees one commit
          # and produces a wrong, too-low value RATHER THAN FAILING. Checking
          # that here is half the point of the lane.
          fetch-depth: 0
      - name: Extension version derives cleanly
        run: |
          set -eu
          # busybox sh on the act_runner — no bashisms (family rule).
          VERSION=$(sh extension/scripts/packaging.sh version)
          echo "derived: $VERSION"

          # Mozilla's published grammar for AMO, transcribed verbatim from
          # MDN's manifest.json/version page:
          #
          #     ^(0|[1-9][0-9]{0,8})([.](0|[1-9][0-9]{0,8})){0,3}$
          #
          # Not the looser `^[0-9]+(\.[0-9]+)*$` this lane used to carry. That
          # one passes `2026.08.29.0201`, which AMO REJECTS — a segment must be
          # the single digit 0 or start 1-9 — and it also passes five segments,
          # where AMO allows four. Both would surface as a failed sign with the
          # version already burned: AMO 409s on re-signing, so a rejected value
          # cannot be reclaimed and cannot be reused. This lane is the cheap
          # place to find out. (#3138, milestone 318 step 8.)
          if ! echo "$VERSION" | grep -qE '^(0|[1-9][0-9]{0,8})(\.(0|[1-9][0-9]{0,8})){0,3}$'; then
            echo "ERROR: derived version '$VERSION' is not a version AMO accepts."
            echo "AMO's grammar: ^(0|[1-9][0-9]{0,8})([.](0|[1-9][0-9]{0,8})){0,3}$"
            echo "Most likely cause: a zero-padded segment (08, 0201). The rest"
            echo "of the family pads; the extension must not — see packaging.sh."
            exit 1
          fi

          # ...and the shape this project actually derives. AMO would happily
          # take `1.0.3500147` too, so the grammar check alone would not notice
          # a regression to the pre-318 shape — which orders BELOW everything
          # signed since, and is unrecoverable once Firefox has the higher one.
          if ! echo "$VERSION" | grep -qE '^20[0-9][0-9]\.[0-9]{1,2}\.[0-9]{1,2}\.[0-9]{1,4}$'; then
            echo "ERROR: derived version '$VERSION' is not YYYY.M.D.HHMM."
            echo "Rule 148's CalVer is what build.yml signs; the old"
            echo "1.0.<minutes> shape would order below every ext-2026.* release."
            exit 1
          fi
          echo "OK: derived version $VERSION"

  backend-lint-and-test:
    runs-on: python-ci
    container:
      image: git.fabledsword.com/bvandeusen/ci-python:3.14
    env:
      # DB_PASSWORD and SECRET_KEY are required by config.py at import time
      # even though unit tests don't actually touch the DB or use the secret.
      DB_PASSWORD: ci_unit_test_placeholder
      SECRET_KEY: ci_unit_test_placeholder
    steps:
      - uses: actions/checkout@v4
        with:
          # Full history for tests/test_artifact_identity.py, which derives
          # each artifact's revision to check the identity scheme. On a
          # depth-1 clone that derivation either fails or returns the tip sha
          # — so the lane would go green while asserting nothing, which is
          # the one outcome worse than a red one.
          fetch-depth: 0

      # Cache step removed 2026-05-26: act_runner's cache backend has been
      # broken on this homelab runner since 2026-05-15 (first as request-
      # timeout warnings, then as hard "Cannot find module .../dist/restore/
      # index.js" failures that tank the whole job). The cache step targeted
      # ~/.cache/pip but the install below uses `uv pip install` primarily,
      # whose own cache lives at ~/.cache/uv — so the cache step's real
      # benefit was marginal even when working. Cost of removal: ~30s of
      # wheel downloads per job. Future re-enable: mount ~/.cache/uv as a
      # docker volume at the runner level (skips actions/cache entirely),
      # or fix the runner-side cache backend (clear /var/run/act/actions/*,
      # pin act_runner version, etc.).

      - name: Install Python deps
        # ruff is pre-installed in the ci-python image (see CI-Runner/CI-python/
        # Dockerfile's RUFF_VERSION). Per FabledRulebook ci-runners.md, toolchain
        # versions live on the runner image, not here.
        # uv: 5-10x faster wheel resolve than pip for cold caches.
        # Falls back to pip install on uv-missing runners (older images).
        run: |
          if command -v uv >/dev/null 2>&1; then
            uv pip install --system -r requirements.txt pytest pytest-asyncio
          else
            pip install -r requirements.txt pytest pytest-asyncio
          fi

      # Ruff moved to the dedicated fast `lint` job above (fails in seconds,
      # no dep install). This job is now unit tests only.
      - name: Pytest (unit only — integration runs in the integration job)
        run: pytest tests/ -v -m "not integration"

  frontend-build:
    runs-on: python-ci
    container:
      image: git.fabledsword.com/bvandeusen/ci-python:3.14
    defaults:
      run:
        working-directory: frontend
    steps:
      - uses: actions/checkout@v4
      # No package-lock.json is tracked yet (we don't run npm locally per
      # feedback-no-local-runs). Using `npm install` instead of `npm ci`.
      # If we want strict lockfile-based reproducibility later, commit a
      # package-lock.json and flip this back to `npm ci`.
      - run: npm install --no-audit --no-fund
      # No type-check step: the frontend is pure JS (no .ts files, no JSDoc),
      # so a type-checker has nothing to do. The vue-tsc devDep + its `check`
      # script were dropped 2026-07-11 rather than bumped to v3. If we add
      # TS/JSDoc later, re-add a tsconfig.json + vue-tsc + a type-check step.
      - run: npm run test:unit
      - run: npm run build

  # Single integration job — collapsed from a 3-way shard split on 2026-06-04.
  # The shards existed to parallelize ~8.5min of integration tests; once the
  # throwaway Postgres runs with fsync OFF (the durability step below) the whole
  # suite runs in ~45s, so the split only triplicated the ~2min fixed overhead
  # (container + `uv pip install` + `alembic upgrade head`) and burned 3 of 6
  # runner slots for no wall-clock gain. One job now: spin up once, install
  # once, migrate once, run every integration test.
  #
  # The docker-ps filter scopes to THIS job's own Postgres/Redis service
  # containers by job name. act_runner strips underscores from job names when
  # labelling containers (`int_api` matched nothing on 2026-05-25), so the name
  # stays separator-free (`integration`). The step prints `docker ps -a` first
  # so a future naming-convention shift surfaces in the log without a
  # guess-and-push cycle.
  #
  # Pre-baking requirements.txt into ci-python:3.14 is intentionally NOT done —
  # per ci-requirements.md, FC is the only Python consumer of that image and the
  # CI-Runner "add deps to image when used by >1 project" rule keeps it per-job.
  integration:
    runs-on: python-ci
    container:
      image: git.fabledsword.com/bvandeusen/ci-python:3.14
    env:
      DB_USER: fabledcurator
      DB_PASSWORD: ci_integration
      DB_PORT: "5432"
      DB_NAME: fabledcurator_test
      SECRET_KEY: ci_integration_placeholder
    services:
      postgres:
        image: pgvector/pgvector:pg16
        env:
          POSTGRES_USER: fabledcurator
          POSTGRES_PASSWORD: ci_integration
          POSTGRES_DB: fabledcurator_test
        options: >-
          --health-cmd "pg_isready -U fabledcurator"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 10
      redis:
        image: redis:7-alpine
        options: >-
          --health-cmd "redis-cli ping"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 10
    steps:
      - uses: actions/checkout@v4
      - name: Integration suite (resolve service IPs, migrate, test)
        run: |
          set -eux
          echo "=== container landscape (diagnostic for filter scoping) ==="
          docker ps -a --format '{{.ID}} {{.Image}} -> {{.Names}}'
          echo "=== end landscape ==="
          PG=$(docker ps --filter "name=integration" --filter "ancestor=pgvector/pgvector:pg16" -q | head -n1)
          RD=$(docker ps --filter "name=integration" --filter "ancestor=redis:7-alpine" -q | head -n1)
          test -n "$PG" && test -n "$RD"
          PG_IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$PG")
          RD_IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$RD")
          test -n "$PG_IP" && test -n "$RD_IP"
          export DB_HOST="$PG_IP"
          export CELERY_BROKER_URL="redis://$RD_IP:6379/0"
          export CELERY_RESULT_BACKEND="redis://$RD_IP:6379/0"
          # These steps run under `sh -e`, not bash, so bash's /dev/tcp magic
          # path does not exist here — the probe this loop used to run could
          # never succeed and simply burned the full 120s on every run, green
          # or red, then continued without having established anything. Python
          # is in the image and needs no installed package for a socket
          # connect, so it is the probe. Exhausting the budget is now a named
          # failure rather than a silent fall-through (rule 156): if Postgres
          # is genuinely not up, that is what the log should say, instead of
          # whatever the first query happens to raise two minutes later.
          pg_ready=""
          for i in $(seq 1 60); do
            if python -c "import socket,sys; s=socket.socket(); s.settimeout(2); sys.exit(0 if s.connect_ex(('$PG_IP', 5432)) == 0 else 1)"; then
              pg_ready=1
              break
            fi
            sleep 2
          done
          if [ -z "$pg_ready" ]; then
            echo "postgres at $PG_IP:5432 did not accept a connection within 120s"
            exit 1
          fi
          if command -v uv >/dev/null 2>&1; then
            uv pip install --system -r requirements.txt pytest pytest-asyncio
          else
            pip install -r requirements.txt pytest pytest-asyncio
          fi
          # Relax durability on the throwaway CI Postgres so the per-test
          # TRUNCATE's commit-fsync — the integration teardown's dominant cost
          # (~1.5-2s/test, which collapsed the suite from ~13min to ~45s) — is
          # skipped. fsync/full_page_writes are sighup GUCs and synchronous_commit
          # is user-context, so ALTER SYSTEM + pg_reload_conf() applies them with
          # NO restart. Ephemeral DB ⇒ fsync-off is safe. Non-fatal so a perms
          # surprise can't red the job; fabledcurator is the postgres image's
          # bootstrap superuser.
          python -c "import os,psycopg; c=psycopg.connect(host=os.environ['DB_HOST'],port=5432,user=os.environ['DB_USER'],password=os.environ['DB_PASSWORD'],dbname=os.environ['DB_NAME'],autocommit=True); [c.execute(q) for q in ('ALTER SYSTEM SET fsync=off','ALTER SYSTEM SET synchronous_commit=off','ALTER SYSTEM SET full_page_writes=off','SELECT pg_reload_conf()')]; c.close()" || echo 'WARN: durability GUC relax failed (continuing)'
          alembic upgrade head
          pytest tests/ -v -m integration --durations=15