@salesforce/afv-skills 1.16.0 → 1.18.0

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

@@ -0,0 +1,286 @@
+# 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/scripts/describe-rule.js

@@ -0,0 +1,382 @@
+#!/usr/bin/env node
+// Version: v1.1 | SHA256: placeholder
+// Get detailed description and documentation for a Code Analyzer rule
+// Usage: node describe-rule.js <rule-name> [--engine <engine>]
+//
+// This script runs `sf code-analyzer rules --view detail` with a targeted
+// selector and parses the output to extract rule details including description,
+// severity, tags, and documentation resources.
+//
+// The CLI output format is:
+//   === 1. RuleName
+//       severity:    2 (High)
+//       engine:      pmd
+//       tags:        Recommended, Security, Apex
+//       resource:    https://...
+//       description: Some description text
+
+const { execSync } = require("child_process");
+
+function printUsage() {
+  console.error(`Usage: node describe-rule.js <rule-name> [--engine <engine>]
+
+Arguments:
+  <rule-name>          The rule name to look up (case-insensitive partial match)
+
+Options:
+  --engine <engine>    Narrow lookup to a specific engine (pmd, eslint, cpd, etc.)
+
+Examples:
+  node describe-rule.js ApexCRUDViolation
+  node describe-rule.js ApexCRUDViolation --engine pmd
+  node describe-rule.js no-var --engine eslint
+  node describe-rule.js OperationWithLimitsInLoop`);
+  process.exit(1);
+}
+
+// Parse CLI arguments
+const args = process.argv.slice(2);
+if (args.length < 1 || args[0] === "--help" || args[0] === "-h") {
+  printUsage();
+}
+
+const ruleName = args[0];
+let engine = null;
+
+for (let i = 1; i < args.length; i++) {
+  if (args[i] === "--engine" && args[i + 1]) {
+    engine = args[++i].toLowerCase();
+  }
+}
+
+// Build the rule selector for the lookup
+const selector = engine ? `${engine}:${ruleName}` : ruleName;
+
+// Run `sf code-analyzer rules` with --view detail to get full rule info
+let rawOutput;
+try {
+  const cmd = `sf code-analyzer rules --rule-selector "${selector}" --view detail 2>&1`;
+  rawOutput = execSync(cmd, {
+    encoding: "utf8",
+    timeout: 60000,
+    maxBuffer: 2 * 1024 * 1024,
+  });
+} catch (err) {
+  // execSync throws on non-zero exit, but we still want the output
+  rawOutput = err.stdout || err.stderr || (err.output && err.output.join("")) || "";
+  if (!rawOutput) {
+    console.log(JSON.stringify({
+      status: "error",
+      message: `Failed to run sf code-analyzer rules: ${err.message}`,
+    }));
+    process.exit(0);
+  }
+}
+
+// Parse the detail view output
+// Format: === N. RuleName\n    key: value\n    key: value\n
+const rules = parseDetailOutput(rawOutput);
+
+if (rules.length === 0) {
+  // Try grep fallback for partial/substring match
+  const grepResult = tryGrepFallback(ruleName, engine);
+  if (grepResult) {
+    console.log(JSON.stringify(grepResult));
+    process.exit(0);
+  }
+
+  // Try fuzzy match as final fallback (catches typos like "Violtion" → "Violation")
+  const fuzzyResult = tryFuzzyFallback(ruleName, engine);
+  if (fuzzyResult) {
+    console.log(JSON.stringify(fuzzyResult));
+    process.exit(0);
+  }
+
+  console.log(JSON.stringify({
+    status: "not_found",
+    message: `Rule "${ruleName}" not found${engine ? ` in engine "${engine}"` : ""}. Verify the rule name with: sf code-analyzer rules --rule-selector ${engine || "all"} 2>&1 | grep -i "${ruleName}"`,
+  }));
+  process.exit(0);
+}
+
+// Find exact match (case-insensitive)
+const exactMatch = rules.find(
+  (r) => r.name.toLowerCase() === ruleName.toLowerCase()
+);
+
+if (exactMatch) {
+  console.log(JSON.stringify({
+    status: "success",
+    rule: exactMatch,
+  }));
+} else if (rules.length === 1) {
+  // Single result, use it
+  console.log(JSON.stringify({
+    status: "success",
+    rule: rules[0],
+  }));
+} else {
+  // Multiple matches
+  console.log(JSON.stringify({
+    status: "multiple_matches",
+    message: `Found ${rules.length} rules matching "${ruleName}":`,
+    candidates: rules.map((r) => ({
+      name: r.name,
+      engine: r.engine,
+      severity: r.severity,
+      tags: r.tags.join(", "),
+    })),
+  }));
+}
+
+/**
+ * Parse the `sf code-analyzer rules --view detail` output format.
+ *
+ * Expected format:
+ *   === 1. RuleName
+ *       severity:    2 (High)
+ *       engine:      pmd
+ *       tags:        Recommended, Security, Apex
+ *       resource:    https://pmd.github.io/...
+ *       description: Validates that CRUD permissions...
+ */
+function parseDetailOutput(output) {
+  const rules = [];
+  const lines = output.split("\n");
+
+  let currentRule = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Match rule header: === N. RuleName (must have a number prefix)
+    // Skip "=== Summary" which is the footer section
+    const headerMatch = line.match(/^===\s+(\d+)\.\s+(.+)$/);
+    if (headerMatch) {
+      if (currentRule && currentRule.name) {
+        rules.push(currentRule);
+      }
+      currentRule = {
+        name: headerMatch[2].trim(),
+        engine: "unknown",
+        severity: "unknown",
+        tags: [],
+        description: "",
+        resources: [],
+      };
+      continue;
+    }
+
+    // Skip lines if no current rule context
+    if (!currentRule) continue;
+
+    // Match key-value pairs (indented with spaces):
+    //     severity:    3 (Moderate)
+    //     engine:      eslint
+    //     tags:        Recommended, BestPractices, JavaScript
+    //     resource:    https://...
+    //     description: Some text here
+    const kvMatch = line.match(/^\s{2,}(\w+):\s+(.+)$/);
+    if (kvMatch) {
+      const key = kvMatch[1].toLowerCase();
+      const value = kvMatch[2].trim();
+
+      switch (key) {
+        case "severity":
+          currentRule.severity = value;
+          break;
+        case "engine":
+          currentRule.engine = value;
+          break;
+        case "tags":
+          currentRule.tags = value.split(",").map((t) => t.trim()).filter(Boolean);
+          break;
+        case "resource":
+          currentRule.resources.push(value);
+          break;
+        case "description":
+          currentRule.description = value;
+          // Description may continue on next lines (indented further)
+          while (
+            i + 1 < lines.length &&
+            lines[i + 1].match(/^\s{14,}/) &&
+            !lines[i + 1].match(/^\s{2,}\w+:/)
+          ) {
+            i++;
+            currentRule.description += " " + lines[i].trim();
+          }
+          break;
+      }
+    }
+  }
+
+  // Push the last rule
+  if (currentRule && currentRule.name) {
+    rules.push(currentRule);
+  }
+
+  return rules;
+}
+
+/**
+ * Fallback: grep the full rule list for partial matches
+ */
+function tryGrepFallback(ruleName, engine) {
+  try {
+    const sel = engine || "Recommended";
+    const cmd = `sf code-analyzer rules --rule-selector "${sel}" 2>&1 | grep -i "${ruleName}"`;
+    const grepOutput = execSync(cmd, {
+      encoding: "utf8",
+      timeout: 60000,
+      maxBuffer: 2 * 1024 * 1024,
+    });
+
+    if (!grepOutput.trim()) return null;
+
+    // Parse table output lines
+    // Format: index  name  engine  severity  tags
+    const candidates = grepOutput
+      .trim()
+      .split("\n")
+      .filter((line) => line.trim() && !line.startsWith("─") && !line.startsWith("="))
+      .slice(0, 10)
+      .map((line) => {
+        const parts = line.trim().split(/\s{2,}/);
+        // Try to identify which part is the rule name (usually index 1 after the row number)
+        if (parts.length >= 4) {
+          return {
+            name: parts[1] || parts[0],
+            engine: parts[2] || "unknown",
+            severity: parts[3] || "unknown",
+            tags: parts[4] || "",
+          };
+        }
+        return { name: line.trim(), engine: "unknown", severity: "unknown", tags: "" };
+      });
+
+    if (candidates.length === 0) return null;
+
+    return {
+      status: "multiple_matches",
+      message: `Rule "${ruleName}" not found as exact match. Found ${candidates.length} potential matches:`,
+      candidates,
+    };
+  } catch (err) {
+    return null;
+  }
+}
+
+/**
+ * Fuzzy fallback: get all rule names and find closest matches by edit distance.
+ * Catches typos like "ApexCRUDVioltion" → "ApexCRUDViolation"
+ */
+function tryFuzzyFallback(ruleName, engine) {
+  try {
+    const sel = engine || "Recommended";
+    const cmd = `sf code-analyzer rules --rule-selector "${sel}" 2>&1`;
+    const output = execSync(cmd, {
+      encoding: "utf8",
+      timeout: 60000,
+      maxBuffer: 2 * 1024 * 1024,
+    });
+
+    // Extract rule names from table output
+    // Lines with rule data have: index  name  engine  severity  tags
+    const ruleNames = [];
+    const ruleInfo = {};
+    output.split("\n").forEach((line) => {
+      const parts = line.trim().split(/\s{2,}/);
+      if (parts.length >= 4 && /^\d+$/.test(parts[0])) {
+        const name = parts[1];
+        ruleNames.push(name);
+        ruleInfo[name] = {
+          name: name,
+          engine: parts[2] || "unknown",
+          severity: parts[3] || "unknown",
+          tags: parts[4] || "",
+        };
+      }
+    });
+
+    if (ruleNames.length === 0) return null;
+
+    // Score each rule by edit distance to the query
+    const queryLower = ruleName.toLowerCase();
+    const scored = ruleNames
+      .map((name) => ({
+        name,
+        distance: levenshtein(queryLower, name.toLowerCase()),
+        // Also check if query is a subsequence (handles missing chars)
+        containsSubseq: isSubsequence(queryLower, name.toLowerCase()),
+      }))
+      .filter((r) => {
+        // Only include if distance is reasonable (within 30% of query length)
+        const maxDistance = Math.max(3, Math.floor(ruleName.length * 0.3));
+        return r.distance <= maxDistance || r.containsSubseq;
+      })
+      .sort((a, b) => a.distance - b.distance)
+      .slice(0, 5);
+
+    if (scored.length === 0) return null;
+
+    const candidates = scored.map((s) => ({
+      ...ruleInfo[s.name],
+      distance: s.distance,
+    }));
+
+    // If the best match is very close (distance <= 2), mark as likely match
+    const best = scored[0];
+    if (best.distance <= 2) {
+      return {
+        status: "multiple_matches",
+        message: `Rule "${ruleName}" not found. Did you mean "${best.name}"? (${best.distance} character${best.distance === 1 ? "" : "s"} different)`,
+        candidates,
+      };
+    }
+
+    return {
+      status: "multiple_matches",
+      message: `Rule "${ruleName}" not found. Closest matches by name similarity:`,
+      candidates,
+    };
+  } catch (err) {
+    return null;
+  }
+}
+
+/**
+ * Levenshtein edit distance between two strings
+ */
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      if (a[i - 1] === b[j - 1]) {
+        dp[i][j] = dp[i - 1][j - 1];
+      } else {
+        dp[i][j] = 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+      }
+    }
+  }
+
+  return dp[m][n];
+}
+
+/**
+ * Check if 'query' is a subsequence of 'target' (handles missing chars)
+ * e.g., "CRUDVioltion" is a subsequence of "CRUDViolation"
+ */
+function isSubsequence(query, target) {
+  let qi = 0;
+  for (let ti = 0; ti < target.length && qi < query.length; ti++) {
+    if (query[qi] === target[ti]) qi++;
+  }
+  // Consider it a match if at least 80% of query chars appear in order
+  return qi >= query.length * 0.8;
+}