Docs Sentry

Audit GitHub organization READMEs and surface documentation gaps in seconds

Quick Start ->

Docs Sentry scans repositories in a GitHub organization, checks README structure against a practical template, and produces actionable reports for maintainers.

---

You are an AI agent working on docs-sentry, a Rust 2024 CLI that audits
README quality for GitHub organization repositories using gh CLI data.
Clone https://github.com/Open330/docs-sentry and improve scoring rules,
report formats, and workflow integrations for documentation governance.

Features

Organization Scan -- Pull repositories with gh repo list and inspect each README through the GitHub API.

Template-Aware Scoring -- Score docs coverage with weighted checks for sections like Features, Quick Start, Architecture, and License using heading-intent matching (#, ##, ###, setext headings with 3+ underline markers) while ignoring fenced code blocks.

Actionable Gaps -- Return missing required and recommended sections per repo, plus threshold-based notes.

Three Output Modes -- Emit terminal table, markdown report, or machine-consumable JSON.

Strict CI Mode -- Use --strict to fail with exit code 2 when one or more repos fall below --min-score.

Fetch Error Visibility -- Network/auth/API failures are reported as fetch-error instead of being mislabeled as missing READMEs.

Score Model

Check	Weight	Type
Features	18	Required
Quick Start / Getting Started	16	Required
Architecture	14	Required
License	14	Required
Tech Stack	10	Recommended
Usage / CLI Options / Commands	8	Recommended
Run Tests / Testing	8	Recommended
Deploy / Deployment	6	Recommended
Centered Hero Block	3	Recommended
Agent Header Block	3	Recommended

Total: 100 points.

Status Tiers

Status	Score
strong	85-100
needs-work	60-84
weak	0-59
missing-readme	README missing
fetch-error	README could not be fetched

CLI Options

Option	Default	Description
--org	Open330	Target GitHub organization
--limit	100	Maximum repositories to scan
--min-score	70	Threshold used to flag low documentation quality
--format	table	Output format: table, markdown, json
--include-private	false	Include private repositories
--strict	false	Exit with code 2 if repos are below threshold

Architecture

docs-sentry/
├── assets/
│   └── logo.svg               # README logo
├── src/
│   ├── main.rs                # CLI entry point and exit-code behavior
│   ├── lib.rs                 # Scan orchestration
│   ├── config.rs              # Argument parsing and defaults
│   ├── github.rs              # gh command wrappers and repository/README fetches
│   ├── audit.rs               # Scoring model, status classification, summaries
│   └── output.rs              # Table/markdown/json rendering
├── .github/workflows/ci.yml   # fmt + clippy + test + release build checks
└── Cargo.toml                 # Package metadata

Tech Stack

Layer	Technology
Language	Rust (edition 2024)
Data Source	GitHub CLI (gh)
Runtime	Rust standard library
CI	GitHub Actions

Quick Start

# Clone
git clone https://github.com/Open330/docs-sentry.git
cd docs-sentry

# Audit default org with table output
cargo run --

# Generate markdown report
cargo run -- --org Open330 --format markdown --min-score 80

# Include private repos and enforce threshold
cargo run -- --org Open330 --include-private --strict

Run Tests

cargo test

Typecheck and Lint

cargo check
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings

Build

cargo build --release

Deploy

No server deployment is required. This project is a local/CI CLI utility.

License

MIT

---

_{Built for maintainers who want fast and consistent README governance across repositories.}