@salesforce/afv-skills 1.22.0 → 1.24.0

package/skills/running-code-analyzer/references/engine-reference.md

@@ -1,34 +0,0 @@
-# Engine Reference
-
-## Engine File Type Support
-
-| Engine | File Extensions |
-|---|---|
-| **pmd** | `.cls`, `.trigger`, `.js`, `.html`, `.htm`, `.vfp`, `.component`, `.page`, `.xml` |
-| **eslint** | `.js`, `.ts`, `.jsx`, `.tsx` |
-| **cpd** | `.cls`, `.trigger`, `.js`, `.ts`, `.html`, `.htm`, `.vfp`, `.component`, `.page`, `.xml` |
-| **retire-js** | `.js`, `.ts`, `package.json`, `package-lock.json` |
-| **regex** | Configurable per rule via `file_extensions` |
-| **flow** | `.flow-meta.xml` |
-| **sfge** | `.cls`, `.trigger` |
-| **apexguru** | `.cls`, `.trigger` |
-
-## Common Rule Tags
-
-These tags can be used in rule selectors:
-
-| Tag | Meaning |
-|---|---|
-| `Recommended` | Default ruleset — curated for most projects |
-| `Security` | Security vulnerabilities (CRUD, XSS, injection, crypto) |
-| `Performance` | Performance anti-patterns (SOQL in loops, limits) |
-| `BestPractices` | Coding standards and conventions |
-| `CodeStyle` | Naming, formatting, braces |
-| `Design` | Complexity, coupling, architecture |
-| `ErrorProne` | Common bug patterns |
-| `Documentation` | Missing docs, comments |
-| `Apex` | Rules applying to Apex language |
-| `JavaScript` | Rules applying to JavaScript |
-| `TypeScript` | Rules applying to TypeScript |
-| `HTML` | Rules applying to HTML/Visualforce |
-| `Custom` | User-defined rules |

package/skills/running-code-analyzer/references/error-handling.md

@@ -1,29 +0,0 @@
-# Error Handling Guide
-
-Common Code Analyzer errors and their resolutions.
-
-## Common Errors and Resolutions
-
-| Error Pattern | Likely Cause | Resolution |
-|---|---|---|
-| `command not found: sf` | SF CLI not installed | "Install Salesforce CLI: `npm install -g @salesforce/cli`" |
-| `plugin-code-analyzer` not found | Plugin not installed | "Install: `sf plugins install @salesforce/plugin-code-analyzer`" |
-| `Java not found` / `JAVA_HOME not set` | Java missing/misconfigured | "Install Java 11+. Set JAVA_HOME or add `engines.pmd.java_command` to config" |
-| `Node.js` version error | Old Node version | "Upgrade Node.js to v18+" |
-| `Python` not found (Flow engine) | Python not installed | "Install Python 3. Or set `engines.flow.python_command` in config" |
-| `Config file error` / YAML parse error | Invalid code-analyzer.yml | "Your config file has a syntax error. Run `sf code-analyzer config` to validate" |
-| `No rules matched selector` | Invalid rule selector | Check selector syntax. Run `sf code-analyzer rules --rule-selector <selector>` to verify |
-| `Target file does not exist` | File path typo or deleted | Verify file path exists |
-| `Org not authenticated` (ApexGuru) | No default org | "Authenticate: `sf org login web --alias myorg`" |
-| Timeout / heap space | Large project + SFGE | "Increase heap: add `engines.sfge.java_max_heap_size: '4g'` to code-analyzer.yml" |
-
-## Diagnosis Steps
-
-If the scan command fails:
-
-1. Check the error message for hints
-2. Run `sf --version` to verify CLI
-3. Run `sf plugins --core | grep code-analyzer` to verify plugin
-4. Run `java -version` to verify Java
-5. Run `sf code-analyzer rules --rule-selector <selector>` to verify the selector matches rules
-6. If config error: run `sf code-analyzer config` to validate

package/skills/running-code-analyzer/references/flag-reference.md

@@ -1,96 +0,0 @@
-# Flag Reference for `sf code-analyzer run`
-
-Complete reference for all flags available in the `sf code-analyzer run` command (v4+).
-
-## Valid Flags
-
-| Flag | Short | Type | Description | Default |
-|------|-------|------|-------------|---------|
-| `--rule-selector` | `-r` | String | Rule selection expression (engine, category, severity, or specific rule) | `Recommended` |
-| `--target` | `-t` | String[] | Files/folders/globs to scan (comma-separated) | Current directory |
-| `--workspace` | `-w` | String | Workspace root directory | `.` (current directory) |
-| `--output-file` | `-f` | String[] | Output file path(s) — format determined by extension (.json, .html, .sarif, .csv, .xml) | None (terminal only) |
-| `--view` | `-v` | String | Terminal display format: `table` or `detail` | None |
-| `--severity-threshold` | `-s` | Number | Exit non-zero if violations at or above this level (1-5) | None |
-| `--config-file` | `-c` | String | Path to code-analyzer.yml configuration file | None |
-| `--include-fixes` | | Boolean | Include fix data in results (enables auto-fix capability) | `false` |
-| `--include-suggestions` | | Boolean | Include suggestion data in results | `false` |
-| `--no-suppressions` | | Boolean | Ignore suppression markers in code | `false` |
-| `--target-org` | `-o` | String | Salesforce org username or alias (required for ApexGuru engine) | None |
-
-## Invalid Flags (DO NOT USE)
-
-These flags existed in v3 but were removed in v4+. Using them causes errors:
-
-| Deprecated Flag | Error Message | Replacement |
-|----------------|---------------|-------------|
-| `--format` | `Unknown flag: --format` | Use `--output-file <path>.<ext>` where extension determines format |
-| `--format table` | `Unknown flag: --format` | Use `--view table` or `--view detail` |
-| `--engine` | `Unknown flag: --engine` | Use `--rule-selector <engine>` |
-| `--category` | `Unknown flag: --category` | Use `--rule-selector <category>` |
-| `--json` | `Unknown flag: --json` | Use `--output-file "./results.json"` |
-
-## Rule Selector Syntax
-
-The `--rule-selector` flag uses a flexible expression syntax:
-
-| Syntax | Description | Example |
-|--------|-------------|---------|
-| `<engine>` | Select all rules from an engine | `pmd`, `eslint`, `cpd` |
-| `<category>` | Select rules by category | `Security`, `Performance` |
-| `<severity>` | Select rules by severity (1-5) | `1`, `2`, `(1,2)` |
-| `<engine>:<category>` | Engine AND category | `pmd:Security` |
-| `<engine>:<severity>` | Engine AND severity | `eslint:2` |
-| `(<a>,<b>)` | OR grouping | `(pmd,eslint)` for PMD OR ESLint |
-| `<a>:<b>:<c>` | Multiple AND conditions | `pmd:Security:1` for PMD AND Security AND Severity 1 |
-| `<engine>:<ruleName>` | Specific rule | `pmd:ApexCRUDViolation` |
-| `all` | All available rules | `all` |
-| `Recommended` | Default recommended rule set | `Recommended` (default) |
-
-### Complex Rule Selector Examples
-
-```bash
-# PMD OR ESLint, Security category, Severity 1 or 2
---rule-selector "(pmd,eslint):Security:(1,2)"
-
-# All Security rules across all engines
---rule-selector "Security"
-
-# Specific rule from PMD
---rule-selector "pmd:ApexCRUDViolation"
-
-# All rules from CPD (duplicate detection)
---rule-selector "cpd"
-
-# High and Critical severity across all engines
---rule-selector "(1,2)"
-```
-
-## Output Format Extensions
-
-The `--output-file` flag determines format by file extension:
-
-| Extension | Format | Use Case |
-|-----------|--------|----------|
-| `.json` | JSON | Programmatic parsing, default for this skill |
-| `.html` | HTML | Human-readable report for browser viewing |
-| `.sarif` | SARIF | IDE integration (VS Code, IntelliJ) or GitHub Advanced Security |
-| `.csv` | CSV | Spreadsheet import (Excel, Google Sheets) |
-| `.xml` | XML | Legacy CI/CD systems |
-
-You can specify multiple output files in a single run:
-```bash
---output-file "./results.json" --output-file "./report.html"
-```
-
-## Why These Constraints Exist
-
-**v4+ CLI redesign:** The Code Analyzer plugin underwent a major redesign from v3 to v4+:
-- Old flags (`--format`, `--engine`, `--category`) were removed for a more flexible `--rule-selector` expression syntax
-- Output format is now determined by file extension rather than a separate flag
-- Terminal display was separated into `--view` flag
-- These changes provide more flexibility but require different syntax than v3 documentation shows
-
-**Always use `--output-file` for results:** Terminal stdout can be truncated, interrupted, or mixed with other output. Writing to a file ensures complete, parseable results.
-
-**Foreground execution with timeout:** SFGE (Salesforce Graph Engine) scans can take 10-20 minutes for large codebases. Running in foreground with `timeout: 1200000` (20 minutes) ensures the scan completes and output is captured.

package/skills/running-code-analyzer/references/post-scan-workflows.md

@@ -1,286 +0,0 @@
-# Post-Scan Workflows
-
-After presenting initial scan results (Step 5), the user may ask follow-up questions to explore results or understand violations. This reference covers three post-scan workflows:
-
-1. **Result Querying** — filter/drill into existing results without re-scanning
-2. **Rule Description** — explain what a rule does and how to fix violations
-3. **Rule Listing** — browse available rules without running a scan
-
----
-
-## Result Querying (Step 7)
-
-### When to Use
-
-Trigger this workflow when the user asks to explore existing results:
-- "Show me just the security violations"
-- "What's in AccountService.cls?"
-- "Show only PMD issues"
-- "Filter to severity 1 and 2"
-- "What ESLint rules fired?"
-- "Show violations in the lwc folder"
-- "Top 20 by file"
-
-### How It Works
-
-The `query-results.js` script re-filters the SAME results JSON file (from Step 4) with different criteria. No re-scan is needed — it is instant.
-
-### Script Reference
-
-```bash
-node "<skill_dir>/scripts/query-results.js" "<results-file.json>" [options]
-```
-
-**Filter options (combine any):**
-
-| Option | Description | Example |
-|--------|-------------|---------|
-| `--engine <name>` | Filter by engine | `--engine pmd` |
-| `--severity <n>` | Filter by severity (comma-separated) | `--severity 1,2` |
-| `--category <tag>` | Filter by category/tag | `--category Security` |
-| `--rule <name>` | Filter by exact rule name | `--rule ApexCRUDViolation` |
-| `--file <substring>` | Filter by file path substring | `--file AccountService` |
-| `--top <n>` | Return top N results (default: 10) | `--top 20` |
-| `--sort <field>` | Sort by: severity, rule, engine, file | `--sort file` |
-| `--sort-dir <dir>` | Sort direction: asc, desc | `--sort-dir desc` |
-| `--summary` | Show only counts (no individual violations) | `--summary` |
-
-**Options can be combined freely:**
-```bash
-# Security violations in PMD, top 5
-node "<skill_dir>/scripts/query-results.js" "./results.json" --engine pmd --category Security --top 5
-
-# All Critical+High in a specific file
-node "<skill_dir>/scripts/query-results.js" "./results.json" --severity 1,2 --file AccountService.cls
-
-# Summary of ESLint issues only
-node "<skill_dir>/scripts/query-results.js" "./results.json" --engine eslint --summary
-```
-
-### Output Format
-
-The script outputs JSON with this structure:
-
-```json
-{
-  "query": { "engine": "pmd", "severity": [1,2], ... },
-  "totalViolations": 500,
-  "totalMatches": 23,
-  "severityCounts": { "1": 5, "2": 18, "3": 0, "4": 0, "5": 0 },
-  "topRules": [{ "rule": "ApexCRUDViolation", "engine": "pmd", "count": 12 }, ...],
-  "topFiles": [{ "file": "AccountService.cls", "count": 8 }, ...],
-  "violations": [
-    { "rule": "...", "engine": "...", "severity": 1, "message": "...", "file": "...", "startLine": 42, "tags": [...] },
-    ...
-  ]
-}
-```
-
-When `--summary` is used, the `violations` array is omitted.
-
-### Presentation Rules
-
-Present query results using the same format as Step 5, but with a header indicating the active filter:
-
-```
-## Filtered Results: [description of filter]
-
-**X matches** out of Y total violations.
-
-| Severity | Count |
-|----------|-------|
-| Critical (1) | X |
-| High (2) | X |
-| ... |
-
-### Matching Violations
-| # | Rule | Engine | Sev | File | Line |
-|---|------|--------|-----|------|------|
-| 1 | ... | ... | ... | ... | ... |
-
-### Top Rules (within filter)
-| Rule | Engine | Count |
-|------|--------|-------|
-| ... | ... | ... |
-
-Full results: `<original-results-file>`
-```
-
-### Follow-Up Offers
-
-After presenting filtered results, offer:
-- "Want me to narrow further?" (add more filters)
-- "Want me to explain any of these rules?" (→ Step 8)
-- "Want me to apply fixes for these?" (→ Step 6, scoped to matched rules)
-
----
-
-## Rule Description (Step 8)
-
-### When to Use
-
-Trigger this workflow when the user asks about a specific rule:
-- "What is ApexCRUDViolation?"
-- "Explain this rule"
-- "What does no-var mean?"
-- "How do I fix OperationWithLimitsInLoop?"
-- "Tell me about the ApexSOQLInjection rule"
-- "Why is this flagged?"
-
-### How It Works
-
-The `describe-rule.js` script calls `sf code-analyzer rules` with a targeted selector to extract rule metadata including description and documentation links.
-
-### Script Reference
-
-```bash
-node "<skill_dir>/scripts/describe-rule.js" "<rule-name>" [--engine <engine>]
-```
-
-**Arguments:**
-
-| Argument | Description | Example |
-|----------|-------------|---------|
-| `<rule-name>` | The rule name to look up | `ApexCRUDViolation` |
-| `--engine <engine>` | Narrow to a specific engine (optional) | `--engine pmd` |
-
-**Examples:**
-```bash
-node "<skill_dir>/scripts/describe-rule.js" "ApexCRUDViolation" --engine pmd
-node "<skill_dir>/scripts/describe-rule.js" "no-var" --engine eslint
-node "<skill_dir>/scripts/describe-rule.js" "OperationWithLimitsInLoop"
-```
-
-### Output Format
-
-**Success — single rule found:**
-```json
-{
-  "status": "success",
-  "rule": {
-    "name": "ApexCRUDViolation",
-    "engine": "pmd",
-    "severity": "2 (High)",
-    "tags": ["Security", "Recommended", "Apex"],
-    "description": "Validates that CRUD and FLS checks are performed before DML operations...",
-    "resources": ["https://pmd.github.io/latest/pmd_rules_apex_security.html#apexcrudviolation"]
-  }
-}
-```
-
-**Multiple matches (partial name):**
-```json
-{
-  "status": "multiple_matches",
-  "message": "Rule \"CRUD\" not found as exact match. Found 3 potential matches:",
-  "candidates": [
-    { "name": "ApexCRUDViolation", "engine": "pmd", "severity": "2", "tags": "Security, Recommended" },
-    ...
-  ]
-}
-```
-
-**Not found:**
-```json
-{
-  "status": "not_found",
-  "message": "Rule \"FakeRule\" not found. Verify the rule name with: sf code-analyzer rules ..."
-}
-```
-
-### Presentation Rules
-
-**For a successful lookup**, present:
-
-```
-## Rule: ApexCRUDViolation
-
-| Property | Value |
-|----------|-------|
-| Engine | pmd |
-| Severity | 2 (High) |
-| Tags | Security, Recommended, Apex |
-
-### Description
-Validates that CRUD and FLS checks are performed before DML operations. Without these
-checks, data may be accessed or modified without proper user permissions, violating
-the Salesforce security model.
-
-### How to Fix
-[Provide actionable fix guidance based on the description. If the description mentions
-a fix pattern, elaborate. If resources are available, include the link.]
-
-### Resources
-- [PMD Documentation](https://pmd.github.io/...)
-
----
-Want me to show all violations of this rule in your scan results?
-```
-
-**For multiple matches**, present:
-
-```
-I found multiple rules matching "CRUD":
-
-| # | Rule | Engine | Severity |
-|---|------|--------|----------|
-| 1 | ApexCRUDViolation | pmd | 2 (High) |
-| 2 | ... | ... | ... |
-
-Which rule would you like details on?
-```
-
-**For not found**, present:
-
-```
-I couldn't find a rule named "FakeRule". Would you like me to:
-- Search for similar rules? (I'll grep the full rule list)
-- List all rules for a specific engine or category?
-```
-
-### After Describing a Rule
-
-Offer next steps:
-- "Want me to show all violations of this rule in your results?" (→ Step 7 with `--rule`)
-- "Want me to apply the engine fix for this rule?" (→ Step 6)
-- "Want me to explain another rule?"
-
----
-
-## Rule Listing (Step 9)
-
-### Presentation Rules
-
-Present available rules in this format:
-
-```
-## Available Rules: Security
-
-**Found X rules** across Y engines.
-
-| Engine | Count |
-|--------|-------|
-| pmd | 12 |
-| eslint | 6 |
-
-| Severity | Count |
-|----------|-------|
-| Critical (1) | 3 |
-| High (2) | 15 |
-
-### Rules (top 25)
-| # | Rule | Engine | Severity | Tags |
-|---|------|--------|----------|------|
-| 1 | ApexCRUDViolation | pmd | 2 (High) | Security, Recommended |
-| 2 | ApexSOQLInjection | pmd | 1 (Critical) | Security, Recommended |
-| ... |
-
-Want me to explain any of these rules? Or run a scan with this selector?
-```
-
-### Follow-Up Offers
-
-After listing rules:
-- "Want me to explain any of these?" (→ Step 8)
-- "Want me to scan with this selector?" (→ Steps 1-5 with the same selector)
-- "Narrow to just high severity?" (re-run with `--severity 1,2`)

package/skills/running-code-analyzer/references/quick-start.md

@@ -1,28 +0,0 @@
-# Quick Start: Minimum Viable Commands
-
-If you're unsure about anything, use these EXACT commands as starting points.
-
-**IMPORTANT:** Always generate a timestamp variable FIRST, then use it in the output filename:
-```bash
-TIMESTAMP=$(date +%Y%m%d-%H%M%S)
-```
-
-Then use it:
-```bash
-# Simplest scan (entire workspace, recommended rules)
-sf code-analyzer run --output-file "./code-analyzer-results-${TIMESTAMP}.json" --include-fixes
-
-# Scan specific target
-sf code-analyzer run --target "force-app/main/default" --output-file "./code-analyzer-results-${TIMESTAMP}.json" --include-fixes
-
-# Scan for security
-sf code-analyzer run --rule-selector Security --output-file "./code-analyzer-results-${TIMESTAMP}.json" --include-fixes
-
-# Scan specific engine
-sf code-analyzer run --rule-selector pmd --output-file "./code-analyzer-results-${TIMESTAMP}.json" --include-fixes
-
-# Scan with HTML report (only if user explicitly asks for HTML)
-sf code-analyzer run --output-file "./code-analyzer-results-${TIMESTAMP}.html" --include-fixes
-```
-
-**After the command completes**, read the output file and present a summary to the user.

package/skills/running-code-analyzer/references/special-behaviors.md

@@ -1,83 +0,0 @@
-# Special Behaviors
-
-Advanced scanning scenarios and engine-specific considerations.
-
-## SFGE (Salesforce Graph Engine) Scans
-
-When `--rule-selector sfge` is requested:
-- **WARN the user**: "SFGE performs deep data-flow analysis and can be resource-intensive. It may take several minutes and use significant memory. Proceed?"
-- If project is large (>100 Apex classes), suggest increasing heap: "Consider setting `engines.sfge.java_max_heap_size: '4g'` in your code-analyzer.yml"
-- SFGE only analyzes Apex (`.cls`, `.trigger` files)
-
-### SFGE Workspace Compilation Behavior
-
-**CRITICAL:** SFGE compiles ALL `.cls` and `.trigger` files found anywhere in the `--workspace` directory (default: `.` = project root), NOT just files under `--target`. The `--target` flag only controls which files are used as **entry points** for data-flow analysis, but SFGE builds a complete inter-procedural call graph from the entire workspace.
-
-This means:
-1. If there are invalid/template Apex files ANYWHERE in the project (e.g., `datasets/`, `scripts/`, `templates/`), SFGE will try to compile them and CRASH with compilation errors.
-2. **The `--target` flag does NOT prevent this** — even `--target "force-app"` still causes SFGE to compile files outside `force-app/`.
-
-**To avoid compilation failures, ALWAYS set `--workspace` explicitly for SFGE scans:**
-```bash
-sf code-analyzer run --rule-selector sfge --workspace "force-app" --target "force-app" --output-file "./code-analyzer-results-${TIMESTAMP}.json" --include-fixes
-```
-
-Or if the user specifies a subfolder target like `force-app/main`:
-```bash
-sf code-analyzer run --rule-selector sfge --workspace "force-app" --target "force-app/main" --output-file "./code-analyzer-results-${TIMESTAMP}.json" --include-fixes
-```
-
-The `--workspace` flag restricts which files SFGE compiles into its graph. Set it to the narrowest directory that contains all valid, deployable Apex source code (typically `force-app` or `src`).
-
-## ApexGuru Scans
-
-When `--rule-selector apexguru` is requested:
-- **Check org authentication**: Run `sf org display` first
-- If no org authenticated: Guide user to `sf org login web` or `sf org login jwt`
-- Add `--target-org <alias>` flag if user has specified an org
-- ApexGuru analyzes Apex performance patterns via cloud service
-
-## AppExchange Security Review Scans
-
-When user mentions "AppExchange", "security review", "ISV", "partner":
-- Use `--rule-selector all` to run comprehensive scan
-- Output both JSON and HTML: `--output-file "./code-analyzer-results-${TIMESTAMP}.json" --output-file "./code-analyzer-results-${TIMESTAMP}.html"`
-- In results, categorize violations as:
-  - **Blockers** (sev 1-2, Security tag): MUST fix before submission
-  - **Warnings** (sev 3, Security/BestPractices): Strongly recommended to fix
-  - **Informational** (sev 4-5): Good to fix but won't block review
-- Highlight specific AppExchange-critical rules:
-  - `ApexCRUDViolation` (CRUD/FLS enforcement)
-  - `ApexSharingViolations` (sharing model)
-  - `ApexSOQLInjection` (injection prevention)
-  - `ApexCSRF` (CSRF protection)
-  - `ApexXSSFromEscapeFalse` / `ApexXSSFromURLParam` (XSS prevention)
-  - `ApexInsecureEndpoint` (HTTPS enforcement)
-  - `ApexBadCrypto` (crypto standards)
-  - `ApexSuggestUsingNamedCred` (credential management)
-
-## Diff-Based Scans
-
-When user wants to scan only changed files:
-1. Determine the base reference:
-   - "my changes" / "what I changed" → `git diff --name-only` (unstaged) or `git diff --name-only --cached` (staged)
-   - "branch changes" / "since main" → `git diff --name-only main...HEAD`
-   - "last commit" → `git diff --name-only HEAD~1`
-2. Filter to scannable file types:
-   ```bash
-   git diff --name-only main...HEAD | grep -E '\.(cls|trigger|js|ts|html|css|xml|flow-meta\.xml)$'
-   ```
-3. If no scannable files changed: "No scannable files in your diff. Code Analyzer supports: .cls, .trigger, .js, .ts, .html, .css, .xml, .flow-meta.xml"
-4. Pass filtered files as comma-separated `--target` value
-
-## Large Result Sets (500+ violations)
-
-- Summarize: top 10 rules by frequency, top 10 files by violation count
-- Offer: "Want me to export the full results? Or focus on a specific category/file?"
-- Don't try to display all 500+ violations inline
-
-## Mega Result Sets (5000+ violations)
-
-- Same as above, but also proactively suggest narrowing scope:
-  - "This is a very large number of violations. Want me to focus on just Critical/High severity, a specific category like Security, or a specific folder?"
-- If the user originally said "scan and fix everything", still follow the full flow (scan → present → discover fixes → ask → apply → summarize) — do NOT shortcut any steps just because the result set is large