73 lines
3.0 KiB
Python
73 lines
3.0 KiB
Python
"""todo.md on disk: read it with the files ranking reads, at the paths the project's config names, then rank or check it, write it back, and print what ranking reports."""
|
|
import pathlib
|
|
import sys
|
|
|
|
from failure import Failure
|
|
from project_config.settings import ProjectConfig
|
|
from release_plan.ranking import rank, Ranked
|
|
from text_files.file_writes import replace_file
|
|
|
|
|
|
def rank_file(todo: pathlib.Path, config: ProjectConfig) -> 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, config)
|
|
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, config: ProjectConfig) -> list[str]:
|
|
"""Why --check fails on todo, empty when it passes."""
|
|
texts = read_all(todo, config)
|
|
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, config: ProjectConfig) -> tuple[str, str, str, str] | Failure:
|
|
"""todo, the plan, then the goals file, the decision log and the comprehension history that config names. The last two are empty when missing; a missing plan 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
|
|
goals_text, decisions, history = read(config.paths["goals-and-audience"], "rank_todo.py weighs goals from the file the project's config names as goals-and-audience"), read(config.paths["decisions"], None), read(config.paths["comprehension-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
|