hstack 0.16.0 → 0.18.0

package/template/scripts/telemetry/parsers/commits.py

@@ -1,219 +0,0 @@
-"""Parse git log of the consuming repo for hstack-style auto-commits."""
-
-from __future__ import annotations
-
-import re
-import subprocess
-from datetime import datetime, timezone
-from pathlib import Path
-
-
-# Auto-commit subject regex confirmed against moso-app's real git log.
-# Examples (from exploration):
-#   change-spec(2026-05-knowledge-resolve-icon-map-duplication-cross-module): shipped
-#   tech-debt(TD-0102): resolved (resolved-by: 2026-05-knowledge-resolve-icon-map-duplication-cross-module)
-#   implement(2026-05-knowledge-kg-ui-bucket-and-entity-rendering) phase-7-fixture-cast-cleanup + plan completed
-#   adversarial-review(2026-05-knowledge-kg-ui-bucket-and-entity-rendering): findings-resolved + change-spec ready-to-ship
-#   verification(2026-05-knowledge-kg-ui-bucket-and-entity-rendering): passed
-ARTIFACT_TYPES = (
-    "change-spec", "tech-debt", "implement", "adversarial-review",
-    "verification", "test-plan", "plan", "security-review",
-    "ui-brief", "figma-handoff", "story", "data-review",
-    "module-spec", "adr",
-)
-
-COMMIT_SUBJECT = re.compile(
-    r"^(?P<atype>" + "|".join(ARTIFACT_TYPES) + r")"
-    r"\((?P<id>[^)]+)\)"
-    r"(?P<rest>.*)$"
-)
-
-# Implement commits use `(<id>) <phase-id>` instead of `(<id>): <status>`.
-IMPLEMENT_PHASE = re.compile(r"^\s*(?P<phase>phase-[a-z0-9-]+)")
-
-# Halt sentinel — emitted into commit body or kernel-defined convention line.
-HALT_SENTINEL = re.compile(r"HSTACK-HALT:\s*reason=(?P<reason>[a-z-]+)", re.IGNORECASE)
-
-
-def run_git(repo: Path, *args: str) -> str:
-    try:
-        result = subprocess.run(
-            ["git", "-C", str(repo), *args],
-            capture_output=True, text=True, check=False,
-        )
-    except FileNotFoundError:
-        return ""
-    return result.stdout
-
-
-def parse_commits(repo: Path, since_days: int | None = None) -> list[dict]:
-    """Return a list of commit dicts: subject parsed, files-touched, timestamp.
-
-    Implementation: two queries to git. The first pulls metadata with a record
-    separator so multi-line bodies survive. The second pulls per-commit file
-    lists keyed by SHA. Merging the two avoids the `--pretty=format` +
-    `--name-only` interaction that mangled multi-line bodies in v1.
-
-    `--no-walk=unsorted` is intentionally not used; we keep author-date sort.
-    Conductor checkpoint commits are filtered post-parse by subject prefix.
-    """
-    # --- pass 1: metadata ---
-    sep = "\x1f"
-    rec_sep = "\x1e"
-    args = [
-        "log", "--all",
-        f"--pretty=format:%H{sep}%cI{sep}%an{sep}%s{sep}%b{rec_sep}",
-    ]
-    if since_days is not None:
-        args.append(f"--since={since_days}.days.ago")
-    raw = run_git(repo, *args)
-    metadata: dict[str, dict] = {}
-    for record in raw.split(rec_sep):
-        record = record.strip("\n")
-        if not record:
-            continue
-        parts = record.split(sep, 4)
-        if len(parts) < 5:
-            continue
-        sha, iso_ts, author, subject, body = parts
-        # Skip Conductor auto-checkpoint commits; they spam the log and carry
-        # no hstack signal.
-        if subject.startswith("checkpoint:"):
-            continue
-        metadata[sha] = {
-            "sha": sha,
-            "timestamp": _parse_iso(iso_ts),
-            "author": author,
-            "subject": subject,
-            "body": body,
-        }
-
-    if not metadata:
-        return []
-
-    # --- pass 2: file lists for the SHAs we kept ---
-    # Use a separate query keyed by SHA to avoid the `--name-only` interaction.
-    files_by_sha = _files_by_sha(repo, list(metadata.keys()))
-
-    out: list[dict] = []
-    for sha, md in metadata.items():
-        subject = md["subject"]
-        body = md["body"]
-        m = COMMIT_SUBJECT.match(subject)
-        atype = m.group("atype") if m else None
-        artifact_id = m.group("id") if m else None
-        rest = m.group("rest") if m else ""
-        phase_id = None
-        action = None
-        if atype == "implement":
-            pm = IMPLEMENT_PHASE.search(rest)
-            if pm:
-                phase_id = pm.group("phase")
-        else:
-            action = rest.lstrip(":").strip() or None
-        halts = HALT_SENTINEL.findall(body)
-        out.append({
-            **md,
-            "artifact_type": atype,
-            "artifact_id": artifact_id,
-            "phase_id": phase_id,
-            "action": action,
-            "files": files_by_sha.get(sha, []),
-            "halt_reasons": halts,
-        })
-    return out
-
-
-def _files_by_sha(repo: Path, shas: list[str]) -> dict[str, list[str]]:
-    """Run `git log --name-only --pretty=format:%H` filtered to the SHAs we care
-    about; chunk the SHA list to avoid command-line length limits."""
-    out: dict[str, list[str]] = {}
-    if not shas:
-        return out
-    chunk_size = 200
-    for start in range(0, len(shas), chunk_size):
-        chunk = shas[start:start + chunk_size]
-        args = ["log", "--no-walk", "--name-only", "--pretty=format:\x1eCOMMIT\x1f%H", *chunk]
-        raw = run_git(repo, *args)
-        if not raw:
-            continue
-        current_sha: str | None = None
-        files: list[str] = []
-        for line in raw.split("\n"):
-            if line.startswith("\x1eCOMMIT\x1f"):
-                if current_sha:
-                    out[current_sha] = files
-                current_sha = line.split("\x1f", 1)[1].strip()
-                files = []
-            elif line.strip() and current_sha:
-                files.append(line.strip())
-        if current_sha:
-            out[current_sha] = files
-    return out
-
-
-def _parse_iso(s: str) -> datetime | None:
-    try:
-        return datetime.fromisoformat(s)
-    except ValueError:
-        try:
-            return datetime.fromisoformat(s.replace("Z", "+00:00"))
-        except ValueError:
-            return None
-
-
-def diff_line_count(repo: Path, sha: str) -> tuple[int, int]:
-    """Return (added, removed) line counts for a commit."""
-    raw = run_git(repo, "show", "--stat", "--format=", sha)
-    added = removed = 0
-    for line in raw.splitlines():
-        if not line.strip():
-            continue
-        # final summary line: " N files changed, M insertions(+), K deletions(-)"
-        m = re.search(r"(\d+) insertion", line)
-        if m:
-            added = int(m.group(1))
-        m = re.search(r"(\d+) deletion", line)
-        if m:
-            removed = int(m.group(1))
-    return added, removed
-
-
-def commits_by_change(commits: list[dict]) -> dict[str, list[dict]]:
-    """Group commits by change-id (artifact_id when artifact_type relates to a change)."""
-    out: dict[str, list[dict]] = {}
-    for c in commits:
-        aid = c.get("artifact_id")
-        atype = c.get("artifact_type")
-        if not aid or atype is None:
-            continue
-        if atype == "tech-debt":
-            # Tech-debt commits also reference a resolving change-spec in the body.
-            # Surface the TD itself; resolving-change correlation is downstream.
-            continue
-        out.setdefault(aid, []).append(c)
-    return out
-
-
-def commits_touching_test_files(commits: list[dict]) -> list[dict]:
-    """Filter commits that touch test files."""
-    test_re = re.compile(r"(\.test\.|\.spec\.|/__tests__/|/__snapshots__/|^e2e/|_test\.go$)")
-    out = []
-    for c in commits:
-        if any(test_re.search(f) for f in c.get("files", [])):
-            out.append(c)
-    return out
-
-
-def commits_with_test_immutability_authorization(commits: list[dict]) -> list[dict]:
-    """Commits whose body carries one of the canonical authorization phrases."""
-    auth_re = re.compile(
-        r"Ok to (change|delete) test\s+\S+"
-        r"|Ok to update snapshot\s+\S+"
-        r"|Ok to refresh fixture\s+\S+"
-    )
-    out = []
-    for c in commits:
-        if auth_re.search(c.get("body", "")):
-            out.append(c)
-    return out

package/template/scripts/telemetry/parsers/frontmatter.py

@@ -1,322 +0,0 @@
-"""Walk hstack artifacts and parse their YAML frontmatter."""
-
-from __future__ import annotations
-
-import os
-from pathlib import Path
-from typing import Iterator
-
-try:
-    import yaml
-except ImportError:
-    yaml = None
-
-
-FRONTMATTER_DELIM = "---"
-
-
-def _split_frontmatter(text: str) -> tuple[dict, str]:
-    """Return (frontmatter_dict, body_text). Empty dict if no frontmatter."""
-    if not text.startswith(FRONTMATTER_DELIM):
-        return {}, text
-    parts = text.split(FRONTMATTER_DELIM, 2)
-    if len(parts) < 3:
-        return {}, text
-    raw = parts[1]
-    body = parts[2].lstrip("\n")
-    if yaml is None:
-        return _parse_simple_yaml(raw), body
-    try:
-        loaded = yaml.safe_load(raw) or {}
-        if not isinstance(loaded, dict):
-            return {}, body
-        return loaded, body
-    except yaml.YAMLError:
-        return _parse_simple_yaml(raw), body
-
-
-def _coerce_scalar(value: str):
-    value = value.strip()
-    if not value:
-        return None
-    if value.startswith('"') and value.endswith('"'):
-        return value[1:-1]
-    if value.startswith("'") and value.endswith("'"):
-        return value[1:-1]
-    if value.startswith("[") and value.endswith("]"):
-        inner = value[1:-1].strip()
-        if not inner:
-            return []
-        return [_coerce_scalar(v) for v in _split_inline_list(inner)]
-    if value.startswith("{") and value.endswith("}"):
-        # inline dict — rare in hstack frontmatter; treat as string fallback
-        return value
-    lower = value.lower()
-    if lower in ("true", "false"):
-        return lower == "true"
-    if lower in ("null", "~"):
-        return None
-    try:
-        return int(value)
-    except ValueError:
-        pass
-    try:
-        return float(value)
-    except ValueError:
-        pass
-    return value
-
-
-def _split_inline_list(inner: str) -> list[str]:
-    """Split a comma-separated inline list, respecting nested brackets."""
-    out = []
-    depth = 0
-    current = []
-    for ch in inner:
-        if ch in "[{":
-            depth += 1
-            current.append(ch)
-        elif ch in "]}":
-            depth -= 1
-            current.append(ch)
-        elif ch == "," and depth == 0:
-            out.append("".join(current).strip())
-            current = []
-        else:
-            current.append(ch)
-    if current:
-        out.append("".join(current).strip())
-    return out
-
-
-def _indent_of(line: str) -> int:
-    n = 0
-    for ch in line:
-        if ch == " ":
-            n += 1
-        else:
-            break
-    return n
-
-
-def _parse_simple_yaml(raw: str) -> dict:
-    """Indent-aware fallback parser for the YAML subset hstack frontmatter uses:
-    top-level scalars, top-level inline arrays, nested dicts (one level),
-    and arrays of dicts (one level). Sufficient for every artifact template.
-    """
-    lines = [ln for ln in raw.splitlines() if ln.strip() and not ln.lstrip().startswith("#")]
-    out: dict = {}
-    i = 0
-    while i < len(lines):
-        line = lines[i]
-        if _indent_of(line) != 0 or ":" not in line:
-            i += 1
-            continue
-        key, _, value = line.partition(":")
-        key = key.strip()
-        value_inline = value.strip()
-        if value_inline:
-            out[key] = _coerce_scalar(value_inline)
-            i += 1
-            continue
-        # Multi-line value; look at next-line indent and shape
-        if i + 1 >= len(lines):
-            out[key] = None
-            break
-        nxt = lines[i + 1]
-        nxt_indent = _indent_of(nxt)
-        if nxt_indent == 0:
-            out[key] = None
-            i += 1
-            continue
-        if nxt.lstrip().startswith("- "):
-            # Array — items may be inline scalars or block dicts.
-            items, consumed = _parse_block_sequence(lines, i + 1, nxt_indent)
-            out[key] = items
-            i = i + 1 + consumed
-        else:
-            # Block mapping (nested dict)
-            sub, consumed = _parse_block_mapping(lines, i + 1, nxt_indent)
-            out[key] = sub
-            i = i + 1 + consumed
-    return out
-
-
-def _parse_block_mapping(lines: list[str], start: int, base_indent: int) -> tuple[dict, int]:
-    out: dict = {}
-    i = start
-    consumed = 0
-    while i < len(lines):
-        line = lines[i]
-        ind = _indent_of(line)
-        if ind < base_indent:
-            break
-        if ind > base_indent:
-            i += 1
-            consumed += 1
-            continue
-        stripped = line.strip()
-        if ":" not in stripped:
-            i += 1
-            consumed += 1
-            continue
-        key, _, value = stripped.partition(":")
-        key = key.strip()
-        value_inline = value.strip()
-        if value_inline:
-            out[key] = _coerce_scalar(value_inline)
-            i += 1
-            consumed += 1
-            continue
-        # Possible nested structure — limited support: keep as None for now
-        if i + 1 < len(lines) and _indent_of(lines[i + 1]) > base_indent:
-            sub, sub_consumed = _parse_block_mapping(lines, i + 1, _indent_of(lines[i + 1]))
-            out[key] = sub
-            i = i + 1 + sub_consumed
-            consumed += 1 + sub_consumed
-        else:
-            out[key] = None
-            i += 1
-            consumed += 1
-    return out, consumed
-
-
-def _parse_block_sequence(lines: list[str], start: int, base_indent: int) -> tuple[list, int]:
-    items: list = []
-    i = start
-    consumed = 0
-    while i < len(lines):
-        line = lines[i]
-        ind = _indent_of(line)
-        if ind < base_indent:
-            break
-        stripped = line.strip()
-        if not stripped.startswith("- "):
-            # Continuation of previous item that we already consumed
-            i += 1
-            consumed += 1
-            continue
-        rest = stripped[2:]
-        if ":" in rest:
-            # First key of an inline dict item; merge any indented continuation
-            key, _, value = rest.partition(":")
-            item: dict = {key.strip(): _coerce_scalar(value)}
-            i += 1
-            consumed += 1
-            # Continuation lines at indent > base_indent (e.g. base_indent + 4)
-            while i < len(lines):
-                cont = lines[i]
-                cont_ind = _indent_of(cont)
-                if cont_ind <= base_indent:
-                    break
-                cont_stripped = cont.strip()
-                if cont_stripped.startswith("- "):
-                    break
-                if ":" in cont_stripped:
-                    k, _, v = cont_stripped.partition(":")
-                    item[k.strip()] = _coerce_scalar(v)
-                i += 1
-                consumed += 1
-            items.append(item)
-        else:
-            items.append(_coerce_scalar(rest))
-            i += 1
-            consumed += 1
-    return items, consumed
-
-
-def _parse_simple_yaml_old(raw: str) -> dict:
-    """Deprecated — retained for the smoke-test fallback path. Not exported."""
-    out: dict = {}
-    for line in raw.splitlines():
-        line = line.split("#", 1)[0].rstrip()
-        if not line or ":" not in line or line.startswith((" ", "\t")):
-            continue
-        key, _, value = line.partition(":")
-        out[key.strip()] = _coerce_scalar(value)
-    return out
-
-
-def read_artifact(path: Path) -> tuple[dict, str] | None:
-    """Read one artifact file. Returns (frontmatter, body) or None on error."""
-    try:
-        text = path.read_text(encoding="utf-8", errors="replace")
-    except OSError:
-        return None
-    return _split_frontmatter(text)
-
-
-def walk_artifacts(hstack_root: Path, pattern: str) -> Iterator[tuple[Path, dict, str]]:
-    """Yield (path, frontmatter, body) for every file under hstack_root matching pattern.
-
-    pattern is a glob relative to hstack_root, e.g. 'specs/changes/*/spec.md'.
-    """
-    for p in sorted(hstack_root.glob(pattern)):
-        if not p.is_file():
-            continue
-        parsed = read_artifact(p)
-        if parsed is None:
-            continue
-        fm, body = parsed
-        yield p, fm, body
-
-
-def load_change_artifacts(hstack_root: Path) -> dict[str, dict]:
-    """For every change folder under hstack/specs/changes/, load every artifact's
-    frontmatter. Returns {change_id: {artifact_type: {path, fm, body}}}."""
-    out: dict[str, dict] = {}
-    changes_dir = hstack_root / "specs" / "changes"
-    if not changes_dir.is_dir():
-        return out
-    for change_dir in sorted(changes_dir.iterdir()):
-        if not change_dir.is_dir():
-            continue
-        change_id = change_dir.name
-        bucket: dict[str, dict] = {}
-        for f in sorted(change_dir.iterdir()):
-            if not f.is_file() or not f.name.endswith(".md"):
-                continue
-            parsed = read_artifact(f)
-            if parsed is None:
-                continue
-            fm, body = parsed
-            atype = fm.get("type") or f.stem
-            bucket[atype] = {"path": f, "fm": fm, "body": body}
-        if bucket:
-            out[change_id] = bucket
-    return out
-
-
-def load_tech_debt(hstack_root: Path) -> list[dict]:
-    """Load every tech-debt artifact's frontmatter + body."""
-    out = []
-    for path, fm, body in walk_artifacts(hstack_root, "tech-debt/*.md"):
-        out.append({"path": path, "fm": fm, "body": body})
-    return out
-
-
-def load_adrs(hstack_root: Path) -> list[dict]:
-    out = []
-    for path, fm, body in walk_artifacts(hstack_root, "adr/ADR-*.md"):
-        out.append({"path": path, "fm": fm, "body": body})
-    return out
-
-
-def load_module_specs(hstack_root: Path) -> list[dict]:
-    """Module specs live at hstack/specs/<module>/spec.md (excluding changes/)."""
-    out = []
-    specs_dir = hstack_root / "specs"
-    if not specs_dir.is_dir():
-        return out
-    for module_dir in sorted(specs_dir.iterdir()):
-        if not module_dir.is_dir() or module_dir.name == "changes":
-            continue
-        spec = module_dir / "spec.md"
-        if not spec.is_file():
-            continue
-        parsed = read_artifact(spec)
-        if parsed is None:
-            continue
-        fm, body = parsed
-        out.append({"path": spec, "fm": fm, "body": body, "module": module_dir.name})
-    return out

package/template/scripts/telemetry/parsers/sidecars.py

@@ -1,61 +0,0 @@
-"""Load the per-change telemetry sidecars written by the five emitting Skills.
-
-Sidecars live at `hstack/specs/changes/<change-id>/.telemetry/*.json` and are
-derivative, gitignored, and never authoritative (ADR-0001). This parser only
-reads them; a malformed or absent sidecar is skipped, never repaired.
-
-Schema versions (see `templates/telemetry-sidecar.md`):
-  1 — no phase window. Reads as *unmeasured*: `phase_usage` returns None.
-  2 — carries `session_id`, `phase_opened_at`, `phase_closed_at` (ADR-0009).
-"""
-
-from __future__ import annotations
-
-import json
-from pathlib import Path
-
-
-def load_sidecars(hstack_root: Path) -> list[dict]:
-    """Every sidecar under every change folder, sorted by change then filename.
-
-    Each entry: {path, change_id, file, skill, phase_id, schema_version, data}.
-    `skill` and `phase_id` fall back to the filename when the payload omits them
-    (`implement-<phase-id>.json`), so a hand-truncated sidecar still groups.
-    """
-    out: list[dict] = []
-    changes_dir = hstack_root / "specs" / "changes"
-    if not changes_dir.is_dir():
-        return out
-    for change_dir in sorted(changes_dir.iterdir()):
-        if not change_dir.is_dir():
-            continue
-        telemetry_dir = change_dir / ".telemetry"
-        if not telemetry_dir.is_dir():
-            continue
-        for f in sorted(telemetry_dir.glob("*.json")):
-            data = _read_json(f)
-            if data is None:
-                continue
-            stem = f.stem
-            skill = data.get("skill") or f"hstack-{stem.split('-')[0]}"
-            phase_id = data.get("phase_id")
-            if phase_id is None and stem.startswith("implement-"):
-                phase_id = stem[len("implement-"):]
-            out.append({
-                "path": f,
-                "file": f.name,
-                "change_id": data.get("change_id") or change_dir.name,
-                "skill": skill,
-                "phase_id": phase_id,
-                "schema_version": data.get("schema_version"),
-                "data": data,
-            })
-    return out
-
-
-def _read_json(path: Path) -> dict | None:
-    try:
-        loaded = json.loads(path.read_text(encoding="utf-8", errors="replace"))
-    except (OSError, json.JSONDecodeError):
-        return None
-    return loaded if isinstance(loaded, dict) else None