@salesforce/afv-skills 1.22.0 → 1.23.0

package/skills/running-code-analyzer/references/vendor-file-handling.md

@@ -1,239 +0,0 @@
-# Vendor File Handling
-
-## Problem
-
-Code Analyzer scans all JavaScript files, including third-party vendor libraries like jQuery, Bootstrap, Lodash, Handlebars, etc. These libraries often trigger thousands of violations, especially:
-
-- **no-var** (legacy `var` declarations)
-- **prefer-const** (variables that could be const)
-- **code style** (indentation, quotes, semicolons)
-
-A typical scan might find:
-- **9,714 total violations**
-- **9,089 in vendor files** (jQuery UI, Bootstrap, tablesorter)
-- **634 in project source** (your Aura/LWC components)
-
-## Why You Shouldn't Fix Vendor Files
-
-| Risk | Impact |
-|------|--------|
-| **Breaks upgrades** | Modified vendor files can't be cleanly upgraded to newer versions |
-| **Untested changes** | Libraries weren't designed for strict mode or modern JS patterns |
-| **Subtle bugs** | Converting `var` to `let/const` can change scope/hoisting behavior in legacy code |
-| **Maintainability** | Future developers won't know the file was modified and why |
-| **Wasted effort** | The next library upgrade will overwrite your fixes anyway |
-
-## Solutions
-
-### Solution 1: Re-scan with --target (Fastest)
-
-If you know your project source locations upfront:
-
-```bash
-sf code-analyzer run --rule-selector <selector> \
-  --target "force-app/main/default/aura,force-app/main/default/lwc" \
-  --output-file "./results-project-only.json" \
-  --include-fixes
-```
-
-**Pros:**
-- Only scans what you need
-- Faster execution
-- Cleaner results
-
-**Cons:**
-- Must know target directories upfront
-- Doesn't show you what violations exist in vendor files (for awareness)
-
-### Solution 2: Intelligent Filtering (Most Accurate)
-
-Scan everything first, then use the intelligent filter script to separate vendor from project:
-
-```bash
-# 1. Run full scan
-sf code-analyzer run --rule-selector <selector> \
-  --output-file "./results-all.json" --include-fixes
-
-# 2. Filter to project files only
-node "<skill_dir>/scripts/filter-violations.js" \
-  "./results-all.json" \
-  "./results-project.json" \
-  --report
-
-# 3. Apply fixes to filtered results
-node "<skill_dir>/scripts/apply-fixes.js" "./results-project.json"
-```
-
-**Pros:**
-- Intelligent classification using multiple heuristics
-- Shows you vendor vs project breakdown
-- Handles uncertain files (30-70% confidence)
-- No manual pattern maintenance
-
-**Cons:**
-- Scans more files than necessary
-- Takes longer for large codebases
-
-## How the Intelligent Filter Works
-
-The `filter-violations.js` script uses a **multi-heuristic confidence scoring system**:
-
-### 1. Path-Based Signals (30% weight)
-
-```javascript
-// High confidence vendor indicators
-node_modules/          → 100% vendor
-bower_components/      → 100% vendor
-vendor/                → 95% vendor
-third-party/           → 95% vendor
-StaticResourceSources/ → 70% vendor
-
-// Project source indicators
-force-app/main/default/aura/    → Project
-force-app/main/default/lwc/     → Project
-```
-
-### 2. Name-Based Signals (30% weight)
-
-```javascript
-// Filename patterns
-*.min.js               → 95% vendor (minified)
-*-1.12.1.js           → 85% vendor (version in name)
-jquery*.js            → 85% vendor (known library)
-bootstrap*.js         → 85% vendor (known library)
-
-// Checked against package.json dependencies
-```
-
-### 3. Content-Based Signals (40% weight)
-
-```javascript
-// License headers
-MIT License, Apache, BSD, GPL → 80% vendor
-
-// Minification indicators
-Average line length > 500 chars → 90% vendor
-< 10 lines but > 5KB file     → 85% vendor
-
-// Library patterns
-UMD/AMD/CommonJS wrapper       → 70% vendor
-@version x.x.x                 → 65% vendor
-@author (non-project)          → 50% vendor
-```
-
-### Final Score
-
-```
-Weighted Score = (PathScore × 0.3) + (NameScore × 0.3) + (ContentScore × 0.4)
-
-> 70% = Vendor file
-< 30% = Project file
-30-70% = Uncertain (manual review)
-```
-
-## Example Output
-
-```
-=== INTELLIGENT VENDOR FILE DETECTION ===
-
-Original violations: 9714
-Filtered violations: 634
-Reduction: 9080 (93.5%)
-
-📦 Vendor files excluded: 127
-   610 violations | 95% confidence | jquery-ui-1.12.1.js
-        located in vendor directory, version number in filename, minified file
-   525 violations | 98% confidence | jquery-ui-1.12.1.min.js
-        located in vendor directory, minified file (.min.js)
-   ... and 125 more vendor files
-
-✅ Project files included: 39
-   157 violations | CRLP_RollupHelper.js
-   103 violations | HH_ContainerHelper.js
-   84 violations | CRLP_FilterGroupHelper.js
-   ...
-
-⚠️  Uncertain files: 2
-    These files have 30-70% vendor confidence - review manually:
-   45 violations | 55% vendor | customUtility.js
-        located in vendor directory
-
-✓ Filtered results written to: ./results-project.json
-```
-
-## Workflow Integration
-
-### When to Use Each Approach
-
-| Scenario | Recommended Approach |
-|----------|---------------------|
-| User says "fix no-var in my code" | Use intelligent filter (excludes vendor by default) |
-| User says "fix all no-var" | Ask: "Including vendor files (jQuery, Bootstrap)?" |
-| User specifies path | Use --target directly |
-| User wants report first | Full scan → intelligent filter → show breakdown |
-
-### Step-by-Step Workflow
-
-```markdown
-1. Run Code Analyzer scan
-2. Parse results
-3. **Check violation distribution:**
-   - If 50%+ are in vendor files → offer intelligent filtering
-   - If user said "my code" or "project" → automatically filter
-4. Discover fixes (on filtered or unfiltered results)
-5. Apply fixes
-6. Summarize
-```
-
-## Edge Cases
-
-### Case 1: Vendored Modified Libraries
-
-**Scenario:** Your org has modified a copy of jQuery
-
-**Solution:** The intelligent filter will classify it as vendor, but violations may be legitimate. Options:
-1. Fix manually after filter identifies it
-2. Re-run with --target excluding that specific file
-3. Add to project exceptions in filter script
-
-### Case 2: Project Code in Static Resources
-
-**Scenario:** Your custom JavaScript is in `staticresources/` alongside vendor libs
-
-**Solution:** The filter checks content + name, not just path. Custom code without vendor markers scores as "project" or "uncertain" for manual review.
-
-### Case 3: Uncertain Classifications
-
-**Scenario:** File scores 30-70% vendor confidence
-
-**Action:** Filter script reports these separately. Review manually:
-- Check file purpose
-- Look for original source/documentation
-- Decide whether to fix or exclude
-
-## Configuration (Future Enhancement)
-
-The filter script could accept custom patterns:
-
-```bash
-node filter-violations.js results.json filtered.json \
-  --exclude-patterns "*.min.js,jquery*,bootstrap*" \
-  --include-patterns "force-app/main/default/aura/**,force-app/main/default/lwc/**"
-```
-
-Currently uses intelligent defaults and doesn't require configuration.
-
-## Testing the Filter
-
-```bash
-# Run with detailed report
-node scripts/filter-violations.js \
-  ./code-analyzer-results-20260519-133252.json \
-  ./filtered-output.json \
-  --report
-
-# Check the output
-node scripts/parse-results.js ./filtered-output.json
-```
-
-Compare before/after violation counts to verify filtering accuracy.

package/skills/running-code-analyzer/scripts/apply-fixes.js

@@ -1,86 +0,0 @@
-#!/usr/bin/env node
-// Apply engine-provided auto-fixes to source files
-// Usage: node apply-fixes.js <path-to-results.json>
-// WARNING: This modifies files in place. Ensure you have backups or are using version control.
-
-const fs = require("fs");
-const path = require("path");
-
-if (process.argv.length < 3) {
-  console.error("Usage: node apply-fixes.js <results-file.json>");
-  process.exit(1);
-}
-
-const filePath = process.argv[2];
-const data = JSON.parse(fs.readFileSync(filePath, "utf8"));
-const runDir = data.runDir || "";
-
-// Group fixes by file
-const fileFixesMap = new Map();
-data.violations.forEach(v => {
-  if (v.fixes && v.fixes.length > 0) {
-    v.fixes.forEach(fix => {
-      const loc = fix.location;
-      let filePath = loc.file;
-      if (runDir && filePath.startsWith(runDir)) filePath = filePath.substring(runDir.length + 1);
-
-      if (!fileFixesMap.has(filePath)) fileFixesMap.set(filePath, []);
-      fileFixesMap.get(filePath).push({
-        startLine: loc.startLine,
-        startColumn: loc.startColumn,
-        endLine: loc.endLine,
-        endColumn: loc.endColumn,
-        fixedCode: fix.fixedCode,
-        rule: v.rule
-      });
-    });
-  }
-});
-
-// Sort fixes by line/column (descending) to apply bottom-up
-// This ensures earlier fixes don't shift line numbers for later ones
-fileFixesMap.forEach((fixes, file) => {
-  fixes.sort((a, b) => {
-    if (b.startLine !== a.startLine) return b.startLine - a.startLine;
-    return b.startColumn - a.startColumn;
-  });
-});
-
-// Apply fixes to each file
-let filesModified = 0;
-let fixesApplied = 0;
-let fixesSkipped = 0;
-
-fileFixesMap.forEach((fixes, filePath) => {
-  try {
-    const content = fs.readFileSync(filePath, "utf8");
-    const lines = content.split("\n");
-
-    fixes.forEach(fix => {
-      const startIdx = fix.startLine - 1;
-      const endIdx = fix.endLine - 1;
-      if (startIdx < 0 || endIdx >= lines.length || startIdx > endIdx) {
-        fixesSkipped++;
-        return;
-      }
-
-      // Handle multi-line replacements: splice out old lines, insert new content
-      const firstLine = lines[startIdx];
-      const lastLine = lines[endIdx];
-      const before = firstLine.substring(0, fix.startColumn - 1);
-      const after = lastLine.substring(fix.endColumn - 1);
-      const replacement = before + fix.fixedCode + after;
-
-      // Remove the spanned lines and insert the replacement
-      lines.splice(startIdx, endIdx - startIdx + 1, replacement);
-      fixesApplied++;
-    });
-
-    fs.writeFileSync(filePath, lines.join("\n"), "utf8");
-    filesModified++;
-  } catch (err) {
-    console.error("Error fixing " + filePath + ": " + err.message);
-  }
-});
-
-console.log(JSON.stringify({ success: true, filesModified, fixesApplied, fixesSkipped, totalFixableFiles: fileFixesMap.size }));

package/skills/running-code-analyzer/scripts/describe-rule.js

@@ -1,382 +0,0 @@
-#!/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;
-}