Skip to main content

repo-hygiene-checker-cli

Check a repo is publish-ready against a fixed publish template — pass/fail per check, nothing invented.

CI Licence: MIT

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.
  • .gitignore exists and is non-empty, and actually covers .env plus 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 --online only: the GitHub description is non-empty and at least one topic is set (read from the public GitHub API, no token). Without --online both 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, every skills/*/SKILL.md carries name: and description: 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 --online it makes no network call at all; with --online its 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)

Source distribution for repo-hygiene-checker-cli 0.1.0
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)

Table of built distributions (wheels) for repo-hygiene-checker-cli 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page