@appchy/jarvis 0.1.37 → 0.1.39

package/harness/harness/frontmatter.py

@@ -0,0 +1,218 @@
+import re
+from pathlib import Path
+
+from .tree import TASK_FM_ORDER
+
+#: Keys rendered as `- item` block lists rather than inline `[a, b]`.
+#:
+#: It is not a formatting preference: the inline form splits on commas, and every
+#: key here holds free text a human wrote — a question, what was observed, a
+#: verify command's name and result. `--question "does it ship signed, or later?"`
+#: rendered inline would come back as two list entries, and the answer would be
+#: filed against half a question.
+BLOCK_LISTS = ("sessions", "plans", "asked", "verified", "observed")
+
+#: A field this parser reads: a name it models, and whatever follows the colon.
+_KEY = re.compile(r"^([A-Za-z0-9_]+):\s*(.*)$")
+
+#: Where one field ends and the next begins — ANY `key:` at column zero, including
+#: the ones `_KEY` declines. It is deliberately wider than what we read: a field we
+#: cannot parse still has to be bounded, or the lines under it get attributed to
+#: whatever came before. A leading `-` or `[` is excluded so a flush-left list item
+#: carrying a colon ("- 2026-01-01  does it ship signed: or later?") stays part of
+#: its list rather than starting a field of its own.
+_FIELD = re.compile(r"^[^\s#\-\[][^:]*:")
+
+
+def split_frontmatter(text: str):
+    """Return (frontmatter_text, body_text). frontmatter_text is None when the
+    file has no `---` fenced block at the top.
+
+    CRLF is matched as well as LF. A file written on Windows is ordinary YAML that
+    every other reader of this format handles; not matching it here meant Python saw
+    no frontmatter at all, and a rewrite then returned the file untouched — so a
+    `move` on such a task reported success and changed nothing."""
+    if not text.startswith("---"):
+        return None, text
+    m = re.match(r"^---\r?\n(.*?)\r?\n---\r?\n?", text, re.DOTALL)
+    if not m:
+        return None, text
+    return m.group(1), text[m.end():]
+def _eol(text: str) -> str:
+    """The line ending the file already uses.
+
+    Reading CRLF correctly and writing LF back is still every line rewritten for
+    whoever produced it, so what comes out matches what went in."""
+    return "\r\n" if text.startswith("---\r\n") else "\n"
+def _inline(raw: str) -> list:
+    """`[a, b]` as a list. Splits on every comma and ignores quoting — narrower than
+    YAML, and left that way on purpose: widening it changes how existing values read,
+    which is a separate question from whether a write destroys them."""
+    return [p.strip() for p in raw[1:-1].strip().split(",") if p.strip()]
+def _bullets(value) -> list:
+    """A block list's item lines. One writer of the `  - ` shape, so the two places
+    that emit one cannot drift apart on the indent."""
+    return [f"  - {item}" for item in as_list(value)]
+#: A field's value when its shape is not one this parser reads. It is a value rather
+#: than a missing key so the renderer still knows the field is THERE — which is what
+#: stops a mutation writing a second copy of a key the file already has.
+KEPT = object()
+
+
+def _name(line: str) -> str:
+    """A field's key as written, whether or not this parser can read its value."""
+    return line.split(":", 1)[0].strip()
+def _field(block: list):
+    """One field, as (name, value, source_lines).
+
+    `value` is `KEPT` when the field's shape is not one this parser reads — a dash in
+    the name, a nested map, an unterminated list. Those carry their source lines
+    instead, because the alternative to understanding a field is keeping it, never
+    dropping it."""
+    m = _KEY.match(block[0])
+    # Blank and comment lines are nobody's content. Counting them as a field's value
+    # made `owner: x` followed by a `# note` unreadable, which the plainer parser
+    # before this one got right.
+    rest = [line for line in block[1:]
+            if line.strip() and not line.lstrip().startswith("#")]
+    if not m:
+        return _name(block[0]), KEPT, block
+    key, raw = m.group(1), m.group(2).strip()
+
+    # The value as one line, wherever it started. A list prettier wrapped across
+    # lines is the same list — and it may open on the key's own line or on the next
+    # one, which is why the join happens before anything is decided rather than
+    # once per entry shape.
+    joined = " ".join(([raw] if raw else []) + [line.strip() for line in rest])
+
+    if joined.startswith("["):
+        return (key, _inline(joined), block) if joined.endswith("]") else (key, KEPT, block)
+    if raw:
+        # A scalar with lines under it is a shape we do not read — a folded block,
+        # most likely — so it is kept whole rather than half-understood.
+        return (key, raw, block) if not rest else (key, KEPT, block)
+    if not rest:
+        return key, "", block
+    if all(re.match(r"^\s*-\s+", line) for line in rest):
+        # Any indent, zero included. `sessions:` with its items at column zero is
+        # valid YAML that a person writes by hand, and demanding leading whitespace
+        # read it as empty — which then deleted it.
+        return key, [line.strip()[1:].strip() for line in rest], block
+    return key, KEPT, block
+def _fields(fm: str):
+    """Walk the frontmatter one field at a time. Everything between a `key:` at
+    column zero and the next one belongs to that field."""
+    lines = fm.splitlines()
+    i = 0
+    while i < len(lines):
+        if not _FIELD.match(lines[i]):
+            i += 1
+            continue
+        start = i
+        i += 1
+        while i < len(lines) and not _FIELD.match(lines[i]):
+            i += 1
+        yield _field(lines[start:i])
+def parse_frontmatter(text: str) -> dict:
+    """Parse the controlled subset of YAML used in frontmatter:
+    `key: scalar`, `key: []`, `key: [a, b]` (wrapped or not), and block lists of
+    `- item`. A field outside that subset is absent rather than empty — an empty
+    value would be indistinguishable from one somebody wrote."""
+    fm, _ = split_frontmatter(text)
+    if fm is None:
+        return {}
+    return {k: v for k, v, _ in _fields(fm) if v is not KEPT}
+def render_frontmatter(data: dict, order=TASK_FM_ORDER, kept=None, eol="\n") -> str:
+    """Serialize a frontmatter dict back to a `---` fenced block. Known keys are
+    emitted in `order`; the `BLOCK_LISTS` keys are rendered as block lists. `kept`
+    maps a field the parser could not read to its source lines, put back as they
+    were found."""
+    kept = kept or {}
+    keys = [k for k in order if k in data]
+    keys += [k for k in data if k not in order]
+    lines = []
+    for k in keys:
+        # A field nobody could read is not a field nobody has. Rendering this one
+        # from `data` would write a SECOND `verified:` into the file — the mutation
+        # appended to a list it was told was empty — and the first would then be
+        # invisible to every later read while its bytes sat there looking fine.
+        if k in kept:
+            continue
+        v = data[k]
+        if k in BLOCK_LISTS:
+            # A scalar here is a person writing `plans: plan.md`, which is the same
+            # thing as a one-item list and used to be dropped for not being one.
+            if as_list(v):
+                lines.append(f"{k}:")
+                lines += _bullets(v)
+            continue
+        if isinstance(v, list):
+            lines.append(f"{k}: [{', '.join(v)}]")
+        else:
+            lines.append(f"{k}: {v}")
+    for name, block in kept.items():
+        lines += block
+        # Whatever the mutation added lands under the lines it could not read, so a
+        # session or a verification is still recorded against a field this parser
+        # will go on declining to understand.
+        if name in BLOCK_LISTS:
+            lines += _bullets(data.get(name))
+    return "---" + eol + eol.join(lines) + eol + "---" + eol
+def rewrite_frontmatter(text: str, mutate, order=TASK_FM_ORDER) -> str:
+    """Apply `mutate(data)` to the parsed frontmatter and re-render the file."""
+    fm, body = split_frontmatter(text)
+    if fm is None:
+        return text
+    fields = list(_fields(fm))
+    data = {k: v for k, v, _ in fields if v is not KEPT}
+    kept = {k: block for k, v, block in fields if v is KEPT}
+    mutate(data)
+    return render_frontmatter(data, order, kept, _eol(text)) + body
+def read_item(md: Path) -> str:
+    """A work file's text, with the line endings it actually has on disk.
+
+    `Path.read_text()` translates CRLF to LF on the way in, and `write_text` does not
+    put it back — so a file written on Windows came back LF, was written LF, and
+    every line of it changed on a command asked to set one field. Nothing was lost
+    that a reader would notice, which is what made it worth closing: a diff touching
+    the whole file is one nobody reviews."""
+    with open(md, "r", encoding="utf-8", newline="") as f:
+        return f.read()
+def write_item(md: Path, text: str) -> None:
+    """The other half of `read_item`: write the endings the text already carries,
+    rather than the ones this platform prefers."""
+    with open(md, "w", encoding="utf-8", newline="") as f:
+        f.write(text)
+def rewrite_file(md: Path, mutate, order=TASK_FM_ORDER) -> None:
+    """`rewrite_frontmatter` over a file in place. The one door onto a board file's
+    frontmatter, so what it guarantees is guaranteed once rather than at thirteen
+    call sites that each read and wrote for themselves."""
+    write_item(md, rewrite_frontmatter(read_item(md), mutate, order))
+def unquote(value: str) -> str:
+    """A scalar with its surrounding quotes taken off.
+
+    `_inline` splits on commas and leaves quoting alone, deliberately — widening it
+    would change how every existing value reads. So a field authored in the quoted
+    JSON style (`paths: ["a", "b"]`, `retired: ["x=y"]`) arrives with the quote
+    characters part of the string, and every reader of one has to take them off. This
+    is that, once, beside the parser that hands them over.
+
+    Only a MATCHED pair: a lone quote is a character somebody typed, not quoting, and
+    stripping it would quietly rewrite the value.
+    """
+    text = str(value).strip()
+    for quote in ('"', "'"):
+        if len(text) >= 2 and text.startswith(quote) and text.endswith(quote):
+            return text[1:-1]
+    return text
+def as_list(value) -> list:
+    if isinstance(value, list):
+        return value
+    return [value] if value else []
+def title_of(md: Path) -> str:
+    """The title — the first `# ` heading in the body."""
+    body = split_frontmatter(md.read_text())[1]
+    for line in body.splitlines():
+        if line.startswith("# "):
+            return line[2:].strip()
+    return md.parent.name