Compare commits
1 Commits
fix/1445
...
burn/672-1
| Author | SHA1 | Date | |
|---|---|---|---|
|
b587e756e0 |
@@ -1,116 +0,0 @@
|
||||
# .gitea/workflows/check-pr-changes.yml
|
||||
# CI workflow to prevent rubber-stamping of PRs with no changes
|
||||
# Issue #1445: process: Prevent rubber-stamping of PRs with no changes
|
||||
|
||||
name: Check PR for Changes
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
types: [opened, synchronize, reopened]
|
||||
|
||||
jobs:
|
||||
check-changes:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout code
|
||||
uses: actions/checkout@v3
|
||||
with:
|
||||
fetch-depth: 0 # Fetch full history for diff comparison
|
||||
|
||||
- name: Check for empty PR
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
run: |
|
||||
# Get PR number from context
|
||||
PR_NUMBER="${{ github.event.pull_request.number }}"
|
||||
echo "Checking PR #$PR_NUMBER for changes..."
|
||||
|
||||
# Get the base and head commits
|
||||
BASE_SHA="${{ github.event.pull_request.base.sha }}"
|
||||
HEAD_SHA="${{ github.event.pull_request.head.sha }}"
|
||||
|
||||
echo "Base SHA: $BASE_SHA"
|
||||
echo "Head SHA: $HEAD_SHA"
|
||||
|
||||
# Get diff stats
|
||||
DIFF_STATS=$(git diff --stat "$BASE_SHA" "$HEAD_SHA")
|
||||
|
||||
if [ -z "$DIFF_STATS" ]; then
|
||||
echo "❌ ERROR: PR has no changes!"
|
||||
echo ""
|
||||
echo "This PR has 0 additions, 0 deletions, and 0 files changed."
|
||||
echo "This is a 'zombie PR' that should not be merged."
|
||||
echo ""
|
||||
echo "Rubber-stamping (approving PRs with no changes) is prohibited."
|
||||
echo "Reviewers must verify that PRs contain actual changes."
|
||||
echo ""
|
||||
echo "If this is a mistake, please add actual changes to the PR."
|
||||
echo "If this PR is not needed, please close it."
|
||||
exit 1
|
||||
else
|
||||
echo "✅ PR has changes:"
|
||||
echo "$DIFF_STATS"
|
||||
|
||||
# Get detailed stats
|
||||
ADDITIONS=$(git diff --numstat "$BASE_SHA" "$HEAD_SHA" | awk '{sum+=$1} END {print sum}')
|
||||
DELETIONS=$(git diff --numstat "$BASE_SHA" "$HEAD_SHA" | awk '{sum+=$2} END {print sum}')
|
||||
FILES_CHANGED=$(git diff --numstat "$BASE_SHA" "$HEAD_SHA" | wc -l)
|
||||
|
||||
echo ""
|
||||
echo "Summary:"
|
||||
echo " Files changed: $FILES_CHANGED"
|
||||
echo " Additions: $ADDITIONS"
|
||||
echo " Deletions: $DELETIONS"
|
||||
|
||||
# Check if this is a "zombie PR" (no actual changes)
|
||||
if [ "$ADDITIONS" -eq 0 ] && [ "$DELETIONS" -eq 0 ]; then
|
||||
echo ""
|
||||
echo "⚠️ WARNING: PR has files changed but no additions or deletions!"
|
||||
echo "This might be a binary file change or permission change."
|
||||
echo "Reviewers should verify this is intentional."
|
||||
fi
|
||||
fi
|
||||
|
||||
- name: Check for empty commits
|
||||
run: |
|
||||
# Check if there are any commits with no changes
|
||||
BASE_SHA="${{ github.event.pull_request.base.sha }}"
|
||||
HEAD_SHA="${{ github.event.pull_request.head.sha }}"
|
||||
|
||||
# Get list of commits
|
||||
COMMITS=$(git log --oneline "$BASE_SHA".."$HEAD_SHA")
|
||||
|
||||
if [ -z "$COMMITS" ]; then
|
||||
echo "❌ ERROR: PR has no commits!"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "Commits in this PR:"
|
||||
echo "$COMMITS"
|
||||
|
||||
# Check each commit for changes
|
||||
EMPTY_COMMITS=0
|
||||
while IFS= read -r commit; do
|
||||
COMMIT_SHA=$(echo "$commit" | awk '{print $1}')
|
||||
COMMIT_MSG=$(echo "$commit" | cut -d' ' -f2-)
|
||||
|
||||
# Get parent commit
|
||||
PARENT_SHA=$(git rev-parse "$COMMIT_SHA^" 2>/dev/null || echo "")
|
||||
|
||||
if [ -n "$PARENT_SHA" ]; then
|
||||
# Check if commit has changes
|
||||
COMMIT_DIFF=$(git diff --stat "$PARENT_SHA" "$COMMIT_SHA")
|
||||
|
||||
if [ -z "$COMMIT_DIFF" ]; then
|
||||
echo "⚠️ WARNING: Commit $COMMIT_SHA has no changes!"
|
||||
echo " Message: $COMMIT_MSG"
|
||||
EMPTY_COMMITS=$((EMPTY_COMMITS + 1))
|
||||
fi
|
||||
fi
|
||||
done <<< "$COMMITS"
|
||||
|
||||
if [ "$EMPTY_COMMITS" -gt 0 ]; then
|
||||
echo ""
|
||||
echo "⚠️ Found $EMPTY_COMMITS commit(s) with no changes."
|
||||
echo "Consider squashing or amending these commits."
|
||||
fi
|
||||
136
.github/pull_request_template.md
vendored
136
.github/pull_request_template.md
vendored
@@ -1,73 +1,65 @@
|
||||
## Description
|
||||
<!-- Provide a clear description of what this PR does -->
|
||||
|
||||
## Changes Made
|
||||
<!-- List the specific changes made in this PR -->
|
||||
|
||||
### Files Changed
|
||||
<!-- List the files that were modified -->
|
||||
|
||||
### Type of Change
|
||||
<!-- Check the relevant option -->
|
||||
- [ ] Bug fix (non-breaking change which fixes an issue)
|
||||
- [ ] New feature (non-breaking change which adds functionality)
|
||||
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
|
||||
- [ ] Documentation update
|
||||
- [ ] Refactoring (no functional changes)
|
||||
- [ ] Test updates
|
||||
- [ ] CI/CD changes
|
||||
|
||||
## Testing
|
||||
<!-- Describe the tests you ran to verify your changes -->
|
||||
|
||||
### Test Instructions
|
||||
<!-- Provide step-by-step instructions to test your changes -->
|
||||
|
||||
## Checklist
|
||||
<!-- Check all that apply -->
|
||||
- [ ] My code follows the style guidelines of this project
|
||||
- [ ] I have performed a self-review of my own code
|
||||
- [ ] I have commented my code, particularly in hard-to-understand areas
|
||||
- [ ] I have made corresponding changes to the documentation
|
||||
- [ ] My changes generate no new warnings
|
||||
- [ ] 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
|
||||
- [ ] Any dependent changes have been merged and published in downstream modules
|
||||
|
||||
## Reviewer Guidelines
|
||||
<!-- IMPORTANT: Reviewers must follow these guidelines to prevent rubber-stamping -->
|
||||
|
||||
### ⚠️ Reviewers MUST verify:
|
||||
1. **PR has actual changes** - Check that the PR contains additions, deletions, or modifications
|
||||
2. **Changes match description** - Verify the changes match what's described in the PR
|
||||
3. **Code quality** - Review code for bugs, security issues, performance problems
|
||||
4. **Tests are adequate** - Ensure new code is properly tested
|
||||
5. **Documentation is updated** - Check if documentation needs updates
|
||||
|
||||
### ❌ DO NOT approve if:
|
||||
- PR has 0 additions, 0 deletions, and 0 files changed (zombie PR)
|
||||
- Changes don't match the PR description
|
||||
- Code has obvious bugs or security issues
|
||||
- No tests for new functionality
|
||||
- Documentation is missing or incorrect
|
||||
|
||||
### ✅ DO approve if:
|
||||
- PR has meaningful changes that match the description
|
||||
- Code is clean, well-tested, and documented
|
||||
- Changes follow project conventions
|
||||
- No obvious issues or risks
|
||||
|
||||
## Related Issues
|
||||
<!-- Link any related issues -->
|
||||
- Fixes #<!-- issue number -->
|
||||
- Related to #<!-- issue number -->
|
||||
|
||||
## Additional Notes
|
||||
<!-- Add any other context about the PR here -->
|
||||
|
||||
---
|
||||
**By submitting this PR, I confirm that:**
|
||||
1. I have actually reviewed the code changes
|
||||
2. The changes are meaningful and not a zombie PR
|
||||
3. I have tested the changes locally (if applicable)
|
||||
4. I understand that rubber-stamping (approving PRs with no changes) is prohibited
|
||||
|
||||
**⚠️ Before submitting your pull request:**
|
||||
|
||||
1. [x] I've read [BRANCH_PROTECTION.md](BRANCH_PROTECTION.md)
|
||||
2. [x] I've followed [CONTRIBUTING.md](CONTRIBUTING.md) guidelines
|
||||
3. [x] My changes have appropriate test coverage
|
||||
4. [x] I've updated documentation where needed
|
||||
5. [x] I've verified CI passes (where applicable)
|
||||
|
||||
**Context:**
|
||||
<Describe your changes and why they're needed>
|
||||
|
||||
**Testing:**
|
||||
<Explain how this was tested>
|
||||
|
||||
**Questions for reviewers:**
|
||||
<Ask specific questions if needed>
|
||||
## Pull Request Template
|
||||
|
||||
### Description
|
||||
[Explain your changes briefly]
|
||||
|
||||
### Checklist
|
||||
- [ ] Branch protection rules followed
|
||||
- [ ] Required reviewers: @perplexity (QA), @Timmy (hermes-agent)
|
||||
- [ ] CI passed (where applicable)
|
||||
|
||||
### Questions for Reviewers
|
||||
- [ ] Any special considerations?
|
||||
- [ ] Does this require additional documentation?
|
||||
# Pull Request Template
|
||||
|
||||
## Summary
|
||||
Briefly describe the changes in this PR.
|
||||
|
||||
## Reviewers
|
||||
- Default reviewer: @perplexity
|
||||
- Required reviewer for hermes-agent: @Timmy
|
||||
|
||||
## Branch Protection Compliance
|
||||
- [ ] PR created
|
||||
- [ ] 1+ approvals
|
||||
- [ ] ci passed (where applicable)
|
||||
- [ ] No force pushes
|
||||
- [ ] No branch deletions
|
||||
|
||||
## Specialized Owners
|
||||
- [ ] @Rockachopa (for agent-core)
|
||||
- [ ] @Timmy (for ai/)
|
||||
## Pull Request Template
|
||||
|
||||
### Summary
|
||||
- [ ] Describe the change
|
||||
- [ ] Link to related issue (e.g. `Closes #123`)
|
||||
|
||||
### Checklist
|
||||
- [ ] Branch protection rules respected
|
||||
- [ ] CI/CD passing (where applicable)
|
||||
- [ ] Code reviewed by @perplexity
|
||||
- [ ] No force pushes to main
|
||||
|
||||
### Review Requirements
|
||||
- [ ] @perplexity for all repos
|
||||
- [ ] @Timmy for hermes-agent changes
|
||||
|
||||
262
GENOME.md
Normal file
262
GENOME.md
Normal file
@@ -0,0 +1,262 @@
|
||||
# GENOME.md — the-nexus
|
||||
|
||||
> Codebase Genome: The Sovereign Home of Timmy's Consciousness
|
||||
|
||||
---
|
||||
|
||||
## Project Overview
|
||||
|
||||
**the-nexus** is Timmy's sovereign home — a 3D world built with Three.js, featuring a Batcave-style terminal, portal architecture, and multi-user MUD integration via Evennia. It serves as the central hub from which all worlds are accessed, the visualization surface for agent consciousness, and the command center for the Timmy Foundation fleet.
|
||||
|
||||
**Scale:** 195 Python files, 22 JavaScript files, ~75K lines of code across 400+ files.
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Frontend Layer"
|
||||
IDX[index.html]
|
||||
BOOT[boot.js]
|
||||
COMP[nexus/components/*]
|
||||
PLAY[playground/playground.html]
|
||||
end
|
||||
|
||||
subgraph "Backend Layer"
|
||||
SRV[server.py<br/>WebSocket Gateway :8765]
|
||||
BRIDGE[multi_user_bridge.py<br/>Evennia MUD Bridge]
|
||||
LLAMA[nexus/llama_provider.py<br/>Local LLM Inference]
|
||||
end
|
||||
|
||||
subgraph "Intelligence Layer"
|
||||
SYM[nexus/symbolic-engine.js<br/>Symbolic Reasoning]
|
||||
THINK[nexus/nexus_think.py<br/>Consciousness Loop]
|
||||
PERCEP[nexus/perception_adapter.py<br/>Perception Buffer]
|
||||
TRAJ[nexus/trajectory_logger.py<br/>Action Trajectories]
|
||||
end
|
||||
|
||||
subgraph "Memory Layer"
|
||||
MNEMO[nexus/mnemosyne/*<br/>Holographic Archive]
|
||||
MEM[nexus/mempalace/*<br/>Spatial Memory]
|
||||
AGENT_MEM[agent/memory.py<br/>Cross-Session Memory]
|
||||
EXP[nexus/experience_store.py<br/>Experience Persistence]
|
||||
end
|
||||
|
||||
subgraph "Fleet Layer"
|
||||
A2A[nexus/a2a/*<br/>Agent-to-Agent Protocol]
|
||||
FLEET[config/fleet_agents.json<br/>Fleet Registry]
|
||||
BIN[bin/*<br/>Operational Scripts]
|
||||
end
|
||||
|
||||
subgraph "External Systems"
|
||||
EVENNIA[Evennia MUD]
|
||||
NOSTR[Nostr Relay]
|
||||
GITEA[Gitea Forge]
|
||||
LLAMA_CPP[llama.cpp Server]
|
||||
end
|
||||
|
||||
IDX --> SRV
|
||||
SRV --> THINK
|
||||
SRV --> BRIDGE
|
||||
BRIDGE --> EVENNIA
|
||||
THINK --> SYM
|
||||
THINK --> PERCEP
|
||||
THINK --> TRAJ
|
||||
THINK --> LLAMA
|
||||
LLAMA --> LLAMA_CPP
|
||||
SYM --> MNEMO
|
||||
THINK --> MNEMO
|
||||
THINK --> MEM
|
||||
THINK --> EXP
|
||||
AGENT_MEM --> MEM
|
||||
A2A --> GITEA
|
||||
THINK --> NOSTR
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Entry Points
|
||||
|
||||
| Entry Point | Type | Purpose |
|
||||
|-------------|------|---------|
|
||||
| `index.html` | Browser | Main 3D world (Three.js) |
|
||||
| `server.py` | Python | WebSocket gateway on :8765 |
|
||||
| `boot.js` | Browser | Module loader, file protocol guard |
|
||||
| `multi_user_bridge.py` | Python | Evennia MUD ↔ AI agent bridge |
|
||||
| `nexus/a2a/server.py` | Python | A2A JSON-RPC server |
|
||||
| `nexus/mnemosyne/cli.py` | CLI | Archive management |
|
||||
| `bin/nexus_watchdog.py` | Script | Health monitoring |
|
||||
| `scripts/smoke.mjs` | Script | Smoke tests |
|
||||
|
||||
---
|
||||
|
||||
## Data Flow
|
||||
|
||||
```
|
||||
User (Browser)
|
||||
│
|
||||
▼
|
||||
index.html (Three.js 3D world)
|
||||
│
|
||||
├── WebSocket ──► server.py :8765
|
||||
│ │
|
||||
│ ├──► nexus_think.py (consciousness loop)
|
||||
│ │ ├── perception_adapter.py (parse events)
|
||||
│ │ ├── symbolic-engine.js (reasoning)
|
||||
│ │ ├── llama_provider.py (inference)
|
||||
│ │ ├── trajectory_logger.py (action log)
|
||||
│ │ └── experience_store.py (persistence)
|
||||
│ │
|
||||
│ └──► evennia_ws_bridge.py
|
||||
│ └──► Evennia MUD (telnet :4000)
|
||||
│
|
||||
├── Three.js Scene ──► nexus/components/*
|
||||
│ ├── memory-particles.js (memory viz)
|
||||
│ ├── portal-status-wall.html (portals)
|
||||
│ ├── fleet-health-dashboard.html
|
||||
│ └── session-rooms.js (spatial rooms)
|
||||
│
|
||||
└── Playground ──► playground/playground.html (creative mode)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Abstractions
|
||||
|
||||
### SymbolicEngine (`nexus/symbolic-engine.js`)
|
||||
Bitmask-based symbolic reasoning engine. Facts are stored as boolean flags, rules fire when patterns match. Used for world state reasoning without LLM overhead.
|
||||
|
||||
### NexusMind (`nexus/nexus_think.py`)
|
||||
The consciousness loop. Receives perceptions, invokes reasoning, produces actions. The bridge between the 3D world and the AI agent.
|
||||
|
||||
### PerceptionBuffer (`nexus/perception_adapter.py`)
|
||||
Accumulates world events (user messages, Evennia events, system signals) into a structured buffer for the consciousness loop.
|
||||
|
||||
### MemPalace (`nexus/mempalace/`, `mempalace/`)
|
||||
Spatial memory system. Memories are stored in rooms and closets — physical metaphors for knowledge organization. Supports fleet-wide shared memory wings.
|
||||
|
||||
### Mnemosyne (`nexus/mnemosyne/`)
|
||||
Holographic archive. Ingests documents, extracts meaning, builds a graph of linked concepts. The long-term memory layer.
|
||||
|
||||
### Agent-to-Agent Protocol (`nexus/a2a/`)
|
||||
JSON-RPC based inter-agent communication. Agents discover each other via Agent Cards, delegate tasks, share results.
|
||||
|
||||
### Multi-User Bridge (`multi_user_bridge.py`)
|
||||
121K-line Evennia MUD bridge. Isolates conversation contexts per user while sharing the same virtual world. Each user gets their own AIAgent instance.
|
||||
|
||||
---
|
||||
|
||||
## API Surface
|
||||
|
||||
### WebSocket API (server.py :8765)
|
||||
```
|
||||
ws://localhost:8765
|
||||
send: {"type": "perception", "data": {...}}
|
||||
recv: {"type": "action", "data": {...}}
|
||||
recv: {"type": "heartbeat", "data": {...}}
|
||||
```
|
||||
|
||||
### A2A JSON-RPC (nexus/a2a/server.py)
|
||||
```
|
||||
POST /a2a/v1
|
||||
{"jsonrpc": "2.0", "method": "SendMessage", "params": {...}}
|
||||
|
||||
GET /.well-known/agent-card.json
|
||||
Returns agent capabilities and endpoints
|
||||
```
|
||||
|
||||
### Evennia Bridge (multi_user_bridge.py)
|
||||
```
|
||||
telnet://localhost:4000
|
||||
Evennia MUD commands → AI responses
|
||||
Each user isolated via session ID
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Files
|
||||
|
||||
| File | Lines | Purpose |
|
||||
|------|-------|---------|
|
||||
| `multi_user_bridge.py` | 121K | Evennia MUD bridge (largest file) |
|
||||
| `index.html` | 21K | Main 3D world |
|
||||
| `nexus/symbolic-engine.js` | 12K | Symbolic reasoning |
|
||||
| `nexus/evennia_ws_bridge.py` | 14K | Evennia ↔ WebSocket |
|
||||
| `nexus/a2a/server.py` | 12K | A2A server |
|
||||
| `agent/memory.py` | 12K | Cross-session memory |
|
||||
| `server.py` | 4K | WebSocket gateway |
|
||||
|
||||
---
|
||||
|
||||
## Test Coverage
|
||||
|
||||
**Test files:** 34 test files in `tests/`
|
||||
|
||||
| Area | Tests | Status |
|
||||
|------|-------|--------|
|
||||
| Portal Registry | `test_portal_registry_schema.py` | ✅ |
|
||||
| MemPalace | `test_mempalace_*.py` (4 files) | ✅ |
|
||||
| Nexus Watchdog | `test_nexus_watchdog.py` | ✅ |
|
||||
| A2A | `test_a2a.py` | ✅ |
|
||||
| Fleet Audit | `test_fleet_audit.py` | ✅ |
|
||||
| Provenance | `test_provenance.py` | ✅ |
|
||||
| Boot | `boot.test.js` | ✅ |
|
||||
|
||||
### Coverage Gaps
|
||||
|
||||
- **No tests for `multi_user_bridge.py`** (121K lines, zero test coverage)
|
||||
- **No tests for `server.py` WebSocket gateway**
|
||||
- **No tests for `nexus/symbolic-engine.js`** (only `symbolic-engine.test.js` stub)
|
||||
- **No integration tests for Evennia ↔ Bridge ↔ AI flow**
|
||||
- **No load tests for WebSocket connections**
|
||||
- **No tests for Nostr publisher**
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **WebSocket gateway** runs on `0.0.0.0:8765` — accessible from network. Needs auth or firewall.
|
||||
2. **No authentication** on WebSocket or A2A endpoints in current code.
|
||||
3. **Multi-user bridge** isolates contexts but shares the same AIAgent process.
|
||||
4. **Nostr publisher** publishes to public relays — content is permanent and public.
|
||||
5. **Fleet scripts** in `bin/` have broad filesystem access.
|
||||
6. **Systemd services** (`systemd/llama-server.service`) run as root.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Python:** websockets, pytest, pyyaml, edge-tts, requests, playwright
|
||||
- **JavaScript:** Three.js (CDN), Monaco Editor (CDN)
|
||||
- **External:** Evennia MUD, llama.cpp, Nostr relay, Gitea
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
| Config | File | Purpose |
|
||||
|--------|------|---------|
|
||||
| Fleet agents | `config/fleet_agents.json` | Agent registry for A2A |
|
||||
| MemPalace | `nexus/mempalace/config.py` | Memory paths and settings |
|
||||
| DeepDive | `config/deepdive_sources.yaml` | Research sources |
|
||||
| MCP | `mcp_config.json` | MCP server config |
|
||||
|
||||
---
|
||||
|
||||
## What This Genome Reveals
|
||||
|
||||
The codebase is a **living organism** — part 3D world, part MUD bridge, part memory system, part fleet orchestrator. The `multi_user_bridge.py` alone is 121K lines — larger than most entire projects.
|
||||
|
||||
**Critical findings:**
|
||||
1. The 121K-line bridge has zero test coverage
|
||||
2. WebSocket gateway exposes on 0.0.0.0 without auth
|
||||
3. No load testing infrastructure exists
|
||||
4. Symbolic engine test is a stub
|
||||
5. Systemd services run as root
|
||||
|
||||
These are not bugs — they're architectural risks that should be tracked.
|
||||
|
||||
---
|
||||
|
||||
*Generated by Codebase Genome Pipeline — Issue #672*
|
||||
@@ -1,193 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Check for zombie PRs (PRs with no changes) to prevent rubber-stamping.
|
||||
Issue #1445: process: Prevent rubber-stamping of PRs with no changes
|
||||
"""
|
||||
|
||||
import json
|
||||
import os
|
||||
import sys
|
||||
import urllib.request
|
||||
import subprocess
|
||||
from typing import Dict, List, Any, Optional
|
||||
|
||||
# Configuration
|
||||
GITEA_BASE = "https://forge.alexanderwhitestone.com/api/v1"
|
||||
TOKEN_PATH = os.path.expanduser("~/.config/gitea/token")
|
||||
ORG = "Timmy_Foundation"
|
||||
|
||||
class ZombiePRChecker:
|
||||
def __init__(self):
|
||||
self.token = self._load_token()
|
||||
|
||||
def _load_token(self) -> str:
|
||||
"""Load Gitea API token."""
|
||||
try:
|
||||
with open(TOKEN_PATH, "r") as f:
|
||||
return f.read().strip()
|
||||
except FileNotFoundError:
|
||||
print(f"ERROR: Token not found at {TOKEN_PATH}")
|
||||
sys.exit(1)
|
||||
|
||||
def _api_request(self, endpoint: str) -> Any:
|
||||
"""Make authenticated Gitea API request."""
|
||||
url = f"{GITEA_BASE}{endpoint}"
|
||||
headers = {"Authorization": f"token {self.token}"}
|
||||
|
||||
req = urllib.request.Request(url, headers=headers)
|
||||
|
||||
try:
|
||||
with urllib.request.urlopen(req) as resp:
|
||||
return json.loads(resp.read())
|
||||
except urllib.error.HTTPError as e:
|
||||
if e.code == 404:
|
||||
return None
|
||||
error_body = e.read().decode() if e.fp else "No error body"
|
||||
print(f"API Error {e.code}: {error_body}")
|
||||
return None
|
||||
|
||||
def get_open_prs(self, repo: str) -> List[Dict]:
|
||||
"""Get open PRs for a repository."""
|
||||
endpoint = f"/repos/{ORG}/{repo}/pulls?state=open"
|
||||
prs = self._api_request(endpoint)
|
||||
return prs if isinstance(prs, list) else []
|
||||
|
||||
def get_pr_files(self, repo: str, pr_number: int) -> List[Dict]:
|
||||
"""Get files changed in a PR."""
|
||||
endpoint = f"/repos/{ORG}/{repo}/pulls/{pr_number}/files"
|
||||
files = self._api_request(endpoint)
|
||||
return files if isinstance(files, list) else []
|
||||
|
||||
def is_zombie_pr(self, repo: str, pr_number: int) -> Dict[str, Any]:
|
||||
"""Check if a PR is a zombie (no actual changes)."""
|
||||
pr_files = self.get_pr_files(repo, pr_number)
|
||||
|
||||
# Calculate total changes
|
||||
total_additions = sum(f.get("additions", 0) for f in pr_files)
|
||||
total_deletions = sum(f.get("deletions", 0) for f in pr_files)
|
||||
total_changes = sum(f.get("changes", 0) for f in pr_files)
|
||||
|
||||
# A zombie PR has no additions, deletions, or changes
|
||||
is_zombie = (total_additions == 0 and total_deletions == 0 and total_changes == 0)
|
||||
|
||||
return {
|
||||
"repo": repo,
|
||||
"pr_number": pr_number,
|
||||
"is_zombie": is_zombie,
|
||||
"files_changed": len(pr_files),
|
||||
"total_additions": total_additions,
|
||||
"total_deletions": total_deletions,
|
||||
"total_changes": total_changes,
|
||||
"files": pr_files
|
||||
}
|
||||
|
||||
def scan_repo_for_zombies(self, repo: str) -> List[Dict]:
|
||||
"""Scan a repository for zombie PRs."""
|
||||
open_prs = self.get_open_prs(repo)
|
||||
zombies = []
|
||||
|
||||
print(f"Scanning {repo} for zombie PRs...")
|
||||
print(f"Found {len(open_prs)} open PRs")
|
||||
|
||||
for pr in open_prs:
|
||||
pr_number = pr["number"]
|
||||
pr_title = pr["title"]
|
||||
|
||||
# Check if it's a zombie
|
||||
zombie_info = self.is_zombie_pr(repo, pr_number)
|
||||
|
||||
if zombie_info["is_zombie"]:
|
||||
zombie_info["title"] = pr_title
|
||||
zombie_info["author"] = pr["user"]["login"]
|
||||
zombie_info["created"] = pr["created_at"]
|
||||
zombies.append(zombie_info)
|
||||
print(f" 🧟 ZOMBIE: #{pr_number} - {pr_title}")
|
||||
else:
|
||||
print(f" ✅ OK: #{pr_number} - {pr_title} ({zombie_info['total_changes']} changes)")
|
||||
|
||||
return zombies
|
||||
|
||||
def generate_report(self, zombies_by_repo: Dict[str, List[Dict]]) -> str:
|
||||
"""Generate a report of zombie PRs found."""
|
||||
total_zombies = sum(len(zombies) for zombies in zombies_by_repo.values())
|
||||
|
||||
report = "# Zombie PR Detection Report\n\n"
|
||||
report += f"## Summary\n"
|
||||
report += f"- **Total zombie PRs found:** {total_zombies}\n"
|
||||
report += f"- **Repositories scanned:** {len(zombies_by_repo)}\n\n"
|
||||
|
||||
if total_zombies == 0:
|
||||
report += "✅ **No zombie PRs found.**\n"
|
||||
else:
|
||||
report += "⚠️ **Zombie PRs found:**\n\n"
|
||||
|
||||
for repo, zombies in zombies_by_repo.items():
|
||||
if zombies:
|
||||
report += f"### {repo}\n"
|
||||
for zombie in zombies:
|
||||
report += f"- **#{zombie['pr_number']}**: {zombie['title']}\n"
|
||||
report += f" - Author: {zombie['author']}\n"
|
||||
report += f" - Created: {zombie['created']}\n"
|
||||
report += f" - Files changed: {zombie['files_changed']}\n"
|
||||
report += f" - Total changes: {zombie['total_changes']}\n"
|
||||
report += "\n"
|
||||
|
||||
# Add recommendations
|
||||
report += "## Recommendations\n"
|
||||
report += "1. **Close zombie PRs** - PRs with no actual changes should be closed\n"
|
||||
report += "2. **Validate before merge** - CI should reject PRs with no changes\n"
|
||||
report += "3. **Prevent future zombies** - Agents should validate changes before creating PRs\n"
|
||||
report += "4. **Review process** - Reviewers must verify PRs have actual changes\n"
|
||||
|
||||
return report
|
||||
|
||||
|
||||
def main():
|
||||
"""Main entry point for zombie PR checker."""
|
||||
import argparse
|
||||
|
||||
parser = argparse.ArgumentParser(description="Check for zombie PRs (PRs with no actual changes)")
|
||||
parser.add_argument("--repos", nargs="+",
|
||||
default=["the-nexus", "timmy-home", "timmy-config", "hermes-agent", "the-beacon"],
|
||||
help="Repositories to scan")
|
||||
parser.add_argument("--report", action="store_true", help="Generate report")
|
||||
parser.add_argument("--json", action="store_true", help="Output JSON instead of report")
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
checker = ZombiePRChecker()
|
||||
|
||||
# Scan repositories for zombie PRs
|
||||
zombies_by_repo = {}
|
||||
|
||||
for repo in args.repos:
|
||||
zombies = checker.scan_repo_for_zombies(repo)
|
||||
zombies_by_repo[repo] = zombies
|
||||
|
||||
# Generate output
|
||||
if args.json:
|
||||
print(json.dumps(zombies_by_repo, indent=2))
|
||||
elif args.report:
|
||||
report = checker.generate_report(zombies_by_repo)
|
||||
print(report)
|
||||
else:
|
||||
# Default: show summary
|
||||
total_zombies = sum(len(zombies) for zombies in zombies_by_repo.values())
|
||||
|
||||
print(f"\nZombie PR Detection Complete")
|
||||
print("=" * 60)
|
||||
print(f"Total zombie PRs found: {total_zombies}")
|
||||
|
||||
if total_zombies > 0:
|
||||
print("\nZombie PRs:")
|
||||
for repo, zombies in zombies_by_repo.items():
|
||||
for zombie in zombies:
|
||||
print(f" {repo} #{zombie['pr_number']}: {zombie['title']}")
|
||||
sys.exit(1)
|
||||
else:
|
||||
print("\n✅ No zombie PRs found")
|
||||
sys.exit(0)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -1,189 +0,0 @@
|
||||
# Preventing Rubber-Stamping of PRs
|
||||
|
||||
**Issue:** #1445 - process: Prevent rubber-stamping of PRs with no changes
|
||||
**Problem:** PRs with no changes (zombie PRs) are being approved without actual review
|
||||
|
||||
## What is Rubber-Stamping?
|
||||
|
||||
Rubber-stamping occurs when:
|
||||
1. A PR has 0 additions, 0 deletions, and 0 files changed (zombie PR)
|
||||
2. Reviewers approve the PR without noticing it has no changes
|
||||
3. The PR gets merged despite adding no value
|
||||
|
||||
This is a serious process issue because:
|
||||
- It wastes reviewer time
|
||||
- It creates false sense of review quality
|
||||
- It allows zombie PRs to appear reviewed
|
||||
- It clutters the PR backlog
|
||||
|
||||
## Prevention Measures
|
||||
|
||||
### 1. CI Check (`.gitea/workflows/check-pr-changes.yml`)
|
||||
Automated check that runs on every PR:
|
||||
- Detects PRs with no changes
|
||||
- Blocks merge if PR is a zombie
|
||||
- Provides clear error messages
|
||||
|
||||
**What it checks:**
|
||||
- PR has additions, deletions, or file changes
|
||||
- Commits contain actual changes
|
||||
- No empty diffs
|
||||
|
||||
**When it runs:**
|
||||
- On PR open
|
||||
- On PR synchronize (new commits)
|
||||
- On PR reopen
|
||||
|
||||
### 2. PR Template (`.github/PULL_REQUEST_TEMPLATE.md`)
|
||||
Updated PR template with reviewer guidelines:
|
||||
- Clear checklist for reviewers
|
||||
- Explicit instructions to check for changes
|
||||
- Warning against rubber-stamping
|
||||
|
||||
**Reviewer requirements:**
|
||||
1. Verify PR has actual changes
|
||||
2. Changes match description
|
||||
3. Code quality review
|
||||
4. Tests are adequate
|
||||
5. Documentation is updated
|
||||
|
||||
### 3. Zombie PR Detection Script (`bin/check_zombie_prs.py`)
|
||||
Script to scan for zombie PRs:
|
||||
- Check all open PRs in repositories
|
||||
- Identify PRs with no changes
|
||||
- Generate reports
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
# Scan all repositories
|
||||
python bin/check_zombie_prs.py
|
||||
|
||||
# Scan specific repositories
|
||||
python bin/check_zombie_prs.py --repos the-nexus timmy-home
|
||||
|
||||
# Generate report
|
||||
python bin/check_zombie_prs.py --report
|
||||
|
||||
# JSON output
|
||||
python bin/check_zombie_prs.py --json
|
||||
```
|
||||
|
||||
## How to Use
|
||||
|
||||
### For CI/CD
|
||||
The workflow runs automatically on all PRs. No setup needed.
|
||||
|
||||
### For Developers
|
||||
1. **Before creating PR:**
|
||||
- Ensure you have actual changes
|
||||
- Test your changes locally
|
||||
- Don't create PRs with no changes
|
||||
|
||||
2. **When reviewing PRs:**
|
||||
- Check that PR has additions, deletions, or file changes
|
||||
- Verify changes match the PR description
|
||||
- Don't approve PRs with no changes
|
||||
|
||||
3. **If you find a zombie PR:**
|
||||
- Add a comment explaining it has no changes
|
||||
- Request changes or close the PR
|
||||
- Don't approve it
|
||||
|
||||
### For Agents (AI Workers)
|
||||
Before creating a PR:
|
||||
```bash
|
||||
# Check if you have changes
|
||||
git status
|
||||
git diff --stat
|
||||
|
||||
# If no changes, don't create PR
|
||||
# If changes exist, create PR
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Zombie PR Detected
|
||||
```
|
||||
❌ ERROR: PR has no changes!
|
||||
|
||||
This PR has 0 additions, 0 deletions, and 0 files changed.
|
||||
This is a 'zombie PR' that should not be merged.
|
||||
|
||||
Rubber-stamping (approving PRs with no changes) is prohibited.
|
||||
Reviewers must verify that PRs contain actual changes.
|
||||
|
||||
If this is a mistake, please add actual changes to the PR.
|
||||
If this PR is not needed, please close it.
|
||||
```
|
||||
|
||||
### Valid PR
|
||||
```
|
||||
✅ PR has changes:
|
||||
README.md | 10 ++++++++++
|
||||
1 file changed, 10 insertions(+)
|
||||
|
||||
Summary:
|
||||
Files changed: 1
|
||||
Additions: 10
|
||||
Deletions: 0
|
||||
```
|
||||
|
||||
## Related Issues
|
||||
|
||||
- **Issue #1127:** Perplexity Evening Pass triage (identified rubber-stamping)
|
||||
- **Issue #1445:** This implementation
|
||||
- **PR #359:** Example of rubber-stamping (3 approvals on empty PR)
|
||||
|
||||
## Prevention Strategy
|
||||
|
||||
### 1. **Automated Checks**
|
||||
- CI workflow blocks zombie PRs
|
||||
- Pre-commit hooks validate changes
|
||||
- Automated scanning for zombie PRs
|
||||
|
||||
### 2. **Process Guidelines**
|
||||
- Updated PR template with reviewer guidelines
|
||||
- Clear instructions to check for changes
|
||||
- Training on rubber-stamping prevention
|
||||
|
||||
### 3. **Monitoring**
|
||||
- Regular scans for zombie PRs
|
||||
- Reports on rubber-stamping incidents
|
||||
- Continuous improvement of prevention measures
|
||||
|
||||
## Files Added
|
||||
|
||||
1. `.gitea/workflows/check-pr-changes.yml` - CI workflow
|
||||
2. `.github/PULL_REQUEST_TEMPLATE.md` - Updated PR template
|
||||
3. `bin/check_zombie_prs.py` - Zombie PR detection script
|
||||
4. `docs/rubber-stamping-prevention.md` - This documentation
|
||||
|
||||
## Testing
|
||||
|
||||
Test the CI workflow:
|
||||
```bash
|
||||
# Create a test PR with no changes
|
||||
git checkout -b test/zombie-pr
|
||||
git commit --allow-empty -m "test: empty commit"
|
||||
git push origin test/zombie-pr
|
||||
# Create PR and watch CI fail
|
||||
```
|
||||
|
||||
Test the detection script:
|
||||
```bash
|
||||
python bin/check_zombie_prs.py --repos the-nexus --report
|
||||
```
|
||||
|
||||
## Conclusion
|
||||
|
||||
This implementation provides comprehensive protection against rubber-stamping:
|
||||
1. **Automated CI checks** block zombie PRs
|
||||
2. **Updated PR template** guides reviewers
|
||||
3. **Detection script** identifies existing zombie PRs
|
||||
4. **Documentation** explains the problem and solution
|
||||
|
||||
**Result:** No more rubber-stamping of PRs with no changes.
|
||||
|
||||
## License
|
||||
|
||||
Part of the Timmy Foundation project.
|
||||
Reference in New Issue
Block a user