Smart Code AI Reviewer

AI-assisted code review tool that combines static analysis with artificial intelligence to provide comprehensive code quality assessments for Salesforce and multi-language projects.

Overview
Prerequisites
Installation
Usage
Examples
Architectural Components
Tools & Technologies
Workflow Integration
AI Analysis Output
License
Support
Roadmap

🚀 Overview

Smart Code AI Reviewer is a Salesforce CLI plugin that revolutionizes code review workflows by integrating multiple static analysis tools with AI-powered insights. The tool performs hybrid analysis on code changes, combining Salesforce Code Analyzer (SCA) for Salesforce-specific files and PMD for general programming languages, then leverages AI models to provide intelligent, contextual code review comments.

📋 Prerequisites

Node.js 20.0.0 or higher
Salesforce CLI installed and configured
Git repository with commit history
Java (v11 or higher - required to run PMD commands)
Python (v3.10 or higher - required for enabled FlowEngine check in SF Code Analyzer)
AI Provider API Key (AzureOpenAI, OpenAI or Anthropic)
GitHub Token (optional, for PR comments)
Datadog API Key (optional, for observability features)

Static Analysis Tools

Salesforce Code Analyzer: Automatically managed by the plugin
PMD: Automatically invoked for non-Salesforce files

🚀 Installation

As a Salesforce CLI Plugin

# Install from npm
sf plugins install sfcoepr-review

💻 Usage

Basic Command Structure

sf ks review diff [OPTIONS]

Required Flags

Flag	Short	Description	Example	Default
`--ai-provider`	`-a`	AI service provider	`AzureOpenAI`, `OpenAI` or `Anthropic`	`AzureOpenAI`
`--ai-token`	`-n`	Authentication token for AI provider	`$OPENAI_TOKEN`
`--ai-model`	`-m`	AI model to use	`gpt-4o-mini`, `claude-3-sonnet`	`gpt-4o-mini-eastus2`

Optional Flags

Flag	Short	Description	Default
`--repo-dir`	`-r`	Path to Git repository	Current directory
`--from`	`-f`	Base commit/branch	`HEAD~1`
`--to`	`-t`	Target commit/branch	`HEAD`
`--sf-config-file`	`-s`	SCA configuration file (YAML)	Built-in ruleset
`--pmd-config-file`	`-x`	PMD configuration file (XML)	Built-in ruleset
`--pull-request-id`	`-p`	PR ID for comment posting	None
`--git-provider`	`-g`	Git hosting service	`GitHub`
`--git-token`	`-k`	Git provider token	None
`--git-owner`	`-w`	Repository owner	None
`--git-repo`	`-o`	Repository name	None
`--ai-api-endpoint`	`-e`	AzureOpenAI endpoint	`https://dts-apigw-sandbox.docusignhq.com/`
`--ai-api-version`	`-v`	AzureOpenAI deployment version	`2024-08-01-preview`

📚 Examples

Basic Local Analysis

sf ks review diff \
  --repo-dir=./my-salesforce-project \
  --ai-provider=AzureOpenAI \
  --ai-token=$AZURE_OPENAI_TOKEN \
  --ai-model=gpt-4o-mini-eastus2 \
  --ai-api-endpoint=https://dts-apigw-sandbox.docusignhq.com/ \
  --ai-api-version=2024-08-01-preview \
  --from=main \
  --to=HEAD \
  --sf-config-file=code-analyzer/sf-code-analyzer-ruleset.yml \
  --pmd-config-file=code-analyzer/pmd-ruleset.yml

Integration with GitHub Action

sf ks review diff \
  --repo-dir=./my-salesforce-project \
  --ai-provider=AzureOpenAI \
  --ai-token=$AZURE_OPENAI_TOKEN \
  --ai-model=gpt-4o-mini-eastus2 \
  --ai-api-endpoint=https://dts-apigw-sandbox.docusignhq.com/ \
  --ai-api-version=2024-08-01-preview \
  --git-provider=GitHub \
  --git-token=$GITHUB_TOKEN \
  --git-owner=myorg \
  --git-repo=my-repo \
  --pull-request-id=123 \
  --from=main \
  --to=HEAD \
  --sf-config-file=code-analyzer/sf-code-analyzer-ruleset.yml \
  --pmd-config-file=code-analyzer/pmd-ruleset.yml

🏗️ Architectural Components

1. Core Command Layer

Main Command: ks review diff - Entry point for code review operations
CLI Interface: Built on Salesforce CLI framework with OCLIF

2. Git Integration Layer

Git Helper: Manages repository operations and diff creation
Git Providers: Support for GitHub (extensible for other providers)
Diff Management: Creates temporary directories with code changes

3. Static Analysis Layer

Hybrid Analysis Engine: Orchestrates different analysis tools
SCA Integration: Salesforce Code Analyzer for Apex, LWC, Visualforce
PMD Integration: PMD for JavaScript, TypeScript, HTML, PL/SQL
SARIF Processing: Standardized Static Analysis Results Interchange Format

4. AI Integration Layer

AI Providers: AzureOpenAI, OpenAI and Anthropic Claude integration
Context Processing: Converts static analysis results to AI prompts
Response Handling: Processes AI-generated review suggestions

5. Configuration Layer

Default Rulesets: Built-in configuration files for both SCA and PMD
Custom Configuration: Support for user-defined ruleset files
File-based Configuration: YAML for SCA, XML for PMD

🛠️ Tools & Technologies

Core Technologies

Language: TypeScript 5.8+
Runtime: Node.js 18+
CLI Framework: OCLIF (Salesforce CLI Plugin Framework)
Build System: Wireit (Incremental build tool)

Static Analysis Tools

Salesforce Code Analyzer (SCA): Official Salesforce static analysis tool
- ESLint for JavaScript/TypeScript/LWC
- PMD for Apex
- Retire.js for security vulnerabilities
- Custom regex rules
PMD: Multi-language static analysis
- JavaScript, TypeScript, HTML
- PL/SQL and other database languages

AI Providers

AzureOpenAI: GPT-4, GPT-4o-mini models via Azure OpenAI endpoint
OpenAI: GPT-4, GPT-4o-mini models via OpenAI model
Anthropic: Claude models (claude-3-sonnet, claude-3-haiku)
Custom Prompts: Specialized prompts for code review context with JSON schema validation

Git Integration

SimpleGit: Git operations and repository management
GitHub REST APIs: Pull request comment integration with intelligent comment management for bot comments to avoid duplication
Bot Identification: Multiple methods to identify and manage AI-generated comments

Development Tools

Testing: Jest, NYC (coverage), Mocha with comprehensive unit tests
Linting: ESLint with Salesforce plugin rules
Formatting: Prettier
Type Checking: TypeScript compiler
Observability: Winston logging with Datadog integration, Datadog metrics
Git Hooks: Husky for pre-commit validation
Build System: Wireit for incremental compilation
Security: Automated security scanning in pre-commit hooks
Commit Validation: Commitlint for conventional commit messages

🔄 Workflow Integration

CI/CD Pipeline Integration

# .github/workflows/code-review.yml
name: Generate AI Code Suggestions

on:
  pull_request:
    types: [opened, synchronize, reopened]
  workflow_dispatch: # Can also be manually triggered, if needed.

permissions:
  contents: write # Required to commit changes from Salesforce and push them back to the remote.
  packages: read
  pull-requests: write
  id-token: write

jobs:
  generate-suggestions:
    runs-on: [self-hosted, linux]

    container:
      image: <docker_image_url>
      credentials:
        username: ${{ github.actor }}
        password: ${{ secrets.GITHUB_TOKEN }}

    env: # Set global environment variables for the job
      AI_PROVIDER: ${{ secrets.AI_PROVIDER }}
      AI_MODEL: ${{ secrets.AI_MODEL }}
      AI_API_ENDPOINT: ${{ secrets.AI_API_ENDPOINT }}
      AI_API_VERSION: ${{ secrets.AI_API_VERSION }}
      AI_TOKEN: ${{ secrets.AI_TOKEN }}
      GIT_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      BASE_COMMIT: ${{ github.event.pull_request.base.sha }}
      HEAD_COMMIT: ${{ github.event.pull_request.head.sha }}
      DD_API_KEY: ${{ secrets.DD_API_KEY }}
      PMD_VERSION: ${{ secrets.PMD_VERSION || '7.15.0' }}
      MAX_TOKENS_PER_REQUEST: ${{ secrets.MAX_TOKENS_PER_REQUEST || '4096' }}
      DD_SOURCE: ${{ secrets.DD_SOURCE }}
      DD_HOSTNAME: ${{ secrets.DD_HOSTNAME }}
      DD_SERVICE: ${{ secrets.DD_SERVICE }}
      DD_METRIC_PREFIX: ${{ secrets.DD_METRIC_PREFIX' }}
      DD_ENV: ${{ secrets.DD_ENV }}
      LOG_LEVEL: ${{ secrets.LOG_LEVEL }}
      BOT_NAME: <bot_name>
      BOT_EMAIL: <bot_email>

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Needed to fetch full history for git diffing later

      - name: Add safe directory for Git ownership
        run: |
          git config --global --add safe.directory "$(pwd)"
          echo "Git safe directory configured."

      - name: Configure Git Bot Identity
        run: |
          git config user.name "${{ env.BOT_NAME }}"
          git config user.email "${{ env.BOT_EMAIL }}"

      - name: Install Salesforce CLI
        run: |
          echo "Installing SF CLI package"
          npm install -g @salesforce/cli || { echo "Failed to install SF CLI" && exit 1; }
          echo "SF CLI installed successfully."

      - name: Ensure Java v11 or greater
        uses: actions/setup-java@v4
        with:
          java-version: '>=11'
          distribution: 'zulu'

      - name: Ensure Python v3.10 or greater
        uses: actions/setup-python@v5
        with:
          python-version: '>=3.10'

      - name: Install PMD CLI
        run: |
          echo "Installing PMD CLI"

          # Check Java version
          echo "Checking Java version..."
          if ! java -version 2>&1 | head -1; then
            echo "Java is not installed or not in PATH"
            exit 1
          fi

          # Check Python version
          echo "Checking Python version..."
          if ! python --version 2>/dev/null && ! python3 --version 2>/dev/null; then
            echo "Python is not installed or not in PATH"
            exit 1
          fi

          PMD_VERSION=${PMD_VERSION}
          PMD_URL="https://github.com/pmd/pmd/releases/download/pmd_releases%2F${PMD_VERSION}/pmd-dist-${PMD_VERSION}-bin.zip"

          echo "Downloading PMD from: $PMD_URL"
          # Download PMD with more verbose output for debugging
          if ! wget --progress=dot:giga "$PMD_URL" -O pmd.zip; then
            echo "Failed to download PMD from $PMD_URL"
            echo "Trying alternative download method..."
            # Try with curl as fallback
            if ! curl -L "$PMD_URL" -o pmd.zip; then
              echo "Failed to download PMD with both wget and curl"
              exit 1
            fi
          fi

          # Verify the zip file was downloaded
          if [ ! -f pmd.zip ] || [ ! -s pmd.zip ]; then
            echo "PMD zip file is missing or empty"
            exit 1
          fi

          # Extract PMD
          echo "Extracting PMD..."
          if ! unzip -q pmd.zip; then
            echo "Failed to extract PMD zip file"
            exit 1
          fi

          # Move PMD to relevant folder and add it to path
          echo "Setting up PMD..."
          if ! mv pmd-bin-${PMD_VERSION} pmd; then
            echo "Failed to move PMD directory"
            exit 1
          fi

          # Add PMD to PATH
          PMD_BIN_PATH="$(pwd)/pmd/bin"
          echo "$PMD_BIN_PATH" >> $GITHUB_PATH
          export PATH="$PMD_BIN_PATH:$PATH"

          # Verify PMD installation with explicit path
          echo "Verifying PMD installation..."
          if ! "$PMD_BIN_PATH/pmd" --version; then
            echo "PMD installation verification failed"
            echo "Checking if PMD binary exists..."
            ls -la "$PMD_BIN_PATH/" || echo "PMD bin directory not found"
            exit 1
          fi

          echo "PMD CLI installed successfully."

          # Clean up
          rm -f pmd.zip

      - name: Install SF plugin 'sfcoepr-review'
        run: |
          echo "Installing SF plugin 'sfcoepr-review'"
          echo "y" | sf plugins install sfcoepr-review --force

      - name: Verify SF plugin installation
        run: |
          echo "Verifying SF plugin installation"
          sf plugins | grep -q sfcoepr-review
          if [ $? -ne 0 ]; then
            echo "Error: SF plugin 'sfcoepr-review' not found after installation attempt."
            echo "Please ensure the plugin name or source is correct and accessible."
            exit 1
          else
            echo "SF plugin 'sfcoepr-review' is successfully installed."
          fi

      - name: Run the AI-assisted Pull Request Review app
        run: |
          # Ensure the tmp-diff and code-analyzer-logs directories exists
          mkdir -p tmp-diff
          mkdir -p code-analyzer/code-analyzer-logs

          # Construct the command with parameters
          SF_COMMAND="sf ks review diff --repo-dir=. --ai-provider=${AI_PROVIDER} --ai-model=${AI_MODEL} --ai-token=${AI_TOKEN} --git-provider=GitHub --git-token=${GIT_TOKEN} --git-owner=${{ github.repository_owner }} --git-repo=${{ github.event.repository.name }} --pull-request-id=${{ github.event.pull_request.number }} --from=${BASE_COMMIT} --to=${HEAD_COMMIT} --ai-api-version=${AI_API_VERSION} --ai-api-endpoint=${AI_API_ENDPOINT}"

          # Print the command
          echo "Executing the command: $SF_COMMAND"

          # Run the command
          $SF_COMMAND

📊 AI Analysis Output

Enhanced GitHub Integration

Intelligent Comment Management

Single Comment Per Analysis: The tool maintains one AI-generated comment per pull request analysis
Update on Re-run: Subsequent runs update the existing comment instead of creating new ones
Clear Bot Identification: All bot comments are clearly marked with recognizable headers and signatures
Backward Compatibility: Supports identifying and updating comments from previous versions

Review Report Structure

The tool generates comprehensive review reports with:

1. Code Quality Review

File-by-file issue breakdown
Rule violations with line numbers
Severity classification (Critical, High, Moderate, Low, Info)

2. AI Suggestion Table

Intelligent issue prioritization
Context-aware suggestions
Code improvement recommendations
Security and performance insights

3. Docusign-Specific Checks

Test framework validation (SObjectMocker vs legacy patterns)
Performance anti-patterns (Schema.getGlobalDescribe() usage)
Security compliance checks
Custom DocuSign development best practices

4. Observability Features (on Datadog, if enabled)

Real-time logging with configurable levels
Performance metrics and execution timing
Error tracking with stack traces
Custom metrics for analysis results

📄 License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

🆘 Support

Common Issues

1. Missing AI Token

Error: Missing required flag: --ai-token

Solution: Set your AI provider token as an environment variable or pass it directly.

2. Git Repository Not Found

Error: Not a git repository

Solution: Ensure you're running the command in a Git repository or specify --repo-dir.

3. No Changes Detected

No issues found in analysis

Solution: Verify there are actual code changes between the specified commits/branches.

4. GitHub API Issues

Comment Update vs Creation: The tool now intelligently updates existing AI comments instead of creating duplicates. If you see multiple AI comments from older versions, they will be consolidated on the next run.

Bot Comment Not Updating: If the tool creates new comments instead of updating existing ones, ensure the previous comments contain the proper bot identification markers.

GitHub API Rate Limits: If you encounter rate limiting issues:

Use a personal access token with appropriate permissions
Ensure the token has repo and pull_request scopes
Consider running analysis less frequently in CI/CD

🐛 Additional Troubleshooting

5. File Analysis Issues

No supported files found for analysis

Solution: The tool supports multiple file types including:

Salesforce: .cls, .trigger, .page, .component, .cmp
JavaScript/TypeScript: .js, .ts, .mjs, .cjs
Web: .html, .htm, .css, .xhtml, .xht, .shtml
Database: .sql, .pks, .pkb, .prc, .fnc, .trg, .typ, .tps, .tpb
Java: .java
Aura Components: .cmp
Visualforce: .page, .component
Metadata: .xml, .json, .yaml, .yml

Ensure your repository contains files with these extensions.

6. Datadog Integration Issues

Failed to initialize Datadog logger

Solution: Datadog integration is optional. If not using observability features, you can omit the DD_API_KEY environment variable.

🔮 Roadmap

[ ] Additional AI Providers: Support for Google Gemini
[ ] More Git Providers: BitBucket, GitLab integration
[ ] Enhanced Analysis: Code complexity metrics, technical debt assessment
[ ] IDE Integration: VS Code extension
[ ] Workflow Templates: Pre-built CI/CD configurations
[ ] Custom Rule Development: SDK for creating custom analysis rules
[ ] Comment Management: Advanced comment threading and resolution tracking
[ ] Multi-language Support: Expanded language coverage for static analysis
[ ] Performance Optimization: Caching and incremental analysis
[ ] Security Enhancements: Advanced secret detection and vulnerability scanning

Made by SF COE Team, with ❤️ for our Salesforce Developer Community

sfcoepr-review

Smart Code AI Reviewer

Table of Contents

🚀 Overview

📋 Prerequisites

Static Analysis Tools

🚀 Installation

As a Salesforce CLI Plugin

💻 Usage

Basic Command Structure

Required Flags

Optional Flags

📚 Examples

Basic Local Analysis

Integration with GitHub Action

🏗️ Architectural Components

1. Core Command Layer

2. Git Integration Layer

3. Static Analysis Layer

4. AI Integration Layer

5. Configuration Layer

🛠️ Tools & Technologies

Core Technologies

Static Analysis Tools

AI Providers

Git Integration

Development Tools

🔄 Workflow Integration

CI/CD Pipeline Integration

📊 AI Analysis Output

Enhanced GitHub Integration

Intelligent Comment Management

Review Report Structure

1. Code Quality Review

2. AI Suggestion Table

3. Docusign-Specific Checks

4. Observability Features (on Datadog, if enabled)

📄 License

🆘 Support

Common Issues

1. Missing AI Token

2. Git Repository Not Found

3. No Changes Detected

4. GitHub API Issues

🐛 Additional Troubleshooting

5. File Analysis Issues

6. Datadog Integration Issues

🔮 Roadmap

Readme

Keywords

Package Sidebar

Install

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads