From c67bf79fc69897bc971e1b66825767e983df6c82 Mon Sep 17 00:00:00 2001 From: Ruben van der Linde Date: Thu, 5 Nov 2026 11:44:17 +0100 Subject: [PATCH 1/6] feat(hydra-gates): gate 122 estimates the SIG maintainability rating and its levers The report now carries `rating`: a continuous 0.5 to 5.5 estimate per check (Alves, Correia and Visser 2011, eq. 1), per property and language, per property across languages (weighted by code), per sub-characteristic and overall. SIG publishes no power-mean exponent for the 2026 model, so the overall rating is reported under p = 1 and p = -1 as a range. Levers: per property and language, the overall gain from fixing the next 1,000 exposed lines worst band first, and the lines needed to raise the property by 0.5. A lever is sure when it ranks in the top 3 under both exponents. Report rows now also carry the lines above each bound. Component independence and entanglement get assumed 3 and 2 star caps for the estimate only; their discrete check still reads <4 below 4 stars. Assisted-by: ClaudeCode:claude-opus-5-5 --- .../scripts/lib/check_sig_maintainability.py | 283 +++++++++++++++++- .../lib/test_check_sig_maintainability.py | 143 +++++++++ 2 files changed, 421 insertions(+), 5 deletions(-) diff --git a/hydra-gates/scripts/lib/check_sig_maintainability.py b/hydra-gates/scripts/lib/check_sig_maintainability.py index e56db257..6e03d97b 100755 --- a/hydra-gates/scripts/lib/check_sig_maintainability.py +++ b/hydra-gates/scripts/lib/check_sig_maintainability.py @@ -49,6 +49,16 @@ than 2. Component independence and entanglement have no band under 4 stars and read "<4" there. Chosen with --profile, or HYDRA_GATE_SIG_PROFILE when the flag is absent. + +RATING ESTIMATE (report mode) +----------------------------- +`rating` in the JSON, and a paragraph in the markdown: an estimate of SIG's +continuous rating (0.5 to 5.5) per check, property, sub-characteristic and +overall, and the levers that raise the overall rating most per 1,000 lines +fixed. SIG publishes no power-mean exponent, so the overall rating is a range +over p = 1 and p = -1. The method and its assumptions are listed above +rating_estimate() and in research/sig-stars.md section 4. The profile does +not change the estimate. The profile changes only the limits a report is compared with; the ratchet's unit bounds and the gate's advisory status do not change. @@ -567,8 +577,9 @@ def profile(units, key, limits, kind): total = sum(u["nloc"] for u in units) or 1 rows = [] for i, (bound, cap) in enumerate(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, + loc = sum(u["nloc"] for u in units if u[key] > bound) + share = loc / total + rows.append({"above": bound, "share": round(share, 4), "loc": loc, "limit": cap, "ok": share <= cap, "stars": stars_of(kind, round(share, 4), i)}) return rows @@ -853,8 +864,9 @@ def structure(app, files, deps, prof=PROFILES[DEFAULT_PROFILE]): total = sum(loc.values()) or 1 coupling = [] for i, (bound, cap) in enumerate(prof["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, + above = sum(loc[m] for m in modules if len(incoming[m]) > bound) + share = above / total + coupling.append({"above": bound, "share": round(share, 4), "loc": above, "limit": cap, "ok": share <= cap, "stars": stars_of("module_coupling", round(share, 4), i)}) 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])) @@ -878,7 +890,8 @@ def structure(app, files, deps, prof=PROFILES[DEFAULT_PROFILE]): 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": prof["independence_min"], + "component_independence": {"hidden_share": round(independence, 4), "hidden_loc": hidden, + "limit_min": prof["independence_min"], "ok": independence >= prof["independence_min"], "stars": stars_of("component_independence", round(independence, 4))}, "component_entanglement": { @@ -948,6 +961,7 @@ def build_report(app, lizard, jscpd, profile_name=DEFAULT_PROFILE, reader=None): report["structure"]["php"] = structure(app, php, php_dependencies(app, php), prof) if py: report["structure"]["python"] = structure(app, py, python_dependencies(app, py), prof) + report["rating"] = rating_estimate(report) return report @@ -969,10 +983,268 @@ def checks_of(report): return out +# ---- rating estimate --------------------------------------------------------- +# +# An estimate of SIG's continuous maintainability rating (0.5 to 5.5), built +# from the report. Sources and assumptions: research/sig-stars.md section 4. +# check Alves, Correia, Visser 2011, eq. 1: linear interpolation +# between the caps of the star level a share falls in; a +# property is the minimum over its checks. Worse than 2 stars +# falls linearly to 0.5 at 100% (assumed). +# language a property's per-language ratings, weighted by the code that +# property measures in each language (assumed). +# sub-char. plain mean of the mapped properties (criteria v12.0 mapping, +# volume and component balance dropped). +# overall power mean of the sub-characteristics. SIG publishes no +# exponent, so p = 1 and p = -1 are both reported. + +# Assumed caps on the exposed share (1 - hidden) and on the violation degree. +# Only 4 stars is published; every level doubles the exposure of the one above. +RATING_EXPOSED_CAPS = { + "component_independence": {5: .0275, 4: .055, 3: .11, 2: .22}, + "component_entanglement": {5: .0375, 4: .075, 3: .15, 2: .30}, +} +RATED_PROPERTIES = ("duplication", "unit_size", "unit_complexity", "unit_interfacing", + "module_coupling", "component_independence", "component_entanglement") +SUBCHARACTERISTICS = { + "analysability": ("duplication", "unit_size"), + "modifiability": ("duplication", "unit_complexity", "module_coupling"), + "testability": ("unit_complexity", "component_independence"), + "modularity": ("module_coupling", "component_independence", "component_entanglement"), + "reusability": ("unit_size", "unit_interfacing"), +} +EXPONENTS = (1, -1) +LEVER_LOC = 1000 +SURE_TOP = 3 + + +def rating_caps(kind, index=None): + """{5: cap, 4: cap, 3: cap, 2: cap} of one check, as a maximum exposed share.""" + if kind in RATING_EXPOSED_CAPS: + return RATING_EXPOSED_CAPS[kind] + bands = STAR_BANDS[kind] + return {lvl: bands[lvl] if index is None else bands[lvl][index] for lvl in (5, 4, 3, 2)} + + +def interpolate(value, caps): + """Continuous rating of one exposed share: s0 + 0.5 - (v - t0) / (t1 - t0), + t0 and t1 the caps around v (0 below 5 stars, 100% past 2 stars).""" + lower = 0.0 + for level in (5, 4, 3, 2): + if value <= caps[level]: + start, upper = level, caps[level] + break + lower = caps[level] + else: + start, upper = 1, 1.0 + if upper <= lower: + return start + 0.5 + return max(0.5, min(5.5, start + 0.5 - (value - lower) / (upper - lower))) + + +def power_mean(values, p): + values = [v for v in values if v is not None] + if not values: + return None + if p == 0: + product = 1.0 + for v in values: + product *= v + return product ** (1 / len(values)) + return (sum(v ** p for v in values) / len(values)) ** (1 / p) + + +def rating_inputs(report): + """{property: {language: {"loc": weight, "above": [exposed loc per check]}}} + from a gate-122 report. Entanglement carries "value" (the violation degree) + instead of exposed loc. Reports written before rows carried "loc" are + read from share x total.""" + def above(rows, total): + return [r["loc"] if "loc" in r else round(r["share"] * total) for r in rows] + out = {prop: {} for prop in RATED_PROPERTIES} + for lang, d in report.get("languages", {}).items(): + total = d.get("unit_loc") or 0 + for prop in ("unit_size", "unit_complexity", "unit_interfacing"): + out[prop][lang] = {"loc": total, "above": above(d[prop], total)} + dup = d.get("duplication") + if dup: + out["duplication"][lang] = {"loc": dup["code_lines"], "above": [dup["redundant_lines"]]} + for lang, s in (report.get("structure") or {}).items(): + if not s: + continue + total = s["module_loc"] + out["module_coupling"][lang] = {"loc": total, "above": above(s["module_coupling"], total)} + ci = s["component_independence"] + hidden = ci["hidden_loc"] if "hidden_loc" in ci else round(ci["hidden_share"] * total) + out["component_independence"][lang] = {"loc": total, "above": [total - hidden]} + out["component_entanglement"][lang] = {"loc": total, "value": s["component_entanglement"]["violation_degree"]} + return out + + +def check_ratings(prop, entry): + """The continuous rating of each check of one property in one language.""" + if "value" in entry: + return [interpolate(entry["value"], rating_caps(prop))] + single = len(entry["above"]) == 1 + return [interpolate(a / entry["loc"], rating_caps(prop, None if single else i)) + for i, a in enumerate(entry["above"])] + + +def property_rating(prop, entry): + if not entry or not entry.get("loc"): + return None + return min(check_ratings(prop, entry)) + + +def rate_inputs(inputs): + """Property, sub-characteristic and overall ratings of rating_inputs().""" + props = {} + for prop in RATED_PROPERTIES: + langs = {lang: (property_rating(prop, e), e["loc"]) for lang, e in inputs.get(prop, {}).items()} + weighted = [(r, w) for r, w in langs.values() if r is not None and w] + rating = sum(r * w for r, w in weighted) / sum(w for _r, w in weighted) if weighted else None + props[prop] = {"rating": rating, + "languages": {lg: {"rating": r, "loc": w} for lg, (r, w) in langs.items() if r is not None}} + subs = {} + for sub, members in SUBCHARACTERISTICS.items(): + subs[sub] = power_mean([props[m]["rating"] for m in members], 1) + overall = {p: power_mean(list(subs.values()), p) for p in EXPONENTS} + return {"properties": props, "subcharacteristics": subs, "overall": overall} + + +def fix_loc(prop, entry, n): + """`entry` with n exposed lines brought to low risk, worst band first: the + lines above the highest bound go before those above the next one down. + Fixed duplication is removed code, so it also leaves the total.""" + above = list(entry["above"]) + exclusive = [a - b for a, b in zip(above, above[1:] + [0])] + left = n + for i in reversed(range(len(exclusive))): + take = min(left, exclusive[i]) + exclusive[i] -= take + left -= take + cumulative = [sum(exclusive[i:]) for i in range(len(exclusive))] + total = entry["loc"] - (n - left if prop == "duplication" else 0) + return {"loc": total, "above": cumulative} + + +def with_entry(inputs, prop, lang, entry): + out = {p: dict(v) for p, v in inputs.items()} + out[prop][lang] = entry + return out + + +def levers(inputs, base=None): + """For every property and language: how much the overall rating rises when + the next LEVER_LOC exposed lines (or all of them, when fewer) move to low + risk, worst band first (a finite difference, under each exponent), and the + lines needed to raise the property by 0.5. Ranked by that gain under each + exponent and listed by the sum of both ranks; "sure" when a lever is in the + top SURE_TOP under every exponent.""" + base = base or rate_inputs(inputs) + if all(base["overall"][p] is None for p in EXPONENTS): + return [] + out = [] + for prop in RATED_PROPERTIES: + for lang, entry in sorted(inputs.get(prop, {}).items()): + if "value" in entry or not entry.get("loc") or entry["above"][0] <= 0: + continue + n = min(LEVER_LOC, entry["above"][0]) + after = rate_inputs(with_entry(inputs, prop, lang, fix_loc(prop, entry, n))) + out.append({"property": prop, "language": lang, "fixable_loc": entry["above"][0], "fixed_loc": n, + "gain_per_kloc": {p: after["overall"][p] - base["overall"][p] for p in EXPONENTS}, + "loc_for_half_star": loc_for_half_star(inputs, prop, lang, + base["properties"][prop]["rating"])}) + for p in EXPONENTS: + for rank, lever in enumerate(sorted(out, key=lambda lv: (-lv["gain_per_kloc"][p], lv["property"], + lv["language"])), 1): + lever.setdefault("rank", {})[p] = rank + for lever in out: + lever["sure"] = all(lever["rank"][p] <= SURE_TOP for p in EXPONENTS) + return sorted(out, key=lambda lv: (sum(lv["rank"].values()), lv["rank"][-1])) + + +def loc_for_half_star(inputs, prop, lang, before): + """Fewest lines fixed in one language that raise the property's + cross-language rating by 0.5, or None when fixing all of them does not.""" + entry = inputs[prop][lang] + target = min(before + 0.5, 5.5) + + def reached(n): + after = rate_inputs(with_entry(inputs, prop, lang, fix_loc(prop, entry, n))) + return after["properties"][prop]["rating"] >= target - 1e-9 + high = entry["above"][0] + if not reached(high): + return None + low = 0 + while high - low > 1: + mid = (low + high) // 2 + if reached(mid): + high = mid + else: + low = mid + return high + + +def rating_estimate(report): + """The rating section of a report: every level, the range, the levers.""" + inputs = rating_inputs(report) + rated = rate_inputs(inputs) + overall = [v for v in rated["overall"].values() if v is not None] + + def r2(x): + return None if x is None else round(x, 2) + return { + "note": "Estimate of SIG's maintainability rating, 0.5 to 5.5. SIG publishes 4-star limits only and " + "no power-mean exponent, so the overall rating is a range over p = 1 and p = -1.", + "overall": {"p1": r2(rated["overall"][1]), "p-1": r2(rated["overall"][-1]), + "range": [r2(min(overall)), r2(max(overall))] if overall else None}, + "subcharacteristics": {k: r2(v) for k, v in rated["subcharacteristics"].items()}, + "properties": {k: {"rating": r2(v["rating"]), + "languages": {lg: {"rating": r2(x["rating"]), "loc": x["loc"]} + for lg, x in v["languages"].items()}} + for k, v in rated["properties"].items()}, + "levers": [{"property": lv["property"], "language": lv["language"], + "fixable_loc": lv["fixable_loc"], "fixed_loc": lv["fixed_loc"], + "gain_per_kloc": {"p1": round(lv["gain_per_kloc"][1], 4), + "p-1": round(lv["gain_per_kloc"][-1], 4)}, + "rank": {"p1": lv["rank"][1], "p-1": lv["rank"][-1]}, + "sure": lv["sure"], "loc_for_half_star": lv["loc_for_half_star"]} + for lv in levers(inputs, rated)], + } + + def pct(x): return f"{x * 100:.1f}%" +def rating_markdown(rating, top=5): + """The rating estimate as markdown lines: range, sub-characteristics, properties, levers.""" + if not rating or not rating["overall"]["range"]: + return [] + + def r(x): + return "n/a" if x is None else f"{x:.2f}" + lo, hi = rating["overall"]["range"] + out = ["", f"Estimated SIG maintainability rating: {lo:.2f} to {hi:.2f} " + f"(power mean p = -1 {r(rating['overall']['p-1'])}, p = 1 {r(rating['overall']['p1'])}). " + "An estimate: SIG publishes only the 4-star limits and no exponent.", "", + "Sub-characteristics: " + ", ".join(f"{k} {r(v)}" for k, v in rating["subcharacteristics"].items()) + ".", + "Properties: " + ", ".join(f"{k.replace('_', ' ')} {r(v['rating'])}" + for k, v in rating["properties"].items()) + "."] + if rating["levers"]: + out += ["", f"Levers: the overall gain from fixing the next {LEVER_LOC:,} exposed lines (fewer when fewer " + "exist), worst band first.", "", + "| lever | fixable lines | gain, p = 1 / p = -1 | lines for +0.5 | sure |", "|---|---|---|---|---|"] + for lv in rating["levers"][:top]: + half = (f"{lv['loc_for_half_star']:,}" if lv["loc_for_half_star"] is not None + else f"not by {lv['language']} alone") + out.append(f"| {lv['property'].replace('_', ' ')} ({lv['language']}) | {lv['fixable_loc']:,} | " + f"{lv['gain_per_kloc']['p1']:+.4f} / {lv['gain_per_kloc']['p-1']:+.4f} | {half} | " + f"{'yes' if lv['sure'] else 'no'} |") + return out + + def markdown(report): out = [f"## SIG maintainability profile: {report['app']}", "", f"lizard {LIZARD_VERSION}, jscpd {JSCPD_VERSION}; limits: {report['limits']}. " @@ -1002,6 +1274,7 @@ def cells(rows): 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)} {report['stars']} checks met. ✗ marks a miss."] + out += rating_markdown(report.get("rating")) 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])] diff --git a/hydra-gates/scripts/lib/test_check_sig_maintainability.py b/hydra-gates/scripts/lib/test_check_sig_maintainability.py index 9537946a..091c8fbd 100755 --- a/hydra-gates/scripts/lib/test_check_sig_maintainability.py +++ b/hydra-gates/scripts/lib/test_check_sig_maintainability.py @@ -30,6 +30,12 @@ entanglement below 4 stars); HYDRA_GATE_SIG_PROFILE picks the profile, --profile overrides it, four-star is the default, and an unknown profile is exit 2. + 7. RATING: the interpolation reproduces the worked example of Alves, + Correia and Visser 2011 (ArgoUML, 2.68); p = 1 is the plain mean of the + sub-characteristics and p = -1 is never higher; levers are ordered by + their gain on a fixture; a language with no code, a single language, + and a report without independence or entanglement are rated; a report + carries the estimate. Run: python3 scripts/lib/test_check_sig_maintainability.py """ @@ -518,6 +524,10 @@ def test_report_rows_carry_their_stars(self): self.assertEqual(self.above_30(report)["stars"], 4) self.assertEqual(php["duplication"]["stars"], 5) self.assertIn(php["unit_size"][0]["stars"], (1, 2, 3, 4, 5)) + self.assertEqual(php["unit_size"][1]["loc"], 44) + rating = report["rating"] + self.assertLessEqual(rating["overall"]["range"][0], rating["overall"]["range"][1]) + self.assertIn("Estimated SIG maintainability rating", out) self.assertIn("4★", out) def test_default_is_four_star(self): @@ -641,5 +651,138 @@ def test_php_and_python_dependencies(self): repo.close() +def rated_report(langs, structure=None): + """A report with the fields rating_inputs() reads. `langs` maps a language + to (unit_loc, size, complexity, interfacing, (code_lines, redundant)), + each property a triple of cumulative shares.""" + out = {"languages": {}, "structure": {}} + for lang, (loc, size, ccn, params, dup) in langs.items(): + out["languages"][lang] = { + "unit_loc": loc, + "unit_size": [{"share": x} for x in size], + "unit_complexity": [{"share": x} for x in ccn], + "unit_interfacing": [{"share": x} for x in params], + "duplication": {"code_lines": dup[0], "redundant_lines": dup[1]}, + } + for lang, (loc, coupling, hidden, degree) in (structure or {}).items(): + out["structure"][lang] = {"module_loc": loc, "module_coupling": [{"share": x} for x in coupling], + "component_independence": {"hidden_share": hidden}, + "component_entanglement": {"violation_degree": degree}} + return out + + +GOOD = (10000, (.30, .10, .02), (.10, .03, .0), (.10, .02, .0), (10000, 200)) + + +class Rating(unittest.TestCase): + def test_interpolation_reproduces_alves_2011_argouml(self): + # Table III (b), McCabe: cumulative caps for moderate / high / very high. + table = {5: (.179, .099, .033), 4: (.234, .169, .067), 3: (.313, .238, .106), 2: (.391, .298, .167)} + profile = (.258, .187, .099) + ratings = [sig.interpolate(v, {lvl: table[lvl][i] for lvl in table}) for i, v in enumerate(profile)] + self.assertAlmostEqual(min(ratings), 2.68, places=2) + self.assertEqual(ratings.index(min(ratings)), 2) + + def test_interpolation_edges(self): + caps = sig.rating_caps("duplication") + self.assertEqual(sig.interpolate(0, caps), 5.5) + self.assertAlmostEqual(sig.interpolate(caps[4], caps), 3.5) + self.assertAlmostEqual(sig.interpolate(caps[2], caps), 1.5) + self.assertAlmostEqual(sig.interpolate(1.0, caps), 0.5) + self.assertAlmostEqual(sig.interpolate((caps[2] + 1) / 2, caps), 1.0) + values = [sig.interpolate(x / 1000, caps) for x in range(1001)] + self.assertEqual(values, sorted(values, reverse=True)) + + def test_p1_is_the_plain_mean_and_harmonic_is_never_higher(self): + self.assertAlmostEqual(sig.power_mean([1.0, 2.0, 4.5], 1), 2.5) + self.assertAlmostEqual(sig.power_mean([1.0, 2.0, 4.0], -1), 3 / (1 + .5 + .25)) + report = rated_report({"php": GOOD, "vue": (2000, (.6, .4, .2), (.3, .2, .05), (.3, .1, .03), (3000, 900))}, + {"php": (8000, (.05, .02, .01), .80, .10)}) + rated = sig.rate_inputs(sig.rating_inputs(report)) + subs = list(rated["subcharacteristics"].values()) + self.assertAlmostEqual(rated["overall"][1], sum(subs) / len(subs)) + self.assertLessEqual(rated["overall"][-1], rated["overall"][1]) + modifiability = [rated["properties"][p]["rating"] for p in ("duplication", "unit_complexity", "module_coupling")] + self.assertAlmostEqual(rated["subcharacteristics"]["modifiability"], sum(modifiability) / 3) + + def test_languages_are_weighted_by_their_code(self): + report = rated_report({"php": GOOD, "vue": (2000, (.6, .4, .2), (.3, .2, .05), (.3, .1, .03), (3000, 900))}) + prop = sig.rate_inputs(sig.rating_inputs(report))["properties"]["unit_size"] + php, vue = prop["languages"]["php"]["rating"], prop["languages"]["vue"]["rating"] + self.assertAlmostEqual(prop["rating"], (php * 10000 + vue * 2000) / 12000) + + def test_a_language_without_code_carries_no_weight(self): + alone = sig.rate_inputs(sig.rating_inputs(rated_report({"php": GOOD}))) + empty = (0, (0, 0, 0), (0, 0, 0), (0, 0, 0), (0, 0)) + both = sig.rate_inputs(sig.rating_inputs(rated_report({"php": GOOD, "typescript": empty}))) + self.assertEqual(alone["overall"], both["overall"]) + self.assertNotIn("typescript", both["properties"]["unit_size"]["languages"]) + + def test_a_single_language_is_its_own_property_rating(self): + rated = sig.rate_inputs(sig.rating_inputs(rated_report({"php": GOOD}))) + for prop in ("unit_size", "unit_complexity", "unit_interfacing", "duplication"): + self.assertEqual(rated["properties"][prop]["rating"], rated["properties"][prop]["languages"]["php"]["rating"]) + + def test_no_structure_leaves_independence_and_entanglement_out(self): + rated = sig.rate_inputs(sig.rating_inputs(rated_report({"php": GOOD}))) + for prop in ("module_coupling", "component_independence", "component_entanglement"): + self.assertIsNone(rated["properties"][prop]["rating"]) + self.assertIsNone(rated["subcharacteristics"]["modularity"]) + self.assertEqual(rated["subcharacteristics"]["testability"], rated["properties"]["unit_complexity"]["rating"]) + self.assertIsNotNone(rated["overall"][-1]) + + def test_independence_and_entanglement_are_rated_below_four(self): + report = rated_report({"php": GOOD}, {"php": (10000, (0, 0, 0), .50, .20)}) + self.assertEqual(sig.stars_of("component_independence", .50), "<4") + props = sig.rate_inputs(sig.rating_inputs(report))["properties"] + self.assertLess(props["component_independence"]["rating"], 1.5) + self.assertGreater(props["component_independence"]["rating"], 0.5) + self.assertLess(props["component_entanglement"]["rating"], 2.5) + self.assertGreater(props["component_entanglement"]["rating"], 1.5) + + def test_levers_are_ordered_by_their_gain(self): + # php duplication is the worst property (30% redundant, 1 star), but on + # the flat 1-star slope 1,000 lines move it little; vue unit size and + # php unit complexity sit on steeper slopes and lead under both exponents. + bad_dup = (10000, (.30, .10, .02), (.10, .03, .0), (.10, .02, .0), (10000, 3000)) + report = rated_report({"php": bad_dup, "vue": (1500, (.6, .4, .2), (.1, .03, 0), (.1, .02, 0), (1500, 0))}, + {"php": (10000, (0, 0, 0), 1.0, .05)}) + inputs = sig.rating_inputs(report) + self.assertLess(sig.rate_inputs(inputs)["properties"]["duplication"]["rating"], 2) + levers = sig.levers(inputs) + order = [(lv["property"], lv["language"]) for lv in levers] + self.assertEqual(set(order[:2]), {("unit_size", "vue"), ("unit_complexity", "php")}) + self.assertEqual(order[4], ("duplication", "php")) + self.assertTrue(levers[0]["sure"] and levers[1]["sure"]) + self.assertFalse(levers[4]["sure"]) + for p in sig.EXPONENTS: + gains = [lv["gain_per_kloc"][p] for lv in sorted(levers, key=lambda lv: lv["rank"][p])] + self.assertEqual(gains, sorted(gains, reverse=True)) + self.assertTrue(all(g > 0 for g in gains)) + for lv in levers: + self.assertEqual(lv["sure"], max(lv["rank"].values()) <= sig.SURE_TOP) + vue = next(lv for lv in levers if order[levers.index(lv)] == ("unit_size", "vue")) + self.assertEqual(vue["fixed_loc"], 900) + self.assertNotIn("component_entanglement", {p for p, _l in order}) + + def test_loc_for_half_star_is_the_fewest_lines(self): + report = rated_report({"php": (10000, (.30, .10, .02), (.10, .03, .0), (.10, .02, .0), (10000, 1500))}) + inputs = sig.rating_inputs(report) + before = sig.rate_inputs(inputs)["properties"]["duplication"]["rating"] + n = sig.loc_for_half_star(inputs, "duplication", "php", before) + self.assertIsNotNone(n) + + def after(k): + fixed = sig.with_entry(inputs, "duplication", "php", sig.fix_loc("duplication", inputs["duplication"]["php"], k)) + return sig.rate_inputs(fixed)["properties"]["duplication"]["rating"] + self.assertGreaterEqual(after(n), before + 0.5 - 1e-9) + self.assertLess(after(n - 1), before + 0.5 - 1e-9) + + def test_fixing_takes_the_worst_band_first(self): + entry = {"loc": 1000, "above": [500, 300, 100]} + self.assertEqual(sig.fix_loc("unit_size", entry, 150), {"loc": 1000, "above": [350, 150, 0]}) + self.assertEqual(sig.fix_loc("duplication", {"loc": 1000, "above": [100]}, 40), {"loc": 960, "above": [60]}) + + if __name__ == "__main__": unittest.main(verbosity=1) From 96f49df1a5a957987462205bef3444546265a746 Mon Sep 17 00:00:00 2001 From: Ruben van der Linde Date: Thu, 5 Nov 2026 14:40:19 +0100 Subject: [PATCH 2/6] feat(hydra-gates): gate 123 holds listed files at the 5-star unit bounds An app may list files in .sig/five-star-files.txt (repo-relative paths, one per line, # comments allowed). Gate 123 then fails when a unit in a listed file exceeds NLOC 15, McCabe 5 or 2 parameters, or when the file holds a duplicated block of 6+ code lines. Units come from gate 122's lizard reader, clones from gate 122's 6-line windows, now shared through dup_windows(). - Clone windows leave out use/namespace/import lines and comment-only end markers such as }//end name(); everything else still counts. - Parameter rule exemptions, detected from the source: constructors that only wire dependencies (promoted, assigned, or forwarded to the parent), and PHP methods that implement an interface method in the class's implements chain (repo interfaces, parents, vendor via composer maps). - Diff mode (a base) judges listed files the change touches or adds to the list; full mode judges all. A listed file that is gone fails, and so does removing a path while its file exists. - Vue/JS/TS findings are warnings while the pinned lizard is 1.25.0 or older (terryyin/lizard#549); the runner reports them as WARNING. - The gate applies when either .github/sig-floor.json or the list exists. Assisted-by: ClaudeCode:claude-opus-5-5 --- hydra-gates/scripts/lib/check_sig_floor.py | 120 ++++- .../scripts/lib/check_sig_maintainability.py | 23 +- hydra-gates/scripts/lib/sig_file_floor.py | 480 ++++++++++++++++++ .../lib/test_gate123_sig_floor_scope.sh | 37 ++ .../scripts/lib/test_sig_file_floor.py | 430 ++++++++++++++++ hydra-gates/scripts/run-hydra-gates.sh | 25 +- hydra-gates/tests/helper-suite-timings.tsv | 1 + 7 files changed, 1077 insertions(+), 39 deletions(-) create mode 100644 hydra-gates/scripts/lib/sig_file_floor.py create mode 100644 hydra-gates/scripts/lib/test_sig_file_floor.py diff --git a/hydra-gates/scripts/lib/check_sig_floor.py b/hydra-gates/scripts/lib/check_sig_floor.py index c58d1d5e..3f980e2a 100644 --- a/hydra-gates/scripts/lib/check_sig_floor.py +++ b/hydra-gates/scripts/lib/check_sig_floor.py @@ -43,13 +43,28 @@ the unit checks (size, complexity, interfacing) of the languages a newer reader measures differently (UNIT_READER_RE_MEASURED). Every other check stays. -Without a floor file the gate is NOT APPLICABLE (exit 4) before any tool is -loaded or any base resolved. +THE FIVE-STAR FILES +------------------- +`.sig/five-star-files.txt` lists files held at SIG's 5-star unit bounds: +repo-relative paths, one per line, `#` comments allowed. Every unit in a +listed file keeps NLOC <= 15, McCabe <= 5 and at most 2 parameters, and the +file holds no duplicated block of 6+ code lines. With a base (the PR gate) +only the listed files the change touches or adds to the list are judged; +without one (the nightly run) every listed file is. In both modes a listed +file that no longer exists fails, and so does removing a path from the list +while its file still exists. The rules, the clone lines left out, the +parameter exemptions and the lizard#549 warning for Vue, JS and TS are in +sig_file_floor.py. + +Without a floor file and without a five-star list the gate is NOT APPLICABLE +(exit 4) before any tool is loaded or any base resolved. Either one alone +makes it apply; the app floor is then judged only when its file exists. The 5-star checks (gate 122's five-star profile, derived from the v18.1 4-star limits) are reported next to the 4-star ones and never block. -`write` never lowers a floor. When the floor file already exists, every check +`write` re-records the floor at the current values and never lowers it: it +adds every check the tree meets now. When the floor file already exists, every check it lists stays in it, also one the current limits no longer meet (the 4-star limits moved from v17.0 to v18.1, stricter on coupling and independence). Such a check is printed as floored but missed, so the change of status is visible; @@ -88,6 +103,7 @@ sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) import check_sig_maintainability as sig # noqa: E402 +import sig_file_floor as files # noqa: E402 GATE = "[gate-123] sig-floor" FLOOR_PATH = ".github/sig-floor.json" @@ -398,20 +414,13 @@ def cmd_write(args, lizard): 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") + f"`check_sig_floor.py write .` to adopt the floor, or list five-star files in {files.LIST_PATH}") return 4 -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() - +def check_app_floor(args, app, mb, reader, lizard): + """The app-level floor: prints its findings and returns (lost, floored, + inherited, met, measured, five-star findings, raised) or an exit status.""" head_file = os.path.join(app, args.floor) head_doc = json.loads(sig.read_text(head_file)) if os.path.isfile(head_file) else None head_floor = parse_floor(json.dumps(head_doc), args.floor) if head_doc is not None else None @@ -419,7 +428,7 @@ def cmd_check(args, lizard): base_floor = parse_floor(json.dumps(base_doc), f"{mb}:{args.floor}") if base_doc is not None else None committed = base_floor if base_floor is not None else head_floor if committed is None: - return no_floor(args.floor) + return None 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 [] # A floor re-recorded by a newer unit reader may drop the checks that reader re-measures. @@ -428,8 +437,6 @@ def cmd_check(args, lizard): and unit_reader_of(base_doc) < sig.UNIT_READER_VERSION == unit_reader_of(head_doc): reread = re_measured_checks(removed, unit_reader_of(base_doc)) - 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 @@ -439,7 +446,6 @@ def cmd_check(args, lizard): 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, scope_changed) @@ -477,14 +483,75 @@ def cmd_check(args, lizard): 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 {"new": len(new), "lowered": len(lowered), "floor": len(floor), "inherited": len(inherited), + "met": len(met_head), "measured": len(head4), "five": five, "raise": len(raise_to)} + + +def check_file_floor(app, mb, reader): + """The five-star file floor: prints its findings and returns (failures, + warnings, files judged, files listed, mode), or None without a list.""" + head_list = files.list_at_head(app) + base_list = files.list_at(app, mb) if mb else None + if head_list is None and base_list is None: + return None + head_list = head_list or [] + paths = files.selected(app, mb, head_list, base_list) + failures, warnings = files.judge(app, paths, reader) + failures += [f"{p}: removed from {files.LIST_PATH} while the file still exists; the list only grows" + for p in files.lowered(app, head_list, base_list)] + js = [p for p in paths if sig.LANG_OF_EXT.get(os.path.splitext(p)[1].lower()) in files.JS_LANGS] + for f in failures: + print(f" five-star file {f}") + for w in warnings: + print(f" warning: five-star file {w}") + if js and not files.js_reliable(): + print(f" lizard {sig.LIZARD_VERSION} reads vue, js and ts unreliably up to 1.25.0 " + f"({files.LIZARD_JS_ISSUE}): {len(js)} listed file(s) judged, findings reported as warnings " + f"until a newer lizard is pinned") + return {"failures": len(failures), "warnings": len(warnings), "judged": len(paths), + "listed": len(head_list), "mode": "diff" if mb else "full"} + + +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() + + cache = load_cache(args.cache) + reader = CachedUnitReader(lizard, cache) + app_floor = check_app_floor(args, app, mb, reader, lizard) + if isinstance(app_floor, int): + return app_floor + file_floor = check_file_floor(app, mb, reader) + save_cache(args.cache, cache, reader.used) + if app_floor is None and file_floor is None: + return no_floor(args.floor) + + a = app_floor or {"new": 0, "lowered": 0, "floor": 0, "inherited": 0} + f = file_floor or {"failures": 0, "warnings": 0} + parts = [] + if app_floor: + parts.append(f"{a['met']} of {a['measured']} 4-star checks met at head; {a['five']} 5-star finding(s), " + f"not blocking; {a['inherited']} inherited") + if file_floor: + parts.append(f"five-star files ({f['mode']} mode): {f['judged']} of {f['listed']} listed file(s) judged, " + f"{f['failures']} failure(s), {f['warnings']} warning(s)") + parts.append(f"lizard {sig.LIZARD_VERSION}, cache {reader.hits} hit(s) {reader.misses} miss(es)") + if app_floor and a["raise"]: + parts.append(f"{a['raise']} check(s) above the committed floor") + tail = "; ".join(parts) + lost = a["new"] + a["lowered"] + f["failures"] + if lost: + print(f"{GATE}: FAIL: {lost} floored check(s) lost " + f"({a['new']} no longer met, {a['lowered']} removed from the floor file, " + f"{f['failures']} on five-star files); {tail}") return 1 - print(f"{GATE}: PASS: {len(floor)} floored check(s) held; {tail}") + print(f"{GATE}: PASS: {a['floor']} floored check(s) held; {tail}") return 0 @@ -505,7 +572,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): + if args.mode == "check" and not floor_present(args.app, args.floor, args.base_ref) \ + and not files.list_present(args.app, args.base_ref): return no_floor(args.floor) lizard, why = sig.load_lizard() if not lizard: diff --git a/hydra-gates/scripts/lib/check_sig_maintainability.py b/hydra-gates/scripts/lib/check_sig_maintainability.py index 6e03d97b..0e8d635f 100755 --- a/hydra-gates/scripts/lib/check_sig_maintainability.py +++ b/hydra-gates/scripts/lib/check_sig_maintainability.py @@ -589,6 +589,20 @@ def worst(units, key, n=8): return [f"{u['file']}:{u['start']} {u['name']} ({u[key]})" for u in ranked] +def dup_windows(lines, code): + """SIG's duplication windows of one file: (index, key, line numbers) for + every run of DUP_MIN_LINES consecutive code lines, keyed by the lines + without whitespace. `lines` is the file's text split into lines, `code` + the line numbers code_lines() returns. Windows made only of brackets are + skipped.""" + seq = [(n, "".join(lines[n - 1].split())) for n in sorted(code)] + 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 not all(len(t) <= 2 for t in key): + yield i, key, [n for n, _t in win] + + def duplication_profile(app, clones, files_by_lang, limit=DUPLICATION_LIMIT): """Redundant code lines per language, two ways. @@ -609,14 +623,9 @@ def duplication_profile(app, clones, files_by_lang, limit=DUPLICATION_LIMIT): 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 + for i, key, nums in dup_windows(lines_of[rel], code[rel]): if key in seen and seen[key] != (rel, i): - redundant[rel].update(n for n, _t in win) + redundant[rel].update(nums) else: seen.setdefault(key, (rel, i)) by_jscpd = collections.defaultdict(set) diff --git a/hydra-gates/scripts/lib/sig_file_floor.py b/hydra-gates/scripts/lib/sig_file_floor.py new file mode 100644 index 00000000..b3240507 --- /dev/null +++ b/hydra-gates/scripts/lib/sig_file_floor.py @@ -0,0 +1,480 @@ +# SPDX-FileCopyrightText: 2026 Conduction +# SPDX-License-Identifier: EUPL-1.2 +"""gate-123 helper library: the five-star file floor. + +An app may list files that must stay at SIG's 5-star unit bounds in +`.sig/five-star-files.txt`: repo-relative paths, one per line, blank lines and +`#` comments allowed. Every unit in a listed file must keep + + NLOC <= 15, McCabe <= 5 and at most 2 parameters + +and the file must hold no duplicated block of 6 or more code lines (SIG's +6-line windows, compared without whitespace, against every measured file of +the same language and against the file itself). The units are gate 122's +(lizard at its pinned version, through UnitReader), the windows are gate +122's dup_windows(). + +Lines every file shares are left out of the clone windows: `use`, +`namespace` and import statements (also a multi-line import block), and +comment-only lines such as the `}//end methodName()` marker. Everything else +counts, a bare `}` included. + +Two kinds of unit are exempt from the parameter rule only, detected from the +source and never listed by hand. Size, complexity and clones still apply. + * A constructor that only wires its dependencies: every parameter is + promoted (PHP 8, TypeScript), assigned to a property (as is, or one of + its properties when a services object is unpacked), or passed on to the + parent constructor, and the body does nothing else. + * A PHP method that implements a method of an interface in its class's + `implements` chain, through parent and abstract parent classes and the + interfaces those extend. Interfaces are read from the repository and from + the files vendor/composer's autoload maps point at. When a type in the + chain cannot be read, a method marked `@inheritDoc` or `#[\\Override]` + counts as implementing it. + +A listed path that does not exist, is not a measured source file, or that +lizard cannot read fails, so the list stays honest. Removing a path from the +list fails too while the file still exists. + +lizard up to 1.25.0 reads Vue, JavaScript and TypeScript unreliably +(terryyin/lizard#549). While the pinned version is one of those, findings in +.vue, .js and .ts files are reported as warnings and never fail. +""" +import os +import re + +import check_sig_maintainability as sig + +LIST_PATH = ".sig/five-star-files.txt" +BOUNDS = {"nloc": 15, "ccn": 5, "params": 2} +LABEL = {"nloc": "NLOC {v} > 15", "ccn": "McCabe {v} > 5", "params": "{v} parameters > 2"} +JS_LANGS = ("vue", "javascript", "typescript") +LIZARD_JS_UNRELIABLE_THROUGH = (1, 25, 0) +LIZARD_JS_ISSUE = "terryyin/lizard#549" +CONSTRUCTORS = ("__construct", "constructor", "__init__") + + +# -------------------------------------------------------------------------- +# the list +# -------------------------------------------------------------------------- + +def parse_list(text): + """The paths of a five-star list, in order, without duplicates.""" + out = [] + for raw in text.splitlines(): + line = raw.split("#", 1)[0].strip() if not raw.lstrip().startswith("#") else "" + if line.startswith("./"): + line = line[2:] + if line and line not in out: + out.append(line) + return out + + +def list_at(app, ref): + """The list committed at `ref`, or None when it has none.""" + rc, out = sig.git(app, "show", f"{ref}:{LIST_PATH}") + return parse_list(out) if rc == 0 else None + + +def list_at_head(app): + path = os.path.join(app, LIST_PATH) + return parse_list(sig.read_text(path)) if os.path.isfile(path) else None + + +def list_present(app, base_ref): + if os.path.isfile(os.path.join(app, LIST_PATH)): + return True + return bool(base_ref) and sig.git(app, "cat-file", "-e", f"{base_ref}:{LIST_PATH}")[0] == 0 + + +def js_reliable(version=None): + """Whether lizard `version` (the pinned one by default) reads Vue, JS and TS reliably.""" + parts = tuple(int(x) for x in re.findall(r"\d+", version or sig.LIZARD_VERSION)[:3]) + return parts > LIZARD_JS_UNRELIABLE_THROUGH + + +# -------------------------------------------------------------------------- +# the constructor exemption +# -------------------------------------------------------------------------- + +def _strip_comments(src, lang): + src = re.sub(r"/\*.*?\*/", " ", src, flags=re.S) + src = re.sub(r"//[^\n]*", "", src) + if lang == "python": + src = re.sub(r"#[^\n]*", "", src) + elif lang == "php": + src = re.sub(r"#(?!\[)[^\n]*", "", src) + return src + + +def _close(src, i, opening="(", closing=")"): + """Index of the bracket that closes the one at `i`, or -1.""" + depth = 0 + for j in range(i, len(src)): + if src[j] == opening: + depth += 1 + elif src[j] == closing: + depth -= 1 + if depth == 0: + return j + return -1 + + +def _split_top(text, seps): + """`text` split at any char of `seps` outside brackets.""" + out, depth, cur = [], 0, [] + for ch in text: + if ch in "([{": + depth += 1 + elif ch in ")]}": + depth -= 1 + if depth == 0 and ch in seps: + out.append("".join(cur)) + cur = [] + else: + cur.append(ch) + out.append("".join(cur)) + return [s.strip() for s in out if s.strip()] + + +def _params(ptext, lang): + """[(name, promoted)] of a parameter list.""" + out = [] + for piece in _split_top(ptext, ","): + piece = re.sub(r"#\[.*?\]", "", piece, flags=re.S).strip() + promoted = bool(re.match(r"(public|protected|private|readonly)\b", piece)) + if lang == "php": + m = re.search(r"\$(\w+)", piece) + else: + piece = re.sub(r"^((public|protected|private|readonly)\s+)+", "", piece) + m = re.match(r"[*\s]*(\w+)", piece) + if m and not (lang == "python" and m.group(1) in ("self", "cls")): + out.append((m.group(1), promoted)) + return out + + +ASSIGN = re.compile(r"^(?:\$this->|this\.|self\.)(\w+)\s*=\s*\$?(\w+)(?:(?:->|\??\.)\w+)*$") +FORWARD = re.compile(r"^(?:parent::__construct|super\(\)\.__init__|super)\s*\((.*)\)$", re.S) + + +def is_wiring_constructor(unit, source, lang): + """Whether `unit` is a constructor that only wires dependencies: every + parameter is promoted, assigned to a property (as is, or one of its + properties when a services object is unpacked), or passed on to the parent + constructor (named arguments too), and the body holds nothing else.""" + if re.split(r"::|\.", unit["name"])[-1] not in CONSTRUCTORS: + return False + lines = source.splitlines() + src = _strip_comments("\n".join(lines[unit["start"] - 1:unit["end"]]), lang) + name = re.search(r"\b(__construct|constructor|__init__)\s*\(", src) + if not name: + return False + open_at = name.end() - 1 + close_at = _close(src, open_at) + if close_at < 0: + return False + params = _params(src[open_at + 1:close_at], lang) + rest = src[close_at + 1:] + if lang == "python": + colon = rest.find(":") + body, seps = (rest[colon + 1:] if colon >= 0 else None), ";\n" + else: + brace = rest.find("{") + end = _close(rest, brace, "{", "}") if brace >= 0 else -1 + body, seps = (rest[brace + 1:end] if end > 0 else None), (";" if lang == "php" else ";\n") + if body is None: + return False + names = {n for n, _p in params} + wired = {n for n, promoted in params if promoted} + for stmt in _split_top(body, seps): + stmt = " ".join(stmt.split()) + m = ASSIGN.match(stmt) + if m and m.group(2) in names: + wired.add(m.group(2)) + continue + f = FORWARD.match(stmt) + args = [re.sub(r"^\w+\s*:\s*", "", a).lstrip(".").lstrip("$") + for a in _split_top(f.group(1), ",")] if f else None + if f and all(a in names for a in args): + wired.update(args) + continue + return False + return wired == names + + +# -------------------------------------------------------------------------- +# the interface exemption (PHP) +# -------------------------------------------------------------------------- + +PHP_NAMESPACE = re.compile(r"^\s*namespace\s+([\w\\]+)\s*;", re.M) +PHP_USE = re.compile(r"^\s*use\s+\\?([\w\\]+)(?:\s+as\s+(\w+))?\s*;", re.M) +PHP_GROUP_USE = re.compile(r"^\s*use\s+\\?([\w\\]+)\\\{([^}]*)\}\s*;", re.M) +PHP_TYPE = re.compile(r"\b(?:(?:abstract|final|readonly)\s+)*(class|interface)\s+(\w+)\s*" + r"(?:extends\s+([\w\\,\s]+?))?\s*(?:implements\s+([\w\\,\s]+?))?\s*\{", re.S) +PHP_FUNCTION = re.compile(r"\bfunction\s+&?\s*(\w+)\s*\(") +PSR4_ENTRY = re.compile(r"'((?:[^'\\]|\\.)*)'\s*=>\s*array\((.*?)\),") +CLASSMAP_ENTRY = re.compile(r"'((?:[^'\\]|\\.)*)'\s*=>\s*\$(vendorDir|baseDir)\s*\.\s*'([^']*)'") +DIR_ENTRY = re.compile(r"\$(vendorDir|baseDir)\s*\.\s*'([^']*)'") +INHERITS_MARK = re.compile(r"@inheritdoc|#\[\\?Override\]", re.I) + + +def php_types_of(text): + """{fully qualified name: {"kind", "extends", "implements", "methods"}} of + the classes and interfaces one PHP file declares, names resolved through + its namespace and `use` imports.""" + code = _strip_comments(text, "php") + m = PHP_NAMESPACE.search(code) + ns = m.group(1) if m else "" + alias = {} + for g in PHP_GROUP_USE.finditer(code): + for part in g.group(2).split(","): + bits = part.split() + if bits: + alias[bits[-1].split("\\")[-1]] = g.group(1) + "\\" + bits[0] + for u in PHP_USE.finditer(code): + alias[u.group(2) or u.group(1).split("\\")[-1]] = u.group(1) + + def resolve(name): + name = name.strip() + if name.startswith("\\"): + return name[1:] + head, _, tail = name.partition("\\") + if head in alias: + return alias[head] + ("\\" + tail if tail else "") + return f"{ns}\\{name}" if ns else name + + def names(group): + return [resolve(n) for n in (group or "").split(",") if n.strip()] + + out = {} + for t in PHP_TYPE.finditer(code): + brace = t.end() - 1 + end = _close(code, brace, "{", "}") + body = code[brace + 1:end] if end > 0 else "" + kind = t.group(1) + out[resolve(t.group(2))] = { + "kind": kind, + "extends": names(t.group(3)), + "implements": names(t.group(4)), + "methods": set(PHP_FUNCTION.findall(body)) if kind == "interface" else set(), + } + return out + + +class PhpTypes: + """The PHP classes and interfaces of the repository, plus those composer's + autoload files (vendor/composer) can locate on disk. Read lazily.""" + + def __init__(self, app): + self.app = app + self.types = None + self.psr4, self.classmap = [], {} + + def _load(self): + self.types = {} + for rel in sig.tracked_files(self.app): + if rel.lower().endswith(".php") and os.path.isfile(os.path.join(self.app, rel)): + self.types.update(php_types_of(sig.read_text(os.path.join(self.app, rel)))) + composer = os.path.join(self.app, "vendor", "composer") + dirs = {"vendorDir": os.path.join(self.app, "vendor"), "baseDir": self.app} + psr4 = os.path.join(composer, "autoload_psr4.php") + if os.path.isfile(psr4): + for m in PSR4_ENTRY.finditer(sig.read_text(psr4)): + prefix = m.group(1).replace("\\\\", "\\") + for d in DIR_ENTRY.finditer(m.group(2)): + self.psr4.append((prefix, dirs[d.group(1)] + d.group(2))) + classmap = os.path.join(composer, "autoload_classmap.php") + if os.path.isfile(classmap): + for m in CLASSMAP_ENTRY.finditer(sig.read_text(classmap)): + self.classmap[m.group(1).replace("\\\\", "\\")] = dirs[m.group(2)] + m.group(3) + + def get(self, fqcn): + if self.types is None: + self._load() + if fqcn not in self.types: + paths = [self.classmap[fqcn]] if fqcn in self.classmap else [] + paths += [os.path.join(d, fqcn[len(p):].replace("\\", "/") + ".php") + for p, d in self.psr4 if fqcn.startswith(p)] + for path in paths: + if os.path.isfile(path): + self.types.update(php_types_of(sig.read_text(path))) + break + return self.types.get(fqcn) + + def interface_methods(self, fqcn): + """(method names of every interface `fqcn` implements, through its + parents and the interfaces those extend; whether a type in the chain + could not be read).""" + methods, unresolved, seen = set(), False, set() + stack = [(fqcn, False)] + while stack: + name, is_iface = stack.pop() + if name in seen: + continue + seen.add(name) + t = self.get(name) + if t is None: + unresolved = unresolved or name != fqcn + continue + if t["kind"] == "interface": + methods |= t["methods"] + stack += [(n, True) for n in t["extends"]] + else: + stack += [(n, False) for n in t["extends"]] + [(n, True) for n in t["implements"]] + return methods, unresolved + + +def implements_interface_method(unit, source, types): + """Whether PHP `unit` (named Class::method) implements a method of an + interface in its class's `implements` chain. When a type of the chain + cannot be read, a method marked `@inheritDoc` or `#[\\Override]` counts.""" + if "::" not in unit["name"]: + return False + cls, method = unit["name"].rsplit("::", 1) + fqcn = next((n for n in php_types_of(source) if n.split("\\")[-1] == cls.split("\\")[-1]), None) + if fqcn is None: + return False + methods, unresolved = types.interface_methods(fqcn) + if method in methods: + return True + if not unresolved: + return False + lines = source.splitlines() + head = [] + for n in range(unit["start"] - 2, max(unit["start"] - 40, -1), -1): + s = lines[n].strip() + if s and not s.startswith(("*", "/*", "#[")): + break + head.append(s) + return bool(INHERITS_MARK.search("\n".join(head) + "\n" + lines[unit["start"] - 1])) + + +# -------------------------------------------------------------------------- +# duplication +# -------------------------------------------------------------------------- + +IMPORT_LINE = { + "php": re.compile(r"^(use|namespace)\s"), + "python": re.compile(r"^(import|from)\s"), +} +JS_IMPORT_LINE = re.compile(r"^(import\b|export\s+(\*|\{[^}]*\}?)\s*(from\b|$))") +END_MARKER = re.compile(r"^[\s{}()\[\];,]*(//|#(?!\[)).*$") + + +def floor_code_lines(text, lang): + """gate 122's code lines minus the lines that are the same in every file: + `use`, `namespace` and import statements (also when they span lines), and + a bracket followed only by a comment, such as `}//end methodName()`.""" + code = sig.code_lines(text, lang) + lines = text.splitlines() + pattern = IMPORT_LINE.get(lang, JS_IMPORT_LINE) + out, depth = set(), 0 + for n in sorted(code): + s = lines[n - 1].strip() + opens = s.count("(") + s.count("{") + s.count("[") - s.count(")") - s.count("}") - s.count("]") + if depth > 0: + depth += opens + continue + if pattern.match(s): + depth = max(opens, 0) + continue + if END_MARKER.match(s): + continue + out.add(n) + return out + + +def duplicated_blocks(app, targets, corpus): + """{target: [(first line, last line, "other:line")]} of the 6+ line blocks + in each target that also occur elsewhere: in the target itself or in a file + of `corpus` ({rel: lang}) of the same language.""" + lines_of, windows = {}, {} + for rel, lang in corpus.items(): + text = sig.read_text(os.path.join(app, rel)) + lines_of[rel] = text.splitlines() + windows[rel] = list(sig.dup_windows(lines_of[rel], floor_code_lines(text, lang))) + where = {} + for rel in sorted(corpus): + for _i, key, nums in windows[rel]: + where.setdefault((corpus[rel], key), []).append((rel, nums[0])) + out = {} + for rel in targets: + blocks = [] + for _i, key, nums in windows.get(rel, []): + copies = [c for c in where[(corpus[rel], key)] if c != (rel, nums[0])] + if not copies: + continue + if blocks and nums[0] <= blocks[-1][1]: + blocks[-1][1] = max(blocks[-1][1], nums[-1]) + else: + blocks.append([nums[0], nums[-1], f"{copies[0][0]}:{copies[0][1]}"]) + out[rel] = [tuple(b) for b in blocks] + return out + + +# -------------------------------------------------------------------------- +# the verdict +# -------------------------------------------------------------------------- + +def judge(app, paths, reader, scope=None): + """(failures, warnings) for the listed `paths`, as lists of message strings. + Findings in Vue, JS and TS files are warnings while lizard reads them + unreliably.""" + scope = scope or sig.Scope(app) + failures, warnings = [], [] + lenient = not js_reliable() + types = PhpTypes(app) + measured = {} + for rel in paths: + full = os.path.normpath(os.path.join(app, rel)) + if os.path.isabs(rel) or not full.startswith(os.path.abspath(app) + os.sep): + failures.append(f"{rel}: listed in {LIST_PATH} but not a path inside the repository") + elif not os.path.isfile(full): + failures.append(f"{rel}: listed in {LIST_PATH} but does not exist; remove it from the list") + elif not sig.LANG_OF_EXT.get(os.path.splitext(rel)[1].lower()): + failures.append(f"{rel}: listed in {LIST_PATH} but not a measured source file (php, js, ts, vue, py)") + else: + measured[rel] = sig.LANG_OF_EXT[os.path.splitext(rel)[1].lower()] + if not measured: + return failures, warnings + corpus = {f: lg for f, lg in sig.production_files(app, scope).items() if lg in set(measured.values())} + corpus.update(measured) + dups = duplicated_blocks(app, sorted(measured), corpus) + for rel, lang in sorted(measured.items()): + sink = warnings if lenient and lang in JS_LANGS else failures + source = sig.read_text(os.path.join(app, rel)) + before = len(reader.skipped) + units = reader.units(rel, lang, source) + if len(reader.skipped) > before: + sink.append(f"{rel}: lizard could not read it, so it cannot be held at 5 stars: " + f"{reader.skipped[-1]['reason']}") + continue + for u in units: + for key, bound in BOUNDS.items(): + if u[key] <= bound: + continue + if key == "params" and (is_wiring_constructor(u, source, lang) or ( + lang == "php" and implements_interface_method(u, source, types))): + continue + sink.append(f"{rel}:{u['start']} {u['name']}: {LABEL[key].format(v=u[key])}") + for first, last, other in dups[rel]: + sink.append(f"{rel}:{first}-{last}: duplicated block of {sig.DUP_MIN_LINES}+ code lines, " + f"same as {other}") + return failures, warnings + + +def selected(app, mb, head_list, base_list): + """The listed paths to judge: all of them without a merge base (full mode); + with one (diff mode) the listed paths the change touches or adds to the + list, and every listed path that no longer exists.""" + if not mb: + return list(head_list) + touched = set(sig.changed_paths(app, mb)) + added = set(head_list) - set(base_list or []) + return [p for p in head_list + if p in touched or p in added or not os.path.isfile(os.path.join(app, p))] + + +def lowered(app, head_list, base_list): + """Paths the change removes from the list while the file still exists.""" + return [p for p in (base_list or []) if p not in head_list and os.path.isfile(os.path.join(app, p))] 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 85e09e9d..0b958509 100755 --- a/hydra-gates/scripts/lib/test_gate123_sig_floor_scope.sh +++ b/hydra-gates/scripts/lib/test_gate123_sig_floor_scope.sh @@ -9,6 +9,8 @@ # 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 +# ARM 5 a file in .sig/five-star-files.txt over a 5-star bound: FAIL +# ARM 6 the same in a Vue file: WARNING, naming terryyin/lizard#549 # # The rule-by-rule arms (inherited breaches, the floor read from the base, a # lowered floor file, the raised floor, the cache) are in @@ -67,6 +69,17 @@ _branch nofloor git rm --quiet .github/sig-floor.json git commit --quiet -m "no floor" +_branch wide +_class Wide "$(_method m1 2 | sed 's/(int \$p)/(int $p, int $q, int $r)/')" +mkdir -p .sig && printf '# five-star files\nlib/Service/Wide.php\n' > .sig/five-star-files.txt +git add -A && git commit --quiet -m "a listed file with a 3-parameter unit" + +_branch vue +mkdir -p src .sig +printf '\n\n' > src/Total.vue +printf 'src/Total.vue\n' > .sig/five-star-files.txt +git add -A && git commit --quiet -m "a listed Vue file with a 3-parameter unit" + _run() { # [extra runner args...] local _b="$1"; shift git -C "${APP}" checkout --quiet "${_b}" @@ -118,6 +131,30 @@ case "${_v}" in *) _bad "expected NOT APPLICABLE, got: ${_v:-}" ;; esac +echo "-- ARM 5: a listed five-star file over a bound: FAIL --" +_out="$(_run wide --base base)" +case "$(_verdict "${_out}")" in + *FAIL*) _ok "a five-star file with a 3-parameter unit fails" ;; + *) _bad "expected FAIL, got: $(_verdict "${_out}")" ;; +esac +if printf '%s\n' "${_out}" | grep -q '^ five-star file lib/Service/Wide.php:.*3 parameters > 2'; then + _ok "the failure names the file, the unit and the bound" +else + _bad "the failure does not name lib/Service/Wide.php" +fi + +echo "-- ARM 6: a Vue five-star file over a bound: WARNING (lizard#549) --" +_out="$(_run vue --base base)" +case "$(_verdict "${_out}")" in + *WARNING*) _ok "a Vue finding is a warning while lizard 1.25.0 or older is pinned" ;; + *) _bad "expected WARNING, got: $(_verdict "${_out}")" ;; +esac +if printf '%s\n' "${_out}" | grep -q 'terryyin/lizard#549'; then + _ok "the run names the lizard issue" +else + _bad "the run does not name terryyin/lizard#549" +fi + 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)" diff --git a/hydra-gates/scripts/lib/test_sig_file_floor.py b/hydra-gates/scripts/lib/test_sig_file_floor.py new file mode 100644 index 00000000..41a9f419 --- /dev/null +++ b/hydra-gates/scripts/lib/test_sig_file_floor.py @@ -0,0 +1,430 @@ +#!/usr/bin/env python3 +# SPDX-FileCopyrightText: 2026 Conduction +# SPDX-License-Identifier: EUPL-1.2 +"""Tests for gate-123's five-star file floor (sig_file_floor.py, through +check_sig_floor.py check), on real git histories. + + 1. RULES: a listed file passes at the 5-star bounds and fails on a unit + over NLOC 15, McCabe 5 or 2 parameters, and on a 6+ line clone. + 2. CLONE LINES: shared `use` / `namespace` / import blocks and + `}//end name()` markers do not make a clone; other lines still do. + 3. EXEMPTIONS (parameters only): a constructor that only wires its + dependencies, and a method of an interface in the class's implements + chain; size and complexity still apply to both. + 4. HONEST LIST: a listed file that is gone fails in both modes, and so does + removing a path from the list while the file exists. + 5. MODES: diff mode judges only the listed files the change touches or adds + to the list; full mode judges them all. + 6. VUE: while lizard <= 1.25.0 is pinned, findings in .vue / .js / .ts + files are warnings and the run passes; a newer pin makes them fail. + 7. RE-RECORD: `write` raises the app floor to the current checks and keeps + every check already floored. + +Run: python3 scripts/lib/test_sig_file_floor.py +""" +import argparse +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 +import sig_file_floor as files # noqa: E402 + +LIZARD, WHY = sig.load_lizard() +if not LIZARD: + print(f"FAIL: pinned tools unavailable: {WHY}") + sys.exit(1) + +HEADER = " 15", out) + self.assertIn("1 on five-star files", out) + + def test_a_unit_over_mccabe_5_fails(self): + rc, out = self.hold("lib/Service/Branchy.php", php_class("Branchy", [complex_method("branchy", 5)])) + self.assertEqual(rc, 1, out) + self.assertIn("Branchy::branchy: McCabe 6 > 5", out) + + def test_a_unit_with_3_parameters_fails(self): + rc, out = self.hold("lib/Service/Wide.php", php_class("Wide", [method("wide", params="int $a, int $b, int $c")])) + self.assertEqual(rc, 1, out) + self.assertIn("Wide::wide: 3 parameters > 2", out) + + def test_a_block_of_6_lines_copied_from_another_file_fails(self): + rc, out = self.hold("lib/Service/Copy.php", php_class("Copy", [method("o0", tag="o0")])) + self.assertEqual(rc, 1, out) + self.assertIn("duplicated block of 6+ code lines, same as lib/Service/Other.php:", out) + + def test_a_block_repeated_inside_the_file_fails(self): + block = "".join(f" $r{i} = strtoupper('{i}');\n" for i in range(6)) + body = f" public function a(): void\n {{\n{block} }}\n\n public function b(): void\n {{\n{block} }}\n" + rc, out = self.hold("lib/Service/Twice.php", php_class("Twice", [body])) + self.assertEqual(rc, 1, out) + self.assertIn("same as lib/Service/Twice.php:", out) + + +class CloneLines(FileFloorCase): + def test_shared_use_blocks_and_end_markers_are_not_a_clone(self): + # Good.php and Other.php share the header, the `}//end` markers and + # the closing lines; on gate 122's lines alone they would be a clone. + text = sig.read_text(os.path.join(self.dir, "lib/Service/Good.php")) + self.assertGreater(len(sig.code_lines(text, "php")), len(files.floor_code_lines(text, "php"))) + rc, out = self.hold("lib/Service/Same.php", php_class("Same", [method("s", tag="s")])) + self.assertEqual(rc, 0, out) + + def test_a_multi_line_import_block_is_left_out(self): + text = "import {\n a,\n b,\n} from 'x'\nconst y = 1\n" + self.assertEqual(files.floor_code_lines(text, "javascript"), {5}) + + def test_a_bare_closing_brace_still_counts(self): + self.assertIn(2, files.floor_code_lines("config = $config; + $this->l10n = $l10n; + }//end __construct() + +""" +CTOR_LOGIC = """ public function __construct(IConfig $config, IL10N $l10n, LoggerInterface $logger) + { + $this->config = $config; + $this->l10n = $l10n; + $this->logger = $logger; + $this->name = $config->getSystemValue('x'); + } + +""" + + +class Exemptions(FileFloorCase): + def test_a_constructor_with_promoted_properties_is_exempt(self): + rc, out = self.hold("lib/Service/Promoted.php", php_class("Promoted", [CTOR_PROMOTED])) + self.assertEqual(rc, 0, out) + + def test_a_constructor_that_assigns_and_forwards_its_dependencies_is_exempt(self): + rc, out = self.hold("lib/Service/Wired.php", php_class("Wired", [CTOR_ASSIGNED], " extends Base")) + self.assertEqual(rc, 0, out) + + def test_a_constructor_that_does_more_than_wire_is_not_exempt(self): + rc, out = self.hold("lib/Service/Busy.php", php_class("Busy", [CTOR_LOGIC])) + self.assertEqual(rc, 1, out) + self.assertIn("Busy::__construct: 3 parameters > 2", out) + + def test_named_forwarding_and_an_unpacked_services_object_are_wiring(self): + src = ("links = $services->domain->links;\n }\n}\n") + unit = {"name": "C::__construct", "start": 3, "end": 7} + self.assertTrue(files.is_wiring_constructor(unit, src, "php")) + self.assertFalse(files.is_wiring_constructor(unit, src.replace("->links;", "->links();"), "php")) + + def test_the_exemption_is_detected_in_typescript_and_python(self): + ts = {"name": "constructor", "start": 2, "end": 5} + src = "export class S {\n constructor(private readonly a: A, b: B, c: C) {\n this.b = b\n this.c = c;\n }\n}\n" + self.assertTrue(files.is_wiring_constructor(ts, src, "typescript")) + py = {"name": "__init__", "start": 2, "end": 4} + src = "class P:\n def __init__(self, a, b, c):\n self.a = a\n super().__init__(b, c)\n" + self.assertTrue(files.is_wiring_constructor(py, src, "python")) + self.assertFalse(files.is_wiring_constructor(py, src.replace("self.a = a", "self.a = a + 1"), "python")) + + def test_an_exempt_constructor_still_has_the_size_rule(self): + assigns = "".join(f" $this->p{i} = $p{i};\n" for i in range(15)) + params = ", ".join(f"int $p{i}" for i in range(15)) + ctor = f" public function __construct({params})\n {{\n{assigns} }}\n\n" + rc, out = self.hold("lib/Service/Many.php", php_class("Many", [ctor])) + self.assertEqual(rc, 1, out) + self.assertIn("Many::__construct: NLOC", out) + self.assertNotIn("parameters > 2", out) + + def interface_repo(self): + self.write("lib/Contract/Reader.php", " 2", out) + + def test_an_interface_method_still_has_the_complexity_rule(self): + self.interface_repo() + branchy = complex_method("read", 5).replace("(int $a)", "(int $a, int $b, int $c)") + rc, out = self.hold("lib/Service/Impl.php", php_class("Impl", [branchy], " extends AbstractStore")) + self.assertEqual(rc, 1, out) + self.assertIn("Impl::read: McCabe 6 > 5", out) + self.assertNotIn("parameters > 2", out) + + def test_an_unreadable_interface_counts_for_a_method_marked_inheritdoc(self): + marked = " /**\n * {@inheritDoc}\n */\n" + method("handle", params="int $a, int $b, int $c", tag="h") + rc, out = self.hold("lib/Service/Ext.php", php_class("Ext", [marked], " implements \\OCP\\External\\IHandler")) + self.assertEqual(rc, 0, out) + rc, out = self.hold("lib/Service/Ext.php", php_class("Ext", [ + method("handle", params="int $a, int $b, int $c", tag="h")], " implements \\OCP\\External\\IHandler")) + self.assertEqual(rc, 1, out) + + def test_an_interface_composer_maps_into_vendor_is_read(self): + self.write("vendor/composer/autoload_psr4.php", " array($vendorDir . '/nextcloud/ocp/OCP'),\n);\n") + self.write("vendor/nextcloud/ocp/OCP/External/IHandler.php", " 2", out) + + def test_diff_mode_judges_a_path_the_change_adds_to_the_list(self): + self.git("checkout", "-q", "base") + self.write("lib/Service/Other.php", php_class("Other", [method("o", params="int $a, int $b, int $c")])) + self.commit("an unlisted wide file") + self.git("checkout", "-q", "-B", "change") + self.listing(["lib/Service/Good.php", "lib/Service/Wide.php", "lib/Service/Other.php"]) + rc, out = self.diff() + self.assertEqual(rc, 1, out) + self.assertIn("Other::o: 3 parameters > 2", out) + self.assertNotIn("Wide::wide", out) + + def test_full_mode_judges_every_listed_file(self): + rc, out = self.full() + self.assertEqual(rc, 1, out) + self.assertIn("Wide::wide: 3 parameters > 2", out) + self.assertIn("five-star files (full mode): 2 of 2 listed file(s) judged", out) + + +VUE = """ + + +""" + + +class Vue(FileFloorCase): + def test_a_vue_finding_is_a_warning_while_lizard_is_1_25_0_or_older(self): + self.assertFalse(files.js_reliable("1.24.3")) + self.assertFalse(files.js_reliable("1.25.0")) + rc, out = self.hold("src/views/Total.vue", VUE) + self.assertEqual(rc, 0, out) + self.assertIn(" warning: five-star file src/views/Total.vue:8 total: 3 parameters > 2", out) + self.assertIn("reads vue, js and ts unreliably up to 1.25.0 (terryyin/lizard#549)", out) + self.assertIn("0 failure(s), 1 warning(s)", out) + + def test_a_newer_pinned_lizard_makes_vue_findings_fail(self): + self.assertTrue(files.js_reliable("1.26.0")) + pinned = sig.LIZARD_VERSION + self.write("src/views/Total.vue", VUE) + self.listing(["src/views/Total.vue"]) + self.commit() + try: + sig.LIZARD_VERSION = "1.26.0" + buf = io.StringIO() + with contextlib.redirect_stdout(buf): + rc = floor.cmd_check(argparse.Namespace( + app=self.dir, base_ref=None, floor=floor.FLOOR_PATH, cache=None, + md=None, json=None, proposed=None), LIZARD) + finally: + sig.LIZARD_VERSION = pinned + self.assertEqual(rc, 1, buf.getvalue()) + self.assertIn(" five-star file src/views/Total.vue:8 total: 3 parameters > 2", buf.getvalue()) + + +class ReRecord(FileFloorCase): + def test_write_re_records_the_app_floor_upwards(self): + rc, out = run("write", self.dir) + self.assertEqual(rc, 0, out) + path = os.path.join(self.dir, floor.FLOOR_PATH) + with open(path) as fh: + doc = json.load(fh) + self.assertIn("php unit_size >60", doc["checks"]) + doc["checks"] = [c for c in doc["checks"] if c != "php unit_size >60"] + with open(path, "w") as fh: + json.dump(doc, fh) + rc, out = run("write", self.dir) + self.assertEqual(rc, 0, out) + with open(path) as fh: + self.assertIn("php unit_size >60", json.load(fh)["checks"]) + + +if __name__ == "__main__": + unittest.main() diff --git a/hydra-gates/scripts/run-hydra-gates.sh b/hydra-gates/scripts/run-hydra-gates.sh index 97de3fcb..9890d436 100755 --- a/hydra-gates/scripts/run-hydra-gates.sh +++ b/hydra-gates/scripts/run-hydra-gates.sh @@ -13874,8 +13874,16 @@ fi # 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 .`. +# `.sig/five-star-files.txt` holds listed files at the 5-star unit bounds +# (NLOC <= 15, McCabe <= 5, at most 2 parameters, no 6+ line clone). With a +# delta base only the listed files the change touches are judged; the nightly +# run judges them all. A listed file that is gone fails. Findings in Vue, JS +# and TS files are a WARNING while the pinned lizard is 1.25.0 or older +# (terryyin/lizard#549). +# +# NOT APPLICABLE in a repository with neither file: adopting the app floor is +# one committed file, generated by `check_sig_floor.py write .`, which also +# re-records an existing floor: it only adds checks, never drops one. # --------------------------------------------------------------------------- _floor_log=${HYDRA_GATE_LOG_DIR}/hydra-gate-sig-floor.log : > "${_floor_log}" @@ -13899,9 +13907,14 @@ else 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" + grep -E '^ (unverified|inherited|warning|lizard)' "${_floor_log}" 2>/dev/null + _floor_w=$(grep -c '^ warning: five-star file' "${_floor_log}" 2>/dev/null) + if [ "${_floor_w:-0}" -gt 0 ]; then + _warn 123 "sig-floor" "${_floor_w} finding(s) in Vue, JS or TS five-star files, reported as warnings because lizard 1.25.0 and older reads them unreliably (terryyin/lizard#549). See ${_floor_log}" + else + grep -E '^\[gate-123\] sig-floor: PASS' "${_floor_log}" + _pass 123 "sig-floor" + fi 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 @@ -13910,7 +13923,7 @@ else 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}" + _fail 123 "sig-floor" "${_floor_n:-1} floored check(s) lost: a SIG 4-star check in .github/sig-floor.json no longer met or removed from it, or a file in .sig/five-star-files.txt above the 5-star bounds, gone, or removed from the list. Each is named above. 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}." diff --git a/hydra-gates/tests/helper-suite-timings.tsv b/hydra-gates/tests/helper-suite-timings.tsv index 04929242..d56ebe88 100644 --- a/hydra-gates/tests/helper-suite-timings.tsv +++ b/hydra-gates/tests/helper-suite-timings.tsv @@ -141,6 +141,7 @@ test_or_abstraction_exceptions.sh 2 test_or_abstraction_pdok.sh 1 test_php_template_scope.py 0 test_shipped_contracts_documented.py 0 +test_sig_file_floor.py 7 test_source_scope.py 0 test_vendored_schema_freshness.js 1 test_write_gates_json.py 25 From f75d96678c8dc32162d553205685419537e7fd8d Mon Sep 17 00:00:00 2001 From: Ruben van der Linde Date: Thu, 5 Nov 2026 15:41:04 +0100 Subject: [PATCH 3/6] feat(hydra-gates): five-star clone rule skips the Vue and JS file shell In .vue, .js and .ts files the clone windows of gate 123's five-star file floor now also leave out SFC block tags (