ci-cost-diff-action 0.1.0

package/src/cost.js

@@ -0,0 +1,603 @@
+import { normalizeRateOverrides, resolveRunnerRate } from "./rates.js";
+
+/**
+ * Workflow job fields consumed from the GitHub Actions jobs API.
+ * @typedef {object} GitHubJob
+ * @property {string|number} [id] Workflow job id.
+ * @property {string} [name] Display name from the workflow job.
+ * @property {string[]} [labels] Runner labels attached to the job.
+ * @property {string} [started_at] ISO timestamp when the job started.
+ * @property {string} [completed_at] ISO timestamp when the job completed.
+ * @property {string} [conclusion] Completed job conclusion.
+ * @property {string} [status] Current job status, used when conclusion is absent.
+ * @property {string} [runner_name] Concrete runner name, when GitHub provides it.
+ * @property {string} [runner_group_name] Runner group name, when available.
+ * @property {string} [check_run_url] Checks API URL containing the related check run id.
+ */
+
+/**
+ * Cost attribution for a single workflow job.
+ * @typedef {object} AnalyzedJob
+ * @property {string|number|undefined} id Workflow job id.
+ * @property {string} name Job display name.
+ * @property {string} conclusion Job conclusion or status fallback.
+ * @property {string|null} startedAt Start timestamp, or null when absent.
+ * @property {string|null} completedAt Completion timestamp, or null when absent.
+ * @property {string[]} labels Runner labels used for SKU inference.
+ * @property {string} runnerName Concrete runner name.
+ * @property {string} runnerGroupName Runner group name.
+ * @property {number} minutes Rounded-up billable minutes.
+ * @property {number|null} rate USD-per-minute rate, or null for unknown runners.
+ * @property {string} rateSource Source used to choose the rate.
+ * @property {string} rateWarning Warning emitted for ambiguous inferred rates.
+ * @property {string} sku Billing SKU or normalized override key.
+ * @property {number} cost Estimated job cost in USD.
+ * @property {string} [runLabel] Report label added when mixing current and baseline jobs.
+ */
+
+/**
+ * Aggregated cost data for jobs with the exact same name.
+ * @typedef {object} JobNameSummary
+ * @property {string} name Job name used as the aggregation key.
+ * @property {number} cost Total cost for matching jobs.
+ * @property {number} minutes Total rounded billable minutes.
+ * @property {number} runs Number of matching job executions.
+ * @property {AnalyzedJob[]} jobs Jobs included in the summary.
+ */
+
+/**
+ * Totals for all analyzed jobs in one workflow run.
+ * @typedef {object} AnalysisTotals
+ * @property {number} cost Total estimated cost in USD.
+ * @property {number} minutes Total rounded billable minutes.
+ * @property {number} unknownRunnerCount Count of jobs without a known rate.
+ * @property {number} jobCount Number of analyzed jobs.
+ */
+
+/**
+ * Analysis output for one workflow run.
+ * @typedef {object} AnalysisSummary
+ * @property {AnalyzedJob[]} jobs Jobs included in cost analysis.
+ * @property {string[]} skippedJobs Names of jobs skipped because they were excluded or incomplete.
+ * @property {Map<string, JobNameSummary>} byJobName Exact-name aggregation map.
+ * @property {AnalysisTotals} totals Run-level totals.
+ */
+
+/**
+ * Options that affect job analysis and runner pricing.
+ * @typedef {object} AnalyzeOptions
+ * @property {string[]} [excludePatterns] Wildcard job-name patterns to skip.
+ * @property {string[]} [excludeNames] Exact job names to skip.
+ * @property {(string|number)[]} [excludeJobIds] Workflow job ids to skip.
+ * @property {Record<string, number|string>|Map<string, number>} [rateOverrides] Runner rate overrides keyed by runner name, group, label, or SKU.
+ */
+
+/**
+ * Per-job-name delta between current and baseline analyses.
+ * @typedef {object} JobCostDelta
+ * @property {string} name Job name used for exact-name matching.
+ * @property {number} currentCost Current run cost for this job name.
+ * @property {number} baselineCost Baseline run cost for this job name.
+ * @property {number} deltaCost Current minus baseline cost.
+ * @property {number|null} deltaPercent Percent cost increase, or null for a zero baseline.
+ * @property {number} currentMinutes Current rounded billable minutes.
+ * @property {number} baselineMinutes Baseline rounded billable minutes.
+ * @property {number} deltaMinutes Current minus baseline rounded minutes.
+ * @property {number} currentRuns Current execution count for this job name.
+ * @property {number} baselineRuns Baseline execution count for this job name.
+ */
+
+/**
+ * Cost and minute deltas between current and baseline workflow runs.
+ * @typedef {object} CostDiff
+ * @property {number} currentCost Total current estimated cost in USD.
+ * @property {number} baselineCost Total baseline estimated cost in USD.
+ * @property {number} deltaCost Current minus baseline cost.
+ * @property {number|null} deltaPercent Percent cost increase, or null for a zero baseline.
+ * @property {number} currentMinutes Total current rounded billable minutes.
+ * @property {number} baselineMinutes Total baseline rounded billable minutes.
+ * @property {number} deltaMinutes Current minus baseline rounded minutes.
+ * @property {number|null} deltaMinutesPercent Percent minute increase, or null for a zero baseline.
+ * @property {JobCostDelta[]} jobs Per-job-name deltas sorted by absolute cost delta.
+ */
+
+/**
+ * Budget gates applied after cost analysis.
+ * @typedef {object} ThresholdOptions
+ * @property {number} [maxTotalUsd] Fail when current cost exceeds this USD amount.
+ * @property {number} [maxIncreaseUsd] Fail when cost delta exceeds this USD amount.
+ * @property {number} [maxIncreasePercent] Fail when cost delta percent exceeds this value.
+ */
+
+/**
+ * Result of applying budget gates.
+ * @typedef {object} ThresholdResult
+ * @property {"pass"|"fail"} conclusion Overall budget result.
+ * @property {string[]} failures Human-readable failure messages.
+ */
+
+const COMPARISON_EPSILON_MULTIPLIER = 8;
+
+/**
+ * Returns rounded-up billable minutes for a job interval.
+ * @param {string|null|undefined} startedAt Start timestamp.
+ * @param {string|null|undefined} completedAt Completion timestamp.
+ * @returns {number} Zero for missing, invalid, or negative intervals.
+ */
+export function roundedMinutes(startedAt, completedAt) {
+  if (!startedAt || !completedAt) {
+    return 0;
+  }
+
+  const started = new Date(startedAt).getTime();
+  const completed = new Date(completedAt).getTime();
+
+  if (!Number.isFinite(started) || !Number.isFinite(completed) || completed < started) {
+    return 0;
+  }
+
+  return Math.max(1, Math.ceil((completed - started) / 60000));
+}
+
+/**
+ * Checks whether a job name matches any exclusion pattern.
+ * @param {string} jobName Job name to test.
+ * @param {string[]} [patterns=[]] Wildcard patterns.
+ * @returns {boolean} True when the job should be excluded.
+ */
+export function shouldExcludeJob(jobName, patterns = []) {
+  return patterns.some((pattern) => wildcardMatches(jobName, pattern));
+}
+
+function wildcardMatches(value, pattern) {
+  const text = String(value).toLowerCase();
+  const normalizedPattern = String(pattern).trim().toLowerCase();
+  if (normalizedPattern === "") {
+    return text === "";
+  }
+
+  const parts = normalizedPattern.split("*");
+
+  return leadingWildcardMatch(text, normalizedPattern, parts)
+    && trailingWildcardMatch(text, normalizedPattern, parts)
+    && orderedWildcardPartsMatch(text, parts);
+}
+
+function leadingWildcardMatch(text, pattern, parts) {
+  return pattern.startsWith("*") || text.startsWith(parts[0] ?? "");
+}
+
+function trailingWildcardMatch(text, pattern, parts) {
+  return pattern.endsWith("*") || text.endsWith(parts.at(-1) ?? "");
+}
+
+function orderedWildcardPartsMatch(text, parts) {
+  let offset = 0;
+  for (const part of parts.filter(Boolean)) {
+    const index = text.indexOf(part, offset);
+    if (index === -1) {
+      return false;
+    }
+
+    offset = index + part.length;
+  }
+
+  return true;
+}
+
+/**
+ * Calculates cost attribution for one GitHub Actions job.
+ * @param {GitHubJob} job Job from the GitHub workflow jobs API.
+ * @param {AnalyzeOptions} [options] Analysis options.
+ * @returns {AnalyzedJob} Normalized job cost data.
+ */
+export function analyzeJob(job, options = {}) {
+  const rateOverrides = rateOverridesFromOptions(options);
+  const minutes = roundedMinutes(job.started_at, job.completed_at);
+  const rateInfo = resolveRunnerRate(job, rateOverrides);
+  const fields = analyzedJobFields(job);
+  const cost = jobCost(fields.name, minutes, rateInfo.rate);
+
+  return {
+    id: job.id,
+    ...fields,
+    minutes,
+    rate: rateInfo.rate,
+    rateSource: rateInfo.source,
+    rateWarning: rateWarning(rateInfo),
+    sku: rateInfo.sku,
+    cost
+  };
+}
+
+/**
+ * Analyzes a workflow run's jobs and aggregates them by exact job name.
+ * @param {GitHubJob[]} jobs Workflow jobs to analyze.
+ * @param {AnalyzeOptions} [options] Analysis options.
+ * @returns {AnalysisSummary} Per-job and run-level cost summary.
+ */
+export function analyzeJobs(jobs, options = {}) {
+  const { excludePatterns, excludeNames, excludeJobIds } = exclusionOptions(options);
+  const rateOverrides = rateOverridesFromOptions(options);
+  const analyzedJobs = [];
+  const skippedJobs = [];
+
+  for (const job of jobs) {
+    const skippedJob = skippedJobName(job, excludeJobIds, excludePatterns, excludeNames);
+    if (skippedJob !== null) {
+      skippedJobs.push(skippedJob);
+      continue;
+    }
+
+    analyzedJobs.push(analyzeJob(job, { rateOverrides }));
+  }
+
+  return {
+    jobs: analyzedJobs,
+    skippedJobs,
+    byJobName: groupJobsByName(analyzedJobs),
+    totals: analyzeTotals(analyzedJobs)
+  };
+}
+
+function analyzedJobFields(job) {
+  return {
+    name: jobName(job),
+    conclusion: jobConclusion(job),
+    startedAt: job.started_at ?? null,
+    completedAt: job.completed_at ?? null,
+    labels: jobLabels(job),
+    runnerName: job.runner_name ?? "",
+    runnerGroupName: job.runner_group_name ?? ""
+  };
+}
+
+function rateWarning(rateInfo) {
+  return rateInfo.warning ?? "";
+}
+
+function jobCost(name, minutes, rate) {
+  if (typeof rate !== "number") {
+    return 0;
+  }
+
+  const cost = minutes * rate;
+  if (!Number.isFinite(cost)) {
+    throw new Error(`Runner rate for job "${name}" produced a non-finite cost.`);
+  }
+
+  return cost;
+}
+
+function exclusionOptions(options) {
+  return {
+    excludePatterns: options.excludePatterns ?? [],
+    excludeNames: new Set(options.excludeNames ?? []),
+    excludeJobIds: new Set((options.excludeJobIds ?? []).map((id) => String(id)))
+  };
+}
+
+function analyzeTotals(jobs) {
+  return jobs.reduce((acc, job) => addJobTotals(acc, job), {
+    cost: 0,
+    minutes: 0,
+    unknownRunnerCount: 0,
+    jobCount: jobs.length
+  });
+}
+
+function addJobTotals(acc, job) {
+  acc.cost = finiteCostSum(acc.cost, job.cost);
+  acc.minutes += job.minutes;
+  acc.unknownRunnerCount += unknownRunnerCount(job);
+  return acc;
+}
+
+function finiteCostSum(left, right) {
+  const sum = left + right;
+  if (!Number.isFinite(sum)) {
+    throw new Error("Analyzed job costs produced a non-finite total.");
+  }
+
+  return sum;
+}
+
+function unknownRunnerCount(job) {
+  return job.rate === null ? 1 : 0;
+}
+
+function groupJobsByName(jobs) {
+  const byJobName = new Map();
+  for (const job of jobs) {
+    addJobToNameGroup(byJobName, job);
+  }
+
+  return byJobName;
+}
+
+function addJobToNameGroup(byJobName, job) {
+  const existing = byJobName.get(job.name) ?? emptyJobNameSummary(job.name);
+
+  existing.cost = finiteCostSum(existing.cost, job.cost);
+  existing.minutes += job.minutes;
+  existing.runs += 1;
+  existing.jobs.push(job);
+  byJobName.set(job.name, existing);
+}
+
+function emptyJobNameSummary(name) {
+  return {
+    name,
+    cost: 0,
+    minutes: 0,
+    runs: 0,
+    jobs: []
+  };
+}
+
+/**
+ * Computes current-versus-baseline cost deltas.
+ * @param {AnalysisSummary} current Current run analysis.
+ * @param {AnalysisSummary} baseline Baseline run analysis.
+ * @returns {CostDiff} Total and per-job-name deltas.
+ */
+export function diffSummaries(current, baseline) {
+  const currentCost = current.totals.cost;
+  const baselineCost = baseline.totals.cost;
+  const deltaCost = currentCost - baselineCost;
+  const deltaPercent = baselineCost > 0 ? (deltaCost / baselineCost) * 100 : null;
+  const currentMinutes = current.totals.minutes;
+  const baselineMinutes = baseline.totals.minutes;
+  const deltaMinutes = currentMinutes - baselineMinutes;
+  const deltaMinutesPercent = baselineMinutes > 0 ? (deltaMinutes / baselineMinutes) * 100 : null;
+
+  const jobNames = new Set([
+    ...current.byJobName.keys(),
+    ...baseline.byJobName.keys()
+  ]);
+
+  const jobs = [...jobNames]
+    .map((name) => diffJobName(name, current.byJobName, baseline.byJobName))
+    .sort((a, b) => Math.abs(b.deltaCost) - Math.abs(a.deltaCost));
+
+  return {
+    currentCost,
+    baselineCost,
+    deltaCost,
+    deltaPercent,
+    currentMinutes,
+    baselineMinutes,
+    deltaMinutes,
+    deltaMinutesPercent,
+    jobs
+  };
+}
+
+function rateOverridesFromOptions(options) {
+  return normalizeRateOverrides(options.rateOverrides ?? {});
+}
+
+function skippedJobName(job, excludeJobIds, excludePatterns, excludeNames) {
+  const name = jobName(job);
+  if (excludeJobIds.has(String(job.id))) {
+    return name;
+  }
+
+  if (excludeNames.has(name)) {
+    return name;
+  }
+
+  if (shouldExcludeJob(name, excludePatterns)) {
+    return name;
+  }
+
+  return hasValidCompletedInterval(job) ? null : name;
+}
+
+function hasValidCompletedInterval(job) {
+  if (!job.started_at || !job.completed_at) {
+    return false;
+  }
+
+  const started = new Date(job.started_at).getTime();
+  const completed = new Date(job.completed_at).getTime();
+  return Number.isFinite(started) && Number.isFinite(completed) && completed >= started;
+}
+
+function jobName(job) {
+  return job.name ?? "Unnamed job";
+}
+
+function jobLabels(job) {
+  return Array.isArray(job.labels) ? job.labels : [];
+}
+
+function jobConclusion(job) {
+  return job.conclusion ?? job.status ?? "unknown";
+}
+
+function diffJobName(name, currentByJobName, baselineByJobName) {
+  const current = jobNameTotals(currentByJobName.get(name));
+  const baseline = jobNameTotals(baselineByJobName.get(name));
+  const deltaCost = current.cost - baseline.cost;
+
+  return {
+    name,
+    currentCost: current.cost,
+    baselineCost: baseline.cost,
+    deltaCost,
+    deltaPercent: baseline.cost > 0 ? (deltaCost / baseline.cost) * 100 : null,
+    currentMinutes: current.minutes,
+    baselineMinutes: baseline.minutes,
+    deltaMinutes: current.minutes - baseline.minutes,
+    currentRuns: current.runs,
+    baselineRuns: baseline.runs
+  };
+}
+
+function jobNameTotals(summary) {
+  return {
+    cost: summary?.cost ?? 0,
+    minutes: summary?.minutes ?? 0,
+    runs: summary?.runs ?? 0
+  };
+}
+
+/**
+ * Applies configured budget thresholds to a cost diff.
+ * @param {CostDiff} diff Current-versus-baseline cost diff.
+ * @param {ThresholdOptions} [thresholds] Budget thresholds.
+ * @returns {ThresholdResult} Pass/fail conclusion and failure messages.
+ */
+export function evaluateThresholds(diff, thresholds = {}) {
+  const normalizedThresholds = thresholdOptions(thresholds);
+  const failures = [];
+  addFailure(failures, totalBudgetFailure(diff, normalizedThresholds.maxTotalUsd));
+  addFailure(failures, increaseUsdFailure(diff, normalizedThresholds.maxIncreaseUsd));
+  addFailure(failures, increasePercentFailure(diff, normalizedThresholds.maxIncreasePercent));
+
+  return {
+    conclusion: failures.length > 0 ? "fail" : "pass",
+    failures
+  };
+}
+
+function thresholdOptions(thresholds) {
+  return {
+    maxTotalUsd: thresholdValue(thresholds.maxTotalUsd, "maxTotalUsd"),
+    maxIncreaseUsd: thresholdValue(thresholds.maxIncreaseUsd, "maxIncreaseUsd"),
+    maxIncreasePercent: thresholdValue(thresholds.maxIncreasePercent, "maxIncreasePercent")
+  };
+}
+
+function thresholdValue(value, name) {
+  if (value === undefined || value === null || value === "") {
+    return undefined;
+  }
+
+  if (!Number.isFinite(value)) {
+    throw new Error(`${name} must be a finite non-negative number.`);
+  }
+
+  if (value < 0) {
+    throw new Error(`${name} must be a non-negative number.`);
+  }
+
+  return value;
+}
+
+function addFailure(failures, failure) {
+  if (failure) {
+    failures.push(failure);
+  }
+}
+
+function totalBudgetFailure(diff, maxTotalUsd) {
+  if (Number.isFinite(maxTotalUsd) && !Number.isFinite(diff.currentCost)) {
+    return "current estimated cost is non-finite; check runner rates.";
+  }
+
+  if (!exceedsThreshold(diff.currentCost, maxTotalUsd)) {
+    return "";
+  }
+
+  return `current estimated cost ${formatUsd(diff.currentCost)} is above total budget ${formatUsd(maxTotalUsd)}`;
+}
+
+function increaseUsdFailure(diff, maxIncreaseUsd) {
+  if (Number.isFinite(maxIncreaseUsd) && !Number.isFinite(diff.deltaCost)) {
+    return "estimated cost increase is non-finite; check runner rates.";
+  }
+
+  if (!exceedsThreshold(diff.deltaCost, maxIncreaseUsd)) {
+    return "";
+  }
+
+  return `estimated cost increased by ${formatUsd(diff.deltaCost)}, above ${formatUsd(maxIncreaseUsd)}`;
+}
+
+function increasePercentFailure(diff, maxIncreasePercent) {
+  if (!Number.isFinite(maxIncreasePercent)) {
+    return "";
+  }
+
+  if (diff.deltaPercent === null) {
+    return zeroBaselinePercentFailure(diff);
+  }
+
+  if (!Number.isFinite(diff.deltaPercent)) {
+    return "estimated cost increase percentage is non-finite; check runner rates.";
+  }
+
+  if (exceedsThreshold(diff.deltaPercent, maxIncreasePercent)) {
+    return `estimated cost increased by ${formatPercent(diff.deltaPercent)}, above ${formatPercent(maxIncreasePercent)}`;
+  }
+
+  return "";
+}
+
+function zeroBaselinePercentFailure(diff) {
+  if (diff.baselineCost !== 0 || diff.currentCost <= 0) {
+    return "";
+  }
+
+  return `estimated cost increased from $0.00 to ${formatUsd(diff.currentCost)}; percentage increase cannot be computed against a zero baseline`;
+}
+
+function exceedsThreshold(value, threshold) {
+  if (!Number.isFinite(value) || !Number.isFinite(threshold)) {
+    return false;
+  }
+
+  return value - threshold > comparisonTolerance(value, threshold);
+}
+
+function comparisonTolerance(value, threshold) {
+  return Number.EPSILON * COMPARISON_EPSILON_MULTIPLIER * Math.max(1, Math.abs(value), Math.abs(threshold));
+}
+
+/**
+ * Formats USD values for report output.
+ * @param {number} value USD value.
+ * @returns {string} Dollar-formatted value.
+ */
+export function formatUsd(value) {
+  const abs = Math.abs(value);
+  const digits = usdDigits(abs);
+  const rounded = Number(abs.toFixed(digits));
+  if (isTinyNonzeroUsd(abs, rounded)) {
+    return `${usdSign(value)}<$0.0001`;
+  }
+
+  return `${usdSign(value)}$${rounded.toFixed(digits)}`;
+}
+
+function usdDigits(abs) {
+  return abs > 0 && abs < 0.01 ? 4 : 2;
+}
+
+function isTinyNonzeroUsd(abs, rounded) {
+  return abs > 0 && rounded === 0;
+}
+
+function usdSign(value) {
+  return value < 0 ? "-" : "";
+}
+
+/**
+ * Formats percentage values for report output.
+ * @param {number|null|undefined} value Percentage value.
+ * @returns {string} Signed percentage or `n/a`.
+ */
+export function formatPercent(value) {
+  if (value === null || value === undefined || !Number.isFinite(value)) {
+    return "n/a";
+  }
+
+  const rounded = Number(value.toFixed(1));
+  if (rounded === 0) {
+    return "0.0%";
+  }
+
+  return `${rounded > 0 ? "+" : ""}${rounded.toFixed(1)}%`;
+}