78 lines
3.2 KiB
Python
78 lines
3.2 KiB
Python
"""todo.md on disk: read it with the project files ranking reads, then rank or check it, write it back, and print what ranking reports."""
|
|
import pathlib
|
|
import sys
|
|
|
|
from failure import Failure
|
|
from project_config.main import goals_file
|
|
from review_rules.comprehension_history import HISTORY
|
|
from release_plan.ranking import rank, Ranked
|
|
from records.file_writes import replace_file
|
|
|
|
|
|
def rank_file(todo: pathlib.Path) -> Ranked | Failure:
|
|
"""Rank todo in place: rank what read_all reads, write todo where that changed it, and print the notes and under-bar lines on stderr."""
|
|
texts = read_all(todo)
|
|
if isinstance(texts, Failure):
|
|
return texts
|
|
ranked = rank(*texts)
|
|
if isinstance(ranked, Failure):
|
|
return ranked
|
|
if ranked.text != texts[0] and (unwritten := write(todo, ranked.text)):
|
|
return unwritten
|
|
print_report(todo, ranked)
|
|
return ranked
|
|
|
|
|
|
def print_report(todo: pathlib.Path, ranked: Ranked) -> None:
|
|
"""Print ranking's notes and under-bar lines on stderr, each prefixed with todo's path."""
|
|
for line in ranked.notes + ranked.under_bar:
|
|
print(f"{todo}: {line}", file=sys.stderr)
|
|
|
|
|
|
def check_failures(todo: pathlib.Path) -> list[str]:
|
|
"""Why --check fails on todo, empty when it passes."""
|
|
texts = read_all(todo)
|
|
if isinstance(texts, Failure):
|
|
return [texts.reason]
|
|
ranked = rank(*texts)
|
|
if isinstance(ranked, Failure):
|
|
return [ranked.reason]
|
|
unranked = [] if ranked.text == texts[0] else [f"{todo}: not ranked; run rank_todo.py on it"]
|
|
return unranked + [f"{todo}: {line}" for line in ranked.under_bar]
|
|
|
|
|
|
def read_all(todo: pathlib.Path) -> tuple[str, str, str, str] | Failure:
|
|
"""todo.md, the goals file its project's config names, and its docs/decisions.md and docs/comprehension-history.md. The last two are empty when missing; a missing todo.md, config or goals file is a Failure."""
|
|
plan = read(todo, "every project keeps a todo.md, and rank_todo.py --help shows one")
|
|
if isinstance(plan, Failure):
|
|
return plan
|
|
# Looked up after todo.md is read, so a mistyped path fails naming todo.md, not in git's words.
|
|
goals = goals_file(str(todo.parent), pathlib.Path.home())
|
|
if isinstance(goals, Failure):
|
|
return goals
|
|
goals_text, decisions, history = read(goals, "rank_todo.py weighs goals from the file the project's config names as goals-and-audience"), read(todo.parent / "docs" / "decisions.md", None), read(todo.parent / HISTORY, None)
|
|
if isinstance(goals_text, Failure):
|
|
return goals_text
|
|
if isinstance(decisions, Failure):
|
|
return decisions
|
|
if isinstance(history, Failure):
|
|
return history
|
|
return plan, goals_text, decisions, history
|
|
|
|
|
|
def read(path: pathlib.Path, missing: str | None) -> str | Failure:
|
|
"""path's text; where it is missing, a Failure saying missing, or "" where missing is None."""
|
|
try:
|
|
return path.read_text(encoding="utf-8")
|
|
except FileNotFoundError:
|
|
return Failure(f"{path}: not found; {missing}") if missing else ""
|
|
except OSError as failure:
|
|
return Failure(f"{path}: {failure.strerror}")
|
|
except UnicodeDecodeError:
|
|
return Failure(f"{path}: not UTF-8")
|
|
|
|
|
|
def write(path: pathlib.Path, text: str) -> Failure | None:
|
|
unwritten = replace_file(path.resolve(), text.encode("utf-8"))
|
|
return Failure(f"{path}: {unwritten.reason}") if unwritten else None
|