repoguard-tool 0.1.0__tar.gz

repoguard_tool-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,27 @@
+---
+name: Bug Report
+about: Create a report to help us improve RepoGuard
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+**Describe the Bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Command executed: `repoguard scan ...`
+2. Configuration file used: (if any)
+3. See error:
+
+**Expected Behavior**
+A clear and concise description of what you expected to happen.
+
+**Environment:**
+- RepoGuard Version: [e.g. 0.1.0]
+- Python Version: [e.g. 3.11.8]
+- OS: [e.g. macOS, Ubuntu 22.04]
+
+**Additional Context**
+Add any other context about the problem here.

repoguard_tool-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature Request
+about: Suggest an idea or analyzer for RepoGuard
+title: '[FEATURE] '
+labels: enhancement
+assignees: ''
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the Solution You'd Like**
+A clear and concise description of what you want to happen.
+
+**Describe Alternatives You've Considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional Context**
+Add any other context or screenshots about the feature request here.

repoguard_tool-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,21 @@
+## Description
+
+Please include a summary of the change and which issue it fixes.
+
+Fixes #(issue)
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds an analyzer or capability)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+
+## Checklist
+
+- [ ] My code follows the style guidelines of this project (`ruff check .` passes)
+- [ ] I have performed a self-review of my own code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] New and existing unit tests pass locally with my changes (`pytest`)
+- [ ] Documentation has been updated accordingly

repoguard_tool-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Lint & Test
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+          pip install -e examples/custom_plugin
+
+      - name: Run Ruff Lint & Format Check
+        run: |
+          ruff check .
+          ruff format --check .
+
+      - name: Run Pytest Test Suite
+        run: |
+          pytest -v

repoguard_tool-0.1.0/.github/workflows/pypi-publish.yml

@@ -0,0 +1,33 @@
+
+name: Publish RepoGuard to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    name: Build and publish package
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

repoguard_tool-0.1.0/.github/workflows/repoguard.yml

@@ -0,0 +1,29 @@
+name: RepoGuard Health Scan
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  repoguard:
+    name: RepoGuard Scan
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Execute RepoGuard Health Scan
+        uses: ./
+        with:
+          min-score: "70"
+          fail-on: "critical"
+          no-network: "false"
+          output-json: "repoguard-report.json"
+          output-markdown: "repoguard-summary.md"

repoguard_tool-0.1.0/.gitignore

@@ -0,0 +1,50 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Testing & Linting
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# Scan report outputs
+*.report.json
+report.json
+repoguard-report.json
+repoguard-summary.md
+
+# OS artifacts
+.DS_Store
+Thumbs.db

repoguard_tool-0.1.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to RepoGuard will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.0] - 2026-11-08
+
+### Added
+- **Core Scanning Engine**:
+  - `RepoScanner` with error-isolated analyzer execution.
+  - Deterministic finding deduplication via content-based SHA-256 fingerprinting.
+  - Safe repository context (`ScanContext`) with traversal protection and file size caps.
+- **Built-in Analyzers**:
+  - `DocumentationAnalyzer`: README existence, installation/usage sections, LICENSE, CONTRIBUTING.
+  - `DependencyAnalyzer`: unpinned dependencies, OSV API CVE/GHSA scanning, registry version checks.
+  - `SecurityAnalyzer`: secret detection (AWS keys, GitHub tokens, Slack webhooks, private keys), dangerous calls (`shell=True`, `eval`), secret masking.
+  - `TestingAnalyzer`: test directory detection, framework identification, CI test step verification.
+  - `CodeQualityAnalyzer`: Python AST cyclomatic complexity, parameter counts, function length, wildcard imports.
+  - `CiCdAnalyzer`: GitHub workflow validation, permissions auditing (`write-all`), mutable branch pinning.
+- **Health Scoring Engine**:
+  - Transparent 0-100 scoring with letter grades (`A` to `F`).
+  - Configurable category weights and severity deductions.
+  - Category breakdown and explicit reporting of unavailable checks.
+- **Multi-Format Reporting**:
+  - Interactive Rich terminal report with styled tables and panels.
+  - Machine-readable JSON output conforming to documented schema.
+  - GitHub-Flavored Markdown report with Shields.io badges.
+- **Extensible Plugin System**:
+  - `BaseAnalyzer` standard interface.
+  - Dynamic discovery via Python entry points (`repoguard.plugins`).
+  - Example Docker security plugin in `examples/custom_plugin/`.
+- **CI/CD Integration**:
+  - Reusable composite GitHub Action (`action.yml`).
+  - Automated step summary, PR annotations, and report artifact uploads.
+- **CLI Commands**:
+  - `repoguard scan [PATH]`
+  - `repoguard version`
+  - `repoguard config init`
+  - `repoguard plugins list` & `repoguard plugins info`

repoguard_tool-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,55 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project team at security@repoguard.dev. All complaints will be
+reviewed and investigated promptly and fairly.

repoguard_tool-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing to RepoGuard
+
+Thank you for your interest in contributing to RepoGuard! 
+
+---
+
+## Code of Conduct
+
+All contributors and participants agree to follow our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+---
+
+## Development Setup
+
+1. Fork and clone the repository:
+   ```bash
+   git clone https://github.com/<your-username>/repoguard.git
+   cd repoguard
+   ```
+
+2. Create and activate a virtual environment (Python 3.11+):
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate
+   ```
+
+3. Install RepoGuard and development dependencies in editable mode:
+   ```bash
+   pip install -e ".[dev]"
+   pip install -e examples/custom_plugin
+   ```
+
+---
+
+## Running Quality Checks
+
+Before submitting a pull request, ensure tests and linting pass cleanly:
+
+```bash
+# Run automated tests
+pytest -v
+
+# Run Ruff linter and formatter
+ruff check .
+ruff format --check .
+```
+
+---
+
+## Pull Request Guidelines
+
+1. Create a descriptive feature branch (`git checkout -b feature/my-new-analyzer`).
+2. Include comprehensive unit tests for any new features or bug fixes.
+3. Keep commits atomic and use conventional commit messages (e.g., `feat:`, `fix:`, `docs:`).
+4. Update relevant documentation in `docs/` or `README.md`.

repoguard_tool-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RepoGuard Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

repoguard_tool-0.1.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.5
+Name: repoguard-tool
+Version: 0.1.0
+Summary: Analyze. Detect. Improve. Open-Source Repository Health Analyzer
+Author: RepoGuard Contributors
+License: MIT
+License-File: LICENSE
+Keywords: code-health,developer-tooling,github-actions,repository-analyzer,security-scanner
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: gitpython>=3.1.40
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: requests>=2.31.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 🛡️ RepoGuard
+
+> **Analyze. Detect. Improve.**
+
+RepoGuard is an extensible, open-source repository health analyzer built for software engineers, open-source maintainers, and CI/CD pipelines.
+
+RepoGuard scans codebases to evaluate documentation completeness, dependency security and freshness, exposed secrets, code maintainability, test coverage indicators, and CI/CD workflow security — calculating a transparent, deterministic health score from 0 to 100 with actionable remediation guidance.
+
+[![CI](https://github.com/repoguard/repoguard/actions/workflows/ci.yml/badge.svg)](https://github.com/repoguard/repoguard/actions/workflows/ci.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+
+---
+
+## Key Features
+
+- 🔍 **Comprehensive Static Analysis**: 6 independent built-in analyzers covering Documentation, Dependencies, Security, Testing, Code Quality, and CI/CD.
+- 🔒 **Security Invariants**: Never executes repository code; masks all detected secrets; prevents path traversal; supports offline scanning (`--no-network`).
+- 📊 **Transparent Health Scoring Engine**: 0–100 health score with letter grades (`A`–`F`), category breakdown, and zero double-counting.
+- 🔌 **Extensible Plugin Architecture**: Build independent custom analyzers using Python entry points (`repoguard.plugins`). Plugin crashes are isolated without stopping scans.
+- 🤖 **GitHub Actions Integration**: Native reusable GitHub Action (`action.yml`) with Step Summary tables, PR annotations, and report artifact uploads.
+- 📄 **Multi-Format Reporting**: Interactive Rich terminal reports, machine-readable JSON schemas, and GitHub-Flavored Markdown.
+
+---
+
+## Built-in Analyzers
+
+| Category | Analyzer | What it Checks |
+|---|---|---|
+| **Documentation** | `documentation` | README presence, installation/usage instructions, LICENSE, CONTRIBUTING |
+| **Dependencies** | `dependencies` | Unpinned versions, OSV API CVE/GHSA scanning, registry version checks |
+| **Security** | `security` | AWS keys, GitHub tokens, Slack webhooks, private keys, `shell=True`, `eval()`, committed `.env` files |
+| **Testing** | `testing` | Test directories, testing frameworks, CI automated test execution |
+| **Code Quality** | `code_quality` | AST cyclomatic complexity, function length, parameter counts, wildcard imports |
+| **CI/CD** | `cicd` | GitHub workflow presence, `permissions: write-all` auditing, mutable branch pinning (`@main`) |
+
+---
+
+## Installation
+
+Requires **Python 3.11+**.
+
+```bash
+pip install repoguard-tool
+```
+
+Or using `pipx` for isolated CLI execution:
+
+```bash
+pipx install repoguard-tool
+```
+
+---
+
+## Quick Start
+
+### 1. Scan a Repository
+
+```bash
+# Interactive terminal scan
+repoguard scan .
+
+# Generate JSON report
+repoguard scan . --format json
+
+# Generate Markdown report
+repoguard scan . --format markdown --output report.md
+
+# Offline scan (no external network lookups)
+repoguard scan . --no-network
+
+# Enforce quality gates (exit with code 1 if thresholds exceeded)
+repoguard scan . --min-score 75 --fail-on high
+```
+
+### 2. Inspect Installed Plugins
+
+```bash
+repoguard plugins list
+repoguard plugins info docker
+```
+
+### 3. Initialize Configuration File
+
+```bash
+repoguard config init
+```
+
+This generates a `.repoguard.yml` file with default scoring weights and thresholds.
+
+---
+
+## Health Scoring Methodology
+
+RepoGuard calculates a deterministic score from 0 to 100 based on configured category weights:
+
+- **Security**: 25%
+- **Code Quality**: 25%
+- **Documentation**: 15%
+- **Dependencies**: 15%
+- **Testing**: 10%
+- **CI/CD**: 10%
+
+Each category begins at **100 points**. Penalties are deducted based on unique finding severities:
+- **Critical**: -25 pts
+- **High**: -15 pts
+- **Medium**: -8 pts
+- **Low**: -3 pts
+- **Info**: 0 pts
+
+Scores are clamped to `[0, 100]` and mapped to grades (`A`: >=90, `B`: 80–89, `C`: 70–79, `D`: 60–69, `F`: <60).
+
+> **Disclaimer**: The RepoGuard Health Score is an automated project-maintenance indicator. It is **NOT** a guarantee or warranty of security.
+
+---
+
+## GitHub Actions CI/CD Integration
+
+Add RepoGuard to your GitHub repository by creating `.github/workflows/repoguard.yml`:
+
+```yaml
+name: RepoGuard Health Scan
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: repoguard/repoguard@v1
+        with:
+          min-score: "70"
+          fail-on: "high"
+```
+
+---
+
+## Documentation
+
+- [Installation Guide](docs/installation.md)
+- [Architecture & Design](docs/architecture.md)
+- [Analyzers Reference](docs/analyzers.md)
+- [Plugin Development Guide](docs/plugins.md)
+- [GitHub Actions Integration](docs/github-actions.md)
+- [Configuration Reference](docs/configuration.md)
+- [Health Scoring Engine](docs/scoring.md)
+- [Example Plugin](examples/custom_plugin/README.md)
+
+---
+
+## Contributing
+
+Contributions are warmly welcomed! Please read our [Contributing Guidelines](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md).
+
+---
+
+## License
+
+RepoGuard is licensed under the [MIT License](LICENSE).