Erich Blume
92e5dcfffc
- prek hooks: convert all rev = "vX.Y.Z" to commit SHAs with version comments - fly/Dockerfile: digest-pin nginx (1.30.0-alpine), tailscale (v1.94.2), and alloy (v1.16.0); bump from previous tag pins - mise-tasks: pin PEP 723 deps with == (rich 15.0.0, typer 0.25.0, pyyaml 6.0.3, httpx 0.28.1) — PEP 508 doesn't support hashes inline - prek additional_dependencies: pin ansible-lint==26.4.0, ansible-core==2.20.5 - taplo-lint: pass --no-schema (upstream catalog format changed and taplo v0.9.3 can't parse it; we don't validate against TOML schemas) - docs/update-tooling-dependencies: document SHA-pin convention, digest-pin lookup via docker buildx imagetools, and prek clean before re-verifying (cache can grow to several GiB) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
102 lines
3.2 KiB
Text
Executable file
102 lines
3.2 KiB
Text
Executable file
#!/usr/bin/env -S uv run --script
|
|
# /// script
|
|
# requires-python = ">=3.12"
|
|
# dependencies = ["rich==15.0.0", "typer==0.25.0"]
|
|
# ///
|
|
#MISE description="Report docs by git-last-modified date, highlighting stale ones"
|
|
#USAGE flag "--threshold <threshold>" default="180" help="Days before a doc is considered stale"
|
|
"""Report documentation files sorted by git-last-modified date.
|
|
|
|
Scans all markdown files in docs/ (excluding changelog.d/) and shows
|
|
their last modification date according to git. Docs older than the
|
|
threshold (default 180 days) are highlighted as stale.
|
|
|
|
This is informational only — it always exits 0.
|
|
|
|
Usage: mise run docs-review-stale [-- --threshold 90]
|
|
"""
|
|
|
|
import subprocess
|
|
import sys
|
|
from datetime import datetime, timezone
|
|
from pathlib import Path
|
|
from typing import Annotated
|
|
|
|
import typer
|
|
from rich.console import Console
|
|
from rich.table import Table
|
|
|
|
DOCS_DIR = Path(__file__).parent.parent / "docs"
|
|
|
|
|
|
def git_last_modified(file_path: Path) -> datetime | None:
|
|
"""Get the last git commit date for a file."""
|
|
try:
|
|
result = subprocess.run(
|
|
["git", "log", "-1", "--format=%aI", "--", str(file_path)],
|
|
capture_output=True,
|
|
text=True,
|
|
check=True,
|
|
)
|
|
date_str = result.stdout.strip()
|
|
if not date_str:
|
|
return None
|
|
return datetime.fromisoformat(date_str)
|
|
except subprocess.CalledProcessError:
|
|
return None
|
|
|
|
|
|
def main(
|
|
threshold: Annotated[int, typer.Option(help="Days before a doc is considered stale")] = 180,
|
|
) -> None:
|
|
console = Console()
|
|
threshold_days = threshold
|
|
console.print("[bold]Documentation Staleness Report[/bold]")
|
|
console.print(f"Threshold: {threshold_days} days")
|
|
console.print()
|
|
|
|
now = datetime.now(timezone.utc)
|
|
entries: list[tuple[str, datetime, int, bool]] = []
|
|
|
|
for md_file in sorted(DOCS_DIR.rglob("*.md")):
|
|
if "changelog.d" in md_file.parts:
|
|
continue
|
|
|
|
last_modified = git_last_modified(md_file)
|
|
if last_modified is None:
|
|
continue
|
|
|
|
rel_path = str(md_file.relative_to(DOCS_DIR))
|
|
age_days = (now - last_modified).days
|
|
is_stale = age_days > threshold_days
|
|
entries.append((rel_path, last_modified, age_days, is_stale))
|
|
|
|
# Sort oldest-first
|
|
entries.sort(key=lambda e: e[1])
|
|
|
|
stale_count = sum(1 for e in entries if e[3])
|
|
|
|
table = Table(show_header=True, header_style="bold")
|
|
table.add_column("File")
|
|
table.add_column("Last Modified", justify="right")
|
|
table.add_column("Age (days)", justify="right")
|
|
table.add_column("Status")
|
|
|
|
for rel_path, last_modified, age_days, is_stale in entries:
|
|
date_str = last_modified.strftime("%Y-%m-%d")
|
|
if is_stale:
|
|
table.add_row(
|
|
f"[red]{rel_path}[/red]",
|
|
f"[red]{date_str}[/red]",
|
|
f"[red]{age_days}[/red]",
|
|
"[red]STALE[/red]",
|
|
)
|
|
else:
|
|
table.add_row(rel_path, date_str, str(age_days), "[green]OK[/green]")
|
|
|
|
console.print(table)
|
|
console.print()
|
|
console.print(f"Total: {len(entries)} docs, {stale_count} stale")
|
|
|
|
if __name__ == "__main__":
|
|
typer.run(main)
|