repo-hygiene-checker-cli
Check a repo is publish-ready against a fixed publish template — pass/fail per check, nothing invented.
What it does
repo-hygiene-checker reads a repo and reports, for each check, one of PASS, FAIL, WARN, or SKIP. A check is never reported PASS unless its test actually ran. Exit code 0 means no failures (warnings allowed), 1 means at least one failure, 2 means a usage error such as a missing path.
Required checks (a missing one is a FAIL):
- README exists, is non-empty, and has a top-level heading.
- README carries Install, Usage, and Examples sections.
- A licence file exists and actually contains MIT licence text — a file named LICENSE with other text fails.
.gitignoreexists and is non-empty, and actually covers.envplus Python cache files (__pycache__/or*.pyc) when the repo contains Python files.- A CI workflow exists in
.github/workflows/and contains a step that runs tests — a workflow with no test step fails. - At least one issue template exists in
.github/ISSUE_TEMPLATE/. - With
--onlineonly: the GitHub description is non-empty and at least one topic is set (read from the public GitHub API, no token). Without--onlineboth report SKIP, never PASS.
Recommended checks (a missing one is a WARN, not a FAIL; --strict turns warnings into failures):
- CONTRIBUTING.md and SECURITY.md present.
- If the repo has a
skills/directory, everyskills/*/SKILL.mdcarriesname:anddescription:frontmatter. - A
tests/directory with at least one test file.
What it does NOT do
- It does not fix anything. It only reads and reports — no file is ever written, deleted, or renamed.
- It does not guess. A check that cannot run (offline description/topics, no
skills/directory) reports SKIP with the reason, never PASS. - It does not check README quality, spelling, or code correctness — only that the publish template is present and conformed to.
- It does not send your code anywhere. Without
--onlineit makes no network call at all; with--onlineits only call is one unauthenticated read of the public GitHub API for the checked repo's description and topics.
Who it is for
Anyone about to publish a small open-source repo — especially an agent skill or a small CLI — who wants a one-command gate that catches the missing file before a reader does, in CI or as a one-off check before publishing.
How this differs from similar tools
Generic presence checkers already exist: repogap checks README / LICENSE / .gitignore / CHANGELOG presence plus package.json / pyproject.toml fields, and repo-doctor scores 17 rules and auto-generates missing files. This tool does a different, narrower job: it checks conformance to a publish template — README section order, MIT licence text (not just a file with the right name), .gitignore content, a CI workflow that actually runs tests, and SKILL.md frontmatter. It never writes anything, and it never calls a check PASS that did not run.
Install
Python standard library only — no packages to download. Clone the repo and run it in place:
git clone https://github.com/haiderstudio/repo-hygiene-checker-cli.git
cd repo-hygiene-checker-cli
Usage
Check a repo (defaults to the current directory):
python3 src/repo_hygiene_checker.py examples/good-repo
python3 src/repo_hygiene_checker.py /path/to/your-repo
Real output from the bundled examples:
repo-hygiene-checker: examples/good-repo
PASS README: README.md present, non-empty, has heading
PASS README sections: Install, Usage, and Examples sections present
PASS Licence (MIT): LICENSE contains MIT licence text
PASS .gitignore: .gitignore present, non-empty
PASS .gitignore coverage: .env and Python cache patterns covered
PASS CI runs tests: ci.yml contains a step that runs tests
PASS Issue templates: 1 template(s) in .github/ISSUE_TEMPLATE/
PASS CONTRIBUTING.md: CONTRIBUTING.md present
PASS SECURITY.md: SECURITY.md present
SKIP Skill frontmatter: no skills/ directory
PASS Tests present: 1 test file(s) in tests/
SKIP GitHub description: needs --online (no network call made)
SKIP GitHub topics: needs --online (no network call made)
repo-hygiene-checker: 10 passed, 0 failed, 0 warnings, 3 skipped
Useful flags:
# Also check the GitHub description and topics (one public API read, no token)
python3 src/repo_hygiene_checker.py --online /path/to/your-repo
# Machine-readable output
python3 src/repo_hygiene_checker.py --format json /path/to/your-repo
# Treat warnings as failures (for CI gates)
python3 src/repo_hygiene_checker.py --strict /path/to/your-repo
Examples
A good repo passes every offline check (exit 0). A bad repo fails five checks (exit 1):
sh examples/run-example.sh
repo-hygiene-checker: examples/bad-repo
PASS README: README.md present, non-empty, has heading
FAIL README sections: missing section(s): usage, example
FAIL Licence (MIT): no licence file found
PASS .gitignore: .gitignore present, non-empty
FAIL .gitignore coverage: .gitignore does not cover: __pycache__/ or *.pyc
FAIL CI runs tests: .github/workflows/ not found
FAIL Issue templates: no issue template in .github/ISSUE_TEMPLATE/
WARN CONTRIBUTING.md: CONTRIBUTING.md missing (recommended, not blocking)
WARN SECURITY.md: SECURITY.md missing (recommended, not blocking)
SKIP Skill frontmatter: no skills/ directory
WARN Tests present: no test files in tests/ (recommended, not blocking)
SKIP GitHub description: needs --online (no network call made)
SKIP GitHub topics: needs --online (no network call made)
repo-hygiene-checker: 2 passed, 5 failed, 3 warnings, 3 skipped
Check this repo against itself (it passes its own gate):
python3 src/repo_hygiene_checker.py .
How it is tested
20 unit tests, standard library unittest only — no third-party packages:
python3 tests/test_repo_hygiene_checker.py
Tests build fixture repos in temp directories (good repo, missing README, non-MIT licence, thin .gitignore, workflow without a test step, missing templates, missing CONTRIBUTING, bad SKILL.md frontmatter) and assert the exact status and exit code for each. The --online checks run against a real local HTTP server started by the tests, never against the public GitHub API.
Contributing
See CONTRIBUTING.md. Small, focused improvements are welcome; every new check must come with a test, and no status may ever be invented for a check that did not run.
Licence
MIT — see LICENSE. This is original work: the checks, the template-conformance idea, and all code were written fresh for this repo. Similar tools are named in "How this differs from similar tools" above; nothing was copied from them.
Metadata
Release files for repo-hygiene-checker-cli 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| repo_hygiene_checker_cli-0.1.0.tar.gz | 14.0 kB | Without provenance | Details for repo_hygiene_checker_cli-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| repo_hygiene_checker_cli-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for repo_hygiene_checker_cli-0.1.0-py3-none-any.whl |
Total release size: 24.2 kB
Release files / repo_hygiene_checker_cli-0.1.0.tar.gz
| Download URL | repo_hygiene_checker_cli-0.1.0.tar.gz |
|---|---|
| Size | 14.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9746a654fde1cb88f77ab339cb452a263ad7b659403d6225dc462e232b83b3f6
|
|
BLAKE2b-256 checksum How to use checksums |
da1bb8087c3a7cdf9b628ab6ed3e4461c75e78c2aa25b83213fe8e117a62282a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / repo_hygiene_checker_cli-0.1.0-py3-none-any.whl
| Download URL | repo_hygiene_checker_cli-0.1.0-py3-none-any.whl |
|---|---|
| Size | 10.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b815a3cc685750f8cad3c15f900088e85de292759bbe9e1e61d1c3ba40f38132
|
|
BLAKE2b-256 checksum How to use checksums |
a1202f30f5d25c6dfcc08073c720b57d2e0d80de8b1be2a61ebdbaa13b63461d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Security for repo-hygiene-checker-cli 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.