🎃 RepoForge

🔍 Smart Repository Auditor for JavaScript/TypeScript Projects

Find ghosts 👻, curses 🧿, and zombies 🧟 in your codebase

Features • Quick Start • Documentation • MCP Integration

🌟 What is RepoForge?

RepoForge is an intelligent code auditing tool that automatically detects your project type and runs framework-aware analysis to identify quality issues. No configuration needed—just run it!

🎯 Key Capabilities

🔍 Smart Detection

Automatically identifies 15+ frameworks including React, Next.js, Vue, Express, and more

🎯 Context-Aware

Understands your framework's conventions and architecture patterns

💡 Actionable Insights

Provides clear explanations and fix recommendations

🎃 What Does It Find?

👻 Ghosts - Files missing test coverage
🧿 Curses - Structural issues (naming, monolithic files, mixed layers)
🧟 Zombies - Code in wrong places (framework-aware detection)

✨ Features

🚀 Core Capabilities

✅ Zero Configuration      # Just install and run
✅ 15+ Framework Support   # React, Next.js, Vue, Express, etc.
✅ Architecture Analysis   # MVC, Layered, Clean Architecture
✅ Human-Friendly Output   # Plain language explanations
✅ 100% Local             # No API keys or external services

🔬 Advanced Analysis

Feature	Description
🤖 AI Code Generation	Generate components, pages, APIs from natural language
🔍 Deep Code Analysis	Detect complexity, unused code, broken imports
📋 Manifest Generation	Machine-readable repository documentation (JSON/YAML)
🎨 Naming Conventions	Enforce camelCase, PascalCase, kebab-case standards
🔗 Dependency Tracking	Track imports, exports, and dead code
🛡️ Security Scanning	Find hardcoded credentials and vulnerabilities

⚡ Rule Engine

🎛️ Configurable Rules System (Click to expand)

Severity Levels: CRITICAL → HIGH → MEDIUM → LOW → SUGGESTION
Custom Rules: Write team-specific validation rules
CI/CD Ready: Fail builds on critical issues
Framework-Aware: Rules adapt to your tech stack
Smart Filtering: Filter by severity, category, or framework

🚀 Quick Start

Installation (Choose One)

🌍 Global Install (Recommended)

npm install -g repoforge
cd /path/to/your/project
repoforge audit

⚡ Run Without Installing

npx repoforge audit
npx repoforge map
npx repoforge generate "login page"

🎯 Basic Usage

# Quick structural audit
repoforge audit

# Deep audit with code quality checks
repoforge audit --deep

# Show only critical issues
repoforge audit --min-severity CRITICAL

# Fail CI/CD on high severity issues
repoforge audit --fail-on-severity HIGH

# Get project overview
repoforge map

# Generate code with AI
repoforge generate "user authentication API"

📊 Example Output

📖 What is this project?
   This is a frontend application built with React and Next.js.
   It uses modular architecture organized by features.
   TypeScript ✅  |  Tests ✅  |  Package Manager: npm
   
🔍 Audit Results

🔴 CRITICAL (2)
  ├─ SEC001_HARDCODED_CREDENTIALS
  │  └─ src/config.ts:12 - Hardcoded API key detected
  │     💡 Fix: Move credentials to environment variables
  │
  └─ SEC002_SQL_INJECTION
     └─ src/db/queries.ts:45 - Unsafe SQL query construction
        💡 Fix: Use parameterized queries

🟠 HIGH (5)
  └─ ARCH001_CIRCULAR_DEPENDENCY
     └─ src/services/user.ts - Circular dependency detected
        💡 Fix: Refactor to remove circular dependency

🟡 MEDIUM (12)
  └─ TEST001_MISSING_TEST
     └─ src/utils/validator.ts - No test file found
        💡 Fix: Create src/utils/validator.test.ts

📊 Summary: 19 violations (2 critical, 5 high, 12 medium)

🎨 What It Detects

🛠️ Supported Frameworks (15+)

Frontend

⚛️ React
🚀 Next.js
💚 Vue.js
🌊 Nuxt.js
🔺 Angular
🔥 Svelte

Backend

🚂 Express.js
⚡ Fastify
🦅 NestJS
🌐 Node.js

Build Tools

⚡ Vite
📦 Webpack

🏗️ Architecture Patterns

✅ MVC (Model-View-Controller)
✅ Layered Architecture
✅ Clean Architecture  
✅ Modular/Feature-based
✅ Flat Structure

🔍 Code Quality Issues

Category	Issues Detected
🔴 Security	Hardcoded credentials, API keys, SQL injection
📐 Complexity	High cyclomatic complexity, tight coupling
💀 Dead Code	Unused variables, functions, files
🔗 Dependencies	Broken imports, circular dependencies
🎨 Style	Naming conventions, console.log statements
📝 Best Practices	Empty catch blocks, excessive TODOs
🔒 Type Safety	Excessive 'any' types in TypeScript

🔧 Advanced Features

🤖 AI Code Generation

Generate production-ready code from natural language:

repoforge generate "homepage for mobile shop"
repoforge generate "REST API for user management"
repoforge generate "product card component with TypeScript"

Generated Code Includes:

✅ Framework-aware structure
✅ Proper file organization
✅ Test files included
✅ TypeScript support
✅ Best practices applied

⚙️ Configuration System

Create .repoforge/rules.json to customize behavior:

{
  "minSeverity": "MEDIUM",
  "failOnSeverity": "HIGH",
  "disabledRules": ["STYLE001_NAMING_CONVENTION"],
  "categories": ["Security", "Architecture"],
  "parallel": true
}

Common Configurations:

🔒 Strict CI/CD

{
  "minSeverity": "MEDIUM",
  "failOnSeverity": "HIGH"
}

🛡️ Security-Only Audit

{
  "categories": ["Security"],
  "failOnSeverity": "HIGH"
}

🎯 Gradual Adoption

{
  "minSeverity": "CRITICAL",
  "failOnSeverity": "CRITICAL"
}

🎨 Custom Rules

Create team-specific validation rules:

// .repoforge/custom-rules.ts
import { Rule } from 'repoforge';

export const customRules: Rule[] = [
  {
    id: 'CUSTOM001_NO_CONSOLE',
    name: 'No Console Statements',
    category: 'Style',
    severity: 'LOW',
    description: 'Detects console.log statements',
    check: (context) => {
      // Your validation logic
      return violations;
    }
  }
];

📖 See the Rule Authoring Guide for detailed instructions.

🚦 CI/CD Integration

GitHub Actions

name: Code Quality
on: [push, pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm install -g repoforge
      - run: repoforge audit --fail-on-severity HIGH

GitLab CI

code_quality:
  stage: test
  script:
    - npm install -g repoforge
    - repoforge audit --fail-on-severity HIGH

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit
repoforge audit --min-severity HIGH --fail-on-severity CRITICAL

🤖 MCP Server Integration (Kiro IDE)

RepoForge integrates seamlessly with AI coding assistants through the Model Context Protocol (MCP).

Quick Setup with Kiro

Automated Setup:

# Clone and setup
git clone https://github.com/Akshat050/repoforge.git
cd repoforge
npm install

# Run setup script
# On Windows:
setup-global-mcp.bat

# On Mac/Linux:
chmod +x setup-global-mcp.sh
./setup-global-mcp.sh

Manual Configuration:

Create ~/.kiro/settings/mcp.json:

{
  "mcpServers": {
    "repoforge": {
      "command": "npx",
      "args": ["-y", "repoforge-mcp"]
    }
  }
}

💬 Chat with Kiro

Once configured, just talk naturally:

💭 "Audit this repository"
💭 "Generate a user login page"
💭 "Show me security issues"
💭 "Create a manifest for this project"
💭 "What's the health status of this codebase?"

📖 See KIRO_CHAT_PROMPTS.md for 50+ example prompts.

Available MCP Tools

repoforge_audit_repo - Full detailed audit with recommendations
repoforge_audit_summary - Quick health check summary
repoforge_generate_code - AI-powered code generation
repoforge_generate_manifest - Generate repository manifest

📚 Documentation

Document	Description
Rule Authoring Guide	Create custom rules for your team
Configuration Examples	Sample configurations for common use cases
Rule Engine Design	Architecture and technical details
Kiro Setup Guide	Integrate with Kiro IDE
Chat Prompts	Example prompts for AI assistants
Troubleshooting	Common issues and solutions

❓ FAQ

Do I need API keys or external services?

No! RepoForge runs 100% locally on your machine. No API keys, no sign-ups, no external dependencies.

Does it work offline?

Yes! RepoForge is a static analysis tool that works completely offline.

What languages does it support?

Currently JavaScript and TypeScript. Support for more languages coming soon!

Can I use it in CI/CD?

Absolutely! RepoForge is designed for CI/CD integration. Use --fail-on-severity to control when builds should fail.

How do I write custom rules?

See the Rule Authoring Guide for detailed instructions.

Is it free?

Yes! RepoForge is open source and completely free to use.

🗺️ Roadmap

🎯 Current Focus

🔮 Coming Soon

💡 Future Ideas

🤝 Contributing

Contributions are welcome! Here's how you can help:

🐛 Report Bugs - Open an issue with reproduction steps
💡 Suggest Features - Share your ideas in discussions
📝 Improve Documentation - Fix typos, add examples
🔧 Submit PRs - Fix bugs or add features

Development Setup

# Clone the repository
git clone https://github.com/Akshat050/repoforge.git
cd repoforge

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Link globally for testing
npm link

🏆 Hackathon Project

🎃 Created for Kiroween 2024 - Frankenstein Category 🎃

Making code quality spooky fun!

📄 License

This project is licensed under the ISC License - see the LICENSE file for details.

👨‍💻 Author

Akshat

🙏 Acknowledgments

Built for the Kiroween 2024 Hackathon
Inspired by the need for better code quality tools
Thanks to all contributors and early testers

💙 If RepoForge helped you find bugs and improve your code, please give it a ⭐

⬆ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
.kiro		.kiro
.repoforge		.repoforge
cli		cli
core		core
docs		docs
mcp-server		mcp-server
src		src
tests		tests
.gitignore		.gitignore
GITHUB_COMMIT_GUIDE.md		GITHUB_COMMIT_GUIDE.md
KIRO_CHAT_PROMPTS.md		KIRO_CHAT_PROMPTS.md
KIRO_GLOBAL_SETUP.md		KIRO_GLOBAL_SETUP.md
KIRO_TROUBLESHOOTING.md		KIRO_TROUBLESHOOTING.md
MCP_SETUP_COMPLETE.md		MCP_SETUP_COMPLETE.md
README.md		README.md
install-hooks.bat		install-hooks.bat
install-hooks.sh		install-hooks.sh
package-lock.json		package-lock.json
package.json		package.json
setup-global-mcp.bat		setup-global-mcp.bat
setup-global-mcp.sh		setup-global-mcp.sh
tsconfig.json		tsconfig.json

Akshat050/repoforge

Folders and files

Latest commit

History

Repository files navigation