@salesforce/afv-skills 1.10.0 → 1.12.0

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

@@ -0,0 +1,34 @@
+# 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

@@ -0,0 +1,29 @@
+# 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

@@ -0,0 +1,96 @@
+# 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/quick-start.md

@@ -0,0 +1,28 @@
+# 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

@@ -0,0 +1,83 @@
+# 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

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

@@ -0,0 +1,239 @@
+# 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

@@ -0,0 +1,86 @@
+#!/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/discover-fixes.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+// Version: v1.0 | SHA256: 19ec035f7132dc162b54a931cfdd882aa473ad80aa21a8a4be1f1127d75168e5
+// Discover which violations have engine-provided auto-fixes
+// Usage: node discover-fixes.js <path-to-results.json>
+
+const fs = require("fs");
+
+if (process.argv.length < 3) {
+  console.error("Usage: node discover-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 || "";
+
+const fixesByRule = {};
+let totalFixable = 0;
+
+data.violations.forEach(v => {
+  if (v.fixes && v.fixes.length > 0) {
+    totalFixable++;
+    const rule = v.rule;
+    if (!fixesByRule[rule]) fixesByRule[rule] = { engine: v.engine, count: 0, severity: v.severity };
+    fixesByRule[rule].count++;
+  }
+});
+
+const topRules = Object.entries(fixesByRule)
+  .sort((a, b) => b[1].count - a[1].count)
+  .slice(0, 10)
+  .map(([rule, info]) => ({ rule, ...info }));
+
+console.log(JSON.stringify({ totalFixable, totalViolations: data.violations.length, topRules }));