extract-rule-names-and-run-validation.js

// @ts-check

/**
 * Extract rule names from GitHub PR and run AutoRest validation
 *
 * This script combines rule extraction and AutoRest execution into a single operation.
 * It reads PR labels and body from GitHub context, extracts rule names, and runs
 * the selected rules against Azure REST API specs.
 *
 * Usage in GitHub Actions:
 * Uses github-script action with direct access to context and core
 */

import { existsSync, mkdirSync, readdirSync, writeFileSync } from "fs";
import { basename, dirname, join, relative } from "path";
import { fileURLToPath } from "url";
import { execNpmExec, isExecError } from "../../shared/src/exec.js";

const __dirname = dirname(fileURLToPath(import.meta.url));

/**
 * Extract rule names from PR labels
 * Expects labels in format: test-<RuleName>
 * @param {Array<string | {name: string}>} labels - Array of label names or label objects
 * @returns {string[]} - Array of extracted rule names
 */
export function extractRulesFromLabels(labels) {
  // If labels are objects (GitHub API), map to their name first.
  const names = labels.map((l) => (l && typeof l === "object" ? l.name : l));
  return names
    .filter((name) => /^test-/i.test(name))
    .map((name) => name.replace(/^test-/i, "").trim())
    .filter(Boolean);
}

/**
 * Extract rule names from GitHub context
 * Extracts rules from PR labels with test- prefix
 * @param {import('@actions/github-script').AsyncFunctionArguments['context']} context - GitHub Actions context object
 * @returns {string[]} - Array of unique rule names
 */
export function extractRuleNames(context) {
  const pr = context.payload.pull_request;
  if (!pr) return [];

  return extractRulesFromLabels(pr.labels ?? []);
}

/**
 * Enumerate stable ARM swagger files.
 * Criteria: contains /resource-manager/ and /stable/, ends with .json.
 * Excludes examples, readme, quickstart-templates, scenarios.
 * Distributes files randomly across all allowed RPs to ensure diversity.
 * @param {string} specRoot - Root directory containing specifications
 * @param {string[]} allowedRPs - Array of allowed resource provider names
 * @param {number} maxFiles - Maximum number of files to return
 * @returns {string[]} - Array of file paths
 */
function enumerateSpecs(specRoot, allowedRPs, maxFiles) {
  /** @param {string} p */
  const isStableArm = (p) => /\/resource-manager\//.test(p) && /\/stable\//.test(p);
  const allFiles = [];

  // Collect all matching files from all RPs
  for (const rp of allowedRPs) {
    const rpRoot = join(specRoot, "specification", rp);
    if (!existsSync(rpRoot)) continue;

    const stack = [rpRoot];
    while (stack.length > 0) {
      const current = stack.pop();
      if (!current) continue;

      let entries;
      try {
        entries = readdirSync(current, { withFileTypes: true });
      } catch {
        continue;
      }

      for (const entry of entries) {
        const abs = join(current, entry.name);
        if (entry.isDirectory()) {
          stack.push(abs);
          continue;
        }
        if (!entry.isFile()) continue;
        if (!abs.toLowerCase().endsWith(".json")) continue;

        const norm = abs.replace(/\\/g, "/");
        if (!isStableArm(norm)) continue;
        if (/\/examples\//i.test(norm)) continue;
        if (/readme\.(md|json)$/i.test(norm)) continue;
        if (/quickstart-templates\//i.test(norm)) continue;
        if (/\/scenarios\//i.test(norm)) continue;

        allFiles.push(abs);
      }
    }
  }

  // Shuffle using sort with random comparator and take first maxFiles
  const results = allFiles.sort(() => Math.random() - 0.5).slice(0, maxFiles);

  // Log distribution for transparency
  console.log(`Collected ${results.length} files randomly from ${allFiles.length} total files`);
  const rpCounts = new Map();
  for (const file of results) {
    const match = file.match(/specification[/\\]([^/\\]+)[/\\]/);
    if (match) {
      const rp = match[1];
      rpCounts.set(rp, (rpCounts.get(rp) || 0) + 1);
    }
  }
  rpCounts.forEach((count, rp) => {
    console.log(`  ${rp}: ${count} files`);
  });

  return results;
}

/**
 * Run AutoRest against a single specification file
 * @param {string} specPath - Path to the specification file
 * @param {string} specRoot - Root directory of specifications
 * @param {string[]} selectedRules - Array of rule names to validate
 * @param {string} repoRoot - Root directory of the repository
 * @returns {Promise<import("../../shared/src/exec.js").ExecResult>}
 */
async function runAutorest(specPath, specRoot, selectedRules, repoRoot) {
  const start = Date.now();
  const rel = relative(specRoot, specPath).replace(/\\/g, "/");
  const args = [
    "autorest",
    "--level=warning",
    "--v3",
    "--spectral",
    "--azure-validator",
    "--semantic-validator=false",
    "--model-validator=false",
    "--openapi-type=arm",
    "--openapi-subtype=arm",
    "--message-format=json",
    // Pass selected rules down to the validator so only those rules execute inside the plugins.
    `--selected-rules=${selectedRules.join(",")}`,
    `--use=${join(repoRoot, "packages", "azure-openapi-validator", "autorest")}`,
    `--input-file=${specPath}`,
  ];

  const result = await execNpmExec(args, {
    // Call "npm exec autorest" from the folder containing this JS file, to ensure it's available
    // in a parent node_modules
    cwd: __dirname,
  });

  const dur = Date.now() - start;
  console.log(`DEBUG | runAutorest | end | ${rel} (${dur}ms)`);

  return result;
}

/**
 * Parse AutoRest output for validation messages
 * @param {string} stdout - Standard output from AutoRest
 * @param {string} stderr - Standard error output from AutoRest
 * @returns {any[]} - Array of parsed validation messages
 */
function parseMessages(stdout, stderr) {
  /** @type {any[]} */
  const msgs = [];
  const allOutput = stdout + "\n" + stderr;
  console.log(`DEBUG | parseMessages | Total output length: ${allOutput.length} characters`);

  allOutput.split(/\r?\n/).forEach((line, idx) => {
    if (!line.includes('"extensionName":"@microsoft.azure/openapi-validator"')) return;

    const i = line.indexOf("{");
    if (i < 0) {
      console.log(`DEBUG | parseMessages | Line ${idx} has no opening brace`);
      return;
    }

    try {
      const parsed = JSON.parse(line.slice(i));
      msgs.push(parsed);
    } catch (e) {
      const errorMessage = e instanceof Error ? e.message : String(e);
      console.log(`DEBUG | parseMessages | Line ${idx} failed to parse: ${errorMessage}`);
    }
  });

  return msgs;
}

/**
 * Check if the PR has a specific label
 * Reads directly from the event payload — no GitHub API calls needed.
 * @param {import('@actions/github-script').AsyncFunctionArguments['context']} context
 * @param {string} labelName
 * @returns {boolean}
 */
export function hasLabel(context, labelName) {
  const labels = context.payload.pull_request?.labels ?? [];
  return labels.some(
    (/** @type {string | {name: string}} */ l) =>
      (typeof l === "object" ? l.name : l).toLowerCase() === labelName.toLowerCase(),
  );
}

/**
 * Evaluate blocking conditions after validation completes.
 * Triggers core.setFailed() when merge should be blocked.
 *
 * Blocking scenarios:
 * 1. Command failures — AutoRest or script crashes
 * 2. Validation errors without "errors-acknowledged" label
 *
 * @param {object} params
 * @param {import('@actions/github-script').AsyncFunctionArguments['context']} params.context
 * @param {import('@actions/github-script').AsyncFunctionArguments['core']} params.core
 * @param {{ specs: number, errors: number, warnings: number, commandFailures: number }} params.result
 */
export function checkBlockingConditions({ context, core, result }) {
  const { errors, warnings, commandFailures } = result;

  // Scenario 1: Command failures always block
  if (commandFailures > 0) {
    core.setFailed(
      `Pipeline execution failed with ${commandFailures} command failure(s). ` +
        "Review the logs and linter-findings artifact for details.",
    );
    return;
  }

  // Scenario 2: Validation errors block unless acknowledged
  if (errors > 0) {
    if (hasLabel(context, ERRORS_ACKNOWLEDGED_LABEL)) {
      core.warning(
        `Found ${errors} validation error(s) and ${warnings} warning(s). ` +
          `Proceeding because "${ERRORS_ACKNOWLEDGED_LABEL}" label is present. ` +
          "Reviewer approval is still required.",
      );
    } else {
      core.setFailed(
        `Found ${errors} validation error(s). Action required:\n` +
          "  1. Review the errors in the linter-findings artifact\n" +
          `  2. Add the "${ERRORS_ACKNOWLEDGED_LABEL}" label to this PR to confirm you have reviewed them\n` +
          "  3. The workflow will automatically re-run when the label is added",
      );
    }
  }
}

/** Label name used to acknowledge validation errors on a PR. */
export const ERRORS_ACKNOWLEDGED_LABEL = "errors-acknowledged";

/**
 * Regex pattern matching linter rule source file paths.
 * Covers both spectral and native rule paths.
 */
export const RULE_FILE_PATTERN =
  /^packages\/rulesets\/src\/spectral\/(az-arm|az-common|az-dataplane|functions\/.+)\.ts$|^packages\/rulesets\/src\/native\/(legacyRules|functions|rulesets)\/.+\.ts$/;

/**
 * Detect whether any linter rule source files were changed in the current PR.
 * Uses the GitHub REST API (pulls.listFiles) via the Octokit client provided by
 * actions/github-script
 *
 * @param {import('@actions/github-script').AsyncFunctionArguments['github']} github - Octokit client
 * @param {import('@actions/github-script').AsyncFunctionArguments['context']} context - GitHub Actions context
 * @returns {Promise<boolean>} - true if rule files were changed
 */
export async function detectRuleChanges(github, context) {
  const pr = context.payload.pull_request;
  if (!pr) return false;

  // Paginate to handle PRs with many changed files
  const files = await github.paginate(github.rest.pulls.listFiles, {
    owner: context.repo.owner,
    repo: context.repo.repo,
    pull_number: pr.number,
    per_page: 100,
  });

  const changedRuleFiles = files.filter(
    (f) => (f.status === "added" || f.status === "modified") && RULE_FILE_PATTERN.test(f.filename),
  );

  if (changedRuleFiles.length > 0) {
    console.log("Detected rule file changes:");
    changedRuleFiles.forEach((f) => console.log(`  ${f.status}\t${f.filename}`));
    return true;
  }

  console.log("No rule file changes detected");
  return false;
}

/**
 * Main execution function for GitHub Actions
 * @param {import('@actions/github-script').AsyncFunctionArguments} AsyncFunctionArguments
 */
export default async function runInGitHubActions({ github, context, core }) {
  try {
    const ruleChangesDetected = await detectRuleChanges(github, context);

    // Extract rule names from PR
    const selectedRules = extractRuleNames(context);

    core.notice(
      `Selected Rules: ${selectedRules.length > 0 ? selectedRules.join(", ") : "<none>"}`,
    );

    if (selectedRules.length === 0) {
      // Scenario 1: Rule changes without test rules
      if (ruleChangesDetected) {
        core.setFailed(
          "Rule changes detected but no test rules specified. " +
            "Add test-<RuleName> labels to this PR.",
        );
        return;
      }

      console.log("No linter-related changes found in the PR. Exiting with empty findings file.");
      // Create empty output file
      const outputFile = join(
        process.env.GITHUB_WORKSPACE || "",
        "artifacts",
        "linter-findings.txt",
      );
      mkdirSync(dirname(outputFile), { recursive: true });
      writeFileSync(
        outputFile,
        "INFO | Runner | summary | Files scanned: 0, Errors: 0, Warnings: 0, Command failures: 0\n",
      );
      return;
    }

    const result = await runValidation(selectedRules, process.env, core);

    // Evaluate blocking conditions (scenarios 2 & 3)
    checkBlockingConditions({ context, core, result });

    return result;
  } catch (error) {
    const errorMessage = error instanceof Error ? error.message : String(error);
    core.setFailed(`Script execution failed: ${errorMessage}`);
    throw error;
  }
}

/**
 * Core validation logic
 * @param {string[]} selectedRules - Array of rule names to validate
 * @param {any} env - Environment variables object
 * @param {import('@actions/github-script').AsyncFunctionArguments['core'] | null} core - GitHub Actions core object (optional)
 * @returns {Promise<{ specs: number, errors: number, warnings: number, commandFailures: number }>}
 */
export async function runValidation(selectedRules, env, core = null) {
  const repoRoot = env.GITHUB_WORKSPACE || process.cwd();
  const specRoot = join(repoRoot, env.SPEC_CHECKOUT_PATH || "specs");
  const maxFiles = parseInt(env.MAX_FILES || "100", 10);
  const allowedRps = (env.ALLOWED_RPS || "compute,monitor,sql,hdinsight,network,resource,storage")
    .split(",")
    .map((/** @type {string} */ s) => s.trim())
    .filter(Boolean);
  const outputFile = join(repoRoot, "artifacts", "linter-findings.txt");

  console.log(`Processing rules: ${selectedRules.join(", ")}`);
  console.log(`Max files: ${maxFiles}, Allowed RPs: ${allowedRps.join(", ")}`);
  console.log(`Spec root: ${specRoot}`);

  let specs;
  try {
    specs = enumerateSpecs(specRoot, allowedRps, maxFiles);
  } catch (err) {
    const errorMessage = err instanceof Error ? err.message : String(err);
    const message = `Failed to enumerate specs: ${errorMessage}`;
    if (core) {
      core.setFailed(message);
    } else {
      console.error(`ERROR | ${message}`);
    }
    return { specs: 0, errors: 0, warnings: 0, commandFailures: 0 };
  }
  if (!specs.length) {
    const message = "No matching spec files found";
    if (core) {
      core.warning(message);
    } else {
      console.log(`WARN | ${message}`);
    }

    mkdirSync(dirname(outputFile), { recursive: true });
    writeFileSync(
      outputFile,
      "INFO | Runner | summary | Files scanned: 0, Errors: 0, Warnings: 0, Command failures: 0\n",
    );
    return { specs: 0, errors: 0, warnings: 0, commandFailures: 0 };
  }

  console.log(`Processing ${specs.length} file(s)`);
  let errors = 0;
  let warnings = 0;
  let commandFailures = 0;
  const outLines = [];
  const seenErrors = new Set(); // Track unique errors to avoid duplicates from $ref resolution

  // Process each spec file sequentially
  for (const spec of specs) {
    let res;
    try {
      res = await runAutorest(spec, specRoot, selectedRules, repoRoot);
    } catch (error) {
      commandFailures++;
      const specRelPath = relative(specRoot, spec).replace(/\\/g, "/");
      const errorMessage = error instanceof Error ? error.message : String(error);
      console.log(`Failed ${spec}: ${errorMessage}`);
      if (isExecError(error)) {
        if (error.stdout) console.log(`  stdout: ${error.stdout}`);
        if (error.stderr) console.log(`  stderr: ${error.stderr}`);
        if (error.code !== undefined) console.log(`  exit code: ${error.code}`);
      }
      outLines.push(`ERROR | CommandFailed | ${specRelPath} | ${errorMessage}`);
      continue;
    }

    const messages = parseMessages(res.stdout, res.stderr);
    const specRelPath = relative(specRoot, spec).replace(/\\/g, "/");
    const specBasename = basename(spec);
    console.log(`Found ${messages.length} message(s) for ${specRelPath}`);

    for (const m of messages) {
      const code = m.code || m.id || "Unknown";
      if (selectedRules.indexOf(code) === -1) continue;

      // Extract the actual source file from the message
      // The source field contains the actual file where the error occurred
      let errorSourceFile = null;
      let errorSourcePath = null;

      if (m.source && Array.isArray(m.source) && m.source.length > 0) {
        const sourceEntry = m.source[0];
        if (sourceEntry && sourceEntry.document) {
          // Extract file path from URI like "file:///home/runner/.../applicationGateway.json"
          errorSourcePath = sourceEntry.document;
          const match = errorSourcePath.match(/([^/\\]+)\.json$/i);
          if (match) {
            errorSourceFile = match[0]; // e.g., "applicationGateway.json"
          }
        }
      }

      // Skip errors that don't have source information or don't match the spec being processed
      if (!errorSourceFile) {
        const jsonpath = m.details?.jsonpath?.[1] || "unknown";
        console.log(`DEBUG | Skipping error with no source field - path: ${jsonpath}`);
        continue;
      }

      if (errorSourceFile !== specBasename) {
        console.log(
          `DEBUG | Skipping error from different file - error source: ${errorSourceFile}, current spec: ${specBasename}`,
        );
        continue;
      }

      console.log(`DEBUG | Processing error from matching file: ${errorSourceFile}`);

      // Extract line and column from the source position (more accurate than other fields)
      const line =
        m.source?.[0]?.position?.line ??
        m.details?.range?.start?.line ??
        m.range?.start?.line ??
        undefined;
      const column =
        m.source?.[0]?.position?.column ??
        m.details?.range?.start?.column ??
        m.range?.start?.character ??
        undefined;
      const loc = line !== undefined ? `:${line}${column !== undefined ? `:${column}` : ""}` : "";

      // Create unique signature for error deduplication
      // Even with source filtering, the same file might be validated multiple times
      const errorSignature = `${errorSourceFile}:${line}:${column}:${code}:${m.message || ""}`;

      if (seenErrors.has(errorSignature)) {
        console.log(`DEBUG | Skipping duplicate error: ${errorSignature}`);
        continue;
      }
      seenErrors.add(errorSignature);

      const level = (m.level || "").toLowerCase();
      const sev = level === "error" ? "ERROR" : level === "warning" ? "WARN" : "INFO";
      if (sev === "ERROR") errors++;
      else if (sev === "WARN") warnings++;

      outLines.push(`${sev} | ${code} | ${specRelPath}${loc} | ${m.message || ""}`.trim());
    }
  }

  // Output results
  const summary = `INFO | Runner | summary | Files scanned: ${specs.length}, Errors: ${errors}, Warnings: ${warnings}, Command failures: ${commandFailures}`;
  console.log(summary);

  // Write output file
  mkdirSync(dirname(outputFile), { recursive: true });
  writeFileSync(outputFile, outLines.concat([summary]).join("\n") + "\n", "utf8");

  return { specs: specs.length, errors, warnings, commandFailures };
}