aw-spec-cli 0.1.29 → 0.1.30

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

@@ -16,6 +16,25 @@ model sha does, and an unrecognised verdict records as `gaps`. That rule changed
 and kept in step by eye. One module both shells invoke removes the question: there is
 nothing left to keep in step. Same reason aw-crstate.py owns "has this change merged".
 
+ONE RECEIPT PER LANE. With --lane, the receipt is `.aw-plan-gate.<lane>.json` and it
+hashes the spec, the model and THAT lane's plan only, with that lane's verdict. A backend
+developer and a frontend developer gate their own plans at different times, so a frontend
+plan edited, or left with gaps, never refuses the backend's implement, and the reverse.
+A feature gated before the per-lane receipts existed still has the shared
+`.aw-plan-gate.json`: `check --lane` falls back to it and compares only that lane's plan
+names in it, so the other lane's document moving does not read as this lane's drift.
+Without --lane both commands keep the shared receipt.
+
+THE FRONTEND RECEIPT ALSO HASHES THE BACKEND'S PUBLISHED SURFACE. A frontend plan binds to
+the operations the backend plan's API section publishes, and the backend developer can
+change that section after the frontend was gated — rename an operation, change a field,
+answer a contract request. So the frontend receipt records `surface_sha`, the hash of that
+section (aw-stack's api_section; the whole backend plan when it has none, "" when there is
+no backend plan), and `check --lane frontend` reads a different surface as moved bytes. The
+backend plan's other sections are not in it: a change to the domain or infrastructure
+layers leaves the frontend receipt fresh. A receipt written before the field existed has no
+baseline for it and is not refused over it.
+
 NO BASELINE IS NOT "NOTHING MOVED". `spec_moved` / `model_moved` report "" where there is
 nothing to compare against — no receipt, or a receipt that hashed nothing for that
 document. "" is falsy in Python, in PowerShell and to the engine's require_true, so every
@@ -23,14 +42,14 @@ flag computed from them reads exactly as a false did; what it buys is that a rea
 tell "unchanged" from "unknown", which a bare false cannot express.
 
 Usage:
-  aw-plangate.py stamp --feature-dir <p> --context-dir <p> --root <p>
+  aw-plangate.py stamp --feature-dir <p> --context-dir <p> --root <p> [--lane <k>]
                        [--spec-version <v>] [--mode <text>]
                        [--verdict conformant|routed-gaps|gaps] [--plan-gaps <n>]
                        [--routed <json list>]
       -> {file, gated, spec_version, verdict, plan_gaps, routed_gaps, hashed[], count}
-  aw-plangate.py check --feature-dir <p> --context-dir <p> --root <p>
-      -> {file, tracked, gate_fresh, verdict, may_generate, plan_gaps, routed_gaps[],
-          routed_csv, spec_moved, model_moved, plans_changed[], plans_changed_csv,
+  aw-plangate.py check --feature-dir <p> --context-dir <p> --root <p> [--lane <k>]
+      -> {file, lane, shared, tracked, gate_fresh, verdict, may_generate, plan_gaps, routed_gaps[],
+          routed_csv, spec_moved, model_moved, surface_moved, plans_changed[], plans_changed_csv,
           gated, spec_version, reason}
 """
 
@@ -56,6 +75,16 @@ VERDICTS = ("conformant", "routed-gaps", "gaps")
 # implement actually generates from is unwatched.
 PLAN_NAMES = ("backend-plan.md", "frontend-plan.md", "design.md", "design.ui.md")
 
+# Each lane's plan, under its current name and its pre-lane-split one.
+LANE_PLAN_NAMES = {
+    "backend": ("backend-plan.md", "design.md"),
+    "frontend": ("frontend-plan.md", "design.ui.md"),
+}
+
+
+def receipt_name(lane=""):
+    return ".aw-plan-gate.%s.json" % lane if lane in LANE_PLAN_NAMES else RECEIPT
+
 NOTE = ("Written by every master-mode analyze-plan run. It records the bytes that were "
         "checked against each other and the verdict on them, not a version — the plans' "
         "**Version**: headers are stamped in lockstep by close-delta and cannot answer "
@@ -71,10 +100,39 @@ def sha(path):
         return ""
 
 
+def _api_section(text):
+    """aw-stack's api_section, loaded by path because its filename is not an importable
+    module name; the whole text when it cannot be loaded."""
+    try:
+        import importlib.util
+        path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "aw-stack.py")
+        spec = importlib.util.spec_from_file_location("aw_stack", path)
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+        return mod.api_section(text)
+    except Exception:
+        return None
+
+
+def surface_sha(fd):
+    """The hash of the backend plan's published surface — its API section, or the whole plan
+    when it has none; "" when the feature has no backend plan."""
+    for name in LANE_PLAN_NAMES["backend"]:
+        path = os.path.join(fd, name)
+        if os.path.isfile(path):
+            with open(path, encoding="utf-8", errors="replace") as fh:
+                text = fh.read()
+            section = _api_section(text)
+            return hashlib.sha256((section if section is not None else text)
+                                  .encode("utf-8")).hexdigest()
+    return ""
+
+
 def stamp(fd, ctx, root, spec_version="", mode="master", verdict="conformant",
-          plan_gaps=0, routed=None):
+          plan_gaps=0, routed=None, lane=""):
+    lane = lane if lane in LANE_PLAN_NAMES else ""
     plans = {}
-    for name in PLAN_NAMES:
+    for name in (LANE_PLAN_NAMES[lane] if lane else PLAN_NAMES):
         h = sha(os.path.join(fd, name))
         if h:
             plans[name] = h
@@ -99,30 +157,50 @@ def stamp(fd, ctx, root, spec_version="", mode="master", verdict="conformant",
         "plans": plans,
         "note": NOTE,
     }
-    path = os.path.join(fd, RECEIPT)
+    if lane:
+        rec["lane"] = lane
+    if lane == "frontend":
+        rec["surface_sha"] = surface_sha(fd)
+    path = os.path.join(fd, receipt_name(lane))
     with open(path, "w", encoding="utf-8") as fh:
         fh.write(json.dumps(rec, indent=2) + "\n")
-    return {"file": os.path.relpath(path, root), "gated": rec["gated"],
+    return {"file": os.path.relpath(path, root), "lane": lane, "gated": rec["gated"],
             "spec_version": rec["spec_version"], "verdict": verdict,
             "plan_gaps": plan_gaps, "routed_gaps": len(routed),
             "hashed": sorted(plans.keys()), "count": len(plans), "ok": True}
 
 
-def check(fd, ctx, root):
-    path = os.path.join(fd, RECEIPT)
+def _load(path):
     try:
-        rec = json.load(open(path, encoding="utf-8"))
+        return json.load(open(path, encoding="utf-8"))
     except Exception:
-        rec = None
-    out = {"file": os.path.relpath(path, root), "tracked": bool(rec), "gate_fresh": False,
+        return None
+
+
+def check(fd, ctx, root, lane=""):
+    lane = lane if lane in LANE_PLAN_NAMES else ""
+    path = os.path.join(fd, receipt_name(lane))
+    rec = _load(path)
+    shared = False
+    if lane and rec is None:
+        # A feature gated before the per-lane receipts: read the shared one, narrowed to
+        # this lane's plan names below.
+        legacy = os.path.join(fd, RECEIPT)
+        rec = _load(legacy)
+        if rec is not None:
+            path, shared = legacy, True
+    out = {"file": os.path.relpath(path, root), "lane": lane, "shared": shared,
+           "tracked": bool(rec), "gate_fresh": False,
            "verdict": "", "may_generate": True, "plan_gaps": 0, "routed_gaps": [],
-           "routed_csv": "", "spec_moved": "", "model_moved": "", "plans_changed": [],
+           "routed_csv": "", "spec_moved": "", "model_moved": "", "surface_moved": "",
+           "plans_changed": [],
            "plans_changed_csv": "", "gated": "", "spec_version": "", "reason": "", "ok": True}
     if not rec:
         # Never gated. Not a failure and not a stale plan — an unknown, and the only honest
         # thing to report about a tree that has not run analyze-plan since this op existed.
-        out["reason"] = ("no .aw-plan-gate.json — this feature has not been through "
-                         "analyze-plan in master mode since the gate began leaving a receipt")
+        out["reason"] = ("no %s — this feature's %s has not been through analyze-plan in "
+                         "master mode since the gate began leaving a receipt"
+                         % (receipt_name(lane), ("%s plan" % lane) if lane else "plans"))
         return out
 
     out["gated"] = rec.get("gated", "")
@@ -149,11 +227,18 @@ def check(fd, ctx, root):
 
     changed = []
     for name, was in sorted((rec.get("plans") or {}).items()):
+        if lane and name not in LANE_PLAN_NAMES[lane]:
+            continue
         if sha(os.path.join(fd, name)) != was:
             changed.append(name)
     out["plans_changed"] = changed
     out["plans_changed_csv"] = ", ".join(changed)
-    out["gate_fresh"] = not (out["spec_moved"] or out["model_moved"] or changed)
+    # The backend's published surface, for the frontend lane only. "" recorded means the
+    # frontend was gated with no backend plan, so a backend plan written since has moved it.
+    if lane == "frontend" and "surface_sha" in rec:
+        out["surface_moved"] = (rec.get("surface_sha") or "") != surface_sha(fd)
+    out["gate_fresh"] = not (out["spec_moved"] or out["model_moved"] or out["surface_moved"]
+                             or changed)
     # Moved bytes refuse whatever the verdict was; unmoved bytes refuse only on `gaps`.
     out["may_generate"] = out["gate_fresh"] and out["verdict"] != "gaps"
 
@@ -163,6 +248,9 @@ def check(fd, ctx, root):
             bits.append("spec.md has changed")
         if out["model_moved"]:
             bits.append("domain-model.md has changed")
+        if out["surface_moved"]:
+            bits.append("the backend plan's published surface (its API section) has changed — "
+                        "re-gate the frontend plan against it")
         if changed:
             bits.append("%s changed (a re-derive by `plan main`, or a hand edit)"
                         % ", ".join(changed))
@@ -190,6 +278,8 @@ def main():
         p.add_argument("--feature-dir", required=True)
         p.add_argument("--context-dir", required=True)
         p.add_argument("--root", required=True)
+        p.add_argument("--lane", default="", choices=["", "backend", "frontend"],
+                       help="the lane's own receipt (.aw-plan-gate.<lane>.json)")
         if name == "stamp":
             p.add_argument("--spec-version", default="")
             p.add_argument("--mode", default="master")
@@ -206,9 +296,9 @@ def main():
         if not isinstance(routed, list):
             routed = []
         out = stamp(args.feature_dir, args.context_dir, args.root, args.spec_version,
-                    args.mode, args.verdict, args.plan_gaps, routed)
+                    args.mode, args.verdict, args.plan_gaps, routed, args.lane)
     else:
-        out = check(args.feature_dir, args.context_dir, args.root)
+        out = check(args.feature_dir, args.context_dir, args.root, args.lane)
     sys.stdout.write(json.dumps(out) + "\n")