pentimento 0.0.1__py3-none-any.whl

pentimento/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from pentimento.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

pentimento/backfill.py

@@ -0,0 +1,139 @@
+"""Derive and write frontmatter for plans that don't have it."""
+
+from __future__ import annotations
+
+from pentimento import frontmatter, lineage, status, times, vocabulary
+from pentimento import plan as plan_module
+
+_PROGRESS_RANK = {s: i for i, s in enumerate(vocabulary.PROGRESS_ORDER)}
+
+
+def _created_date(target) -> str:
+    return times.local_date(target.created_at) or target.started[:10]
+
+
+def _derive_project(target, sessions) -> str | None:
+    session = sessions.get(target.id)
+    if session and session.project:
+        return session.project
+    return target.fields.get("project")
+
+
+def _resolves_to_cycle(plan_id: str, parent_id: str, fields_by_id: dict[str, dict]) -> bool:
+    seen = {plan_id}
+    current = parent_id
+    while current is not None:
+        if current in seen:
+            return True
+        seen.add(current)
+        current = fields_by_id.get(current, {}).get("parent")
+    return False
+
+
+def derive_fields(
+    target,
+    candidates,
+    sessions,
+    *,
+    rederive: bool = False,
+    recreate: bool = False,
+    max_status: str | None = None,
+) -> dict[str, str]:
+    """Fields to backfill for `target`."""
+    fields = dict(target.fields)
+    fields.setdefault("intent", vocabulary.DEFAULT_INTENT)
+    fields.setdefault("created", _created_date(target))
+    if recreate:
+        fields["created"] = _created_date(target)
+
+    existing_status = fields.get("status")
+    derived_status = status.derive_status(target.body)
+    if max_status and _PROGRESS_RANK.get(derived_status, -1) > _PROGRESS_RANK[max_status]:
+        derived_status = max_status
+    if existing_status is None:
+        fields["status"] = derived_status
+    elif existing_status != vocabulary.SUPERSEDED:
+        if rederive:
+            fields["status"] = derived_status
+        else:
+            existing_rank = _PROGRESS_RANK.get(existing_status, -1)
+            derived_rank = _PROGRESS_RANK.get(derived_status, -1)
+            if derived_rank > existing_rank:
+                fields["status"] = derived_status
+
+    if rederive or "project" not in fields:
+        project = _derive_project(target, sessions)
+        if project:
+            fields["project"] = project
+
+    if rederive:
+        parent_id = lineage.derive_parent(
+            target, candidates, sessions, project=fields.get("project")
+        )
+        if parent_id:
+            fields["parent"] = parent_id
+        else:
+            fields.pop("parent", None)
+    elif "parent" not in fields:
+        parent_id = lineage.derive_parent(
+            target, candidates, sessions, project=fields.get("project")
+        )
+        if parent_id:
+            fields["parent"] = parent_id
+
+    return fields
+
+
+def run(
+    plans,
+    sessions=None,
+    *,
+    dry_run: bool = False,
+    rederive: bool = False,
+    recreate: bool = False,
+    max_status: str | None = None,
+    only=None,
+) -> list[str]:
+    """Backfill frontmatter across `plans`. Returns ids that were changed.
+
+    `only`, when given, restricts writes to those ids; derivation still spans
+    `plans` entire, because `lineage.derive_parent` resolves against the whole
+    corpus and `_resolves_to_cycle` needs every plan's new fields.
+    """
+    sessions = sessions or {}
+    new_fields_by_path = {
+        target.path: derive_fields(
+            target,
+            plans,
+            sessions,
+            rederive=rederive,
+            recreate=recreate,
+            max_status=max_status,
+        )
+        for target in plans
+    }
+    # Cycle traversal walks `parent` id references, so it needs an id-keyed view.
+    # A shared id makes the choice of which plan's fields represent that id
+    # arbitrary here, but that ambiguity is inherent to duplicate ids, not
+    # introduced by this map -- it does not affect which plan's fields get
+    # written, which is keyed by path above.
+    new_fields_by_id = {target.id: new_fields_by_path[target.path] for target in plans}
+
+    for target in plans:
+        new_fields = new_fields_by_path[target.path]
+        parent_id = new_fields.get("parent")
+        if parent_id and _resolves_to_cycle(target.id, parent_id, new_fields_by_id):
+            new_fields.pop("parent", None)
+
+    changed = []
+    for target in plans:
+        if only is not None and target.id not in only:
+            continue
+        new_fields = new_fields_by_path[target.path]
+        if frontmatter.serialize(new_fields, target.body, target.extras) == target.text:
+            continue
+        changed.append(target.id)
+        if not dry_run:
+            target.fields = new_fields
+            plan_module.save(target, keep_mtime=True)
+    return changed

pentimento/cache.py

@@ -0,0 +1,54 @@
+"""Memoize per-file derived data across `pentimento` invocations.
+
+A cache miss, a corrupt file, or an unwritable cache directory all degrade
+to a full parse rather than an error.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+VERSION = 1
+
+
+def cache_dir() -> Path:
+    base = os.environ.get("XDG_CACHE_HOME")
+    root = Path(base) if base else Path.home() / ".cache"
+    return root / "pentimento"
+
+
+def key(path: Path) -> str:
+    stat = path.stat()
+    return f"{path}:{stat.st_size}:{stat.st_mtime_ns}"
+
+
+def read(namespace: str) -> dict:
+    try:
+        data = json.loads((cache_dir() / f"{namespace}.json").read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+
+    if data.get("version") != VERSION:
+        return {}
+
+    entries = data.get("entries")
+    return entries if isinstance(entries, dict) else {}
+
+
+def write(namespace: str, entries: dict) -> None:
+    directory = cache_dir()
+    try:
+        directory.mkdir(parents=True, exist_ok=True)
+        fd, tmp_name = tempfile.mkstemp(dir=directory, prefix=f".{namespace}.", suffix=".json.tmp")
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                handle.write(json.dumps({"version": VERSION, "entries": entries}))
+            os.replace(tmp_name, directory / f"{namespace}.json")
+        except OSError:
+            os.unlink(tmp_name)
+            raise
+    except OSError:
+        pass

pentimento/check.py

@@ -0,0 +1,197 @@
+"""Validate the plan corpus for lineage and vocabulary defects."""
+
+from __future__ import annotations
+
+import dataclasses
+
+from pentimento import counts
+from pentimento import status as status_module
+from pentimento import tags as tags_module
+from pentimento import touches as touches_module
+from pentimento import vocabulary as vocabulary_module
+
+_HISTORY_ELIGIBLE_STATUSES = vocabulary_module.UNWORKED_STATUSES
+
+
+@dataclasses.dataclass
+class Finding:
+    plan_id: str
+    code: str
+    message: str
+
+
+def _dangling_parents(plans, by_id):
+    return [p for p in plans if p.parent and p.parent not in by_id]
+
+
+def _self_parents(plans):
+    return [p for p in plans if p.parent == p.id]
+
+
+def _cross_project_parents(plans, by_id):
+    findings = []
+    for p in plans:
+        if not p.parent:
+            continue
+        parent = by_id.get(p.parent)
+        if parent is None:
+            continue
+        if parent.project != p.project:
+            findings.append(p)
+    return findings
+
+
+def _in_cycle(plan, by_id):
+    if plan.parent == plan.id:
+        return False
+    seen = set()
+    current = plan
+    while current is not None and current.parent:
+        if current.id in seen:
+            return current.id == plan.id
+        seen.add(current.id)
+        current = by_id.get(current.parent)
+    return False
+
+
+def _cycle_members(plans, by_id):
+    return [p for p in plans if p.parent and _in_cycle(p, by_id)]
+
+
+def duplicate_ids(plans):
+    seen = set()
+    duplicates = []
+    for p in plans:
+        if p.id in seen:
+            duplicates.append(p)
+        else:
+            seen.add(p.id)
+    return duplicates
+
+
+def _off_vocabulary_status(plans):
+    return [p for p in plans if p.status not in vocabulary_module.STATUS_ORDER]
+
+
+def _off_vocabulary_intent(plans):
+    return [p for p in plans if p.intent not in vocabulary_module.INTENT_VALUES]
+
+
+def _missing_title(plans):
+    return [p for p in plans if not p.has_title]
+
+
+def _malformed_tags(plans):
+    return [p for p in plans if any(not tags_module.is_valid(t) for t in p.tags)]
+
+
+def _missing_progress(plans):
+    return [p for p in plans if status_module.progress_section(p.body) is None]
+
+
+def _underived_project(plans, sessions):
+    findings = []
+    for p in plans:
+        if p.project:
+            continue
+        session = sessions.get(p.id)
+        if session and session.project:
+            findings.append(p)
+    return findings
+
+
+def _status_behind_history(plans, touches):
+    findings = []
+    for p in plans:
+        if p.status not in _HISTORY_ELIGIBLE_STATUSES:
+            continue
+        worked = touches_module.worked(touches.get(p.id, []), p.id)
+        if not worked:
+            continue
+        sessions_worked = len({t.session for t in worked})
+        message = (
+            f"status {p.status!r} but "
+            f"{counts.plural(sessions_worked, 'later session')} worked this plan; "
+            f"see `pentimento history {p.id}`"
+        )
+        findings.append(Finding(p.id, "status-behind-history", message))
+    return findings
+
+
+_PROGRESS_RANK = {s: i for i, s in enumerate(vocabulary_module.PROGRESS_ORDER)}
+
+
+def _status_behind_progress(plans):
+    findings = []
+    for p in plans:
+        if p.status not in _PROGRESS_RANK:
+            continue
+        derived = status_module.derive_status(p.body)
+        if derived not in _PROGRESS_RANK:
+            continue
+        if _PROGRESS_RANK[derived] <= _PROGRESS_RANK[p.status]:
+            continue
+        message = (
+            f"status {p.status!r} but '## Progress' derives {derived!r}; run pentimento backfill"
+        )
+        findings.append(Finding(p.id, "status-behind-progress", message))
+    return findings
+
+
+def run(plans, sessions=None, touches=None, skips=None) -> list[Finding]:
+    """Return structured findings; an empty list means a clean corpus.
+
+    `sessions`, when given, enables the `underived-project` finding; it
+    stays silent by default so Cursor plans and session-less plans, where
+    an empty `project` is a legitimate state, are not flagged. `touches`,
+    when given, enables `status-behind-history` the same way. `skips`, when
+    given, is the `(source, path, error)` list `corpus.load_all` collected
+    for files it could not read; each becomes an `unreadable-file` finding.
+    """
+    sessions = sessions or {}
+    touches = touches or {}
+    skips = skips or []
+    by_id = {p.id: p for p in plans}
+    findings = []
+
+    for _source, path, exc in skips:
+        message = f"could not read {path}: {exc}"
+        findings.append(Finding(path.name, "unreadable-file", message))
+
+    for p in _dangling_parents(plans, by_id):
+        message = f"parent {p.parent!r} does not resolve to a plan"
+        findings.append(Finding(p.id, "dangling-parent", message))
+    for p in _self_parents(plans):
+        findings.append(Finding(p.id, "self-parent", "parent is itself"))
+    for p in _cross_project_parents(plans, by_id):
+        message = f"parent {p.parent!r} is in a different project"
+        findings.append(Finding(p.id, "cross-project-parent", message))
+    for p in _cycle_members(plans, by_id):
+        message = "parent chain cycles back to itself"
+        findings.append(Finding(p.id, "cycle", message))
+    for p in duplicate_ids(plans):
+        message = f"duplicate id across sources (second occurrence from {p.source})"
+        findings.append(Finding(p.id, "duplicate-id", message))
+    for p in _off_vocabulary_status(plans):
+        message = f"status {p.status!r} is outside {vocabulary_module.STATUS_ORDER}"
+        findings.append(Finding(p.id, "off-vocabulary-status", message))
+    for p in _off_vocabulary_intent(plans):
+        message = f"intent {p.intent!r} is outside {vocabulary_module.INTENT_VALUES}"
+        findings.append(Finding(p.id, "off-vocabulary-intent", message))
+    for p in _missing_title(plans):
+        message = "body has no H1 title; falling back to the plan id"
+        findings.append(Finding(p.id, "missing-title", message))
+    for p in _malformed_tags(plans):
+        bad = [t for t in p.tags if not tags_module.is_valid(t)]
+        message = f"malformed tag(s) {bad!r}"
+        findings.append(Finding(p.id, "malformed-tag", message))
+    for p in _missing_progress(plans):
+        message = "body has no '## Progress' heading; status can't be derived"
+        findings.append(Finding(p.id, "missing-progress", message))
+    for p in _underived_project(plans, sessions):
+        message = f"session supplies project {sessions[p.id].project!r} but frontmatter has none"
+        findings.append(Finding(p.id, "underived-project", message))
+    findings.extend(_status_behind_history(plans, touches))
+    findings.extend(_status_behind_progress(plans))
+
+    return findings