formwork-kit 0.1.0__py3-none-any.whl

formwork_cli/kit/check/checks/doc-links

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""Check: every link between documents points at something that exists.
+
+    doc-links <directory>
+
+CATCHES  A document that refers to a file which was renamed, moved or never
+         written. The reference still reads correctly, so nothing announces it,
+         and the reader follows it into nothing.
+
+         Both forms count: a markdown link, and a path in backticks. The
+         second is how a broken reference sat on the front page unnoticed.
+
+Exit status:
+    0   every link resolves
+    1   at least one does not, and it is named with its line
+    2   the check could not run
+
+Only links between files are checked. Web addresses are somebody else's
+problem, and an anchor without a path points inside the same document.
+
+Python 3, standard library only, no dependencies.
+"""
+import os
+import re
+import sys
+
+LINK = re.compile(r"\[[^\]]*\]\(([^)]+)\)")
+# A path inside backticks is a reference too. The front page pointed at a file
+# that did not exist for a day, and the markdown-only version never saw it.
+TICKED = re.compile(r"`([A-Za-z0-9_.\-]+(?:/[A-Za-z0-9_.\-]+)+/?)`")
+# Only paths into the kit's own tree, and they resolve from the project root
+# rather than from the file they appear in. Anything else in backticks is
+# somebody else's repository, a command, or an example, and guessing which
+# would produce noise rather than findings.
+OURS = ("formwork/",)
+# Third-party and generated trees. Without these, a single install of
+# somebody's dependencies produced dozens of findings about other people's
+# READMEs, and the file count in the summary was meaningless.
+SKIP_DIRS = {".git", "node_modules", "__pycache__", ".venv", "venv", "env",
+             ".tox", ".nox", "build", "dist", "target", "vendor",
+             "site-packages", ".next", ".nuxt", "coverage", ".mypy_cache",
+             ".pytest_cache", ".ruff_cache", ".gradle", "Pods"}
+
+# Paths the runner has told this check to stay out of. Part of the check
+# contract: the runner decides, the check obeys.
+EXCLUDED = [os.path.abspath(p) for p in
+            os.environ.get("FORMWORK_EXCLUDE", "").split(os.pathsep) if p]
+# .txt was included and produced findings in data files that merely happened
+# to contain bracket-parenthesis text. Markdown and reStructuredText only.
+TEXT_EXT = {".md", ".rst"}
+
+
+def links_in(text):
+    # A fenced code block holds examples. Showing a link in one is legitimate
+    # work, and failing the gate for it is a false positive in a kit that is
+    # mostly documentation.
+    fenced = False
+    for line_no, line in enumerate(text.split("\n"), 1):
+        if line.lstrip().startswith("```"):
+            fenced = not fenced
+            continue
+        if fenced:
+            continue
+        for m in TICKED.finditer(line):
+            target = m.group(1).strip().rstrip("/")
+            if target.startswith(OURS):
+                yield line_no, target, True      # resolves from the root
+        for m in LINK.finditer(line):
+            target = m.group(1).strip()
+            if not target:
+                continue
+            # Somebody else's server, or a spot inside this same document.
+            if target.startswith(("http://", "https://", "mailto:", "#")):
+                continue
+            # A trailing anchor names a heading; the file is what we resolve.
+            path = target.split("#", 1)[0]
+            if path:
+                yield line_no, path, False       # resolves from this file
+
+
+def main(argv):
+    if len(argv) < 2:
+        print("usage: doc-links <directory>", file=sys.stderr)
+        return 2
+    root = argv[1]
+    if not os.path.isdir(root):
+        print("ERROR: not a directory: %s" % root, file=sys.stderr)
+        return 2
+
+    broken = []
+    unreadable = []
+    scanned = 0
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+        here = os.path.abspath(dirpath)
+        if any(here == e or here.startswith(e + os.sep) for e in EXCLUDED):
+            dirnames[:] = []
+            continue
+        for fn in filenames:
+            if os.path.splitext(fn)[1].lower() not in TEXT_EXT:
+                continue
+            full = os.path.join(dirpath, fn)
+            try:
+                text = open(full, encoding="utf-8", errors="strict").read()
+            except (UnicodeDecodeError, OSError) as e:
+                # Silently skipping meant one stray byte hid a document from
+                # this check entirely, and the summary still said every link
+                # resolved. Say so instead.
+                unreadable.append("%s — cannot be read (%s)"
+                                  % (os.path.relpath(full, root), e))
+                continue
+            scanned += 1
+            for line_no, path, from_root in links_in(text):
+                base = root if from_root else dirpath
+                resolved = os.path.normpath(os.path.join(base, path))
+                if not os.path.exists(resolved):
+                    broken.append((os.path.relpath(full, root), line_no, path))
+
+    if broken or unreadable:
+        print("%d link(s) point at nothing, in %d file(s) scanned"
+              % (len(broken), scanned))
+        for rel, line_no, path in broken:
+            print("  %s:%d  ->  %s" % (rel, line_no, path))
+        for u in unreadable:
+            print("  %s" % u)
+        return 1
+
+    print("%d file(s) scanned, every link resolves" % scanned)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

formwork_cli/kit/check/checks/generated-current

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""Check: every generated file matches what its source produces.
+
+    generated-current <directory>
+
+CATCHES  A hand-edit to a generated file. It works, for exactly as long as
+         nobody regenerates — then it vanishes, and whoever made it does not
+         find out.
+
+         And a generated file left behind after its source changed, which is
+         the drift that copying was supposed to remove and quietly reintroduces
+         it.
+
+The real work is done by `formwork roles --check`, which regenerates in memory
+and compares bytes. This check exists so that comparison happens on every turn
+rather than when somebody remembers.
+
+Exit status:
+    0   everything current, or nothing is generated here
+    1   something is stale or hand-edited, and it is named
+    2   the check could not run
+"""
+import os
+import subprocess
+import sys
+
+TIMEOUT = 120
+
+
+def main(argv):
+    args = [a for a in argv[1:] if not a.startswith("--")]
+    if not args:
+        print("usage: generated-current <directory>", file=sys.stderr)
+        return 2
+    root = args[0]
+    if not os.path.isdir(root):
+        print("ERROR: not a directory: %s" % root, file=sys.stderr)
+        return 2
+
+    # Absolute, because the generator is run with the project as its working
+    # directory and a relative path would then resolve against the wrong root.
+    build = os.path.abspath(os.path.join(root, "formwork", "build"))
+    if not os.path.isfile(build):
+        print("no generator here, nothing generated")
+        return 0
+    if not os.access(build, os.X_OK):
+        print("ERROR: %s is not executable, so nothing can be compared"
+              % os.path.relpath(build, root), file=sys.stderr)
+        return 2
+
+    try:
+        # No --all: the generator checks the configured runtime plus any
+        # generated tree already present. Demanding --all made a fork that
+        # uses one runtime generate files for three, or live with a red gate.
+        p = subprocess.run([build, "--check"], capture_output=True,
+                           text=True, cwd=root, timeout=TIMEOUT)
+    except subprocess.TimeoutExpired:
+        print("ERROR: the generator took longer than %ds" % TIMEOUT,
+              file=sys.stderr)
+        return 2
+    except OSError as e:
+        print("ERROR: could not run the generator: %s" % e, file=sys.stderr)
+        return 2
+
+    out = (p.stdout + p.stderr).strip()
+    if p.returncode == 2:
+        print("ERROR: the generator could not run:\n%s" % out, file=sys.stderr)
+        return 2
+    print(out)
+    return 1 if p.returncode else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

formwork_cli/kit/check/checks/guard-wired

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""Check: if a runtime is declared, its guard is actually wired up.
+
+    guard-wired <directory>
+
+CATCHES  A project that believes it has a boundary and does not. The rule is
+         written down, the adapter exists in the repository, and nothing
+         connects the two. Everything looks right and nothing refuses.
+
+A project that declares no runtime is not failed. It has made no claim.
+
+Exit status:
+    0   no runtime declared, or the declared runtime is wired
+    1   a runtime is declared and its wiring is missing
+    2   the check could not run
+"""
+import json
+import os
+import re
+import sys
+
+# Where each runtime keeps its hook configuration, relative to the project.
+WIRING = {
+    "claude-code": ".claude/settings.json",
+    "codex":       ".codex/hooks.json",
+    "cursor":      ".cursor/hooks.json",
+    "gemini-cli":  ".gemini/settings.json",
+}
+# All three guards, not one. A settings file with the other two deleted used
+# to report "declared and wired".
+MARKERS = ("formwork/guard/git-boundary",
+           "formwork/guard/protected-files",
+           "formwork/guard/quality-gate")
+MARKER = MARKERS[0]
+
+# Events that actually fire before a tool runs, or at the end of a turn.
+# Anything else is a place to park a hook so it never happens.
+LIVE_EVENTS = {"PreToolUse", "Stop", "SubagentStop", "preToolUse",
+               "beforeShellExecution", "BeforeTool"}
+
+# A matcher that can match a real tool name. "zzz-never-matches" cannot.
+MATCHES_A_TOOL = re.compile(
+    r"(?i)\b(Bash|Write|Edit|NotebookEdit|Task|WebFetch|Read|Glob|Grep|\*|\.\*)\b")
+
+
+def declared_runtime(root):
+    config = os.path.join(root, ".formwork.toml")
+    if not os.path.exists(config):
+        return None
+    try:
+        text = open(config, encoding="utf-8", errors="ignore").read()
+    except OSError:
+        return None
+    # Accept the key wherever it sits. The configuration grew a [bindings]
+    # section and three documents disagreed about where runtime lived; a
+    # reader that only understood one of them broke the other.
+    m = re.search(r'^\s*runtime\s*=\s*["\']([^"\']+)["\']', text, re.M)
+    return m.group(1) if m else None
+
+
+def main(argv):
+    if len(argv) < 2:
+        print("usage: guard-wired <directory>", file=sys.stderr)
+        return 2
+    root = argv[1]
+    if not os.path.isdir(root):
+        print("ERROR: not a directory: %s" % root, file=sys.stderr)
+        return 2
+
+    runtime = declared_runtime(root)
+    if runtime is None:
+        print("no runtime declared, nothing claimed")
+        return 0
+    if runtime not in WIRING:
+        print("runtime '%s' is not one this kit knows how to wire" % runtime)
+        print("  known: %s" % ", ".join(sorted(WIRING)))
+        return 1
+
+    path = os.path.join(root, WIRING[runtime])
+    if not os.path.exists(path):
+        print("runtime '%s' is declared, but %s does not exist"
+              % (runtime, WIRING[runtime]))
+        return 1
+    try:
+        text = open(path, encoding="utf-8", errors="ignore").read()
+    except OSError as e:
+        print("ERROR: cannot read %s: %s" % (path, e), file=sys.stderr)
+        return 2
+    # A bare substring test passed when a guard's path appeared anywhere at
+    # all — including inside a key called "_disabled_note", and including
+    # inside an echo. The path must START a command value.
+    # The value may contain escaped quotes: "\"$CLAUDE_PROJECT_DIR\"/formwork/..."
+    # A path inside a "command" string was not enough. Every guard was moved
+    # to an event that never fires, with a matcher that matches nothing, and
+    # this check still said wired. It now reads the shape, not just the text.
+    def wired_for(marker):
+        try:
+            data = json.loads(text)
+        except ValueError:
+            # Not JSON. Fall back to the text test, which is all the TOML
+            # runtimes can be given today.
+            return marker in text
+
+        hooks = data.get("hooks")
+        if not isinstance(hooks, dict):
+            return False
+        for event, entries in hooks.items():
+            if event not in LIVE_EVENTS:
+                continue
+            if not isinstance(entries, list):
+                continue
+            for entry in entries:
+                if not isinstance(entry, dict):
+                    continue
+                matcher = entry.get("matcher")
+                if matcher is not None and not MATCHES_A_TOOL.search(str(matcher)):
+                    continue
+                for h in entry.get("hooks") or []:
+                    if not isinstance(h, dict):
+                        continue
+                    cmd = str(h.get("command", ""))
+                    if marker in cmd and not cmd.strip().startswith("echo"):
+                        return True
+        return False
+
+    missing = [m for m in MARKERS if not wired_for(m)]
+    if missing:
+        print("runtime '%s' is declared and %s exists, but it does not "
+              "invoke:" % (runtime, WIRING[runtime]))
+        for m in missing:
+            print("  %s" % m)
+        return 1
+
+    print("runtime '%s' declared and wired in %s" % (runtime, WIRING[runtime]))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

formwork_cli/kit/check/checks/kit-integrity

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""Check: nothing that does the enforcing has been changed without saying so.
+
+    kit-integrity <directory>
+    kit-integrity --record <directory>    write down what is there now
+
+CATCHES  A guard, a check, the gate, or a piece of wiring, quietly altered.
+         Four characters turn the strongest rule in this kit off, and before
+         this check nothing anywhere noticed.
+
+         It catches the routes the guard cannot: an interpreter assembling a
+         path, a human editing in their own editor, a file replaced while the
+         hook was disabled.
+
+The fingerprints live OUTSIDE the repository, beside the word lists. A record
+kept next to the thing it describes protects nothing.
+
+Exit status:
+    0   every protected file matches its fingerprint
+    1   something changed, was added, or went missing
+    2   the check could not run — including no fingerprints recorded yet
+"""
+import hashlib
+import os
+import re
+import shutil
+import sys
+
+PROTECTED = (
+    "formwork/guard",
+    "formwork/check/run",
+    "formwork/check/checks",
+    "formwork/adapters",
+    ".formwork.toml",
+    ".claude/settings.json",
+)
+
+STATE = os.environ.get("FORMWORK_STATE_DIR") or os.environ.get(
+    "FORMWORK_DENYLIST_DIR", os.path.expanduser("~/.formwork"))
+
+
+def record_path(root):
+    """Where this project's fingerprints live.
+
+    One file per project, named after the project's own path.
+
+    It used to be a single file for the whole machine. Two projects on one
+    machine then shared one record, so the second one to be set up inherited
+    the first one's fingerprints and reported that its untouched guards had
+    been tampered with. Recording to fix it moved the accusation to the other
+    project. An audit hit this on its first run.
+    """
+    # realpath, not abspath. On macOS /tmp is a symlink to /private/tmp, so
+    # the same project reached two ways hashed to two different records and
+    # the second one reported "nothing recorded yet".
+    # An explicit file wins. Fixtures carry their own state directory and
+    # cannot know the name below, which depends on where they were copied to.
+    explicit = os.environ.get("FORMWORK_FINGERPRINTS")
+    if explicit:
+        return explicit
+    full = os.path.realpath(root)
+    digest = hashlib.sha256(full.encode("utf-8")).hexdigest()[:16]
+    name = re.sub(r"[^A-Za-z0-9_.-]", "-", os.path.basename(full.rstrip(os.sep)))
+    mine = os.path.join(STATE, "fingerprints", "%s-%s.txt" % (name, digest))
+
+    # One migration, once. An older version kept a single record for the whole
+    # machine. Reading it as a fallback brought the shared-record bug straight
+    # back, so instead it is moved here the first time this project is
+    # checked, and the flat file is left behind renamed so nothing is lost.
+    legacy = os.path.join(STATE, "fingerprints.txt")
+    if os.path.isfile(legacy) and not os.path.exists(mine):
+        try:
+            os.makedirs(os.path.dirname(mine), exist_ok=True)
+            shutil.copyfile(legacy, mine)
+            os.rename(legacy, legacy + ".migrated")
+            print("moved the old machine-wide record to %s" % mine,
+                  file=sys.stderr)
+            print("  It used to be shared by every project on this machine.",
+                  file=sys.stderr)
+        except OSError:
+            pass
+    return mine
+
+
+def digest(path):
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for block in iter(lambda: f.read(65536), b""):
+            h.update(block)
+    return h.hexdigest()
+
+
+def protected_files(root):
+    found = {}
+    for rel in PROTECTED:
+        full = os.path.join(root, rel)
+        if os.path.isfile(full):
+            found[rel] = digest(full)
+        elif os.path.isdir(full):
+            for dp, dn, fns in os.walk(full):
+                dn[:] = [d for d in dn if d not in ("__pycache__", "state")]
+                for fn in sorted(fns):
+                    if fn.endswith(".pyc"):
+                        continue
+                    p = os.path.join(dp, fn)
+                    try:
+                        found[os.path.relpath(p, root)] = digest(p)
+                    except OSError:
+                        # A dangling symlink used to become a traceback and
+                        # exit 1, which the contract reserves for findings.
+                        found[os.path.relpath(p, root)] = "UNREADABLE"
+    return found
+
+
+def load_record(root):
+    if not os.path.exists(record_path(root)):
+        return None
+    out = {}
+    for line in open(record_path(root), encoding="utf-8"):
+        line = line.split("#", 1)[0].strip()
+        if not line or " " not in line:
+            continue
+        h, rel = line.split(None, 1)
+        out[rel.strip()] = h
+    return out
+
+
+def main(argv):
+    record_mode = "--record" in argv
+    args = [a for a in argv[1:] if not a.startswith("--")]
+    if not args:
+        print("usage: kit-integrity [--record] <directory>", file=sys.stderr)
+        return 2
+    root = args[0]
+    if not os.path.isdir(root):
+        print("ERROR: not a directory: %s" % root, file=sys.stderr)
+        return 2
+
+    now = protected_files(root)
+
+    if record_mode:
+        try:
+            os.makedirs(os.path.dirname(record_path(root)), exist_ok=True)
+        except OSError as e:
+            print("ERROR: cannot write the record: %s" % e, file=sys.stderr)
+            print("       Check FORMWORK_STATE_DIR points at a directory you "
+                  "can write to.", file=sys.stderr)
+            return 2
+        with open(record_path(root), "w", encoding="utf-8") as f:
+            f.write("# Fingerprints of everything that enforces a rule.\n")
+            f.write("# Kept outside the repository on purpose: a record beside\n")
+            f.write("# the thing it describes protects nothing.\n")
+            f.write("# Re-record deliberately, after reviewing what changed.\n")
+            for rel in sorted(now):
+                f.write("%s  %s\n" % (now[rel], rel))
+        print("recorded %d file(s) to %s" % (len(now), record_path(root)))
+        return 0
+
+    if not now:
+        # Every other check in this kit treats "the watcher is not watching"
+        # as status 2. This one used to call it a pass.
+        print("ERROR: none of the protected files are here", file=sys.stderr)
+        print("       Nothing is being watched, and that is not a pass.",
+              file=sys.stderr)
+        return 2
+
+    was = load_record(root)
+    if was is None:
+        print("ERROR: no fingerprints recorded at %s" % record_path(root), file=sys.stderr)
+        print("       Run: formwork/check/checks/kit-integrity --record .",
+              file=sys.stderr)
+        print("       Until then nothing is watching the guards, and that is "
+              "not a pass.", file=sys.stderr)
+        return 2
+
+    changed = sorted(r for r in now if r in was and now[r] != was[r])
+    added = sorted(r for r in now if r not in was)
+    missing = sorted(r for r in was if r not in now)
+
+    if changed or added or missing:
+        print("%d protected file(s) differ from the record"
+              % (len(changed) + len(added) + len(missing)))
+        for r in changed:
+            print("  changed  %s" % r)
+        for r in added:
+            print("  added    %s" % r)
+        for r in missing:
+            print("  missing  %s" % r)
+        print()
+        print("These files enforce every other rule. If you meant it, review "
+              "the change and re-record.")
+        return 1
+
+    print("%d protected file(s), all matching the record" % len(now))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

formwork_cli/kit/check/checks/predictions-first

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""Check: the challenger's predictions were written before it read anything.
+
+    predictions-first <directory>
+
+A round lives in docs/rounds/<name>/ and holds one file per participant. The
+challenger's file is predictions.md.
+
+CATCHES  A round whose predictions were written afterwards, or not at all.
+
+         An objection composed after reading somebody's work is shaped by that
+         work — you find whichever weakness the text put in front of you. A
+         prediction is not. One that proves accurate shows the weakness was
+         built into the approach rather than a slip on the day, which is a far
+         stronger result. Written afterwards, it is a description, and it
+         proves nothing while looking exactly the same.
+
+WHAT THE EVIDENCE IS WORTH, HONESTLY
+------------------------------------
+Two things are checked, and they are not equally strong.
+
+  * **The file exists.** Solid. A round with reports and no predictions did
+    not do this at all.
+  * **It is older than the reports.** Weak. Modification times are not carried
+    by version control and are reset by copying, so this can be wrong in both
+    directions.
+
+The second is reported as a warning rather than treated as proof. Nothing here
+can prove when somebody thought something; what it can do is make the absence
+impossible to miss.
+
+Exit status:
+    0   every round has predictions, written first as far as can be told
+    1   a round has reports and no predictions
+    2   the check could not run
+"""
+import os
+import sys
+
+ROUNDS = os.path.join("docs", "rounds")
+PREDICTIONS = "predictions.md"
+# brief.md is the human's input, written before anybody works. Counting it as
+# a participant report meant every correctly-run round warned about itself.
+SKIP = {"README.md", "round.md", "index.md", "brief.md"}
+
+
+def rounds(root):
+    base = os.path.join(root, ROUNDS)
+    if not os.path.isdir(base):
+        return None
+    out = []
+    for name in sorted(os.listdir(base)):
+        d = os.path.join(base, name)
+        if os.path.isdir(d):
+            out.append((name, d))
+    return out
+
+
+def main(argv):
+    args = [a for a in argv[1:] if not a.startswith("--")]
+    if not args:
+        print("usage: predictions-first <directory>", file=sys.stderr)
+        return 2
+    root = args[0]
+    if not os.path.isdir(root):
+        print("ERROR: not a directory: %s" % root, file=sys.stderr)
+        return 2
+
+    found = rounds(root)
+    if found is None:
+        print("no %s directory, no rounds to check" % ROUNDS)
+        return 0
+    if not found:
+        print("no rounds recorded yet")
+        return 0
+
+    problems = []
+    warnings = []
+    checked = 0
+
+    for name, d in found:
+        files = [f for f in sorted(os.listdir(d))
+                 if f.endswith(".md") and f not in SKIP]
+        reports = [f for f in files if f != PREDICTIONS]
+        if not reports:
+            continue                      # nothing was argued yet
+        checked += 1
+
+        predictions = os.path.join(d, PREDICTIONS)
+        if not os.path.exists(predictions):
+            problems.append("%s — has %d report(s) and no %s"
+                            % (name, len(reports), PREDICTIONS))
+            continue
+
+        try:
+            when = os.path.getmtime(predictions)
+            earliest = min(os.path.getmtime(os.path.join(d, r)) for r in reports)
+        except OSError:
+            continue
+        if when > earliest:
+            warnings.append("%s — %s is newer than the earliest report"
+                            % (name, PREDICTIONS))
+
+    if problems:
+        print("%d round(s) argued without predictions, of %d checked"
+              % (len(problems), checked))
+        for p in problems:
+            print("  %s" % p)
+        if warnings:
+            for w in warnings:
+                print("  warning: %s" % w)
+        return 1
+
+    if warnings:
+        print("%d round(s) checked. Nothing missing, but:" % checked)
+        for w in warnings:
+            print("  warning: %s" % w)
+        print("  Modification times are weak evidence — version control does "
+              "not carry them and copying resets them.")
+        return 0
+
+    print("%d round(s) checked, each with predictions on record" % checked)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))