rust-fs-ext4 0.8.0

name: CI

# EVERY JOB RUNS CHORE TASKS, so a green local `chore test` is the same
# evidence as a green run here (see the test contract at the top of
# chores.yml):
#
#   unit         `chore test:unit` on a runner with NO fixtures: the tests
#                that need no tool, no fixture and no VM, in the debug
#                profile that traps an arithmetic overflow. That the job
#                passes with test-disks/ empty is what proves the split.
#   fixtures     `chore fixtures`: the kernel-made images, built in the
#                fs-linux-test-harness VM under KVM on x86_64, and handed
#                to the other jobs as an artifact (they are disk images,
#                the same for every architecture).
#   test         x86_64, where GitHub gives us KVM: `chore lint` and
#                `chore test` — the whole gate, with EVERY e2fsprogs call,
#                every kernel mount and every lwext4 call happening inside
#                the harness VM. Nothing installs e2fsprogs on the runner,
#                and the log shows `[oracle vm]` / `[kernel vm]` for each
#                one. The guest also builds lwext4 (a third ext4
#                implementation, at the commit scripts/vm-setup.sh pins)
#                so `chore test:lwext4` can cross-validate against it.
#   test-arm64   aarch64 matters on its own (c_char is unsigned there, and
#                Apple Silicon hosts run on it) but GitHub's arm64
#                runners have NO KVM, so no VM can run: this job runs the
#                tiers that need none — lint, the unit tier, and the
#                fixture-reading tests. The tool, kernel and lwext4
#                oracles are architecture-independent (they read the same
#                images) and are covered by `test`; so are the script
#                tests, which check the tree rather than the machine.
#   suite-in-vm  `chore test:vm`: the whole suite COMPILED AND RUN INSIDE
#                the guest. That is how a macOS host runs a Linux suite,
#                and this job is what keeps that path working.
#   wasm         `chore test:wasm`: the browser build (wasm32-unknown-
#                unknown) RUN under wasm-bindgen-test in Node, because std
#                there compiles clock and process-ID calls that panic at
#                run time -- a build-only check cannot see them.
#   semver       `chore check:semver`: the public API against the newest
#                crates.io release, refusing a break Cargo.toml's version
#                does not declare (#120).
#   msrv         `chore check:msrv`: the library and the binaries built on
#                the toolchain Cargo.toml's `rust-version` names, so the
#                declared minimum stays the true one.
#   cli          `chore cli:install` then `chore test:cli`: the command-line
#                tools built in release mode, staged under every name first
#                on PATH, and tested AS INSTALLED -- `rust-fs-ext4 doctor`
#                first, then tests/cli/*.sh. A change that breaks a tool
#                fails the pull request, not the release. No VM: what
#                e2fsprogs makes of the tools' output is judged in the
#                oracle tier (tests/cli_*_oracle.rs).
#   provenance   `chore check:provenance`: no tracked file names a Linux
#                kernel or e2fsprogs function, internal macro or source
#                path (AGENTS.md, "Clean room"). No toolchain, no fixtures:
#                it reads the tree, so it answers in seconds.
#   ci-ok        the one required check: green only when every job above
#                ran and succeeded (failed, cancelled OR skipped fails it).
#
# THE OUTPUT BUDGET IS IN THE TASKS, so it is in this workflow too. Each
# tier writes its full output to tmp/logs/<tier>.log and prints a verdict;
# a tier that prints more than its measured budget FAILS (exit 65), which
# is how a job that starts emitting thousands of lines turns red here
# rather than being noticed by whoever scrolls it next. See the budget
# table at the top of chores.yml, and the harness README's "Output: quiet
# by default, --verbose on request". Nothing extra is needed in this file:
# every job already runs chore tasks, which is the whole point of them.
#
# The logs are uploaded as artefacts (tier-logs-<job>), `if: always()`
# because the run worth reading is the one that failed -- AND only once
# the job's first tier step has run (`steps.tier.outcome != 'skipped'`).
# A job that dies in setup, the sibling checkout, the fixture download
# or lint has written no tmp/logs/*.log, and an upload refusing an
# empty path would add a second red step hiding the real cause (#306).
# tests/ci_profile.rs holds every such upload to that.

on:
  push:
    branches: [main]
    tags: ['v*']
  # NO BRANCH FILTER ON PULL REQUESTS (#132). With `branches: [main]` a
  # pull request based on anything else ran no CI at all — and still
  # collected its review-bot ticks, so it read as verified. This
  # repository stacks pull requests routinely, a fix branched off a fix
  # that has not merged yet, which is exactly the case that got nothing:
  # PR #131 came back with one check, its review bot, against PR #130's
  # three on the same day.
  pull_request:

concurrency:
  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

permissions:
  contents: read

env:
  CARGO_TERM_COLOR: always
  CHORE_VERSION: "0.11.0"

jobs:
  unit:
    name: unit (no tools, no fixtures)
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - name: Install chore
        # Pinned (CHORE_VERSION) and checked against the release's
        # checksums: the siblings, the tools and the tests all come
        # through it.
        run: scripts/ci-install-chore.sh
      - name: chore siblings
        # rust-fs-core (the path dependency) and fs-linux-test-harness, at
        # the refs pinned in chores.yml.
        run: chore siblings
      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable
        with:
          components: rustfmt, clippy
      # restore-keys: any Cargo.lock change (fuzz/Cargo.lock included) misses
      # the exact key, and a cold start prints every crate download and
      # compile into the tier log -- 714 lines against the unit budget of
      # 700, measured on #370, where a warm run prints about 645.
      - name: Cache cargo
        uses: actions/cache@v4
        with:
          path: |
            ~/.cargo/registry
            ~/.cargo/git
            target
          key: ${{ runner.os }}-unit-cargo-${{ hashFiles('**/Cargo.lock') }}
          restore-keys: ${{ runner.os }}-unit-cargo-
      - name: No fixtures are present
        run: |
          set -euo pipefail
          if ls test-disks/*.img >/dev/null 2>&1; then
            echo "::error::test-disks/ has images; this job must prove the unit tier needs none"
            exit 1
          fi
      - name: chore test:unit
        id: tier
        run: chore test:unit
      - name: Keep the tier logs
        # A quiet tier writes its detail to tmp/logs/<tier>.log and prints a
        # verdict; without this the detail dies with the runner and the only
        # record left is the one line the terminal got. `if: always()` because
        # the run worth reading is the one that failed; not before the tier
        # ran, though, or there is no log and this step's red hides the real
        # one (#306).
        if: always() && steps.tier.outcome != 'skipped'
        uses: actions/upload-artifact@v4
        with:
          name: tier-logs-unit
          path: tmp/logs/*.log
          if-no-files-found: error

  fixtures:
    name: fixtures (harness VM, x86_64 KVM)
    runs-on: ubuntu-24.04
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@v4
      - name: Install chore
        run: scripts/ci-install-chore.sh
      - name: chore siblings
        run: chore siblings
      - name: KVM, QEMU and Vagrant
        id: vm-host
        run: ../fs-linux-test-harness/scripts/ci-setup-linux.sh
      - name: Cache the Vagrant box
        uses: actions/cache@v4
        with:
          path: ~/.vagrant.d/boxes
          key: ${{ steps.vm-host.outputs.box-cache-key }}
      - name: chore fixtures
        run: chore fixtures
      - name: chore vm:status (the VM is down again)
        run: '! chore vm:status'
      - uses: actions/upload-artifact@v4
        with:
          name: fixtures
          path: test-disks/*.img
          if-no-files-found: error
          retention-days: 7

  test:
    name: test (x86_64, oracles in the VM)
    needs: fixtures
    runs-on: ubuntu-24.04
    timeout-minutes: 90
    steps:
      - uses: actions/checkout@v4
      - name: Install chore
        run: scripts/ci-install-chore.sh
      - name: chore siblings
        run: chore siblings
      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable
        with:
          components: rustfmt, clippy
      - name: Cache cargo
        uses: actions/cache@v4
        with:
          path: |
            ~/.cargo/registry
            ~/.cargo/git
            target
          key: ${{ runner.os }}-x86_64-cargo-${{ hashFiles('**/Cargo.lock') }}
          restore-keys: ${{ runner.os }}-x86_64-cargo-
      - name: KVM, QEMU and Vagrant
        id: vm-host
        run: ../fs-linux-test-harness/scripts/ci-setup-linux.sh
      - name: Cache the Vagrant box
        uses: actions/cache@v4
        with:
          path: ~/.vagrant.d/boxes
          key: ${{ steps.vm-host.outputs.box-cache-key }}
      - name: chore tools
        run: chore tools
      - uses: actions/download-artifact@v4
        with:
          name: fixtures
          path: test-disks
      # THE EVIDENCE, NOT THE CLAIM. e2fsprogs cannot be removed from an
      # Ubuntu runner — it is essential — so instead every one of its
      # programs is replaced with a stub that fails loudly. Nothing this
      # job runs may use them: the tools belong to the guest, and a test
      # that reached for one here would turn the run red with a message
      # saying so, rather than quietly passing on the wrong version.
      - name: Make the runner's own e2fsprogs unusable
        run: |
          set -eu
          for tool in debugfs dumpe2fs e2fsck fsck.ext4 mke2fs mkfs.ext4 tune2fs resize2fs; do
            path="$(command -v "$tool" 2>/dev/null || true)"
            [ -n "$path" ] || continue
            sudo mv "$path" "$path.host-copy"
            printf '#!/bin/sh\necho "::error::%s ran on the runner; the oracle tools belong in the VM" >&2\nexit 97\n' \
              "$tool" | sudo tee "$path" >/dev/null
            sudo chmod +x "$path"
            echo "poisoned $path"
          done
      - name: chore lint
        run: chore lint
      - name: chore test
        id: tier
        run: chore test
      - name: Keep the tier logs
        # A quiet tier writes its detail to tmp/logs/<tier>.log and prints a
        # verdict; without this the detail dies with the runner and the only
        # record left is the one line the terminal got. `if: always()` because
        # the run worth reading is the one that failed; not before the tier
        # ran, though, or there is no log and this step's red hides the real
        # one (#306).
        if: always() && steps.tier.outcome != 'skipped'
        uses: actions/upload-artifact@v4
        with:
          name: tier-logs-x86_64
          path: tmp/logs/*.log
          if-no-files-found: error
      - name: chore vm:status (the VM is down again)
        run: '! chore vm:status'

  test-arm64:
    name: test (aarch64, no KVM on this runner)
    needs: fixtures
    runs-on: ubuntu-24.04-arm
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@v4
      - name: Install chore
        run: scripts/ci-install-chore.sh
      - name: chore siblings
        run: chore siblings
      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable
        with:
          components: rustfmt, clippy
      - name: Cache cargo
        uses: actions/cache@v4
        with:
          path: |
            ~/.cargo/registry
            ~/.cargo/git
            target
          key: ${{ runner.os }}-aarch64-cargo-${{ hashFiles('**/Cargo.lock') }}
          restore-keys: ${{ runner.os }}-aarch64-cargo-
      - uses: actions/download-artifact@v4
        with:
          name: fixtures
          path: test-disks
      - name: chore lint
        run: chore lint
      - name: chore test:unit
        id: tier
        run: chore test:unit
      # Everything that reads a fixture but needs no VM. The oracle and
      # kernel tiers cannot run here — GitHub's arm64 runners have no
      # /dev/kvm — and they are not architecture-specific: they read the
      # same bytes the x86_64 job's guest reads.
      - name: chore test:images
        run: chore test:images
      - name: Keep the tier logs
        # A quiet tier writes its detail to tmp/logs/<tier>.log and prints a
        # verdict; without this the detail dies with the runner and the only
        # record left is the one line the terminal got. `if: always()` because
        # the run worth reading is the one that failed; not before the tier
        # ran, though, or there is no log and this step's red hides the real
        # one (#306).
        if: always() && steps.tier.outcome != 'skipped'
        uses: actions/upload-artifact@v4
        with:
          name: tier-logs-aarch64
          path: tmp/logs/*.log
          if-no-files-found: error

  suite-in-vm:
    name: suite in the guest (the macOS path)
    needs: fixtures
    runs-on: ubuntu-24.04
    timeout-minutes: 120
    steps:
      - uses: actions/checkout@v4
      - name: Install chore
        run: scripts/ci-install-chore.sh
      - name: chore siblings
        run: chore siblings
      - name: KVM, QEMU and Vagrant
        id: vm-host
        run: ../fs-linux-test-harness/scripts/ci-setup-linux.sh
      - name: Cache the Vagrant box
        uses: actions/cache@v4
        with:
          path: ~/.vagrant.d/boxes
          key: ${{ steps.vm-host.outputs.box-cache-key }}
      - uses: actions/download-artifact@v4
        with:
          name: fixtures
          path: test-disks
      # No Rust on the runner: the toolchain that matters is the one the
      # guest installs from rust-toolchain.toml. That is the point of the
      # job — on a Mac there is no usable host toolchain for these tests
      # either.
      - name: chore test:vm
        id: tier
        run: chore test:vm
      - name: Keep the tier logs
        # A quiet tier writes its detail to tmp/logs/<tier>.log and prints a
        # verdict; without this the detail dies with the runner and the only
        # record left is the one line the terminal got. `if: always()` because
        # the run worth reading is the one that failed; not before the tier
        # ran, though, or there is no log and this step's red hides the real
        # one (#306).
        if: always() && steps.tier.outcome != 'skipped'
        uses: actions/upload-artifact@v4
        with:
          name: tier-logs-suite-in-vm
          path: tmp/logs/*.log
          if-no-files-found: error
      - name: chore vm:status (the VM is down again)
        run: '! chore vm:status'

  wasm:
    name: wasm32 (browser build, tests under Node)
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4
      - name: Install chore
        run: scripts/ci-install-chore.sh
      - name: chore siblings
        run: chore siblings
      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable
      - name: Install Node
        uses: actions/setup-node@v4
        with:
          node-version: '22'
      - name: Cache cargo
        uses: actions/cache@v4
        with:
          path: |
            ~/.cargo/registry
            ~/.cargo/git
            target
          key: ${{ runner.os }}-wasm-cargo-${{ hashFiles('**/Cargo.lock') }}
          restore-keys: ${{ runner.os }}-wasm-cargo-
      - name: chore tools:wasm
        # The wasm32 target, and wasm-bindgen-test-runner at the exact
        # wasm-bindgen version Cargo.lock resolved.
        run: chore tools:wasm
      - name: chore test:wasm
        id: tier
        run: chore test:wasm
      - name: Keep the tier logs
        if: always() && steps.tier.outcome != 'skipped'
        uses: actions/upload-artifact@v4
        with:
          name: tier-logs-wasm
          path: tmp/logs/*.log
          if-no-files-found: error

  semver:
    # `chore check:semver`: this tree's public API against the newest
    # version on crates.io, refusing a break the version in Cargo.toml does
    # not declare (#120). No fixtures, no VM -- only the registry.
    name: semver (public API against crates.io)
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    env:
      # The version scripts/semver-check.sh expects. A prebuilt binary,
      # checksum-verified by the action, rather than a ten-minute build.
      CARGO_SEMVER_CHECKS_VERSION: "0.50.0"
      # A failing tier prints only its verdict by default. Here the tail IS
      # the answer -- which items broke -- so it is printed in full.
      OUTPUT_BUDGET_FAIL_TAIL: "200"
    steps:
      - uses: actions/checkout@v4
      - name: Install chore
        run: scripts/ci-install-chore.sh
      - name: chore siblings
        run: chore siblings
      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable
      - name: Install cargo-semver-checks
        uses: taiki-e/install-action@v2
        with:
          tool: cargo-semver-checks@${{ env.CARGO_SEMVER_CHECKS_VERSION }}
      - name: Cache cargo
        uses: actions/cache@v4
        with:
          path: |
            ~/.cargo/registry
            ~/.cargo/git
            target
          key: ${{ runner.os }}-semver-cargo-${{ hashFiles('**/Cargo.lock') }}
          restore-keys: ${{ runner.os }}-semver-cargo-
      - name: chore check:semver
        id: tier
        run: chore check:semver
      - name: Keep the tier logs
        # Not before the tier ran: there is no log then, and this step's red
        # would hide the real one (#306).
        if: always() && steps.tier.outcome != 'skipped'
        uses: actions/upload-artifact@v4
        with:
          name: tier-logs-semver
          path: tmp/logs/*.log
          if-no-files-found: error

  msrv:
    name: msrv (Cargo.toml rust-version)
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - name: Install chore
        run: scripts/ci-install-chore.sh
      - name: chore siblings
        run: chore siblings
      - name: Cache cargo
        uses: actions/cache@v4
        with:
          path: |
            ~/.cargo/registry
            ~/.cargo/git
            target/msrv
          key: ${{ runner.os }}-msrv-cargo-${{ hashFiles('**/Cargo.lock', 'Cargo.toml') }}
          restore-keys: ${{ runner.os }}-msrv-cargo-
      - name: chore check:msrv
        # The script installs the toolchain rust-version names; the runner's
        # rustup is all it needs.
        run: chore check:msrv

  cli:
    name: cli (the installed tools, on PATH)
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4
      - name: Install chore
        run: scripts/ci-install-chore.sh
      - name: chore siblings
        run: chore siblings
      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable
      - name: Cache cargo
        uses: actions/cache@v4
        with:
          path: |
            ~/.cargo/registry
            ~/.cargo/git
            target
          key: ${{ runner.os }}-cli-cargo-${{ hashFiles('**/Cargo.lock') }}
          restore-keys: ${{ runner.os }}-cli-cargo-
      - name: chore cli:install
        run: chore cli:install
      # FIRST on PATH, ahead of the runner's own /usr/sbin/mkfs.ext4 and
      # fsck.ext4 -- which doctor then reports as present and not run.
      - name: The staged tools first on PATH
        run: scripts/cli-install.sh --print-bin-dir >> "$GITHUB_PATH"
      - name: chore test:cli
        id: tier
        run: chore test:cli
      # THE RELEASE TARBALL, built here so a release is not the first time
      # it is put together: rust-fs-core's package-cli, run through
      # scripts/core.sh as release.yml's called workflow runs it, stages the
      # install prefix Cargo.toml's [package.metadata.package-cli] declares
      # from the binary cli:install built, then refuses it unless it holds
      # exactly that layout, every dotted name is a relative symlink to
      # bin/rust-fs-ext4, every name has its man page and completions,
      # CAVEATS is at most four lines, and every name answers --version as
      # this crate at Cargo.toml's version.
      - name: The release tarball has the install layout
        run: |
          set -euo pipefail
          version="$(sed -n 's/^version = "\(.*\)"$/\1/p' Cargo.toml | head -n 1)"
          mkdir -p tmp/package
          cd tmp/package
          tarball="$(bash ../../scripts/core.sh package-cli "$version" linux-x86_64 "${CARGO_TARGET_DIR:-$GITHUB_WORKSPACE/target}/release" | tail -n 1)"
          tar -tzvf "$tarball"
      - name: Keep the tier logs
        # Not before the tier ran: there is no log then, and this step's red
        # would hide the real one (#306).
        if: always() && steps.tier.outcome != 'skipped'
        uses: actions/upload-artifact@v4
        with:
          name: tier-logs-cli
          path: tmp/logs/*.log
          if-no-files-found: error

  provenance:
    name: provenance (no kernel or e2fsprogs internals named)
    runs-on: ubuntu-24.04
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v4
      - name: Install chore
        run: scripts/ci-install-chore.sh
      - name: chore check:provenance
        run: chore check:provenance

  ci-ok:
    name: ci-ok
    if: always()
    needs: [unit, fixtures, test, test-arm64, suite-in-vm, wasm, semver, msrv, cli, provenance]
    runs-on: ubuntu-latest
    steps:
      - name: Every job ran and succeeded
        env:
          NEEDS: ${{ toJSON(needs) }}
        run: |
          set -euo pipefail
          echo "$NEEDS" | jq -r 'to_entries[] | "\(.key): \(.value.result)"'
          bad="$(echo "$NEEDS" | jq -r '[to_entries[] | select(.value.result != "success") | .key] | join(", ")')"
          if [ -n "$bad" ]; then
            echo "::error::not green: $bad (failed, cancelled or skipped)"
            exit 1
          fi
          echo "all required jobs succeeded"