aw-spec-cli 0.1.20 → 0.1.22

package/assets/.appweaver/scripts/python/aw-stack.py

@@ -426,7 +426,19 @@ def cmd_list(args):
     suggested_root = detected.get("root") or detected.get("profile_root") or ""
     evidence = ", ".join(detected.get("evidence", [])[:4])
 
-    ordered = sorted(profiles, key=lambda p: p["id"] != suggested_profile) \
+    # One readable line for prompts and outputs, so a caller never glues the profile
+    # and root together itself and prints " at " when the scan found nothing.
+    if not args.suggest:
+        detected_summary = "not scanned"
+    elif not suggested_profile:
+        detected_summary = "nothing detected"
+    else:
+        where = norm_root(suggested_root)
+        detected_summary = "%s at %s" % (
+            suggested_profile,
+            "the repo root" if where in ("", REPO_ROOT) else where)
+
+    ordered =sorted(profiles, key=lambda p: p["id"] != suggested_profile) \
         if suggested_profile else profiles
     options = [option_label(p) for p in ordered]
     if args.include_none:
@@ -435,11 +447,25 @@ def cmd_list(args):
     preselect = resolve_preselect(args.preselect, profiles, args.include_none, args.kind)
     preselect_source = "argument" if preselect else ""
 
-    # Candidate SOURCE PATHS for the follow-up question, best first: where the
-    # evidence actually sits, then each profile's own default. Labelled with why
+    # Candidate SOURCE PATHS for the follow-up question, best first. Labelled with why
     # each is offered, because the operator picking from this list is choosing the
     # subtree a generator will be allowed to write into. Free text is always
     # accepted — a repo that matches no profile still has a source path.
+    #
+    # WITH --profile the stack is already chosen, and the list answers for it alone:
+    # where THAT stack's evidence sits, then its own default, then where another
+    # stack's evidence sits (existing code of this kind, even if it was not what was
+    # picked). Other profiles' defaults are not offered — they describe stacks the
+    # operator did not choose.
+    #
+    # WITHOUT --profile the list is built before any choice, and a default root is
+    # usually shared (six frontend profiles default to web/), so its label names every
+    # profile that proposes it rather than whichever one sorts first.
+    chosen = None
+    if args.profile:
+        pid = profile_id_from_label(args.profile)
+        chosen = next((p for p in profiles if p["id"] == pid), None)
+
     root_options, seen = [], set()
 
     def offer(root, why):
@@ -449,12 +475,29 @@ def cmd_list(args):
         seen.add(r)
         root_options.append(ROOT_LABEL_SEP.join([r, why]))
 
-    if suggested_root:
-        offer(suggested_root, "detected here (%s)" % (suggested_profile or "evidence"))
-    for m in matches[1:]:
-        offer(m.get("root") or m.get("profile_root"), "detected here (%s)" % m["id"])
-    for p in profiles:
-        offer(p.get("root"), "%s default" % p["id"])
+    def match_root(m):
+        return m.get("root") or m.get("profile_root")
+
+    if chosen:
+        for m in matches:
+            if m["id"] == chosen["id"]:
+                offer(match_root(m), "detected here (%s)" % m["id"])
+        offer(chosen.get("root"), "%s default" % chosen["id"])
+        for m in matches:
+            offer(match_root(m), "detected here (%s)" % m["id"])
+    else:
+        if suggested_root:
+            offer(suggested_root, "detected here (%s)" % (suggested_profile or "evidence"))
+        for m in matches[1:]:
+            offer(match_root(m), "detected here (%s)" % m["id"])
+        by_root = {}
+        for p in profiles:
+            r = norm_root(p.get("root"))
+            if r:
+                by_root.setdefault(r, []).append(p["id"])
+        for r, ids in by_root.items():
+            offer(r, "%s default" % ids[0] if len(ids) == 1
+                  else "default for %s" % ", ".join(ids))
 
     emit({
         "kind": args.kind or "all",
@@ -466,6 +509,7 @@ def cmd_list(args):
         "preselect_source": preselect_source,
         "detected_profile": suggested_profile,
         "detected_root": suggested_root,
+        "detected_summary": detected_summary,
         "detected_evidence": evidence,
         "detected_count": len(matches),
         "root_options": root_options,
@@ -604,6 +648,56 @@ def roots_overlap(a, b):
     return a == b or a.startswith(b) or b.startswith(a)
 
 
+def lane_test_path(repo, lane, prof=None):
+    """Where a lane's paired tests go — the second subtree the lane owns.
+
+    Most backend stacks keep tests BESIDE the source rather than in it: .NET's `tests/`
+    next to `src/`, Maven's `src/test/java/` next to `src/main/java/`, pytest's `tests/`
+    next to `app/`. A lane that owned only its source path could not hold its own tests.
+
+    Answered at READ time, like `ecosystem`, so a lane declared before this existed has
+    one without being re-declared:
+      - a `test_root` written on the lane wins — the way to record a layout the profile
+        does not describe;
+      - else the profile's `test_root`, which pairs with the profile's default `root`. A
+        lane at that root takes it as is; a lane whose root ends with it takes it under
+        the same prefix (`backend/src/` ⇒ `backend/tests/`);
+      - else the tests live inside the source path. That is right for every frontend
+        profile, for Go's colocated `_test.go` files, and for a Maven lane rooted at the
+        directory holding its pom.xml.
+    """
+    if not lane:
+        return ""
+    root = norm_root(lane.get("root"))
+    if not root:
+        return ""
+    own = norm_root(lane.get("test_root"))
+    if own:
+        return own
+    prof = profile_of(repo, lane) if prof is None else prof
+    default_root = norm_root(prof.get("root"))
+    default_tests = norm_root(prof.get("test_root"))
+    if not default_root or not default_tests or REPO_ROOT in (default_root, default_tests):
+        return root
+    if root == default_root:
+        return default_tests
+    if root.endswith("/" + default_root):
+        return root[: -len(default_root)] + default_tests
+    return root
+
+
+def lane_owned_paths(repo, lane, prof=None):
+    """Every subtree a lane owns, labelled: its source path, and its test path when that
+    is a different directory. Ownership checks compare these, so a test path can never
+    land inside another lane's subtree."""
+    root = norm_root(lane.get("root"))
+    tests = lane_test_path(repo, lane, prof)
+    owned = [("source path", root)] if root else []
+    if tests and tests != root:
+        owned.append(("test path", tests))
+    return owned
+
+
 def cmd_declare(args):
     repo = args.repo
     data = read_stacks(repo) or {"lanes": []}
@@ -632,6 +726,7 @@ def cmd_declare(args):
             "profile": "",
             "root": "",
             "source_path": "",
+            "test_path": "",
             "root_exists": False,
             "replaced": False,
             "removed": [l.get("id") for l in removed],
@@ -718,14 +813,19 @@ def cmd_declare(args):
     if args.origin and args.origin != "declared":
         lane["origin"] = args.origin
 
-    # root IS ownership: two generators must never be able to write one file.
+    # root IS ownership, and so is the test path: two generators must never be able to
+    # write one file.
+    test_path = lane_test_path(repo, lane, prof or {})
     for other in lanes:
         if other.get("id") == lane_id:
             continue
-        if roots_overlap(root, other.get("root")):
-            fail("lane-declare: root '%s' for lane '%s' overlaps lane '%s' at '%s'. "
-                 "Lane roots own their subtree and must be disjoint."
-                 % (root, lane_id, other.get("id"), other.get("root")))
+        for mine_label, mine in lane_owned_paths(repo, lane, prof or {}):
+            for theirs_label, theirs in lane_owned_paths(repo, other):
+                if roots_overlap(mine, theirs):
+                    fail("lane-declare: %s '%s' for lane '%s' overlaps lane '%s''s %s '%s'. "
+                         "A lane owns its source path and its test path, and no two lanes "
+                         "may share a subtree."
+                         % (mine_label, mine, lane_id, other.get("id"), theirs_label, theirs))
 
     replaced = False
     for i, other in enumerate(lanes):
@@ -759,6 +859,7 @@ def cmd_declare(args):
         "origin": lane.get("origin", "declared"),
         "root": root,
         "source_path": root,
+        "test_path": test_path,
         "root_exists": exists,
         "replaced": replaced,
         "removed": [],
@@ -801,6 +902,7 @@ def kind_block(repo, lanes, kind):
     lane = next((l for l in lanes if l.get("kind") == kind), {})
     root = lane.get("root", "")
     prof = profile_of(repo, lane)
+    test_path = lane_test_path(repo, lane, prof)
     return {
         kind + "_declared": bool(lane),
         kind + "_lane_id": lane.get("id", ""),
@@ -815,9 +917,19 @@ def kind_block(repo, lanes, kind):
         kind + "_language": prof.get("language", ""),
         kind + "_ecosystem": prof.get("ecosystem", ""),
         kind + "_title": prof.get("title", "") or lane.get("stack", ""),
+        # Names this stack's AMBIENT scope already defines — C#'s implicit usings, the
+        # browser and TS globals, java.lang, typing. A domain noun that matches one is
+        # not a naming mistake (the plan's names are the ubiquitous language) but it does
+        # have to be written qualified, or the compiler cannot tell the two apart.
+        kind + "_reserved_names": prof.get("reserved_names", []),
+        kind + "_reserved_csv": ", ".join(prof.get("reserved_names", [])),
         kind + "_root": root,
         kind + "_source_path": root,
         kind + "_root_exists": root_on_disk(repo, root),
+        # Where the lane's paired tests go. Equal to the source path when the stack keeps
+        # its tests inside it; see lane_test_path.
+        kind + "_test_path": test_path,
+        kind + "_test_path_exists": root_on_disk(repo, test_path),
         kind + "_build": lane_command(lane, "build"),
         kind + "_test": lane_command(lane, "test"),
         kind + "_run": lane_command(lane, "run"),
@@ -825,6 +937,33 @@ def kind_block(repo, lanes, kind):
     }
 
 
+def lane_options(repo, lanes):
+    """One selectable line per declared lane: its id, then what it is and where it lives.
+
+    The same "<value>  — <why it is offered>" shape as the source-path options, so a
+    caller hands the selection straight back as `--id` and `resolve` strips the label
+    off it. A phase that has to ask WHICH LANE — `foundation` scaffolds into exactly
+    one — then turns the answer into a path with no second lookup and no parsing of
+    its own.
+    """
+    out = []
+    for lane in lanes:
+        lid = lane.get("id", "")
+        if not lid:
+            continue
+        prof = profile_of(repo, lane)
+        title = (prof.get("title", "") or lane.get("stack", "")
+                 or lane.get("profile", "") or "no stack declared")
+        root = norm_root(lane.get("root"))
+        where = "the repo root" if root == REPO_ROOT else (root or "no source path")
+        label = "%s %s at %s" % (lane.get("kind", "lane"), title, where)
+        tests = lane_test_path(repo, lane, prof)
+        if tests and tests != root:
+            label += ", tests in %s" % tests
+        out.append(ROOT_LABEL_SEP.join([lid, label]))
+    return out
+
+
 def cmd_resolve(args):
     data = read_stacks(args.repo)
 
@@ -834,8 +973,9 @@ def cmd_resolve(args):
     if data is None:
         payload = {
             "declared": False, "exists": False, "lanes": [], "lane_count": 0,
+            "lane_options": [],
             "found": False, "lane": {}, "kinds": [], "prototype": {},
-            "lane_id": "", "root": "", "source_path": "", "root_exists": False,
+            "lane_id": "", "root": "", "source_path": "", "test_path": "", "root_exists": False,
             "build": "", "test": "", "run": "", "migrate": "",
             "language": "", "ecosystem": "",
             "path": STACKS_REL,
@@ -847,8 +987,11 @@ def cmd_resolve(args):
 
     lanes = data.get("lanes") or []
     match = {}
-    if args.id:
-        match = next((l for l in lanes if l.get("id") == args.id), {})
+    # The id may arrive as a whole option line — `user_select` hands back the string it
+    # displayed, label and all — so strip it the way a source path is stripped.
+    wanted = strip_root_label(args.id) if args.id else ""
+    if wanted:
+        match = next((l for l in lanes if l.get("id") == wanted), {})
     elif args.kind:
         match = next((l for l in lanes if l.get("kind") == args.kind), {})
 
@@ -859,12 +1002,14 @@ def cmd_resolve(args):
         "exists": True,
         "lanes": lanes,
         "lane_count": len(lanes),
+        "lane_options": lane_options(args.repo, lanes),
         "kinds": sorted({l.get("kind", "") for l in lanes if l.get("kind")}),
         "found": bool(match),
         "lane": match,
         "lane_id": match.get("id", ""),
         "root": match.get("root", ""),
         "source_path": match.get("root", ""),
+        "test_path": lane_test_path(args.repo, match),
         "root_exists": root_on_disk(args.repo, match.get("root", "")),
         "build": lane_command(match, "build"),
         "test": lane_command(match, "test"),
@@ -956,17 +1101,22 @@ def cmd_verify(args):
         # `declare` refuses an overlap, so one can only arrive here through a
         # hand-edited file — a supported way to fill this in, and the one path that
         # does not pass the writer. The invariant is worth a second check anywhere:
-        # two lanes sharing a subtree means two generators can write one file.
+        # two lanes sharing a subtree means two generators can write one file. A lane
+        # owns its test path as well as its source path, so both are compared.
         for i, first in enumerate(lanes):
             for second in lanes[i + 1:]:
-                if roots_overlap(first.get("root"), second.get("root")):
+                clash = next(((fl, fp, sl, sp)
+                              for fl, fp in lane_owned_paths(repo, first)
+                              for sl, sp in lane_owned_paths(repo, second)
+                              if roots_overlap(fp, sp)), None)
+                if clash:
                     issues.append(
-                        "lanes '%s' and '%s' claim overlapping source paths '%s' and '%s'. "
-                        "Lane roots own their subtree and must be disjoint, or two "
-                        "generators can write the same file. Give each lane a source path "
-                        "outside the other's."
+                        "lanes '%s' and '%s' claim overlapping subtrees: %s '%s' and %s '%s'. "
+                        "A lane owns its source path and its test path, and they must be "
+                        "disjoint from every other lane's, or two generators can write the "
+                        "same file. Give each lane paths outside the other's."
                         % (first.get("id", "?"), second.get("id", "?"),
-                           first.get("root", ""), second.get("root", "")))
+                           clash[0], clash[1], clash[2], clash[3]))
 
     payload = {
         "ok": not issues,
@@ -981,7 +1131,10 @@ def cmd_verify(args):
         # No lanes always carries an issue now, so a clean run always has lanes to name.
         "message": " ".join(issues) if issues else
                    ("lane model ok: " + ", ".join(
-                       "%s (%s) at %s" % (l.get("id", "?"), l.get("profile", "?"), l.get("root", "?"))
+                       "%s (%s) at %s%s" % (
+                           l.get("id", "?"), l.get("profile", "?"), l.get("root", "?"),
+                           "".join(", tests at " + p for label, p in lane_owned_paths(repo, l)
+                                   if label == "test path"))
                        for l in lanes)),
         "path": STACKS_REL,
     }
@@ -1009,6 +1162,38 @@ def cmd_verify(args):
 # command, and a lane the project never wired up should not fail a build.
 
 LOG_TAIL = 1400
+# Per FAILING lane, for both the tail and the excerpt. Budgeted per lane rather than over
+# the joined string: cutting the join to a global tail drops the FIRST failing lane's
+# output entirely, which is how a fix agent came to be shown a green .NET restore while
+# the web lane was the one that failed.
+LANE_TAIL = 900
+LANE_EXCERPT = 1100
+
+
+def _testlog():
+    """aw-testlog.py, loaded by path because its filename is not an importable module
+    name. Returns None when it is unavailable, and every caller degrades."""
+    try:
+        import importlib.util
+        path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "aw-testlog.py")
+        spec = importlib.util.spec_from_file_location("aw_testlog", path)
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+        return mod
+    except Exception:
+        return None
+
+
+def _failing_excerpt(text, budget, label, mod=None):
+    """The failing lines of one lane's output, or a plain tail if the helper is gone."""
+    mod = mod or _testlog()
+    if mod:
+        try:
+            return mod.excerpt(text, budget, label)
+        except Exception:
+            pass
+    tail = (text or "")[-budget:].strip()
+    return ("[%s]\n%s" % (label, tail)) if tail else ""
 
 
 def cmd_run_phase(args):
@@ -1021,7 +1206,12 @@ def cmd_run_phase(args):
     if args.kind:
         lanes = [l for l in lanes if l.get("kind") == args.kind]
 
-    results, tails, cmds = [], [], []
+    results, tails, cmds, excerpts, failing = [], [], [], [], []
+    # A lane whose command never RAN — no test script, no runner, no test project — is not
+    # a red suite: there is no failing test to repair. Tracked apart from `failing` so a
+    # caller can warn about the setup instead of sending a fix loop after nothing.
+    unwired, suite_ran = [], False
+    testlog = _testlog()
     ok, ran = True, False
     for lane in lanes:
         cmd = lane_command(lane, args.phase)
@@ -1038,6 +1228,9 @@ def cmd_run_phase(args):
             results.append({"lane": lane_id, "root": root, "cmd": cmd, "ran": False, "ok": False,
                             "error": "source path '%s' is not a directory" % root})
             tails.append("[%s] source path '%s' is not a directory" % (lane_id, root))
+            excerpts.append("[%s] source path '%s' is not a directory — nothing ran"
+                            % (lane_id, root))
+            failing.append(lane_id)
             continue
         ran = True
         cmds.append(cmd)
@@ -1051,7 +1244,29 @@ def cmd_run_phase(args):
                         "ok": lane_ok, "exit_code": proc.returncode,
                         "cwd": os.path.relpath(workdir, repo).replace("\\", "/")})
         if not lane_ok or args.phase == "run":
-            tails.append("[%s] %s" % (lane_id, out[-LOG_TAIL:]))
+            tails.append("[%s] %s" % (lane_id, out[-LANE_TAIL:]))
+        why = ""
+        if not lane_ok and testlog:
+            try:
+                _unwired, why = testlog.no_setup(out, proc.returncode)
+            except Exception:
+                why = ""
+        if lane_ok or not why:
+            suite_ran = True          # a suite that passed, or one that genuinely failed
+        if not lane_ok:
+            failing.append(lane_id)
+            if why:
+                unwired.append({"lane": lane_id, "reason": why})
+                results[-1]["no_setup"] = why
+            # The command is a project-supplied string and can be any length, so the label
+            # carries a readable head of it, on one line.
+            shown = " ".join(cmd.split())
+            if len(shown) > 80:
+                shown = shown[:77] + "…"
+            label = "%s · %s · exit %d" % (lane_id, shown, proc.returncode)
+            if why:
+                label += " · NOT WIRED UP"
+            excerpts.append(_failing_excerpt(out, LANE_EXCERPT, label, testlog))
 
     emit({
         "ok": ok,
@@ -1065,7 +1280,18 @@ def cmd_run_phase(args):
         "lanes_skipped": [r["lane"] for r in results if not r["ran"]],
         "results": results,
         "cmd": " && ".join(cmds),
-        "log_tail": "\n".join(tails)[-LOG_TAIL:],
+        # Every failing lane is represented: each contributes its own budgeted share, and
+        # the join is not cut again.
+        "log_tail": "\n".join(tails),
+        "failing_lanes": failing,
+        "failing_excerpt": "\n\n".join(e for e in excerpts if e),
+        # `no_setup` is the whole-run verdict: NOTHING ran a suite, and at least one lane
+        # said why. With one lane genuinely failing beside one that is not wired up, this
+        # stays false — there IS a failure to fix — and `setup_missing` still names the
+        # other lane so it is not lost.
+        "no_setup": bool(unwired) and not suite_ran,
+        "setup_missing": unwired,
+        "setup_reason": "; ".join("%s: %s" % (u["lane"], u["reason"]) for u in unwired),
     })
 
 
@@ -1169,6 +1395,9 @@ def main():
                    help="also run detection over this repo, so the menu opens on the "
                         "stack the files point at and root_options leads with the "
                         "directory the evidence sits in")
+    p.add_argument("--profile", default="",
+                   help="the stack already chosen (id or select_options label); root_options "
+                        "is then built for that stack alone")
     p.set_defaults(func=cmd_list)
 
     p = sub.add_parser("detect", help="match the repo's files against the installed profiles")

package/assets/.appweaver/scripts/python/aw-testlog.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""
+aw-testlog — the FAILING LINES of a test log, not the last lines of it.
+
+Backs the `failing_excerpt` field of `test-run` in both shells, and is imported by
+aw-stack.py's run-phase for the multi-lane path, so there is ONE implementation of what
+counts as a failure line.
+
+WHY IT EXISTS. The fix loop used to be handed `log_tail`: the last 1400 characters,
+whatever they were. A .NET run prints its restore banner first and a test runner prints
+its summary last, and on a two-lane run the lanes' tails were joined and then cut again —
+so the fix agent could be shown a successful restore while the failure it was asked to
+repair was the other lane's, thousands of characters earlier. Asking a model to fix a
+failure from a log that shows nothing wrong invites invention.
+
+WHAT IT KEEPS. Lines that NAME a failure (error, failed, assertion, exception, traceback,
+a runner's ✕/✗, a `not ok` TAP line, a stack frame) plus one line before and two after, in
+file order, first occurrences first — a cascade is usually explained by the first failure,
+so a budget is better spent at the start than at the end. Anything dropped is stated.
+
+IT ALSO ANSWERS WHETHER THE SUITE RAN AT ALL. A lane whose test command is not wired up —
+`npm test` on a scaffold that defines no `test` script, a runner that is not installed, a
+solution with no test project — fails like a red suite and is nothing of the kind: there is
+no failing test to repair, and a fix loop spends its attempts rediscovering that. The
+callers use `no_setup` to tell the two apart, and it reports the reason in the lane's own
+words rather than "tests failed".
+
+Usage:
+  aw-testlog.py [--file LOG | -] [--budget N] [--label TEXT] [--exit N]
+      -> {"excerpt": "...", "lines": N, "no_setup": bool, "reason": "..."}
+"""
+
+import argparse
+import json
+import re
+import sys
+
+# Deliberately broad: it feeds a prompt, and a false positive costs a few lines of context
+# while a false negative costs the fix agent the only line that mattered.
+FAIL_RX = re.compile(
+    r"(?i)(?:^|[^a-z])("
+    r"error|errors|failed|failure|failures|failing|fails"
+    r"|assert\w*|exception|panic|traceback|fatal|segfault"
+    r"|not ok|✕|✗|×|\[FAIL\]|FAIL:|FAILED|E/|❌"
+    r")(?:[^a-z]|$)")
+# Stack frames and file:line references carry the location and rarely match the words above.
+FRAME_RX = re.compile(r"^\s*(at\s+\S+|File \"|\S+\.(cs|ts|tsx|js|jsx|py|java|kt|go|rb|php):\d+)")
+BEFORE, AFTER = 1, 2
+DEFAULT_BUDGET = 1600
+
+# "The command never ran", in the words each toolchain uses for it. Each entry is
+# (pattern, what to tell the operator). Deliberately narrow: every one of these means
+# there was no suite, not that a suite failed — the wrong call in this direction would
+# downgrade a real red run to a warning.
+NO_SETUP = [
+    (r"(?im)^\s*npm error Missing script:\s*\"?(\w+)",
+     "the lane's package.json defines no \"%s\" script — npm had nothing to run"),
+    (r"(?im)^\s*npm ERR! missing script:\s*(\w+)",
+     "the lane's package.json defines no \"%s\" script — npm had nothing to run"),
+    (r"(?i)\bno test (?:source )?files were specified\b",
+     "the test command found no test project to run"),
+    (r"(?i)\bMSB1003\b|\bno projects? (?:were )?found\b",
+     "the test command found no project to run"),
+    (r"(?i)\b(?:command not found|is not recognized as an internal or external command)\b",
+     "the test command is not installed on this machine"),
+    (r"(?i)\bno module named\s+(\w+)",
+     "the test runner (%s) is not installed in this environment"),
+    (r"(?i)\bno tests ran\b|\bno tests found\b|\bcollected 0 items\b",
+     "the runner ran but found no tests"),
+]
+# Every shell answers a missing executable this way, whatever the stack.
+EXIT_NOT_FOUND = (126, 127)
+
+
+def no_setup(text, exit_code=None):
+    """(True, reason) when the log says the suite never ran; (False, "") otherwise."""
+    for rx, why in NO_SETUP:
+        m = re.search(rx, text or "")
+        if m:
+            return True, (why % m.group(1)) if "%s" in why and m.groups() else why
+    if exit_code in EXIT_NOT_FOUND:
+        return True, "the test command could not be executed (exit %d)" % exit_code
+    return False, ""
+
+
+def excerpt(text, budget=DEFAULT_BUDGET, label=""):
+    """The failing lines of one log, with context, within `budget` characters."""
+    if not text:
+        return ""
+    lines = text.replace("\r\n", "\n").split("\n")
+    keep = set()
+    for i, line in enumerate(lines):
+        if FAIL_RX.search(line) or FRAME_RX.match(line):
+            for j in range(max(0, i - BEFORE), min(len(lines), i + AFTER + 1)):
+                keep.add(j)
+    if not keep:
+        # Nothing names a failure — the tail is the best available answer, and saying so
+        # is better than an empty excerpt the reader would take for "no failure".
+        tail = text[-budget:].strip()
+        return (("[%s] " % label if label else "") +
+                "no line names a failure; last output:\n" + tail) if tail else ""
+
+    out, used, gap, dropped, last = [], 0, False, 0, None
+    for i in sorted(keep):
+        if last is not None and i > last + 1:
+            gap = True
+        line = lines[i]
+        if used + len(line) + 1 > budget:
+            dropped = len([k for k in sorted(keep) if k >= i])
+            break
+        if gap:
+            out.append("   …")
+            used += 5
+            gap = False
+        out.append(line)
+        used += len(line) + 1
+        last = i
+    body = "\n".join(out).strip()
+    if dropped:
+        body += "\n   … %d more matching line(s) not shown" % dropped
+    return ("[%s]\n" % label if label else "") + body
+
+
+def main():
+    ap = argparse.ArgumentParser(description="extract the failing lines of a test log")
+    ap.add_argument("--file", default="-", help="log file, or - for stdin")
+    ap.add_argument("--budget", type=int, default=DEFAULT_BUDGET)
+    ap.add_argument("--label", default="", help="lane or tool name to prefix the excerpt with")
+    ap.add_argument("--exit", dest="exit_code", type=int, default=None,
+                    help="the command's exit code, so 126/127 read as 'not executable'")
+    args = ap.parse_args()
+    if args.file in ("", "-"):
+        text = sys.stdin.read()
+    else:
+        try:
+            text = open(args.file, encoding="utf-8", errors="replace").read()
+        except OSError:
+            text = ""
+    body = excerpt(text, args.budget, args.label)
+    unwired, reason = no_setup(text, args.exit_code)
+    sys.stdout.write(json.dumps({"excerpt": body,
+                                 "lines": len(body.split("\n")) if body else 0,
+                                 "no_setup": unwired, "reason": reason},
+                                separators=(",", ":")) + "\n")
+
+
+if __name__ == "__main__":
+    main()