@appchy/jarvis 0.1.114 → 0.1.115

package/harness/harness/links.py

@@ -191,3 +191,117 @@ def repairing(repo: Path, indent: str = "  "):
                 print(f"{indent}repaired {repaired} link(s) that pointed at what moved")
             for line in unresolved:
                 print(f"{indent}COULD NOT PLACE  {line}")
+
+
+#: The three files that ARE a board item, so a folder holding one is addressable by
+#: its name. Names are globally unique across tasks, epics and versions, which is what
+#: makes a name a usable second resolver when a path has stopped working.
+_ITEM_FILES = ("task.md", "epic.md", "version.md")
+
+
+def _index(base: Path) -> dict:
+    """Board item folders by name. A name with two homes is left out rather than guessed."""
+    homes: dict = {}
+    for doc in base.rglob("*.md"):
+        if SKIP & set(doc.parts) or doc.name not in _ITEM_FILES:
+            continue
+        homes.setdefault(doc.parent.name, set()).add(doc.parent.resolve())
+    return {name: next(iter(dirs)) for name, dirs in homes.items() if len(dirs) == 1}
+
+
+def _settle(doc: Path, href: str, index: dict):
+    """Where a broken link meant to point, or None when that is a guess.
+
+    Two resolvers, and both must land on exactly one file. **Depth first**: the tail
+    is right and the `../` count is wrong, which is what a file written at one tier
+    and moved to another leaves behind. **Then by name**: the item moved bucket or
+    epic, so no `../` count reaches it, but the folder it lives in is named in the
+    link and a board name has one home. Anything either resolver finds twice, or
+    neither finds at all, is reported for a person — a link repaired to the wrong
+    real file is worse than one that is visibly broken.
+    """
+    path = href.split("#")[0]
+    # Only the leading `./` and `../` hops come off. `lstrip("./")` would take the
+    # dot of `.github` with them and then resolve nothing, which is a link reported
+    # as unfixable because the checker damaged it on the way in.
+    tail = _HOPS.sub("", path)
+    hits = {c.resolve() for n in range(10)
+            if (c := doc.parent / ("../" * n) / tail).exists()}
+    if len(hits) == 1:
+        return next(iter(hits))
+
+    parts = [p for p in path.split("/") if p not in ("..", ".", "")]
+    if len(parts) >= 2 and (home := index.get(parts[-2])) is not None:
+        want = home / parts[-1]
+        if want.exists():
+            return want.resolve()
+    return None
+
+
+#: An inline code span. A doc that TEACHES the link syntax writes `](../…md)` inside
+#: backticks, and a checker that reads it as a link reports a file nobody ever meant
+#: to exist. Same shape of suppression the governance lints use, and the same reason:
+#: a blocking check's whole cost is its false positives.
+#:
+#: It crosses newlines because a quoted anchor wraps like any other prose, and the
+#: one live false positive this check ever produced was a span that opened on one
+#: line and closed on the next. Bounded rather than greedy: an unbalanced backtick
+#: somewhere in a long document must not swallow the links after it.
+CODE_SPAN = re.compile(r"`[^`]{0,500}`", re.S)
+
+#: Leading `./` and `../` hops, and nothing else.
+_HOPS = re.compile(r"^(?:\.{1,2}/)+")
+
+
+def dangling(base: Path) -> list:
+    """Every relative markdown link under `base` that resolves to nothing.
+
+    Returns `(doc, href, fix_or_None)` per broken link. This is the set `snapshot()`
+    records and `repair()` refuses on purpose — a link broken BEFORE a move has no
+    before-state to be repaired by identity, so it is settled from its own text or
+    not at all.
+    """
+    index = _index(base)
+    out = []
+    for doc in sorted(_docs(base)):
+        try:
+            text = doc.read_text(errors="ignore")
+        except OSError:
+            continue
+        text = CODE_SPAN.sub("", text)
+        for href in dict.fromkeys(m.group(1) for m in LINK.finditer(text)):
+            if "://" in href or href.startswith(("#", "mailto:", "/")):
+                continue
+            if (doc.parent / href.split("#")[0]).exists():
+                continue
+            out.append((doc, href, _settle(doc, href, index)))
+    return out
+
+
+def repair_dangling(base: Path, apply: bool = False) -> tuple:
+    """Point every settled broken link at what it names. Returns (fixed, stuck).
+
+    Rewrites on the link's own syntax, never on the bare path, so a path that also
+    appears in a sentence is left alone — the same anchoring `repair()` uses, for the
+    same reason.
+    """
+    fixed, stuck = 0, []
+    edits: dict = {}
+    for doc, href, target in dangling(base):
+        if target is None:
+            stuck.append((doc, href))
+            continue
+        _, _, anchor = href.partition("#")
+        new = os.path.relpath(target, doc.parent) + (f"#{anchor}" if anchor else "")
+        if new == href:
+            stuck.append((doc, href))
+            continue
+        edits.setdefault(doc, []).append((href, new))
+        fixed += 1
+    if apply:
+        for doc, pairs in edits.items():
+            text = doc.read_text(errors="ignore")
+            for href, new in pairs:
+                text = text.replace(f"]({href})", f"]({new})")
+            doc.write_text(text)
+    return fixed, stuck

package/harness/harness/report.py

@@ -165,6 +165,50 @@ def misalignments(root: Path) -> list:
             + _align_agents(root) + _align_retired(root) + _align_acceptance(root))
 
 
+#: A cut that has shipped, and the archive it ends up in. Their links are reported
+#: and never blocking: a plan naming source that has since been deleted, or a
+#: `handoff.md` that `archive` stripped, is an accurate record of a world that is
+#: gone. Demanding those resolve would make the gate unsatisfiable for a reason
+#: nobody could act on.
+_SHIPPED = ("versions/complete/", "archive/")
+
+
+def cmd_links(args) -> int:
+    """Board links that point at nothing. Exits 1 on a LIVE one, so a gate can block.
+
+    Blocking is safe here in a way it is not for the prose checks next door: a link
+    either resolves or it does not, there is no sentence to argue with, and the steady
+    state is zero because every folder move repairs its own links. A red therefore
+    means somebody hand-wrote a path, which is a ten-second fix — not a judgement call
+    a reader has to relitigate.
+
+    `--fix` repairs what is settled and leaves the rest. It is the only write, and it
+    is refused nothing: repairing a link that resolves to exactly one file cannot lose
+    anything, because the old path resolved to no file at all.
+    """
+    from . import links as links_mod
+    root = find_work_root()
+    if args.get("fix"):
+        fixed, _ = links_mod.repair_dangling(root, apply=True)
+        print(f"  repaired {fixed} link(s)")
+
+    broken = links_mod.dangling(root)
+    live = [(d, h) for d, h, _ in broken
+            if not any(m in str(d) for m in _SHIPPED)]
+    shipped = len(broken) - len(live)
+
+    for doc, href in live:
+        print(f"  ✗ {doc.relative_to(root.parent)} -> {href}")
+    if shipped:
+        print(f"  · {shipped} more in cuts that have shipped — reported, never blocking")
+    if not live:
+        print("  every link in a live brief or governance file resolves")
+        return 0
+    print(f"\n  {len(live)} broken link(s) in live files · exit 1   "
+          f"(`jarvis work links --fix` repairs what it can settle)")
+    return 1
+
+
 def cmd_align(args) -> int:
     """Report every misalignment class. REPORT-ONLY, exit 0 — by founder call.
 

package/harness/test_work.py

@@ -2076,6 +2076,103 @@ def test_a_finished_cut_leaves_the_board_without_pretending_it_shipped():
             os.environ.pop("WORK_DIR", None)
 
 
+def test_a_standing_broken_link_is_settled_by_depth_or_by_board_name():
+    # The set `repair()` refuses on purpose: broken BEFORE any move, so there is no
+    # before-state and identity cannot answer. Two resolvers instead — the tail is
+    # right and the `../` count is wrong, or the item moved bucket and the folder it
+    # lives in is named in the link.
+    from harness import links
+    with tempfile.TemporaryDirectory() as tmp:
+        base = Path(tmp) / "work"
+        (base / "product").mkdir(parents=True)
+        (base / "product" / "board.md").write_text("# board\n")
+        moved = base / "versions" / "a-cut" / "an-epic" / "complete" / "shipped-thing"
+        moved.mkdir(parents=True)
+        (moved / "task.md").write_text("# shipped thing\n")
+
+        doc = base / "versions" / "a-cut" / "an-epic" / "queue" / "live-one" / "task.md"
+        doc.parent.mkdir(parents=True)
+        doc.write_text(
+            # two hops short of product/
+            "governed by [board](../../../product/board.md), "
+            # names a bucket the item has left
+            "after [shipped](../shipped-thing/task.md).\n")
+
+        fixed, stuck = links.repair_dangling(base, apply=True)
+        assert (fixed, stuck) == (2, []), (fixed, stuck)
+        body = doc.read_text()
+        assert "](../../../../../product/board.md)" in body, body
+        assert "](../../complete/shipped-thing/task.md)" in body, body
+        assert links.dangling(base) == []
+
+
+def test_a_broken_link_two_resolvers_disagree_about_is_left_for_a_person():
+    # A link repaired to the wrong real file is worse than one that is visibly
+    # broken: nothing afterwards can tell it was ever wrong.
+    from harness import links
+    with tempfile.TemporaryDirectory() as tmp:
+        base = Path(tmp) / "work"
+        # The SAME tail exists at two heights on one walk up, so counting `../`
+        # cannot choose between them.
+        (base / "notes").mkdir(parents=True)
+        (base / "notes" / "shared.md").write_text("# the outer one\n")
+        (base / "one" / "notes").mkdir(parents=True)
+        (base / "one" / "notes" / "shared.md").write_text("# the inner one\n")
+        doc = base / "one" / "notes" / "deep" / "doc.md"
+        doc.parent.mkdir(parents=True)
+        doc.write_text("see [it](../../../../notes/shared.md)\n")
+
+        fixed, stuck = links.repair_dangling(base, apply=True)
+        assert fixed == 0, "a link two candidates answer must not be rewritten"
+        assert [h for _, h in stuck] == ["../../../../notes/shared.md"]
+        assert "](../../../../notes/shared.md)" in doc.read_text(), "it was rewritten"
+
+
+def test_a_link_inside_a_code_span_is_prose_and_never_a_finding():
+    # A doc teaching the syntax writes `](../…md)` in backticks. The live false
+    # positive this check ever produced was a quoted anchor whose span opened on one
+    # line and closed on the next, so the span has to cross newlines.
+    from harness import links
+    with tempfile.TemporaryDirectory() as tmp:
+        base = Path(tmp) / "work"
+        base.mkdir(parents=True)
+        (base / "doc.md").write_text(
+            "Resolving every `](../…md)` in the tree.\n\n"
+            "The anchor reads `[sessions](sessions.md)'s AC-03 and the test\n"
+            "lands later`, which is a quotation.\n\n"
+            "But [this one](../really-gone.md) is a link.\n")
+
+        broken = links.dangling(base)
+        assert [h for _, h, _ in broken] == ["../really-gone.md"], broken
+
+
+def test_the_links_gate_blocks_on_a_live_brief_and_never_on_a_shipped_cut():
+    # Blocking is only safe because the steady state is zero — every folder move
+    # repairs its own links — and because a shipped cut is allowed to name things
+    # that have since been deleted.
+    import contextlib, io
+    from harness import report
+    with tempfile.TemporaryDirectory() as tmp:
+        root = Path(tmp) / "work"
+        shipped = root / "versions" / "complete" / "01-done" / "an-epic"
+        shipped.mkdir(parents=True)
+        (shipped / "epic.md").write_text("gone: [src](../../../../src/deleted.ts)\n")
+        os.environ["WORK_DIR"] = str(root)
+        try:
+            with contextlib.redirect_stdout(io.StringIO()) as out:
+                assert report.cmd_links({}) == 0, "a shipped cut must not block"
+            assert "never blocking" in out.getvalue()
+
+            live = root / "versions" / "02-open" / "an-epic" / "queue" / "a-task"
+            live.mkdir(parents=True)
+            (live / "task.md").write_text("see [rule](../../../../nowhere.md)\n")
+            with contextlib.redirect_stdout(io.StringIO()) as out:
+                assert report.cmd_links({}) == 1, "a live broken link must block"
+            assert "nowhere.md" in out.getvalue()
+        finally:
+            os.environ.pop("WORK_DIR", None)
+
+
 def test_links_are_repaired_by_what_they_pointed_at_not_by_what_they_say():
     from harness import links
     with tempfile.TemporaryDirectory() as tmp:

package/harness/work.py

@@ -77,6 +77,9 @@ Subcommands:
     list --branch <ref>            the board as another branch has it (read-only)
     rules --task <name>            what constrains a task, derived
     align [--class <name>]         every misalignment class; REPORT-ONLY, exit 0
+    links [--fix]                  board links that point at nothing. Exits 1 when a
+                                   LIVE brief or governance file holds one, so a gate
+                                   can block; history is reported and never blocks
     wrap [--task <name>]           finish a session cleanly: what a machine knows
                                    about this run, then what to do. Writes NOTHING
     coverage [--feature <name>]    what a RUN proved vs what features promise
@@ -143,7 +146,7 @@ from harness import ids
 from harness.architecture import (cmd_domain_new, cmd_init, cmd_rules, cmd_system_new,
                                   cmd_where)
 from harness.coverage import cmd_coverage
-from harness.report import cmd_align, cmd_list, cmd_readme
+from harness.report import cmd_align, cmd_links, cmd_list, cmd_readme
 from harness.wrap import cmd_wrap
 from harness.config import (DEFAULTS, ConfigError, apply, cmd_applies, cmd_config,
                             cmd_context, cmd_method, cmd_remind, resolve)
@@ -167,7 +170,7 @@ SUBCOMMANDS = (
     "find", "list", "readme", "move", "plan", "session", "kickoff", "path", "code",
     "domain-new", "system-new", "where", "rules", "align", "wrap", "coverage",
     "migrate", "next", "status", "drop", "ask", "answer", "needs", "verify",
-    "observed", "log", "digest", "sync", "check",
+    "observed", "log", "digest", "sync", "check", "links",
 )
 
 
@@ -350,7 +353,7 @@ def _say(note: str) -> None:
 #: remembering to come back here.
 _READS = {"list", "find", "path", "code", "where", "rules", "status", "digest",
           "log", "needs", "align", "coverage", "readme", "config", "context",
-          "doctor", "kickoff", "remind", "applies", "wrap"}
+          "doctor", "kickoff", "remind", "applies", "wrap", "links"}
 
 
 def _reads_only(cmd: str, flags: dict) -> None:
@@ -514,6 +517,8 @@ def dispatch(cmd, pos, flags, cfg) -> int:
         return cmd_rules({**flags, "task": flags.get("task") or (pos[0] if pos else None)})
     if cmd == "align":
         return cmd_align(flags)
+    if cmd == "links":
+        return cmd_links(flags)
     if cmd == "wrap":
         return cmd_wrap(cfg, flags, _project_root(flags))
     if cmd == "coverage":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appchy/jarvis",
-  "version": "0.1.114",
+  "version": "0.1.115",
   "description": "Jarvis — local AI coding assistant CLI",
   "private": false,
   "type": "module",
@@ -57,16 +57,16 @@
     "typescript": "^5.7.0",
     "vitest": "^2.1.0",
     "@jarvis/agents": "1.0.0",
+    "@jarvis/anthropic": "1.0.0",
     "@jarvis/board": "0.1.0",
     "@jarvis/data": "0.1.0",
     "@jarvis/errors": "1.0.0",
     "@jarvis/logger": "1.0.0",
-    "@jarvis/rpc": "1.0.0",
-    "@jarvis/anthropic": "1.0.0",
     "@jarvis/types": "1.0.0",
+    "@jarvis/rpc": "1.0.0",
     "@jarvis/typescript-config": "1.0.0",
-    "@jarvis/vitest-config": "1.0.0",
-    "@jarvis/ui": "0.1.0"
+    "@jarvis/ui": "0.1.0",
+    "@jarvis/vitest-config": "1.0.0"
   },
   "scripts": {
     "dev": "tsx watch src/bin.ts start --foreground",