diff --git a/docs/hydra/operations/sig-scores.mdx b/docs/hydra/operations/sig-scores.mdx index e6240a72..451d880f 100644 --- a/docs/hydra/operations/sig-scores.mdx +++ b/docs/hydra/operations/sig-scores.mdx @@ -36,6 +36,9 @@ for the value and both limits. - **Unit size, complexity and interfacing:** the share of unit code above the bound, for example the code in units longer than 15 lines. - **Duplication:** the share of redundant lines, in fragments of 6 lines or more. + In a Vue file we treat template, script and style as separate pieces, so a + fragment never crosses from one into the next. This is our assumption until a + real Sigrid scan confirms it. - **Module coupling:** the share of module code in files with more than 10, 20 or 50 incoming dependencies. - **Component independence:** the share of code that no other component calls. 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 e56db257..13ea40f2 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. @@ -67,7 +77,10 @@ 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. +figure next to it as a cross-check. In a Vue file the windows stay inside one +top-level block: template, script and style are separate pieces, and the tag +lines belong to none. That is our assumption until a real Sigrid scan confirms +it, and every report with Vue files says so. jscpd's figure does not apply it. 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 @@ -135,6 +148,8 @@ RATCHET = {"nloc": 60, "ccn": 10, "params": 4} RATCHET_LABEL = {"nloc": "NLOC > 60", "ccn": "McCabe > 10", "params": "5 or more parameters"} DUP_MIN_LINES = 6 +VUE_PIECES_ASSUMPTION = ("Vue duplication treats template, script and style as separate pieces, so no 6-line " + "window crosses a block boundary. This is our assumption until a real Sigrid scan confirms it.") # Star bands, per language: for each level, the max share of unit LOC strictly # above each bound. 4 stars is the SIG/TUV NORD CERT Guidance for Producers @@ -567,8 +582,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 @@ -578,6 +594,53 @@ def worst(units, key, n=8): return [f"{u['file']}:{u['start']} {u['name']} ({u[key]})" for u in ranked] +SFC_OPEN = re.compile(r"^<([a-zA-Z][\w-]*)\b") + + +def sfc_pieces(lines, code): + """The code lines of a Vue file as one sorted list per piece: the inside + of each top-level block (template, script, style, custom blocks) and each + run of lines between blocks. The block's own tag lines are in no piece. + A top-level tag starts in the first column, so an indented nested + `