forcedotcom/sf-skills / skills/dx-apexguru-scan
dx-apexguru-scan
VerifiedRun an ApexGuru performance scan on a Salesforce Apex project via the ApexGuru SFAP Scan API. Zips the project's Apex (any layout), submits it, polls to completion, decodes the base64 report, and presents performance antipattern violations (SOQL in loop, DML in loop, Schema.getGlobalDescribe(), SOQL without WHERE/LIMIT, unused SOQL fields) grouped by rule with severity, file:line, and suggested fixes — clearly attributed as 'Static only' or 'Production insights'. TRIGGER when the user says 'run ApexGuru', 'ApexGuru scan', 'check Apex performance', 'find governor-limit / performance antipatterns', 'SOQL in loop', 'scan my Apex for performance', or 'ApexGuru performance insights'. DO NOT TRIGGER for general static analysis or security scans (use dx-code-analyzer-run), for fixing code without scanning, or for onboarding an org to ApexGuru.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 20.4 KB |
| examples/README.md | markdown | 2.8 KB |
| examples/sample-decoded-summary.json | config | 4.3 KB |
| examples/sample-full-no-runtime-response.json | config | 27.6 KB |
| examples/sample-succeeded-response.json | config | 1.7 KB |
| references/api-reference.md | markdown | 2.5 KB |
| references/authentication.md | markdown | 7.1 KB |
| references/error-handling.md | markdown | 3.7 KB |
| references/violation-catalog.md | markdown | 2.1 KB |
| scripts/build-zip.shexecutable | script | 3.8 KB |
| scripts/decode-report.jsexecutable | script | 19.4 KB |
| scripts/resolve-token.shexecutable | script | 9.8 KB |
| scripts/run-scan.shexecutable | script | 6.5 KB |
| scripts/scan.shexecutable | script | 3.7 KB |
| scripts/validate-token.js | script | 5.5 KB |
references/error-handling.md
View on GitHub# Error Handling Guide
`run-scan.sh` emits `{error, httpStatus, status, hint}` on failure and maps each HTTP
status to an actionable hint. Relay the hint to the user.
## HTTP status codes
| Code | Likely cause | Resolution |
|------|--------------|------------|
| **400** | Malformed zip, no Apex inside, or over size limit | Re-package with `build-zip.sh` (collects every `.cls`/`.trigger` and checks the 200MB compressed limit). If genuinely large, scope to a subset of the project. Decompressed limit is 1GB. |
| **401** | Token bad or expired | Re-authenticate the Salesforce org (or supply a fresh `sfap_api` JWT via `APEXGURU_SFAP_TOKEN`). The endpoint is routed to the token's environment automatically. See `authentication.md`. |
| **403** | Scan owned by a different org | The token's `tnk`-claim org must match the scan owner. Use the token for the org that submitted the scan. |
| **404** | Unknown `scanId`, or scan archived | Scans are GC'd after ~30 days. Re-submit to get a fresh `scanId`. |
## Scan `status: FAILED`
The poll returns `FAILED` with a `message`. Surface the message verbatim, address the
stated cause, and re-submit. This is distinct from an HTTP error — the request
succeeded but the scan itself failed server-side.
## Timeout (scan didn't finish)
`run-scan.sh` polls up to `--max-polls` × `--interval` seconds (default 40 × 15s =
10 min). If it times out:
- Large projects legitimately take longer → re-run with `--max-polls 80`.
- Or add `--fast` to skip LLM-heavy fix generation.
## `analysisMode` and the three ApexGuru states
**Not an error.** The API's `analysisMode` plus the presence of runtime metrics
(`cpu_time_percentage` on any violation) distinguish three states. `decode-report.js`
handles all three automatically — this is background for interpreting the output:
| State | `analysisMode` | Runtime metrics | Header | What it means |
|-------|----------------|-----------------|--------|---------------|
| Not onboarded | `static` | none | **Static only** | The org is **not onboarded** to ApexGuru — only source-only analysis ran. |
| Onboarded, no runtime data yet | `full` | none | **Static only** | The org **is onboarded**, but there's no runtime data for this code yet. Result is static-equivalent. |
| Onboarded, enriched | `full` | present | **Production insights** | Onboarded **and** runtime metrics were applied (CPU hotspots, severity adjusted from production performance). |
Runtime data is populated by ApexGuru's weekend runs, or on demand from Scale
Center. So `full` + no runtime data is expected for a freshly-onboarded org or
newly-added code — it is **not** an error, and re-scanning won't change it until
runtime data exists. `decode-report.js --present` prints the correct guidance line
for each state ("generate a runtime report in Scale Center"); print it verbatim.
## Missing local prerequisites
| Symptom | Fix |
|---------|-----|
| `no SFAP token found` | No authenticated org and no token env var. Print the script's `hint` verbatim as the entire message — do not add framing or alternative instructions: "Sign in to an authorized Salesforce org to run an ApexGuru scan and compare your code against production performance data." |
| `token scope does not include sfap_api` | Re-mint the token with the `sfap_api` scope. Pre-empts a 401. |
| `token expired Ns ago` | Re-mint a fresh SFAP token and retry. Pre-empts a 401. |
| `no Apex (.cls/.trigger) files found` | Point `build-zip.sh` at a folder that contains Apex classes or triggers (any layout — an sfdx project, a `force-app/` subtree, or a loose folder of `.cls` files) |
| `zip: command not found` / `jq: command not found` | Install the missing tool (`brew install jq`, etc.) |
| `network error submitting scan` | Check connectivity/VPN to the API host |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |