mirror of
https://github.com/kuhyx/utils.git
synced 2026-11-10 21:07:15 +01:00
Krzysztof kuhy Rudnicki
a10d190b65
Some checks failed
file length / file-length (push) Waiting to run
md-naming / markdown naming convention (push) Waiting to run
palette drift / palette (push) Waiting to run
design_system tests / test (push) Has been cancelled
gatelock pre-commit / pre-commit (push) Has been cancelled
gatelock tests / test (3.10) (push) Has been cancelled
gatelock tests / test (3.11) (push) Has been cancelled
gatelock tests / test (3.12) (push) Has been cancelled
web_ui tests / test (push) Has been cancelled
Markdown across every repo had accumulated a dozen ad-hoc names (refactor_claude_todo.md x23, DESIGN_AUDIT_TODO.md, NEXT_SESSION, HANDOFF, PLAN, SPEC) with nothing distinguishing a live task from a finished record. An audit found docs asserting work was pending that shipped months earlier, and one asserting completion while the work was open. Four namespaces now: README.md, CLAUDE*.md, DOCS*.md, TODO*.md. Task files carry the literal "REMOVE ME AFTER FINISH" and are deleted when the work lands. Enforced bidirectionally -- a TODO without the marker fails, AND any file carrying the marker that is not named TODO*.md fails. Without the reverse rule a task can be renamed into the permanent namespace and quietly live forever, which is the failure being fixed. md_naming/ mirrors the file_length topology and imports its tables (EXCLUDED_DIRS, THIRD_PARTY_REPOS, VENDORED_ANYWHERE, GENERATED_PATTERN) rather than restating them, so the two gates cannot disagree about the same file. 71 tests, 100% branch coverage. stale.py warns on TODOs past 90 days but never fails: no machine can prove a task is finished, so the honest mechanism is a nudge. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01A47aX5DJwmA3QFn3pkEWi7
84 lines
2.7 KiB
Python
84 lines
2.7 KiB
Python
"""Report TODO files that have sat untouched for too long.
|
|
|
|
CI cannot prove a task is finished -- no exit code exists for "done" -- so the
|
|
honest mechanism is a nudge, not a gate. This module only ever emits GitHub
|
|
`::warning::` lines and exits 0, deliberately: a build that fails because a
|
|
task is merely *old* trains people to ignore it.
|
|
|
|
Ages come from the last git commit that touched the file, not mtime, because
|
|
a checkout rewrites every mtime to the clone time.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import argparse
|
|
import subprocess
|
|
import sys
|
|
from datetime import datetime, timezone
|
|
from pathlib import Path
|
|
|
|
if __package__ in (None, ""): # pragma: no cover - plain-script import path
|
|
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
|
|
|
|
from file_length.check import iter_all
|
|
from md_naming.config import STALE_DAYS, is_todo
|
|
|
|
|
|
def last_commit_epoch(path: Path, root: Path) -> int | None:
|
|
"""Unix time of the last commit touching `path`, or None if unknown."""
|
|
try:
|
|
result = subprocess.run(
|
|
["git", "-C", str(root), "log", "-1", "--format=%ct", "--", str(path)],
|
|
capture_output=True,
|
|
text=True,
|
|
check=False,
|
|
)
|
|
except OSError: # git not installed
|
|
return None
|
|
if result.returncode != 0:
|
|
return None
|
|
stamp = result.stdout.strip()
|
|
return int(stamp) if stamp.isdigit() else None
|
|
|
|
|
|
def age_days(path: Path, root: Path, now: int) -> int | None:
|
|
"""Whole days since `path` was last committed, or None if unknown."""
|
|
epoch = last_commit_epoch(path, root)
|
|
if epoch is None:
|
|
return None
|
|
return (now - epoch) // 86_400
|
|
|
|
|
|
def stale_todos(root: Path, limit: int, now: int) -> list[tuple[Path, int]]:
|
|
"""Every TODO under `root` older than `limit` days, oldest first."""
|
|
found: list[tuple[Path, int]] = []
|
|
for path in iter_all(root):
|
|
if not is_todo(path):
|
|
continue
|
|
days = age_days(path, root, now)
|
|
if days is not None and days >= limit:
|
|
found.append((path, days))
|
|
return sorted(found, key=lambda item: -item[1])
|
|
|
|
|
|
def main() -> int:
|
|
parser = argparse.ArgumentParser(
|
|
description="Warn about TODO files older than the staleness limit."
|
|
)
|
|
parser.add_argument("--days", type=int, default=STALE_DAYS)
|
|
args = parser.parse_args()
|
|
|
|
root = Path.cwd()
|
|
now = int(datetime.now(tz=timezone.utc).timestamp())
|
|
for path, days in stale_todos(root, args.days, now):
|
|
rel = path.relative_to(root) if path.is_relative_to(root) else path
|
|
print(
|
|
f"::warning file={rel}::{rel} is {days} days old. "
|
|
"Still outstanding? If the work landed, delete this file."
|
|
)
|
|
return 0
|
|
|
|
|
|
if __name__ == "__main__":
|
|
raise SystemExit(main())
|