SpecGuard

• 

  all the files having config

• 

  AI results

• 

  Blast Radius

Inspiration

Every developer has lived through this scenario: you refactor a shared configuration, rename a core helper function, or adjust a base class, push to staging, and unknowingly trigger a critical downstream regression in production.

Modern code review is often blind and stressful. Standard IDE searches and grep only match flat strings without architectural context—they cannot trace call hierarchies, module imports, or downstream impact paths. We built SpecGuard to answer one critical question before code ever gets merged: "What else could this change break?"

What it does

SpecGuard is an impact analysis platform that turns complex repository relationships into an intuitive, evidence-based blast-radius map.

Safe Repository Ingestion: Accepts a public GitHub repository URL and safely clones it into an isolated temporary workspace.

AST Dependency Tracing: Parses Python source files using Abstract Syntax Trees (AST) to track definitions, direct references, import aliasing, and function/class invocations across the entire codebase.

Blast-Radius Scoring: Evaluates reference density, cross-module propagation, and file depth to compute an automated risk score and risk classification level.

Interactive Bubble Graph: Replaces cumbersome text lists with a dynamic visual network. The selected target symbol sits at the center, surrounded by affected file nodes connected by relationship paths.

Inspectable Source Evidence: Clicking any file bubble instantly reveals exact matching lines, line numbers, reference types (import, call, read/write), and source snippets.

How we built it

We designed SpecGuard with a decoupled, cloud-ready architecture:

Frontend: Built with Next.js, React, and Tailwind CSS, featuring an interactive SVG/canvas bubble graph for visual exploration and responsive risk inspection.

Backend API: Powered by FastAPI (Python), handling asynchronous request lifecycles, execution timeouts, rate limiting, and shallow git cloning.

Static Analysis Engine: Leveraged Python's native ast module to build custom visitors (NodeVisitor) capable of resolving module imports, symbol renames, and call sites without needing runtime execution.

Authentication: Integrated Supabase Auth supporting GitHub/Google OAuth and email verification flows, validated on the backend via cryptographic JWT/JWKS verification.

Containerization & Deployment Architecture: Containerized using OCI standards (Podman/Docker) and designed for AWS deployment targeting ECS Fargate, Application Load Balancer (ALB), Amazon ECR, and AWS Secrets Manager.

Challenges we ran into AST vs. Dynamic Python Aliasing: Unlike static languages, Python allows dynamic imports like from config import Settings as AppConfig. Building the AST visitor to detect aliases and track their invocations downstream required careful scope handling without introducing false positives.

Subprocess Safety & Isolation: Cloning arbitrary public repositories introduces security and resource exhaustion risks. We had to enforce strict process timeouts, shallow --depth 1 single-branch clones, disk-size ceilings, and file-count thresholds to keep worker containers healthy.

State Synchronization & Cleanup: Ensuring cloned workspaces were cleanly removed from the container file system after every scan—even when syntax errors or timeouts occurred—required strict asynchronous try...finally resource cleanups.

Accomplishments that we're proud of Successfully running full AST impact analysis across large, real-world repositories (like encode/uvicorn) in seconds.

Replacing static, hard-to-read dependency trees with an interactive, fluid bubble graph that visualizes risk at a glance.

Achieving a fully containerized prototype with stateless backend execution, clean OAuth integration, and zero persistent code storage on our servers.

What we learned

The distinct advantages and boundaries of AST static analysis over full Language Server Protocols (LSP) specifically how much speed you can achieve when parsing syntax trees directly versus compiling runtime type environments.

Designing developer-first risk heuristics: developers don't just want a list of files; they need confidence scores and contextual snippets to prioritize review time.

Managing OCI-compliant container builds with Podman targeting AWS ECS Fargate architectures.

What's next for SpecGuard Git Diff & PR Ingestion: Automatically extracting changed symbols directly from GitHub Pull Request URLs or git diffs instead of requiring manual symbol inputs.

CI/CD GitHub Action: Packaging SpecGuard into a lightweight GitHub Action that automatically comments a blast-radius map directly on Pull Requests.

Asynchronous Task Queue: Decoupling scans into background worker containers using Amazon SQS and Celery for large-scale enterprise monorepos.

Multi-Language Support: Expanding syntax analysis beyond Python to TypeScript, Go, and Rust using tree-sitter. Also Adding amazon voice system to support early on

Built With

• amazon
• amazon-ecs
• amazon-web-services
• ast
• aws-fargate
• docker
• fastapi
• git
• next.js
• podman
• python
• react
• supabase
• tailwind-css
• typescript