[Feature]: allow discovery using external tools

[buffcode]

Problem Statement

Currently, Sugar has some hard-coded rules to auto-detect code quality issues. For continuous delivery, it would be nice to have external commands that can supply input.

Current limitations:

• Static, built-in rule set cannot adapt to project-specific tooling
• No standardized way to incorporate existing CI/CD quality gates
• Teams cannot leverage their established linting/analysis configurations
• Manual intervention required to feed external tool findings into Sugar

Proposed Solution

Allow an array of tools to be added for code_quality. As tools usually have their own configuration regarding inclusion and exclusion of files/directories, they should be able to run on the root_path.

Output of the tools should be fed back to Sugar via Claude Code, in order to avoid error-prone conversion/mapping of tool outputs to Sugar CLI arguments.

Configuration example:

# sugar.config.yaml
code_quality:
  external_tools:
    - name: eslint
      command: "npx eslint . --format json"
      severity_mapping:
        error: urgent
      
    - name: phpstan
      command: "vendor/bin/phpstan analyse --error-format=json"
      
    - name: sonarqube
      command: "sonar-scanner -Dsonar.login=$SONAR_TOKEN"
      api_endpoint: "https://sonar.example.com/api/issues/search"

Architecture flow

flowchart TB
    subgraph Sugar["Sugar 🍰 Core"]
        Config[Configuration Parser]
        Orchestrator[Tool Orchestrator]
        CLI[Sugar CLI]
    end
    
    subgraph External["External Tools"]
        ESLint[ESLint]
        PHPStan[PHPStan]
        SonarQube[SonarQube]
        Custom[Custom Tools...]
    end
    
    subgraph Output["Output Processing"]
        ClaudeCode[Claude Code]
        Parser[Output Parser]
    end
    
  
    Config --> Orchestrator
    Orchestrator --> ESLint
    Orchestrator --> PHPStan
    Orchestrator --> SonarQube
    Orchestrator --> Custom
    
    ESLint --> Parser
    PHPStan --> Parser
    SonarQube --> Parser
    Custom --> Parser
    
    Parser --> ClaudeCode
    ClaudeCode --> CLI

Loading

Example Claude Code prompt that could be used to process tool output:

You are an AI assistant integrated into Sugar, an autonomous development system.
Your task is to interpret raw output from code quality tools and convert it into
Sugar tasks using the `sugar add` CLI.

## Sugar CLI Reference
```
sugar add [OPTIONS] TITLE
--type TEXT               Type of task
--priority INTEGER        Priority (1=low, 5=urgent)
--description TEXT        Detailed description
--urgent                  Mark as urgent (priority 5)
--status [pending|hold]   Initial task status
--stdin                   Read task data from stdin (JSON format)
```

## Your Responsibilities

1. **Parse** the raw tool output (JSON, XML, or plain text)
2. **Group** related issues into logical tasks (NOT one task per warning!)
3. **Prioritize** based on severity and blocking status
4. **Output** executable shell commands using `sugar add`

## Grouping Strategy

Create ONE task for:
- All issues of the same rule in the same file
- All issues of the same rule in the same directory (if <10 occurrences)
- Logically connected issues (e.g., missing PropTypes for same component)

NEVER create hundreds of individual tasks for lint warnings!

## Priority Mapping

| Condition                              | Priority |
|----------------------------------------|----------|
| Security vulnerability (Critical/High) | 5        |
| Blocking error / CI failure            | 4        |
| Error (non-blocking)                   | 3        |
| Warning (code smell)                   | 2        |
| Info / style suggestion                | 1        |

## Important Rules

- Group aggressively - a codebase with 500 warnings should produce ~20-50 tasks, not 500
- Use heredoc (`cat << 'EOF'`) for multi-line descriptions with markdown
- Include file paths, line numbers, and rule IDs in descriptions
- Add auto-fix commands when available
- Set status to "hold" for issues that need human decision

Alternatives Considered

Option A: External Wrapper Script

Have some other tool run those external tools in a loop and call the Sugar CLI.

Pros:

• Works with current Sugar implementation
• No changes required to Sugar core

Cons:

• Error-prone output mapping
• No unified configuration
• Duplicated orchestration logic
• Harder to maintain consistency

Option B: Pre-processing Pipeline

Create a separate pre-processor that normalizes all tool outputs before Sugar.

Pros:

• Single entry point for all tools
• Standardized format

Cons:

• Additional component to maintain
• Loses tool-specific context
• Extra processing step

Option C: Native Integration (Proposed) ✅

Native support for external tools with Claude Code interpretation.

Pros:

• Unified configuration
• Intelligent output parsing via Claude Code
• No error-prone mappings
• Extensible architecture

Cons:

• Requires Sugar core changes
• Initial implementation effort

Feature Type

Integration

Priority

High - Very important

Use Case

1. Gradually Reduce Non-Blocking Warnings (ESLint)
   Scenario: A legacy JavaScript codebase has 2,500+ ESLint warnings accumulated over years.

2. Gradually Fix Deprecation Errors (PHPUnit)
   Scenario: PHP project needs to upgrade from Symfony 5 to Symfony 8 with 150+ deprecation notices.

3. Gradually Work on Code Smells / technical debt (SonarQube)
   Scenario: SonarQube reports 400 code smells with varying severity and technical debt estimates.

4. Security Vulnerability Remediation (Snyk/Dependabot)
   Scenario: Security scanner identifies 30 vulnerable dependencies with available patches.

5. TypeScript Migration from JavaScript (tsc)
   Scenario: Gradual TypeScript adoption in a large JS project with 500 files.

6. Accessibility Compliance (axe-core/pa11y)
   Scenario: Web application needs WCAG 2.1 AA compliance, with 200+ accessibility violations.

7. Docker/Container Best Practices (Hadolint/Trivy)
   Scenario: Dockerfile linter reports 50 best practice violations.

8. Code Coverage Gaps (Jest/PHPUnit Coverage)
   Scenario: Coverage report shows 150 uncovered functions.

9. License Compliance (FOSSA/License Finder)
   Scenario: License scanner finds 20 dependencies with incompatible licenses.

Additional Context

❤️ the current work!

[cdnsteve]

Great suggestion! Investigating this more

[buffcode]

I have already implemented this in our meevagmbh/sugar-ai repo with some enhancements

[cdnsteve]

Ah, is this separate from the PR here? #10
Oh nvm, I see it listed above here: meevagmbh#2
I'll check

[cdnsteve]

Hey @buffcode - reviewed your external tools implementation and the dogfooding results, looks great. I noticed PR #11 got closed - mind re-opening it or submitting a fresh PR? Would love to get this merged.