@salesforce/afv-skills 1.28.0 → 1.30.0

package/skills/dx-code-analyzer-custom-rule-create/references/xpath-patterns.md

@@ -0,0 +1,131 @@
+# XPath Patterns for Apex Custom Rules
+
+Pre-validated PMD XPath patterns for Salesforce Apex code. Every pattern below has been verified against actual `sf code-analyzer ast-dump` output. Use these directly — but still run `ast-dump` on YOUR code to confirm node names haven't changed in newer PMD versions.
+
+## XPath Syntax Quick Reference
+
+| Syntax | Meaning |
+|--------|---------|
+| `//Node` | Find Node anywhere in tree |
+| `//Node[@attr='value']` | Node with specific string attribute value |
+| `//Node[@attr = true()]` | Node with boolean attribute = true (**PMD 7 requirement**) |
+| `//Parent//Child` | Child anywhere inside Parent (any descendant) |
+| `//Parent/Child` | **Direct child only** — use this to avoid false positives |
+| `//Node[not(...)]` | Node where condition is NOT true |
+| `//Node[ancestor::Other]` | Node that has Other as an ancestor |
+| `//Node[.//Other]` | Node that contains Other somewhere inside |
+| `@Image` | The name/text of the node |
+| `@FullMethodName` | Full qualified method name (e.g., 'System.debug') |
+| `@LiteralType` | Type of literal: STRING, INTEGER, BOOLEAN, TRUE, FALSE, NULL |
+
+### PMD 7 Boolean Attributes — MUST use `true()` / `false()`
+
+In PMD 7, many node attributes are **boolean typed**, not strings — even though `ast-dump` renders them as `Nested='false'` or `Test='true'` in the XML output. String attributes (`@FullMethodName`, `@Name`, `@Image`, `@LiteralType`, etc.) are safe to copy from the AST dump as-is. But **attributes whose values are `true` or `false` in the dump are boolean-typed** — comparing them with string literals (`@Nested='false'`) causes the error: "Cannot compare xs:boolean to xs:string".
+
+Known boolean attributes by node:
+
+| Node | Boolean Attributes |
+|------|--------------------|
+| `ModifierNode` | `@Test`, `@Public`, `@Private`, `@Protected`, `@Static`, `@Abstract`, `@Final`, `@Global`, `@WithSharing`, `@WithoutSharing`, `@InheritedSharing` |
+| `UserClass` | `@Nested` |
+| `Method` | `@Constructor` |
+
+| WRONG | CORRECT |
+|-------|---------|
+| `UserClass[@Nested='false']` | `UserClass[@Nested = false()]` |
+| `UserClass[@Nested='true']` | `UserClass[@Nested = true()]` |
+| `ModifierNode[@Test='true']` | `ModifierNode[@Test = true()]` |
+| `ModifierNode[@Static='false']` | `ModifierNode[@Static = false()]` |
+| `Method[@Constructor = false()]` | `Method[@Constructor = false()]` |
+
+`true()` and `false()` are XPath boolean functions. If you see an attribute that looks boolean in the AST dump, assume it is typed as boolean and use `true()`/`false()`.
+
+---
+
+### `/` vs `//` — The Most Common Source of False Positives
+
+| XPath | Meaning | Risk |
+|-------|---------|------|
+| `//ForEachStatement//SoqlExpression` | SOQL anywhere inside ForEachStatement | ❌ Matches iterable position too |
+| `//ForEachStatement/BlockStatement//SoqlExpression` | SOQL inside loop **body** only | ✅ Correct |
+
+**Rule of thumb:** When matching inside a structural node (loop, if, try), always scope to `/BlockStatement//` to target the body, not sibling children like iterables or conditions.
+
+---
+
+## Pattern Categories (By Topic)
+
+For detailed patterns in each category, see the dedicated files below:
+
+| Category | File | Contents |
+|----------|------|----------|
+| Governor Limits | [xpath-patterns-governor-limits.md](xpath-patterns-governor-limits.md) | SOQL/DML in loops, Database methods in loops |
+| Method Calls & Annotations | [xpath-patterns-method-calls.md](xpath-patterns-method-calls.md) | Ban specific methods, @AuraEnabled, @future, @IsTest, @SuppressWarnings patterns |
+| Security | [xpath-patterns-security.md](xpath-patterns-security.md) | Sharing declarations, SOQL security modes, hardcoded IDs |
+| Code Structure, Tests & Naming | [xpath-patterns-structure.md](xpath-patterns-structure.md) | DML error handling, empty catches, test assertions, naming conventions |
+
+---
+
+## Key Apex AST Node Names
+
+| Apex Construct | AST Node | Key Attributes |
+|---|---|---|
+| Class | `UserClass` | `Image`, `SuperClassName`, `InterfaceNames`, `Nested` |
+| Interface | `UserInterface` | `Image`, `SuperInterfaceName` |
+| Method | `Method` | `Image`, `Arity`, `ReturnType`, `Constructor` |
+| Trigger | `UserTrigger` | `Image`, `TargetName` |
+| SOQL query | `SoqlExpression` | `Query`, `CanonicalQuery` |
+| DML insert | `DmlInsertStatement` | |
+| DML update | `DmlUpdateStatement` | |
+| DML delete | `DmlDeleteStatement` | |
+| DML upsert | `DmlUpsertStatement` | |
+| Method call | `MethodCallExpression` | `FullMethodName`, `MethodName`, `InputParametersSize` |
+| For-each loop | `ForEachStatement` | children: VariableDeclarationStatements, VariableExpression, **BlockStatement** (body), iterable |
+| For loop | `ForLoopStatement` | children: init, condition, update, **BlockStatement** (body) |
+| While loop | `WhileLoopStatement` | children: condition, **BlockStatement** (body) |
+| If/else | `IfElseBlockStatement` > `IfBlockStatement` | `ElseStatement` |
+| Try-catch | `TryCatchFinallyBlockStatement` | |
+| Catch block | `CatchBlockStatement` | `ExceptionType`, `VariableName` |
+| RunAs | `RunAsBlockStatement` | |
+| String literal | `LiteralExpression` | `@LiteralType='STRING'`, `@Image` (value without quotes) |
+| Integer literal | `LiteralExpression` | `@LiteralType='INTEGER'`, `@Image` |
+| Boolean true | `LiteralExpression` | `@LiteralType='TRUE'` |
+| Boolean false | `LiteralExpression` | `@LiteralType='FALSE'` |
+| Null | `LiteralExpression` | `@LiteralType='NULL'` |
+| Variable | `VariableExpression` | `@Image` (name) |
+| Assignment | `AssignmentExpression` | `@Op` (=, +=, etc.) |
+| Binary expression | `BinaryExpression` | `@Op` (+, -, *, /) |
+| Boolean expression | `BooleanExpression` | `@Op` (>, <, ==, !=, >=, <=) |
+| New object | `NewKeyValueObjectExpression` | `@Type` |
+| New object (no-arg) | `NewObjectExpression` | `@Type` |
+| Return | `ReturnStatement` | |
+| Annotation | `Annotation` | `@Name` (IsTest, AuraEnabled, Future, SuppressWarnings) |
+| Annotation param | `AnnotationParameter` | `@Name`, `@Value` |
+| Modifier | `ModifierNode` | `Public`, `Private`, `Static`, `Test`, `WithSharing`, `Global`, etc. |
+| Parameter | `Parameter` | `@Image` (name), `@Type` |
+| New list | `NewListInitExpression` | |
+| New map | `NewMapInitExpression` | |
+
+---
+
+## XPath Best Practices
+
+1. **ALWAYS run `ast-dump` first** — never guess node names, even for patterns listed here
+2. **Use `/BlockStatement//` for loop/if body** — avoids matching iterables, conditions, etc.
+3. **Use `@FullMethodName`** for method calls — not `@Image` or `@MethodName` alone
+4. **Exclude test classes** with `[not(ancestor::UserClass[ModifierNode[@Test = true()]])]`
+5. **Test with BOTH positive AND negative cases** — ensure no false positives
+6. **Prefer `//Node` over absolute paths** — code structure varies
+7. **Use `ancestor::` / `not(ancestor::)`** for structural exclusions (try-catch, test class)
+8. **Keep XPath simple** — complex expressions are fragile and hard to maintain
+
+## Common False Positive Traps
+
+| Pattern | Trap | Fix |
+|---------|------|-----|
+| SOQL in loop | `//ForEachStatement//SoqlExpression` matches iterable | Use `/BlockStatement//` |
+| DML in loop | Same as above | Use `/BlockStatement//` |
+| Ban method in all code | Flags test code too | Add `[not(ancestor::UserClass[ModifierNode[@Test = true()]])]` |
+| Empty block detection | Matches intentional empty constructors | Add `[@Constructor = false()]` or exclude specific patterns |
+| No sharing declaration | Flags inner classes (which inherit) | Add `[@Nested = false()]` |
+| String literal length check | Matches test data strings | Exclude test classes |

package/skills/dx-code-analyzer-custom-rule-create/scripts/create-pmd-rule.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+// Creates a PMD XPath custom rule (XML ruleset file + config reference)
+// Usage: node create-pmd-rule.js --name <name> --xpath <expression> --message <msg> [options]
+
+const fs = require("fs");
+const path = require("path");
+
+function printUsage() {
+  console.error(`Usage: node create-pmd-rule.js --name <name> --xpath <expression> --message <msg> [options]
+
+Required:
+  --name <name>              Rule name (PascalCase, no spaces)
+  --xpath <expression>       XPath expression to match violations
+  --message <msg>            Violation message shown to users
+
+Optional:
+  --description <desc>       Detailed rule description (default: same as message)
+  --language <lang>          PMD language (default: apex)
+  --priority <1-5>           PMD priority (default: 3)
+  --example <code>           Example violating code snippet
+  --config-file <path>       Path to code-analyzer.yml (default: ./code-analyzer.yml)
+  --ruleset-dir <dir>        Directory for ruleset XML (default: ./custom-rules)
+
+Examples:
+  node create-pmd-rule.js --name NoSystemDebug --xpath "//MethodCallExpression[@FullMethodName='System.debug']" --message "System.debug not allowed" --priority 3
+  node create-pmd-rule.js --name SoqlInLoop --xpath "//ForEachStatement//SoqlExpression" --message "SOQL inside loop" --priority 2`);
+  process.exit(1);
+}
+
+// Parse arguments
+const args = process.argv.slice(2);
+if (args.length < 1 || args[0] === "--help" || args[0] === "-h") {
+  printUsage();
+}
+
+const options = {
+  name: null,
+  xpath: null,
+  message: null,
+  description: null,
+  language: "apex",
+  priority: 3,
+  example: null,
+  configFile: "./code-analyzer.yml",
+  rulesetDir: "./custom-rules",
+};
+
+for (let i = 0; i < args.length; i++) {
+  switch (args[i]) {
+    case "--name": options.name = args[++i]; break;
+    case "--xpath": options.xpath = args[++i]; break;
+    case "--message": options.message = args[++i]; break;
+    case "--description": options.description = args[++i]; break;
+    case "--language": options.language = args[++i]; break;
+    case "--priority": options.priority = parseInt(args[++i], 10); break;
+    case "--example": options.example = args[++i]; break;
+    case "--config-file": options.configFile = args[++i]; break;
+    case "--ruleset-dir": options.rulesetDir = args[++i]; break;
+    default:
+      console.error(`Unknown option: ${args[i]}`);
+      printUsage();
+  }
+}
+
+// Validate required fields
+if (!options.name) { console.error("Error: --name is required"); process.exit(1); }
+if (!options.xpath) { console.error("Error: --xpath is required"); process.exit(1); }
+if (!options.message) { console.error("Error: --message is required"); process.exit(1); }
+
+// Validate rule name
+const RULE_NAME_PATTERN = /^[A-Za-z@][A-Za-z_0-9@\-/]*$/;
+if (!RULE_NAME_PATTERN.test(options.name)) {
+  console.error(`Error: Invalid rule name "${options.name}". Must match: ${RULE_NAME_PATTERN}`);
+  process.exit(1);
+}
+
+// Validate priority
+if (options.priority < 1 || options.priority > 5) {
+  console.error("Error: Priority must be 1-5");
+  process.exit(1);
+}
+
+// Validate language
+const VALID_LANGUAGES = ["apex", "visualforce", "html", "xml", "javascript"];
+if (!VALID_LANGUAGES.includes(options.language.toLowerCase())) {
+  console.error(`Error: Invalid language "${options.language}". Supported: ${VALID_LANGUAGES.join(", ")}`);
+  process.exit(1);
+}
+
+// Set defaults
+if (!options.description) {
+  options.description = options.message;
+}
+
+// Generate the PMD ruleset XML
+function buildRulesetXml() {
+  const escXpath = options.xpath.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  const escMessage = options.message.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+  const escDescription = options.description.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+  let xml = `<?xml version="1.0" encoding="UTF-8"?>
+<ruleset name="${options.name}CustomRules"
+    xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 https://pmd.sourceforge.io/ruleset_2_0_0.xsd">
+
+    <description>Custom rules for ${options.name}</description>
+
+    <rule name="${options.name}"
+          language="${options.language}"
+          message="${escMessage}"
+          class="net.sourceforge.pmd.lang.rule.xpath.XPathRule">
+
+        <description>${escDescription}</description>
+        <priority>${options.priority}</priority>
+
+        <properties>
+            <property name="xpath">
+                <value><![CDATA[
+${options.xpath}
+]]></value>
+            </property>
+        </properties>`;
+
+  if (options.example) {
+    xml += `
+
+        <example>
+<![CDATA[
+${options.example}
+]]>
+        </example>`;
+  }
+
+  xml += `
+    </rule>
+</ruleset>
+`;
+
+  return xml;
+}
+
+// Create ruleset directory if needed
+const rulesetDir = path.resolve(options.rulesetDir);
+if (!fs.existsSync(rulesetDir)) {
+  fs.mkdirSync(rulesetDir, { recursive: true });
+}
+
+// Write ruleset XML
+const rulesetFileName = `${options.name}-pmd-ruleset.xml`;
+const rulesetPath = path.join(rulesetDir, rulesetFileName);
+
+if (fs.existsSync(rulesetPath)) {
+  console.error(`Error: Ruleset file already exists: ${rulesetPath}`);
+  process.exit(1);
+}
+
+const rulesetXml = buildRulesetXml();
+fs.writeFileSync(rulesetPath, rulesetXml, "utf8");
+
+// Update code-analyzer.yml to reference the ruleset
+const configPath = path.resolve(options.configFile);
+const rulesetRelativePath = path.relative(path.dirname(configPath), rulesetPath);
+let configContent = "";
+
+if (fs.existsSync(configPath)) {
+  configContent = fs.readFileSync(configPath, "utf8");
+}
+
+// Check if this ruleset path is already referenced in config (deduplication)
+const alreadyReferenced = configContent.includes(rulesetRelativePath);
+
+if (!configContent) {
+  // Create new config
+  configContent = `engines:\n  pmd:\n    custom_rulesets:\n      - "${rulesetRelativePath}"\n`;
+} else if (alreadyReferenced) {
+  // Ruleset path already in config — skip adding duplicate entry
+  // (This happens when the XML was deleted and recreated during iteration)
+} else if (configContent.includes("custom_rulesets:") && configContent.includes("pmd:")) {
+  // Add to existing custom_rulesets
+  const insertPoint = configContent.indexOf("custom_rulesets:");
+  const afterLine = configContent.indexOf("\n", insertPoint) + 1;
+  configContent = configContent.slice(0, afterLine) + `      - "${rulesetRelativePath}"\n` + configContent.slice(afterLine);
+} else if (configContent.includes("pmd:")) {
+  // Add custom_rulesets under pmd
+  const insertPoint = configContent.indexOf("pmd:");
+  const afterLine = configContent.indexOf("\n", insertPoint) + 1;
+  configContent = configContent.slice(0, afterLine) + `    custom_rulesets:\n      - "${rulesetRelativePath}"\n` + configContent.slice(afterLine);
+} else if (configContent.includes("engines:")) {
+  // Add pmd section under engines
+  const insertPoint = configContent.indexOf("engines:");
+  const afterLine = configContent.indexOf("\n", insertPoint) + 1;
+  configContent = configContent.slice(0, afterLine) + `  pmd:\n    custom_rulesets:\n      - "${rulesetRelativePath}"\n` + configContent.slice(afterLine);
+} else {
+  // Append engines section
+  configContent += `\nengines:\n  pmd:\n    custom_rulesets:\n      - "${rulesetRelativePath}"\n`;
+}
+
+fs.writeFileSync(configPath, configContent, "utf8");
+
+console.log(JSON.stringify({
+  status: "success",
+  ruleName: options.name,
+  engine: "pmd",
+  language: options.language,
+  rulesetFile: rulesetPath,
+  configFile: configPath,
+  message: `Rule "${options.name}" created. Validate with: sf code-analyzer rules --rule-selector pmd:${options.name}`
+}));

package/skills/dx-code-analyzer-custom-rule-create/scripts/create-regex-rule.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+// Creates a regex custom rule in code-analyzer.yml
+// Usage: node create-regex-rule.js --name <name> --regex <pattern> --description <desc> [options]
+
+const fs = require("fs");
+const path = require("path");
+
+function printUsage() {
+  console.error(`Usage: node create-regex-rule.js --name <name> --regex <pattern> --description <desc> [options]
+
+Required:
+  --name <name>              Rule name (PascalCase, no spaces)
+  --regex <pattern>          Regex in /pattern/flags format
+  --description <desc>       What the rule checks
+
+Optional:
+  --violation-message <msg>  Message shown on violation
+  --severity <1-5>           Severity level (default: 3)
+  --tags <tag1,tag2>         Comma-separated tags (default: Recommended,Custom)
+  --file-extensions <exts>   Comma-separated extensions (e.g., .cls,.trigger)
+  --regex-ignore <pattern>   Negative pattern to exclude matches
+  --config-file <path>       Path to code-analyzer.yml (default: ./code-analyzer.yml)
+
+Examples:
+  node create-regex-rule.js --name NoHardcodedIds --regex "/[0-9a-zA-Z]{18}/g" --description "Detects hardcoded IDs" --severity 2 --file-extensions ".cls,.trigger"
+  node create-regex-rule.js --name NoTodos --regex "/TODO|FIXME/gi" --description "Flags TODO comments" --severity 4`);
+  process.exit(1);
+}
+
+// Parse arguments
+const args = process.argv.slice(2);
+if (args.length < 1 || args[0] === "--help" || args[0] === "-h") {
+  printUsage();
+}
+
+const options = {
+  name: null,
+  regex: null,
+  description: null,
+  violationMessage: null,
+  severity: 3,
+  tags: ["Recommended", "Custom"],
+  fileExtensions: null,
+  regexIgnore: null,
+  configFile: "./code-analyzer.yml",
+};
+
+for (let i = 0; i < args.length; i++) {
+  switch (args[i]) {
+    case "--name": options.name = args[++i]; break;
+    case "--regex": options.regex = args[++i]; break;
+    case "--description": options.description = args[++i]; break;
+    case "--violation-message": options.violationMessage = args[++i]; break;
+    case "--severity": options.severity = parseInt(args[++i], 10); break;
+    case "--tags": options.tags = args[++i].split(",").map(t => t.trim()); break;
+    case "--file-extensions": options.fileExtensions = args[++i].split(",").map(e => e.trim()); break;
+    case "--regex-ignore": options.regexIgnore = args[++i]; break;
+    case "--config-file": options.configFile = args[++i]; break;
+    default:
+      console.error(`Unknown option: ${args[i]}`);
+      printUsage();
+  }
+}
+
+// Validate required fields
+if (!options.name) { console.error("Error: --name is required"); process.exit(1); }
+if (!options.regex) { console.error("Error: --regex is required"); process.exit(1); }
+if (!options.description) { console.error("Error: --description is required"); process.exit(1); }
+
+// Validate rule name
+const RULE_NAME_PATTERN = /^[A-Za-z@][A-Za-z_0-9@\-/]*$/;
+if (!RULE_NAME_PATTERN.test(options.name)) {
+  console.error(`Error: Invalid rule name "${options.name}". Must match: ${RULE_NAME_PATTERN}`);
+  process.exit(1);
+}
+
+// Validate regex format — must be /pattern/flags with no surrounding whitespace
+// and the flags portion must contain only valid JavaScript regex flag characters.
+options.regex = options.regex.trim();
+if (!options.regex.startsWith("/") || options.regex.lastIndexOf("/") <= 0) {
+  console.error(`Error: Regex must be in /pattern/flags format. Got: "${options.regex}"`);
+  process.exit(1);
+}
+const lastSlash = options.regex.lastIndexOf("/");
+const flags = options.regex.slice(lastSlash + 1);
+if (!flags) {
+  console.error(`Error: Regex must include flags after the closing /. Use /pattern/g at minimum. Got: "${options.regex}"`);
+  process.exit(1);
+}
+// Strict flags validation — only valid JS regex flag chars allowed, no spaces, no junk.
+if (!/^[gimsuy]+$/.test(flags)) {
+  console.error(`Error: Invalid regex flags "${flags}". Allowed: g, i, m, s, u, y (no spaces, no other characters). Got: "${options.regex}"`);
+  process.exit(1);
+}
+// Code Analyzer regex rules require the global flag.
+if (!flags.includes("g")) {
+  console.error(`Error: Regex must include the global flag 'g'. Got flags: "${flags}"`);
+  process.exit(1);
+}
+
+// Validate severity
+if (options.severity < 1 || options.severity > 5) {
+  console.error("Error: Severity must be 1-5");
+  process.exit(1);
+}
+
+// Validate file extensions
+if (options.fileExtensions) {
+  for (const ext of options.fileExtensions) {
+    if (!ext.startsWith(".")) {
+      console.error(`Error: File extension must start with dot: "${ext}"`);
+      process.exit(1);
+    }
+  }
+}
+
+// Safely quote a string for YAML output.
+// CRITICAL: regex patterns contain backslashes (`\.`, `\d`, `\\`, etc.).
+// Double-quoted YAML treats `\` as an escape introducer — `\.` is an unknown
+// escape and YAML rejects the file with "unknown escape sequence". Single-quoted
+// YAML treats backslash as literal, which is exactly what regex needs.
+// Strategy:
+//   - If value contains a backslash → ALWAYS use single quotes (escape ' as '')
+//   - Else if value has no quotes → double quotes (simplest, most readable)
+//   - Else → single quotes (escape ' as '')
+function yamlQuote(value) {
+  const hasBackslash = value.includes("\\");
+  const hasSingle = value.includes("'");
+  const hasDouble = value.includes('"');
+
+  if (!hasBackslash && !hasSingle && !hasDouble) {
+    return `"${value}"`;
+  }
+
+  // Single-quoted YAML: only ' needs escaping (as ''). Backslashes pass through.
+  const escaped = value.replace(/'/g, "''");
+  return `'${escaped}'`;
+}
+
+// Build the rule YAML block
+function buildRuleYaml() {
+  const indent = "      ";
+  const lines = [];
+  lines.push(`      ${options.name}:`);
+  lines.push(`${indent}  regex: ${yamlQuote(options.regex)}`);
+  lines.push(`${indent}  description: ${yamlQuote(options.description)}`);
+
+  if (options.violationMessage) {
+    lines.push(`${indent}  violation_message: ${yamlQuote(options.violationMessage)}`);
+  }
+
+  lines.push(`${indent}  severity: ${options.severity}`);
+
+  if (options.tags && options.tags.length > 0) {
+    lines.push(`${indent}  tags:`);
+    options.tags.forEach(tag => lines.push(`${indent}    - "${tag}"`));
+  }
+
+  if (options.fileExtensions && options.fileExtensions.length > 0) {
+    lines.push(`${indent}  file_extensions:`);
+    options.fileExtensions.forEach(ext => lines.push(`${indent}    - "${ext}"`));
+  }
+
+  if (options.regexIgnore) {
+    lines.push(`${indent}  regex_ignore: ${yamlQuote(options.regexIgnore)}`);
+  }
+
+  return lines.join("\n");
+}
+
+// Read or create config file
+const configPath = path.resolve(options.configFile);
+let configContent = "";
+
+if (fs.existsSync(configPath)) {
+  configContent = fs.readFileSync(configPath, "utf8");
+
+  // Check if rule already exists
+  if (configContent.includes(`${options.name}:`)) {
+    console.error(`Error: Rule "${options.name}" already exists in ${configPath}`);
+    process.exit(1);
+  }
+}
+
+const ruleYaml = buildRuleYaml();
+
+// Upsert into config
+if (!configContent) {
+  // Create new file
+  configContent = `engines:\n  regex:\n    custom_rules:\n${ruleYaml}\n`;
+} else if (configContent.includes("custom_rules:") && configContent.includes("regex:")) {
+  // Add to existing custom_rules section
+  const insertPoint = configContent.indexOf("custom_rules:");
+  const afterCustomRules = configContent.indexOf("\n", insertPoint) + 1;
+  configContent = configContent.slice(0, afterCustomRules) + ruleYaml + "\n" + configContent.slice(afterCustomRules);
+} else if (configContent.includes("regex:")) {
+  // Add custom_rules section under regex
+  const insertPoint = configContent.indexOf("regex:");
+  const afterRegex = configContent.indexOf("\n", insertPoint) + 1;
+  configContent = configContent.slice(0, afterRegex) + "    custom_rules:\n" + ruleYaml + "\n" + configContent.slice(afterRegex);
+} else if (configContent.includes("engines:")) {
+  // Add regex section under engines
+  const insertPoint = configContent.indexOf("engines:");
+  const afterEngines = configContent.indexOf("\n", insertPoint) + 1;
+  configContent = configContent.slice(0, afterEngines) + "  regex:\n    custom_rules:\n" + ruleYaml + "\n" + configContent.slice(afterEngines);
+} else {
+  // Append engines section
+  configContent += "\nengines:\n  regex:\n    custom_rules:\n" + ruleYaml + "\n";
+}
+
+// Write config
+fs.writeFileSync(configPath, configContent, "utf8");
+
+console.log(JSON.stringify({
+  status: "success",
+  ruleName: options.name,
+  engine: "regex",
+  configFile: configPath,
+  message: `Rule "${options.name}" created. Validate with: sf code-analyzer rules --rule-selector regex:${options.name}`
+}));

package/skills/dx-code-analyzer-run/SKILL.md

@@ -1,10 +1,18 @@
 ---
 name: dx-code-analyzer-run
-description: "Run Salesforce Code Analyzer to scan code for security, performance, best practice, and code style violations. Supports all engines (PMD, ESLint, CPD, RetireJS, Flow, SFGE, ApexGuru), targets (files, folders, git diff), categories, and severities. Also handles post-scan exploration: filtering results by engine/severity/category/file, and explaining what specific rules mean. TRIGGER when: user says 'scan my code', 'check for security issues', 'run PMD/ESLint', 'find duplicates', 'analyze Flows', 'check vulnerable libraries', 'AppExchange review', 'lint my LWC', 'static analysis', 'code quality', 'show only security violations', 'what is this rule', 'explain ApexCRUDViolation', 'filter results', or mentions engines/file types (.cls, .trigger, .js, .flow-meta.xml). Use this skill for scanning, exploring results, understanding rules, and listing available rules. DO NOT TRIGGER when: user wants to fix code without scanning, or asks ONLY about installation/configuration."
-allowed-tools: Read, Bash(sf code-analyzer), Bash(node), Bash(git diff), Bash(date), Write, Edit
+description: "Run Salesforce Code Analyzer to scan code for security, performance, best practice, and code style violations. Supports all engines (PMD, ESLint, CPD, RetireJS, Flow, SFGE, ApexGuru), targets (files, folders, git diff), categories, and severities. Also handles post-scan exploration: filtering results by engine/severity/category/file, and explaining what rules mean. TRIGGER when: user says 'scan my code', 'check security issues', 'run PMD/ESLint', 'find duplicates', 'analyze Flows', 'check vulnerable libraries', 'AppExchange review', 'lint my LWC', 'static analysis', 'code quality', 'show security violations', 'what is this rule', 'explain ApexCRUDViolation', 'filter results', or mentions engines/file types (.cls, .trigger, .js, .flow-meta.xml). Use this skill for scanning, exploring results, and listing rules. DO NOT TRIGGER when: user asks only about installation/configuration (use dx-code-analyzer-configure), or wants to create a custom rule (use dx-code-analyzer-custom-rule-create)."
 metadata:
   version: "1.0"
-  argument-hint: "[target-path] [--engine pmd|eslint|cpd|retire-js|regex|flow|sfge|apexguru] [--category Security|Performance|BestPractices|...] [--severity 1-5] [--diff]"
+  relatedSkills:
+    - "dx-code-analyzer-configure"
+    - "dx-code-analyzer-custom-rule-create"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+    - tool: ["node"]
+      semver: ">=18.0.0"
+    - tool: ["git"]
+      semver: ">=2.0.0"
 ---
 
 # Running Code Analyzer Skill
@@ -67,11 +75,13 @@ Any aggregation, filter, or rank question ("which file has the most violations?"
 
 ## Overview
 
+> **Ecosystem:** This skill is part of a 3-skill Code Analyzer suite — `dx-code-analyzer-run` (scans & results) · `dx-code-analyzer-configure` (setup, config, CI/CD) · `dx-code-analyzer-custom-rule-create` (custom rule authoring).
+
 This skill translates natural-language requests ("scan for security issues", "check my changes") into the correct `sf code-analyzer run` command, executes scans across any combination of engines/targets/severities, and presents actionable results. When engine-provided fixes are available, it discovers them, asks for user confirmation, applies them safely, and offers verification. Use it for static analysis, security reviews, AppExchange certification, code-quality checks, and finding duplicates/vulnerabilities in Salesforce projects.
 
 **In scope:** running scans, parsing/filtering/ranking results, applying engine auto-fixes, diff-based scans, all output formats (JSON/HTML/SARIF/CSV/XML), describing/listing rules, scan-failure troubleshooting.
 
-**Out of scope:** installing/configuring `sf` or the plugin (→ `dx-code-analyzer-configure`), writing custom rules/engines, AI-generated fixes beyond engine-provided ones, deep refactoring, CI/CD setup (→ `dx-code-analyzer-configure`).
+**Out of scope:** installing/configuring `sf` or the plugin (→ `dx-code-analyzer-configure`), writing custom rules/engines (→ `dx-code-analyzer-custom-rule-create`), AI-generated fixes beyond engine-provided ones, deep refactoring, CI/CD setup (→ `dx-code-analyzer-configure`).
 
 **Allowed tools:** Bash (`sf code-analyzer`, `node`, `git diff`, `date`), Read, Write, Edit. **Forbidden:** any MCP tool, Agent tool, web tools, other skills, Python, `jq`, inline scripts/heredocs. This skill owns the complete scan-fix-verify-query-explain workflow end-to-end.
 
@@ -203,7 +213,7 @@ Use the **Bash tool only** — never the `run_code_analyzer` MCP tool.
 
 1. Generate the timestamp via Bash: `date +%Y%m%d-%H%M%S` → e.g. `20260512-143022`.
 2. Tell the user:
-   ```
+   ```text
    Starting scan...
    Results: ./code-analyzer-results-20260512-143022.json
    Log:     ./code-analyzer-results-20260512-143022.log
@@ -237,7 +247,7 @@ node "<skill_dir>/scripts/parse-results.js" "./code-analyzer-results-TIMESTAMP.j
 
 ### Presentation template
 
-```
+```text
 ## Scan Complete
 
 **Found X violations** across Y files.
@@ -296,7 +306,7 @@ node "<skill_dir>/scripts/discover-fixes.js" "./code-analyzer-results-TIMESTAMP.
 
 ### 6.3 Present + ASK (then STOP)
 
-```
+```text
 ### Engine-Provided Fixes Available
 **X of Y violations** have auto-fixes provided by the analysis engine:
 
@@ -327,7 +337,7 @@ node "<skill_dir>/scripts/summarize-fixes.js" "./code-analyzer-results-TIMESTAMP
 
 Then present:
 
-```
+```text
 ### Engine-Provided Fixes Applied Successfully ✓
 **Applied X auto-fixes across Y files.**
 
@@ -439,6 +449,29 @@ node "<skill_dir>/scripts/list-rules.js" "<selector>" [options]
 
 Filters: `--engine`, `--severity`, `--top` (default 100), `--count-only`. The script pre-validates selector tokens (catches typos like `secruity`) before calling the CLI. Presentation: `<skill_dir>/references/post-scan-workflows.md`.
 
+---
+## Cross-Skill Integration
+
+This skill is part of a 3-skill Code Analyzer ecosystem. Hand off cleanly rather than attempting work that belongs to another skill.
+
+### When THIS skill delegates to `dx-code-analyzer-configure`:
+
+- Pre-flight check fails (CLI missing, plugin not installed, engine prereqs broken) → stop, delegate, return here after fix
+- User asks to set up CI/CD, edit `code-analyzer.yml`, change severities, or disable engines → delegate entirely
+
+### When THIS skill delegates to `dx-code-analyzer-custom-rule-create`:
+
+- User asks to create a new rule, write XPath, write a regex rule, or enforce a pattern not covered by built-in rules → delegate entirely. Do NOT attempt to create rules here.
+
+### When other skills hand off HERE:
+
+- `dx-code-analyzer-configure` completes setup → proceed with scan (Step 1–5)
+- `dx-code-analyzer-custom-rule-create` finishes creating a rule → proceed with scan targeting the new rule (e.g., `--rule-selector pmd:<RuleName>`) to verify it works
+
+### Ownership boundary
+
+This skill owns the complete **scan → explore → fix** workflow end-to-end. It does NOT own installation, config file management, or rule authoring.
+
 ---
 
 ## Constraints & Gotchas