feature-flow-cli 0.1.0__py3-none-any.whl

feature_flow/status.py

@@ -0,0 +1,231 @@
+"""The ticket graph reader, ported from the bash script of the same name.
+
+usage: python3 scripts/flow-status.py <feature> [--next | --counts | --check | --mermaid [plain] | --json]
+Exit codes for --next: 0 a ready ticket path is printed, 10 all done, 11 unfinished but nothing ready.
+"""
+
+import os
+import re
+import sys
+
+from feature_flow import tickets
+
+USAGE = "usage: python3 scripts/flow-status.py <feature> [--next | --counts | --check | --mermaid [plain] | --json]"
+
+
+def _env(name, default):
+    return os.environ.get(name) or default
+
+
+def jstr(s):
+    out = ['"']
+    for c in s:
+        if c == "\\":
+            out.append("\\\\")
+        elif c == '"':
+            out.append('\\"')
+        elif c == "\t":
+            out.append("\\t")
+        elif c == "\001":
+            out.append("\\n")
+        elif c < " ":
+            pass
+        else:
+            out.append(c)
+    out.append('"')
+    return "".join(out)
+
+
+def run(argv, out, err):
+    """Write what the bash script would to out and err, and return its exit code."""
+    feature = argv[0] if len(argv) > 0 else ""
+    mode = argv[1] if len(argv) > 1 and argv[1] != "" else "table"
+    opt = argv[2] if len(argv) > 2 else ""
+    if feature == "":
+        err.write(USAGE + "\n")
+        return 2
+    root = _env("FLOW_DIR", "plans")
+    folder = "%s/%s/%s" % (root, feature, _env("FLOW_TICKETS", "tasks"))
+    if not os.path.isdir(folder):
+        err.write("no ticket folder: %s\n" % folder)
+        return 2
+    paths = tickets.ticket_files(folder)
+    if not paths:
+        err.write("no tickets in %s\n" % folder)
+        return 2
+
+    if mode == "--check":
+        learnings = "%s/%s/learnings.md" % (root, feature)
+        if os.path.isfile(learnings):
+            lines = sum(1 for line in tickets.records(learnings) if line.strip(" \t\n\v\f\r") != "")
+            if lines > 40:
+                out.write("warning: learnings.md has %d lines. every session reads it, so a human should prune it\n"
+                          % lines)
+
+    g = tickets.Graph(paths)
+    return _report(g, mode, opt, feature, out, err)
+
+
+def _report(g, mode, opt, feature, out, err):
+    n = len(g.order)
+    count = {"resolved": 0, "open": 0, "claimed": 0, "waiting": 0, "parked": 0, "unknown": 0}
+    ready = {}
+    first = None
+    unfinished = 0
+    for t in g.order:
+        ready[t] = False
+        count[g.stat[t]] += 1
+        if g.stat[t] == "open":
+            if all(d in g.seen and g.stat[d] == "resolved" for d in g.blk[t]):
+                ready[t] = True
+                if first is None:
+                    first = t
+        if g.stat[t] not in ("resolved", "parked"):
+            unfinished += 1
+    nready = sum(1 for t in g.order if ready[t])
+
+    if mode == "--next":
+        if first is not None:
+            out.write(g.path[first] + "\n")
+            return 0
+        if unfinished == 0:
+            err.write("COMPLETE\n")
+            return 10
+        err.write("stuck: %d claimed, %d waiting, %d open but blocked, %d unknown status\n"
+                  % (count["claimed"], count["waiting"], count["open"], count["unknown"]))
+        return 11
+
+    counts = (n, count["resolved"], count["open"], count["claimed"], count["waiting"], count["parked"],
+              count["unknown"], nready)
+
+    if mode == "--counts":
+        out.write("total=%d resolved=%d open=%d claimed=%d waiting=%d parked=%d unknown=%d ready=%d\n" % counts)
+        return 0
+
+    if mode == "--json":
+        parts = []
+        for t in g.order:
+            bl = ",".join(jstr(g.lab[d] if d in g.seen else "%02d" % d) for d in g.blk[t])
+            parts.append('{"id":%d,"label":%s,"title":%s,"status":%s,"type":%s,"test_first":%s,"blocked_by":[%s],'
+                         '"ready":%s,"file":%s}'
+                         % (t, jstr(g.lab[t]), jstr(g.title[t]), jstr(g.stat[t]), jstr(g.typ.get(t) or "task"),
+                            jstr(g.tf.get(t, "")), bl, "true" if ready[t] else "false", jstr(g.path[t])))
+        out.write('{"feature":%s,"tickets":[%s],"counts":{"total":%d,"resolved":%d,"open":%d,"claimed":%d,'
+                  '"waiting":%d,"parked":%d,"unknown":%d,"ready":%d}}\n' % ((jstr(feature), ",".join(parts)) + counts))
+        return 0
+
+    if mode == "--mermaid":
+        out.write("flowchart TD\n")
+        for t in g.order:
+            cls = g.stat[t]
+            if cls == "open":
+                cls = "ready" if ready[t] else "open"
+            if cls == "unknown":
+                cls = "open"
+            suffix = "" if opt == "plain" else ":::" + cls
+            out.write('  T%s["%s %s"]%s\n' % (g.lab[t], g.lab[t], g.title[t].replace('"', "'"), suffix))
+        for t in g.order:
+            for d in g.blk[t]:
+                if d in g.seen:
+                    out.write("  T%s --> T%s\n" % (g.lab[d], g.lab[t]))
+        if opt != "plain":
+            out.write("  classDef resolved fill:#d4edda,stroke:#2e7d32\n"
+                      "  classDef ready fill:#fff3cd,stroke:#b8860b\n"
+                      "  classDef open fill:#f5f5f5,stroke:#999999\n"
+                      "  classDef claimed fill:#cfe2ff,stroke:#1d4ed8\n"
+                      "  classDef waiting fill:#fde2e2,stroke:#b91c1c\n"
+                      "  classDef parked fill:#eeeeee,stroke:#bbbbbb,stroke-dasharray:4 3\n")
+        return 0
+
+    if mode == "--check":
+        return _check(g, ready, nready, unfinished, out)
+
+    for t in g.order:
+        bl = ",".join("%02d" % d for d in g.blk[t])
+        out.write("%s  %-9s %-6s %-12s %s\n" % (g.lab[t], g.stat[t], "READY" if ready[t] else "-",
+                                                 "after " + bl if bl else "", g.title[t]))
+    return 0
+
+
+def _check(g, ready, nready, unfinished, out):
+    errors = []
+    for t in g.order:
+        lab = g.lab[t]
+        if t in g.dup:
+            errors.append(lab + ": two tickets share this number")
+        if not g.hasstatus[t]:
+            errors.append(lab + ": no Status line in the first 20 lines")
+        elif g.stat[t] == "unknown":
+            errors.append(lab + ": unrecognised Status value")
+        if not g.hasdone[t]:
+            errors.append(lab + ": no ## Done when section")
+        if t in g.hastf and g.tf[t] not in ("yes", "no"):
+            errors.append(lab + ": Test first must be yes or no")
+        for d in g.blk[t]:
+            if d == t:
+                errors.append(lab + ": blocked by itself")
+            elif d not in g.seen:
+                errors.append("%s: blocked by %d, which does not exist" % (lab, d))
+
+    placed = set()
+    progress = True
+    left = len(g.order)
+    while progress and left > 0:
+        progress = False
+        for t in g.order:
+            if t in placed:
+                continue
+            if all(not (d in g.seen and d != t and d not in placed) for d in g.blk[t]):
+                placed.add(t)
+                progress = True
+                left -= 1
+    if left > 0:
+        errors.extend(g.lab[t] + ": part of a dependency cycle" for t in g.order if t not in placed)
+    if nready == 0 and unfinished > 0:
+        errors.append("no ticket is ready to start")
+
+    reach = set()
+    for _ in range(len(g.order)):
+        changed = False
+        for t in g.order:
+            for d in g.blk[t]:
+                if d not in g.seen:
+                    continue
+                if (t, d) not in reach:
+                    reach.add((t, d))
+                    changed = True
+                for x in g.order:
+                    if (d, x) in reach and (t, x) not in reach:
+                        reach.add((t, x))
+                        changed = True
+        if not changed:
+            break
+    for t in g.order:
+        for m in g.mentions.get(t, []):
+            if m == t or m not in g.seen or (t, m) in reach or (m, t) in reach:
+                continue
+            out.write("warning: %s: mentions ticket %s but is not ordered against it. add it to Blocked by, or reword\n"
+                      % (g.lab[t], g.lab[m]))
+    if errors:
+        for e in errors:
+            out.write(e + "\n")
+        return 1
+    out.write("OK: %d tickets, %d ready now\n" % (len(g.order), nready))
+    return 0
+
+
+class _Bytes:
+    """Writes text to a byte stream, keeping the bytes awk would have passed through untouched."""
+
+    def __init__(self, stream):
+        self.stream = stream
+
+    def write(self, text):
+        self.stream.write(text.encode("utf-8", "surrogateescape"))
+        self.stream.flush()
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    sys.stdout.flush()
+    return run(argv, _Bytes(sys.stdout.buffer), _Bytes(sys.stderr.buffer))

feature_flow/tickets.py

@@ -0,0 +1,168 @@
+"""Reading and changing ticket files."""
+
+import os
+import re
+from pathlib import Path
+
+DONE = ("resolved", "done", "closed")
+RESET = ("claimed", "in-progress")
+
+
+def name(path):
+    return Path(path).stem
+
+
+def number(path):
+    return name(path).split("-", 1)[0]
+
+
+def _lines(path):
+    return Path(path).read_text(encoding="utf-8").splitlines(True)
+
+
+def status(path):
+    """The first word of the Status line in the first 20 lines, lower case."""
+    for line in _lines(path)[:20]:
+        if line.startswith("Status:"):
+            value = line[len("Status:"):].strip().lower()
+            return value.split()[0] if value else ""
+    return ""
+
+
+def set_open(path):
+    lines = _lines(path)
+    for i, line in enumerate(lines[:20]):
+        if line.startswith("Status:"):
+            lines[i] = "Status: open\n"
+            break
+    Path(path).write_text("".join(lines), encoding="utf-8")
+
+
+def append_findings(path, round_no, source, findings):
+    text = "\n## Review findings (round %d, %s)\n\n%s\n" % (round_no, source, findings.rstrip("\n"))
+    with open(path, "a", encoding="utf-8") as handle:
+        handle.write(text)
+
+
+def commands_value(path, key):
+    """A command from commands.md, or "" when it is missing or a placeholder in angle brackets."""
+    path = Path(path)
+    if not path.is_file():
+        return ""
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if re.match(r"^%s:" % re.escape(key), line):
+            value = re.sub(r"^%s:[ \t]*" % re.escape(key), "", line).replace("`", "")
+            return "" if value.startswith("<") else value
+    return ""
+
+
+# The ticket graph, read the way the bash flow-status script's awk program reads it.
+
+STATUS_WORDS = {
+    "resolved": "resolved", "done": "resolved", "closed": "resolved",
+    "claimed": "claimed", "in-progress": "claimed",
+    "parked": "parked", "wontfix": "parked",
+    "needs-triage": "waiting", "needs-info": "waiting", "ready-for-human": "waiting", "waiting": "waiting",
+    "open": "open", "ready-for-agent": "open",
+}
+_FILE_RE = re.compile(r"^[0-9][0-9].*-.*\.md$")
+_MENTION_RE = re.compile(r"[Tt]ickets? +[0-9]+( *(,|and|&) *[0-9]+)*")
+_DIGITS_RE = re.compile(r"[0-9]+")
+
+
+def records(path):
+    """The file's lines: split on \\n only, no final empty record, bytes kept. A trailing \\r is dropped,
+    so a ticket saved with Windows line endings reads the same as one saved with \\n."""
+    text = Path(path).read_bytes().decode("utf-8", "surrogateescape")
+    if text == "":
+        return []
+    lines = text.split("\n")
+    if text.endswith("\n"):
+        lines.pop()
+    return [line[:-1] if line.endswith("\r") else line for line in lines]
+
+
+def ticket_files(folder):
+    """What the glob [0-9][0-9]*-*.md finds in the folder, as folder/name, in name order."""
+    folder = str(folder)
+    try:
+        names = sorted(n for n in os.listdir(folder) if _FILE_RE.match(n))
+    except OSError:
+        return []
+    return ["%s/%s" % (folder, n) for n in names]
+
+
+def norm_status(value):
+    s = value.lower()
+    s = re.sub(r"^[ \t]+", "", s)
+    s = re.sub(r"[ \t(].*$", "", s, flags=re.S)
+    return STATUS_WORDS.get(s, "unknown")
+
+
+class Graph:
+    """Every ticket in a folder, keyed by number. The fields follow the awk arrays one to one."""
+
+    def __init__(self, paths):
+        self.seen = set()
+        self.dup = set()
+        self.path, self.lab, self.stat, self.title = {}, {}, {}, {}
+        self.hasstatus, self.hasdone, self.blk = {}, {}, {}
+        self.hasblk, self.hastype, self.hastf, self.hastitle = set(), set(), set(), set()
+        self.typ, self.tf = {}, {}
+        self.mentions = {}
+        for p in paths:
+            self._read(p)
+        self.order = sorted(self.seen)
+
+    def _read(self, filename):
+        lines = records(filename)
+        if not lines:
+            return  # awk never starts an empty file
+        base = filename.rsplit("/", 1)[-1]
+        label = re.match(r"^[0-9]+", base).group(0)
+        cur = int(label)
+        if cur in self.path:
+            self.dup.add(cur)
+        self.path[cur] = filename
+        self.lab[cur] = label
+        self.stat[cur] = "unknown"
+        self.hasstatus[cur] = False
+        self.hasdone[cur] = False
+        self.blk[cur] = []
+        self.title[cur] = base
+        self.seen.add(cur)
+        skipm = False
+        ment = self.mentions.setdefault(cur, [])
+        for fnr, line in enumerate(lines, 1):
+            head = fnr <= 20
+            if head and line.startswith("Status:") and not self.hasstatus[cur]:
+                self.stat[cur] = norm_status(line[len("Status:"):])
+                self.hasstatus[cur] = True
+            if head and line.startswith("Blocked by:") and cur not in self.hasblk:
+                self.hasblk.add(cur)
+                self.blk[cur].extend(int(m) for m in _DIGITS_RE.findall(line[len("Blocked by:"):]))
+            if head and line.startswith("Type:") and cur not in self.hastype:
+                self.hastype.add(cur)
+                self.typ[cur] = _first_word(line.lower(), "type:")
+            if head and line.startswith("Test first:") and cur not in self.hastf:
+                self.hastf.add(cur)
+                self.tf[cur] = _first_word(line.lower(), "test first:")
+            if line.startswith("# ") and cur not in self.hastitle:
+                self.hastitle.add(cur)
+                self.title[cur] = line[2:]
+            if line.startswith("## Done when"):
+                self.hasdone[cur] = True
+            if line.startswith("## "):
+                skipm = re.match(r"^(not in this ticket|answer|review findings)", line[3:].lower()) is not None
+                continue
+            if not skipm and fnr > 1:
+                for seg in _MENTION_RE.finditer(line):
+                    for num in _DIGITS_RE.findall(seg.group(0)):
+                        m = int(num)
+                        if m < 1000 and m not in ment:
+                            ment.append(m)
+
+
+def _first_word(lowered, key):
+    v = re.sub(r"^%s[ \t]*" % re.escape(key), "", lowered)
+    return re.sub(r"[ \t].*$", "", v, flags=re.S)