dx-code-analyzer-run

# Running Code Analyzer Skill ## CRITICAL: Mandatory Script Usage Every interaction with Code Analyzer results MUST go through the bundled scripts in `<skill_dir>/scripts/`. No exceptions. ### WRONG — never do this: ```bash # WRONG: inline Python to parse results python3 -c "import json; data = json.load(open('results.json'))..." # WRONG: inline Node.js to parse results node -e "const data = require('./results.json')..." # WRONG: jq to filter results cat results.json | jq '.violations[] | select(.engine=="pmd")' # WRONG: reading the results file directly (it can be 10MB+) Read tool → code-analyzer-results-*.json ``` Also forbidden: `run_code_analyzer` and any `mcp__*` tool — Bash only. ### RIGHT — always do this: ```bash # Summarize scan results node "<skill_dir>/scripts/parse-results.js" "./code-analyzer-results-TIMESTAMP.json" # Filter/rank/query results (by engine, severity, file, rule, category) node "<skill_dir>/scripts/query-results.js" "./code-analyzer-results-TIMESTAMP.json" --engine pmd --summary # List/browse available rules (by engine, category, language, severity) node "<skill_dir>/scripts/list-rules.js" "Security" --top 10 # Look up what a rule means node "<skill_dir>/scripts/describe-rule.js" "ApexCRUDViolation" --engine pmd # Discover fixable violations node "<skill_dir>/scripts/discover-fixes.js" "./code-analyzer-results-TIMESTAMP.json" # Apply fixes (after user confirms) node "<skill_dir>/scripts/apply-fixes.js" "./code-analyzer-results-TIMESTAMP.json" # Summarize applied fixes node "<skill_dir>/scripts/summarize-fixes.js" "./code-analyzer-results-TIMESTAMP.json" # Filter vendor files (jQuery, Bootstrap, *.min.js) before applying fixes node "<skill_dir>/scripts/filter-violations.js" "./code-analyzer-results-TIMESTAMP.json" "./code-analyzer-results-TIMESTAMP-filtered.json" --report ``` `<skill_dir>` is the absolute path to the directory containing this SKILL.md. **Never** use `./scripts/` — that resolves against the user's CWD, not the skill dir. Any aggregation, filter, or rank question ("which file has the most violations?", "how many PMD issues?", "top rules by count", "break down by severity") is answered by `query-results.js` — its output already includes `topRules`, `topFiles`, and `severityCounts`. --- ## Overview > **Ecosystem:** This skill is part of a 3-skill Code Analyzer suite — `dx-code-analyzer-run` (scans & results) · `dx-code-analyzer-configure` (setup, config, CI/CD) · `dx-code-analyzer-custom-rule-create` (custom rule authoring). This skill translates natural-language requests ("scan for security issues", "check my changes") into the correct `sf code-analyzer run` command, executes scans across 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 it for static analysis, security reviews, AppExchange certification, code-quality checks, and finding duplicates/vulnerabilities in Salesforce projects. **In scope:** running scans, parsing/filtering/ranking results, applying engine auto-fixes, diff-based scans, all output formats (JSON/HTML/SARIF/CSV/XML), describing/listing rules, scan-failure troubleshooting. **Out of scope:** installing/configuring `sf` or the plugin (→ `dx-code-analyzer-configure`), writing custom rules/engines (→ `dx-code-analyzer-custom-rule-create`), AI-generated fixes beyond engine-provided ones, deep refactoring, CI/CD setup (→ `dx-code-analyzer-configure`). **Allowed tools:** Bash (`sf code-analyzer`, `node`, `git diff`, `date`), Read, Write, Edit. **Forbidden:** any MCP tool, Agent tool, web tools, other skills, Python, `jq`, inline scripts/heredocs. This skill owns the complete scan-fix-verify-query-explain workflow end-to-end. --- ## Command Syntax Rules (READ FIRST — ABSOLUTE) 1. The command is **`sf code-analyzer run`** — NOT `sf scanner run` (deprecated v3). 2. **No `--format` flag.** Use `--output-file <path>.<ext>`; the extension determines the format. 3. **Always** pass `--output-file` with a timestamped name (e.g., `./code-analyzer-results-20260512-143022.json`) — do not rely on stdout. 4. **Foreground only** (no `run_in_background`); timeout 1200000ms for large scans. 5. **Invalid v3 flags** that cause errors: `--format`, `--engine`, `--category`, `--json`. Use `--rule-selector` + `--output-file` instead. 6. **Tool restriction:** Bash, Read, Write, Edit only. No MCP tools, no Agent tool, no web tools, no other skills. Why: the v4+ CLI redesigned the flag interface; v3 flags now error. Full flag/selector docs: `<skill_dir>/references/flag-reference.md`. --- ## Prerequisites User needs: **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). Pre-flight: run `sf code-analyzer --help 2>&1 | head -1`. If that fails, or if a scan reports an engine startup error (e.g., "PMD failed to start", "java: command not found", "SFGE failed"): 1. **Stop** — do not attempt to install/diagnose prerequisites yourself. 2. **Delegate to `dx-code-analyzer-configure`** — it handles all setup. 3. After it finishes, return here and re-run the scan. If a scan fails for other reasons, see `<skill_dir>/references/error-handling.md`. --- ## Quick Start: Common Patterns Match the request below; if it matches, jump to Step 3 (Build Command). Otherwise, walk Step 1. | User Says | Rule Selector | Notes | |-----------|---------------|-------| | "scan my code" / "run code analyzer" | `Recommended` | Curated set, all file types | | "check for security issues" / "security review" | `all:Security:(1,2)` | All engines, Critical+High | | "scan my changes" / "check the diff" | (see Step 1.5) | Get files via `git diff`, filter to scannable types, pass via `--target` | | "run PMD" / "check my Apex" | `pmd` | Apex classes and triggers | | "lint my LWC" / "check my JavaScript" | `eslint` | JavaScript/TypeScript/LWC | | "find duplicates" / "check for copy-paste" | `cpd` | Code clones | | "check for vulnerabilities" / "scan libraries" | `retire-js` | JavaScript library CVEs | | "deep analysis" / "data flow analysis" | `sfge` | Java 11+, 10–20 min, use `--workspace "force-app"` | | "performance analysis" / "governor limits" | `apexguru` | Authenticated org required | | "analyze my Flows" | `flow` | `--target **/*.flow-meta.xml`, Python 3 | | "AppExchange security review" | `all:Security:(1,2)` | See `<skill_dir>/references/special-behaviors.md` → AppExchange | --- ## Step 1: Parse the User's Intent Analyze the request along these 7 dimensions; any can combine. ### 1.1 ENGINE PMD/Apex → `pmd` · ESLint/JS/TS/lint → `eslint` · Flows → `flow` · duplicates/CPD → `cpd` · vulnerabilities/CVE/RetireJS → `retire-js` · SFGE/data flow → `sfge` · performance/ApexGuru → `apexguru` · regex → `regex` · everything → `all` · unspecified → `Recommended`. ### 1.2 CATEGORY security/OWASP → `Security` · performance → `Performance` · best practices → `BestPractices` · style/format → `CodeStyle` · design/complexity → `Design` · bugs → `ErrorProne` · docs → `Documentation`. ### 1.3 SEVERITY 1=Critical · 2=High · 3=Moderate · 4=Low · 5=Info. "critical only" → `1` · "critical+high" → `(1,2)` · "moderate and above" → `(1,2,3)`. ### 1.4 SPECIFIC RULE If the user names a rule (e.g., "ApexCRUDViolation", "no-unused-vars"): `--rule-selector <engine>:<ruleName>`, or just `<ruleName>` if engine is ambiguous. **Partial names:** `--rule-selector` requires the **exact full** rule name (e.g., `@salesforce-ux/slds/no-hardcoded-values-slds2`, not `no-hardcoded-values`). No wildcards. If you are not 100% certain, look it up first — **do not guess**: ```bash sf code-analyzer rules --rule-selector all 2>&1 | grep -i "USER_KEYWORD" ``` Multiple matches → ask the user which. Zero matches → tell the user nothing matched. ### 1.5 TARGET specific path → `--target <path>` · glob ("all Apex") → `--target **/*.cls,**/*.trigger` · "my changes"/"diff" → `git diff --name-only [base]...HEAD`, filter to scannable types, pass as `--target` · "LWC" → `--target **/lwc/**` · "Flows" → `--target **/*.flow-meta.xml` · unspecified → omit (entire workspace). Diff-filtering details: `<skill_dir>/references/special-behaviors.md`. ### 1.6 OUTPUT **Default JSON.** Only change if the user explicitly asks. Name: `./code-analyzer-results-<YYYYMMDD-HHmmss>.<ext>` via `TIMESTAMP=$(date +%Y%m%d-%H%M%S)`. Formats: `.json` (default), `.html`, `.sarif`, `.csv`, `.xml`. ### 1.7 COMPARISON / DELTA "new since main" → `git diff --name-only main...HEAD` → scan those · "since last commit" → `HEAD~1` · "vs develop" → `develop...HEAD`. --- ## Step 2: Build the Rule Selector Syntax: `:` = AND, `,` = OR, `()` = grouping. - 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: `all` More: `<skill_dir>/references/command-examples.md`. --- ## Step 3: Build the Full Command ```bash TIMESTAMP=$(date +%Y%m%d-%H%M%S) 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 ``` - Default to timestamped JSON; only change format on explicit request. - Always pass `--include-fixes` (enables Step 6 auto-fix). - Omit `--target` to scan the whole workspace. - Diff scans: `git diff --name-only` → filter scannable types → pass as `--target`. Special cases (SFGE/ApexGuru/AppExchange/diff): `<skill_dir>/references/special-behaviors.md`. --- ## Step 4: Execute the Scan Use the **Bash tool only** — never the `run_code_analyzer` MCP tool. 1. Generate the timestamp via Bash: `date +%Y%m%d-%H%M%S` → e.g. `20260512-143022`. 2. Tell the user: ```text Starting scan... Results: ./code-analyzer-results-20260512-143022.json Log: ./code-analyzer-results-20260512-143022.log May take several minutes for large codebases. ``` 3. Run with the **literal** timestamp baked in (not `$TIMESTAMP`), foreground, timeout 1200000ms, `tee` to a `.log`: ```bash 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" ``` 4. Exit 0 = success. On error, read both the log file and `<skill_dir>/references/error-handling.md`. 5. **Immediately** parse results (Step 5) — do not ask the user what to do next. --- ## Step 5: Parse and Present Results Run the parse script straight after the scan — do not pause to ask: ```bash 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 (shell quoting will break) - Read the JSON file directly ### Presentation template ```text ## Scan Complete