diff options
Diffstat (limited to 'plugins/code-modernization/scripts/trace_rules.py')
| -rw-r--r-- | plugins/code-modernization/scripts/trace_rules.py | 520 |
1 files changed, 520 insertions, 0 deletions
diff --git a/plugins/code-modernization/scripts/trace_rules.py b/plugins/code-modernization/scripts/trace_rules.py new file mode 100644 index 00000000..139e438c --- /dev/null +++ b/plugins/code-modernization/scripts/trace_rules.py @@ -0,0 +1,520 @@ +#!/usr/bin/env python3 +"""Trace every business rule to the code and the tests that name it, and to the tests that ran. + + python3 trace_rules.py <system> [--workspace DIR] [--json] [--all] [--module NAME --results PATH ...] + +Reads analysis/<system>/BUSINESS_RULES.md (rule cards: "### RULE-NNN: name" with **Priority:**, +**Confidence:** and **Source:** lines), then scans the built code under modernized/<system>, +modernized/<system>-uplifted and modernized/<system>-reimagined (never build output: target/, +build/, dist/, node_modules/, bin/, obj/, __pycache__/, or any folder starting with a dot) for +mentions of each rule id, and sorts every file into "test" or "main" code. One row per rule. + +Evidence, strongest first: + tested executed evidence backs it, from the per-test results of that run (JUnit or TRX XML; --results + reads them here, the proof pack passes them in): a test that ran and passed names the rule in + its test or class name, or a test file names it on a line not marked skipped and that file's + name is the class or file of a test that ran and passed. Without per-test results nothing is + "tested" + named, not run a test file names it, but nothing that ran backs it: the test is skipped, pending or failing, + its class never ran, or no per-test results were given + code only only main code names it + claimed only only the mapping table in TRANSFORMATION_NOTES.md or UPLIFT_NOTES.md names it, on a + row that also names a file that exists in the module + none nothing names it + +A mention is RULE-017 (any case, or RULE_017), rule017 or Rule017 inside an identifier such as +rule017_emptyInput or testRule017, and the shorthand RULE-002/003 and RULE-001, -018. Nothing is +guessed from words. A line is marked skipped when it, or one of the 3 lines above it, holds @Disabled, +@Ignore, [Ignore], #[ignore], xit(, xdescribe, skip (so also @Skip, t.Skip, it.skip, test.skip, +describe.skip and @pytest.mark.skip), pending or todo, in any case. A mention shows that a test names +the rule, not that the test is good. + +A test is a file under a folder called test, tests, __tests__, spec or specs, or named like +FooTest.java, FooTests.cs, TestFoo.java, test_foo.py, foo_test.go, foo.spec.ts or foo.test.js. +Documentation files (.md, .txt, .rst, .adoc) are never code. Symbolic links are never followed. +A built folder that holds only test files and the files that build them (pom.xml, mvnw, package.json, +...) is test tooling, not a module: tooling_only() says so. +Everything read is untrusted text: it is never executed and only shortened, never trusted. + +Exit 0 when every P0 rule is "tested", 1 when some are not, 2 when the rules file cannot be read. +Standard library only. +""" +import argparse +import bisect +import collections +import json +import os +import re +import sys + +SKIP_DIRS = {"target", "build", "dist", "node_modules", "bin", "obj", "__pycache__", "venv"} +DOC_EXT = {".md", ".markdown", ".rst", ".txt", ".adoc"} +TEST_DIRS = {"test", "tests", "__tests__", "spec", "specs"} +TEST_NAME = re.compile(r"^test_|_tests?\.[^.]+$|\.(?:spec|test)\.[^.]+$|(?:Test|Tests|TestCase|IT)\.[^.]+$|^Test[A-Z0-9_]") +NOTES_NAMES = ("TRANSFORMATION_NOTES.md", "UPLIFT_NOTES.md") +TRACKS = (("rewrite", ""), ("uplift", "-uplifted"), ("reimagine", "-reimagined")) +FILE_CAP, RULES_CAP, NOTES_CAP, LINE_CAP, MAX_FILES, SAMPLES = 2 << 20, 8 << 20, 1 << 20, 4000, 200000, 3 +MENTION = [re.compile(r"(?<![A-Za-z0-9])rule[-_](\d{1,6})(?!\d)", re.I), + re.compile(r"(?<![A-Za-z0-9])rule(\d{3,6})(?!\d)", re.I), + re.compile(r"(?<=[a-z])Rule[-_]?(\d{3,6})(?!\d)")] +MORE = re.compile(r"(?:/|,[ \t]*-)(\d{2,6})(?!\d)") +NOT_A_CLAIM = re.compile(r"(?i)not migrated|not implemented|not ported|removed|retired|dead code|dropped|out of scope") +CARD = re.compile(r"#{2,5}[ \t]+[*`\[]*RULE[-_](\d{1,6})(?![A-Za-z0-9])", re.I) +FENCE = re.compile(r"^ {0,3}(`{3,}|~{3,})") +PATH = re.compile(r"[A-Za-z0-9_@][A-Za-z0-9_@./+-]{0,199}\.[A-Za-z][A-Za-z0-9]{0,7}(?![A-Za-z0-9_])") +SKIPPED_LINE = re.compile(r"@Disabled|@Ignore|\[Ignore\]|#\[ignore\]|xit\(|xdescribe|skip|pending|todo", re.I) # "skip" also covers @Skip, t.Skip, it.skip, test.skip, describe.skip, @pytest.mark.skip +MARK_LINES = 3 # a mention is skipped when its own line, or one of this many lines above it, holds a marker +NOT_RUN = "named, not run" +NO_RUN = {"known": False, "ids": frozenset(), "keys": frozenset()} +TOOLING_NAMES = {"pom.xml", "mvnw", "mvnw.cmd", "gradlew", "gradlew.bat", "build.gradle", "build.gradle.kts", "settings.gradle", "settings.gradle.kts", "gradle.properties", + "package.json", "package-lock.json", "yarn.lock", "pnpm-lock.yaml", "pytest.ini", "tox.ini", "setup.cfg", "pyproject.toml", "uv.lock", "poetry.lock", "conftest.py", + "cargo.toml", "cargo.lock", "go.mod", "go.sum", "composer.json", "composer.lock", "phpunit.xml", "phpunit.xml.dist", "cmakelists.txt", "makefile", "dockerfile"} +TOOLING_EXT = {".csproj", ".sln", ".props", ".targets", ".runsettings"} +TOOLING_PATTERN = re.compile(r"tsconfig[\w.-]*\.json|[\w-]+\.config\.(?:js|cjs|mjs|ts)|docker-compose[\w.-]*\.ya?ml") + + +def clean(value, limit=200): + text = " ".join(re.sub(r"[\x00-\x1f\x7f-\x9f\u2028\u2029]", " ", str(value if value is not None else "")).split()) + return text if len(text) <= limit else text[:limit - 1] + "\u2026" + + +def read_text(path, cap): + """Text of a regular, non-binary file (first `cap` bytes), or None.""" + try: + with open(path, "rb") as fh: + raw = fh.read(cap) + except OSError: + return None + return None if b"\x00" in raw[:4096] else raw.decode("utf-8", "replace") + + +def find_ids(text): + """[(rule number, offset)] for every id named in text, shorthand included.""" + found = [] + for rx in MENTION: + for m in rx.finditer(text): + found.append((int(m.group(1)), m.start())) + pos = m.end() + more = MORE.match(text, pos) + while more: + found.append((int(more.group(1)), m.start())) + pos = more.end() + more = MORE.match(text, pos) + return found + + +def class_keys(name): + """The lower-case names a test class goes by in a result file, for matching a test file's name (without its extension): the last two + parts of a dotted, slashed or $-nested name (a Python module and its class, a Java class), the outermost class of a nested one and, + for a file path, its file name with and without the extension.""" + text = str(name if name is not None else "")[:400] + parts = [p for p in re.split(r"[.$:/\\]+", text) if p] + outer = [p for p in re.split(r"[.:/\\]+", text.split("$")[0]) if p] + keys = {p.lower() for p in parts[-2:] + outer[-1:]} + if "/" in text or "\\" in text: + base = re.split(r"[/\\]", text)[-1] + keys.update((base.lower(), os.path.splitext(base)[0].lower())) + return keys + + +def run_evidence(results): + """What ran for one module, from its parsed results (baseline_diff.read_results, one per suite): {"known", "ids", "keys"}. + known: some result lists its tests one by one (a count, or a summary line of a log, names no test). + ids: the rule numbers named by the test name or class name of a test that ran and passed. + keys: class_keys of every class that has a test that ran and passed.""" + out = {"known": False, "ids": set(), "keys": set()} + for res in results: + if not res or not res.get("tests"): + continue + out["known"] = True + for tid, status in res["tests"].items(): + if status == "PASS" and "rule" in tid.lower(): + out["ids"].update(n for n, _ in find_ids(tid)) + for klass, c in (res.get("classes") or {}).items(): + if c.get("pass"): + out["keys"] |= class_keys(klass) + return out + + +def line_marks(body): + """([offset where each line starts], [whether the line holds a skip marker]) for one test file's text.""" + starts, flags, pos = [], [], 0 + for line in body.split("\n"): + starts.append(pos) + flags.append(SKIPPED_LINE.search(line) is not None) + pos += len(line) + 1 + return starts, flags + + +def is_live(marks, at): + """True when the mention at text offset `at` is not marked skipped: its own line and the 3 lines above hold no marker.""" + starts, flags = marks + i = bisect.bisect_right(starts, at) - 1 + return not any(flags[max(0, i - MARK_LINES):i + 1]) + + +def field(lines, name): + """The value of a "**Name:** value" line, or ''. Linear in the line length whatever the line holds.""" + for line in lines: + s = line[:LINE_CAP].lstrip(" \t>*-") + if s[:len(name)].lower() == name.lower(): + rest = s[len(name):].lstrip("*").lstrip(" \t") + if rest.startswith(":"): + return rest[1:].lstrip(" \t*").strip() + return "" + + +def parse_rules(text): + """-> ([rule dicts in file order], [notes]). A duplicate id keeps its first card.""" + rules, notes, seen, card, fence, rows = [], [], set(), None, "", {} + lines = text.replace("\r\n", "\n").replace("\r", "\n").split("\n") + for line in lines: + if line.lstrip().startswith("|"): + cells = [re.sub(r"[*`]", "", c).strip() for c in line[:LINE_CAP].strip().strip("|").split("|")] + ids = [int(m.group(1)) for c in cells for m in [re.fullmatch(r"RULE[-_](\d{1,6})", c, re.I)] if m] + if ids: + rows.setdefault(ids[0], {"p": next((c for c in cells if re.fullmatch(r"P\d", c)), ""), + "c": next((c for c in cells if re.match(r"(?i)(high|medium|low)\b", c)), "")}) + for line in lines: + f = FENCE.match(line) + if fence: + fence = "" if f and f.group(1)[0] == fence[0] and len(f.group(1)) >= len(fence) else fence + if card is not None: + card["body"].append(line) + continue + if f: + fence = f.group(1) + m = None if f else CARD.match(line[:LINE_CAP]) + if not f and re.match(r"#{1,6}\s", line): + card = None + if m: + n = int(m.group(1)) + if n in seen: + notes.append("RULE-%03d has more than one card; the first was used." % n) + continue + seen.add(n) + name = line[m.end():LINE_CAP].lstrip("*`] \t:\u00b7\u2013\u2014-").rstrip("# \t") + card = {"n": n, "id": "RULE-%03d" % n, "name": clean(name, 160), "body": []} + rules.append(card) + elif card is not None: + card["body"].append(line) + for r in rules: + body = r.pop("body") + prio = re.search(r"\bP\d\b", field(body, "Priority")) + conf = re.search(r"(?i)\b(high|medium|low)\b", field(body, "Confidence")) + row = rows.get(r["n"], {}) + source = field(body, "Source") + first = PATH.search(source) + r.update({"priority": prio.group(0) if prio else row.get("p", ""), + "confidence": conf.group(1).capitalize() if conf else row.get("c", "").capitalize()[:10], + "source": clean(source, 160), "sourceFile": os.path.basename(first.group(0)) if first else ""}) + return rules, notes + + +def file_kind(rel): + parts = rel.split("/") + name = parts[-1] + if os.path.splitext(name)[1].lower() in DOC_EXT: + return "doc" + if any(p.lower() in TEST_DIRS for p in parts[:-1]) or TEST_NAME.search(name): + return "test" + return "main" + + +def is_real_dir(path): + return os.path.isdir(path) and not os.path.islink(path) + + +def discover_modules(workspace, system): + """[{name, track, path, rel}] for every built module under modernized/.""" + out = [] + for track, suffix in TRACKS: + root = os.path.join(workspace, "modernized", system + suffix) + if not is_real_dir(root): + continue + rel = "modernized/" + system + suffix + if track == "uplift": + out.append({"name": system + suffix, "track": track, "path": root, "rel": rel}) + continue + try: + subs = sorted(d for d in os.listdir(root) if not d.startswith(".") and d not in SKIP_DIRS and is_real_dir(os.path.join(root, d))) + except OSError: + subs = [] + for d in subs: + out.append({"name": d, "track": track, "path": os.path.join(root, d), "rel": rel + "/" + d}) + if not subs: + out.append({"name": system + suffix, "track": track, "path": root, "rel": rel}) + return out + + +def walk_module(path, budget): + """([(relative posix path, absolute path)] of regular files, links skipped, cut short).""" + files, skipped = [], 0 + for base, dirs, names in os.walk(path): + keep = [] + for d in sorted(dirs): + if d.startswith(".") or d in SKIP_DIRS: + continue + if os.path.islink(os.path.join(base, d)): + skipped += 1 + continue + keep.append(d) + dirs[:] = keep + for n in sorted(names): + full = os.path.join(base, n) + if os.path.islink(full): + skipped += 1 + elif not n.startswith(".") and os.path.isfile(full): + if len(files) >= budget: + return files, skipped, True + files.append((os.path.relpath(full, path).replace(os.sep, "/"), full)) + return files, skipped, False + + +def is_tooling(name): + """A file that builds or runs code without being code: pom.xml, mvnw, package.json, conftest.py, *.csproj, ...""" + low = name.lower() + return low in TOOLING_NAMES or os.path.splitext(low)[1] in TOOLING_EXT or TOOLING_PATTERN.fullmatch(low) is not None + + +def tooling_only(path): + """True when a built folder holds test code and the files that build or run it, and nothing else that is not a document: at least + one test file, no main code. A file this does not recognise counts as main code, so a folder is only left out when it is clear.""" + files, _, cut = walk_module(path, MAX_FILES) + tests = 0 + for rel, _ in files: + kind = file_kind(rel) + if kind == "test": + tests += 1 + elif kind == "main" and not is_tooling(rel.rsplit("/", 1)[-1]): + return False + return tests > 0 and not cut + + +def claims_of(notes, names): + """(rule numbers claimed, rule rows naming no existing file, basenames of every file the notes name). + A row claims a rule only when it names the rule AND a file that exists in the module.""" + claimed, unresolved, named, head = set(), 0, set(), "" + for line in notes.split("\n"): + line = line[:LINE_CAP] + tokens = PATH.findall(line) + named.update(os.path.basename(t) for t in tokens) + if line.startswith("#"): + head = line.lstrip("#").strip() + if not line.lstrip().startswith("|") or NOT_A_CLAIM.search(head): # a table under "Not migrated" claims nothing + continue + ids = {n for n, _ in find_ids(line)} + if not ids: + continue + if any(os.path.basename(t) in names and any(p == t or p.endswith("/" + t) for p in names[os.path.basename(t)]) for t in tokens): + claimed |= ids + else: + unresolved += 1 + return claimed, unresolved, named + + +def status_of(main, tests, claimed, ran=False): + """A rule's status. `ran`: executed evidence backs it. A test file that names it without that evidence is "named, not run".""" + return "tested" if ran else NOT_RUN if tests else "code only" if main else "claimed only" if claimed else "none" + + +def blank(): + """`tests`: mentions in test files; `live`: those not marked skipped; `by`: how executed evidence backs the rule ("test name", "test file") or ''; `at`: the first + unskipped mention in a test file that ran (file:line), the one that backs it.""" + return {"main": 0, "tests": 0, "live": 0, "claimed": False, "named": False, "by": "", "at": ""} + + +def trace(workspace, system, ran=None): + """-> the trace. Raises OSError when BUSINESS_RULES.md cannot be read. + ran: {module folder (as "path" in the modules list): run_evidence(...)}: what ran, per module. Without it no rule is "tested".""" + rules_path = os.path.join(workspace, "analysis", system, "BUSINESS_RULES.md") + if os.path.islink(rules_path): + raise OSError("analysis/%s/BUSINESS_RULES.md is a symbolic link" % system) + text = read_text(rules_path, RULES_CAP) + if text is None: + raise OSError("analysis/%s/BUSINESS_RULES.md is missing or is not text" % system) + rules, notes = parse_rules(text) + by_n = {r["n"]: r for r in rules} + per = {r["n"]: {} for r in rules} + samples = {r["n"]: {"main": [], "tests": []} for r in rules} + modules, budget = [], MAX_FILES + scan = {"files": 0, "textFiles": 0, "linksSkipped": 0, "cut": False} + for mod in discover_modules(workspace, system): + files, skipped, cut = walk_module(mod["path"], budget) + budget -= len(files) + names = collections.defaultdict(list) + for rel, _ in files: + names[os.path.basename(rel)].append(rel) + notes_name = next((n for n in NOTES_NAMES if n in names[n]), "") + claimed, unresolved, named = set(), 0, set() + if notes_name: + ntext = read_text(os.path.join(mod["path"], notes_name), NOTES_CAP) + if ntext is not None: + claimed, unresolved, named = claims_of(ntext, names) + ev = (ran or {}).get(mod["rel"]) or NO_RUN + test_files = 0 + for rel, full in files: + kind = file_kind(rel) + if kind == "doc": + continue + key = "tests" if kind == "test" else "main" + test_files += kind == "test" + body = read_text(full, FILE_CAP) + scan["textFiles"] += body is not None + hits = [(n, None) for n, _ in find_ids(os.path.basename(rel))] + [(n, at) for n, at in find_ids(body or "")] + # a test file backs the rules it names (on lines not marked skipped) when its name is the class or file of a test that ran and passed here + marks, backed = None, kind == "test" and bool(ev.get("known")) and os.path.splitext(os.path.basename(rel))[0].lower() in (ev.get("keys") or ()) + for n, at in hits: + if n not in by_n: + continue + slot = per[n].setdefault(mod["rel"], blank()) + slot[key] += 1 + if kind == "test": + if at is not None and marks is None: + marks = line_marks(body) + if at is None or is_live(marks, at): + slot["live"] += 1 + if backed and not slot["by"]: + slot["by"], slot["at"] = "test file", "%s/%s:%d" % (mod["rel"], rel, 0 if at is None else bisect.bisect_right(marks[0], at)) + place = "%s/%s" % (mod["rel"], rel) + if len(samples[n][key]) < SAMPLES and not any(s.rsplit(":", 1)[0] == place for s in samples[n][key]): + samples[n][key].append("%s:%d" % (place, 0 if at is None else body.count("\n", 0, at) + 1)) + for n in (ev.get("ids") or ()): + if n in by_n: + per[n].setdefault(mod["rel"], blank())["by"] = "test name" + for n in claimed & set(by_n): + per[n].setdefault(mod["rel"], blank())["claimed"] = True + for r in rules: + if r["sourceFile"] and r["sourceFile"] in named: + per[r["n"]].setdefault(mod["rel"], blank())["named"] = True + scan["files"] += len(files) + scan["linksSkipped"] += skipped + scan["cut"] = scan["cut"] or cut + modules.append({"name": mod["name"], "track": mod["track"], "path": mod["rel"], "files": len(files), "testFiles": test_files, + "notes": notes_name, "claimRowsUnresolved": unresolved}) + out = [] + for r in rules: + slots = per[r["n"]] + main, tests_n = sum(s["main"] for s in slots.values()), sum(s["tests"] for s in slots.values()) + claim = any(s["claimed"] for s in slots.values()) + out.append({"id": r["id"], "name": r["name"], "priority": r["priority"], "confidence": r["confidence"], "source": r["source"], + "main": main, "tests": tests_n, "claimed": claim, "status": status_of(main, tests_n, claim, any(s["by"] for s in slots.values())), + "perModule": slots, "samples": samples[r["n"]]}) + if scan["cut"]: + notes.append("More than %d files were found, so the scan stopped early." % MAX_FILES) + if scan["linksSkipped"]: + notes.append("%d symbolic link(s) were not followed." % scan["linksSkipped"]) + if not modules: + notes.append("No built code was found under modernized/%s, %s-uplifted or %s-reimagined." % (system, system, system)) + return {"system": clean(system, 100), "rulesFile": "analysis/%s/BUSINESS_RULES.md" % system, "modules": modules, "rules": out, + "totals": totals(out), "p0NoTests": [r["id"] for r in out if r["priority"] == "P0" and r["status"] != "tested"], + "scan": scan, "notes": notes} + + +def totals(rows): + """Per priority: rules, and how many are tested / named, not run / code only / claimed only / none.""" + out = {} + for r in rows: + t = out.setdefault(r["priority"] or "unrated", {"rules": 0, "tested": 0, NOT_RUN: 0, "code only": 0, "claimed only": 0, "none": 0}) + t["rules"] += 1 + t[r["status"]] += 1 + return dict(sorted(out.items())) + + +def module_row(r, slot): + """A rule as one module sees it: the module's own counts and the status they give.""" + return dict(r, main=slot["main"], tests=slot["tests"], live=slot["live"], claimed=slot["claimed"], by=slot["by"], at=slot["at"], + status=status_of(slot["main"], slot["tests"], slot["claimed"], bool(slot["by"]))) + + +def module_view(result, rel): + """The rules one module answers for, each with the module's own status. A rewrite answers for the rules its code, + tests or notes name, that a test of its run names, or whose legacy file its notes name; an uplift keeps the whole + code, so it answers for all. When nothing ties any rule to the module, every rule counts (`tied` is then False): + an empty list must never pass. `p0NoTests` lists the P0 rules that are not "tested": no executed test backs them.""" + mod = next((m for m in result["modules"] if m["path"] == rel), None) + rows, tied = [], True + for r in result["rules"]: + slot = r["perModule"].get(rel) or blank() + if mod and (mod["track"] == "uplift" or slot["main"] or slot["tests"] or slot["claimed"] or slot["named"] or slot["by"]): + rows.append(module_row(r, slot)) + if mod and not rows and result["rules"]: + tied = False + rows = [module_row(r, r["perModule"].get(rel) or blank()) for r in result["rules"]] + return {"rows": rows, "totals": totals(rows), "outOfScope": len(result["rules"]) - len(rows), "tied": tied, + "p0NoTests": [r["id"] for r in rows if r["priority"] == "P0" and r["status"] != "tested"]} + + +def render(result, everything=False, view=None, module=None): + """The matrix as text. With `view` (from module_view) only the rules that module answers for are listed.""" + rows = view["rows"] if view else result["rules"] + tot = view["totals"] if view else result["totals"] + missing = view["p0NoTests"] if view else result["p0NoTests"] + scanned = ", ".join("%s (%d files, %d test)" % (clean(m["name"], 60), m["files"], m["testFiles"]) for m in result["modules"] + if not module or m["name"] == module) or "nothing built yet" + head = "Rule trace for %s%s: %d rule(s) in %s" % (result["system"], ", module " + clean(module, 60) if module else "", len(result["rules"]), result["rulesFile"]) + lines = [head, "Scanned: " + scanned] + if view: + lines.append("Counted for this module: %d rule(s)%s" % (len(rows), "" if view["tied"] else " (nothing ties a rule to it by name, so every rule counts)")) + lines.append("") + for p, c in tot.items(): + lines.append("%-7s %3d rules: %d tested, %d named not run, %d code only, %d claimed only, %d none" % (p, c["rules"], c["tested"], c[NOT_RUN], c["code only"], c["claimed only"], c["none"])) + lines += ["", "%-9s %-4s %-7s %5s %5s %s" % ("Rule", "Pri", "Conf", "Code", "Tests", "Status")] + shown = [r for r in rows if everything or r["priority"] == "P0"] + ([] if everything else [r for r in rows if r["priority"] != "P0"][:40]) + for r in shown: + lines.append("%-9s %-4s %-7s %5d %5d %s %s" % (r["id"], r["priority"] or "-", r["confidence"] or "-", r["main"], r["tests"], r["status"], clean(r["name"], 60))) + if len(shown) < len(rows): + lines.append("... %d more rule(s) not listed (use --all)" % (len(rows) - len(shown))) + lines += ["", "P0 rules with no test that ran and passed behind them: " + (", ".join(missing) if missing else "none")] + lines += ["Note: " + n for n in result["notes"]] + return "\n".join(lines) + + +def main(argv=None): + ap = argparse.ArgumentParser(description="Trace business rules to the code and tests that name them, and to the tests that ran.") + ap.add_argument("system", help="the system's folder name under analysis/") + ap.add_argument("--workspace", default=".", help="the project root holding analysis/ and modernized/ (default: current folder)") + ap.add_argument("--json", action="store_true", help="print the full trace as JSON") + ap.add_argument("--all", action="store_true", help="list every rule, not just P0 and the first 40 others") + ap.add_argument("--module", metavar="NAME", help="only the rules this built module answers for (a folder under modernized/<system>/)") + ap.add_argument("--results", action="append", default=[], metavar="PATH", + help="a JUnit or TRX result file, or a folder of them, from a run of the module named by --module (repeatable); only tests that ran and passed there make a rule 'tested'") + args = ap.parse_args(argv) + if not args.system or args.system in (".", "..") or re.search(r"[\\/\x00]", args.system): + print("trace_rules.py: the system must be a folder name under analysis/, not a path", file=sys.stderr) + return 2 + if args.results and not args.module: + print("trace_rules.py: --results goes with --module: say which module's run the results are from", file=sys.stderr) + return 2 + ran, read_notes = None, [] + if args.results: + found = next((m for m in discover_modules(args.workspace, args.system) if m["name"].lower() == args.module.lower()), None) + if found is not None: + sys.dont_write_bytecode = True # importing a sibling script must not leave __pycache__ in the plugin folder + import baseline_diff # only this command line reads result files itself; the proof pack passes them in + res = baseline_diff.read_results(args.results) + ran = {found["rel"]: run_evidence([res])} + read_notes = ["%d result file(s) read: %d test(s), %d passed." % (res["files"], len(res["tests"]), sum(1 for s in res["tests"].values() if s == "PASS"))] + read_notes += ["result file not used: " + u for u in res["unreadable"][:3]] + [clean(p, 200) for p in res["problems"][:3]] + try: + result = trace(args.workspace, args.system, ran) + except OSError as err: + print("trace_rules.py: %s" % err, file=sys.stderr) + return 2 + result["notes"] += read_notes or ["No test results were given, so no rule can be 'tested' here: the proof pack reads them from the result files (or add --module NAME --results PATH)."] + view, mod = None, None + if args.module: + mod = next((m for m in result["modules"] if m["name"].lower() == args.module.lower()), None) + if mod is None: + print("trace_rules.py: no built module called %s (found: %s)" % (clean(args.module, 60), ", ".join(clean(m["name"], 40) for m in result["modules"]) or "none"), file=sys.stderr) + return 2 + view = module_view(result, mod["path"]) + if args.json: + print(json.dumps(dict(result, moduleView=view) if view else result, indent=1, ensure_ascii=True)) + else: + print(render(result, args.all, view, mod["name"] if mod else None)) + return 1 if (view["p0NoTests"] if view else result["p0NoTests"]) else 0 + + +if __name__ == "__main__": + sys.exit(main()) |
