@salesforce/afv-skills 1.17.0 → 1.19.0

package/skills/running-code-analyzer/scripts/list-rules.js

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+// Version: v1.0 | SHA256: placeholder
+// List Code Analyzer rules matching a selector and return structured JSON
+// Usage: node list-rules.js <selector> [options]
+//
+// This script runs `sf code-analyzer rules --rule-selector <selector>` and
+// parses the table output into structured JSON for presentation.
+//
+// The CLI table format is:
+//   #   Name                   Engine   Severity       Tags
+//   1   @lwc/lwc/no-inner-html eslint   2 (High)       Recommended, LWC, Security
+//
+// Output: JSON with {status, totalRules, rules: [{name, engine, severity, severityNum, tags}], engines, summary}
+
+const { execSync } = require("child_process");
+
+function printUsage() {
+  console.error(`Usage: node list-rules.js <selector> [options]
+
+Arguments:
+  <selector>           Rule selector (same syntax as --rule-selector)
+                       Examples: "Security", "pmd", "eslint:Recommended",
+                       "(pmd,eslint):Security:(1,2)", "Apex", "JavaScript"
+
+Options:
+  --engine <name>      Filter results to a specific engine after listing
+  --severity <n>       Filter results to specific severity (1-5, comma-separated)
+  --top <n>            Return at most N rules (default: 100)
+  --count-only         Return only counts by engine/severity/category (no rule list)
+
+Valid selector tokens:
+  Engines: eslint, regex, retire-js, flow, pmd, cpd, sfge
+  Severities: Critical/1, High/2, Moderate/3, Low/4, Info/5
+  Categories: Security, Performance, BestPractices, CodeStyle, Design, ErrorProne, Documentation
+  Languages: Apex, JavaScript, TypeScript, HTML, CSS, Visualforce, XML
+  Tags: Recommended, Custom, All, DevPreview, LWC, Fixable
+
+Examples:
+  node list-rules.js "Security"
+  node list-rules.js "pmd:Security"
+  node list-rules.js "eslint:Recommended"
+  node list-rules.js "(pmd,eslint):Security:(1,2)"
+  node list-rules.js "Apex"
+  node list-rules.js "JavaScript:BestPractices"
+  node list-rules.js "Recommended" --count-only
+  node list-rules.js "all" --engine pmd --severity 1,2 --top 10`);
+  process.exit(1);
+}
+
+// Parse CLI arguments
+const args = process.argv.slice(2);
+if (args.length < 1 || args[0] === "--help" || args[0] === "-h") {
+  printUsage();
+}
+
+const selector = args[0];
+const options = {
+  engine: null,
+  severity: null,
+  top: 100,
+  countOnly: false,
+};
+
+for (let i = 1; i < args.length; i++) {
+  switch (args[i]) {
+    case "--engine":
+      options.engine = (args[++i] || "").toLowerCase();
+      break;
+    case "--severity":
+      options.severity = (args[++i] || "")
+        .split(",")
+        .map((s) => parseInt(s.trim(), 10))
+        .filter((n) => n >= 1 && n <= 5);
+      break;
+    case "--top":
+      options.top = parseInt(args[++i] || "25", 10);
+      break;
+    case "--count-only":
+      options.countOnly = true;
+      break;
+    default:
+      console.error(`Unknown option: ${args[i]}`);
+      printUsage();
+  }
+}
+
+// Validate selector tokens before running CLI
+const validationError = validateSelector(selector);
+if (validationError) {
+  console.log(JSON.stringify({
+    status: "invalid_selector",
+    message: validationError,
+    hint: "Valid tokens: engines (pmd, eslint, cpd, retire-js, regex, flow, sfge), severities (1-5 or Critical/High/Moderate/Low/Info), categories (Security, Performance, BestPractices, CodeStyle, Design, ErrorProne, Documentation), languages (Apex, JavaScript, TypeScript, HTML, CSS, Visualforce, XML), tags (Recommended, Custom, All, DevPreview, LWC, Fixable)",
+  }));
+  process.exit(0);
+}
+
+// Run `sf code-analyzer rules`
+let rawOutput;
+try {
+  const cmd = `sf code-analyzer rules --rule-selector "${selector}" 2>&1`;
+  rawOutput = execSync(cmd, {
+    encoding: "utf8",
+    timeout: 60000,
+    maxBuffer: 2 * 1024 * 1024,
+  });
+} catch (err) {
+  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 table output
+const rules = parseTableOutput(rawOutput);
+
+if (rules.length === 0) {
+  console.log(JSON.stringify({
+    status: "no_rules_found",
+    message: `No rules matched selector "${selector}". Check the selector syntax or try a broader query.`,
+    hint: "Use tokens like: Security, pmd, eslint:Recommended, (1,2), Apex",
+  }));
+  process.exit(0);
+}
+
+// Apply post-filters
+let filtered = rules;
+if (options.engine) {
+  filtered = filtered.filter((r) => r.engine.toLowerCase() === options.engine);
+}
+if (options.severity) {
+  filtered = filtered.filter((r) => options.severity.includes(r.severityNum));
+}
+
+// Compute summary stats
+const engineCounts = {};
+const severityCounts = {};
+const categoryCounts = {};
+filtered.forEach((r) => {
+  engineCounts[r.engine] = (engineCounts[r.engine] || 0) + 1;
+  const sevKey = `${r.severityNum} (${severityName(r.severityNum)})`;
+  severityCounts[sevKey] = (severityCounts[sevKey] || 0) + 1;
+  (r.tags || []).forEach((tag) => {
+    const t = tag.trim();
+    if (["Security", "Performance", "BestPractices", "CodeStyle", "Design", "ErrorProne", "Documentation"].includes(t)) {
+      categoryCounts[t] = (categoryCounts[t] || 0) + 1;
+    }
+  });
+});
+
+// Build result
+const result = {
+  status: "success",
+  selector,
+  totalRules: filtered.length,
+  summary: {
+    byEngine: engineCounts,
+    bySeverity: severityCounts,
+    byCategory: categoryCounts,
+  },
+};
+
+if (!options.countOnly) {
+  result.rules = filtered.slice(0, options.top).map((r) => ({
+    name: r.name,
+    engine: r.engine,
+    severity: r.severity,
+    severityNum: r.severityNum,
+    tags: r.tags,
+  }));
+  if (filtered.length > options.top) {
+    result.truncated = true;
+    result.showing = options.top;
+  }
+}
+
+console.log(JSON.stringify(result));
+
+// --- Helper Functions ---
+
+function parseTableOutput(output) {
+  const rules = [];
+  const lines = output.split("\n");
+
+  for (const line of lines) {
+    // Match table rows: starts with spaces + number
+    // Format: "  1   ruleName   engine   severity   tags"
+    const match = line.match(/^\s+(\d+)\s{2,}(\S+)\s{2,}(\S+)\s{2,}(\d+\s*\([^)]+\))\s{2,}(.+)$/);
+    if (match) {
+      const severityStr = match[4].trim();
+      const sevNumMatch = severityStr.match(/^(\d)/);
+      rules.push({
+        name: match[2].trim(),
+        engine: match[3].trim(),
+        severity: severityStr,
+        severityNum: sevNumMatch ? parseInt(sevNumMatch[1], 10) : 0,
+        tags: match[5].trim().split(",").map((t) => t.trim()).filter(Boolean),
+      });
+    }
+  }
+
+  return rules;
+}
+
+function validateSelector(selector) {
+  if (!selector || !selector.trim()) {
+    return "Selector cannot be empty.";
+  }
+
+  const VALID_TOKENS = new Set([
+    // Engines
+    "eslint", "regex", "retire-js", "flow", "pmd", "cpd", "sfge",
+    // Severity names
+    "critical", "high", "moderate", "low", "info",
+    // Severity numbers
+    "1", "2", "3", "4", "5",
+    // General tags
+    "recommended", "custom", "all",
+    // Categories
+    "bestpractices", "codestyle", "design", "documentation", "errorprone", "security", "performance",
+    // Languages
+    "apex", "css", "html", "javascript", "typescript", "visualforce", "xml",
+    // Engine-specific
+    "devpreview", "lwc", "fixable",
+  ]);
+
+  // Split by : (AND), then handle () groups (OR)
+  const groups = selector.split(":").map((s) => s.trim()).filter(Boolean);
+  const invalid = [];
+
+  for (const group of groups) {
+    let tokens;
+    if (group.startsWith("(") && group.endsWith(")")) {
+      // OR group: (token1,token2)
+      tokens = group.slice(1, -1).split(",").map((t) => t.trim()).filter(Boolean);
+    } else {
+      tokens = [group];
+    }
+
+    for (const token of tokens) {
+      if (!VALID_TOKENS.has(token.toLowerCase())) {
+        invalid.push(token);
+      }
+    }
+  }
+
+  if (invalid.length > 0) {
+    return `Invalid selector token(s): ${invalid.join(", ")}. Did you misspell a token?`;
+  }
+  return null;
+}
+
+function severityName(num) {
+  const names = { 1: "Critical", 2: "High", 3: "Moderate", 4: "Low", 5: "Info" };
+  return names[num] || "Unknown";
+}

package/skills/running-code-analyzer/scripts/query-results.js

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+// Version: v1.0 | SHA256: placeholder
+// Query and filter Code Analyzer results JSON with rich filtering capabilities
+// Usage: node query-results.js <results-file.json> [options]
+//
+// Options:
+//   --engine <name>        Filter by engine (pmd, eslint, cpd, retire-js, etc.)
+//   --severity <n>         Filter by severity (1-5, comma-separated for multiple)
+//   --category <tag>       Filter by category/tag (Security, Performance, etc.)
+//   --rule <name>          Filter by exact rule name (case-insensitive)
+//   --file <substring>     Filter by file path substring
+//   --top <n>              Return top N results (default: 10)
+//   --sort <field>         Sort by: severity, rule, engine, file (default: severity)
+//   --sort-dir <dir>       Sort direction: asc, desc (default: asc)
+//   --summary              Show only summary counts (no individual violations)
+
+const fs = require("fs");
+const path = require("path");
+
+function printUsage() {
+  console.error(`Usage: node query-results.js <results-file.json> [options]
+
+Options:
+  --engine <name>        Filter by engine (pmd, eslint, cpd, retire-js, etc.)
+  --severity <n>         Filter by severity (1-5, comma-separated for multiple: 1,2)
+  --category <tag>       Filter by category/tag (Security, Performance, BestPractices, etc.)
+  --rule <name>          Filter by exact rule name (case-insensitive)
+  --file <substring>     Filter by file path substring (case-insensitive)
+  --top <n>              Return top N results (default: 10)
+  --sort <field>         Sort by: severity, rule, engine, file (default: severity)
+  --sort-dir <dir>       Sort direction: asc, desc (default: asc)
+  --summary              Show only summary counts (no individual violations)
+
+Examples:
+  node query-results.js results.json --engine pmd --severity 1,2
+  node query-results.js results.json --category Security --top 20
+  node query-results.js results.json --file AccountService.cls
+  node query-results.js results.json --rule ApexCRUDViolation
+  node query-results.js results.json --summary`);
+  process.exit(1);
+}
+
+// Parse CLI arguments
+const args = process.argv.slice(2);
+if (args.length < 1 || args[0] === "--help" || args[0] === "-h") {
+  printUsage();
+}
+
+const filePath = args[0];
+const options = {
+  engine: null,
+  severity: null,
+  category: null,
+  rule: null,
+  file: null,
+  top: 10,
+  sort: "severity",
+  sortDir: "asc",
+  summary: false,
+};
+
+// Parse named options
+for (let i = 1; i < args.length; i++) {
+  const arg = args[i];
+  switch (arg) {
+    case "--engine":
+      options.engine = (args[++i] || "").toLowerCase();
+      break;
+    case "--severity":
+      options.severity = (args[++i] || "")
+        .split(",")
+        .map((s) => parseInt(s.trim(), 10))
+        .filter((n) => n >= 1 && n <= 5);
+      break;
+    case "--category":
+      options.category = (args[++i] || "").toLowerCase();
+      break;
+    case "--rule":
+      options.rule = (args[++i] || "").toLowerCase();
+      break;
+    case "--file":
+      options.file = (args[++i] || "").toLowerCase();
+      break;
+    case "--top":
+      options.top = parseInt(args[++i] || "10", 10);
+      break;
+    case "--sort":
+      options.sort = args[++i] || "severity";
+      break;
+    case "--sort-dir":
+      options.sortDir = args[++i] || "asc";
+      break;
+    case "--summary":
+      options.summary = true;
+      break;
+    default:
+      console.error(`Unknown option: ${arg}`);
+      printUsage();
+  }
+}
+
+// Read and parse results file
+let data;
+try {
+  data = JSON.parse(fs.readFileSync(filePath, "utf8"));
+} catch (err) {
+  console.error(`Error reading results file: ${err.message}`);
+  process.exit(1);
+}
+
+const runDir = data.runDir || "";
+const violations = data.violations || [];
+
+// Apply filters
+let filtered = violations.filter((v) => {
+  if (options.engine && v.engine.toLowerCase() !== options.engine) return false;
+  if (options.severity && !options.severity.includes(v.severity)) return false;
+  if (options.category) {
+    const tags = (v.tags || []).map((t) => t.toLowerCase());
+    if (!tags.includes(options.category)) return false;
+  }
+  if (options.rule && v.rule.toLowerCase() !== options.rule) return false;
+  if (options.file) {
+    const loc = v.locations && v.locations[v.primaryLocationIndex || 0];
+    const fileLower = ((loc && loc.file) || "").toLowerCase();
+    if (!fileLower.includes(options.file)) return false;
+  }
+  return true;
+});
+
+// Sort
+const sortMul = options.sortDir === "desc" ? -1 : 1;
+filtered.sort((a, b) => {
+  let cmp = 0;
+  switch (options.sort) {
+    case "severity":
+      cmp = a.severity - b.severity;
+      break;
+    case "rule":
+      cmp = a.rule.localeCompare(b.rule);
+      break;
+    case "engine":
+      cmp = a.engine.localeCompare(b.engine);
+      break;
+    case "file": {
+      const aLoc = a.locations && a.locations[a.primaryLocationIndex || 0];
+      const bLoc = b.locations && b.locations[b.primaryLocationIndex || 0];
+      const aFile = (aLoc && aLoc.file) || "";
+      const bFile = (bLoc && bLoc.file) || "";
+      cmp = aFile.localeCompare(bFile);
+      break;
+    }
+  }
+  if (cmp !== 0) return cmp * sortMul;
+  // Secondary sort: severity ascending
+  return (a.severity - b.severity) * sortMul;
+});
+
+// Build output
+const totalMatches = filtered.length;
+const limited = filtered.slice(0, options.top);
+
+// Compute severity breakdown of matches
+const sevCounts = { 1: 0, 2: 0, 3: 0, 4: 0, 5: 0 };
+filtered.forEach((v) => {
+  if (sevCounts[v.severity] !== undefined) sevCounts[v.severity]++;
+});
+
+// Compute rule frequency for matches
+const ruleCounts = {};
+const ruleEngines = {};
+filtered.forEach((v) => {
+  ruleCounts[v.rule] = (ruleCounts[v.rule] || 0) + 1;
+  if (!ruleEngines[v.rule]) ruleEngines[v.rule] = v.engine;
+});
+const topRules = Object.entries(ruleCounts)
+  .sort((a, b) => b[1] - a[1])
+  .slice(0, options.top)
+  .map(([rule, count]) => ({ rule, engine: ruleEngines[rule], count }));
+
+// Compute file frequency for matches
+const fileCounts = {};
+filtered.forEach((v) => {
+  const loc = v.locations && v.locations[v.primaryLocationIndex || 0];
+  let file = (loc && loc.file) || "unknown";
+  if (runDir && file.startsWith(runDir)) file = file.substring(runDir.length + 1);
+  fileCounts[file] = (fileCounts[file] || 0) + 1;
+});
+const topFiles = Object.entries(fileCounts)
+  .sort((a, b) => b[1] - a[1])
+  .slice(0, options.top)
+  .map(([file, count]) => ({ file, count }));
+
+// Build result object
+const result = {
+  query: {
+    engine: options.engine,
+    severity: options.severity,
+    category: options.category,
+    rule: options.rule,
+    file: options.file,
+    top: options.top,
+    sort: options.sort,
+    sortDir: options.sortDir,
+  },
+  totalViolations: violations.length,
+  totalMatches,
+  severityCounts: sevCounts,
+  topRules,
+  topFiles,
+};
+
+if (!options.summary) {
+  result.violations = limited.map((v) => {
+    const loc = v.locations && v.locations[v.primaryLocationIndex || 0];
+    let file = (loc && loc.file) || "unknown";
+    if (runDir && file.startsWith(runDir)) file = file.substring(runDir.length + 1);
+    return {
+      rule: v.rule,
+      engine: v.engine,
+      severity: v.severity,
+      message: v.message,
+      file: file,
+      startLine: (loc && loc.startLine) || 0,
+      tags: v.tags || [],
+    };
+  });
+}
+
+console.log(JSON.stringify(result));

package/skills/running-devops-test-suite/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: running-devops-test-suite
+description: "Triggers async execution of one or more DevOps Center test suites on a pipeline stage (Pre-Promote, Post-Promote, or Review event) via the Connect API, after an explicit user confirmation gate, then hands off to result polling via the `polling-test-results` skill. Also re-runs (retriggers) a quality gate after fixes — but only once validation confirms the coverage threshold is now met. TRIGGER when: the user wants to run, kick off, or launch test suites on a pipeline stage; execute tests before or after a promotion; trigger a Pre-Promote, Post-Promote, or Review-event run; re-run a quality gate after fixing failures; retry a failed gate once coverage is met; or unblock a blocked promotion after adding tests. DO NOT TRIGGER when: running sf apex run test directly (use running-apex-tests); or configuring a NEW gate or threshold (use configuring-quality-gate)."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+---
+
+# Running a DevOps Center Test Suite
+
+## Prerequisites
+
+Load and follow `checking-devops-prerequisites` first — run Prerequisites 1–4 AND Prerequisite 5 (pipeline stage), since this skill operates on a specific stage. You need the confirmed `doce-org-alias`, `pipelineId`, and `stageId` before proceeding.
+
+## Inputs required before calling this skill
+
+| Input | How to obtain |
+|---|---|
+| `pipelineId` | From Prerequisite 4 (pipeline selection) |
+| `stageId` | From Prerequisite 5 (pipeline stage confirmation) |
+| `event` | Confirm with user: `Pre-Promote` or `Post-Promote` (or `Review` if the context is a review environment) |
+| `testSuiteIds` | Confirmed suite IDs from the suite selection or recommendation step |
+| `doce-org-alias` | Established in Prerequisite 1 |
+
+## Confirmation gate
+
+**This call mutates org state — do not proceed without explicit user confirmation.**
+
+Before calling the API, show the user:
+
+> "I'm about to run tests with the following configuration:
+> - Pipeline: `<pipelineName>`
+> - Stage: `<stageName>`
+> - Event: `<event>`
+> - Suite(s): `<suiteName(s)>`
+> - Org: `<doce-org-alias>`
+>
+> Shall I proceed?"
+
+Do not make the API call until the user confirms.
+
+## API call
+
+```bash
+sf api request rest \
+  "/services/data/v67.0/connect/devopstesting/pipeline/<pipelineId>/stage/execute" \
+  --method POST \
+  --body '{
+    "stageId": "<stageId>",
+    "event": "<event>",
+    "testSuiteIds": ["<suiteId1>", "<suiteId2>"]
+  }' \
+  --target-org <doce-org-alias>
+```
+
+### Body schema
+
+| Field | Type | Description |
+|---|---|---|
+| `stageId` | string | The ID of the pipeline stage to execute tests on |
+| `event` | string | `Pre-Promote`, `Post-Promote`, or `Review` |
+| `testSuiteIds` | string[] | One or more test suite IDs to execute |
+
+## On success
+
+Extract the `runId` (or execution ID) from the response. Inform the user:
+
+> "Tests are running in `<doce-org-alias>`. I'll update you when results are ready."
+
+Immediately hand off the `runId` to the `polling-test-results` skill to begin the polling loop.
+
+## On error
+
+| Status | Message to user |
+|---|---|
+| 400 | "The test execution request was invalid. Check that the stage and suite IDs are correct." |
+| 403 | "You don't have permission to run tests on this pipeline. Check your DevOps Testing API access." |
+| 404 | "The pipeline or stage was not found. It may have been deleted." |
+| 500 | "The DevOps Center org returned a server error. Try again in a few minutes." |
+
+Never expose raw API errors to the user.
+
+---
+
+## Retrigger mode (re-running a quality gate)
+
+Use this mode when a promotion was blocked by a quality gate failure and the coverage gap has since been addressed.
+
+### Extra preconditions — all must be true before proceeding
+
+1. The `Coverage` field on the latest `DevopsTestSuiteExecution` meets or exceeds the threshold defined in the `DevopsQualityGateRule`
+2. The user has explicitly asked to retrigger the gate
+3. The same `pipelineId`, `stageId`, and `event` from the blocked promotion are known
+
+If coverage is still below threshold, do **not** retrigger. Instead, respond:
+
+> "Coverage is still at `<X>%`, below the `<threshold>%` gate. The gate cannot be retriggered until the threshold is met. Here are the remaining uncovered methods: `<list>`."
+
+Do not retry. Explain what must be resolved first and stop.
+
+### Inputs required for retrigger
+
+| Input | Source |
+|---|---|
+| `pipelineId` | From the blocked promotion context |
+| `stageId` | From the blocked promotion context |
+| `event` | Same event type that originally blocked (`Pre-Promote` or `Post-Promote`) |
+| `suiteIds` | Same suites that were originally run |
+| `doce-org-alias` | Established in Prerequisite 1 |
+
+### Confirmation gate (retrigger)
+
+Before executing the API call, present this confirmation prompt and wait for explicit user approval:
+
+> "Coverage is confirmed at `<X>%`, which meets the `<threshold>%` gate. I'll retrigger the quality gate check for the `<stageName>` stage (`<event>`). Confirm?"
+
+Only proceed after the user confirms. If the user declines, stop without making any API call.
+
+### API call (retrigger)
+
+Uses the same Connect API stage/execute endpoint:
+
+```bash
+sf api request rest "/services/data/v67.0/connect/devopstesting/pipeline/<pipelineId>/stage/execute" --method POST --body '{"stageId":"<stageId>","event":"<event>","testSuiteIds":["<suiteId1>"]}' --target-org <doce-org-alias>
+```
+
+After the call returns a `runId`, hand off to the `polling-test-results` skill with the new `runId` to monitor the execution result.
+
+### Error handling (retrigger)
+
+If the API returns an error indicating the gate cannot be retriggered, respond with:
+
+> "The quality gate cannot be retriggered right now. Reason: `<plain-language summary>`. Here's what needs to be resolved first: `<list>`."
+
+Never expose raw API error details to the user.
+
+---
+
+## Related skills
+
+- **`polling-test-results`** — poll for async run results after receiving the `runId`
+- **`recommending-devops-tests`** — recommend which suites to run first before triggering execution
+- **`managing-suite-assignments`** — assign or map a suite to a pipeline stage if it isn't linked yet
+- **`configuring-quality-gate`** — configure a new gate or threshold