SphereAI Pipeline

AI-powered code analysis tool for CI/CD pipelines. Integrate SphereAI into your GitHub Actions, GitLab CI, Azure DevOps, or any other CI/CD platform.

Features

• Two Analysis Modes:

  • changed-only: Analyze only files changed between branches (ideal for PRs)
  • full-branch: Analyze all files in the repository

• Pipeline Integration:

  • Exit codes for pipeline control (0=success, 1=warning, 2=failure)
  • GitHub Actions annotations and outputs
  • Detailed markdown reports

• Smart File Detection:

  • Automatic detection of changed files using Git
  • Configurable include/exclude patterns
  • Support for multiple programming languages

Installation

npm install -g sphereai-pipeline

Or use directly with npx:

npx sphereai-pipeline analyze

Quick Start

# Set environment variables
export SPHEREAI_API_KEY="your-api-key"
export SPHEREAI_PROMPT_ID="your-prompt-id"

# Analyze changed files (compared to main branch)
sphereai-pipeline analyze --mode changed-only --base-branch main

# Analyze all files
sphereai-pipeline analyze --mode full-branch

Usage

Commands

analyze

Run code analysis on your repository.

sphereai-pipeline analyze [options]

Options:

| Option | Description | Default | |--------|-------------|---------| | -k, --api-key <key> | SphereAI API key | SPHEREAI_API_KEY env var | | -u, --api-url <url> | SphereAI API URL | https://api.sphereai.com.br | | -p, --prompt-id <id> | Prompt ID for analysis | SPHEREAI_PROMPT_ID env var | | -m, --mode <mode> | Analysis mode: full-branch or changed-only | changed-only | | -b, --base-branch <branch> | Base branch for comparison | main | | -t, --target-branch <branch> | Target branch for comparison | HEAD | | -d, --directory <path> | Working directory | Current directory | | -i, --include <patterns> | Comma-separated include patterns | See defaults below | | -e, --exclude <patterns> | Comma-separated exclude patterns | See defaults below | | --fail-on-warning | Exit with failure code on warnings | false | | -o, --output <path> | Save detailed report to file | - | | -v, --verbose | Enable verbose output | false |

config

Show current configuration.

sphereai-pipeline config

Exit Codes

| Code | Status | Description | |------|--------|-------------| | 0 | Success | Analysis passed with no issues | | 1 | Warning | Analysis found warnings (pipeline continues) | | 2 | Failure | Analysis found critical issues (pipeline should abort) |

Use --fail-on-warning to treat warnings as failures (exit code 2).

GitHub Actions Integration

Basic Setup

1. Add secrets to your repository:

   • SPHEREAI_API_KEY: Your SphereAI API key
   • SPHEREAI_PROMPT_ID: The prompt ID to use for analysis

2. Create .github/workflows/sphereai.yml:

name: SphereAI Code Analysis

on:
  pull_request:
    branches: [main]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v6
        with:
          node-version: '20'

      - run: npm install -g sphereai-pipeline

      - name: Run Analysis
        env:
          SPHEREAI_API_KEY: ${{ secrets.SPHEREAI_API_KEY }}
          SPHEREAI_PROMPT_ID: ${{ secrets.SPHEREAI_PROMPT_ID }}
        run: |
          sphereai-pipeline analyze \
            --mode changed-only \
            --base-branch ${{ github.base_ref }}

Advanced Configuration

See .github/workflows/sphereai-analysis.yml for a complete example with:

• PR comments with analysis results
• Artifact upload for reports
• Different modes for PRs vs pushes

GitHub Actions Outputs

When running in GitHub Actions, the following outputs are set:

| Output | Description | |--------|-------------| | status | Analysis status (success/warning/failure) | | exit_code | Exit code (0/1/2) | | files_analyzed | Number of files analyzed | | tokens_used | Total tokens used |

Environment Variables

| Variable | Description | |----------|-------------| | SPHEREAI_API_KEY | SphereAI API key | | SPHEREAI_API_URL | API URL (default: https://api.sphereai.com.br) | | SPHEREAI_PROMPT_ID | Prompt ID for analysis | | SPHEREAI_MODE | Analysis mode | | SPHEREAI_BASE_BRANCH | Base branch for comparison | | SPHEREAI_TARGET_BRANCH | Target branch for comparison | | SPHEREAI_FAIL_ON_WARNING | Set to "true" to fail on warnings | | SPHEREAI_INCLUDE_PATTERNS | Comma-separated include patterns | | SPHEREAI_EXCLUDE_PATTERNS | Comma-separated exclude patterns |

Default Patterns

Include Patterns

By default, the following file types are analyzed:

• TypeScript: **/*.ts, **/*.tsx
• JavaScript: **/*.js, **/*.jsx
• Python: **/*.py
• Java: **/*.java
• C#: **/*.cs
• Go: **/*.go
• Rust: **/*.rs
• Ruby: **/*.rb
• PHP: **/*.php
• Swift: **/*.swift
• Kotlin: **/*.kt
• Scala: **/*.scala
• Vue: **/*.vue
• Svelte: **/*.svelte

Exclude Patterns

By default, the following are excluded:

• node_modules/**
• .git/**
• dist/**, build/**
• coverage/**
• .next/**, .nuxt/**
• vendor/**
• *.min.js, *.min.css
• *.map, *.lock
• package-lock.json, yarn.lock, pnpm-lock.yaml
• .env*
• *.log

Examples

Analyze only TypeScript files

sphereai-pipeline analyze \
  --include "**/*.ts,**/*.tsx" \
  --mode full-branch

Analyze with custom exclude patterns

sphereai-pipeline analyze \
  --exclude "**/*.test.ts,**/*.spec.ts,**/fixtures/**" \
  --mode changed-only

Save report and fail on warnings

sphereai-pipeline analyze \
  --output ./reports/analysis.md \
  --fail-on-warning \
  --verbose

Development

# Install dependencies
npm install

# Build
npm run build

# Development mode (watch)
npm run dev

# Production build with obfuscation
npm run build:prod

License

MIT - Nava Tech For Business