🧙‍♂️ Code-Sage

Code-Sage is a pragmatic, AI-powered code reviewer CLI that understands the logic and architecture of your codebase.

Instead of treating code reviews as isolated file edits, Code-Sage parses the Abstract Syntax Tree (AST) of your project locally to construct a directed dependency graph. When you modify code, Code-Sage traces the "blast radius" of your changes and feeds targeted caller context to Gemini to catch downstream integration bugs before they reach production.

🌟 Key Features

• Semantic Impact Analysis (Concept C): Locally builds an AST-based call graph of JavaScript and TypeScript files. When an exported function signature changes, it locates and reviews every unmodified file that calls it.
• Closed-Loop CI Integration: Designed to run automatically inside GitHub Actions on Pull Requests, posting inline code reviews and suggestions directly onto the code lines.
• Token-Efficient Reasoning: Avoids sending massive repository contexts to LLMs. Only the git difference and the precise caller-site snippets are evaluated.
• Developer-Friendly Console: Outputs elegant, structured warnings, severities, and suggested code patches directly in your local terminal.

🚀 Local Installation & Usage

You can run Code-Sage directly on any repository on your machine without installing it, using npx:

1. Set Your API Key

Ensure you have a Google Gemini API Key. Get one for free at Google AI Studio.

Set the key in your terminal session:

• macOS/Linux: export GEMINI_API_KEY="your_key_here"
• Windows (PowerShell): $env:GEMINI_API_KEY="your_key_here"

(Alternatively, you can create a .env file in the root of your project containing GEMINI_API_KEY=your_key_here)

2. Execute Code-Sage

Navigate to your target project folder and run:

# Review all uncommitted changes (unstaged + staged)
npx code-sage-cli

# Review only staged changes
npx code-sage-cli --staged

# Review only unstaged changes
npx code-sage-cli --unstaged

🤖 GitHub Actions CI Integration

Code-Sage is designed to run automatically on every Pull Request.

Step 1: Add your Gemini API Key to GitHub Secrets

1. Go to your repository settings on GitHub.
2. Navigate to Secrets and variables ➔ Actions.
3. Click New repository secret, name it GEMINI_API_KEY, and paste your API key.

Step 2: Auto-Generate the Workflow File

Navigate to your project repository and run:

npx code-sage-cli --init

This will automatically create the .github/workflows/code-review.yml file with the correct configuration:

name: Code-Sage Reviewer

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write  # Required to post inline reviews
      contents: read
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Required to calculate git diffs

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Run Code-Sage
        run: npx code-sage-cli --staged
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Automatically provided by GitHub

🛠️ Local Development & Contributing

If you want to modify Code-Sage or run your own fork locally:

1. Clone the repository and install dependencies:

   npm install

2. Build the TypeScript compiler:

   npm run build

3. Symlink the package globally:

   npm link

4. Now you can run code-sage globally on your system.

📄 License

MIT License.