@salesforce/afv-skills 1.27.0 → 1.29.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}`
+}));