DEV Community

Abdulaleem Zakariyah
Abdulaleem Zakariyah

Posted on

PyReviewer: A Production-Grade Python AST, Security & Docker Reviewer for Large Codebases

#devchallenge #weekendchallenge #hf26challenge #render

Hacktoberfest Weekend Challenge: Build for a Friend Submission 🤝

This is a submission for the Hacktoberfest Weekend Challenge: Build for a Friend

What I Built

I built PyReviewer for my close friend Dave, a self-taught junior Python developer currently building multi-file FastAPI microservices and background data pipelines.

Who I Built It For: My Friend Dave

Dave is a passionate developer, but like many juniors working across growing multi-file repositories, he continually runs into high-severity traps that are hard to catch without senior peer review:

  • Async Concurrency Freezes: Accidentally placing synchronous blocking functions (time.sleep(), requests.get()) inside FastAPI async def endpoints, locking Python's single-threaded event loop and stalling client requests.
  • Mutable Default Leaks: Using def append_item(item, cache=[]), causing memory to leak and state to bleed across completely unrelated requests.
  • OWASP Security Vulnerabilities: String-interpolated SQL queries (f"SELECT * FROM users WHERE id = '{user_id}'"), shell command injections (subprocess.run(..., shell=True)), and insecure deserialization (pickle.loads()).
  • Codebase Review Fatigue: Struggling to get a unified view of 30+ files across a repo, rank security hotspots, and write production-hardened Dockerfiles that don't run as root.

What PyReviewer Does For Him

PyReviewer turns large, messy codebases into clean, production-ready systems in seconds:

  1. GitHub Repository Scanner: Dave pastes his public GitHub repository URL. PyReviewer executes a shallow clone, indexes every Python file into an interactive 3-column file tree explorer, and runs an AST security sweep.
  2. Deterministic AST & Security Engine: Inspects Python Abstract Syntax Trees via ast.NodeVisitor for zero-day vulnerabilities, blocking async calls, and Python anti-patterns.
  3. Hotspot Ranking & Executive Audit Report: Ranks files by risk concentration and compiles a comprehensive, downloadable Markdown audit report.
  4. Unified Refactor Diffs: Generates Git-style unified diffs showing exact fixes with a 1-click "Apply Refactor" button.
  5. Production Docker Packaging & Render Deployment: Automatically generates a hardened multi-stage Dockerfile and a render.yaml Blueprint for 1-click deployment on Render.

Demo

PyReviewer is containerized with Docker and running live in production on Render:

How It Works:

  1. Paste any GitHub repository URL (e.g. https://github.com/psf/requests or click "Load Demo Microservice Repo").
  2. The 3-column workspace immediately opens the codebase tree, color-coded by vulnerability risk (Green = Safe, Amber = Warnings, Red = Critical Flaws).
  3. Select any file to inspect syntax-highlighted code with gutter line numbers and live diagnostic warning pills.
  4. Click "Review & Refactor" to inspect unified diffs and one-click fixes.
  5. Switch to "Docker & Render" to inspect the auto-generated multi-stage Dockerfile and one-click deploy to Render.

Code

PyReviewer is completely open source under the MIT License:

├── Dockerfile                  # Hardened Docker container for Render (git + non-root user)
├── render.yaml                 # Render Blueprint specification
├── docker-compose.yml          # Local container orchestration
├── server.py                   # High-performance server with /healthz & /api/scan-repo
├── requirements.txt            # Optional production dependencies
├── .dockerignore               # Clean container exclusion rules
├── app/
│   ├── analyzer.py             # Pure Python AST NodeVisitor & Security Rules
│   └── repo_scanner.py         # Git shallow cloning & repository auditor
└── static/
    ├── index.html              # Clean 3-column repository explorer UI
    ├── style.css               # Slate/zinc high-density developer stylesheet
    └── app.js                  # File tree, diff viewer & report exporter
Enter fullscreen mode Exit fullscreen mode

How I Built It

PyReviewer is built around an open agentic harness and open-source local analysis tools:

  1. Open-Source Agent Harness: Developed collaboratively using the open Antigravity agentic harness with the DevRelay gateway, which tracked session milestones and verified architectural decisions.
  2. Deterministic AST Visitor Engine (ast.NodeVisitor): Rather than relying on unreliable black-box LLMs that hallucinate syntax errors or leak source code, PyReviewer inspects the raw compiler syntax tree using Python's native ast library: 
   class PythonASTAnalyzer(ast.NodeVisitor):
       def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef):
           for child in ast.walk(node):
               if isinstance(child, ast.Call):
                   name = self._get_call_name(child.func)
                   if name in ["time.sleep", "sleep"]:
                       self.issues.append({
                           "line": child.lineno,
                           "code": "PERF-001",
                           "title": "Blocking Call in Async Function",
                           "severity": "CRITICAL",
                           "message": f"Synchronous '{name}()' blocks the event loop in '{node.name}'.",
                           "suggestion": "Use 'await asyncio.sleep()' instead."
                       })
Enter fullscreen mode Exit fullscreen mode
  1. Multi-Stage Docker Packaging: Packaged inside a slim python:3.12-slim container with git and ca-certificates installed so repository cloning works directly inside the container, running under non-root appuser (UID 10001).
  2. Render Infrastructure-as-Code (render.yaml): Uses a declarative Render Blueprint to configure the container web service, health checks, and port forwarding.

Why Does Open Innovation Matter?

  1. Zero Intellectual Property & Code Leakage: Dave and other developers should never have to paste proprietary codebases into closed third-party cloud LLMs where sensitive code can be retained or used for model retraining. PyReviewer runs AST analysis entirely locally on Dave's laptop or inside his own isolated Render container.
  2. 100% Deterministic & Reproducible: Closed AI models yield stochastic, inconsistent outputs between runs. Python's native AST engine produces identical, reproducible results every time, making it suitable for CI/CD gating and production standards.
  3. Zero Inference Costs & Zero Latency: No expensive API keys, no rate limits, and sub-20ms analysis times across dozens of files.

My Agent Session

The complete end-to-end development session was captured and curated using DevRelay:

PyReviewer: Large Codebase GitHub Scanner & Executive Audit Reporter for Render
You

Make it suitable for large codebase where the user can just paste in the GitHub URL, it populates the codebase, and scans and writes a detailed report.

Agent

We expanded PyReviewer into a full repository-scale code auditor. We added a shallow git cloning engine with ast.NodeVisitor traversal that maps entire GitHub codebases into an interactive file tree, ranks risk hotspots, and generates an audit-grade Markdown report with multi-stage Dockerfile and render.yaml blueprints.

2 of 2 messages

(View the complete transcript on DevRelay Agent Session #470.)

Prize Categories

  • Best Use of Render ($200 Featured Category): PyReviewer is deployed in production as a Docker web service on Render at https://pyreviewer.onrender.com/. It features native /healthz health check monitoring, a production Dockerfile with non-root security isolation, and a declarative render.yaml Blueprint for 1-click zero-downtime deployment.

Top comments (0)