@techierathore/techieflow 1.1.0 → 1.2.0

package/.tfcore/utils/tf-verify-list.py

@@ -1,19 +1,24 @@
 #!/usr/bin/env python3
 """tf-verify-list.py — the working list of a verify run (see tf-verify-list.sh).
 
-    bash .tfcore/utils/tf-verify-list.sh <App> <scope> [--phase N] [--json-out <file>]
+    bash .tfcore/utils/tf-verify-list.sh <App> <scope> [--phase N|all] [--json-out <file>]
 
 scope: ui (REQ-UI rows) · functional (REQ-FN, REQ-NFR, REQ-RAG) · all · a comma list of ids.
+--phase N grades phase N's checklist (default appPhase); --phase all only prints the phases that have
+a checklist, phase 1 first, as "PHASES 1 2 3", and writes nothing: the task runs one pass per phase.
 Reads the phase's checklist, the UIDesign, the BRD screens table and the UsageGuide, and prints:
   - every row in scope with its status, acceptance line, screen, route, mockup and perf budget;
     N/A rows are skipped, every other status is graded (a Verified row is re-confirmed)
   - the screens to drive, each with its route, its mockup and the rows it owns; a dialog row
     is listed under its parent screen (Schemas §2: a dialog is verified on its page)
   - rows whose screen could not be resolved (graded by their test only)
-  - the test users from the UsageGuide
+  - the test users from the UsageGuide, as plain text (no Markdown)
+  - for each screen, from the code: the page file that serves its route, that file's project, and
+    the labels of the links or buttons to click from the app's menu to reach it (Lekhak TF-027)
 Writes the same as JSON (default tests/.artifacts/verify/list.json) for the other verify scripts.
 Python 3 standard library only. Exit 0 printed, 2 could not run.
 """
+import html
 import json
 import os
 import re
@@ -86,7 +91,7 @@ def entries_of(text):
             h = re.match(r"^#{2,3}\s+(?:page|screen)\s*:\s*(.+)$", nxt, re.I)
             if h:
                 current = h.group(1).strip()
-            e = {"section": current, "acceptance": "", "mockup": "", "brd": "", "perf_budget": ""}
+            e = {"section": current, "acceptance": "", "mockup": "", "brd": "", "perf_budget": "", "zoom_check": ""}
             for j in range(i, min(i + 14, len(lines))):
                 l = lines[j]
                 if re.search(r"\*Acceptance:?\*|^\s*[-*]\s*Acceptance:", l, re.I) and not e["acceptance"]:
@@ -100,6 +105,9 @@ def entries_of(text):
                 pb = re.search(r"perf-budget:\s*([^|`]+)", l)
                 if pb and not e["perf_budget"]:
                     e["perf_budget"] = pb.group(1).strip()
+                zc = re.search(r"zoom-check:\s*(keys|kept)\b", l)   # coding-standards-dotnet.md §9b
+                if zc and not e["zoom_check"]:
+                    e["zoom_check"] = zc.group(1)
                 if j > i and re.match(r"^\s*(?:[-*]\s*)?<a id=|^## ", l):
                     break   # the next entry starts: nothing below belongs to this row
             out[rid] = e
@@ -117,14 +125,43 @@ def screens_of_uidesign(path):
         m = re.match(r"###\s+Screen:\s*(.+?)\s*\(`?([^)`]+)`?\)\s*$", p.splitlines()[0] if p.strip() else "")
         if not m:
             continue
-        mk = re.search(r"((?:docs/)?mockups/[\w./-]+\.html)", p)
-        mock = mk.group(1) if mk else ""
-        if mock and not mock.startswith("docs/"):
-            mock = "docs/" + mock
-        out.append({"name": m.group(1).strip(), "route": m.group(2).strip(), "mockup": mock})
+        mocks = []
+        for mk in re.findall(r"((?:docs/)?mockups/[\w./-]+\.html)", p):
+            mk = mk if mk.startswith("docs/") else "docs/" + mk
+            if mk not in mocks:
+                mocks.append(mk)
+        name, route = m.group(1).strip(), m.group(2).strip()
+        tabs = split_by_mockup(name, route, mocks)
+        out.extend(tabs or [{"name": name, "route": route, "mockup": mocks[0] if mocks else ""}])
     return out
 
 
+def split_by_mockup(name, route, mocks):
+    """One screen per mockup when the route takes one value and the entry links a mockup per value:
+    `/settings/{tab}` with settings-providers.html, settings-agents.html … is seven screens,
+    `/settings/providers` and so on. Kept as one screen it was never driven, and its rows were
+    Verified on their tests alone (Chatur TF-003). [] when the route or the mockups do not fit."""
+    params = re.findall(r"\{[^}]+\}", route)
+    if len(params) != 1 or len(mocks) < 2:
+        return []
+    stems = [os.path.basename(m)[:-5] for m in mocks]
+    prefix = os.path.commonprefix(stems)
+    prefix = prefix[:prefix.rfind("-") + 1] if "-" in prefix else ""
+    values = [s[len(prefix):] for s in stems]
+    if not prefix or not all(re.fullmatch(r"[a-z0-9][a-z0-9-]*", v) for v in values):
+        return []
+    return [{"name": f"{name} / {v}", "route": route.replace(params[0], v), "mockup": mk,
+             "route_pattern": route, "parent": name} for v, mk in zip(values, mocks)]
+
+
+def seed_of(screen):
+    """tests/verify/seed/<mockup name>.sh, when the project has one: it puts the running app in the
+    state the mockup draws before the screen is driven (Chatur TF-002). tf-verify-screens runs it."""
+    stem = os.path.basename(screen.get("mockup") or "")[:-5] or re.sub(r"[^a-z0-9]+", "-", screen["name"].lower()).strip("-")
+    p = os.path.join("tests", "verify", "seed", f"{stem}.sh")
+    return p if os.path.isfile(p) else ""
+
+
 def screens_of_checklist(text, ent):
     """[{name, route, mockup}] from the checklist's own '## Page: Name (`/route`, …)' headings, at ## or
     ###, for a project with no UIDesign: the first route that can be opened as typed (no `{id}`),
@@ -172,6 +209,114 @@ def usage_guide(app):
     return os.path.join("docs", f"{app}-UsageGuide.md")
 
 
+def plain(cell):
+    """A Markdown table cell as plain text: code spans, emphasis and links unwrapped."""
+    t = re.sub(r"\[([^\]]*)\]\([^)]*\)", r"\1", cell)
+    t = re.sub(r"`([^`]*)`", r"\1", t).replace("`", "")
+    return re.sub(r"(\*\*|__|\*)", "", t).strip()
+
+
+# --- how each screen is reached, read from the code (Lekhak TF-027) ---------------------------------
+# A Blazor Hybrid head on a Mac shows mac2 no data-testid and no URL, so its screens are reached by
+# clicking what a person clicks. The code says what that is: a page declares its route with @page, and
+# a link or button anywhere names a route in href/Href with its visible text. A link in a file that is
+# not a page (a layout, the menu) is on every screen; a link on a page is on that page only. Only the
+# code of the screen's own project and the projects it references counts, so a website page is never
+# looked for in the desktop app's menu.
+CODE_DIRS = ("src", "source")
+SKIP_DIRS = {"bin", "obj", "node_modules", ".git", ".tfbuild", "tests", "wwwroot"}
+LINK = re.compile(r"<([A-Za-z][\w.]*)\b([^>]*?)\b[Hh]ref\s*=\s*\"([^\"]+)\"([^>]*)>(.*?)</\1\s*>", re.S)
+
+
+def route_key(r):
+    """'/admin/llm-signin/{ProviderId:long}' and 'admin/llm-signin/@p.Id' -> ('admin', 'llm-signin', '*')"""
+    r = re.split(r"[?#]", r.strip())[0].strip("/").lower()
+    return tuple("*" if ("{" in seg or "@" in seg) else seg for seg in r.split("/")) if r else ()
+
+
+def label_of(inner):
+    t = re.sub(r"<[^>]+>", " ", inner)
+    if "@" in t:
+        return ""                                    # a label the code computes is not known here
+    t = html.unescape(t)
+    t = "".join(ch for ch in t if ch.isalnum() or ch in " +-'&/.,()")   # icon glyphs out
+    return re.sub(r"\s+", " ", t).strip()
+
+
+def code_map():
+    """-> projects {dir: [referenced dirs]}, pages {route_key: (file, project dir)}, links [(file, own keys, project, key, label)]"""
+    projects, pages, links, files = {}, {}, [], []
+    for top in CODE_DIRS:
+        for d, subs, names in os.walk(top):
+            subs[:] = [x for x in subs if x not in SKIP_DIRS and not x.startswith(".")]
+            for n in names:
+                p = os.path.join(d, n)
+                if n.endswith(".csproj"):
+                    refs = re.findall(r'<ProjectReference\s+Include="([^"]+)"', read(p))
+                    projects[d] = [os.path.normpath(os.path.join(d, os.path.dirname(x.replace("\\", "/")))) for x in refs]
+                elif n.endswith(".razor") or n.endswith(".cshtml"):
+                    files.append(p)
+    def project_of(f):
+        d = os.path.dirname(f)
+        while d and d not in projects:
+            nd = os.path.dirname(d)
+            if nd == d:
+                return ""
+            d = nd
+        return d
+    for f in files:
+        t = read(f)
+        own = [route_key(r) for r in re.findall(r'(?m)^\s*@page\s+"([^"]+)"', t)]
+        for k in own:
+            pages.setdefault(k, (f, project_of(f)))
+        for m in LINK.finditer(t):
+            lab = label_of(m.group(5))
+            if lab and not m.group(3).startswith(("http:", "https:", "mailto:", "#")):
+                links.append((f, own, project_of(f), route_key(m.group(3)), lab))
+    return projects, pages, links
+
+
+def closure(projects, d):
+    seen, todo = [], [d]
+    while todo:
+        x = todo.pop()
+        if x in seen:
+            continue
+        seen.append(x)
+        todo.extend(projects.get(x, []))
+    return seen
+
+
+def matches(a, b):
+    return len(a) == len(b) and all(x == y or "*" in (x, y) for x, y in zip(a, b))
+
+
+def navigation(screens):
+    """Adds page, project and nav (labels to click, in order) to each screen the code serves."""
+    projects, pages, links = code_map()
+    for s in screens:
+        k = route_key(s["route"])
+        hit = next(((f, pr) for pk, (f, pr) in pages.items() if matches(pk, k)), None)
+        if not hit:
+            continue
+        s["page"], s["project"] = hit[0], hit[1]
+        scope = set(closure(projects, hit[1]))
+        mine = [l for l in links if l[2] in scope]
+        # breadth first, from the links on every screen (a layout, the menu: files that are not pages)
+        paths, todo = {}, []
+        for f, own, _, to, lab in mine:
+            if not own and to not in paths:
+                paths[to] = [lab]; todo.append(to)
+        while todo:
+            cur = todo.pop(0)
+            for f, own, _, to, lab in mine:
+                if any(matches(o, cur) for o in own) and to not in paths:
+                    paths[to] = paths[cur] + [lab]; todo.append(to)
+        nav = next((p for to, p in paths.items() if matches(to, k)), None)
+        if nav is not None:
+            s["nav"] = nav
+
+
 def test_users(path):
     """The rows of the guide's Test users table. The heading may sit at ## or ### (a guide that
     numbers its chapters nests it one level down), and the table may be the template's
@@ -187,7 +332,7 @@ def test_users(path):
     for line in m.group(1).splitlines():
         if not line.strip().startswith("|"):
             continue
-        c = [x.strip().strip("`* ") for x in line.strip().strip("|").split("|")]
+        c = [x.strip() for x in line.strip().strip("|").split("|")]
         if cols is None:
             low = [x.lower() for x in c]
             def col(*names):
@@ -198,10 +343,13 @@ def test_users(path):
             continue
         if set("".join(c)) <= set("-: "):
             continue                                        # the header rule
-        if len(c) > max(cols["user"], cols["role"]) and c[cols["user"]] and not c[cols["user"]].isdigit():
-            users.append({"user": c[cols["user"]],
-                          "password_source": c[cols["pw"]] if cols["pw"] is not None and len(c) > cols["pw"] else "",
-                          "role": c[cols["role"]]})
+        if len(c) > max(cols["user"], cols["role"]) and plain(c[cols["user"]]) and not plain(c[cols["user"]]).isdigit():
+            # The cell is Markdown. The user is its first code span when it has one ("`a@b.c` (username
+            # `a`)" is a@b.c); every field is plain text, never with a stray backtick (Lekhak TF-027).
+            u = re.match(r"\s*`([^`]+)`", c[cols["user"]])
+            users.append({"user": u.group(1).strip() if u else plain(c[cols["user"]]),
+                          "password_source": plain(c[cols["pw"]]) if cols["pw"] is not None and len(c) > cols["pw"] else "",
+                          "role": plain(c[cols["role"]])})
     return users
 
 
@@ -226,21 +374,50 @@ def screen_from_acceptance(acc):
     return hits[-1].strip() if hits else ""
 
 
+def checklist_of(app, phase):
+    return os.path.join("docs", f"{app}-Checklist.md" if phase <= 1 else f"{app}-P{phase}-Checklist.md")
+
+
+def phases_of(app):
+    """The phase numbers that have a checklist, phase 1 first."""
+    found = [1] if os.path.isfile(checklist_of(app, 1)) else []
+    for f in os.listdir("docs") if os.path.isdir("docs") else []:
+        m = re.fullmatch(re.escape(app) + r"-P(\d+)-Checklist\.md", f)
+        if m and int(m.group(1)) > 1:
+            found.append(int(m.group(1)))
+    return sorted(set(found))
+
+
 def main(argv):
     if len(argv) < 3 or argv[1] in ("-h", "--help"):
         print(__doc__)
         return 0
     app, scope = argv[1], argv[2]
+    # Sevak TF-005: *verify graded only appPhase's checklist, so phases 1 and 2 (86 rows waiting) were
+    # never graded. --phase N grades that phase's checklist; --phase all prints the phases to grade, in
+    # order, and the task runs one pass per phase. Every later script reads the checklist from list.json.
+    have = phases_of(app)
     phase = int(cfg("appPhase", "1"))
     if "--phase" in argv:
-        phase = int(argv[argv.index("--phase") + 1])
+        val = argv[argv.index("--phase") + 1] if argv.index("--phase") + 1 < len(argv) else ""
+        if val == "all":
+            if not have:
+                die(f"no checklist for {app} under docs/")
+            print(f"# tf-verify-list — {app} — phase all — scope {scope}")
+            print("PHASES " + " ".join(str(p) for p in have))
+            print("Grade them one at a time, in this order: steps 1 and 4 to 6 of verify-phase.md with "
+                  + ", then ".join(f"--phase {p} ({checklist_of(app, p)})" for p in have) + ". Nothing was written.")
+            return 0
+        if not val.isdigit() or int(val) < 1:
+            die(f"--phase takes a phase number or all, not {val or 'nothing'}")
+        phase = int(val)
     out_path = os.path.join("tests", ".artifacts", "verify", "list.json")
     if "--json-out" in argv:
         out_path = argv[argv.index("--json-out") + 1]
     pfx = f"{app}-" if phase <= 1 else f"{app}-P{phase}-"
-    cl = os.path.join("docs", f"{pfx}Checklist.md")
+    cl = checklist_of(app, phase)
     if not os.path.isfile(cl):
-        die(f"{cl} does not exist")
+        die(f"{cl} does not exist" + (f"; the phases with a checklist are {', '.join(map(str, have))}" if have else ""))
     text = read(cl)
     rows = rows_of(text)
     if not rows:
@@ -252,6 +429,9 @@ def main(argv):
     dialogs = dialogs_of_brd(os.path.join("docs", f"{pfx}BRD.md"))
     users = test_users(usage_guide(app))
     by_name = {norm_name(s["name"]): s for s in screens}
+    for s in screens:                   # a split screen's own name reaches its first tab (Chatur TF-003)
+        if s.get("parent"):
+            by_name.setdefault(norm_name(s["parent"]), s)
     by_mock = {s["mockup"]: s for s in screens if s["mockup"]}
     by_route = {s["route"].lower(): s for s in screens}
     by_section = {s["section"]: s for s in screens if s.get("section")}
@@ -263,8 +443,9 @@ def main(argv):
         if r["status"] in NA:
             skipped += 1
             continue
-        e = ent.get(r["id"], {"section": "", "acceptance": "", "mockup": "", "brd": "", "perf_budget": ""})
+        e = ent.get(r["id"], {"section": "", "acceptance": "", "mockup": "", "brd": "", "perf_budget": "", "zoom_check": ""})
         row = dict(r, acceptance=e["acceptance"], mockup=e["mockup"], brd=e["brd"], perf_budget=e["perf_budget"],
+                   zoom_check=e.get("zoom_check", ""),
                    section=e["section"], screen="", route="", dialog="")
         cand = [screen_from_acceptance(e["acceptance"]), e["section"], r["title"]]
         if e["section"] in by_section:     # a screen read from the checklist: the heading the row sits under
@@ -285,6 +466,10 @@ def main(argv):
         if not row["screen"] and e["mockup"] in by_mock:
             s = by_mock[e["mockup"]]
             row["screen"], row["route"] = s["name"], s["route"]
+        # a row on a split screen belongs to the tab whose mockup it names
+        tab = by_mock.get(e["mockup"])
+        if row["screen"] and tab and tab.get("parent") and by_name.get(norm_name(row["screen"]), {}).get("parent") == tab["parent"]:
+            row["screen"], row["route"] = tab["name"], tab["route"]
         if not row["screen"] and row["class"] != "NFR":
             unresolved.append(row["id"])
         work.append(row)
@@ -293,7 +478,8 @@ def main(argv):
     for s in screens:
         owned = [r["id"] for r in work if r["screen"] == s["name"]]
         if owned:
-            screen_list.append(dict(s, rows=owned))
+            screen_list.append(dict(s, rows=owned, seed=seed_of(s)))
+    navigation(screen_list)
 
     print(f"# tf-verify-list — {app} — {cl} — phase {phase} — scope {scope}")
     counts = {}
@@ -305,12 +491,25 @@ def main(argv):
     print()
     print(f"## Screens to drive ({len(screen_list)} of {len(screens)} in the {source})")
     for s in screen_list:
-        print(f"- {s['name']} ({s['route']}) — mockup {s['mockup'] or 'none'} — rows {', '.join(s['rows'])}")
+        print(f"- {s['name']} ({s['route']}) — mockup {s['mockup'] or 'none'}"
+              + (f" — seed {s['seed']}" if s["seed"] else "")
+              + (f" — served by {s['project']}" if s.get("project") else "")
+              + (f" — reached by clicking {' > '.join(repr(x) for x in s['nav'])}" if s.get("nav") else "")
+              + f" — rows {', '.join(s['rows'])}")
+    par = [f"--screen {os.path.basename(s['mockup'])[:-5]}={s['route']}" for s in screen_list
+           if s["mockup"] and "{" not in s["route"]]
+    if par:
+        # --list carries each screen's mockup path: the --screen name is the file's stem only, so
+        # docs/mockups/admin/prompt-manager.html read as NO-MOCKUP (Lekhak TF-022)
+        print(f"Mockup parity: {' '.join(par)} --list {out_path}")
     print()
     print("## Rows")
     for r in work:
         where = f"{r['screen']} {r['route']}" + (f" — dialog {r['dialog']}" if r["dialog"] else "") if r["screen"] else "no screen resolved"
-        extra = f" — perf-budget: {r['perf_budget']}" if r["perf_budget"] else ""
+        extra = (f" — perf-budget: {r['perf_budget']}" if r["perf_budget"] else "") \
+            + (f" — zoom-check: {r['zoom_check']} (bash .tfcore/utils/tf-verify-zoom.sh --appium|--cdp <url>"
+               + (" --expect-restored 1.3, after a run with --leave 3 and a restart" if r.get("zoom_check") == "kept" else "")
+               + f" --json-out tests/.artifacts/verify/zoom/{r['id']}.json)" if r.get("zoom_check") else "")
         print(f"- {r['id']} [{r['status_raw']}] {r['title']} — {where}{extra}")
         print(f"    acceptance: {r['acceptance'] or 'MISSING — the row cannot be graded; fix the checklist'}")
     if unresolved:

package/.tfcore/utils/tf-verify-list.sh

@@ -1,8 +1,10 @@
 #!/usr/bin/env bash
 # tf-verify-list.sh — the working list of a verify run (Sitting 4c, 2026-09-06).
 #
-#   bash .tfcore/utils/tf-verify-list.sh <App> <scope> [--phase N] [--json-out <file>]
+#   bash .tfcore/utils/tf-verify-list.sh <App> <scope> [--phase N|all] [--json-out <file>]
 #
+# --phase N grades phase N's checklist (default appPhase); --phase all prints the phases to grade, in
+# order, and writes nothing (Sevak TF-005).
 # scope: ui · functional · all · a comma list of REQ ids. Prints every row to grade with its
 # acceptance line, screen, route, mockup and perf budget, the screens to drive, and the test
 # users; writes tests/.artifacts/verify/list.json for the other verify scripts. Skips N/A rows