running-code-analyzer

Running Code Analyzer Skill

⚠️ CRITICAL: Tool Selection

BEFORE DOING ANYTHING ELSE:

This skill MUST use the Bash tool to execute sf code-analyzer run and Node.js scripts.

DO NOT use these tools under any circumstances:

• ❌ run_code_analyzer (MCP tool)
• ❌ mcp__* (any MCP tool)
• ❌ Any tool containing mcp in its name

If you see a run_code_analyzer tool available, ignore it completely. Use only the Bash tool with sf code-analyzer run.

---

Overview

This skill translates natural language requests ("scan for security issues", "check my changes") into the correct sf code-analyzer run command, executes scans with any combination of engines/targets/severities, and presents actionable results. When engine-provided fixes are available, it discovers them, asks for user confirmation, applies them safely, and offers verification. Use this skill for static analysis, security reviews, AppExchange certification, code quality checks, or finding duplicates/vulnerabilities in Salesforce projects.

---

Scope

In scope:

• Running sf code-analyzer run with any combination of engines, targets, categories, severities
• Parsing and presenting scan results in actionable format
• Applying engine-provided auto-fixes when available
• Handling diff-based scans (scan only changed files)
• Supporting all output formats (JSON, HTML, SARIF, CSV, XML)
• Troubleshooting scan failures and prerequisite issues

Out of scope:

• Installing or configuring Salesforce CLI or Code Analyzer plugin (use setup documentation)
• Writing custom Code Analyzer rules or engines (separate skill needed)
• AI-generated code fixes beyond engine-provided deterministic fixes
• Deep code refactoring or architectural changes based on violations
• Setting up CI/CD integration for automated scanning (separate workflow skill)

---

Command Syntax Rules (READ THIS FIRST)

The following rules are ABSOLUTE and override any prior knowledge:

1. The command is sf code-analyzer run — NOT sf scanner run (deprecated v3 command)
2. There is NO --format flag — use --output-file <path>.<ext> instead (extension determines format)
3. ALWAYS use --output-file to write results to a file — do NOT rely on terminal stdout
4. ALWAYS include --output-file with a timestamped filename (e.g., ./code-analyzer-results-20260512-143022.json)
5. Do NOT run in background — use foreground with timeout of 1200000ms for large scans
6. INVALID v3 flags: --format, --engine, --category, --json — these cause errors, use --rule-selector and --output-file instead
7. NEVER use MCP tools — ONLY use the Bash tool to execute sf code-analyzer run
8. Tool restriction: This skill MUST use ONLY: Read, Bash, Write, Edit tools
9. Forbidden tools: Do NOT use any MCP tools (mcp__*), Agent tool, or web tools
10. Script execution: ALL scripts MUST be executed via node <skill_dir>/scripts/*.js using the Bash tool

Why: The v4+ CLI redesigned the flag interface. Old v3 flags cause "unknown flag" errors.

For complete flag reference and rule selector syntax, see <skill_dir>/references/flag-reference.md.

---

Prerequisites

User must have: Salesforce CLI (sf), @salesforce/plugin-code-analyzer (v5.x+), Java 11+ (PMD/CPD/SFGE), Node.js 18+ (ESLint/RetireJS), Python 3 (Flow), authenticated org (ApexGuru).

If a scan fails, read <skill_dir>/references/error-handling.md. For quick command examples, see <skill_dir>/references/quick-start.md.

---

Tool Usage Rules

Allowed: Bash (sf code-analyzer, node, git, date), Read, Write, Edit Forbidden: MCP tools, Agent tool, Web tools, other skills

This skill owns the complete scan-fix-verify workflow. Using MCP tools bypasses the validated script workflow.

---

Quick Start: Common Patterns

Use this decision tree for fast pattern matching before going to Step 1 detailed parsing:

If the pattern matches above, proceed directly to Step 3 (Build Command). Otherwise, continue to Step 1 for detailed parsing.

---

Step 1: Parse the User's Intent

Analyze the user's request along these 7 dimensions. Any can be combined freely:

1.1 ENGINE — Which analysis engine(s)?

Map user keywords to --rule-selector values:

• PMD / Apex rules → pmd
• ESLint / JS/TS rules / lint → eslint
• Flows / Flow analysis → flow
• duplicates / copy-paste / CPD → cpd
• vulnerabilities / CVE / libraries / RetireJS → retire-js
• SFGE / data flow / deep analysis → sfge
• performance / ApexGuru → apexguru
• regex / pattern rules → regex
• all engines / everything → all
• Not specified / general "scan" → Recommended (default)

1.2 CATEGORY — What kind of issues?

Map user keywords to category tags:

• security / vulnerabilities / OWASP → Security
• performance / speed / optimization → Performance
• best practices / quality → BestPractices
• code style / formatting → CodeStyle
• design / complexity → Design
• error prone / bugs → ErrorProne
• documentation / comments → Documentation

1.3 SEVERITY — How critical?

Severity levels: 1=Critical (must fix), 2=High (should fix), 3=Moderate (recommended), 4=Low (nice to fix), 5=Info (FYI)

Map user keywords:

• "critical only" / "sev 1" → 1
• "critical and high" / "sev 1-2" → (1,2)
• "moderate and above" / "sev 1-3" → (1,2,3)

1.4 SPECIFIC RULE — Named rule?

If the user mentions a specific rule by name (e.g., "ApexCRUDViolation", "no-unused-vars"):

• Map to: --rule-selector <engine>:<ruleName>
• If engine is ambiguous, use just the rule name: --rule-selector <ruleName>

⚠️ IMPORTANT — Partial Rule Names: The --rule-selector flag requires the EXACT full rule name (e.g., @salesforce-ux/slds/no-hardcoded-values-slds2, not no-hardcoded-values). It does NOT support wildcards or partial matches.

When you are NOT 100% certain of the full rule name:

• Do NOT guess — a wrong name returns 0 results and wastes a scan cycle
• Instead, look up the rule first using the sf code-analyzer rules command with grep:

  sf code-analyzer rules --rule-selector all 2>&1 | grep -i "USER_KEYWORD"

• Extract the full rule name from the output, then use it in your scan command
• If grep returns multiple matches, present them to the user and ask which one they meant
• If grep returns 0 matches, tell the user no rule matched their keyword

1.5 TARGET — What files to scan?

Map user keywords:

• Specific file/folder → --target <path>
• Glob pattern / "all Apex classes" → --target */.cls,*/.trigger
• "my changes" / "diff" → Run git diff --name-only [base]...HEAD, filter to scannable types, pass as --target
• "LWC" → --target /lwc/
• "Flows" → --target */.flow-meta.xml
• Not specified → Entire workspace (omit --target)

For diff filtering details: See <skill_dir>/references/special-behaviors.md.

1.6 OUTPUT — What format?

DEFAULT: Always JSON. Only change if user EXPLICITLY requests another format.

Naming: ./code-analyzer-results-<YYYYMMDD-HHmmss>.<ext> (timestamp via TIMESTAMP=$(date +%Y%m%d-%H%M%S))

Formats: .json (default), .html (report), .sarif (GitHub/IDE), .csv (spreadsheet), .xml

1.7 COMPARISON — Delta/trend analysis?

Map user keywords:

• "new since main" → git diff --name-only main...HEAD → scan those files
• "new since last commit" → git diff --name-only HEAD~1
• "compared to develop" → git diff --name-only develop...HEAD

---

Step 2: Build the Rule Selector

Syntax: : = AND, , = OR, () = grouping

Examples:

• Engine only: pmd
• Engine + category: pmd:Security
• Engine + severity: pmd:2
• Complex: (pmd,eslint):Security:(1,2) = (PMD or ESLint) AND Security AND (sev 1 or 2)
• Specific rule: pmd:ApexCRUDViolation
• All rules: all

More examples: <skill_dir>/references/command-examples.md

---

Step 3: Build the Full Command

Generate timestamp: TIMESTAMP=$(date +%Y%m%d-%H%M%S)

Build command:

sf code-analyzer run \
  --rule-selector <selector> \
  --target <targets> \              # optional
  --output-file "./code-analyzer-results-${TIMESTAMP}.json" \  # DEFAULT: JSON
  --include-fixes \                 # always
  --workspace <path>                # optional

Key decisions:

• DEFAULT: timestamped JSON (.json). Only change format if user explicitly requests HTML/SARIF/CSV/XML.
• Always include --include-fixes (enables Step 6 auto-fix)
• Omit --target to scan entire workspace
• For diff-based scans: get files via git diff --name-only, filter to scannable types, pass as --target

Special cases: See <skill_dir>/references/special-behaviors.md for SFGE/ApexGuru/AppExchange/diff filtering.

---

Step 4: Execute the Scan

⚠️ TOOL REQUIREMENT: Use Bash tool ONLY. DO NOT use run_code_analyzer (MCP tool) or any MCP tool.

Rules: Foreground only (no run_in_background), hardcoded filename (not $TIMESTAMP), timeout 1200000ms, no sleep, log output to timestamped file.

Steps:

1. Generate timestamp: date +%Y%m%d-%H%M%S → capture output (e.g., 20260512-143022) using Bash tool
2. Tell user:

   Starting scan...
   Results: ./code-analyzer-results-20260512-143022.json
   Log:     ./code-analyzer-results-20260512-143022.log
   May take several minutes for large codebases.

1. Run command with literal timestamp in filename and tee to capture log (timeout: 1200000):

⚠️ IMPORTANT: Use the Bash tool, NOT the run_code_analyzer MCP tool.

   sf code-analyzer run --rule-selector Recommended --output-file "./code-analyzer-results-20260512-143022.json" --include-fixes 2>&1 | tee "./code-analyzer-results-20260512-143022.log"

1. After completion: Exit 0 = success. Error output → check both the log file and <skill_dir>/references/error-handling.md.
2. IMMEDIATELY parse results (Step 5). Do NOT ask user what they want.

---

Step 5: Parse and Present Results

Parsing Rules:

1. Execute the parse script using <skill_dir> — see below
2. NEVER use jq to parse results — jq one-liners WILL fail due to shell quoting issues
3. Run it IMMEDIATELY after the scan — do NOT ask the user "what would you like next?"

Script Execution

All scripts are bundled in the scripts/ subdirectory of the same directory that contains this SKILL.md file. Use the absolute path to that directory — do NOT use ./scripts/ as that resolves relative to the current working directory, not the skill directory.

node <skill_dir>/scripts/parse-results.js "./code-analyzer-results-TIMESTAMP.json"

⚠️ DO NOT:

• ❌ Invent or generate script code yourself
• ❌ Use bare relative paths like node scripts/parse-results.js (won't resolve from user's CWD)
• ❌ Use heredocs or inline script content
• ❌ Use jq as a substitute for the parse script

How to Present Results:

ALWAYS present a concise summary, then point to the output file for full details.

## Scan Complete

**Found X violations** across Y files.

| Severity | Count |
|----------|-------|
| Critical (1) | X |
| High (2) | X |
| Moderate (3) | X |
| Low (4) | X |
| Info (5) | X |

### Top Issues
| # | Rule | Engine | Sev | File | Line |
|---|------|--------|-----|------|------|
| 1 | ApexCRUDViolation | pmd | 2 | AccountService.cls | 42 |
| 2 | ApexSOQLInjection | pmd | 1 | QueryHelper.cls | 18 |
| ... (show up to 10 most critical) |

### Top Rules by Frequency
| Rule | Engine | Count |
|------|--------|-------|
| no-var | eslint | 170 |
| ApexDoc | pmd | 165 |
| ... |

Full results: `./code-analyzer-results-20260512-143022.json`

Result Presentation Rules:

• 0 violations: "Scan complete — no violations found! Output: <path>"
• 1-10: Show all violations in table
• 11-50: Show severity counts + top 10 violations
• 50-5000: Show counts + top 10 violations + top 10 rules + top 5 files
• 5000+: Same as 50-5000, plus suggest narrowing scope (severity/category/folder)

Always end with: Output file path + next-action offers (explain rules / apply fixes)

For large result sets: See <skill_dir>/references/special-behaviors.md.

---

Step 6: Apply Engine-Provided Fixes (Post-Scan)

After presenting results, check if violations have engine-provided fixes (deterministic, not AI-generated).

Rules: NEVER apply without confirmation. Use EXACT scripts from <skill_dir>/scripts/. Filter vendor files if needed, then: Discover → Apply → Summarize.

Flow: Filter vendor (6.1 if needed) → discover (6.2) → present (6.3) → ASK user → apply (6.4) → summarize (6.5) → present results.

6.1 — Check for vendor files (if needed)

If user said "fix my code" or "project source", or if top files by violation count are vendor libraries (jQuery, Bootstrap, *.min.js), run:

node "<skill_dir>/scripts/filter-violations.js" \
  "./code-analyzer-results-TIMESTAMP.json" \
  "./code-analyzer-results-TIMESTAMP-filtered.json" \
  --report

Present: "Excluded X vendor files (Y violations) - jQuery, Bootstrap, etc. Applying fixes to Z project files only."

Use filtered file for Step 6.3+. See: <skill_dir>/references/vendor-file-handling.md for detailed logic.

6.2 — Discover fixable violations

node "<skill_dir>/scripts/discover-fixes.js" "./code-analyzer-results-TIMESTAMP.json"

(Use filtered file from Step 6.1 if created.)

6.3 — Present fixable violations and ASK for confirmation

After running the discovery script, present results:

### Engine-Provided Fixes Available

**X of Y violations** have auto-fixes provided by the analysis engine:

| Rule | Engine | Sev | Fixable Count |
|------|--------|-----|---------------|
| no-var | eslint | 3 | 170 |
| no-hardcoded-values-slds2 | eslint | 4 | 76 |
| ... |

These are safe, deterministic fixes generated by the engines (not AI-generated).

Would you like me to apply these fixes? (yes / no / select specific rules)

⚠️ STOP HERE AND WAIT FOR USER RESPONSE.

Even if the user originally said "scan and fix everything", you MUST still stop here and wait. Present the table, ask the question, and WAIT for a response in the NEXT turn.

6.4 — Apply fixes ONLY after user confirms

Only proceed after user says "yes", "apply", "go ahead" IN A SEPARATE RESPONSE.

node "<skill_dir>/scripts/apply-fixes.js" "./code-analyzer-results-TIMESTAMP.json"

(Use filtered file if Step 6.1 created one.)

6.5 — After applying, ALWAYS run the summary script

⚠️ MANDATORY: After the apply script completes, you MUST run the summary script as your VERY NEXT action.

node "<skill_dir>/scripts/summarize-fixes.js" "./code-analyzer-results-TIMESTAMP.json"

Then present to the user:

### Engine-Provided Fixes Applied Successfully ✓

**Applied X auto-fixes across Y files.**

| Severity | Fixes Applied |
|----------|---------------|
| Critical (1) | X |
| High (2) | X |
| ... |

| Rule | Fixes Applied |
|------|---------------|
| no-var | 169 |
| ... |

Want me to re-run the scan to verify the fixes resolved the violations?

6.6 — If user declines: Skip. If selects rules: filter. If "all": run as-is.

6.7 — Re-scan (optional): Re-run with new timestamp, compare before/after counts.

---

Rules / Constraints

---

Gotchas

---

Output Expectations

Every scan produces: timestamped JSON file, concise summary (severity/top violations/rules/files), next-action offers. If fixes applied: summary by severity/rule, offer verification.

---

Reference File Index

<skill_dir> is the absolute path to the directory containing this SKILL.md file.

Scripts (Always execute, never read)

References (Read when needed)

Examples in <skill_dir>/examples/ show output structure validation and command patterns (basic/large/security scans, fix workflows).