opencode-sonarqube 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manuel Guttmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,409 @@
+# opencode-sonarqube
+
+OpenCode Plugin for SonarQube integration - Enterprise-level code quality from the start.
+
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://sonarqube.example.com)
+[![Quality Gate](https://img.shields.io/badge/quality%20gate-passed-brightgreen)](https://sonarqube.example.com)
+[![Tests](https://img.shields.io/badge/tests-626%20passing-brightgreen)](https://sonarqube.example.com)
+[![License](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+## Features
+
+- **Automatic Analysis**: Triggers SonarQube analysis when the AI agent becomes idle
+- **15 Tool Actions**: Comprehensive SonarQube integration for AI agents
+- **Clean as You Code**: Focus on new code issues with `newissues` action
+- **Custom Command**: Use `/sonarqube` command for quick analysis
+- **Security Hotspots**: Review and track security hotspots requiring manual review
+- **Quality Gate Integration**: Shows pass/fail status with detailed metrics
+- **Git Integration**: Detects git operations and suggests quality checks
+- **Pre-commit Validation**: Warns about blockers before commit (enterprise mode)
+- **System Prompt Injection**: AI always knows current quality status
+- **Toast Notifications**: Visual feedback on analysis completion
+- **Session Compaction**: Preserves analysis state across session compaction
+- **Multi-Language Support**: Works with any language SonarQube supports
+- **Auto-Fix Mode**: Optionally let the agent fix issues automatically
+- **Enterprise Levels**: Configure strictness (enterprise/standard/relaxed/off)
+
+## Quick Start
+
+### One-Line Installation
+
+```bash
+# Interactive installation (recommended)
+bash <(curl -fsSL https://raw.githubusercontent.com/mguttmann/opencode-sonarqube/main/scripts/install.sh)
+
+# Or download and run:
+curl -fsSL https://raw.githubusercontent.com/mguttmann/opencode-sonarqube/main/scripts/install.sh -o install.sh
+chmod +x install.sh && ./install.sh
+```
+
+For CI/automation (non-interactive):
+
+```bash
+export SONAR_URL=https://your-sonarqube-server.com
+export SONAR_USER=admin
+export SONAR_PASSWORD=your-password
+curl -fsSL https://raw.githubusercontent.com/mguttmann/opencode-sonarqube/main/scripts/install.sh | bash
+```
+
+The installer will:
+1. Check prerequisites (Bun/npm)
+2. Ask for SonarQube server URL, username, and password
+3. Test the connection
+4. Configure `opencode.json`
+5. Set up environment variables
+
+**Important: Restart OpenCode after installation!**
+
+### Manual Installation
+
+```bash
+# Install package
+bun add opencode-sonarqube
+
+# Or with npm
+npm install opencode-sonarqube
+```
+
+Add to your `opencode.json`:
+
+```json
+{
+  "plugin": ["opencode-sonarqube"]
+}
+```
+
+**Important:** Configuration is done via environment variables (NOT in opencode.json):
+
+```bash
+export SONAR_HOST_URL="https://your-sonarqube-server.com"
+export SONAR_USER="admin"
+export SONAR_PASSWORD="your-password"
+```
+
+Add these to your `~/.zshrc` or `~/.bashrc` to make them permanent.
+
+## Configuration
+
+### Using the Configuration Script
+
+```bash
+./scripts/configure.sh
+```
+
+This interactive script allows you to:
+- Update SonarQube URL
+- Change credentials
+- Test connection
+- Reset project state
+
+### Environment Variables (Required)
+
+| Variable | Description |
+|----------|-------------|
+| `SONAR_HOST_URL` | SonarQube server URL (e.g., `https://sonarqube.example.com`) |
+| `SONAR_USER` | Username for authentication |
+| `SONAR_PASSWORD` | Password for authentication |
+
+### Default Behavior
+
+The plugin uses these defaults (configurable in future versions):
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| Level | `enterprise` | Strictest quality requirements |
+| Auto-Analyze | `true` | Analyze when AI becomes idle |
+| Auto-Fix | `false` | Don't auto-fix issues |
+| Sources | `src` | Source directory |
+
+### Strictness Levels
+
+| Level | Behavior |
+|-------|----------|
+| `enterprise` | All rules active, blocks on blocker/critical/major, requires 80%+ coverage |
+| `standard` | Major+ rules, blocks on blocker/critical |
+| `relaxed` | Only blocker/critical, blocks on blocker |
+| `off` | Plugin disabled |
+
+## Tool Actions (15 total)
+
+The plugin adds a `sonarqube` tool with these actions:
+
+### Setup & Analysis
+
+| Action | Description |
+|--------|-------------|
+| `setup` / `init` | Initialize project (auto-creates on SonarQube if needed) |
+| `analyze` | Run full analysis, return issues |
+
+### Issue Investigation
+
+| Action | Description |
+|--------|-------------|
+| `issues` | Get all current issues |
+| `newissues` | Get only issues in NEW code (Clean as You Code) |
+| `worstfiles` | Show files with most issues (prioritize refactoring) |
+| `hotspots` | Get security hotspots that need manual review |
+| `duplications` | Find code duplications across the project |
+
+### Status & Validation
+
+| Action | Description |
+|--------|-------------|
+| `status` | Get quality gate status and metrics |
+| `validate` | Check if project meets enterprise quality standards |
+| `metrics` | Show detailed code metrics with trends |
+
+### Information
+
+| Action | Description |
+|--------|-------------|
+| `rule` | Explain a specific SonarQube rule (requires `ruleKey`) |
+| `history` | Show past analysis history |
+| `profile` | Show quality profile configuration |
+| `branches` | Show branch analysis status |
+
+### Tool Options
+
+```typescript
+sonarqube({
+  action: "analyze" | "issues" | "newissues" | "worstfiles" | "status" | 
+          "validate" | "hotspots" | "duplications" | "rule" | "history" |
+          "profile" | "branches" | "metrics" | "setup",
+  scope: "all" | "new" | "changed",     // What to analyze
+  severity: "blocker" | "critical" | "major" | "minor" | "info" | "all",
+  fix: true | false,                     // Include fix suggestions
+  projectKey: "override-key",            // Optional override
+  force: true | false,                   // Force re-initialization
+  ruleKey: "typescript:S1234",           // For "rule" action
+  branch: "feature-branch"               // For multi-branch analysis
+})
+```
+
+## Automatic Behaviors
+
+The plugin automatically handles many scenarios without user intervention:
+
+### Session Start
+- Checks for existing issues
+- Injects quality status into system prompt
+- AI is immediately aware of code quality state
+
+### File Changes
+- Tracks all edited files during the session
+- When agent becomes idle, runs automatic analysis (if `autoAnalyze: true`)
+- Notifies of any new issues introduced
+
+### Git Operations
+
+| Operation | Automatic Behavior |
+|-----------|-------------------|
+| `git pull` / `git merge` | Suggests checking for new issues |
+| `git checkout` (with changes) | Suggests running analysis |
+| `git commit` (enterprise mode) | Warns if BLOCKER/CRITICAL issues exist |
+| `git push` | Shows notification that code was pushed |
+
+### System Prompt Injection
+- Quality gate status is injected into every conversation
+- AI always knows: issue counts, quality gate status, failed conditions
+- No need to manually check - AI proactively addresses quality issues
+
+### Session Compaction
+- Quality context is preserved when session is compacted
+- Long conversations maintain awareness of code quality state
+
+## Usage Examples
+
+### Via AI Agent Tool
+
+```
+User: "Implement user authentication"
+
+Agent: I'll implement user authentication. Let me first check the current code quality.
+[Uses sonarqube({ action: "status" })]
+
+Agent: Quality gate is passing. Now implementing the feature...
+[Writes code in src/auth/...]
+
+Agent: Let me analyze the new code.
+[Uses sonarqube({ action: "newissues" })]
+
+Result:
+## New Code Issues (Clean as You Code)
+**Issues in New Code:** 2
+
+### CRITICAL (1)
+- **src/auth/login.ts:15** - Hardcoded password detected
+  Rule: `typescript:S2068`
+
+Agent: I found a critical issue. Let me fix it...
+[Fixes the hardcoded password]
+[Uses sonarqube({ action: "analyze" })]
+
+Result:
+## SonarQube Analysis Results
+**Quality Gate: [PASS] OK**
+No issues in new code!
+```
+
+### Common Workflows
+
+```typescript
+// Initialize project (first run)
+sonarqube({ action: "setup" })
+
+// Run analysis with fix suggestions
+sonarqube({ action: "analyze", fix: true })
+
+// Check only YOUR recent changes (Clean as You Code)
+sonarqube({ action: "newissues" })
+
+// Find files that need most attention
+sonarqube({ action: "worstfiles" })
+
+// Get only critical issues
+sonarqube({ action: "issues", severity: "critical" })
+
+// Understand a rule
+sonarqube({ action: "rule", ruleKey: "typescript:S3776" })
+
+// Enterprise validation before release
+sonarqube({ action: "validate" })
+```
+
+## CLI Usage
+
+```bash
+# Initialize project (first run)
+bun run src/index.ts --setup
+
+# Run analysis
+bun run src/index.ts --analyze
+
+# Check quality gate status
+bun run src/index.ts --status
+
+# View current issues
+bun run src/index.ts --issues
+
+# View security hotspots
+bun run src/index.ts --hotspots
+
+# Override project key
+bun run src/index.ts --status --project-key=my-project
+
+# Force re-initialize
+bun run src/index.ts --setup --force
+```
+
+## Programmatic API
+
+```typescript
+import { 
+  createSonarQubeAPI, 
+  loadConfig, 
+  getProjectState,
+  runAnalysis,
+  bootstrap 
+} from "opencode-sonarqube";
+
+// Create API client
+const config = loadConfig();
+const state = await getProjectState("./");
+const api = createSonarQubeAPI(config, state);
+
+// Health check
+const health = await api.healthCheck();
+console.log("Healthy:", health.healthy);
+
+// Get issues
+const issues = await api.issues.getFormattedIssues({
+  projectKey: "my-project",
+  severities: ["BLOCKER", "CRITICAL"],
+});
+
+// Get quality gate status
+const status = await api.qualityGate.getStatus("my-project");
+console.log("Status:", status.projectStatus.status);
+
+// Get new code issues only
+const newIssues = await api.issues.search({
+  projectKey: "my-project",
+  inNewCode: true,
+});
+
+// Get worst files for refactoring
+const worstFiles = await api.components.getWorstFiles("my-project", 10);
+
+// Run full analysis
+const result = await runAnalysis(config, state, { projectKey: "my-project" }, "./");
+console.log("Quality Gate:", result.qualityGateStatus);
+```
+
+See [API Documentation](./docs/API.md) for complete reference.
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [API Reference](./docs/API.md) | Complete API documentation |
+| [Architecture](./docs/ARCHITECTURE.md) | System architecture and design |
+| [SonarQube Setup](./docs/SONARQUBE_SETUP.md) | Server installation guide |
+| [Contributing](./CONTRIBUTING.md) | Development guidelines |
+| [Changelog](./CHANGELOG.md) | Version history |
+
+## API Modules
+
+The plugin provides 12 API modules for SonarQube interaction:
+
+| Module | Purpose |
+|--------|---------|
+| `ProjectsAPI` | Create, search, delete projects |
+| `IssuesAPI` | Search issues, get counts, format for display |
+| `QualityGateAPI` | Check status, validate enterprise quality |
+| `RulesAPI` | Get rule details and explanations |
+| `SourcesAPI` | Fetch source code context for issues |
+| `DuplicationsAPI` | Find code duplications |
+| `ComputeEngineAPI` | Track analysis task status |
+| `ProjectAnalysesAPI` | Get analysis history |
+| `QualityProfilesAPI` | Get active quality profiles |
+| `BranchesAPI` | Multi-branch analysis management |
+| `MetricsAPI` | Get detailed metrics with period comparison |
+| `ComponentsAPI` | Get files/directories with issue counts |
+
+## Requirements
+
+- SonarQube server 9.9+ (tested with 26.1)
+- Node.js 18+ or Bun
+- OpenCode with plugin support
+
+## Quality Metrics
+
+This project maintains enterprise-level quality:
+
+| Metric | Value |
+|--------|-------|
+| Test Coverage | 100% |
+| Tests | 626 |
+| Bugs | 0 |
+| Vulnerabilities | 0 |
+| Code Smells | 0 |
+| Duplications | 0% |
+| Quality Gate | Passed |
+| Reliability Rating | A |
+| Security Rating | A |
+| Maintainability Rating | A |
+
+## License
+
+MIT
+
+## Author
+
+Manuel Guttmann
+
+## Links
+
+- [GitHub Repository](https://github.com/mguttmann/opencode-sonarqube)
+- [Issue Tracker](https://github.com/mguttmann/opencode-sonarqube/issues)
+- [SonarQube Documentation](https://docs.sonarqube.org/)