alissa-tools-github-genloop 0.1.0__py3-none-any.whl

alissa/tools/github/genloop/plan.py

@@ -0,0 +1,461 @@
+"""The plan directory as the SEAT sees it: frontmatter, never prose (D14).
+
+After a pass the seat reads the pushed branch's `plan.md` and `tasks/*.md`
+from the plans repository, parses their FRONTMATTER -- the structured fields
+the plan row and the trailers need (`id`, `title`, `anchor`, `program`,
+`sources`, each task's `id` and `commitClass`) -- and renders the PR body by
+COPYING `plan.md`'s header lines, *Why now* and *Summary*. It never judges
+the prose; the judgment was the session's, and the refutation is revloop's.
+
+The YAML subset parser below is copied from orcloop's `plans.py` (the plan
+close edge reads the same files with it): the dist carries no third-party
+runtime dependency, and the files are written to a schema that needs only
+`key: value` pairs, flow mappings and sequences, and block sequences of such
+values. `plan-lint` has already validated the files, so a shape this parser
+cannot read is a bypass, not a style.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Sequence
+
+# The marker the seat writes into every plan PR body, on a line of its own --
+# one of revloop's four plan signals (§6.1) and orcloop's plan-PR test.
+PLAN_MARKER = "<!-- alissa-genloop:plan v1 -->"
+PLAN_TRAILER = "Alissa-Plan"
+ANCHOR_TRAILER = "Plan-Anchor"
+
+# Design §7.1, in severity order; a task's `commitClass` draws on the last ten.
+COMMIT_CLASSES = (
+    "unanchored",
+    "schema-migration",
+    "auth-secrets",
+    "pricing-billing",
+    "customer-promise",
+    "product-surface",
+    "gate-verification",
+    "drift-fix",
+    "flaky-test",
+    "exhaust-followup",
+    "doc-correction",
+)
+
+PLAN_ID_RE = re.compile(r"^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9][a-z0-9-]{2,47}$")
+PLAN_BRANCH_RE = re.compile(r"^PLAN-\d{8}T\d{6}Z-[a-z0-9-]+$")
+SOURCE_KEY_RE = re.compile(r"^(gate|later|minor|esc|drift|stale):\S+$")
+_FRONTMATTER_RE = re.compile(r"^---\n([\s\S]*?)\n---\n?([\s\S]*)$")
+_TASK_FILE_RE = re.compile(r"^[a-z0-9][a-z0-9-]*\.md$")
+MAX_TASKS = 8
+PR_BODY_MAX_CHARS = 60000
+
+
+class PlanError(ValueError):
+    """The pushed plan cannot be read into a plan row; the seat holds it."""
+
+
+# --- the YAML subset (copied from orcloop's plans.py) ------------------------
+
+
+class FrontmatterError(ValueError):
+    """The frontmatter is not the YAML subset the plan files are written in."""
+
+
+# --- the YAML subset ----------------------------------------------------------
+#
+# The dist carries no third-party runtime dependency, and the plan files are
+# written to a schema (design §5.3) that needs only: `key: value` pairs; a
+# value that is a plain or quoted scalar, a flow mapping `{ a: b }` or a flow
+# sequence `[a, b]`; and a block sequence of such values under a key. Anything
+# else -- a block mapping inside a list, an anchor, a multi-line scalar -- is
+# refused (rule 2): the lint has already validated the files against the
+# schema, so a shape this parser cannot read is a bypass, not a style.
+
+_PLAIN_INT_RE = re.compile(r"^[-+]?[0-9]+$")
+_PLAIN_FLOAT_RE = re.compile(r"^[-+]?(?:[0-9]+\.[0-9]*|\.[0-9]+)(?:[eE][-+]?[0-9]+)?$")
+
+
+def _strip_comment(line: str) -> str:
+    """A line with its trailing ` # comment` removed, quotes respected."""
+    quote = ""
+    for index, char in enumerate(line):
+        if quote:
+            if char == quote:
+                quote = ""
+            elif char == "\\" and quote == '"':
+                continue
+        elif char in "\"'":
+            quote = char
+        elif char == "#" and (index == 0 or line[index - 1] in " \t"):
+            return line[:index].rstrip()
+    return line.rstrip()
+
+
+class _Flow:
+    """A tiny recursive-descent reader for one value (flow or scalar)."""
+
+    def __init__(self, text: str):
+        self.text = text
+        self.pos = 0
+
+    def _ws(self) -> None:
+        while self.pos < len(self.text) and self.text[self.pos] in " \t":
+            self.pos += 1
+
+    def value(self, stops: str = "") -> Any:
+        self._ws()
+        if self.pos >= len(self.text):
+            return None
+        char = self.text[self.pos]
+        if char == "{":
+            return self._mapping()
+        if char == "[":
+            return self._sequence()
+        if char == '"':
+            return self._double()
+        if char == "'":
+            return self._single()
+        return self._plain(stops)
+
+    def _mapping(self) -> dict:
+        self.pos += 1
+        out: dict = {}
+        while True:
+            self._ws()
+            if self.pos < len(self.text) and self.text[self.pos] == "}":
+                self.pos += 1
+                return out
+            key = self.value(stops=":,}")
+            self._ws()
+            if self.pos >= len(self.text) or self.text[self.pos] != ":":
+                raise FrontmatterError(f"expected `:` in a flow mapping: {self.text!r}")
+            self.pos += 1
+            if not isinstance(key, str) or key in out:
+                raise FrontmatterError(f"bad or repeated key {key!r} in {self.text!r}")
+            out[key] = self.value(stops=",}")
+            self._ws()
+            if self.pos < len(self.text) and self.text[self.pos] == ",":
+                self.pos += 1
+                continue
+            if self.pos < len(self.text) and self.text[self.pos] == "}":
+                self.pos += 1
+                return out
+            raise FrontmatterError(f"unterminated flow mapping: {self.text!r}")
+
+    def _sequence(self) -> list:
+        self.pos += 1
+        out: list = []
+        while True:
+            self._ws()
+            if self.pos < len(self.text) and self.text[self.pos] == "]":
+                self.pos += 1
+                return out
+            out.append(self.value(stops=",]"))
+            self._ws()
+            if self.pos < len(self.text) and self.text[self.pos] == ",":
+                self.pos += 1
+                continue
+            if self.pos < len(self.text) and self.text[self.pos] == "]":
+                self.pos += 1
+                return out
+            raise FrontmatterError(f"unterminated flow sequence: {self.text!r}")
+
+    def _double(self) -> str:
+        self.pos += 1
+        out: list[str] = []
+        escapes = {'"': '"', "\\": "\\", "n": "\n", "t": "\t", "/": "/"}
+        while self.pos < len(self.text):
+            char = self.text[self.pos]
+            if char == "\\":
+                nxt = self.text[self.pos + 1:self.pos + 2]
+                if nxt not in escapes:
+                    raise FrontmatterError(f"unsupported escape \\{nxt} in {self.text!r}")
+                out.append(escapes[nxt])
+                self.pos += 2
+                continue
+            if char == '"':
+                self.pos += 1
+                return "".join(out)
+            out.append(char)
+            self.pos += 1
+        raise FrontmatterError(f"unterminated string: {self.text!r}")
+
+    def _single(self) -> str:
+        self.pos += 1
+        out: list[str] = []
+        while self.pos < len(self.text):
+            char = self.text[self.pos]
+            if char == "'":
+                if self.text[self.pos + 1:self.pos + 2] == "'":
+                    out.append("'")
+                    self.pos += 2
+                    continue
+                self.pos += 1
+                return "".join(out)
+            out.append(char)
+            self.pos += 1
+        raise FrontmatterError(f"unterminated string: {self.text!r}")
+
+    def _plain(self, stops: str) -> Any:
+        start = self.pos
+        while self.pos < len(self.text):
+            char = self.text[self.pos]
+            if char in stops and (char != ":" or self.text[self.pos + 1:self.pos + 2] in ("", " ", "\t")):
+                break
+            self.pos += 1
+        token = self.text[start:self.pos].strip()
+        if token.startswith(("&", "*", "!", "|", ">", "%", "@", "`")):
+            raise FrontmatterError(f"unsupported YAML construct {token!r}")
+        if token in ("", "~", "null", "Null", "NULL"):
+            return None
+        if token in ("true", "True", "TRUE"):
+            return True
+        if token in ("false", "False", "FALSE"):
+            return False
+        if _PLAIN_INT_RE.match(token):
+            return int(token)
+        if _PLAIN_FLOAT_RE.match(token):
+            return float(token)
+        return token
+
+    def done(self) -> bool:
+        self._ws()
+        return self.pos >= len(self.text)
+
+
+def _one_value(text: str) -> Any:
+    reader = _Flow(text)
+    value = reader.value()
+    if not reader.done():
+        raise FrontmatterError(f"trailing text after a value: {text!r}")
+    return value
+
+
+def parse_frontmatter_yaml(text: str) -> dict:
+    """The frontmatter subset (see above) as a dict, key order kept. Raises
+    `FrontmatterError` on anything outside it."""
+    out: dict = {}
+    current_list: list | None = None
+    for raw in text.split("\n"):
+        line = _strip_comment(raw)
+        if not line.strip():
+            continue
+        if line[0] in " \t" or line.startswith("-"):
+            stripped = line.strip()
+            if current_list is None or not stripped.startswith("- ") and stripped != "-":
+                raise FrontmatterError(f"unexpected indented line {raw!r}")
+            item = stripped[1:].strip()
+            if re.match(r"^[^\s\"'{\[][^:]*:(\s|$)", item):
+                raise FrontmatterError(f"a block mapping inside a list is not supported: {raw!r}")
+            current_list.append(_one_value(item))
+            continue
+        key, sep, rest = line.partition(":")
+        key = key.strip()
+        if not sep or not key or key in out or not re.match(r"^[A-Za-z_][A-Za-z0-9_-]*$", key):
+            raise FrontmatterError(f"not a `key: value` line: {raw!r}")
+        if rest.strip():
+            out[key] = _one_value(rest.strip())
+            current_list = None
+        else:
+            current_list = []
+            out[key] = current_list
+    return out
+
+
+# --- the plan, as the seat reads it ------------------------------------------
+
+
+@dataclass(frozen=True)
+class PlanTask:
+    id: str
+    commit_class: str
+
+
+@dataclass(frozen=True)
+class Plan:
+    plan_id: str
+    title: str
+    anchor: dict
+    program: str
+    sources: tuple[dict, ...]
+    tasks: tuple[PlanTask, ...]
+    body: str = field(repr=False)
+    frontmatter: dict = field(repr=False, default_factory=dict)
+
+    @property
+    def plan_class(self) -> str:
+        """The most severe `commitClass` of the tasks (§7.1's order)."""
+        ranks = [COMMIT_CLASSES.index(t.commit_class) for t in self.tasks if t.commit_class in COMMIT_CLASSES]
+        return COMMIT_CLASSES[min(ranks)] if ranks else "unanchored"
+
+    @property
+    def source_keys(self) -> list[str]:
+        return [str(s["key"]) for s in self.sources]
+
+    @property
+    def anchor_ref(self) -> str:
+        """`<kind>:<ref>` for the `Plan-Anchor:` trailer and the rule pattern."""
+        return anchor_ref(self.anchor)
+
+    def loop_plan_record(self, *, repo: str, pr_number: int, status: str, at_ms: int | None = None) -> dict:
+        """The `POST /v1/loop/plans` body (Studio G3-2)."""
+        record: dict = {
+            "repo": repo,
+            "prNumber": int(pr_number),
+            "planId": self.plan_id,
+            "title": self.title[:300],
+            "anchor": dict(self.anchor),
+            "class": self.plan_class,
+            "status": status,
+            "sources": [{"key": str(s["key"]), "evidence": str(s.get("evidence") or "")[:2000]} for s in self.sources],
+            "tasks": [{"id": t.id} for t in self.tasks],
+        }
+        if at_ms is not None:
+            record["at"] = int(at_ms)
+        return record
+
+
+def anchor_ref(anchor: dict) -> str:
+    kind = str(anchor.get("kind") or "")
+    if kind == "milestone":
+        return f"milestone:{anchor.get('milestoneId')}"
+    if kind == "criterion":
+        return f"criterion:{anchor.get('milestoneId')}/{anchor.get('criterionId')}"
+    if kind == "objective":
+        return f"objective:{anchor.get('objectiveId')}"
+    if kind == "exhaust":
+        return f"exhaust:{anchor.get('class')}"
+    return f"{kind or 'unknown'}:"
+
+
+def anchor_rule_pattern(anchor: dict) -> str | None:
+    """The `proposalRules` pattern a rejection writes for the anchor (§4.4):
+    `milestone:<id>` or `objective:<id>`; an exhaust anchor's keys are its
+    sources, which get their own rows."""
+    kind = anchor.get("kind")
+    if kind in ("milestone", "criterion") and anchor.get("milestoneId"):
+        return f"milestone:{anchor['milestoneId']}"
+    if kind == "objective" and anchor.get("objectiveId"):
+        return f"objective:{anchor['objectiveId']}"
+    return None
+
+
+def split_frontmatter(path: str, text: str) -> tuple[dict, str]:
+    text = text.replace("\r\n", "\n").replace("\r", "\n")
+    match = _FRONTMATTER_RE.match(text)
+    if match is None:
+        raise PlanError(f"{path} has no YAML frontmatter")
+    try:
+        return parse_frontmatter_yaml(match.group(1)), match.group(2)
+    except FrontmatterError as exc:
+        raise PlanError(f"{path}: {exc}") from None
+
+
+def task_file_names(names: Sequence[str]) -> list[str]:
+    return sorted(name for name in names if _TASK_FILE_RE.match(name))
+
+
+def parse_plan(plan_md: str, task_files: dict[str, str], *, expect_id: str | None = None) -> Plan:
+    """The plan row's facts from `plan.md` and `{file name: text}` of the
+    task files. Raises `PlanError` naming the first thing it cannot read."""
+    front, body = split_frontmatter("plan.md", plan_md)
+    plan_id = front.get("id")
+    if not isinstance(plan_id, str) or not PLAN_ID_RE.match(plan_id):
+        raise PlanError(f"plan.md id {plan_id!r} is not <yyyy-mm-dd>-<slug>")
+    if expect_id is not None and plan_id != expect_id:
+        raise PlanError(f"plan.md id {plan_id!r} is not the recorded planId {expect_id!r}")
+    title = front.get("title")
+    if not isinstance(title, str) or not title.strip():
+        raise PlanError("plan.md has no title")
+    anchor = front.get("anchor")
+    if not isinstance(anchor, dict) or anchor.get("kind") not in ("milestone", "criterion", "objective", "exhaust"):
+        raise PlanError(f"plan.md anchor {anchor!r} is not one of milestone, criterion, objective, exhaust")
+    program = front.get("program")
+    if not isinstance(program, str) or not program:
+        raise PlanError("plan.md has no program")
+    sources: list[dict] = []
+    for entry in front.get("sources") or []:
+        if not isinstance(entry, dict) or not isinstance(entry.get("key"), str) \
+                or not SOURCE_KEY_RE.match(entry["key"]):
+            raise PlanError(f"plan.md source {entry!r} is not {{key, evidence}} with a source key")
+        sources.append(entry)
+    names = task_file_names(list(task_files))
+    if not 1 <= len(names) <= MAX_TASKS:
+        raise PlanError(f"the plan has {len(names)} task files (1–{MAX_TASKS})")
+    tasks: list[PlanTask] = []
+    for name in names:
+        task_front, _ = split_frontmatter(f"tasks/{name}", task_files[name])
+        task_id = task_front.get("id")
+        if not isinstance(task_id, str) or f"{task_id}.md" != name:
+            raise PlanError(f"tasks/{name}: id {task_id!r} does not match the file name")
+        klass = task_front.get("commitClass")
+        if klass not in COMMIT_CLASSES[1:]:
+            raise PlanError(f"tasks/{name}: commitClass {klass!r} is not one of §7.1's task classes")
+        tasks.append(PlanTask(id=task_id, commit_class=str(klass)))
+    return Plan(
+        plan_id=plan_id, title=title.strip(), anchor=anchor, program=program, sources=tuple(sources),
+        tasks=tuple(tasks), body=body, frontmatter=front,
+    )
+
+
+# --- the PR body ---------------------------------------------------------------
+
+
+def _section(body: str, heading: str) -> str:
+    """The text under `## <heading>` up to the next `## ` heading, or ""."""
+    lines = body.split("\n")
+    out: list[str] = []
+    inside = False
+    for line in lines:
+        if line.startswith("## "):
+            if inside:
+                break
+            inside = line[3:].strip() == heading
+            continue
+        if inside:
+            out.append(line)
+    return "\n".join(out).strip()
+
+
+def render_pr_title(plan: Plan) -> str:
+    return f"Plan: {plan.title}"[:256]
+
+
+def render_pr_body(plan: Plan, *, branch: str, plans_dir: str, budget_note: str = "") -> str:
+    """The plan PR's body: the header lines, *Why now* and *Summary* COPIED
+    from `plan.md`, the marker on a line of its own, and the two trailers as
+    the body's last lines. The files are the truth; this is a rendering."""
+    budget = plan.frontmatter.get("budget") if isinstance(plan.frontmatter.get("budget"), dict) else {}
+    header = [
+        f"# Plan: {plan.title}",
+        PLAN_MARKER,
+        "",
+        f"- **Directory:** `{plans_dir}/` on `{branch}`",
+        f"- **Anchor:** `{plan.anchor_ref}` · **Program:** `{plan.program}`"
+        + (f" · **Milestone:** `{plan.frontmatter.get('milestone')}`" if plan.frontmatter.get("milestone") else ""),
+        f"- **Class:** `{plan.plan_class}` · **Tasks:** {len(plan.tasks)}",
+    ]
+    if budget:
+        header.append(f"- **Budget estimate:** ${budget.get('estimateUsd')} — {budget.get('basis')}")
+    if plan.source_keys:
+        header.append("- **Sources:** " + ", ".join(f"`{k}`" for k in plan.source_keys))
+    if budget_note:
+        header.append(f"- **Budget:** {budget_note}")
+    parts = ["\n".join(header)]
+    why_now = _section(plan.body, "Why now")
+    summary = _section(plan.body, "Summary")
+    if why_now:
+        parts.append("## Why now\n\n" + why_now)
+    if summary:
+        parts.append("## Summary\n\n" + summary)
+    parts.append(
+        "_Opened by the genloop seat. The plan directory is the truth; this body is a rendering. "
+        "Review it under the plan directive; amendments come from the next genloop pass._"
+    )
+    trailers = f"{PLAN_TRAILER}: {plan.plan_id}\n{ANCHOR_TRAILER}: {plan.anchor_ref}"
+    body = "\n\n".join(parts)
+    keep = PR_BODY_MAX_CHARS - len(trailers) - 40
+    if len(body) > keep:
+        body = body[:keep].rstrip() + "\n\n[… truncated — read plan.md]"
+    return body + "\n\n" + trailers + "\n"

alissa/tools/github/genloop/proc.py

@@ -0,0 +1,61 @@
+"""Subprocess helpers, copied from orcloop's `proc.py`.
+
+`github` shells out to `gh` (which keeps its own auth handling) and
+`alissa_cli` to `alissa`. The Alissa REST client does NOT go through here: it
+is in-process `urllib`, never a subprocess. Nothing in this module ever
+touches a token.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import subprocess
+from typing import Sequence
+
+log = logging.getLogger(__name__)
+
+
+class CommandError(RuntimeError):
+    def __init__(self, argv: Sequence[str], returncode: int, stderr: str):
+        self.argv = list(argv)
+        self.returncode = returncode
+        self.stderr = stderr
+        super().__init__(f"{argv[0]} exited {returncode}: {stderr.strip()[:400]}")
+
+
+def run(
+    argv: Sequence[str],
+    *,
+    timeout: int = 60,
+    check: bool = True,
+    cwd: "str | os.PathLike[str] | None" = None,
+) -> str:
+    """Run a command, return stdout. Never uses shell=True."""
+    log.debug("exec: %s", " ".join(argv))
+    try:
+        proc = subprocess.run(
+            list(argv),
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            cwd=str(cwd) if cwd is not None else None,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise CommandError(argv, -1, f"timed out after {timeout}s") from exc
+
+    if check and proc.returncode != 0:
+        raise CommandError(argv, proc.returncode, proc.stderr)
+    return proc.stdout
+
+
+def run_json(argv: Sequence[str], *, timeout: int = 60):
+    """Run a command whose stdout is JSON."""
+    out = run(argv, timeout=timeout).strip()
+    if not out:
+        return None
+    try:
+        return json.loads(out)
+    except json.JSONDecodeError as exc:
+        raise CommandError(argv, 0, f"expected JSON, got: {out[:300]}") from exc

alissa/tools/github/genloop/state.py

@@ -0,0 +1,113 @@
+"""The seat's own state: a small JSON file under the state dir.
+
+L8 (external truth): the spent-set, the plans and the rules live in Studio and
+GitHub and are re-derived every pass. What is left for this file is what only
+the seat knows -- the pass clock, the stamps it spawned, which records it has
+ingested, which PR a stamp opened, and the once-only marks on pages and
+writes. Every row carries the time it was written and ages out after
+`LEDGER_MAX_AGE_SECONDS`, like every other seat's ledger.
+
+Writes are atomic (temp file + rename), so a crash mid-write leaves the
+previous state whole.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import tempfile
+from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+STATE_FILENAME = "genloop-state.json"
+LEDGER_MAX_AGE_SECONDS = 30 * 86400
+
+
+def write_json_atomic(path: Path, payload: object) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=f".{path.name}.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(payload, handle, indent=2, sort_keys=True)
+            handle.write("\n")
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+class State:
+    """`meta` (latest-wins strings) and `ledger` (key -> written-at epoch)."""
+
+    def __init__(self, path: Path):
+        self.path = path
+        self.meta: dict[str, str] = {}
+        self.ledger: dict[str, int] = {}
+        self._load()
+
+    @classmethod
+    def in_dir(cls, state_dir: Path) -> "State":
+        return cls(state_dir / STATE_FILENAME)
+
+    def _load(self) -> None:
+        try:
+            raw = json.loads(self.path.read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            return
+        except (OSError, json.JSONDecodeError) as exc:
+            # A corrupt file must not wedge the seat; it re-derives what it can.
+            log.error("state: %s is unreadable (%s) — starting from an empty ledger", self.path, exc)
+            return
+        if isinstance(raw, dict):
+            meta = raw.get("meta")
+            ledger = raw.get("ledger")
+            if isinstance(meta, dict):
+                self.meta = {str(k): str(v) for k, v in meta.items()}
+            if isinstance(ledger, dict):
+                self.ledger = {str(k): int(v) for k, v in ledger.items() if isinstance(v, (int, float))}
+
+    def save(self) -> None:
+        write_json_atomic(self.path, {"meta": self.meta, "ledger": self.ledger})
+
+    # -- meta ----------------------------------------------------------------
+
+    def get_meta(self, key: str) -> str | None:
+        return self.meta.get(key)
+
+    def set_meta(self, key: str, value: str) -> None:
+        self.meta[key] = value
+        self.save()
+
+    def del_meta(self, key: str) -> None:
+        if self.meta.pop(key, None) is not None:
+            self.save()
+
+    # -- ledger --------------------------------------------------------------
+
+    def has(self, key: str) -> bool:
+        return key in self.ledger
+
+    def mark(self, key: str, *, at: int) -> None:
+        self.ledger[key] = int(at)
+        self.save()
+
+    def unmark(self, key: str) -> None:
+        if self.ledger.pop(key, None) is not None:
+            self.save()
+
+    def keys_with_prefix(self, prefix: str) -> list[str]:
+        return sorted(key for key in self.ledger if key.startswith(prefix))
+
+    def age_out(self, *, now: int) -> int:
+        """Drop ledger rows older than the max age; returns how many."""
+        stale = [key for key, at in self.ledger.items() if now - at > LEDGER_MAX_AGE_SECONDS]
+        for key in stale:
+            del self.ledger[key]
+        if stale:
+            self.save()
+        return len(stale)

alissa/tools/github/genloop/version

@@ -0,0 +1 @@
+0.1.0

alissa/tools/github/genloop/version.py

@@ -0,0 +1,46 @@
+import os
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Version:
+    name: str
+    value: str
+
+    def components(self, as_int: bool = False) -> list:
+        return [int(val) if as_int else val for val in self.value.split(".")]
+
+    @property
+    def major(self) -> int:
+        component, *_ = self.components(as_int=True)
+        return component
+
+    @property
+    def minor(self) -> int:
+        _, component, *_ = self.components(as_int=True)
+        return component
+
+    @property
+    def patch(self) -> int:
+        *_, component = self.components(as_int=True)
+        return component
+
+    @classmethod
+    def from_path(cls, dirpath: str, name: str):
+        for file in os.listdir(dirpath):
+            if file.lower().endswith("version"):
+                filepath = os.path.join(dirpath, file)
+                break
+        else:
+            raise ValueError("Version file not found for package name: " + name)
+
+        with open(filepath, "r") as version_file:
+            version_value = version_file.readline().strip()
+            return cls(name=name, value=version_value)
+
+
+try:
+    version = Version.from_path(name="alissa-tools-github-genloop", dirpath=os.path.dirname(__file__))
+except Exception:
+    print("Version file not found for package name: alissa-tools-github-genloop, using 0.0.0")
+    version = Version(name="alissa-tools-github-genloop", value="0.0.0")