diff --git a/hydra-gates/scripts/lib/check_sig_maintainability.py b/hydra-gates/scripts/lib/check_sig_maintainability.py new file mode 100755 index 00000000..0f325076 --- /dev/null +++ b/hydra-gates/scripts/lib/check_sig_maintainability.py @@ -0,0 +1,1144 @@ +#!/usr/bin/env python3 +# SPDX-FileCopyrightText: 2026 Conduction +# SPDX-License-Identifier: EUPL-1.2 +"""gate-122 helper: the SIG maintainability metrics, as a ratchet and as a report. + +The Software Improvement Group (SIG, platform Sigrid) rates maintainability per +language from risk profiles: the share of code that sits in units (methods and +functions) above a size, complexity or parameter bound, plus duplication and a +few architecture properties. The 4-star limits come from the SIG/TUV NORD CERT +"Guidance for Producers" v17.0. hydra's phpmd runs at its own defaults with +baselines, so a green phpmd is not a green SIG profile. + +TWO MODES +--------- +ratchet (the gate, on a delta base) + For every unit the diff ADDS or CHANGES (a unit whose line range holds an + added line), a finding when + NLOC > 60, McCabe > 10, or 5 or more parameters + and for every duplicated fragment of 6 or more lines the diff INTRODUCES + (one occurrence of the clone has at least 6 added lines). + + A finding is NEW when the unit is new, or when the change pushed it over a + bound or made an already-over unit worse. A changed unit that was already + over the bound at the base and did not get worse is INHERITED, and so is + every finding on a unit the diff did not touch. Only NEW findings count. + +report (nightly, or a full-scope run with no base) + The whole risk profile of one app, per language, against the 4-star limits: + unit size, unit complexity, unit interfacing, duplication, and for PHP and + Python module coupling, component independence and an entanglement + approximation. Written as JSON and as a short markdown table. + +WHAT IS MEASURED +---------------- +Tracked files with a source extension (php, js/mjs/cjs/jsx, ts/tsx, vue, py), +minus Sigrid's own default excludes (vendored at the bottom of this file, from +github.com/Software-Improvement-Group/sigridci resources/default-excludes.txt), +minus test code (SIG rates test code separately), minus the Nextcloud build +output directory js/ and l10n/. A `sigrid.yaml` (or .yml) at the repository +root adds its top-level `exclude:` patterns, so the gate scopes the code the +way SIG will once the repository carries a scope file. + +TOOLS, PINNED +------------- +lizard 1.24.3 (units: NLOC, McCabe, parameters) and jscpd 4.0.5 (the +ratchet's clones). The report's duplication follows SIG's line definition +directly (windows of 6 code lines equal modulo whitespace) and shows jscpd's +figure next to it as a cross-check. +A different version produces different numbers, so the pinned version is +loaded or installed into the tool cache (HYDRA_GATE_TOOLS_DIR, default +~/.cache/hydra-gates/tools) and any other version is refused. Set +HYDRA_GATE_SIG_NO_INSTALL=1 to forbid the install. + +Two lizard traps are handled here: + * PHP parameter counts: lizard's PHP reader keeps only the last parameter in + `parameters`. The count is the number of unique `$names` in `long_name`. + * Crashes: lizard raises on some files (a Vue component in openconnector). + Each file is analysed on its own with a time limit, and a file lizard + cannot read is listed as skipped, never silently dropped. + +Python methods do not count `self` or `cls` as a parameter. + +Usage: + check_sig_maintainability.py ratchet --base-ref REF + check_sig_maintainability.py report [--json FILE] [--md FILE] + +Output ends in one of + [gate-122] sig-maintainability: checked U changed unit(s) in F file(s), ... + [gate-122] sig-maintainability: FAIL: N finding(s) ... + [gate-122] sig-maintainability: report: ... +Exit status: 0 clean (or a report), 1 findings, 3 the base does not resolve, +4 nothing to judge, 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 collections +import json +import os +import re +import shutil +import signal +import subprocess +import sys +import tempfile + +GATE = "[gate-122] sig-maintainability" +LIZARD_VERSION = "1.24.3" +JSCPD_VERSION = "4.0.5" + +LANG_OF_EXT = { + ".php": "php", + ".js": "javascript", ".mjs": "javascript", ".cjs": "javascript", ".jsx": "javascript", + ".ts": "typescript", ".tsx": "typescript", + ".vue": "vue", + ".py": "python", +} + +# Ratchet bounds: a changed unit is a finding ABOVE these. +RATCHET = {"nloc": 60, "ccn": 10, "params": 4} +RATCHET_LABEL = {"nloc": "NLOC > 60", "ccn": "McCabe > 10", "params": "5 or more parameters"} +DUP_MIN_LINES = 6 + +# 4-star limits, per language, as (bound, max share of unit LOC strictly above bound). +LIMITS = { + "unit_size": [(15, .471), (30, .231), (60, .083)], + "unit_complexity": [(5, .202), (10, .073), (25, .011)], + "unit_interfacing": [(2, .150), (4, .033), (6, .009)], # 3+, 5+, 7+ parameters + "module_coupling": [(10, .100), (20, .056), (50, .019)], +} +DUPLICATION_LIMIT = .056 +INDEPENDENCE_MIN = .937 +ENTANGLEMENT_LIMIT = .077 + +TEST_PATTERNS = [ + r".*/tests?/.*", r".*/__tests__/.*", r".*/__mocks__/.*", r".*/e2e/.*", + r".*[.](spec|test)[.](js|mjs|cjs|jsx|ts|tsx)", + r".*/test_[^/]*[.]py", r".*/[^/]*_test[.]py", r".*/conftest[.]py", +] +NEXTCLOUD_EXCLUDES = [r"/js/.*", r"/l10n/.*"] + +FILE_TIMEOUT = int(os.environ.get("HYDRA_GATE_SIG_FILE_TIMEOUT", "30")) + + +# -------------------------------------------------------------------------- +# scope +# -------------------------------------------------------------------------- + +def sigrid_yaml_excludes(app): + """Top-level `exclude:` regexes of sigrid.yaml / sigrid.yml, if present.""" + for name in ("sigrid.yaml", "sigrid.yml"): + path = os.path.join(app, name) + if not os.path.isfile(path): + continue + out, inside = [], False + with open(path, encoding="utf-8", errors="replace") as fh: + for line in fh: + if re.match(r"^exclude:\s*$", line): + inside = True + continue + if inside: + m = re.match(r"^\s+-\s+[\"']?(.+?)[\"']?\s*$", line) + if m: + out.append(m.group(1)) + elif line.strip() and not line.startswith((" ", "\t", "#")): + inside = False + return out + return [] + + +class Scope: + def __init__(self, app): + pats = SIGRID_DEFAULT_EXCLUDES + NEXTCLOUD_EXCLUDES + sigrid_yaml_excludes(app) + self.exclude = [re.compile(p) for p in pats] + self.tests = [re.compile(p) for p in TEST_PATTERNS] + + def language(self, rel): + lang = LANG_OF_EXT.get(os.path.splitext(rel)[1].lower()) + if not lang: + return None + probe = "/" + rel + if any(p.fullmatch(probe) for p in self.exclude): + return None + if any(p.fullmatch(probe) for p in self.tests): + return None + return lang + + +def tracked_files(app): + rc, out = git(app, "ls-files", "-z") + if rc == 0: + return [p for p in out.split("\0") if p] + found = [] + for root, dirs, files in os.walk(app): + dirs[:] = [d for d in dirs if d not in (".git", "node_modules", "vendor")] + for fn in files: + found.append(os.path.relpath(os.path.join(root, fn), app)) + return found + + +def production_files(app, scope): + """{rel path: language} for every measured file in the working tree.""" + out = {} + for rel in tracked_files(app): + lang = scope.language(rel) + if lang and os.path.isfile(os.path.join(app, rel)): + out[rel] = lang + return out + + +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 + + +# -------------------------------------------------------------------------- +# tools +# -------------------------------------------------------------------------- + +def tools_dir(): + base = os.environ.get("HYDRA_GATE_TOOLS_DIR") or os.path.join( + os.environ.get("XDG_CACHE_HOME") or os.path.join(os.path.expanduser("~"), ".cache"), + "hydra-gates", "tools") + return base + + +def may_install(): + return os.environ.get("HYDRA_GATE_SIG_NO_INSTALL", "0") != "1" + + +def load_lizard(): + """Import lizard at the pinned version, installing it into the tool cache + when allowed. Returns (module, None) or (None, reason).""" + target = os.path.join(tools_dir(), f"lizard-{LIZARD_VERSION}") + if os.path.isdir(target): + sys.path.insert(0, target) + try: + import lizard # noqa: F401 + except ImportError: + lizard = None + if lizard is not None and getattr(lizard, "version", "") == LIZARD_VERSION: + return lizard, None + if lizard is not None: + found = getattr(lizard, "version", "?") + for name in [m for m in sys.modules if m == "lizard" or m.startswith(("lizard_", "lizard."))]: + del sys.modules[name] + if target in sys.path: + return None, f"lizard {found} is importable but {LIZARD_VERSION} is pinned; remove {target} and retry" + if not may_install(): + return None, f"lizard {LIZARD_VERSION} is not installed and HYDRA_GATE_SIG_NO_INSTALL=1 forbids installing it" + os.makedirs(target, exist_ok=True) + p = subprocess.run([sys.executable, "-m", "pip", "install", "--quiet", "--disable-pip-version-check", + "--no-input", "--target", target, f"lizard=={LIZARD_VERSION}"], + capture_output=True, text=True) + if p.returncode != 0: + shutil.rmtree(target, ignore_errors=True) + return None, f"pip could not install lizard=={LIZARD_VERSION}: {(p.stderr or p.stdout).strip()[-300:]}" + sys.path.insert(0, target) + try: + import lizard + except ImportError as e: + return None, f"lizard installed into {target} but does not import: {e}" + if getattr(lizard, "version", "") != LIZARD_VERSION: + return None, f"imported lizard {getattr(lizard, 'version', '?')} from {lizard.__file__}, not the pinned {LIZARD_VERSION}" + return lizard, None + + +def find_jscpd(): + """Path to a jscpd binary at the pinned version, or (None, reason).""" + env = os.environ.get("HYDRA_GATE_JSCPD") + target = os.path.join(tools_dir(), f"jscpd-{JSCPD_VERSION}") + exe = env or os.path.join(target, "node_modules", ".bin", "jscpd") + if not os.path.isfile(exe): + if env: + return None, f"HYDRA_GATE_JSCPD={env} does not exist" + if not shutil.which("npm"): + return None, "npm is not on PATH, so jscpd cannot be installed" + if not may_install(): + return None, f"jscpd {JSCPD_VERSION} is not installed and HYDRA_GATE_SIG_NO_INSTALL=1 forbids installing it" + os.makedirs(target, exist_ok=True) + p = subprocess.run(["npm", "install", "--silent", "--no-audit", "--no-fund", "--ignore-scripts", + "--prefix", target, f"jscpd@{JSCPD_VERSION}"], capture_output=True, text=True) + if p.returncode != 0 or not os.path.isfile(exe): + return None, f"npm could not install jscpd@{JSCPD_VERSION}: {(p.stderr or p.stdout).strip()[-300:]}" + p = subprocess.run([exe, "--version"], capture_output=True, text=True) + found = (p.stdout or "").strip().splitlines()[-1:] or ["?"] + if found[0] != JSCPD_VERSION: + return None, f"{exe} reports jscpd {found[0]}, not the pinned {JSCPD_VERSION}" + return exe, None + + +# -------------------------------------------------------------------------- +# units +# -------------------------------------------------------------------------- + +class _Timeout(Exception): + pass + + +def _alarm(_sig, _frame): + raise _Timeout() + + +def unit_params(lang, func): + if lang == "php": + # lizard's PHP reader keeps only the last parameter; long_name lists each $name twice. + return len(set(re.findall(r"\$\w+", func.long_name))) + params = list(func.parameters) + if lang == "python" and params and params[0] in ("self", "cls"): + params = params[1:] + return len(params) + + +class UnitReader: + def __init__(self, lizard): + self.analyzer = lizard.FileAnalyzer(lizard.get_extensions([])) + self.skipped = [] + + def units(self, rel, lang, code): + """Units of one file's source. A file lizard cannot read is recorded in + self.skipped and yields no units.""" + use_alarm = hasattr(signal, "SIGALRM") + if use_alarm: + old = signal.signal(signal.SIGALRM, _alarm) + signal.alarm(FILE_TIMEOUT) + try: + info = self.analyzer.analyze_source_code(rel, code) + except _Timeout: + self.skipped.append({"file": rel, "reason": f"lizard did not finish within {FILE_TIMEOUT}s"}) + return [] + except Exception as e: # lizard raises on some inputs; one file must not sink the run + self.skipped.append({"file": rel, "reason": f"lizard raised {type(e).__name__}: {str(e)[:160]}"}) + return [] + finally: + if use_alarm: + signal.alarm(0) + signal.signal(signal.SIGALRM, old) + out = [] + for f in info.function_list: + out.append({ + "file": rel, "lang": lang, "name": f.name, "start": f.start_line, "end": f.end_line, + "nloc": f.nloc, "ccn": f.cyclomatic_complexity, "params": unit_params(lang, f), + }) + return out + + +def read_text(path): + with open(path, encoding="utf-8", errors="replace") as fh: + return fh.read() + + +# -------------------------------------------------------------------------- +# duplication +# -------------------------------------------------------------------------- + +def run_jscpd(app, exe, files): + """Clone pairs among `files` (repo-relative), as a list of + {"a": (file, start, end), "b": (file, start, end), "lines": n, "code": {file: set}}. + + jscpd matches tokens and skips comments, so a reported fragment can span a + docblock, and its first and last line may match only in part. SIG counts + code lines repeated literally modulo whitespace, so the code lines of both + fragments are paired in order and only the pairs that are equal without + whitespace count. A clone is kept when at least 6 lines do, and "code" + holds those line numbers per fragment.""" + if not files: + return [] + out_dir = tempfile.mkdtemp(prefix="sig-jscpd-") + try: + cmd = [exe, "--silent", "--reporters", "json", "--output", out_dir, + "--min-lines", str(DUP_MIN_LINES), "--min-tokens", "30", "--mode", "weak", *files] + p = subprocess.run(cmd, cwd=app, capture_output=True, text=True) + report = os.path.join(out_dir, "jscpd-report.json") + if not os.path.isfile(report): + raise RuntimeError(f"jscpd exited {p.returncode} without a report: {(p.stderr or p.stdout).strip()[-300:]}") + with open(report) as fh: + data = json.load(fh) + finally: + shutil.rmtree(out_dir, ignore_errors=True) + code, text = {}, {} + + def code_in(occ): + f, s, e = occ + if f not in code: + lang = LANG_OF_EXT.get(os.path.splitext(f)[1].lower(), "") + text[f] = read_text(os.path.join(app, f)).splitlines() + code[f] = code_lines("\n".join(text[f]), lang) + return [n for n in range(s, e + 1) if n in code[f]] + + def literal_pairs(occ_a, occ_b): + same_a, same_b = set(), set() + for na, nb in zip(code_in(occ_a), code_in(occ_b)): + if "".join(text[occ_a[0]][na - 1].split()) == "".join(text[occ_b[0]][nb - 1].split()): + same_a.add(na) + same_b.add(nb) + return same_a, same_b + + clones = [] + for d in data.get("duplicates", []): + a, b = d["firstFile"], d["secondFile"] + occ_a = (os.path.relpath(os.path.join(app, a["name"]), app), a["start"], a["end"]) + occ_b = (os.path.relpath(os.path.join(app, b["name"]), app), b["start"], b["end"]) + code_a, code_b = literal_pairs(occ_a, occ_b) + if len(code_b) < DUP_MIN_LINES: + continue + clones.append({"a": occ_a, "b": occ_b, "lines": len(code_b), "code": {occ_a: code_a, occ_b: code_b}}) + return clones + + +def code_lines(text, lang): + """Line numbers (1-based) holding code: not blank, not a comment-only line.""" + lines = set() + in_block = False + hash_comments = lang in ("python", "php") + for i, raw in enumerate(text.splitlines(), 1): + s = raw.strip() + if in_block: + if "*/" in s: + in_block = False + s = s.split("*/", 1)[1].strip() + else: + continue + if not s: + continue + if s.startswith("/*"): + if "*/" not in s[2:]: + in_block = True + continue + s = s[s.index("*/", 2) + 2:].strip() + if not s: + continue + if s.startswith("//") or (hash_comments and s.startswith("#")) or s.startswith("*"): + continue + lines.add(i) + return lines + + +# -------------------------------------------------------------------------- +# report +# -------------------------------------------------------------------------- + +def profile(units, key, limits): + total = sum(u["nloc"] for u in units) or 1 + rows = [] + for bound, cap in limits: + share = sum(u["nloc"] for u in units if u[key] > bound) / total + rows.append({"above": bound, "share": round(share, 4), "limit": cap, "ok": share <= cap}) + return rows + + +def worst(units, key, n=8): + ranked = sorted(units, key=lambda u: (-u[key], u["file"], u["start"]))[:n] + return [f"{u['file']}:{u['start']} {u['name']} ({u[key]})" for u in ranked] + + +def duplication_profile(app, clones, files_by_lang): + """Redundant code lines per language, two ways. + + "duplication" follows SIG's definition directly: every window of 6 + consecutive code lines, compared without whitespace, that already occurred + earlier in a file of the same language makes its lines redundant (so N + copies count N-1 times). Windows made only of brackets are skipped. + + "duplication_jscpd" is the cross-check from jscpd's clone pairs: the + literally equal code lines of each pair's second occurrence. jscpd reports + clones pairwise and needs 30 tokens, so it finds fewer clones than SIG.""" + lines_of, code = {}, {} + for rel, lang in files_by_lang.items(): + text = read_text(os.path.join(app, rel)) + lines_of[rel] = text.splitlines() + code[rel] = code_lines(text, lang) + windows = collections.defaultdict(dict) + redundant = collections.defaultdict(set) + for rel in sorted(files_by_lang): + seen = windows[files_by_lang[rel]] + seq = [(n, "".join(lines_of[rel][n - 1].split())) for n in sorted(code[rel])] + for i in range(len(seq) - DUP_MIN_LINES + 1): + win = seq[i:i + DUP_MIN_LINES] + key = tuple(t for _n, t in win) + if all(len(t) <= 2 for t in key): + continue + if key in seen and seen[key] != (rel, i): + redundant[rel].update(n for n, _t in win) + else: + seen.setdefault(key, (rel, i)) + by_jscpd = collections.defaultdict(set) + for c in clones: + f = c["b"][0] + if f in code: + by_jscpd[f].update(c["code"][c["b"]]) + + def row(dup, total): + share = dup / total if total else 0.0 + return {"code_lines": total, "redundant_lines": dup, "share": round(share, 4), + "limit": DUPLICATION_LIMIT, "ok": share <= DUPLICATION_LIMIT} + out = {} + for lang in sorted(set(files_by_lang.values())): + files = [f for f, lg in files_by_lang.items() if lg == lang] + total = sum(len(code[f]) for f in files) + out[lang] = (row(sum(len(redundant[f]) for f in files), total), + row(sum(len(by_jscpd[f]) for f in files), total)) + return out + + +# ---- module structure ------------------------------------------------------ + +def php_dependencies(app, files): + """{module: set(modules it depends on)} for PHP files that declare a class + in a namespace. Dependencies are `use` imports, fully-qualified names, and + bare class names resolved in the file's own namespace.""" + fqcn, ns_of, srcs = {}, {}, {} + for rel in files: + src = read_text(os.path.join(app, rel)) + m = re.search(r"^namespace\s+([^;]+);", src, re.M) + if not m: + continue + ns = m.group(1).strip() + ns_of[rel] = ns + srcs[rel] = re.sub(r"/\*.*?\*/|//[^\n]*", "", src, flags=re.S) + fqcn[f"{ns}\\{os.path.basename(rel)[:-4]}"] = rel + deps = {} + for rel, body in srcs.items(): + targets = set() + for imp in re.findall(r"^use\s+([^;]+);", body, re.M): + prefix = "" + group = re.match(r"(.*)\\\{(.*)\}$", imp.strip()) + parts = group.group(2).split(",") if group else imp.split(",") + if group: + prefix = group.group(1).strip().lstrip("\\") + "\\" + for part in parts: + name = prefix + part.strip().split(" as ")[0].strip().lstrip("\\") + if name in fqcn: + targets.add(fqcn[name]) + for ident in set(re.findall(r"\b([A-Z][A-Za-z0-9_]*)\b", body)): + t = fqcn.get(f"{ns_of[rel]}\\{ident}") + if t: + targets.add(t) + for fq in re.findall(r"\\?([A-Z][A-Za-z0-9_]*(?:\\[A-Za-z0-9_]+)+)", body): + if fq in fqcn: + targets.add(fqcn[fq]) + deps[rel] = targets - {rel} + return deps + + +def python_dependencies(app, files): + """{module: set(modules it imports)} for Python files, resolving absolute + imports against the repository root and every `src`-style parent, and + relative imports against the file's package.""" + index = {} + for rel in files: + mod = rel[:-3].replace("/", ".") + if mod.endswith(".__init__"): + mod = mod[: -len(".__init__")] + parts = mod.split(".") + for i in range(len(parts)): + index.setdefault(".".join(parts[i:]), rel) + + def resolve(name): + while name: + if name in index: + return index[name] + name = name.rpartition(".")[0] + return None + + deps = {} + for rel in files: + src = read_text(os.path.join(app, rel)) + pkg = rel[:-3].replace("/", ".").split(".")[:-1] + targets = set() + for m in re.finditer(r"^\s*import\s+([\w., ]+)", src, re.M): + for part in m.group(1).split(","): + t = resolve(part.strip().split(" as ")[0].strip()) + if t: + targets.add(t) + for m in re.finditer(r"^\s*from\s+(\.*)([\w.]*)\s+import\s+(\([^)]*\)|[^\n#]+)", src, re.M): + dots, base, names = m.group(1), m.group(2), m.group(3).strip("() \n") + if dots: + anchor = pkg[: len(pkg) - (len(dots) - 1)] if len(dots) > 1 else pkg + base = ".".join([*anchor, base] if base else anchor) + for n in names.replace("\n", " ").split(","): + n = n.strip().split(" as ")[0].strip() + t = resolve(f"{base}.{n}" if n else base) if base else None + if t: + targets.add(t) + deps[rel] = targets - {rel} + return deps + + +def component_of_factory(files): + """Components are directories. Start at the repository root and descend + while one child directory holds more than 80% of the modules under the + current root: lib/ in a Nextcloud app, src/api/ in a Python service. (In + the fleet's apps lib/Service holds 50 to 71% of lib/, so it stays a + component next to lib/Db and lib/Controller.) A component is a first-level + directory below that root, and "(root)" for files directly in it. A module + outside the root belongs to its own top-level directory ("(top)" for a file + at the repository root).""" + root = "" + while files: + children = collections.Counter() + inside = [f for f in files if not root or f.startswith(root + "/")] + for f in inside: + rest = f[len(root) + 1:] if root else f + if "/" in rest: + children[rest.split("/")[0]] += 1 + if not children: + break + top, count = children.most_common(1)[0] + if count * 5 <= len(inside) * 4: + break + root = f"{root}/{top}" if root else top + + def component(rel): + if not root or rel.startswith(root + "/"): + rest = rel[len(root) + 1:] if root else rel + return rest.split("/")[0] if "/" in rest else "(root)" + return rel.split("/")[0] if "/" in rel else "(top)" + return root, component + + +def violation_degree(lines): + """SIG communication violation degree from {(src, dst): weight}: direct + cycles, then indirect cycles on what remains, then transitive lines. + Each line is counted as at most one violation.""" + total = sum(lines.values()) or 1 + violated = {} + for (a, b), w in lines.items(): + if (b, a) in lines and a < b: + w2 = lines[(b, a)] + low = min(w, w2) + if w <= w2: + violated[(a, b)] = ("cyclic", low) + if w2 <= w: + violated[(b, a)] = ("cyclic", low) + remaining = {k: v for k, v in lines.items() if k not in violated} + + def find_cycle(graph): + adj = collections.defaultdict(list) + for (a, b) in graph: + adj[a].append(b) + state, stack = {}, [] + + def dfs(n): + state[n] = 1 + stack.append(n) + for m in sorted(adj[n]): + if state.get(m) == 1: + return stack[stack.index(m):] + [m] + if not state.get(m): + c = dfs(m) + if c: + return c + state[n] = 2 + stack.pop() + return None + for n in sorted(adj): + if not state.get(n): + c = dfs(n) + if c: + return c + return None + + while True: + cyc = find_cycle(remaining) + if not cyc: + break + edges = list(zip(cyc, cyc[1:])) + weakest = min(edges, key=lambda e: (remaining[e], e)) + violated[weakest] = ("indirect-cyclic", remaining[weakest]) + del remaining[weakest] + + outgoing = collections.Counter(a for (a, _b) in remaining) + adj = collections.defaultdict(set) + for (a, b) in remaining: + adj[a].add(b) + + def reach(start, skip): + seen, todo = {start}, [start] + while todo: + n = todo.pop() + for m in adj[n]: + if (n, m) != skip and m not in seen: + seen.add(m) + todo.append(m) + return seen + + rev = collections.defaultdict(set) + for (a, b) in remaining: + rev[b].add(a) + + def reach_back(start, skip): + seen, todo = {start}, [start] + while todo: + n = todo.pop() + for m in rev[n]: + if (m, n) != skip and m not in seen: + seen.add(m) + todo.append(m) + return seen + + for (a, b), w in sorted(remaining.items()): + if not outgoing[b]: + continue + fwd, back = reach(a, (a, b)), reach_back(b, (a, b)) + if b not in fwd: + continue + on_paths = [remaining[(u, v)] for (u, v) in remaining + if (u, v) != (a, b) and u in fwd and v in back] + if on_paths and w <= min(on_paths): + violated[(a, b)] = ("transitive", w) + degree = sum(w for _kind, w in violated.values()) / total + kinds = collections.Counter(kind for kind, _w in violated.values()) + return round(degree, 4), dict(kinds), sorted(f"{a} -> {b} ({kind})" for (a, b), (kind, _w) in violated.items()) + + +def structure(app, files, deps): + """Module coupling, component independence and entanglement for one language.""" + if not deps: + return None + modules = sorted(deps) + loc = {m: len(code_lines(read_text(os.path.join(app, m)), files[m])) for m in modules} + incoming = collections.defaultdict(set) + for src, targets in deps.items(): + for t in targets: + incoming[t].add(src) + total = sum(loc.values()) or 1 + coupling = [] + for bound, cap in LIMITS["module_coupling"]: + share = sum(loc[m] for m in modules if len(incoming[m]) > bound) / total + coupling.append({"above": bound, "share": round(share, 4), "limit": cap, "ok": share <= cap}) + root, comp = component_of_factory(modules) + hidden = sum(loc[m] for m in modules if all(comp(s) == comp(m) for s in incoming[m])) + lines = collections.Counter() + for t, srcs in incoming.items(): + for s in srcs: + if comp(s) != comp(t): + lines[(comp(s), comp(t))] += 1 + connected = {c for k in lines for c in k} + density = len(lines) / max(len(connected), 1) + degree, kinds, examples = violation_degree(dict(lines)) + comp_loc = collections.Counter() + for m in modules: + comp_loc[comp(m)] += loc[m] + independence = hidden / total + return { + "modules": len(modules), + "module_loc": total, + "module_coupling": coupling, + "highest_fan_in": [f"{m} (fan-in {len(incoming[m])}, {loc[m]} loc)" + for m in sorted(modules, key=lambda m: (-len(incoming[m]), m))[:10]], + "component_root": root or ".", + "components": dict(comp_loc.most_common()), + "component_independence": {"hidden_share": round(independence, 4), "limit_min": INDEPENDENCE_MIN, + "ok": independence >= INDEPENDENCE_MIN}, + "component_entanglement": { + "communication_lines": len(lines), + "connected_components": len(connected), + "communication_density": round(density, 2), + "violation_degree": round(degree, 4), + "violations": kinds, + "violation_examples": examples[:12], + "limit": ENTANGLEMENT_LIMIT, + "ok": None, + "note": "SIG normalises density and violation degree by benchmark maxima it does not publish, " + "so this is the two inputs, not the rated value. Lower is better on both.", + }, + } + + +def build_report(app, lizard, jscpd): + scope = Scope(app) + files = production_files(app, scope) + reader = 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 [] + dup = duplication_profile(app, clones, files) + 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}, + "limits": "SIG/TUV NORD CERT Guidance for Producers v17.0, 4 stars", + "files": len(files), + "skipped_files": reader.skipped, + "languages": {}, + } + for lang in sorted(set(files.values())): + rows = by_lang.get(lang, []) + report["languages"][lang] = { + "files": sum(1 for v in files.values() if v == lang), + "units": len(rows), + "unit_loc": sum(u["nloc"] for u in rows), + "unit_size": profile(rows, "nloc", LIMITS["unit_size"]), + "unit_complexity": profile(rows, "ccn", LIMITS["unit_complexity"]), + "unit_interfacing": profile(rows, "params", LIMITS["unit_interfacing"]), + "duplication": dup[lang][0] if lang in dup else None, + "duplication_jscpd": dup[lang][1] if lang in dup else None, + "largest_units": worst(rows, "nloc"), + "most_complex_units": worst(rows, "ccn"), + "widest_units": worst(rows, "params"), + } + php = {f: lg for f, lg in files.items() if lg == "php" and f.startswith("lib/")} + py = {f: lg for f, lg in files.items() if lg == "python"} + report["structure"] = {} + if php: + report["structure"]["php"] = structure(app, php, php_dependencies(app, php)) + if py: + report["structure"]["python"] = structure(app, py, python_dependencies(app, py)) + return report + + +def checks_of(report): + """Every 4-star check in a report as (label, ok).""" + out = [] + for lang, d in report["languages"].items(): + for prop in ("unit_size", "unit_complexity", "unit_interfacing"): + for row in d[prop]: + out.append((f"{lang} {prop} >{row['above']}", row["ok"])) + if d.get("duplication"): + out.append((f"{lang} duplication", d["duplication"]["ok"])) + for lang, s in report.get("structure", {}).items(): + if not s: + continue + for row in s["module_coupling"]: + out.append((f"{lang} module_coupling >{row['above']}", row["ok"])) + out.append((f"{lang} component_independence", s["component_independence"]["ok"])) + return out + + +def pct(x): + return f"{x * 100:.1f}%" + + +def markdown(report): + out = [f"## SIG maintainability profile: {report['app']}", "", + f"lizard {LIZARD_VERSION}, jscpd {JSCPD_VERSION}; limits: {report['limits']}. " + "Each cell is the share of code above the bound, against the 4-star limit.", "", + "| language | units | size >15/30/60 | complexity >5/10/25 | params 3+/5+/7+ | duplication | jscpd |", + "|---|---|---|---|---|---|---|"] + + def cells(rows): + return " / ".join(f"{pct(r['share'])}{'' if r['ok'] else ' ✗'}" for r in rows) + for lang, d in report["languages"].items(): + dup = d.get("duplication") + dcell = f"{pct(dup['share'])}{'' if dup['ok'] else ' ✗'}" if dup else "n/a" + jdup = d.get("duplication_jscpd") + jcell = pct(jdup["share"]) if jdup else "n/a" + out.append(f"| {lang} | {d['units']} | {cells(d['unit_size'])} | {cells(d['unit_complexity'])} " + f"| {cells(d['unit_interfacing'])} | {dcell} | {jcell} |") + for lang, s in report.get("structure", {}).items(): + if not s: + continue + e = s["component_entanglement"] + ci = s["component_independence"] + out += ["", f"{lang} structure ({s['modules']} modules, components under `{s['component_root']}`): " + f"module coupling >10/20/50 {cells(s['module_coupling'])}; " + f"component independence {pct(ci['hidden_share'])}{'' if ci['ok'] else ' ✗'} (min {pct(INDEPENDENCE_MIN)}); " + f"entanglement inputs: {e['communication_lines']} lines between {e['connected_components']} components, " + f"density {e['communication_density']}, violation degree {e['violation_degree']}."] + checks = checks_of(report) + out += ["", f"{sum(1 for _c, ok in checks if ok)} of {len(checks)} 4-star checks met. ✗ marks a miss."] + if report["skipped_files"]: + out += ["", f"{len(report['skipped_files'])} file(s) lizard could not read, NOT measured: " + + ", ".join(s["file"] for s in report["skipped_files"][:10])] + return "\n".join(out) + "\n" + + +def cmd_report(args, lizard, jscpd): + report = build_report(args.app, lizard, jscpd) + if args.json: + with open(args.json, "w") as fh: + json.dump(report, fh, indent=1) + md = markdown(report) + if args.md: + with open(args.md, "w") as fh: + fh.write(md) + print(md) + for s in report["skipped_files"]: + print(f" skipped (lizard): {s['file']}: {s['reason']}") + if not report["files"]: + print(f"{GATE}: no measured source file in this repository (php, js, ts, vue, py outside tests and Sigrid's default excludes)") + return 4 + checks = checks_of(report) + missed = [c for c, ok in checks if not ok] + units = sum(d["units"] for d in report["languages"].values()) + print(f"{GATE}: report: {units} unit(s) " + f"in {report['files']} file(s), languages {', '.join(report['languages'])}; " + f"{len(checks) - len(missed)} of {len(checks)} 4-star checks met" + + (f"; missed: {', '.join(missed)}" if missed else "")) + return 0 + + +# -------------------------------------------------------------------------- +# ratchet +# -------------------------------------------------------------------------- + +def added_lines(app, base, rel): + rc, out = git(app, "diff", "-U0", "--no-color", base, "HEAD", "--", rel) + lines = set() + for line in out.splitlines(): + m = re.match(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@", line) + if m: + start, count = int(m.group(1)), int(m.group(2) or 1) + lines.update(range(start, start + count)) + return lines + + +def changed_paths(app, base): + """{new path: old path or None} for files added, copied, modified or renamed.""" + rc, out = git(app, "diff", "--name-status", "-M", "--diff-filter=ACMR", base, "HEAD") + paths = {} + for line in out.splitlines(): + parts = line.split("\t") + if parts[0].startswith(("R", "C")) and len(parts) == 3: + paths[parts[2]] = parts[1] if parts[0].startswith("R") else None + elif len(parts) == 2: + paths[parts[1]] = parts[1] if parts[0] != "A" else None + return paths + + +def cmd_ratchet(args, lizard, jscpd_exe): + app = args.app + rc, mb = git(app, "merge-base", args.base_ref, "HEAD") + if rc != 0 or not mb.strip(): + print(f"{GATE}: the base '{args.base_ref}' has no merge base with HEAD, so no change could be isolated") + return 3 + mb = mb.strip() + scope = Scope(app) + changed = {} + for new, old in changed_paths(app, mb).items(): + lang = scope.language(new) + if lang and os.path.isfile(os.path.join(app, new)): + changed[new] = (lang, old) + if not changed: + print(f"{GATE}: this change touches no measured source file (php, js, ts, vue, py outside tests and Sigrid's default excludes)") + return 4 + + reader = UnitReader(lizard) + new_findings, inherited = [], [] + touched_units = 0 + added = {} + for rel, (lang, old) in sorted(changed.items()): + added[rel] = added_lines(app, mb, rel) + head_units = reader.units(rel, lang, read_text(os.path.join(app, rel))) + base_units = {} + if old: + rc, base_src = git(app, "show", f"{mb}:{old}") + if rc == 0: + for u in reader.units(old, lang, base_src): + base_units.setdefault(u["name"], u) + for u in head_units: + touched = any(u["start"] <= n <= u["end"] for n in added[rel]) + touched_units += touched + before = base_units.get(u["name"]) + for key, bound in RATCHET.items(): + if u[key] <= bound: + continue + f = {"file": rel, "line": u["start"], "unit": u["name"], "metric": key, + "value": u[key], "rule": RATCHET_LABEL[key], + "before": before[key] if before else None} + if not touched: + inherited.append(f) + elif before is None or before[key] <= bound or u[key] > before[key]: + new_findings.append(f) + else: + inherited.append(f) + + # Duplication: clones among every measured file of the languages this change touches. + langs = {lang for lang, _old in changed.values()} + corpus = sorted(f for f, lg in production_files(app, scope).items() if lg in langs) + if not any(len(lines) >= DUP_MIN_LINES for lines in added.values()): + corpus = [] # no file gained 6 lines, so no new clone is possible + dup_new = 0 + for c in run_jscpd(app, jscpd_exe, corpus): + hits = [] + for occ in (c["a"], c["b"]): + f, s, e = occ + if f in added and len(added[f] & c["code"][occ]) >= DUP_MIN_LINES: + hits.append(occ) + if hits: + f, s, e = hits[0] + other = c["b"] if hits[0] == c["a"] else c["a"] + new_findings.append({"file": f, "line": s, "unit": f"lines {s}-{e}", "metric": "duplication", + "value": c["lines"], "rule": f"duplicated fragment of {DUP_MIN_LINES}+ lines", + "before": None, "other": f"{other[0]}:{other[1]}-{other[2]}"}) + dup_new += 1 + + for s in reader.skipped: + print(f" unverified (lizard could not read it): {s['file']}: {s['reason']}") + for f in new_findings: + was = f" (was {f['before']})" if f.get("before") is not None else "" + extra = f", same as {f['other']}" if f.get("other") else "" + print(f" {f['file']}:{f['line']} {f['unit']}: {f['rule']}: {f['value']}{was}{extra}") + if inherited: + print(f" inherited, not counted: {len(inherited)} finding(s) on units this change did not touch " + f"or did not make worse") + for f in inherited[:10]: + print(f" {f['file']}:{f['line']} {f['unit']}: {f['rule']}: {f['value']}") + tail = (f"lizard {LIZARD_VERSION}, jscpd {JSCPD_VERSION}; {len(inherited)} inherited" + + (f"; {len(reader.skipped)} file(s) NOT measured" if reader.skipped else "")) + if new_findings: + print(f"{GATE}: FAIL: {len(new_findings)} finding(s) in {touched_units} changed unit(s) " + f"({dup_new} duplicated fragment(s)); {tail}") + return 1 + print(f"{GATE}: checked {touched_units} changed unit(s) in {len(changed)} file(s), 0 finding(s); {tail}") + return 0 + + +# -------------------------------------------------------------------------- + +def main(argv): + ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) + sub = ap.add_subparsers(dest="mode", required=True) + r = sub.add_parser("ratchet") + r.add_argument("app") + r.add_argument("--base-ref", required=True) + p = sub.add_parser("report") + p.add_argument("app") + p.add_argument("--json") + p.add_argument("--md") + args = ap.parse_args(argv) + args.app = os.path.abspath(args.app) + + lizard, why = load_lizard() + if not lizard: + print(f"{GATE}: tooling: {why}") + return 5 + jscpd, why = find_jscpd() + if not jscpd: + print(f"{GATE}: tooling: {why}") + return 5 + if args.mode == "ratchet": + return cmd_ratchet(args, lizard, jscpd) + return cmd_report(args, lizard, jscpd) + + +# Sigrid's default excludes, verbatim, from +# github.com/Software-Improvement-Group/sigridci resources/default-excludes.txt +# (fetched 2026-10-29). Matched against "/" + the repo-relative path. +SIGRID_DEFAULT_EXCLUDES = r""" +.*/[.]cache/.* +.*/[.]sonarlint/.* +.*/[.]DS_Store +.*/[.]ipynb +.*/[.]class +.*/[.]classpath +.*/[.]project +.*/[.]hg/.* +.*/.*[.][Gg]en(enerated)?[.].* +.*/[.]circleci/.* +.*/[.]git/.* +.*/git[.]log +.*/[.]github/.* +.*/[.]gitlab/.* +.*/[.]gradle/.* +.*/[.]idea/.* +.*/[.]maven/.* +.*/[.]mvn/.* +.*/[.]phpstorm[.]meta[.]php/.* +.*/[.]prettierrc[.]js +.*/[.]settings/.* +.*/[.]svn/.* +.*/[.]teamcity/.* +.*/\$tf/.* +.*/__MACOSX/.* +.*/.*(-|.)min[.](css|js) +.*/.*[.]asm[.]js +.*/.*[.]conf(ig)?[.](js|ts|coffee) +.*/.*[.]es[.]js +.*/.*[.]eslintrc[.]js +.*/.*[.]excl[.]mendix +.*/.*[.]g[.]vb +.*/.*[.]out[.]js +.*/.*[.][Dd]esigner[.]cs +.*/.*[.]style[.](js|jsx|ts|tsx) +.*/.*[.]styles[.](js|jsx|ts|tsx) +.*/.*[.]umd[.]js +.*/.*[.]vendor[.](js|ts) +.*/.*[.]wasm[.]js +.*/3rd(party)?/.* +.*/AppData/.* +.*/[Aa]ssembly[Ii]nfo.* +.*/bin/.* +.*/bitbucket-pipelines[.]yml +.*bootstrap.*[.](js|css) +.*/modernizr.*[.]js +.*/bower_components/.* +.*/branches/.* +.*/build/.* +.*/build[.]rs +.*/contrib/.* +.*/[Dd]ebug/.* +.*/dist/.* +.*/(java)?doc(s)?/.* +.*/environment[.][\w.]*[.](t|j)s +.*/example(s)?/.* +.*/external-files/.* +.*/gen(enerated)?/.* +.*/gradle.*[.]properties +.*/gradlew[.]bat +.*/InvisibleStyleSheet[.]css +.*/jdiff/.* +.*/jquery.*[.](js|css) +.*/library-preload[.]js +.*/LICENSE[.]txt +.*/locale/.*[.]js +.*/log4j.*[.]properties +.*/mapping.*[.]txt +.*/META-INF/.* +.*[Mm]ock.* +.*/[Mm]igrations?/.* +.*/node_modules/.* +.*/open3rd/.* +.*/obj/.* +.*/out/.* +.*/package-info[.]java +.*/[Pp]ods/.* +.*/polyfills[.]js +.*/proguard-rules[.]pro +.*/project[.]properties +.*/public/components/.* +.*/[Rr]elease/.* +.*/Reference[.]cs +.*/sap/.*/libs/.*[.]js +.*/sapui5-rt.* +.*/Service References/.* +.*sigridci.* +.*/sigrid(-metadata)?[.]ya?ml +.*/src/test/resources/.* +.*stub.* +.*/tags/.* +.*/target(-eclipse)?/.* +.*/[Tt]emporary[Gg]enerated[Ff]ile.* +.*/theme/.*[.]css +.*/themes/.*[.]css +.*/[Tt]hird(_|-)?[Pp]arty/.* +.*/[Vv]endor/.* +.*/widgets/com[.]mendix[.].* +.*/widgets/.*/com/mendix/.* +.*/.*vendor.*[.]js +.*pom[.]xml +.*/webpack[.][^/]*[.]js +.*/webpack[.](js|ts) +.*/wwwroot/assets/.* +.*/App[.]config +.*tinymce.* +.*toastify.* +.*x-editable.* +.*/.*[.]editorConfig[.]js +.*/.*[.]editorPreview[.]js +.*[.]gradle +.*[.]gradle[.]kts +.*[.]lock[.]hcl +.*AssemblyInfo[.]cs +.*/[.]sigrid/.* +""".strip().splitlines() + + +if __name__ == "__main__": + sys.exit(main(sys.argv[1:])) diff --git a/hydra-gates/scripts/lib/test_check_sig_maintainability.py b/hydra-gates/scripts/lib/test_check_sig_maintainability.py new file mode 100755 index 00000000..a382710f --- /dev/null +++ b/hydra-gates/scripts/lib/test_check_sig_maintainability.py @@ -0,0 +1,396 @@ +#!/usr/bin/env python3 +# SPDX-FileCopyrightText: 2026 Conduction +# SPDX-License-Identifier: EUPL-1.2 +"""Tests for gate-122's checker (check_sig_maintainability.py), rule by rule. + + 1. UNITS: lizard's PHP parameter count is replaced by the unique $names; + Python `self`/`cls` is not a parameter; a file lizard raises on is listed + as skipped and the rest is still measured. + 2. SCOPE: tests, vendor, Sigrid's default excludes, Nextcloud js/ and l10n/ + are not measured; sigrid.yaml excludes are honoured. + 3. RATCHET on a real git history: + a new unit over each bound is NEW, and names file, line and unit; + a legacy unit touched but not made worse is INHERITED; + a legacy unit made worse is NEW; + an untouched oversize unit is INHERITED; + a new copy of a 6+ line fragment is NEW, an edit inside an existing + clone is not; + a change with no measured source file is exit 4; + a base with no merge base is exit 3. + 4. REPORT: the shares are code-weighted and compared with the 4-star limits. + 5. STRUCTURE: PHP and Python dependencies, the component root, and the + violation degree on the examples in SIG's Guidance for Producers. + +Run: python3 scripts/lib/test_check_sig_maintainability.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_maintainability as sig # noqa: E402 + +LIZARD, WHY = sig.load_lizard() +JSCPD, WHY_JSCPD = sig.find_jscpd() if LIZARD else (None, WHY) +if not LIZARD or not JSCPD: + # A suite that cannot load its tools must not report green. + print(f"FAIL: pinned tools unavailable: {WHY or WHY_JSCPD}") + sys.exit(1) + + +def php_method(name, lines=3, params=1, branches=0, tag="x"): + ps = ", ".join(f"${'p'}{i}" for i in range(params)) + body = "".join(f" if ($p0 === {i}) {{ return strlen('{tag}{i}'); }}\n" for i in range(branches)) + body += "".join(f" ${tag}{i} = {i} + strlen('{tag}{name}');\n" for i in range(lines)) + return f" public function {name}({ps}): int\n {{\n{body} return 0;\n }}\n" + + +def nloc(lines, branches=0): + """lizard's NLOC for php_method(): signature, braces and return add four.""" + return lines + branches + 4 + + +def php_class(name, methods): + return f""), []) + self.assertEqual(self.reader.skipped[0]["file"], "src/X.vue") + self.assertIn("IndexError", self.reader.skipped[0]["reason"]) + + +class ScopeRules(unittest.TestCase): + def setUp(self): + self.repo = Repo() + + def tearDown(self): + self.repo.close() + + def test_measured_and_excluded_paths(self): + s = sig.Scope(self.repo.dir) + self.assertEqual(s.language("lib/Service/A.php"), "php") + self.assertEqual(s.language("src/views/A.vue"), "vue") + self.assertEqual(s.language("src/store/a.ts"), "typescript") + self.assertEqual(s.language("src/api/main.py"), "python") + for rel in ("tests/Unit/ATest.php", "src/a.spec.js", "src/tests/test_x.py", "vendor/x/A.php", + "js/app.js", "l10n/nl.js", "lib/Migration/Version1.php", "webpack.config.js", + "src/__mocks__/a.js", "lib/Service/MockService.php", "docs/a.js", "README.md"): + self.assertIsNone(s.language(rel), rel) + + def test_sigrid_yaml_excludes_are_honoured(self): + self.repo.write("sigrid.yaml", "default_excludes: true\nexclude:\n - \".*/phpmetrics/.*\"\n - .*/generated[.]php\nlanguages:\n - php\n") + s = sig.Scope(self.repo.dir) + self.assertIsNone(s.language("phpmetrics/html/js/d3.v3.js")) + self.assertIsNone(s.language("lib/generated.php")) + self.assertEqual(s.language("lib/languages.php"), "php") + + +class Ratchet(unittest.TestCase): + def setUp(self): + self.repo = Repo() + self.repo.write("lib/Service/Legacy.php", php_class("Legacy", [ + php_method("big", lines=70, tag="a"), + php_method("bigToo", lines=70, tag="b"), + php_method("copyOne", lines=1, tag="c").replace(" return 0;", DUP_BLOCK + " return 0;"), + php_method("small", lines=3, tag="d"), + ])) + self.repo.write("README.md", "fixture\n") + self.repo.commit("base") + self.repo.git("branch", "-M", "base") + self.repo.git("checkout", "-q", "-b", "change") + + def tearDown(self): + self.repo.close() + + def edit(self, old, new, rel="lib/Service/Legacy.php"): + path = os.path.join(self.repo.dir, rel) + with open(path) as fh: + text = fh.read() + self.assertIn(old, text) + with open(path, "w") as fh: + fh.write(text.replace(old, new, 1)) + + def ratchet(self): + self.repo.commit("change") + return run("ratchet", self.repo.dir, "--base-ref", "base") + + def add_class(self, methods): + self.repo.write("lib/Service/Fresh.php", php_class("Fresh", methods)) + + def test_new_units_over_each_bound_are_new_findings(self): + self.add_class([php_method("long", lines=62, tag="e"), php_method("wide", params=5, tag="f"), + php_method("branchy", branches=11, tag="g"), php_method("fine", params=4, branches=9, tag="h")]) + rc, out = self.ratchet() + self.assertEqual(rc, 1, out) + self.assertIn(f"lib/Service/Fresh.php:6 Fresh::long: NLOC > 60: {nloc(62)}", out) + self.assertIn("Fresh::wide: 5 or more parameters: 5", out) + self.assertIn("Fresh::branchy: McCabe > 10: 12", out) + self.assertNotIn("Fresh::fine", out) + self.assertIn("[gate-122] sig-maintainability: FAIL: 3 finding(s)", out) + + def test_bounds_are_exclusive(self): + self.add_class([php_method("edge", lines=47, params=4, branches=9, tag="e")]) + self.assertEqual(nloc(47, 9), 60) + rc, out = self.ratchet() + self.assertEqual(rc, 0, out) + self.assertIn("checked 1 changed unit(s) in 1 file(s), 0 finding(s)", out) + + def test_touched_legacy_unit_not_made_worse_is_inherited(self): + self.edit("$a5 = 5 + strlen('abig');", "$a5 = 6 + strlen('abig');") + rc, out = self.ratchet() + self.assertEqual(rc, 0, out) + self.assertIn("inherited, not counted", out) + self.assertIn(f"Legacy::big: NLOC > 60: {nloc(70)}", out) + + def test_legacy_unit_made_worse_is_new(self): + self.edit("$a5 = 5 + strlen('abig');", "$a5 = 5 + strlen('abig');\n $grow = 1;") + rc, out = self.ratchet() + self.assertEqual(rc, 1, out) + self.assertIn(f"Legacy::big: NLOC > 60: {nloc(71)} (was {nloc(70)})", out) + self.assertNotIn("Legacy::bigToo: NLOC", out.split("inherited")[0]) + + def test_new_copy_of_a_fragment_is_new_and_names_the_original(self): + self.add_class([php_method("copyTwo", lines=1, tag="z").replace(" return 0;", DUP_BLOCK + " return 0;")]) + rc, out = self.ratchet() + self.assertEqual(rc, 1, out) + self.assertIn("duplicated fragment of 6+ lines", out) + self.assertIn("same as lib/Service/Legacy.php:", out) + + def test_a_clone_of_mostly_comment_lines_is_not_six_lines_of_code(self): + # The openregister #5008 shape: jscpd's weak mode matches across a + # docblock, so a long "fragment" can hold three lines of code. + tail = (" $this->addType(fieldName: 'linkedBy', type: 'string', nullable: true, default: null);\n }\n\n" + " /**\n" + "".join(f" * Line {i} of a long explanation of the method below.\n" for i in range(9)) + + " */\n") + self.repo.git("checkout", "-q", "base") + self.repo.write("lib/Service/First.php", php_class("First", [" public function __construct()\n {\n" + tail + + php_method("one", lines=2, tag="o")])) + self.repo.commit("base with the first copy") + self.repo.git("checkout", "-q", "-B", "change", "base") + self.repo.write("lib/Service/Second.php", php_class("Second", [" public function __construct()\n {\n" + tail + + php_method("two", lines=2, tag="t")])) + rc, out = self.ratchet() + self.assertEqual(rc, 0, out) + self.assertNotIn("duplicated fragment", out) + # Five equal code lines are not a SIG clone, so the report counts no redundant code either. + clones = sig.run_jscpd(self.repo.dir, JSCPD, ["lib/Service/First.php", "lib/Service/Second.php"]) + self.assertEqual(clones, []) + + def test_edit_inside_an_existing_clone_is_not_new(self): + self.repo.git("checkout", "-q", "base") + self.repo.write("lib/Service/Twin.php", php_class("Twin", [ + php_method("copyTwo", lines=1, tag="y").replace(" return 0;", DUP_BLOCK + " return 0;")])) + self.repo.commit("base with an existing clone") + self.repo.git("checkout", "-q", "-B", "change", "base") + # Re-indent two lines inside the clone (still a clone in jscpd's weak + # mode) and add an unrelated method, so the clone search does run. + self.edit(" $shared4 = $p0 * 4 + 28;\n $shared5", " $shared4 = $p0 * 4 + 28;\n $shared5", + rel="lib/Service/Twin.php") + self.edit("class Twin\n{\n", "class Twin\n{\n" + php_method("unrelated", lines=8, tag="u"), rel="lib/Service/Twin.php") + rc, out = self.ratchet() + self.assertEqual(rc, 0, out) + self.assertNotIn("duplicated fragment", out) + + def test_a_change_with_no_measured_source_is_not_applicable(self): + self.repo.write("README.md", "changed\n") + self.repo.write("tests/Unit/FreshTest.php", php_class("FreshTest", [php_method("t", lines=80)])) + rc, out = self.ratchet() + self.assertEqual(rc, 4, out) + self.assertIn("touches no measured source file", out) + + def test_an_unrelated_base_is_exit_3(self): + self.repo.git("checkout", "-q", "--orphan", "other") + self.repo.write("lib/Other.php", "B 10, B->C 8, C->D 3, D->A 15, no direct pair. + degree, kinds, examples = sig.violation_degree({("A", "B"): 10, ("B", "C"): 8, ("C", "D"): 3, ("D", "A"): 15}) + self.assertEqual(kinds, {"indirect-cyclic": 1}) + self.assertIn("C -> D (indirect-cyclic)", examples) + + def test_violation_degree_transitive(self): + # Guidance figure 11 shape: B->C->D and a lighter direct B->D; D has an outgoing line. + lines = {("B", "C"): 10, ("C", "D"): 14, ("B", "D"): 1, ("D", "E"): 18} + degree, kinds, examples = sig.violation_degree(lines) + self.assertEqual(kinds, {"transitive": 1}) + self.assertIn("B -> D (transitive)", examples) + # Heavier than the path it bypasses: not a violation. + _d, kinds, _e = sig.violation_degree({**lines, ("B", "D"): 50}) + self.assertEqual(kinds, {}) + + def test_component_root_descends_into_the_dominant_directory(self): + # lib/Service holding 71% of lib/ (filinq) must not become the root. + files = [f"lib/Service/X{i}.php" for i in range(71)] + [f"lib/Db/X{i}.php" for i in range(28)] + ["lib/AppInfo.php"] + root, comp = sig.component_of_factory(files) + self.assertEqual(root, "lib") + self.assertEqual(comp("lib/Service/X1.php"), "Service") + self.assertEqual(comp("lib/AppInfo.php"), "(root)") + + def test_component_root_in_a_python_service_and_modules_outside_it(self): + files = ["src/__init__.py", "src/api/main.py", "src/api/routers/a.py", "src/api/routers/b.py", + "src/api/utils/c.py", "src/api/utils/d.py", "src/api/utils/e.py", "src/api/utils/f.py", + "src/api/services/g.py", "src/api/services/h.py", "scripts/run.py", "api.py"] + root, comp = sig.component_of_factory(files) + self.assertEqual(root, "src/api") + self.assertEqual(comp("src/api/routers/a.py"), "routers") + self.assertEqual(comp("src/api/main.py"), "(root)") + self.assertEqual(comp("scripts/run.py"), "scripts") + self.assertEqual(comp("api.py"), "(top)") + self.assertEqual(comp("src/__init__.py"), "src") + + def test_php_and_python_dependencies(self): + repo = Repo() + try: + repo.write("lib/Service/A.php", " -> a small PHP method + local _p="" _i + for _i in $(seq 1 "$2"); do _p="${_p}${_p:+, }\$p${_i}"; done + printf ' public function %s(%s): int\n {\n return strlen(\x27%s\x27);\n }\n' "$1" "${_p}" "$1" +} +_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 +_class Base "$(_method existing 1)" +printf 'fixture\n' > README.md +git add -A && git commit --quiet -m "base" +git branch -M base + +_branch() { git checkout --quiet base && git checkout --quiet -b "$1"; } + +_branch planted +_class Fresh "$(_method wide 5)" +git add -A && git commit --quiet -m "a five-parameter unit" + +_branch clean +_class Fresh "$(_method narrow 2)" +git add -A && git commit --quiet -m "a small unit" + +_branch docs +printf 'changed\n' > README.md +git commit --quiet -am "docs only" + +_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-122\] sig-maintainability: (PASS|FAIL|WARNING|SKIPPED|NOT APPLICABLE)' | head -1 +} + +echo "-- ARM 1: a five-parameter unit: WARNING --" +_out="$(_run planted --base base)" +_v="$(_verdict "${_out}")" +case "${_v}" in + *WARNING*) _ok "a new wide unit warns" ;; + *) _bad "expected WARNING, got: ${_v:-}" ;; +esac +if printf '%s\n' "${_out}" | grep -q 'lib/Service/Fresh.php:6 Fresh::wide: 5 or more parameters: 5'; then + _ok "the finding names the file, line and unit" +else + _bad "the finding does not name lib/Service/Fresh.php:6 Fresh::wide" +fi + +echo "-- ARM 2: the promotion switch blocks --" +_v="$(_verdict "$(HYDRA_GATE_SIG_MAINTAINABILITY_BLOCKING=1 _run planted --base base)")" +case "${_v}" in + *FAIL*) _ok "HYDRA_GATE_SIG_MAINTAINABILITY_BLOCKING=1 makes it FAIL" ;; + *) _bad "expected FAIL with the switch on, got: ${_v:-}" ;; +esac + +echo "-- ARM 3: a small unit: PASS with the census line --" +_out="$(_run clean --base base)" +_v="$(_verdict "${_out}")" +case "${_v}" in + *PASS*) _ok "a small unit passes" ;; + *) _bad "expected PASS, got: ${_v:-}" ;; +esac +if printf '%s\n' "${_out}" | grep -q '^\[gate-122\] sig-maintainability: checked 1 changed unit(s) in 1 file(s), 0 finding(s)'; then + _ok "the census line counts what was judged" +else + _bad "no census line in the PASS output" +fi + +echo "-- ARM 4: no delta base: report mode --" +REPORTS="${WORK}/reports" +_out="$(HYDRA_GATE_SIG_REPORT_DIR="${REPORTS}" _run planted)" +_v="$(_verdict "${_out}")" +case "${_v}" in + *PASS*) _ok "a full-scope run with no base reports and passes" ;; + *) _bad "expected PASS (report-only), got: ${_v:-}" ;; +esac +if [ -s "${REPORTS}/sig-profile.json" ] && [ -s "${REPORTS}/sig-profile.md" ] \ + && python3 -c 'import json,sys; d=json.load(open(sys.argv[1])); sys.exit(0 if d["languages"]["php"]["units"] == 2 else 1)' "${REPORTS}/sig-profile.json"; then + _ok "sig-profile.json (2 php units) and sig-profile.md are written to HYDRA_GATE_SIG_REPORT_DIR" +else + _bad "the report files are missing or do not count the 2 php units" +fi +if printf '%s\n' "${_out}" | grep -q '^\[gate-122\] sig-maintainability: report: 2 unit(s) in 2 file(s)'; then + _ok "the report census line reaches the run's output" +else + _bad "no report census line in the run's output" +fi + +echo "-- ARM 5: docs only: NOT APPLICABLE --" +_v="$(_verdict "$(_run docs --base base)")" +case "${_v}" in + *"NOT APPLICABLE"*) _ok "a change with no measured source is not applicable" ;; + *) _bad "expected NOT APPLICABLE, got: ${_v:-}" ;; +esac + +echo "-- ARM 6: 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-122 scope: all arms passed" + exit 0 +fi +echo "gate-122 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 a2a30db8..1fd0c74b 100755 --- a/hydra-gates/scripts/run-hydra-gates.sh +++ b/hydra-gates/scripts/run-hydra-gates.sh @@ -13587,6 +13587,101 @@ else fi fi +# --------------------------------------------------------------------------- +# gate-122: sig-maintainability +# +# The Software Improvement Group (SIG, Sigrid) rates maintainability per +# language from risk profiles: how much code sits in units above a size, +# complexity or parameter bound, plus duplication and architecture. Its 4-star +# limits are far stricter than phpmd at the fleet's defaults (CC 10, methods up +# to 100 lines, 10 parameters, with baselines). Measured 2026-10-29 with +# lizard 1.24.3 and jscpd 4.0.5: openregister, opencatalogi and openconnector +# all miss unit size, complexity and interfacing in PHP; openregister keeps +# 17.7% of its PHP in units over 60 lines against a limit of 8.3%. +# +# Two modes, chosen by whether a delta base exists: +# * delta base -> RATCHET. A unit the change adds or edits fails when it has +# NLOC > 60, McCabe > 10 or 5+ parameters, and so does a duplicated +# fragment of 6+ lines the change introduces. A unit that was already over +# the bound and did not get worse is inherited, and so is everything the +# change did not touch. +# * no delta base (a full-scope run: the nightly drift sweep, a dispatch) -> +# REPORT. The whole risk profile against the 4-star limits, written to +# sig-profile.json and sig-profile.md in $HYDRA_GATE_SIG_REPORT_DIR (the +# log directory by default). Report-only: it PASSES with its census line. +# +# Ships as a WARNING under the fleet rule for new gates: the package resolves +# at @main for every core app, so a blocking ratchet would land everywhere the +# minute it merged. HYDRA_GATE_SIG_MAINTAINABILITY_BLOCKING=1 makes it block. +# --------------------------------------------------------------------------- +_sig_log=${HYDRA_GATE_LOG_DIR}/hydra-gate-sig-maintainability.log +: > "${_sig_log}" +_sig_helper="${SCRIPT_DIR}/lib/check_sig_maintainability.py" +_sig_report_dir="${HYDRA_GATE_SIG_REPORT_DIR:-${HYDRA_GATE_LOG_DIR}}" +if [ ! -f "${_sig_helper}" ]; then + _skip 122 "sig-maintainability" wiring "check_sig_maintainability.py not found at ${_sig_helper}, so no unit was measured by this run." +elif ! command -v python3 > /dev/null 2>&1; then + _skip 122 "sig-maintainability" wiring "python3 is not on PATH, so no unit was measured by this run." +else + set +e + if [ "${HAVE_DELTA_BASE}" = "1" ]; then + _sig_mode=ratchet + python3 "${_sig_helper}" ratchet . --base-ref "${BASE_REF}" > "${_sig_log}" 2>&1 + _sig_rc=$? + else + _sig_mode=report + mkdir -p "${_sig_report_dir}" 2>/dev/null + python3 "${_sig_helper}" report . --json "${_sig_report_dir}/sig-profile.json" \ + --md "${_sig_report_dir}/sig-profile.md" > "${_sig_log}" 2>&1 + _sig_rc=$? + fi + set +e + _sig_why=$(tail -3 "${_sig_log}" 2>/dev/null | tr '\n' ' ' | cut -c1-240) + case "${_sig_rc}" in + 0) + if [ "${_sig_mode}" = "ratchet" ] \ + && _helper_finished "${_sig_log}" '^\[gate-122\] sig-maintainability: checked [0-9]+ changed unit'; then + grep -E '^ (unverified|inherited)' "${_sig_log}" 2>/dev/null + grep -E '^\[gate-122\] sig-maintainability: checked' "${_sig_log}" + _pass 122 "sig-maintainability" + elif [ "${_sig_mode}" = "report" ] \ + && _helper_finished "${_sig_log}" '^\[gate-122\] sig-maintainability: report: [0-9]+ unit'; then + grep -E '^\| ' "${_sig_log}" 2>/dev/null + grep -E '^\[gate-122\] sig-maintainability: report:' "${_sig_log}" + echo "[gate-122] sig-maintainability: profile written to ${_sig_report_dir}/sig-profile.json and sig-profile.md (report-only)" + _pass 122 "sig-maintainability" + else + _skip 122 "sig-maintainability" wiring "check_sig_maintainability.py exited 0 without its ${_sig_mode} census line, so nothing is verified by this run. Checker output: ${_sig_why:-}. See ${_sig_log}." + fi + ;; + 1) + if [ "${_sig_mode}" = "ratchet" ] \ + && _helper_finished "${_sig_log}" '^\[gate-122\] sig-maintainability: FAIL: [0-9]+ finding'; then + grep -E '^ [^ ]' "${_sig_log}" 2>/dev/null + _sig_n=$(sed -n 's/^\[gate-122\] sig-maintainability: FAIL: \([0-9]*\) finding.*/\1/p' "${_sig_log}" | tail -1) + _sig_msg="${_sig_n:-1} unit(s) or duplicated fragment(s) this change adds or makes worse exceed the SIG ratchet (NLOC > 60, McCabe > 10, 5+ parameters, or a new 6+ line clone). Split the unit, pass a value object, or reuse the existing code. See ${_sig_log}" + if [ "${HYDRA_GATE_SIG_MAINTAINABILITY_BLOCKING:-0}" = "1" ]; then + _fail 122 "sig-maintainability" "${_sig_msg}" + else + _warn 122 "sig-maintainability" "${_sig_msg} (warning; HYDRA_GATE_SIG_MAINTAINABILITY_BLOCKING=1 makes it block)" + fi + else + # A CRASH IS NOT A FINDING. A Python traceback also exits 1. + _skip 122 "sig-maintainability" wiring "check_sig_maintainability.py exited 1 without its FAIL summary, so it did not finish and nothing is verified by this run. Checker output: ${_sig_why:-}. See ${_sig_log}." + fi + ;; + 4) + _skip 122 "sig-maintainability" na "$(tail -1 "${_sig_log}" 2>/dev/null | sed 's/^\[gate-122\] sig-maintainability: //' | cut -c1-240)" + ;; + 5) + _skip 122 "sig-maintainability" wiring "a pinned measuring tool is unavailable, so no unit was measured by this run: ${_sig_why:-}. See ${_sig_log}." + ;; + *) + _skip 122 "sig-maintainability" wiring "check_sig_maintainability.py exited ${_sig_rc} without a verdict, so nothing is verified by this run. Checker output: ${_sig_why:-}. See ${_sig_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 63af03bf..51f4c2fa 100644 --- a/hydra-gates/scripts/test-fixtures/gate-acceptance/COVERED-ELSEWHERE.md +++ b/hydra-gates/scripts/test-fixtures/gate-acceptance/COVERED-ELSEWHERE.md @@ -57,6 +57,7 @@ with the missing half named. | gate-119 | procedure-code | `test_gate119_procedure_code_scope.sh` + `test_check_procedure_code.py` | builds a real git history in a tmpdir. A ratchet against a committed baseline cannot be covered by a bundle, which has no history to lift a baseline in. ARM 1 pins the convention for the PR that adds the gate: no `.procedure-code-baseline.json` is NOT APPLICABLE, never PASS. ARM 2 is equality, PASS with the census line. ARM 3 adds a procedure-named class and FAILS. ARM 4 removes one without lowering the baseline and FAILS naming the number to write. ARM 5 removes and lowers together and PASSES. ARM 6 raises the baseline and FAILS. ARM 7 adds a `lib/Service/Zgw/` file and a `Stuf` name and the count does not move. ARM 8 is a baseline that is not JSON: FAIL, not NOT APPLICABLE. ARM 9 is a config the checker cannot read: SKIPPED (wiring). ARM 10 runs full scope, since the gate is not a delta gate. The rule-by-rule arms (every configured token, class-name matches, whole-word short tokens, the allowlist by word and by path, scope, ref mode agreeing with working-tree mode) are in the Python suite. | | 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-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}` |