good-egg 0.1.0__tar.gz

good_egg-0.1.0/.claude/agents.md

@@ -0,0 +1 @@
+../CLAUDE.md

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

@@ -0,0 +1,36 @@
+---
+name: Bug Report
+about: Report a bug in Good Egg
+labels: bug
+---
+
+## Describe the bug
+
+A clear description of what the bug is.
+
+## To Reproduce
+
+Steps to reproduce the behavior:
+
+1. ...
+2. ...
+
+## Expected behavior
+
+What you expected to happen.
+
+## Environment
+
+- Good Egg version: (e.g. v0.1.0 or commit SHA)
+- Python version:
+- OS:
+
+## Logs / Error Output
+
+```
+Paste relevant logs here
+```
+
+## Additional context
+
+Any other context about the problem.

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

@@ -0,0 +1,21 @@
+---
+name: Feature Request
+about: Suggest a feature for Good Egg
+labels: enhancement
+---
+
+## Problem
+
+What problem does this solve? What use case does it address?
+
+## Proposed Solution
+
+Describe what you'd like to happen.
+
+## Alternatives Considered
+
+Any alternative solutions or features you've considered.
+
+## Additional Context
+
+Any other context, screenshots, or examples.

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

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint
+        run: uv run ruff check src/ tests/ scripts/
+
+      - name: Type check
+        run: uv run mypy src/good_egg/
+
+      - name: Test
+        run: uv run pytest --cov=good_egg -v

good_egg-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,74 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint
+        run: uv run ruff check src/ tests/ scripts/
+
+      - name: Test
+        run: uv run pytest --cov=good_egg -v
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+
+      - name: Update major version tag
+        run: |
+          TAG=${GITHUB_REF#refs/tags/}
+          MAJOR=${TAG%%.*}
+          git tag -f "$MAJOR" "$TAG"
+          git push origin "$MAJOR" --force

good_egg-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+*.db
+*.sqlite
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage

good_egg-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

good_egg-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project 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-02-10
+
+### Added
+
+- GitHub Action for automated PR author trust scoring.
+- CLI tool (`good-egg score`) for scoring contributors from the command line.
+- Python library API for programmatic trust scoring.
+- MCP server for AI assistant integration (optional `mcp` extra).
+- Graph-based trust scoring engine built on weighted contribution graphs.
+- Bipartite graph construction from merged PRs, reviews, and repository metadata.
+- Configurable trust level thresholds (HIGH, MEDIUM, LOW).
+- Recency decay so recent contributions count more than old ones.
+- Language ecosystem normalization for fair cross-language comparison.
+- SQLite-backed response cache with configurable TTLs.
+- YAML configuration with environment variable overrides.
+- Multiple output formatters: Markdown, CLI table, JSON, and GitHub check-run.
+
+[0.1.0]: https://github.com/2ndSetAI/good-egg/releases/tag/v0.1.0

good_egg-0.1.0/CLAUDE.md

@@ -0,0 +1,86 @@
+# Good Egg -- Project Instructions
+
+## Overview
+
+Good Egg is a trust scoring tool for GitHub PR authors. It builds a weighted contribution graph from a user's merged PRs and computes a personalised trust score to assess how established a contributor is relative to a given project. It runs as a GitHub Action, a CLI, a Python library, and an MCP server.
+
+## Tech Stack
+
+- **Language**: Python 3.12+
+- **Package manager**: uv
+- **Framework**: Pydantic for config/models, Click for CLI, httpx for async HTTP, NetworkX for graph scoring
+- **Testing**: pytest (with pytest-asyncio, respx for HTTP mocking, pytest-cov)
+- **Linting**: ruff
+- **Type checking**: mypy (strict)
+
+## Project Structure
+
+```
+src/good_egg/       # Main package
+  config.py         # Pydantic config models, YAML + env var loading
+  models.py         # Data models (UserProfile, MergedPR, TrustScore, etc.)
+  github_client.py  # Async GitHub GraphQL/REST client with retry
+  graph_builder.py  # Bipartite trust graph construction
+  scorer.py         # Graph-based trust scoring engine
+  formatter.py      # Output formatters (Markdown, CLI, JSON, check-run)
+  action.py         # GitHub Action entry point
+  cli.py            # Click CLI
+  mcp_server.py     # MCP server for AI assistant integration
+  cache.py          # SQLite-backed response cache
+  exceptions.py     # Custom exception hierarchy
+tests/              # pytest test suite (mirrors src/ structure)
+scripts/            # Utility scripts (validation, language multiplier generation)
+docs/               # Documentation (library, action, MCP, config reference)
+examples/           # Example workflows, config files, library usage
+```
+
+## Commands
+
+### Development
+
+```bash
+uv run pytest --cov=good_egg -v     # Run tests with coverage
+uv run ruff check src/ tests/ scripts/  # Lint
+uv run mypy src/good_egg/           # Type check
+uv run ruff check --fix src/ tests/ scripts/  # Auto-fix lint issues
+```
+
+### Running
+
+```bash
+good-egg score <username> --repo <owner/repo>   # Score a user
+good-egg cache-stats                             # Cache statistics
+good-egg cache-clear                             # Clear cache
+good-egg-mcp                                    # Start MCP server
+```
+
+### Installation
+
+```bash
+pip install good-egg          # Core package
+pip install good-egg[mcp]     # With MCP server support
+```
+
+## Code Conventions
+
+- Use `from __future__ import annotations` in every module.
+- Type annotations required on all function signatures.
+- Line length: 99 characters (enforced by ruff).
+- Ruff rule set: E, F, I, N, W, UP, B, A, SIM.
+- Tests go in `tests/` with `test_` prefix matching the source module.
+- Prefer editing existing files over creating new ones.
+- Keep changes minimal and focused -- don't refactor surrounding code unless asked.
+
+## Configuration
+
+- Config class is `GoodEggConfig` in `config.py`, composed of sub-configs: `GraphScoringConfig`, `EdgeWeightConfig`, `RecencyConfig`, `ThresholdConfig`, `CacheTTLConfig`, `LanguageNormalization`, `FetchConfig`.
+- YAML config key for scoring parameters is `graph_scoring` (not "pagerank").
+- Environment variable overrides use `GOOD_EGG_` prefix.
+- The `[mcp]` optional extra adds the `mcp` dependency for the MCP server.
+
+## Important Rules
+
+- **No AI attribution**: Do not add `Co-Authored-By`, `Signed-off-by`, or any other trailer attributing AI/Claude to commits. Do not sign PR descriptions, comments, or code comments as Claude or any AI assistant. Commits should be attributed solely to the human author.
+- **No "PageRank" branding**: The project uses NetworkX's `nx.pagerank()` internally, but all user-facing names, docs, config keys, and class names use "graph scoring" instead. Do not introduce "PageRank" into any user-facing surface.
+- **Test before committing**: Always run `uv run pytest --cov=good_egg -v` and `uv run ruff check src/ tests/ scripts/` before considering work complete.
+- **Coverage threshold**: Maintain >= 90% test coverage.

good_egg-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing to Good Egg
+
+## Setup
+
+```bash
+# Clone
+git clone https://github.com/2ndSetAI/good-egg.git
+cd good-egg
+
+# Install uv (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install dependencies
+uv sync
+```
+
+## Project Structure
+
+```
+good-egg/
+├── src/good_egg/
+│   ├── action.py         # GitHub Action entry point
+│   ├── cache.py          # SQLite-backed response cache
+│   ├── cli.py            # Click CLI (good-egg score, cache-stats, cache-clear)
+│   ├── config.py         # YAML + env var configuration
+│   ├── exceptions.py     # Custom exception hierarchy
+│   ├── formatter.py      # Markdown, CLI, JSON, check-run formatters
+│   ├── github_client.py  # Async GitHub GraphQL/REST client with retry
+│   ├── graph_builder.py  # Bipartite trust graph construction
+│   ├── mcp_server.py     # MCP server for AI assistant integration
+│   ├── models.py         # Pydantic data models
+│   └── scorer.py         # Graph-based trust scoring engine
+├── tests/                # pytest test suite
+├── scripts/
+│   └── validate_scoring.py  # Validation against real repos
+├── docs/                 # Documentation (library, action, MCP, config)
+├── examples/             # Example workflows and config files
+└── CHANGELOG.md          # Release history
+```
+
+## Development Workflow
+
+```bash
+# Run tests
+uv run pytest --cov=good_egg -v
+
+# Lint
+uv run ruff check src/ tests/ scripts/
+
+# Type check
+uv run mypy src/good_egg/
+
+# Format (auto-fix)
+uv run ruff check --fix src/ tests/ scripts/
+
+# Verify packaging
+uv build
+```
+
+## Code Style
+
+- Ruff enforces style (E, F, I, N, W, UP, B, A, SIM rules)
+- Line length: 99 characters
+- Type annotations required on all function signatures (mypy strict)
+- Use `from __future__ import annotations` in every module
+
+## Running the Validation Suite
+
+The validation script scores real PR authors from popular repos to check scoring methodology:
+
+```bash
+GITHUB_TOKEN=$(gh auth token) uv run python scripts/validate_scoring.py --sample-size 5
+```
+
+This requires `gh` CLI authenticated. Results are written to the `validation/` directory.
+
+## Pull Requests
+
+1. Create a feature branch from `main`
+2. Make your changes with tests
+3. Ensure `uv run pytest --cov=good_egg -v` passes with >= 90% coverage
+4. Ensure `uv run ruff check src/ tests/ scripts/` is clean
+5. Open a PR with a clear description

good_egg-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 2ndSetAI
+
+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.

good_egg-0.1.0/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: good-egg
+Version: 0.1.0
+Summary: Trust scoring for GitHub contributors using graph-based ranking on contribution graphs
+Project-URL: Homepage, https://github.com/2ndSetAI/good-egg
+Project-URL: Repository, https://github.com/2ndSetAI/good-egg
+Project-URL: Issues, https://github.com/2ndSetAI/good-egg/issues
+Author-email: Jeff Smith <jeff@2ndset.ai>
+License: MIT
+License-File: LICENSE
+Keywords: code-review,github,pull-request,security,trust
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: networkx>=3.2
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic>=2.5
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: scipy>=1.12
+Requires-Dist: tenacity>=8.2
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# Good Egg
+
+<img src="https://raw.githubusercontent.com/2ndSetAI/good-egg/main/assets/egg.jpg" alt="Good Egg" width="200">
+
+Trust scoring for GitHub PR authors using graph-based ranking on contribution
+graphs. Good Egg analyses a contributor's merged pull requests across the
+GitHub ecosystem, builds a weighted contribution graph, and computes a
+personalised trust score to surface how established a contributor is relative
+to your project.
+
+Good Egg runs as a **GitHub Action**, a **CLI tool**, a **Python library**,
+and an **MCP server** for AI assistant integration.
+
+## Installation
+
+```bash
+pip install good-egg
+```
+
+To use the MCP server for AI assistant integration:
+
+```bash
+pip install good-egg[mcp]
+```
+
+## GitHub Action
+
+Add Good Egg to any pull request workflow:
+
+```yaml
+name: Good Egg
+
+on:
+  pull_request:
+    types: [opened, reopened, synchronize]
+
+permissions:
+  pull-requests: write
+
+jobs:
+  score:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: 2ndSetAI/good-egg@v0
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+Add `checks: write` to permissions if you enable `check-run: true`.
+
+### Action Inputs
+
+| Input | Description | Default |
+|-------|-------------|---------|
+| `github-token` | GitHub token for API access | `${{ github.token }}` |
+| `config-path` | Path to `.good-egg.yml` config file | _(auto-detected)_ |
+| `comment` | Post a PR comment with the trust score | `true` |
+| `check-run` | Create a check run with the trust score | `false` |
+| `fail-on-low` | Fail the action if trust level is LOW | `false` |
+
+### Action Outputs
+
+| Output | Description |
+|--------|-------------|
+| `score` | Normalized trust score (0.0 - 1.0) |
+| `trust-level` | Trust level: HIGH, MEDIUM, LOW, UNKNOWN, or BOT |
+| `user` | GitHub username that was scored |
+
+See [docs/github-action.md](docs/github-action.md) for advanced usage,
+custom configuration, and using outputs in downstream steps.
+
+## CLI
+
+```bash
+# Score a PR author
+good-egg score <username> --repo <owner/repo>
+
+# With a GitHub token for higher rate limits
+GITHUB_TOKEN=ghp_... good-egg score octocat --repo octocat/Hello-World
+
+# JSON output
+good-egg score octocat --repo octocat/Hello-World --json
+
+# Verbose output with contribution details
+good-egg score octocat --repo octocat/Hello-World --verbose
+```
+
+### Additional Commands
+
+```bash
+good-egg cache-stats                 # Show cache statistics
+good-egg cache-clear                 # Remove expired cache entries
+good-egg cache-clear --category repo_metadata  # Clear specific category
+good-egg --version                   # Print version
+good-egg --help                      # Show help
+```
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Error (invalid input, API failure, missing token) |
+
+## Python Library
+
+```python
+import asyncio
+import os
+from good_egg import score_pr_author
+
+async def main() -> None:
+    result = await score_pr_author(
+        login="octocat",
+        repo_owner="octocat",
+        repo_name="Hello-World",
+        token=os.environ["GITHUB_TOKEN"],
+    )
+    print(f"Trust level: {result.trust_level}")
+    print(f"Score: {result.normalized_score:.2f}")
+
+asyncio.run(main())
+```
+
+See [docs/library.md](docs/library.md) for full API documentation, custom
+configuration, error handling, and cache usage.
+
+## MCP Server
+
+Good Egg includes an MCP (Model Context Protocol) server for integration
+with AI assistants like Claude.
+
+```bash
+pip install good-egg[mcp]
+GITHUB_TOKEN=ghp_... good-egg-mcp
+```
+
+Add to your Claude Desktop configuration (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "good-egg": {
+      "command": "good-egg-mcp",
+      "env": {
+        "GITHUB_TOKEN": "ghp_your_token_here"
+      }
+    }
+  }
+}
+```
+
+See [docs/mcp-server.md](docs/mcp-server.md) for tool reference and
+Claude Code configuration.
+
+## How It Works
+
+1. **Fetch** -- Retrieves the user's merged pull requests and the metadata
+   of repositories they have contributed to via the GitHub API.
+2. **Build Graph** -- Constructs a directed graph where nodes represent
+   users and repositories, and weighted edges encode contributions. Edge
+   weights account for recency (exponential decay) and ecosystem size
+   (language normalization).
+3. **Score** -- Runs personalised graph scoring seeded from the context
+   repository, so contributions to related projects carry more weight.
+4. **Classify** -- Normalizes the raw graph score to a 0-1 range and maps
+   it to a trust level.
+
+## Trust Levels
+
+| Level | Description |
+|-------|-------------|
+| **HIGH** | Established contributor with a strong cross-project track record |
+| **MEDIUM** | Some contribution history, but limited breadth or recency |
+| **LOW** | Little to no prior contribution history -- review manually |
+| **UNKNOWN** | Insufficient data to produce a meaningful score |
+| **BOT** | Detected bot account (e.g. dependabot, renovate) |
+
+## Configuration
+
+Create a `.good-egg.yml` in your repository root to customize thresholds,
+scoring parameters, and more:
+
+```yaml
+thresholds:
+  high_trust: 0.7
+  medium_trust: 0.3
+  new_account_days: 30
+
+graph_scoring:
+  alpha: 0.85
+
+recency:
+  half_life_days: 180
+```
+
+Environment variables with the `GOOD_EGG_` prefix can override individual
+settings. See [docs/configuration.md](docs/configuration.md) for the full
+reference, and [examples/.good-egg.yml](examples/.good-egg.yml) for a
+complete example config file with all defaults.
+
+## Troubleshooting
+
+### Rate Limits
+
+Good Egg retries automatically on GitHub API rate limits with exponential
+backoff. If you see persistent failures:
+
+- Use a GitHub App token instead of `GITHUB_TOKEN` for higher rate limits
+  (5000 req/hr vs 1000).
+- Reduce `fetch.max_prs` in your config to lower API usage per scored user.
+
+### Required Permissions
+
+| Permission | Required For |
+|-----------|-------------|
+| `pull-requests: write` | Posting PR comments |
+| `checks: write` | Creating check runs (when `check-run: true`) |
+
+### Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Rate limit exhausted` | Too many API calls | Wait for reset or use App token |
+| `User not found` | Deleted/renamed account | Action continues with UNKNOWN score |
+| `Could not extract PR number` | Not a PR event | Ensure workflow triggers on `pull_request` |
+| `Invalid GITHUB_REPOSITORY` | Malformed env var | Check Actions environment |
+
+## License
+
+MIT
+
+---
+
+Egg image CC BY 2.0 (Flickr: renwest)