name: CI

on:
  pull_request:
    branches: ["**"]
  # Lets `hive-forge ci-rerun` re-trigger CI via the workflow-dispatch API
  # without an empty commit. No effect on the PR-triggered runs above.
  workflow_dispatch:

jobs:
  check:
    name: nix flake check
    runs-on: [hive-ci]
    # Bound the job so a wedged build fails in minutes instead of
    # hanging until the runner's 3h cap (or, when the runner itself
    # deadlocks, never). 30 min is well above a cold-cache rebuild
    # (~15 min observed) and well under the 3h hard cap — tune if a
    # legit cold build ever trips it.
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v3
      - name: check
        # Runs all flake checks: formatting (treefmt+rustfmt), cargo test,
        # cargo clippy, and module evaluation. No --no-build: the checks
        # derivations are the canonical source of truth.
        run: nix flake check

  tracker-tags:
    name: tracker-tag lint
    runs-on: [hive-ci]
    # Pure git+grep — seconds normally; a few minutes is already a hang.
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@v3
      - name: lint
        # Flags hash-number tracker tags in source (hive convention is
        # prose, not tags — /knowledge/hive-rules.md). Its own job, and
        # IS a required check on the forge (branch protection) — a hit
        # blocks merge. See scripts/check-issue-refs.sh.
        run: sh scripts/check-issue-refs.sh

  comment-blocks:
    name: comment-block lint
    runs-on: [hive-ci]
    # Pure git+awk — seconds.
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@v3
      - name: lint
        # Flags contiguous comment blocks over 30 lines (a giant prose
        # block belongs in docs/ as implementation notes, not in source).
        # Own job, and IS a required check on the forge (branch
        # protection) — a hit blocks merge. See
        # scripts/check-comment-blocks.sh.
        run: sh scripts/check-comment-blocks.sh

  doc-refs:
    name: doc-pointer lint
    runs-on: [hive-ci]
    # Pure git+grep — seconds.
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@v3
      - name: lint
        # Flags `docs/…md` paths and relative markdown links that no
        # longer resolve. Pointing at a doc is what the comment-block
        # lint above pushes people toward, so the pointers need a gate of
        # their own. See scripts/check-doc-refs.sh.
        run: sh scripts/check-doc-refs.sh

  prose-lint:
    name: prose lint (vale)
    runs-on: [hive-ci]
    # A `vale sync` + full docs/ run took under a minute in testing.
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@v3
      - name: lint
        # Styles (Microsoft + alex + write-good, named in .vale.ini's
        # `Packages` line) are fetched fresh from the Vale Package Hub each
        # run rather than vendored, so this job always lints against
        # upstream's current rules. Failing red on a hit is intentional --
        # the existing docs/ tree has a real backlog against these rules
        # (663 hits as of this writing), so this job starts out red on
        # unrelated PRs until that backlog is worked down. Not (yet) wired
        # into branch protection as a required check, so a red result here
        # doesn't block a merge -- opting it into required-check status is
        # a separate, later call.
        run: XDG_DATA_HOME="$PWD/.vale-data" nix shell nixpkgs#vale --command sh -c 'vale sync && vale docs'