factorio-mod-workshop 0.1.0__py3-none-any.whl

fmw/threadstate.py

@@ -0,0 +1,150 @@
+"""Per-thread annotations: your judgement about a conversation.
+
+The third layer of the workspace, distinct from both neighbours:
+
+- `cache/` holds what the portal says. Disposable, refetchable, never edited.
+- `threads/<mod>.yaml` (this module) holds what *you* decided about the
+  conversation - whether it is dealt with, whether you owe a reply, what it
+  really is regardless of how the reporter tagged it.
+- `tracker/` holds what you are doing about the underlying problem.
+
+Without this layer the only way to record any judgement about a thread is to
+create a ticket, which forces a ticket per thread. Most threads never deserve
+one: thanks, answered questions, duplicates.
+
+The thread -> ticket link is deliberately NOT stored here. It is derived from
+each ticket's `sources:`, so the two cannot drift apart.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import yaml
+
+from .config import Workspace, yaml_load
+
+# How you have dealt with the conversation itself.
+TRIAGE = ("pending", "handled", "ignored")
+
+# What the thread actually is, in your judgement. The portal's own tag is only
+# a hint: reporters mislabel constantly - questions filed as bugs by shy users,
+# expected behaviour filed as errors by careless ones - so nothing keys
+# automatic behaviour off it.
+CLASSES = ("error", "feature", "question", "wrong", "duplicate", "chatter")
+
+DEFAULT_TRIAGE = "pending"
+
+
+@dataclass
+class ThreadState:
+    triage: str = DEFAULT_TRIAGE
+    needs_response: bool = False
+    cls: str = ""
+    note: str = ""
+    duplicate_of: str = ""
+    # Ticket ids whose release you have already told this thread's reporter
+    # about. Prevents a shipped fix from nagging forever once announced.
+    announced: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        d: dict = {}
+        if self.triage != DEFAULT_TRIAGE:
+            d["triage"] = self.triage
+        if self.needs_response:
+            d["needs_response"] = True
+        if self.cls:
+            d["class"] = self.cls
+        if self.note:
+            d["note"] = self.note
+        if self.duplicate_of:
+            d["duplicate_of"] = self.duplicate_of
+        if self.announced:
+            d["announced"] = sorted(self.announced)
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict | None) -> "ThreadState":
+        d = d or {}
+        return cls(
+            triage=d.get("triage", DEFAULT_TRIAGE),
+            needs_response=bool(d.get("needs_response", False)),
+            cls=d.get("class", "") or "",
+            note=d.get("note", "") or "",
+            duplicate_of=d.get("duplicate_of", "") or "",
+            announced=list(d.get("announced") or []),
+        )
+
+    @property
+    def is_open(self) -> bool:
+        return self.triage == "pending" or self.needs_response
+
+
+def pending_announcements(state: "ThreadState", tickets) -> list[str]:
+    """Released tickets citing this thread that the reporter has not been told about.
+
+    Derived rather than stored: a fix reaching `released` is what creates the
+    obligation, and deriving it means the obligation cannot be missed because
+    nobody remembered to set a flag. It is still cleared only explicitly, via
+    `fmw mark --responded`, which records the ticket ids in `announced`.
+    """
+    return [
+        t.id for t in tickets
+        if t.meta.get("status") == "released" and t.id not in state.announced
+    ]
+
+
+def reply_reason(state: "ThreadState", tickets) -> str:
+    """Why this thread owes a reply, or an empty string if it does not."""
+    if state.needs_response:
+        return "flagged"
+    pending = pending_announcements(state, tickets)
+    if pending:
+        return "released: " + ", ".join(pending)
+    return ""
+
+
+def _file(ws: Workspace, mod: str):
+    return ws.threads_dir / f"{mod}.yaml"
+
+
+def load(ws: Workspace, mod: str) -> dict[str, ThreadState]:
+    path = _file(ws, mod)
+    if not path.exists():
+        return {}
+    raw = yaml_load(path.read_text()) or {}
+    return {tid: ThreadState.from_dict(d) for tid, d in (raw.get("threads") or {}).items()}
+
+
+def save(ws: Workspace, mod: str, states: dict[str, ThreadState]) -> None:
+    payload = {tid: s.to_dict() for tid, s in sorted(states.items()) if s.to_dict()}
+    path = _file(ws, mod)
+    if not payload:
+        if path.exists():
+            path.unlink()
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    header = (
+        f"# Your judgement about {mod} discussion threads, keyed by thread id.\n"
+        "# Portable: no local paths, so it can be committed and shared.\n"
+        "# The thread -> ticket link is not here; it is derived from ticket sources.\n"
+    )
+    path.write_text(
+        header + yaml.safe_dump({"threads": payload}, sort_keys=False,
+                                allow_unicode=True, width=100)
+    )
+
+
+def get(ws: Workspace, mod: str, thread_id: str) -> ThreadState:
+    return load(ws, mod).get(thread_id, ThreadState())
+
+
+def update(ws: Workspace, mod: str, thread_id: str, **changes) -> ThreadState:
+    states = load(ws, mod)
+    state = states.get(thread_id, ThreadState())
+    for key, value in changes.items():
+        if value is not None:
+            setattr(state, key, value)
+    states[thread_id] = state
+    save(ws, mod, states)
+    return state

fmw/tracker.py

@@ -0,0 +1,223 @@
+"""Curated tracker items: bugs, feature ideas and development plans.
+
+One Markdown file per item, YAML frontmatter for structure and a free-form
+body for analysis. Plain files so both humans and agents can read, grep,
+diff and edit them without any tooling in the way.
+"""
+
+from __future__ import annotations
+
+import re
+import secrets
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+
+import yaml
+
+from .config import Workspace, yaml_load
+
+# Tickets describe code changes only. A thread that needs an answer rather than
+# a change is resolved at the thread level and never becomes a ticket; roadmap
+# notes live in the workspace's notes/ directory.
+KINDS = ("error", "feature")
+
+# Vocabulary from earlier versions, mapped on migration.
+LEGACY_KINDS = {"bug": "error", "compat": "feature", "port": "feature"}
+STATUSES = (
+    "new",
+    "needs-info",
+    "confirmed",
+    "in-progress",
+    "needs-testing",
+    "fixed",
+    "released",
+    "wontfix",
+    "duplicate",
+)
+
+FRONTMATTER_RE = re.compile(r"\A---\s*\n(.*?)\n---\s*\n?(.*)\Z", re.S)
+
+
+@dataclass
+class Item:
+    path: Path
+    meta: dict
+    body: str
+
+    @property
+    def id(self) -> str:
+        return self.meta.get("id") or self.path.stem
+
+    @property
+    def mods(self) -> list[str]:
+        """Every mod this ticket applies to; the first is the primary one.
+
+        Accepts the older singular `mod:` key so existing files keep working.
+        """
+        raw = self.meta.get("mods")
+        if isinstance(raw, str):
+            return [raw]
+        if raw:
+            return [str(m) for m in raw]
+        single = self.meta.get("mod")
+        return [single] if single else []
+
+    @property
+    def mod(self) -> str:
+        mods = self.mods
+        return mods[0] if mods else ""
+
+    @property
+    def sources(self) -> list[str]:
+        raw = self.meta.get("sources") or []
+        return [str(s) for s in raw]
+
+    def portal_threads(self) -> set[str]:
+        return {s.split(":", 1)[1] for s in self.sources if s.startswith("portal:")}
+
+    def render(self) -> str:
+        fm = yaml.safe_dump(self.meta, sort_keys=False, allow_unicode=True, width=100)
+        return f"---\n{fm}---\n\n{self.body.strip()}\n"
+
+    def save(self) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(self.render())
+
+
+def parse(path: Path) -> Item:
+    text = path.read_text()
+    m = FRONTMATTER_RE.match(text)
+    if not m:
+        return Item(path=path, meta={}, body=text)
+    meta = yaml_load(m.group(1)) or {}
+    return Item(path=path, meta=meta, body=m.group(2))
+
+
+def load_all(ws: Workspace, mod: str | None = None) -> list[Item]:
+    """All tickets, or those applying to one mod.
+
+    A ticket lives in its primary mod's directory but may list others in
+    `mods:`, so filtering by mod has to read every ticket rather than one
+    directory. That costs a few milliseconds at any realistic ticket count.
+    """
+    root = ws.tracker_dir
+    if not root.is_dir():
+        return []
+    items = [parse(p) for p in sorted(root.rglob("*.md")) if p.name != "README.md"]
+    if mod:
+        items = [i for i in items if mod in i.mods]
+    return items
+
+
+ID_RE = re.compile(r"^[0-9a-f]{6}$")
+
+
+def existing_ids(ws: Workspace) -> set[str]:
+    return {i.id for i in load_all(ws)}
+
+
+def new_id(taken: set[str]) -> str:
+    """A short, stable, meaningless identifier.
+
+    Meaningless on purpose: reporters title threads "game crashes" and similar,
+    so a title-derived id is neither unique nor informative, and renaming the
+    ticket would silently break every reference to it.
+    """
+    while True:
+        candidate = secrets.token_hex(3)
+        if candidate not in taken:
+            return candidate
+
+
+def slugify(text: str, maxlen: int = 48) -> str:
+    s = re.sub(r"[^a-zA-Z0-9]+", "-", text.lower()).strip("-")
+    if len(s) > maxlen:
+        s = s[:maxlen].rsplit("-", 1)[0]
+    return s or "item"
+
+
+def create(
+    ws: Workspace,
+    mods: list[str],
+    title: str,
+    kind: str = "error",
+    status: str = "new",
+    sources: list[str] | None = None,
+    body: str = "",
+    extra: dict | None = None,
+) -> Item:
+    ident = new_id(existing_ids(ws))
+    primary = mods[0]
+    # The id is what references use; the slug is decoration so `ls tracker/` is
+    # readable, and may be renamed freely without breaking anything.
+    path = ws.mod_tracker_dir(primary) / f"{ident}-{slugify(title, 40)}.md"
+    today = date.today().isoformat()
+    meta = {
+        "id": ident,
+        "mods": list(mods),
+        "kind": kind,
+        "status": status,
+        "title": title,
+        "created": today,
+        "updated": today,
+        "sources": sources or [],
+    }
+    if extra:
+        meta.update(extra)
+    item = Item(path=path, meta=meta, body=body or DEFAULT_BODY)
+    item.save()
+    return item
+
+
+DEFAULT_BODY = """## Summary
+
+_What the user reported / what the idea is._
+
+## Analysis
+
+_Root cause, affected code, Factorio API details._
+
+## Resolution
+
+_What was changed, in which files, in which version._
+
+## Test plan
+
+_Concrete steps to verify in game. Written for a single playthrough shared
+with other fixes, so keep it short and say what a pass looks like._
+"""
+
+
+def index_by_thread(items: list[Item]) -> dict[str, list[Item]]:
+    """Map portal thread id -> tracker items referencing it."""
+    idx: dict[str, list[Item]] = {}
+    for it in items:
+        for tid in it.portal_threads():
+            idx.setdefault(tid, []).append(it)
+    return idx
+
+
+def open_statuses() -> set[str]:
+    """Statuses that still need someone to do something."""
+    return {"new", "needs-info", "confirmed", "in-progress", "needs-testing"}
+
+
+TEST_HEADING = "## Test plan"
+
+
+def test_plan(item: "Item") -> str:
+    """The item's Test plan section, if it has one."""
+    lines = item.body.splitlines()
+    out: list[str] = []
+    collecting = False
+    for line in lines:
+        if line.strip().lower().startswith(TEST_HEADING.lower()):
+            collecting = True
+            continue
+        if collecting and line.startswith("## "):
+            break
+        if collecting:
+            out.append(line)
+    text = "\n".join(out).strip()
+    return "" if text.startswith("_") and text.endswith("_") else text