Rename doc-* mise tasks to docs-check-* / docs-review-* (#113)
## Summary - Rename 4 automated-check tasks: `doc-titles` → `docs-check-titles`, `doc-filenames` → `docs-check-filenames`, `doc-links` → `docs-check-links`, `doc-index` → `docs-check-index` - Rename 3 interactive-review tasks: `doc-random` → `docs-review-random`, `doc-tags` → `docs-review-tags`, `doc-stale` → `docs-review-stale` - Update all references in `.pre-commit-config.yaml`, `ai-assistance-guide.md`, and `review-documentation.md` - Historical changelog entries left as-is ## Test plan - [x] `mise run docs-check-titles` exits 0 - [x] `mise run docs-check-links` exits 0 - [x] `mise run docs-review-tags` exits 0 - [x] `mise run doc-titles` fails with "no task found" - [x] All pre-commit hooks pass (including renamed hook IDs) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Reviewed-on: https://forge.ops.eblu.me/eblume/blumeops/pulls/113
This commit is contained in:
parent
060c7a24e3
commit
cb343a2e35
11 changed files with 30 additions and 29 deletions
101
mise-tasks/docs-review-stale
Executable file
101
mise-tasks/docs-review-stale
Executable file
|
|
@ -0,0 +1,101 @@
|
|||
#!/usr/bin/env -S uv run --script
|
||||
# /// script
|
||||
# requires-python = ">=3.12"
|
||||
# dependencies = ["rich>=13.0.0", "typer>=0.9.0"]
|
||||
# ///
|
||||
#MISE description="Report docs by git-last-modified date, highlighting stale ones"
|
||||
"""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)
|
||||
Loading…
Add table
Add a link
Reference in a new issue