repository-hygiene

Repository hygiene auditor for Git repositories. Checks for secrets, broken links, missing references, artifacts outside .gitignore, GitHub Actions workflow security, and more.

Installation

pip install repository-hygiene

Usage

Audit a repository

repository-hygiene audit .                    # text (default)
repository-hygiene audit . --format json      # JSON
repository-hygiene audit . --format sarif     # SARIF
repository-hygiene audit --config path/to/auditoria.yaml .

Initialize a project

repository-hygiene install .                  # creates auditoria.yaml + workflow
repository-hygiene install --force .          # overwrites existing files

Update

repository-hygiene update                     # check for updates
repository-hygiene update --version 0.1.0     # update to specific version

Exit codes

Configuration

File auditoria.yaml in the project root:

versao_configuracao: 1

regras:
  segredos_rastreados:
    habilitada: true
    severidade: error
  links_internos_quebrados:
    habilitada: true
    severidade: error
  referencias_inexistentes:
    habilitada: true
    severidade: error
  artefatos_fora_gitignore:
    habilitada: true
    severidade: error
  gitkeep_sem_conteudo:
    habilitada: true
    severidade: warning
  arquivos_sem_referencia:
    habilitada: true
    severidade: warning
  documentacao_desatualizada:
    habilitada: true
    severidade: warning
  configuracao_sem_integracao:
    habilitada: true
    severidade: warning
  openspec_parada:
    habilitada: true
    severidade: warning
  workflows_inseguros:
    habilitada: true
    severidade: warning

excecoes:
  segredos_rastreados:
    - .secrets.baseline
    - .env.example
  referencias_inexistentes:
    - audit-report.txt
  artefatos_fora_gitignore:
    - .git
  arquivos_sem_referencia:
    - .gitignore
    - Makefile

Rules

GitHub Actions

The install command generates a caller workflow in .github/workflows/repository-hygiene.yml that:

• Runs weekly and on push/PR in relevant paths
• Calls the reusable workflow from frederico-mello/repository-hygiene at a fixed version
• Publishes report in the execution summary
• Creates/updates a consolidated issue when errors are found
• Closes the issue when the audit is clean

Minimum workflow permissions

permissions:
  contents: read
  issues: write
  pull-requests: read

Versioning

The package follows SemVer. Configuration declares versao_configuracao for future compatibility.

• v0.1.x — initial version
• Workflow tags follow package tags

Development

pip install -e .
pytest tests_package/

License

MIT