From 49ca27d623d335a9f1495820815fa663faaa6e20 Mon Sep 17 00:00:00 2001 From: Ruben van der Linde Date: Mon, 2 Nov 2026 12:50:58 +0100 Subject: [PATCH 1/3] docs(openspec): gate-123 sig-floor, the per-app SIG score floor Assisted-by: ClaudeCode:claude-opus-5-5 --- .../changes/gate-123-sig-floor/.openspec.yaml | 2 + openspec/changes/gate-123-sig-floor/design.md | 50 +++++++++++++ .../changes/gate-123-sig-floor/proposal.md | 24 ++++++ .../specs/gate-sig-floor/spec.md | 75 +++++++++++++++++++ openspec/changes/gate-123-sig-floor/tasks.md | 23 ++++++ 5 files changed, 174 insertions(+) create mode 100644 openspec/changes/gate-123-sig-floor/.openspec.yaml create mode 100644 openspec/changes/gate-123-sig-floor/design.md create mode 100644 openspec/changes/gate-123-sig-floor/proposal.md create mode 100644 openspec/changes/gate-123-sig-floor/specs/gate-sig-floor/spec.md create mode 100644 openspec/changes/gate-123-sig-floor/tasks.md diff --git a/openspec/changes/gate-123-sig-floor/.openspec.yaml b/openspec/changes/gate-123-sig-floor/.openspec.yaml new file mode 100644 index 00000000..a7587c5f --- /dev/null +++ b/openspec/changes/gate-123-sig-floor/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-02 diff --git a/openspec/changes/gate-123-sig-floor/design.md b/openspec/changes/gate-123-sig-floor/design.md new file mode 100644 index 00000000..08cd5f19 --- /dev/null +++ b/openspec/changes/gate-123-sig-floor/design.md @@ -0,0 +1,50 @@ +# Design: gate-123 sig-floor + +## Checks + +A check is one row of gate 122's report, named as `checks_of()` names it, per language: `unit_size >15/>30/>60`, `unit_complexity >5/>10/>25`, `unit_interfacing >2/>4/>6` (3+, 5+, 7+ parameters), `duplication`, and for PHP and Python `module_coupling >10/>20/>50` and `component_independence`. These are the checks the fleet measurement (M7, M8) counts, so a floor file and a fleet table speak the same names. Entanglement has no 4-star verdict in gate 122 and is not a check. + +The measurement is gate 122's `build_report` with the same scope: tracked files, Sigrid's default excludes, test code, Nextcloud `js/` and `l10n/`, and the app's `sigrid.yaml` excludes. The jscpd cross-check feeds no check, so the floor skips it. The sigarch extension used by the fleet scripts adds informational numbers only and is not part of any check. + +## The floor + +``` +floor = committed(.github/sig-floor.json at the merge base) ∪ met(merge base) +``` + +- Reading the file at the base means a pull request cannot lower its own floor. +- Adding the checks the base meets means a check development reaches is guarded at once, before any raise is merged. "The floor only rises" holds even while the raise pull request is open. +- On the adoption pull request the base has no file, and the head's file is the committed floor. +- On a run with no base (the drift sweep's dispatch), the floor is the file alone and every miss fails. + +## Verdict + +For each floored check the head misses: + +| at the base | head versus base | verdict | +|---|---|---| +| met | any | FAIL: this change breaks it | +| missed (only possible via the file) | worse | FAIL: it erodes a floor development already breaks | +| missed | not worse | inherited: printed, not counted | + +A check that disappears from the head (its language left the measured scope) fails, because nothing proves it is still met. A pull request that removes a check from the floor file fails as well. + +Inherited breaches exist only after an admin merge past a red gate. They do not fail unrelated pull requests, in line with the inherited-debt rule; development fixes them forward. + +## Raising the floor + +The org ruleset requires a pull request with review on development, so a workflow cannot commit to it. After a push to development the gate writes `sig-floor.proposed.json` when the head meets checks the file does not list and nothing failed. The `sig-floor-raise` job opens `bot/sig-floor-` with that file as the only change and closes older raise pull requests. + +The job declares no `permissions:` and inherits the caller's grant. A caller caps the permissions a called job may declare, and a job that asks for more makes the whole call fail to start. humaniq grants only contents and actions, so there the job pushes the branch and warns that it cannot open the pull request. + +A pull request opened with `GITHUB_TOKEN` starts no workflow, so the raise carries no checks and an admin merges it. Nothing is lost while it waits, because the measured base already guards the new checks. + +## Speed + +lizard is the slow part (about 20 s for opencatalogi's 467 files on a loaded machine). Units are cached in `sig-units.json`, keyed by lizard version, extension, language and content. The base and the head share almost every file, so the base costs only the files the change touched. `actions/cache` restores the newest cache of the repository; only pushes save one, so pull requests read development's cache and add nothing to the cache store. The pinned lizard and jscpd install into the same cached directory. + +## Output + +- `[gate-123] sig-floor: PASS: N floored check(s) held; ...` or `FAIL: N floored check(s) lost ...`, with one line per lost check. +- `sig-floor.md`: a table of every check at base and head, its 4-star limit, whether it is floored, and its 5-star verdict. The workflow appends it to the step summary. +- `sig-floor.json`: the same as data. diff --git a/openspec/changes/gate-123-sig-floor/proposal.md b/openspec/changes/gate-123-sig-floor/proposal.md new file mode 100644 index 00000000..43fe4aa7 --- /dev/null +++ b/openspec/changes/gate-123-sig-floor/proposal.md @@ -0,0 +1,24 @@ +--- +kind: code +--- + +## Why + +Gate 122 (sig-maintainability) judges single units: a unit a change adds or makes worse must stay under NLOC 60, McCabe 10 and 5 parameters. It does not see the app's whole risk profile. A change can keep every unit under those bounds and still push an app over a 4-star limit, for example by adding many 40-line units (unit size >30), by exposing more code across components (component independence), or by copying a fragment that jscpd's 30-token minimum misses. + +On 2 November 2026 Ruben decided that every SIG 4-star check an app already meets must still be met after each pull request, and that this floor only rises. Replaying today's opencatalogi development shows why: merge #2283 lowered PHP component independence from 93.9% to 93.5%, under the 93.7% limit, and no check noticed. + +## What changes + +- A new gate, **gate-123 `sig-floor`**, in `conduction/hydra-gates`, helper `scripts/lib/check_sig_floor.py`. +- A committed floor file per app, `.github/sig-floor.json`, listing the 4-star checks the app meets, under gate 122's check names. `check_sig_floor.py write .` generates it. +- On every run the gate measures the head and the merge base with gate 122's report. The floor is the committed file read at the base, plus every check the base meets. A floored check the head misses fails the gate and is named with its share and limit. +- The 5-star checks (gate 122's five-star profile, half of every 4-star limit) are reported in the step summary and never block. +- A `sig-floor-raise` job in `quality.yml` opens a pull request with the raised floor file after a push to development that meets more checks. +- A unit cache keyed by file content, restored by `actions/cache`, so a pull request re-reads only the files it changed. + +## Impact + +- Apps without a floor file: NOT APPLICABLE, nothing changes. +- The 20 fleet apps get a floor file in one small pull request each, generated from their development head. +- The hydra-gates job gains one measurement of the head and one of the merge base, without jscpd. diff --git a/openspec/changes/gate-123-sig-floor/specs/gate-sig-floor/spec.md b/openspec/changes/gate-123-sig-floor/specs/gate-sig-floor/spec.md new file mode 100644 index 00000000..3c942be2 --- /dev/null +++ b/openspec/changes/gate-123-sig-floor/specs/gate-sig-floor/spec.md @@ -0,0 +1,75 @@ +## ADDED Requirements + +### Requirement: A change keeps every floored 4-star check + +The `sig-floor` gate SHALL measure the app at the head and at the merge base with gate 122's report and SHALL fail when a check in the floor is met at the base and missed at the head. The floor SHALL be the `checks` of `.github/sig-floor.json` read at the merge base, together with every 4-star check the merge base meets. + +#### Scenario: A planted regression + +- **GIVEN** opencatalogi's floor lists `php component_independence` +- **WHEN** a pull request lowers PHP component independence from 93.9% to 93.5% +- **THEN** the gate fails +- **AND** prints `php component_independence: 93.5% < limit 93.7%; met at the base (93.9%)` + +#### Scenario: A refactor + +- **WHEN** a pull request splits a unit and every check stays met +- **THEN** the gate passes and prints how many floored checks held + +#### Scenario: A check met before the file lists it + +- **GIVEN** development meets `php unit_size >60` and the floor file does not list it +- **WHEN** a pull request breaks it +- **THEN** the gate fails + +### Requirement: The floor only rises + +A pull request SHALL NOT lower the floor. The gate SHALL read the floor file from the base and SHALL fail when the head's file lacks a check the base's file lists. After a push to development that meets checks the file does not list, the workflow SHALL offer the raised file as a pull request that changes only that file. + +#### Scenario: Removing a check from the file + +- **WHEN** a pull request deletes `php unit_size >60` from `.github/sig-floor.json` +- **THEN** the gate fails and names the removed check + +#### Scenario: Development meets one more check + +- **WHEN** a push to development meets `php unit_size >15` for the first time +- **THEN** `sig-floor.proposed.json` lists it +- **AND** the `sig-floor-raise` job opens a pull request with the raised file + +### Requirement: Inherited breaches do not fail unrelated changes + +When the base already misses a floored check, the gate SHALL report it as inherited and SHALL NOT fail, unless the change makes that check's share worse. + +#### Scenario: Development is already below its floor + +- **GIVEN** development misses the floored `php unit_size >60` +- **WHEN** a pull request adds a small unit elsewhere +- **THEN** the gate passes and prints the check as inherited +- **WHEN** a pull request makes the largest unit longer +- **THEN** the gate fails + +### Requirement: 5-star findings are reported and never block + +The gate SHALL report every 5-star check (half of each 4-star limit) the head misses in its summary and in the step summary, and SHALL NOT fail on them. + +#### Scenario: Between half the limit and the limit + +- **WHEN** 8.3% of the PHP code is in units with 3 or more parameters +- **THEN** the 4-star check passes +- **AND** the summary lists `php unit_interfacing >2` as a 5-star finding + +### Requirement: Scope and adoption + +The gate SHALL measure exactly what gate 122 measures, including the app's `sigrid.yaml` excludes. Without a floor file the gate SHALL report NOT APPLICABLE and name the `write` command. + +#### Scenario: No floor file + +- **WHEN** the app has no `.github/sig-floor.json` +- **THEN** the gate reports NOT APPLICABLE + +#### Scenario: An excluded directory + +- **GIVEN** `sigrid.yaml` excludes `lib/Generated/` +- **WHEN** a pull request adds a 74-line unit there +- **THEN** the gate passes diff --git a/openspec/changes/gate-123-sig-floor/tasks.md b/openspec/changes/gate-123-sig-floor/tasks.md new file mode 100644 index 00000000..759000d4 --- /dev/null +++ b/openspec/changes/gate-123-sig-floor/tasks.md @@ -0,0 +1,23 @@ +# Tasks: gate-123 sig-floor + +## 1. Helper + +- [x] 1.1 `hydra-gates/scripts/lib/check_sig_floor.py` with `check` and `write`, reusing gate 122's `build_report`, scope and check names +- [x] 1.2 `build_report` takes an optional unit reader and runs without jscpd +- [x] 1.3 Content-keyed unit cache (`--cache`) +- [x] 1.4 5-star rows in the summary, never blocking + +## 2. Tests + +- [x] 2.1 `test_check_sig_floor.py`: write, planted regression, refactor, base-met guard, inherited breach, lowered file, floor read from the base, no file, unrelated base, sigrid.yaml, 5-star, raise proposal, cache +- [x] 2.2 `test_gate123_sig_floor_scope.sh` through the real runner, registered in `COVERED-ELSEWHERE.md` + +## 3. Wiring + +- [x] 3.1 Gate 123 in `run-hydra-gates.sh` +- [x] 3.2 `quality.yml`: restore and save the measuring cache, publish `sig-floor.md` on every run, `sig-floor-raise` job +- [x] 3.3 Allowlist `sig-floor-raise` in the two shared-workflow guards (it renders no verdict) + +## 4. Adoption + +- [ ] 4.1 One pull request per fleet app with `.github/sig-floor.json` from its development head, together with `hydra-gates-sig-blocking: true` From 773394fd7a5eaba1e3d8f4b5f6832e839e9a25f2 Mon Sep 17 00:00:00 2001 From: Ruben van der Linde Date: Mon, 2 Nov 2026 12:50:58 +0100 Subject: [PATCH 2/3] feat(hydra-gates): gate 123 keeps every met SIG 4-star check met, and reports 5-star check_sig_floor.py measures the head and the merge base with gate 122's report and fails when a check in the floor is lost. The floor is .github/sig-floor.json read at the base plus every check the base meets, so it only rises. 5-star misses go to the step summary and never block. Units are cached by content; a sig-floor-raise job offers the raised floor as a pull request after a push to development. Assisted-by: ClaudeCode:claude-opus-5-5 --- .github/workflows/quality.yml | 118 ++++- hydra-gates/scripts/lib/check_sig_floor.py | 422 ++++++++++++++++++ .../scripts/lib/check_sig_maintainability.py | 13 +- .../scripts/lib/test_check_sig_floor.py | 313 +++++++++++++ .../lib/test_gate123_sig_floor_scope.sh | 137 ++++++ hydra-gates/scripts/run-hydra-gates.sh | 73 +++ .../gate-acceptance/COVERED-ELSEWHERE.md | 1 + .../assert-no-producer-deletes-a-verdict.py | 10 +- .../assert-quality-report-gates-every-leg.py | 5 + 9 files changed, 1084 insertions(+), 8 deletions(-) create mode 100644 hydra-gates/scripts/lib/check_sig_floor.py create mode 100644 hydra-gates/scripts/lib/test_check_sig_floor.py create mode 100755 hydra-gates/scripts/lib/test_gate123_sig_floor_scope.sh diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml index ba941c20..0ede1118 100644 --- a/.github/workflows/quality.yml +++ b/.github/workflows/quality.yml @@ -8388,6 +8388,20 @@ jobs: # `--full`. It therefore needs none of the capability probing that # `--axe-enabled` and `--require-full-coverage` require, whose parsers # would otherwise swallow an unknown flag as the app directory. + # Gates 122 and 123 measure with pinned lizard and jscpd, installed into + # this tool cache, and gate 123 keeps every file's units keyed by content + # (sig-units.json). A restored cache means a PR re-reads only the files + # it changed. The key moves on every run, so the newest cache of the repo + # is restored. Only a push saves one (step "Save the SIG measuring + # cache"), so pull requests read development's cache and add none. + - name: Restore the SIG measuring cache + uses: actions/cache/restore@v4 + with: + path: ${{ runner.temp }}/hydra-sig-cache + key: hydra-sig-${{ github.repository }}-${{ github.run_id }}-${{ github.run_attempt }} + restore-keys: | + hydra-sig-${{ github.repository }}- + - name: Resolve the diff base and the scope id: base env: @@ -8539,6 +8553,8 @@ jobs: # ratcheting; the step after the gates publishes it. HYDRA_GATE_SIG_MAINTAINABILITY_BLOCKING: ${{ inputs.hydra-gates-sig-blocking && '1' || '0' }} HYDRA_GATE_SIG_REPORT_DIR: ${{ runner.temp }}/sig-profile + HYDRA_GATE_TOOLS_DIR: ${{ runner.temp }}/hydra-sig-cache/tools + HYDRA_GATE_SIG_CACHE: ${{ runner.temp }}/hydra-sig-cache/sig-units.json # Gate 109: the apps this caller's CI installs (both lists, as two # JSON arrays). Passed even when both are `[]`, so "installs nothing" # and "was not told" stay different answers. @@ -8663,13 +8679,32 @@ jobs: else echo "No SIG profile was written by this run. Read the [gate-122] line in the gate output for why (not applicable, or a tool that could not run)." | tee -a "$GITHUB_STEP_SUMMARY" fi + - name: Publish the SIG score floor + # Every run of an app with a .github/sig-floor.json: the 4-star checks + # at the base and the head, which of them are floored, and the 5-star + # findings, which are reported and never block (gate 123). + if: ${{ always() }} + run: | + FLOOR="${RUNNER_TEMP}/sig-profile/sig-floor.md" + if [ -s "${FLOOR}" ]; then + cat "${FLOOR}" >> "$GITHUB_STEP_SUMMARY" + fi - name: Upload the SIG maintainability profile - if: ${{ always() && steps.base.outputs.scope == 'full' }} + # The full-scope profile, and gate 123's floor files on every run. + # sig-floor.proposed.json, when present, is what the floor-raise job + # below offers as a pull request. + if: ${{ always() }} uses: actions/upload-artifact@v4 with: name: sig-profile path: ${{ runner.temp }}/sig-profile/ if-no-files-found: ignore + - name: Save the SIG measuring cache + if: ${{ always() && github.event_name != 'pull_request' }} + uses: actions/cache/save@v4 + with: + path: ${{ runner.temp }}/hydra-sig-cache + key: hydra-sig-${{ github.repository }}-${{ github.run_id }}-${{ github.run_attempt }} - name: Record result if: always() run: | @@ -8682,6 +8717,87 @@ jobs: name: result-hydra-gates path: quality-results/ + # ── gate-123's floor, raised after a push to development ──────────────── + # + # When development meets 4-star checks its .github/sig-floor.json does not + # list, the hydra-gates job writes the raised floor as + # sig-floor.proposed.json. This job offers it as a pull request that changes + # only that file. Pushing to development itself is refused by the org + # ruleset (pull request and review required), so a pull request is the only + # route. A pull request opened with GITHUB_TOKEN starts no workflow, so it + # carries no checks and is merged by an admin. + # + # The floor is safe while that pull request is open: gate 123 also guards + # every check the merge base measures as met, so a raise that waits loses + # nothing. + # + # Deliberately NO `permissions:` block. A caller caps what a called job may + # declare, and a job that declares more than the cap makes the whole call + # fail to start. This job inherits the caller's grant instead: with + # contents and pull-requests write it opens the pull request, without them + # it says so in a warning and the proposed file stays in the sig-profile + # artifact. + sig-floor-raise: + needs: [hydra-gates] + if: ${{ !cancelled() && needs.hydra-gates.result == 'success' && github.event_name == 'push' && github.ref == 'refs/heads/development' }} + runs-on: ubuntu-latest + name: "SIG floor raise" + timeout-minutes: 5 + steps: + - name: Download the proposed floor + uses: actions/download-artifact@v4 + with: + name: sig-profile + path: ${{ runner.temp }}/sig-profile + continue-on-error: true + - name: Is there a raise? + id: raise + run: | + if [ -s "${RUNNER_TEMP}/sig-profile/sig-floor.proposed.json" ]; then + echo "raise=1" >> "$GITHUB_OUTPUT" + jq -r '"Proposed floor: \(.checks | length) checks."' "${RUNNER_TEMP}/sig-profile/sig-floor.proposed.json" + else + echo "raise=0" >> "$GITHUB_OUTPUT" + echo "development meets no 4-star check beyond its committed floor." + fi + - name: Checkout app + if: ${{ steps.raise.outputs.raise == '1' }} + uses: actions/checkout@v4 + - name: Open the floor-raise pull request + if: ${{ steps.raise.outputs.raise == '1' }} + env: + GH_TOKEN: ${{ github.token }} + SHA: ${{ github.sha }} + run: | + set -u + BRANCH="bot/sig-floor-${SHA:0:12}" + cp "${RUNNER_TEMP}/sig-profile/sig-floor.proposed.json" .github/sig-floor.json + if git diff --quiet -- .github/sig-floor.json; then + echo "The committed floor already equals the proposal." + exit 0 + fi + ADDED=$(jq -r --slurpfile old <(git show HEAD:.github/sig-floor.json) \ + '[.checks[] | select(. as $c | $old[0].checks | index($c) | not)] | join(", ")' .github/sig-floor.json) + git config user.name "github-actions[bot]" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git switch -c "${BRANCH}" + git add .github/sig-floor.json + git commit -q -m "chore(sig): raise the SIG score floor" -m "development now meets: ${ADDED}." + if ! git push -q origin "${BRANCH}"; then + echo "::warning::Could not push ${BRANCH}: the caller does not grant contents: write to this job. The raised floor is in the sig-profile artifact as sig-floor.proposed.json." + exit 0 + fi + BODY="development at ${SHA} meets SIG 4-star checks that .github/sig-floor.json does not list yet: ${ADDED}. This pull request adds them to the floor (gate 123), so a later change cannot lose them. It changes only that file." + if ! URL=$(gh pr create --base development --head "${BRANCH}" --title "chore(sig): raise the SIG score floor" --body "${BODY}"); then + echo "::warning::Pushed ${BRANCH}, but could not open a pull request: the caller does not grant pull-requests: write to this job. Open it by hand from that branch." + exit 0 + fi + echo "Opened ${URL}" + for n in $(gh pr list --state open --limit 100 --json number,headRefName \ + --jq ".[] | select(.headRefName | startswith(\"bot/sig-floor-\")) | select(.headRefName != \"${BRANCH}\") | .number"); do + gh pr close "${n}" --delete-branch --comment "Superseded by ${URL}." || true + done + # ── gate-33, the one gate that needs a browser ────────────────────────── # # Split out of `hydra-gates` on 2026-09-12 so the other gates stop waiting diff --git a/hydra-gates/scripts/lib/check_sig_floor.py b/hydra-gates/scripts/lib/check_sig_floor.py new file mode 100644 index 00000000..104c243f --- /dev/null +++ b/hydra-gates/scripts/lib/check_sig_floor.py @@ -0,0 +1,422 @@ +#!/usr/bin/env python3 +# SPDX-FileCopyrightText: 2026 Conduction +# SPDX-License-Identifier: EUPL-1.2 +"""gate-123 helper: the SIG score floor, checked on every change. + +Gate 122 ratchets single units. This gate guards the app's whole risk profile: +every SIG 4-star check the app meets must still be met after the change, and +the set of guarded checks only grows. + +A CHECK is one row of gate 122's report, named as `checks_of()` names it: +`php unit_size >30`, `vue unit_complexity >10`, `php duplication`, +`php module_coupling >20`, `php component_independence` and so on. The +measurement is gate 122's report (lizard 1.24.3, Sigrid's default excludes, +the app's sigrid.yaml excludes, SIG's 6-line window duplication). The jscpd +cross-check is not needed for any check, so it does not run here. + +THE FLOOR +--------- +`.github/sig-floor.json` in the app lists the checks the app has committed to. +`write` generates it from the current tree. The floor that judges a change is + + the committed floor AT THE BASE ∪ every check met at the merge base + +so a change can neither lower its own floor (the file is read from the base) +nor lose a check development already meets, even before the file is raised. + +VERDICT, per floored check that the head misses + met at the base NEW: the change breaks it -> FAIL + missed at the base, head worse NEW: it erodes a broken floor -> FAIL + missed at the base, head not worse INHERITED: development must fix + forward; reported, not counted +A change that removes a check from the committed floor file fails as well. + +The 5-star checks (half of every 4-star limit, gate 122's five-star profile) +are reported next to the 4-star ones and never block. + +When the head meets checks the committed floor does not list, `--proposed` +receives the raised floor file, for the workflow to offer as a pull request. + +UNIT CACHE +---------- +lizard is the slow part. `--cache FILE` keeps each file's units keyed by +(lizard version, extension, content), so a run re-reads only the files whose +content it has not seen. The base and the head share almost every file. + +Usage: + check_sig_floor.py check [--base-ref REF] [--floor PATH] + [--cache FILE] [--md FILE] [--json FILE] [--proposed FILE] + check_sig_floor.py write [--floor PATH] [--cache FILE] + +Output ends in one of + [gate-123] sig-floor: PASS: ... + [gate-123] sig-floor: FAIL: N floored check(s) ... + [gate-123] sig-floor: wrote ... +Exit status: 0 pass (or written), 1 a floored check is lost, 3 the base does not +resolve, 4 no floor file, 5 a pinned tool is unavailable. A traceback is exit 1 +with no summary line, which the runner reports as WIRING, never as a finding. +""" +import argparse +import hashlib +import json +import os +import shutil +import subprocess +import sys +import tempfile + +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +import check_sig_maintainability as sig # noqa: E402 + +GATE = "[gate-123] sig-floor" +FLOOR_PATH = ".github/sig-floor.json" +SCHEMA = 1 + + +# -------------------------------------------------------------------------- +# measuring +# -------------------------------------------------------------------------- + +class CachedUnitReader(sig.UnitReader): + """gate 122's UnitReader with a content-keyed cache. A file lizard did not + finish in time is not cached: that depends on the machine, not the file.""" + + def __init__(self, lizard, cache): + super().__init__(lizard) + self.cache = cache + self.used = set() + self.hits = self.misses = 0 + + @staticmethod + def key(rel, lang, code): + h = hashlib.sha256() + h.update(f"{sig.LIZARD_VERSION}\0{os.path.splitext(rel)[1].lower()}\0{lang}\0".encode()) + h.update(code.encode("utf-8", errors="replace")) + return h.hexdigest() + + def units(self, rel, lang, code): + k = self.key(rel, lang, code) + self.used.add(k) + hit = self.cache.get(k) + if hit is not None: + self.hits += 1 + if hit.get("skipped"): + self.skipped.append({"file": rel, "reason": hit["skipped"]}) + return [] + return [dict(u, file=rel, lang=lang) for u in hit["units"]] + self.misses += 1 + before = len(self.skipped) + out = super().units(rel, lang, code) + if len(self.skipped) > before: + reason = self.skipped[-1]["reason"] + if "did not finish" not in reason: + self.cache[k] = {"skipped": reason} + return out + self.cache[k] = {"units": [{f: u[f] for f in u if f not in ("file", "lang")} for u in out]} + return out + + +def load_cache(path): + if not path or not os.path.isfile(path): + return {} + try: + with open(path) as fh: + data = json.load(fh) + except (OSError, ValueError): + return {} + if data.get("lizard") != sig.LIZARD_VERSION: + return {} + return data.get("files", {}) + + +def save_cache(path, cache, used): + if not path: + return + os.makedirs(os.path.dirname(os.path.abspath(path)), exist_ok=True) + with open(path, "w") as fh: + json.dump({"lizard": sig.LIZARD_VERSION, "files": {k: v for k, v in cache.items() if k in used}}, fh) + + +def measure(app, lizard, reader): + """gate 122's four-star report of `app`, without the jscpd cross-check.""" + return sig.build_report(app, lizard, None, "four-star", reader=reader) + + +def check_rows(report, profile_name): + """{label: {"share", "limit", "ok", "higher_is_better"}} for every check of + the report, judged against `profile_name`. Labels are gate 122's.""" + prof = sig.PROFILES[profile_name] + rows = {} + for lang, d in report["languages"].items(): + for prop in ("unit_size", "unit_complexity", "unit_interfacing"): + for i, row in enumerate(d[prop]): + cap = prof["limits"][prop][i][1] + rows[f"{lang} {prop} >{row['above']}"] = { + "share": row["share"], "limit": cap, "ok": row["share"] <= cap, "higher_is_better": False} + dup = d.get("duplication") + if dup: + rows[f"{lang} duplication"] = {"share": dup["share"], "limit": prof["duplication"], + "ok": dup["share"] <= prof["duplication"], "higher_is_better": False} + for lang, s in report.get("structure", {}).items(): + if not s: + continue + for i, row in enumerate(s["module_coupling"]): + cap = prof["limits"]["module_coupling"][i][1] + rows[f"{lang} module_coupling >{row['above']}"] = { + "share": row["share"], "limit": cap, "ok": row["share"] <= cap, "higher_is_better": False} + h = s["component_independence"]["hidden_share"] + rows[f"{lang} component_independence"] = { + "share": h, "limit": prof["independence_min"], "ok": h >= prof["independence_min"], + "higher_is_better": True} + return rows + + +def worse(row_head, row_base): + if row_base is None: + return True + if row_head["higher_is_better"]: + return row_head["share"] < row_base["share"] + return row_head["share"] > row_base["share"] + + +# -------------------------------------------------------------------------- +# git +# -------------------------------------------------------------------------- + +def git(app, *args): + p = subprocess.run(["git", "-c", "safe.directory=*", *args], cwd=app, + capture_output=True, text=True, errors="replace") + return p.returncode, p.stdout + + +def floor_at(app, ref, path): + """The committed floor (a list of labels) at `ref`, or None when absent.""" + rc, out = git(app, "show", f"{ref}:{path}") + if rc != 0: + return None + return parse_floor(out, f"{ref}:{path}") + + +def parse_floor(text, where): + data = json.loads(text) + checks = data.get("checks") + if not isinstance(checks, list) or not all(isinstance(c, str) for c in checks): + raise ValueError(f"{where}: `checks` must be a list of check names") + return checks + + +def floor_document(app, labels): + head = (git(app, "rev-parse", "HEAD")[1] or "").strip() or None + return { + "about": "SIG 4-star checks this app meets and must keep meeting (gate 123, sig-floor). " + "Generated by check_sig_floor.py write; raised by the workflow, never lowered by hand.", + "schema": SCHEMA, + "profile": "four-star", + "tools": {"lizard": sig.LIZARD_VERSION}, + "measured_at": head, + "checks": sorted(labels), + } + + +def measure_base(app, mb, lizard, reader): + """Measure the tree at commit `mb` in a temporary worktree.""" + tmp = tempfile.mkdtemp(prefix="sig-floor-base-") + wt = os.path.join(tmp, os.path.basename(os.path.abspath(app))) + try: + rc, _ = git(app, "worktree", "add", "--quiet", "--detach", wt, mb) + if rc != 0: + return None + return measure(wt, lizard, reader) + finally: + git(app, "worktree", "remove", "--force", wt) + shutil.rmtree(tmp, ignore_errors=True) + git(app, "worktree", "prune") + + +# -------------------------------------------------------------------------- +# verdict +# -------------------------------------------------------------------------- + +def judge(floor, head4, base4): + """(new, inherited) breaches of `floor`: lists of (label, why).""" + new, inherited = [], [] + for label in sorted(floor): + h = head4.get(label) + b = base4.get(label) if base4 is not None else None + if h is None: + new.append((label, "no longer measured (its language or module structure left the measured scope)")) + continue + if h["ok"]: + continue + cmp = "<" if h["higher_is_better"] else ">" + why = f"{sig.pct(h['share'])} {cmp} limit {sig.pct(h['limit'])}" + if b is not None and b["ok"]: + new.append((label, f"{why}; met at the base ({sig.pct(b['share'])})")) + elif base4 is None: + new.append((label, why)) + elif worse(h, b): + new.append((label, f"{why}; already missed at the base ({sig.pct(b['share'])}) and this change makes it worse")) + else: + inherited.append((label, f"{why}; already missed at the base ({sig.pct(b['share']) if b else 'n/a'})")) + return new, inherited + + +def markdown(app_name, floor, head4, head5, base4, new, inherited, lowered, proposed): + def cell(r): + return "n/a" if r is None else sig.pct(r["share"]) + ("" if r["ok"] else " ✗") + + out = [f"## SIG score floor: {app_name}", "", + "Every 4-star check in the floor must stay met. 5-star (half of each 4-star limit) " + "is reported only and never blocks. ✗ marks a miss.", "", + "| check | base | head | 4-star limit | floored | 5-star |", "|---|---|---|---|---|---|"] + for label in sorted(set(head4) | set(floor) | set(base4 or {})): + h, b, h5 = head4.get(label), (base4 or {}).get(label), head5.get(label) + lim = h or b + lim = (">= " if lim["higher_is_better"] else "<= ") + sig.pct(lim["limit"]) if lim else "n/a" + out.append(f"| {label} | {cell(b) if base4 is not None else '-'} | {cell(h)} | {lim} " + f"| {'yes' if label in floor else ''} | {cell(h5)} |") + met4 = sum(1 for r in head4.values() if r["ok"]) + met5 = sum(1 for r in head5.values() if r["ok"]) + out += ["", f"Head: {met4} of {len(head4)} 4-star checks met, {met5} of {len(head5)} 5-star checks met; " + f"{len(floor)} check(s) floored."] + if new: + out += ["", "**Floor broken by this change:**"] + [f"- {lbl}: {why}" for lbl, why in new] + if lowered: + out += ["", "**This change removes checks from the committed floor:** " + ", ".join(lowered)] + if inherited: + out += ["", "Inherited (development already misses these; fix forward):"] + \ + [f"- {lbl}: {why}" for lbl, why in inherited] + five_missed = sorted(lbl for lbl, r in head5.items() if not r["ok"]) + if five_missed: + out += ["", f"5-star findings (not blocking): {len(five_missed)} check(s) above half the 4-star limit: " + + ", ".join(five_missed)] + if proposed: + out += ["", "The head meets checks the committed floor does not list yet: " + ", ".join(proposed) + + ". The floor is raised after this reaches development."] + return "\n".join(out) + "\n" + + +# -------------------------------------------------------------------------- +# commands +# -------------------------------------------------------------------------- + +def cmd_write(args, lizard): + cache = load_cache(args.cache) + reader = CachedUnitReader(lizard, cache) + report = measure(args.app, lizard, reader) + save_cache(args.cache, cache, reader.used) + if not report["files"]: + print(f"{GATE}: no measured source file in this repository, so there is no floor to write") + return 4 + rows = check_rows(report, "four-star") + met = [lbl for lbl, r in rows.items() if r["ok"]] + path = os.path.join(args.app, args.floor) + os.makedirs(os.path.dirname(path), exist_ok=True) + with open(path, "w") as fh: + json.dump(floor_document(args.app, met), fh, indent=1) + fh.write("\n") + print(f"{GATE}: wrote {args.floor}: {len(met)} of {len(rows)} 4-star checks met and floored") + return 0 + + +def cmd_check(args, lizard): + app = args.app + mb = None + if args.base_ref: + rc, out = git(app, "merge-base", args.base_ref, "HEAD") + if rc != 0 or not out.strip(): + print(f"{GATE}: the base '{args.base_ref}' has no merge base with HEAD, so the floor cannot be read") + return 3 + mb = out.strip() + + head_file = os.path.join(app, args.floor) + head_floor = parse_floor(sig.read_text(head_file), args.floor) if os.path.isfile(head_file) else None + base_floor = floor_at(app, mb, args.floor) if mb else None + committed = base_floor if base_floor is not None else head_floor + if committed is None: + print(f"{GATE}: this repository has no {args.floor}; generate it with " + f"`check_sig_floor.py write .` to adopt the floor") + return 4 + lowered = sorted(set(base_floor) - set(head_floor or [])) if base_floor is not None else [] + + cache = load_cache(args.cache) + reader = CachedUnitReader(lizard, cache) + head_report = measure(app, lizard, reader) + head4, head5 = check_rows(head_report, "four-star"), check_rows(head_report, "five-star") + base4 = None + if mb: + base_report = measure_base(app, mb, lizard, reader) + if base_report is None: + print(f"{GATE}: could not check out the merge base {mb[:12]} to measure it") + return 3 + base4 = check_rows(base_report, "four-star") + save_cache(args.cache, cache, reader.used) + + floor = set(committed) | ({lbl for lbl, r in base4.items() if r["ok"]} if base4 else set()) + new, inherited = judge(floor, head4, base4) + met_head = {lbl for lbl, r in head4.items() if r["ok"]} + raise_to = sorted(met_head - set(committed)) + if args.proposed and raise_to and not new and not lowered: + with open(args.proposed, "w") as fh: + json.dump(floor_document(app, set(committed) | met_head), fh, indent=1) + fh.write("\n") + + md = markdown(os.path.basename(os.path.abspath(app)), floor, head4, head5, base4, + new, inherited, lowered, raise_to) + if args.md: + with open(args.md, "w") as fh: + fh.write(md) + if args.json: + with open(args.json, "w") as fh: + json.dump({"floor": sorted(floor), "committed": sorted(committed), "head": head4, + "head_five_star": head5, "base": base4, "new": new, "inherited": inherited, + "lowered": lowered, "raise": raise_to}, fh, indent=1) + + for s in head_report["skipped_files"]: + print(f" unverified (lizard could not read it): {s['file']}: {s['reason']}") + for lbl, why in new: + print(f" {lbl}: {why}") + if lowered: + print(f" this change removes {len(lowered)} check(s) from the committed floor: {', '.join(lowered)}") + for lbl, why in inherited: + print(f" inherited, not counted: {lbl}: {why}") + five = sum(1 for r in head5.values() if not r["ok"]) + tail = (f"{len(met_head)} of {len(head4)} 4-star checks met at head; {five} 5-star finding(s), not blocking; " + f"{len(inherited)} inherited; lizard {sig.LIZARD_VERSION}, cache {reader.hits} hit(s) {reader.misses} miss(es)" + + (f"; {len(raise_to)} check(s) above the committed floor" if raise_to else "")) + if new or lowered: + print(f"{GATE}: FAIL: {len(new) + len(lowered)} floored check(s) lost " + f"({len(new)} no longer met, {len(lowered)} removed from the floor file); {tail}") + return 1 + print(f"{GATE}: PASS: {len(floor)} floored check(s) held; {tail}") + return 0 + + +def main(argv): + ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) + sub = ap.add_subparsers(dest="mode", required=True) + c = sub.add_parser("check") + c.add_argument("app") + c.add_argument("--base-ref") + c.add_argument("--floor", default=FLOOR_PATH) + c.add_argument("--cache") + c.add_argument("--md") + c.add_argument("--json") + c.add_argument("--proposed") + w = sub.add_parser("write") + w.add_argument("app") + w.add_argument("--floor", default=FLOOR_PATH) + w.add_argument("--cache") + args = ap.parse_args(argv) + args.app = os.path.abspath(args.app) + lizard, why = sig.load_lizard() + if not lizard: + print(f"{GATE}: tooling: {why}") + return 5 + if args.mode == "write": + return cmd_write(args, lizard) + return cmd_check(args, lizard) + + +if __name__ == "__main__": + sys.exit(main(sys.argv[1:])) diff --git a/hydra-gates/scripts/lib/check_sig_maintainability.py b/hydra-gates/scripts/lib/check_sig_maintainability.py index 36bc0555..40af54b7 100755 --- a/hydra-gates/scripts/lib/check_sig_maintainability.py +++ b/hydra-gates/scripts/lib/check_sig_maintainability.py @@ -795,23 +795,26 @@ def structure(app, files, deps, prof=PROFILES[DEFAULT_PROFILE]): } -def build_report(app, lizard, jscpd, profile_name=DEFAULT_PROFILE): +def build_report(app, lizard, jscpd, profile_name=DEFAULT_PROFILE, reader=None): + """The risk profile of one app. `jscpd` None skips the jscpd cross-check + (duplication_jscpd is then None); `reader` replaces the plain UnitReader, + for a caller that caches units.""" prof = PROFILES[profile_name] scope = Scope(app) files = production_files(app, scope) - reader = UnitReader(lizard) + reader = reader or UnitReader(lizard) units = [] for rel, lang in sorted(files.items()): units.extend(reader.units(rel, lang, read_text(os.path.join(app, rel)))) by_lang = collections.defaultdict(list) for u in units: by_lang[u["lang"]].append(u) - clones = run_jscpd(app, jscpd, sorted(files)) if files else [] + clones = run_jscpd(app, jscpd, sorted(files)) if files and jscpd else [] dup = duplication_profile(app, clones, files, prof["duplication"]) report = { "app": os.path.basename(os.path.abspath(app)), "head": (git(app, "rev-parse", "HEAD")[1] or "").strip() or None, - "tools": {"lizard": LIZARD_VERSION, "jscpd": JSCPD_VERSION}, + "tools": {"lizard": LIZARD_VERSION, "jscpd": JSCPD_VERSION if jscpd else None}, "profile": profile_name, "stars": prof["stars"], "limits": prof["source"], @@ -829,7 +832,7 @@ def build_report(app, lizard, jscpd, profile_name=DEFAULT_PROFILE): "unit_complexity": profile(rows, "ccn", prof["limits"]["unit_complexity"]), "unit_interfacing": profile(rows, "params", prof["limits"]["unit_interfacing"]), "duplication": dup[lang][0] if lang in dup else None, - "duplication_jscpd": dup[lang][1] if lang in dup else None, + "duplication_jscpd": dup[lang][1] if lang in dup and jscpd else None, "largest_units": worst(rows, "nloc"), "most_complex_units": worst(rows, "ccn"), "widest_units": worst(rows, "params"), diff --git a/hydra-gates/scripts/lib/test_check_sig_floor.py b/hydra-gates/scripts/lib/test_check_sig_floor.py new file mode 100644 index 00000000..2db486f2 --- /dev/null +++ b/hydra-gates/scripts/lib/test_check_sig_floor.py @@ -0,0 +1,313 @@ +#!/usr/bin/env python3 +# SPDX-FileCopyrightText: 2026 Conduction +# SPDX-License-Identifier: EUPL-1.2 +"""Tests for gate-123's checker (check_sig_floor.py), on real git histories. + + 1. WRITE: the floor lists exactly the 4-star checks gate 122's report meets, + under gate 122's own check names. + 2. CHECK, against a committed floor: + a planted regression that breaks a floored check FAILS and names it; + a refactor that keeps every check PASSES; + a check met at the merge base is guarded even when the committed file + does not list it yet; + a floored check development already misses is INHERITED while the + change does not make it worse, and FAILS when it does; + a change that removes a check from the floor file FAILS, and the floor + is read from the base, so the change cannot lower its own; + no floor file is exit 4, an unrelated base is exit 3; + sigrid.yaml excludes are honoured, as in gate 122. + 3. FIVE STAR: a share between half the limit and the limit passes and is + listed as a 5-star finding, never as a failure. + 4. RAISE: a head that meets checks the floor does not list writes the + raised floor to --proposed, and writes nothing when it fails. + 5. CACHE: a cached run reads the same units as an uncached one and reads + no file twice. + +Run: python3 scripts/lib/test_check_sig_floor.py +""" +import contextlib +import io +import json +import os +import shutil +import subprocess +import sys +import tempfile +import unittest + +HERE = os.path.dirname(os.path.abspath(__file__)) +sys.path.insert(0, HERE) +import check_sig_floor as floor # noqa: E402 +import check_sig_maintainability as sig # noqa: E402 + +LIZARD, WHY = sig.load_lizard() +if not LIZARD: + # A suite that cannot load its tools must not report green. + print(f"FAIL: pinned tools unavailable: {WHY}") + sys.exit(1) + + +def php_method(name, lines=3, tag="x"): + body = "".join(f" ${tag}{i} = {i} + strlen('{tag}{name}');\n" for i in range(lines)) + return f" public function {name}(int $p0): int\n {{\n{body} return $p0;\n }}\n" + + +def php_class(name, methods): + return f"60", met) + self.assertEqual(self.repo.floor_file()["profile"], "four-star") + + def test_check_rows_agree_with_gate_122_checks(self): + self.repo.write("lib/Service/Big.php", php_class("Big", [php_method("huge", lines=70, tag="h")])) + report = floor.measure(self.repo.dir, LIZARD, sig.UnitReader(LIZARD)) + rows = floor.check_rows(report, "four-star") + self.assertEqual({k: r["ok"] for k, r in rows.items()}, dict(sig.checks_of(report))) + + +class Check(FloorCase): + def test_a_planted_regression_fails_and_names_the_check(self): + self.repo.write("lib/Service/Big.php", php_class("Big", [php_method("huge", lines=70, tag="h")])) + rc, out = self.check() + self.assertEqual(rc, 1, out) + self.assertIn(" php unit_size >60: ", out) + self.assertIn("met at the base (0.0%)", out) + self.assertIn("[gate-123] sig-floor: FAIL: ", out) + + def test_a_refactor_that_keeps_every_check_passes(self): + methods = SMALL[:10] + [php_method("merged", lines=4, tag="mm")] + self.repo.write("lib/Service/Small.php", php_class("Small", methods)) + self.repo.write("lib/Service/Split.php", php_class("Split", [php_method("moved", lines=2, tag="mv")])) + rc, out = self.check() + self.assertEqual(rc, 0, out) + self.assertIn("[gate-123] sig-floor: PASS: ", out) + + def test_a_check_met_at_the_base_is_guarded_before_the_file_lists_it(self): + self.repo.git("checkout", "-q", "base") + self.repo.set_floor([c for c in self.repo.floor_file()["checks"] if c != "php unit_size >60"]) + self.repo.commit("floor without the check") + self.repo.git("checkout", "-q", "-B", "change") + self.repo.write("lib/Service/Big.php", php_class("Big", [php_method("huge", lines=70, tag="h")])) + rc, out = self.check() + self.assertEqual(rc, 1, out) + self.assertIn(" php unit_size >60: ", out) + + def test_a_check_development_already_misses_is_inherited_until_made_worse(self): + self.repo.git("checkout", "-q", "base") + checks = self.repo.floor_file()["checks"] + self.repo.write("lib/Service/Big.php", php_class("Big", [php_method("huge", lines=70, tag="h")])) + self.repo.commit("development broke it") + self.assertIn("php unit_size >60", checks) + + self.repo.git("checkout", "-q", "-B", "change") + self.repo.write("lib/Service/More.php", php_class("More", [php_method("tiny", lines=2, tag="t")])) + rc, out = self.check() + self.assertEqual(rc, 0, out) + self.assertIn("inherited, not counted: php unit_size >60", out) + + self.repo.write("lib/Service/Big.php", php_class("Big", [php_method("huge", lines=90, tag="h")])) + rc, out = self.check() + self.assertEqual(rc, 1, out) + self.assertIn("already missed at the base", out) + self.assertIn("makes it worse", out) + + def test_removing_a_check_from_the_floor_file_fails(self): + checks = self.repo.floor_file()["checks"] + self.repo.set_floor([c for c in checks if c != "php unit_size >60"]) + rc, out = self.check() + self.assertEqual(rc, 1, out) + self.assertIn("removes 1 check(s) from the committed floor: php unit_size >60", out) + + def test_the_floor_is_read_from_the_base_so_a_change_cannot_lower_its_own(self): + self.repo.git("checkout", "-q", "base") + checks = self.repo.floor_file()["checks"] + self.repo.write("lib/Service/Big.php", php_class("Big", [php_method("huge", lines=70, tag="h")])) + self.repo.commit("development broke it") + self.repo.git("checkout", "-q", "-B", "change") + self.repo.set_floor([c for c in checks if c != "php unit_size >60"]) + self.repo.write("lib/Service/Big.php", php_class("Big", [php_method("huge", lines=90, tag="h")])) + rc, out = self.check() + self.assertEqual(rc, 1, out) + self.assertIn(" php unit_size >60: ", out) + self.assertIn("makes it worse", out) + + def test_no_floor_file_is_exit_4(self): + self.repo.remove(floor.FLOOR_PATH) + self.repo.commit("drop") + rc, out = run("check", self.repo.dir) + self.assertEqual(rc, 4, out) + self.assertIn("check_sig_floor.py write", out) + + def test_an_unrelated_base_is_exit_3(self): + self.repo.git("checkout", "-q", "--orphan", "other") + self.repo.write("README.md", "x\n") + self.repo.commit("unrelated") + self.repo.git("checkout", "-q", "change") + rc, out = run("check", self.repo.dir, "--base-ref", "other") + self.assertEqual(rc, 3, out) + + def test_sigrid_yaml_excludes_are_honoured(self): + self.repo.write("sigrid.yaml", "exclude:\n - \".*/lib/Generated/.*\"\n") + self.repo.write("lib/Generated/Big.php", php_class("Big", [php_method("huge", lines=70, tag="h")])) + rc, out = self.check() + self.assertEqual(rc, 0, out) + + +class FiveStar(FloorCase): + def test_a_five_star_miss_is_reported_and_never_blocks(self): + # One of twelve equal units takes three parameters: 8.3% of the code, + # above the 5-star 7.5% and below the 4-star 15%. + wide = [SMALL[0].replace("(int $p0)", "(int $p0, int $q, int $r)")] + self.repo.write("lib/Service/Small.php", php_class("Small", wide + SMALL[1:])) + md = os.path.join(self.repo.dir, "..", os.path.basename(self.repo.dir) + ".md") + rc, out = self.check("--md", md) + try: + self.assertEqual(rc, 0, out) + self.assertIn("5-star finding(s), not blocking", out) + with open(md) as fh: + text = fh.read() + self.assertIn("5-star findings (not blocking)", text) + self.assertIn("php unit_interfacing >2", text.split("5-star findings (not blocking)")[1]) + finally: + if os.path.exists(md): + os.remove(md) + + +class Raise(FloorCase): + def setUp(self): + super().setUp() + self.proposed = tempfile.mktemp(suffix=".json") + + def tearDown(self): + if os.path.exists(self.proposed): + os.remove(self.proposed) + super().tearDown() + + def test_a_head_that_meets_more_checks_proposes_the_raised_floor(self): + self.repo.git("checkout", "-q", "base") + checks = self.repo.floor_file()["checks"] + self.repo.set_floor([c for c in checks if c != "php unit_size >60"]) + self.repo.commit("lower floor") + self.repo.git("checkout", "-q", "-B", "change") + self.repo.write("README.md", "docs\n") + rc, out = self.check("--proposed", self.proposed) + self.assertEqual(rc, 0, out) + self.assertIn("1 check(s) above the committed floor", out) + with open(self.proposed) as fh: + self.assertEqual(json.load(fh)["checks"], checks) + + def test_a_failing_change_proposes_nothing(self): + self.repo.git("checkout", "-q", "base") + self.repo.set_floor([c for c in self.repo.floor_file()["checks"] if c != "php unit_interfacing >6"]) + self.repo.commit("floor below what the app meets") + self.repo.git("checkout", "-q", "-B", "change") + self.repo.write("lib/Service/Big.php", php_class("Big", [php_method("huge", lines=70, tag="h")])) + rc, out = self.check("--proposed", self.proposed) + self.assertEqual(rc, 1, out) + self.assertIn("1 check(s) above the committed floor", out) + self.assertFalse(os.path.exists(self.proposed)) + + +class Cache(unittest.TestCase): + def test_a_cached_run_reads_the_same_units_and_no_file_twice(self): + repo = Repo() + try: + repo.write("lib/Service/Small.php", php_class("Small", SMALL)) + repo.write("src/a.js", "export function f(a, b, c) {\n if (a) { return b }\n return c\n}\n") + repo.commit("app") + cache = {} + first = floor.CachedUnitReader(LIZARD, cache) + r1 = floor.measure(repo.dir, LIZARD, first) + self.assertEqual((first.hits, first.misses), (0, 2)) + second = floor.CachedUnitReader(LIZARD, cache) + r2 = floor.measure(repo.dir, LIZARD, second) + self.assertEqual((second.hits, second.misses), (2, 0)) + self.assertEqual(r1["languages"], r2["languages"]) + plain = floor.measure(repo.dir, LIZARD, sig.UnitReader(LIZARD)) + self.assertEqual(plain["languages"], r2["languages"]) + + path = os.path.join(repo.dir, "..", os.path.basename(repo.dir) + "-cache.json") + floor.save_cache(path, cache, second.used) + try: + self.assertEqual(floor.load_cache(path), cache) + finally: + os.remove(path) + finally: + repo.close() + + +if __name__ == "__main__": + unittest.main(verbosity=1) diff --git a/hydra-gates/scripts/lib/test_gate123_sig_floor_scope.sh b/hydra-gates/scripts/lib/test_gate123_sig_floor_scope.sh new file mode 100755 index 00000000..a1594753 --- /dev/null +++ b/hydra-gates/scripts/lib/test_gate123_sig_floor_scope.sh @@ -0,0 +1,137 @@ +#!/usr/bin/env bash +# SPDX-FileCopyrightText: 2026 Conduction +# SPDX-License-Identifier: EUPL-1.2 +# +# gate-123 (sig-floor) through the real runner, on a real git history. +# +# ARM 1 a planted regression breaks a floored check: FAIL, naming the check +# ARM 2 a refactor that keeps every check: PASS with the census line, and +# sig-floor.md (with its 5-star line) is written to the report dir +# ARM 3 no floor file: NOT APPLICABLE +# ARM 4 the pinned tools are unavailable: SKIPPED (wiring), never PASS +# +# The rule-by-rule arms (inherited breaches, the floor read from the base, a +# lowered floor file, the raised floor, the cache) are in +# test_check_sig_floor.py. + +set -u + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)" +RUNNER="${SCRIPT_DIR}/../run-hydra-gates.sh" +HELPER="${SCRIPT_DIR}/check_sig_floor.py" + +_fail_n=0 +_ok() { printf ' ok: %s\n' "$1"; } +_bad() { _fail_n=$((_fail_n + 1)); printf ' FAIL: %s\n' "$1"; } + +WORK="$(mktemp -d "${TMPDIR:-/tmp}/gate123-scope.XXXXXXXX")" +trap 'rm -rf "${WORK}"' EXIT +APP="${WORK}/app" +mkdir -p "${APP}/appinfo" "${APP}/lib/Service" + +_method() { # -> a one-parameter PHP method with statements + local _b="" _i + for _i in $(seq 1 "$2"); do _b="${_b} \$v${_i} = ${_i} + strlen('$1');\n"; done + printf ' public function %s(int $p): int\n {\n%b return $p;\n }\n' "$1" "${_b}" +} +_class() { # + local _n="$1"; shift + printf ' "lib/Service/${_n}.php" +} + +cd "${APP}" || exit 1 +git init --quiet . +git config user.email fixture@example.invalid +git config user.name Fixture +printf '\n\n fixture\n 1.0.0\n\n' > appinfo/info.xml +_m="" +for _i in $(seq 1 12); do _m="${_m}$(_method "m${_i}" 3)"$'\n'; done +_class Small "${_m}" +git add -A && git commit --quiet -m "app" +python3 "${HELPER}" write . > /dev/null || { echo "gate-123 scope: could not write the floor"; exit 1; } +git add -A && git commit --quiet -m "floor" +git branch -M base + +_branch() { git checkout --quiet base && git checkout --quiet -b "$1"; } + +_branch planted +_class Big "$(_method huge 70)" +git add -A && git commit --quiet -m "a 74-line unit" + +_branch refactor +_class Split "$(_method moved 2)" +git add -A && git commit --quiet -m "a small new unit" + +_branch nofloor +git rm --quiet .github/sig-floor.json +git commit --quiet -m "no floor" + +_run() { # [extra runner args...] + local _b="$1"; shift + git -C "${APP}" checkout --quiet "${_b}" + mkdir -p "${WORK}/logs-${_b}" + HYDRA_GATE_LOG_DIR="${WORK}/logs-${_b}" bash "${RUNNER}" "$@" "${APP}" 2>&1 +} + +_verdict() { + printf '%s\n' "$1" | grep -E '^\[gate-123\] sig-floor: (PASS|FAIL|WARNING|SKIPPED|NOT APPLICABLE)' | head -1 +} + +echo "-- ARM 1: a planted regression: FAIL --" +_out="$(_run planted --base base)" +_v="$(_verdict "${_out}")" +case "${_v}" in + *FAIL*) _ok "a change that breaks a floored check fails" ;; + *) _bad "expected FAIL, got: ${_v:-}" ;; +esac +if printf '%s\n' "${_out}" | grep -q '^ php unit_size >60: .*met at the base'; then + _ok "the failure names the check and its base share" +else + _bad "the failure does not name php unit_size >60" +fi + +echo "-- ARM 2: a refactor that keeps every check: PASS --" +REPORTS="${WORK}/reports" +_out="$(HYDRA_GATE_SIG_REPORT_DIR="${REPORTS}" _run refactor --base base)" +_v="$(_verdict "${_out}")" +case "${_v}" in + *PASS*) _ok "a change that keeps the floor passes" ;; + *) _bad "expected PASS, got: ${_v:-}" ;; +esac +if printf '%s\n' "${_out}" | grep -q '^\[gate-123\] sig-floor: PASS: [0-9]* floored check(s) held'; then + _ok "the census line reaches the run's output" +else + _bad "no census line in the PASS output" +fi +if [ -s "${REPORTS}/sig-floor.md" ] && grep -q '^| php unit_size >60 |' "${REPORTS}/sig-floor.md" \ + && grep -q '5-star checks met' "${REPORTS}/sig-floor.md"; then + _ok "sig-floor.md, with the 5-star count, is written to HYDRA_GATE_SIG_REPORT_DIR" +else + _bad "sig-floor.md is missing or lacks the check table" +fi + +echo "-- ARM 3: no floor file: NOT APPLICABLE --" +_v="$(_verdict "$(_run nofloor)")" +case "${_v}" in + *"NOT APPLICABLE"*) _ok "a repository with no floor file is not applicable" ;; + *) _bad "expected NOT APPLICABLE, got: ${_v:-}" ;; +esac + +echo "-- ARM 4: tools unavailable: SKIPPED (wiring) --" +if python3 -c 'import lizard' > /dev/null 2>&1; then + _ok "lizard is importable outside the tool cache on this host, so this arm cannot remove it (not run)" +else + _v="$(_verdict "$(HYDRA_GATE_TOOLS_DIR="${WORK}/no-tools" HYDRA_GATE_SIG_NO_INSTALL=1 _run planted --base base)")" + case "${_v}" in + *"SKIPPED (wiring)"*) _ok "a missing pinned tool is wiring, not a verdict" ;; + *) _bad "expected SKIPPED (wiring), got: ${_v:-}" ;; + esac +fi + +echo +if [ "${_fail_n}" -eq 0 ]; then + echo "gate-123 scope: all arms passed" + exit 0 +fi +echo "gate-123 scope: ${_fail_n} arm(s) failed" +exit 1 diff --git a/hydra-gates/scripts/run-hydra-gates.sh b/hydra-gates/scripts/run-hydra-gates.sh index 62455597..5fb9d826 100755 --- a/hydra-gates/scripts/run-hydra-gates.sh +++ b/hydra-gates/scripts/run-hydra-gates.sh @@ -13687,6 +13687,79 @@ else esac fi +# --------------------------------------------------------------------------- +# gate-123: sig-floor +# +# Gate 122 ratchets single units; this gate guards the app's whole SIG risk +# profile. `.github/sig-floor.json` lists the 4-star checks the app meets +# (gate 122's check names, e.g. `php unit_size >30`). On a change, the floor is +# that file READ AT THE BASE, plus every check the merge base measures as met, +# so a change can neither lower its own floor nor lose a check development +# already meets. A floored check the head no longer meets FAILS; one that +# development already misses is inherited unless the change makes it worse. +# The 5-star checks are reported and never block. +# +# The measurement is gate 122's report (lizard 1.24.3, Sigrid's default +# excludes, the app's sigrid.yaml), measured at the head and at the merge base. +# Units are cached by file content in $HYDRA_GATE_SIG_CACHE, so the base costs +# only the files the change touched. sig-floor.md (the summary table), +# sig-floor.json and, when the head meets more than the committed floor, +# sig-floor.proposed.json are written to $HYDRA_GATE_SIG_REPORT_DIR. +# +# NOT APPLICABLE in a repository with no floor file: adopting it is one +# committed file, generated by `check_sig_floor.py write .`. +# --------------------------------------------------------------------------- +_floor_log=${HYDRA_GATE_LOG_DIR}/hydra-gate-sig-floor.log +: > "${_floor_log}" +_floor_helper="${SCRIPT_DIR}/lib/check_sig_floor.py" +_floor_report_dir="${HYDRA_GATE_SIG_REPORT_DIR:-${HYDRA_GATE_LOG_DIR}}" +if [ ! -f "${_floor_helper}" ]; then + _skip 123 "sig-floor" wiring "check_sig_floor.py not found at ${_floor_helper}, so no floor was checked by this run." +elif ! command -v python3 > /dev/null 2>&1; then + _skip 123 "sig-floor" wiring "python3 is not on PATH, so no floor was checked by this run." +else + mkdir -p "${_floor_report_dir}" 2>/dev/null + _floor_args=(check . --md "${_floor_report_dir}/sig-floor.md" --json "${_floor_report_dir}/sig-floor.json" + --proposed "${_floor_report_dir}/sig-floor.proposed.json") + [ -n "${HYDRA_GATE_SIG_CACHE:-}" ] && _floor_args+=(--cache "${HYDRA_GATE_SIG_CACHE}") + [ "${HAVE_DELTA_BASE}" = "1" ] && _floor_args+=(--base-ref "${BASE_REF}") + set +e + python3 "${_floor_helper}" "${_floor_args[@]}" > "${_floor_log}" 2>&1 + _floor_rc=$? + set +e + _floor_why=$(tail -3 "${_floor_log}" 2>/dev/null | tr '\n' ' ' | cut -c1-240) + case "${_floor_rc}" in + 0) + if _helper_finished "${_floor_log}" '^\[gate-123\] sig-floor: PASS: [0-9]+ floored check'; then + grep -E '^ (unverified|inherited)' "${_floor_log}" 2>/dev/null + grep -E '^\[gate-123\] sig-floor: PASS' "${_floor_log}" + _pass 123 "sig-floor" + else + _skip 123 "sig-floor" wiring "check_sig_floor.py exited 0 without its PASS census line, so nothing is verified by this run. Checker output: ${_floor_why:-}. See ${_floor_log}." + fi + ;; + 1) + if _helper_finished "${_floor_log}" '^\[gate-123\] sig-floor: FAIL: [0-9]+ floored check'; then + grep -E '^ [^ ]' "${_floor_log}" 2>/dev/null + _floor_n=$(sed -n 's/^\[gate-123\] sig-floor: FAIL: \([0-9]*\) floored.*/\1/p' "${_floor_log}" | tail -1) + _fail 123 "sig-floor" "${_floor_n:-1} SIG 4-star check(s) in this app's floor are no longer met, or were removed from .github/sig-floor.json. Each is named above with its share and limit. See ${_floor_report_dir}/sig-floor.md and ${_floor_log}" + else + # A CRASH IS NOT A FINDING. A Python traceback also exits 1. + _skip 123 "sig-floor" wiring "check_sig_floor.py exited 1 without its FAIL summary, so it did not finish and nothing is verified by this run. Checker output: ${_floor_why:-}. See ${_floor_log}." + fi + ;; + 4) + _skip 123 "sig-floor" na "$(tail -1 "${_floor_log}" 2>/dev/null | sed 's/^\[gate-123\] sig-floor: //' | cut -c1-240)" + ;; + 5) + _skip 123 "sig-floor" wiring "a pinned measuring tool is unavailable, so no floor was checked by this run: ${_floor_why:-}. See ${_floor_log}." + ;; + *) + _skip 123 "sig-floor" wiring "check_sig_floor.py exited ${_floor_rc} without a verdict, so nothing is verified by this run. Checker output: ${_floor_why:-}. See ${_floor_log}." + ;; + esac +fi + # --------------------------------------------------------------------------- # Summary + COVERAGE ACCOUNTING # diff --git a/hydra-gates/scripts/test-fixtures/gate-acceptance/COVERED-ELSEWHERE.md b/hydra-gates/scripts/test-fixtures/gate-acceptance/COVERED-ELSEWHERE.md index 51f4c2fa..b3223754 100644 --- a/hydra-gates/scripts/test-fixtures/gate-acceptance/COVERED-ELSEWHERE.md +++ b/hydra-gates/scripts/test-fixtures/gate-acceptance/COVERED-ELSEWHERE.md @@ -58,6 +58,7 @@ with the missing half named. | gate-120 | register-version-needs-app-version | `test_gate120_register_version_scope.sh` + `test_check_register_version_bump.py` | builds a real git history in a tmpdir. A delta rule needs a base and a change, which a bundle does not have. ARM 1 raises `lib/Settings/fixture_register.json` info.version 0.96.0 to 0.97.0 and leaves ``: FAIL, naming the document and both versions. ARM 2 raises both: PASS with the census line. ARM 3 raises only a mock: PASS. ARM 4 has no delta base: NOT APPLICABLE, never PASS. ARM 5 is a repo with no lib/Settings: NOT APPLICABLE. ARM 6 is a register document that is not JSON: SKIPPED (wiring), never a verdict. The rule-by-rule arms (fragments count, a register's effective version raised by a new register.d fragment counts as in pipelinq #2471, an added document counts and a deleted one does not, only watched paths, no info.xml, ref mode agreeing with working-tree mode) are in the Python suite. | | gate-121 | register-auth-dialect | `test_gate121_register_auth_dialect_scope.sh` + `test_check_register_auth_dialect.py` | builds a real git repository in a tmpdir, so the runner's tracked-file enumeration of lib/Settings is what is exercised, not a bundle's copy. ARM 1 plants `x-openregister-rbac` on a schema and FAILS, naming the file and `components.schemas.Invoice.x-openregister-rbac`. ARM 2 is the same schema on `authorization`: PASS with the census line. ARM 3 is the report-only pin: an open schema beside a closed one still PASSES, and the `authorization coverage: 1 of 2` line reaches the run's output. ARM 4 pins the promotion, `HYDRA_GATE_REGISTER_AUTHORIZATION_BLOCKING=1`, which FAILS the same tree. ARM 5 is a repo with no register document: NOT APPLICABLE. ARM 6 is a register document that is not JSON: SKIPPED (wiring), never a verdict. The rule-by-rule arms (each dead key, a transition's `x-rbac-role`, a property's singular validation, a property NAMED like a dead key, every watched path including packages/** and mocks, the register.d deep merge in the census, empty blocks, mocks out of the census, `--judge-from` narrowing findings and not the census) are in the Python suite. | | gate-122 | sig-maintainability | `test_gate122_sig_maintainability_scope.sh` + `test_check_sig_maintainability.py` | builds a real git history in a tmpdir. A ratchet needs a base and a change, which a bundle does not have. ARM 1 adds a unit with five parameters and WARNS, naming `lib/Service/Fresh.php:6 Fresh::wide`. ARM 2 pins the promotion, `HYDRA_GATE_SIG_MAINTAINABILITY_BLOCKING=1`, which FAILS the same tree. ARM 3 is a small unit: PASS with the census line. ARM 4 has no delta base: report mode, PASS, and sig-profile.json and sig-profile.md are written to `HYDRA_GATE_SIG_REPORT_DIR`. ARM 5 is a docs-only change: NOT APPLICABLE. ARM 6 removes the pinned tools and forbids installing them: SKIPPED (wiring), never PASS. The rule-by-rule arms (each bound and its exclusive edge, a legacy unit touched but not made worse is inherited, made worse is new, a new copy of a 6+ line fragment is new and an edit inside an existing clone is not, the PHP parameter count, Python `self`, a file lizard raises on, Sigrid's default excludes and sigrid.yaml, the code-weighted report, PHP and Python dependencies, the component root, and the violation degree on the Guidance for Producers examples) are in the Python suite. | +| gate-123 | sig-floor | `test_gate123_sig_floor_scope.sh` + `test_check_sig_floor.py` | builds a real git history in a tmpdir with a floor written by `check_sig_floor.py write`. ARM 1 adds a 74-line unit, which breaks the floored `php unit_size >60`: FAIL, naming the check and its base share. ARM 2 is a small new unit: PASS with the census line, and sig-floor.md is written to `HYDRA_GATE_SIG_REPORT_DIR`. ARM 3 has no floor file: NOT APPLICABLE. ARM 4 removes the pinned tools: SKIPPED (wiring), never PASS. The rule-by-rule arms (a check met at the base is guarded before the file lists it, an inherited breach passes until made worse, a lowered floor file fails, the floor is read from the base, sigrid.yaml excludes, the 5-star report never blocks, the raised floor proposal, the unit cache) are in the Python suite. | | gate-100 | setup-demo-data-first | `test_gate100_setup_demo_first_scope.sh` | real two-commit history. ARM 3 pins that an app declaring NO setup block is not failed — twenty of thirty fleet manifests are in that state, so failing them would block unrelated manifest edits fleet-wide. Adoption is a rollout; the gate holds the line on the ten that exist. | | gate-19 | e2e-coverage | `test_gate19_coverage_credibility.sh` | `test-fixtures/e2e-credibility/{req-inherit,scenario-level,file-level-tag,honest}` — `.github#356`, `#343`, `#345` and the never-false `test.skip` guard | | gate-23 | or-abstraction-anti-patterns | `test_gates_23_33_never_green_over_nothing.sh` | `test-fixtures/gates-23-33/{planted,clean}` | diff --git a/scripts/assert-no-producer-deletes-a-verdict.py b/scripts/assert-no-producer-deletes-a-verdict.py index e975f0c6..c35eb6c3 100755 --- a/scripts/assert-no-producer-deletes-a-verdict.py +++ b/scripts/assert-no-producer-deletes-a-verdict.py @@ -58,8 +58,14 @@ r"needs(?:\.[A-Za-z0-9_-]+|\[['\"][A-Za-z0-9_-]+['\"]\])\.result\s*(?:!=|==)" ) -# job-id -> reason. Empty on purpose. -ALLOWLIST: dict[str, str] = {} +# job-id -> reason. Each entry argues why the job renders no verdict. +ALLOWLIST: dict[str, str] = { + "sig-floor-raise": ( + "renders no verdict: it runs only after a successful hydra-gates job on " + "a push to development, to offer gate 123's raised floor file as a pull " + "request. Skipping it loses no verdict; the floor is judged by gate 123." + ), +} def check(workflow: dict, injected: dict | None = None) -> list[str]: diff --git a/scripts/assert-quality-report-gates-every-leg.py b/scripts/assert-quality-report-gates-every-leg.py index 3f18cc3c..29b44460 100644 --- a/scripts/assert-quality-report-gates-every-leg.py +++ b/scripts/assert-quality-report-gates-every-leg.py @@ -57,6 +57,11 @@ "waits for the Quality Report to complete, so the report cannot also " "wait for it." ), + "sig-floor-raise": ( + "renders no verdict: after a push to development it offers gate 123's " + "raised floor file as a pull request. The floor's verdict is gate 123 " + "inside the hydra-gates job, which the report already gates on." + ), } From 8e9e8d8cdd8fcc5696948015f50dee4516142700 Mon Sep 17 00:00:00 2001 From: Ruben van der Linde Date: Mon, 2 Nov 2026 15:43:42 +0100 Subject: [PATCH 3/3] fix(hydra-gates): gate 123 reads the floor file first and lets checks leave only through sigrid.yaml An app without a floor file is NOT APPLICABLE before any tool is loaded or base resolved. A floored check the head no longer measures fails unless the change edits sigrid.yaml, or the base no longer measured it either. The raise proposal keeps committed checks the head misses. Tests pin the 4-star boundaries, equal shares as not worse, and the scope rule. ShellCheck SC2016 is disabled on the PHP template line. Assisted-by: ClaudeCode:claude-opus-5-5 --- hydra-gates/scripts/lib/check_sig_floor.py | 61 ++++++-- .../scripts/lib/test_check_sig_floor.py | 132 ++++++++++++++++++ .../lib/test_gate123_sig_floor_scope.sh | 1 + 3 files changed, 184 insertions(+), 10 deletions(-) diff --git a/hydra-gates/scripts/lib/check_sig_floor.py b/hydra-gates/scripts/lib/check_sig_floor.py index 104c243f..b50518d1 100644 --- a/hydra-gates/scripts/lib/check_sig_floor.py +++ b/hydra-gates/scripts/lib/check_sig_floor.py @@ -31,6 +31,14 @@ forward; reported, not counted A change that removes a check from the committed floor file fails as well. +A floored check the head no longer measures at all (its language left the +measured scope) fails, unless the same change edits sigrid.yaml: an explicit +scope change may take checks out of the floor, file included. A check that the +base did not measure either left in an earlier change and is not judged again. + +Without a floor file the gate is NOT APPLICABLE (exit 4) before any tool is +loaded or any base resolved. + The 5-star checks (half of every 4-star limit, gate 122's five-star profile) are reported next to the 4-star ones and never block. @@ -218,6 +226,20 @@ def floor_document(app, labels): } +def floor_present(app, path, base_ref): + """Whether a floor file exists at the head or at `base_ref`. Asked before + any tool is loaded or any merge base resolved, so an app without a floor + is NOT APPLICABLE however its tooling or history looks.""" + if os.path.isfile(os.path.join(app, path)): + return True + return bool(base_ref) and git(app, "cat-file", "-e", f"{base_ref}:{path}")[0] == 0 + + +def sigrid_changed(app, mb): + rc, out = git(app, "diff", "--name-only", mb, "HEAD", "--", "sigrid.yaml", "sigrid.yml") + return rc == 0 and bool(out.strip()) + + def measure_base(app, mb, lizard, reader): """Measure the tree at commit `mb` in a temporary worktree.""" tmp = tempfile.mkdtemp(prefix="sig-floor-base-") @@ -237,14 +259,22 @@ def measure_base(app, mb, lizard, reader): # verdict # -------------------------------------------------------------------------- -def judge(floor, head4, base4): - """(new, inherited) breaches of `floor`: lists of (label, why).""" +def judge(floor, head4, base4, scope_changed=False): + """(new, inherited) breaches of `floor`: lists of (label, why). + + A floored check the head no longer measures may leave the floor only when + the change edits sigrid.yaml (an explicit scope change), or when the base + did not measure it either (it left in an earlier change).""" new, inherited = [], [] for label in sorted(floor): h = head4.get(label) b = base4.get(label) if base4 is not None else None if h is None: - new.append((label, "no longer measured (its language or module structure left the measured scope)")) + if scope_changed or (base4 is not None and b is None): + inherited.append((label, "no longer measured; it left the measured scope through sigrid.yaml")) + else: + new.append((label, "no longer measured (its language or module structure left the measured scope " + "without a sigrid.yaml change)")) continue if h["ok"]: continue @@ -319,6 +349,12 @@ def cmd_write(args, lizard): return 0 +def no_floor(path): + print(f"{GATE}: this repository has no {path}; generate it with " + f"`check_sig_floor.py write .` to adopt the floor") + return 4 + + def cmd_check(args, lizard): app = args.app mb = None @@ -334,10 +370,9 @@ def cmd_check(args, lizard): base_floor = floor_at(app, mb, args.floor) if mb else None committed = base_floor if base_floor is not None else head_floor if committed is None: - print(f"{GATE}: this repository has no {args.floor}; generate it with " - f"`check_sig_floor.py write .` to adopt the floor") - return 4 - lowered = sorted(set(base_floor) - set(head_floor or [])) if base_floor is not None else [] + return no_floor(args.floor) + scope_changed = bool(mb) and sigrid_changed(app, mb) + removed = sorted(set(base_floor) - set(head_floor or [])) if base_floor is not None else [] cache = load_cache(args.cache) reader = CachedUnitReader(lizard, cache) @@ -353,12 +388,16 @@ def cmd_check(args, lizard): save_cache(args.cache, cache, reader.used) floor = set(committed) | ({lbl for lbl, r in base4.items() if r["ok"]} if base4 else set()) - new, inherited = judge(floor, head4, base4) + new, inherited = judge(floor, head4, base4, scope_changed) + # A check may leave the file only when it also left the measurement, as judge() allows. + gone = {lbl for lbl, _why in inherited if lbl not in head4} + lowered = [lbl for lbl in removed if lbl not in gone] met_head = {lbl for lbl, r in head4.items() if r["ok"]} raise_to = sorted(met_head - set(committed)) - if args.proposed and raise_to and not new and not lowered: + proposal = (set(committed) - gone) | met_head + if args.proposed and proposal != set(committed) and not new and not lowered: with open(args.proposed, "w") as fh: - json.dump(floor_document(app, set(committed) | met_head), fh, indent=1) + json.dump(floor_document(app, proposal), fh, indent=1) fh.write("\n") md = markdown(os.path.basename(os.path.abspath(app)), floor, head4, head5, base4, @@ -409,6 +448,8 @@ def main(argv): w.add_argument("--cache") args = ap.parse_args(argv) args.app = os.path.abspath(args.app) + if args.mode == "check" and not floor_present(args.app, args.floor, args.base_ref): + return no_floor(args.floor) lizard, why = sig.load_lizard() if not lizard: print(f"{GATE}: tooling: {why}") diff --git a/hydra-gates/scripts/lib/test_check_sig_floor.py b/hydra-gates/scripts/lib/test_check_sig_floor.py index 2db486f2..8cad330d 100644 --- a/hydra-gates/scripts/lib/test_check_sig_floor.py +++ b/hydra-gates/scripts/lib/test_check_sig_floor.py @@ -184,6 +184,16 @@ def test_a_check_development_already_misses_is_inherited_until_made_worse(self): self.assertIn("already missed at the base", out) self.assertIn("makes it worse", out) + def test_an_equal_share_on_an_inherited_breach_is_not_worse(self): + self.repo.git("checkout", "-q", "base") + self.repo.write("lib/Service/Big.php", php_class("Big", [php_method("huge", lines=70, tag="h")])) + self.repo.commit("development broke it") + self.repo.git("checkout", "-q", "-B", "change") + self.repo.write("README.md", "docs only\n") + rc, out = self.check() + self.assertEqual(rc, 0, out) + self.assertIn("inherited, not counted: php unit_size >60", out) + def test_removing_a_check_from_the_floor_file_fails(self): checks = self.repo.floor_file()["checks"] self.repo.set_floor([c for c in checks if c != "php unit_size >60"]) @@ -269,6 +279,21 @@ def test_a_head_that_meets_more_checks_proposes_the_raised_floor(self): with open(self.proposed) as fh: self.assertEqual(json.load(fh)["checks"], checks) + def test_the_proposal_keeps_committed_checks_the_head_misses(self): + self.repo.git("checkout", "-q", "base") + checks = self.repo.floor_file()["checks"] + self.repo.set_floor([c for c in checks if c != "php unit_interfacing >6"]) + self.repo.write("lib/Service/Big.php", php_class("Big", [php_method("huge", lines=70, tag="h")])) + self.repo.commit("development broke a floored check and the file misses another") + self.repo.git("checkout", "-q", "-B", "change") + self.repo.write("README.md", "docs\n") + rc, out = self.check("--proposed", self.proposed) + self.assertEqual(rc, 0, out) + with open(self.proposed) as fh: + proposed = json.load(fh)["checks"] + self.assertIn("php unit_size >60", proposed) + self.assertIn("php unit_interfacing >6", proposed) + def test_a_failing_change_proposes_nothing(self): self.repo.git("checkout", "-q", "base") self.repo.set_floor([c for c in self.repo.floor_file()["checks"] if c != "php unit_interfacing >6"]) @@ -281,6 +306,113 @@ def test_a_failing_change_proposes_nothing(self): self.assertFalse(os.path.exists(self.proposed)) +class FloorFirst(FloorCase): + def test_no_floor_is_not_applicable_before_any_tool_or_base(self): + self.repo.remove(floor.FLOOR_PATH) + self.repo.commit("drop") + real = sig.load_lizard + sig.load_lizard = lambda: (None, "tools must not be loaded without a floor") + try: + rc, out = run("check", self.repo.dir) + self.assertEqual(rc, 4, out) + rc, out = run("check", self.repo.dir, "--base-ref", "no-such-ref") + self.assertEqual(rc, 4, out) + self.assertNotIn("tooling", out) + finally: + sig.load_lizard = real + + def test_with_a_floor_missing_tools_are_wiring(self): + real = sig.load_lizard + sig.load_lizard = lambda: (None, "no lizard") + try: + rc, out = run("check", self.repo.dir, "--base-ref", "base") + self.assertEqual(rc, 5, out) + finally: + sig.load_lizard = real + + +class Boundaries(unittest.TestCase): + def report(self, size, dup, coupling, hidden): + rows = lambda prop: [{"above": b, "share": size if i == 0 else 0.0} + for i, (b, _cap) in enumerate(sig.LIMITS[prop])] + return {"languages": {"php": {"unit_size": rows("unit_size"), "unit_complexity": rows("unit_complexity"), + "unit_interfacing": rows("unit_interfacing"), + "duplication": {"share": dup}}}, + "structure": {"php": {"module_coupling": [{"above": 10, "share": coupling}, + {"above": 20, "share": 0.0}, {"above": 50, "share": 0.0}], + "component_independence": {"hidden_share": hidden}}}} + + def test_a_share_equal_to_the_limit_meets_it(self): + rows = floor.check_rows(self.report(.471, .056, .100, .937), "four-star") + for label in ("php unit_size >15", "php duplication", "php module_coupling >10", + "php component_independence"): + self.assertTrue(rows[label]["ok"], label) + + def test_an_equal_share_is_not_worse_in_either_direction(self): + for better_high in (False, True): + row = {"share": .5, "higher_is_better": better_high} + self.assertFalse(floor.worse(row, dict(row))) + self.assertTrue(floor.worse(row, dict(row, share=.6 if better_high else .4))) + + def test_just_past_the_limit_misses_it(self): + rows = floor.check_rows(self.report(.4711, .0561, .1001, .9369), "four-star") + for label in ("php unit_size >15", "php duplication", "php module_coupling >10", + "php component_independence"): + self.assertFalse(rows[label]["ok"], label) + + +class Scope(FloorCase): + def setUp(self): + super().setUp() + self.repo.git("checkout", "-q", "base") + self.repo.write("src/a.js", "export function f(a) {\n if (a) { return 1 }\n return 2\n}\n") + self.repo.commit("a js file") + rc, out = run("write", self.repo.dir) + self.assertEqual(rc, 0, out) + self.repo.commit("floor with javascript") + self.assertIn("javascript unit_size >15", self.repo.floor_file()["checks"]) + self.repo.git("checkout", "-q", "-B", "change") + + def test_a_language_that_leaves_without_a_scope_change_fails(self): + self.repo.remove("src/a.js") + rc, out = self.check() + self.assertEqual(rc, 1, out) + self.assertIn("javascript unit_size >15: no longer measured", out) + + def test_a_sigrid_yaml_exclude_takes_the_checks_out_of_the_floor(self): + self.repo.write("sigrid.yaml", "exclude:\n - \".*/src/.*\"\n") + js = [c for c in self.repo.floor_file()["checks"] if c.startswith("javascript")] + self.repo.set_floor([c for c in self.repo.floor_file()["checks"] if c not in js]) + rc, out = self.check() + self.assertEqual(rc, 0, out) + self.assertIn("left the measured scope through sigrid.yaml", out) + + # The next change, on a base that already excludes it, is not judged on it again. + self.repo.git("branch", "-f", "base", "HEAD") + self.repo.write("README.md", "next\n") + rc, out = self.check() + self.assertEqual(rc, 0, out) + self.assertNotIn("javascript", out.split("[gate-123]")[0]) + + def test_a_check_the_base_no_longer_measures_is_not_judged_again(self): + self.repo.write("sigrid.yaml", "exclude:\n - \".*/src/.*\"\n") + rc, out = self.check() + self.assertEqual(rc, 0, out) + self.assertIn("javascript unit_size >15", self.repo.floor_file()["checks"]) + self.repo.git("branch", "-f", "base", "HEAD") + self.repo.write("README.md", "next\n") + rc, out = self.check() + self.assertEqual(rc, 0, out) + self.assertIn("inherited, not counted: javascript unit_size >15", out) + + def test_removing_a_still_measured_check_fails_even_with_a_sigrid_change(self): + self.repo.write("sigrid.yaml", "exclude:\n - \".*/docs/.*\"\n") + self.repo.set_floor([c for c in self.repo.floor_file()["checks"] if c != "javascript unit_size >15"]) + rc, out = self.check() + self.assertEqual(rc, 1, out) + self.assertIn("removes 1 check(s) from the committed floor: javascript unit_size >15", out) + + class Cache(unittest.TestCase): def test_a_cached_run_reads_the_same_units_and_no_file_twice(self): repo = Repo() diff --git a/hydra-gates/scripts/lib/test_gate123_sig_floor_scope.sh b/hydra-gates/scripts/lib/test_gate123_sig_floor_scope.sh index a1594753..85e09e9d 100755 --- a/hydra-gates/scripts/lib/test_gate123_sig_floor_scope.sh +++ b/hydra-gates/scripts/lib/test_gate123_sig_floor_scope.sh @@ -32,6 +32,7 @@ mkdir -p "${APP}/appinfo" "${APP}/lib/Service" _method() { # -> a one-parameter PHP method with statements local _b="" _i for _i in $(seq 1 "$2"); do _b="${_b} \$v${_i} = ${_i} + strlen('$1');\n"; done + # shellcheck disable=SC2016 # $p is PHP source text and must stay literal. printf ' public function %s(int $p): int\n {\n%b return $p;\n }\n' "$1" "${_b}" } _class() { #