froid-loop 0.11.1__py3-none-any.whl

froid_loop/fences.py

@@ -0,0 +1,103 @@
+"""Whether a markdown offset sits inside a fenced code block.
+
+A leaf module with no froid-loop imports, deliberately: the two readers that need
+this — `devcontract` (is a `## Auto Run Result` heading real, or quoted?) and
+`deferredwork` (is a `gate:` line a declaration, or an example?) — sit on opposite
+sides of an import edge (`devcontract` imports `deferredwork`), so neither can
+host it for the other. `devcontract._section_headings` already argued the case in
+prose: "a second copy of `_fenced`'s open-marker walk is exactly the kind of
+near-duplicate that drifts." This module is that argument taken one step further
+once a second subsystem needed the same walk.
+"""
+
+from __future__ import annotations
+
+import re
+
+# A fence line: up to three spaces of indent, then a maximal run of >= 3 backticks
+# or tildes (its char AND length both matter per CommonMark), then the rest of the
+# line — an info string on an opener; on a close, only whitespace is allowed.
+FENCE_LINE_RE = re.compile(r"^ {0,3}(`{3,}|~{3,})([^\n]*)$", re.MULTILINE)
+
+
+def _delimits(marker: str, rest: str) -> bool:
+    """Whether a matched line delimits a fence at all, or is ordinary text.
+
+    CommonMark forbids a backtick anywhere in the info string of a BACKTICK fence,
+    and only there — the rule exists so that inline code is not read as opening a
+    block. Tilde fences carry no such restriction. Checked here rather than folded
+    into `FENCE_LINE_RE` so the pattern stays one readable alternation instead of
+    two near-identical arms with different info-string classes.
+
+    The miss runs the wrong way for `deferredwork`: a line of prose quoting a
+    fence opens a block CommonMark never opens, and a real `gate:` above the next
+    closing run is then read as an example and silently stops gating — the lost
+    gate the field exists to prevent, not the spurious refusal it tolerates.
+    """
+    return marker[0] == "~" or "`" not in rest
+
+
+def fenced(text: str, offset: int, *, unclosed_hides_rest: bool = True) -> bool:
+    """True when ``offset`` falls inside a ``` / ~~~ fenced code block.
+
+    A fence opens on a line of three-or-more backticks or tildes (indentable up
+    to three spaces; a tab would make an indented code block instead). Per
+    CommonMark it closes only on a later line using the SAME character, at least
+    as long as the opener, with no trailing non-whitespace — so a shorter run, a
+    different fence char, or an info-bearing line inside the block is content,
+    not a close. Tracking the open fence's char+length (not a bare line-parity
+    count) is what stops a nested-or-mismatched inner fence from flipping state
+    early and exposing a quoted heading as a real one.
+
+    ``unclosed_hides_rest`` decides the one case CommonMark leaves to the reader:
+    a fence that opens and never closes. The two callers need opposite answers,
+    and both are choosing the direction where being wrong is survivable, so this
+    is a parameter rather than a policy:
+
+    - ``True`` (``devcontract``): everything after the opener is content. Reading
+      a quoted ``## Auto Run Result`` as a real section is a *destructive* misread
+      — it strips or terminates a spec — so an ambiguous tail must stay inert.
+    - ``False`` (``deferredwork``): the opener is ordinary text. A `gate:` line
+      below a stray fence must keep gating, because a gate lost in silence is the
+      exact failure that field exists to end; a spurious refusal in an entry whose
+      markdown is already malformed is the cheaper wrong answer.
+    """
+    return any(
+        s <= offset < e for s, e in fenced_spans(text, unclosed_hides_rest=unclosed_hides_rest)
+    )
+
+
+def fenced_spans(text: str, *, unclosed_hides_rest: bool = True) -> list[tuple[int, int]]:
+    """Half-open ``[start, end)`` ranges of ``text`` that sit inside a fenced block.
+
+    The walk itself, which `fenced()` reduces to one offset and
+    `deferredwork.parse_legacy` blanks out wholesale before scanning line by line.
+    Keeping it here is the point of the module: a reader that needs the ranges and
+    a reader that needs one answer must not disagree about where a block ends.
+
+    The bounds follow the delimiters' roles rather than their extents. A span opens
+    one character past the opener's line start, so the opener itself reads as
+    outside the block — it is markup that a scanner may still want to see. It ends
+    one character past the closer's line start, which puts the closer *inside*: the
+    scanners this serves anchor at column 0, and a closing delimiter is the one
+    line of a block that can never be mistaken for the content it terminates.
+    """
+    spans: list[tuple[int, int]] = []
+    open_marker: str | None = None
+    start = 0
+    for m in FENCE_LINE_RE.finditer(text):
+        marker, rest = m.group(1), m.group(2)
+        if not _delimits(marker, rest):
+            continue  # inline code, not a fence line
+        if open_marker is None:
+            open_marker, start = marker, m.start() + 1  # opener — an info string is allowed
+        elif marker[0] == open_marker[0] and len(marker) >= len(open_marker) and not rest.strip():
+            spans.append((start, m.start() + 1))  # valid closing fence
+            open_marker = None
+        # else: a shorter / mismatched / info-bearing fence line — literal content
+    if open_marker is not None and unclosed_hides_rest:
+        # Past the last offset, not up to it: an unclosed fence has no end, and
+        # `fenced()` answered True for an offset at or beyond `len(text)` before
+        # these ranges existed. Slicing clamps, so a mask is unaffected either way.
+        spans.append((start, len(text) + 1))
+    return spans

froid_loop/froidconfig.py

@@ -0,0 +1,226 @@
+"""Resolve FROID artifact paths from _froid/bmm/config.yaml."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+from .platform_util import resolve_or_lexical
+
+
+class FroidConfigError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class ProjectPaths:
+    project: Path
+    implementation_artifacts: Path
+    planning_artifacts: Path
+    # the FROID output root (parent of the artifact dirs, holds project-context,
+    # test-artifacts, story-froid_loop, …). Protected wholesale on rollback so a
+    # failed attempt never deletes generated FROID output. Defaults to
+    # {project-root}/_froid-output when the config omits `output_folder`.
+    output_folder: Path = field(default=None)  # type: ignore[assignment]
+    # the git root code/git work happens against; defaults to `project`. Phase 1
+    # foundation for worktree isolation — see ProjectPaths.rebased and Workspace.
+    repo_root: Path = field(default=None)  # type: ignore[assignment]
+
+    def __post_init__(self) -> None:
+        if self.output_folder is None:
+            object.__setattr__(self, "output_folder", (self.project / "_froid-output").resolve())
+        if self.repo_root is None:
+            object.__setattr__(self, "repo_root", self.project)
+
+    @property
+    def sprint_status(self) -> Path:
+        return self.implementation_artifacts / "sprint-status.yaml"
+
+    @property
+    def deferred_work(self) -> Path:
+        return self.implementation_artifacts / "deferred-work.md"
+
+    def rebased(self, new_root: Path) -> ProjectPaths:
+        """Re-resolve the project and its artifact dirs onto `new_root` (a full
+        checkout, e.g. a git worktree). Artifact dirs configured outside the
+        project tree are shared, not per-checkout, so they don't move. The new
+        ProjectPaths is rooted at `new_root` for both `project` and `repo_root`."""
+        new_root = new_root.resolve()
+
+        def rebase(p: Path) -> Path:
+            try:
+                rel = p.relative_to(self.project)
+            except ValueError:
+                return p  # configured outside the project tree; doesn't move
+            return (new_root / rel).resolve()
+
+        return ProjectPaths(
+            project=new_root,
+            implementation_artifacts=rebase(self.implementation_artifacts),
+            planning_artifacts=rebase(self.planning_artifacts),
+            output_folder=rebase(self.output_folder),
+            repo_root=new_root,
+        )
+
+
+def worktree_isolation_conflict(paths: ProjectPaths, isolation: str) -> str | None:
+    """The refusal message for ``isolation = "worktree"`` under a `repo_root`
+    override, or None when the combination is supported (#414).
+
+    Worktree provisioning reads ``repo_root`` for every surface it seeds *off disk*
+    — the upstream skill trees, `_froid/` and the `_froid/custom/` overrides inside
+    it, and each `seed_files`/`seed_globs` entry — and bakes the absolute hook-relay
+    path from it into the worktree's hook config, while `init`, `validate` and the
+    run preflight write and probe those same surfaces under ``project``. (The relay
+    itself is pointed at, never copied. The `MODULE_SKILLS` this wheel bundles are
+    seeded from package data and are unaffected by either root; nothing is seeded
+    from ``project``, which `provision_worktree` is never even passed.)
+    `load_paths` *requires* `project/_froid/bmm/config.yaml`, so `_froid/` is under
+    `project` by definition and `repo_root/_froid/` generally does not exist. When
+    the two diverge the preflight therefore approves a surface the isolated run
+    never receives, and the seed-completeness gates go inert rather than fire: an
+    isolated session dispatches into a worktree with no dev primitive and no
+    renderer, and stops with no result and nothing journaled naming the cause.
+
+    **This function exists to be deleted.** The real fix is #443 — plumb ``project``
+    through provisioning for the non-git reads — and landing it removes this
+    function, all five of its call sites, the `policy.isolation-repo-root` id and
+    both doc sentences. It is a refusal rather than the fix because "which root
+    wins" is a separate decision per seeded surface (the relay only exists under
+    `project`; operator-configured `seed_files` may legitimately name a path outside
+    it), and `ProjectPaths.rebased` encodes `project == repo_root` besides. So the
+    message names only remediations that exist today. Both are named because either
+    alone is sufficient and which one is right is the operator's call: the override
+    buys a decoupled git root, the isolation mode buys per-unit worktrees, and until
+    #443 lands the orchestrator cannot give both.
+
+    Sole producer of the text, shared by `cmd_validate`, the run/sweep preflight,
+    the dry-run honesty banner and the TUI's pre-launch guard, so the four cannot
+    drift. Compares resolved paths: `load_paths` resolves both sides, but a
+    hand-built :class:`ProjectPaths` (tests) need not have."""
+    if isolation != "worktree":
+        return None
+    # The default config — no `repo_root` key, so `__post_init__` makes the two the
+    # same object — is settled here, before anything asks the OS. That is not just an
+    # optimization: the two calls below are independent, so a *transient*
+    # canonicalization failure between them (the guard catches every OSError, not only
+    # a persistent WinError 64) could have one side degrade to lexical while the other
+    # succeeds and canonicalizes, making one path unequal to itself and refusing an
+    # ordinary isolated run with the #414 text. Comparing raw first means the common
+    # shape cannot reach that window at all.
+    if paths.repo_root == paths.project:
+        return None
+    # Degrades rather than raises (#552): this gate runs in `cmd_validate` *before*
+    # the platform preflight, so a raise here is the #332 finding going unreachable
+    # again for anyone on `isolation = "worktree"`. A ProjectPaths built by
+    # `load_paths` arrives with both sides canonical (it raises otherwise), so the
+    # degrade below covers only hand-built instances and a share flapping between
+    # the load and this gate. Both sides take the same treatment, so a host that
+    # cannot canonicalize compares lexical to lexical; the cost, stated rather than
+    # hidden: two spellings that only canonicalization folds together (`p/../p` vs
+    # `p`) would be refused with a wrong message, where the alternative is no
+    # message and no command at all.
+    if resolve_or_lexical(paths.repo_root) == resolve_or_lexical(paths.project):
+        return None
+    return (
+        'isolation = "worktree" is not supported when repo_root differs from the project '
+        f"directory: worktree provisioning seeds from repo_root ({paths.repo_root}) while "
+        f"init, validate and the run preflight read the project ({paths.project}), so an "
+        "isolated session would get none of the skills the preflight just approved. "
+        "Remove the `repo_root` key from _froid/bmm/config.yaml, or set "
+        '`isolation = "none"` under [scm] in .froid-loop/policy.toml.'
+    )
+
+
+def _canonical(expanded: Path, label: str) -> Path:
+    """Canonicalize-or-raise, the shared boundary for every ProjectPaths member.
+    `label` names what refused in the operator's terms — a configured string is
+    reported with its raw spelling, the default output folder as the default —
+    so the message never calls a path "configured" that nobody configured."""
+    try:
+        return expanded.resolve()
+    except (OSError, RuntimeError) as e:
+        raise FroidConfigError(
+            f"cannot canonicalize the {label} ({expanded}): {e} — "
+            "whether it lies inside or outside the project tree cannot be determined, "
+            "so no run can safely proceed. Run `froid-loop validate` for what this "
+            "host is doing."
+        ) from e
+
+
+def _resolve(raw: str, project: Path) -> Path:
+    """Expand `{project-root}` and canonicalize, or raise typed. A config string can
+    name a UNC share of its own, independent of `--project`, so it refuses on the same
+    terms as the root in `load_paths` (#552). Degrading to the lexical spelling was
+    tried and retired: a spelling the OS cannot canonicalize has an *unknowable*
+    location — it can sit lexically inside the project while an in-tree symlink or
+    junction carries it to a dead share outside — so any in-tree/external answer
+    `rebased`'s `relative_to` reads off the spelling is a guess, and a wrong guess
+    sends a worktree-isolated run's artifact writes into a worktree-local directory
+    instead of the configured destination. No member enters a snapshot unresolved."""
+    expanded = Path(raw.replace("{project-root}", str(project)))
+    return _canonical(expanded, f"configured path {raw!r}")
+
+
+def load_paths(project: Path) -> ProjectPaths:
+    # The root must canonicalize or there is no consistent ProjectPaths to hand back
+    # (#552). Every member is compared against `project` — `rebased` decides "is this
+    # artifact dir inside the tree" with `relative_to` — so a lexical root next to a
+    # canonically spelled member (a resolved child, or an absolute path written
+    # canonically in config.yaml) sits on the far side of a symlink from it, files an
+    # in-tree artifact dir as external, and a worktree-isolated run then writes into
+    # the original checkout. Degrading here reopened that split once per review round;
+    # a typed raise closes every route at once, and it costs the diagnostic commands
+    # nothing: every caller already catches FroidConfigError — `cmd_validate` records
+    # the failure and still reaches the platform preflight that names the host — and
+    # `diagnose` never loads paths at all. Only `cli._project` still degrades: it runs
+    # pre-dispatch, where there is no handler to catch anything.
+    try:
+        project = Path(project).resolve()
+    except (OSError, RuntimeError) as e:
+        raise FroidConfigError(
+            f"cannot canonicalize the project root {project}: {e} — artifact paths "
+            "are derived from the canonical root, so no run can safely proceed. "
+            "Run `froid-loop validate` for what this host is doing."
+        ) from e
+    config_path = project / "_froid" / "bmm" / "config.yaml"
+    if not config_path.is_file():
+        raise FroidConfigError(f"FROID config not found: {config_path} (is FROID installed here?)")
+    try:
+        # UnicodeDecodeError is a ValueError, not an OSError, so an undecodable file
+        # would otherwise escape every caller's `except FroidConfigError` and crash
+        # them. Same reasoning as `policy.load`.
+        raw = config_path.read_text(encoding="utf-8")
+    except UnicodeDecodeError as e:
+        raise FroidConfigError(f"{config_path} is not valid UTF-8: {e}") from e
+    try:
+        doc = yaml.safe_load(raw) or {}
+    except yaml.YAMLError as e:
+        raise FroidConfigError(f"invalid YAML in {config_path}: {e}") from e
+
+    impl = doc.get("implementation_artifacts")
+    plan = doc.get("planning_artifacts")
+    if not impl or not plan:
+        raise FroidConfigError(
+            f"{config_path} missing implementation_artifacts/planning_artifacts keys"
+        )
+    repo_root_raw = doc.get("repo_root")
+    repo_root = _resolve(str(repo_root_raw), project) if repo_root_raw else project
+    out_raw = doc.get("output_folder")
+    output_folder = (
+        _resolve(str(out_raw), project)
+        if out_raw
+        # the default branch is a bare join off the (canonical) root and takes the
+        # same canonicalize-or-raise treatment as a configured string: an in-tree
+        # junction under the default name misclassifies exactly like a configured one.
+        else _canonical(project / "_froid-output", "default output folder")
+    )
+    return ProjectPaths(
+        project=project,
+        implementation_artifacts=_resolve(str(impl), project),
+        planning_artifacts=_resolve(str(plan), project),
+        output_folder=output_folder,
+        repo_root=repo_root,
+    )