ci-cost-diff-action 0.1.0

package/src/report.js

@@ -0,0 +1,258 @@
+import { createHash } from "node:crypto";
+import { formatPercent, formatUsd } from "./cost.js";
+
+const COMMENT_MARKER_ID = "ci-cost-diff-action";
+const MARKER_SCOPE_MAX_LENGTH = 120;
+const MARKER_SCOPE_HASH_LENGTH = 12;
+const MAX_REPORT_LENGTH = 60000;
+const MAX_REPORT_FIELD_LENGTH = 500;
+const MAX_LINK_DESTINATION_LENGTH = 1000;
+const REPORT_TRUNCATION_NOTICE = `\n\n> Report truncated because it exceeded ${MAX_REPORT_LENGTH} characters. Reduce job and runner field sizes or exclusions for more detail.\n`;
+
+/**
+ * Minimal workflow run reference used in Markdown reports.
+ * @typedef {object} RunRef
+ * @property {string|number} [id] Workflow run id.
+ * @property {string|number} [run_number] Human-readable workflow run number.
+ * @property {string} [head_branch] Branch name associated with the run.
+ * @property {string} [html_url] Browser URL for the run.
+ */
+
+/**
+ * Report rendering inputs.
+ * @typedef {object} RenderReportOptions
+ * @property {import("./cost.js").CostDiff} diff Current-versus-baseline cost diff.
+ * @property {RunRef} currentRun Current workflow run reference.
+ * @property {RunRef|null} baselineRun Baseline workflow run reference, or null when absent.
+ * @property {import("./cost.js").ThresholdResult} thresholdResult Budget threshold result.
+ * @property {import("./cost.js").AnalyzedJob[]} [unknownJobs] Jobs with unknown runner rates.
+ * @property {import("./cost.js").AnalyzedJob[]} [ambiguousRateJobs] Jobs with ambiguous default-rate fallback.
+ * @property {string} [marker] Stable HTML marker embedded for PR comment updates.
+ */
+
+/**
+ * Returns the stable marker used to find existing PR comments.
+ * @param {string} [scope=""] Optional stable scope for one workflow/action instance.
+ * @returns {string} HTML comment marker.
+ */
+export function commentMarker(scope = "") {
+  const normalizedScope = markerScope(scope);
+  return normalizedScope
+    ? `<!-- ${COMMENT_MARKER_ID}:${normalizedScope} -->`
+    : `<!-- ${COMMENT_MARKER_ID} -->`;
+}
+
+function markerScope(scope) {
+  const rawScope = String(scope ?? "").trim();
+  if (!rawScope) {
+    return "";
+  }
+
+  const digest = createHash("sha256").update(rawScope).digest("hex").slice(0, MARKER_SCOPE_HASH_LENGTH);
+  const maxPrefixLength = MARKER_SCOPE_MAX_LENGTH - MARKER_SCOPE_HASH_LENGTH - 1;
+  const prefix = rawScope
+    .toLowerCase()
+    .replace(/[^a-z0-9_.-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, maxPrefixLength)
+    .replace(/-+$/g, "");
+
+  return prefix ? `${prefix}-${digest}` : digest;
+}
+
+/**
+ * Renders the Markdown report written to the step summary and PR comments.
+ * @param {RenderReportOptions} options Report rendering inputs.
+ * @returns {string} Markdown report with trailing newline.
+ */
+export function renderReport({ diff, currentRun, baselineRun, thresholdResult, unknownJobs = [], ambiguousRateJobs = [], marker = commentMarker() }) {
+  const lines = [
+    marker,
+    "# CI Cost Diff",
+    "",
+    renderConclusion(thresholdResult),
+    "",
+    "## Summary",
+    "",
+    "| Metric | Current | Baseline | Delta |",
+    "| --- | ---: | ---: | ---: |",
+    `| Estimated cost | ${formatUsd(diff.currentCost)} | ${formatUsd(diff.baselineCost)} | ${formatUsd(diff.deltaCost)} (${formatPercent(diff.deltaPercent)}) |`,
+    `| Rounded billable minutes | ${diff.currentMinutes} | ${diff.baselineMinutes} | ${signedNumber(diff.deltaMinutes)} (${formatPercent(diff.deltaMinutesPercent)}) |`,
+    "",
+    "## Compared Runs",
+    "",
+    `- Current: ${formatRun(currentRun)}`,
+    `- Baseline: ${baselineRun ? formatRun(baselineRun) : "not found"}`,
+    "",
+    "## Largest Job Deltas",
+    "",
+    "| Job | Current | Baseline | Delta | Minutes |",
+    "| --- | ---: | ---: | ---: | ---: |"
+  ];
+
+  lines.push(
+    ...renderJobDeltaRows(diff.jobs),
+    ...renderUnknownRunnerRates(unknownJobs),
+    ...renderAmbiguousRunnerRates(ambiguousRateJobs),
+    ...renderBudgetFailures(thresholdResult.failures),
+    "",
+    "> Estimates use rounded job minutes and runner list prices. Public repositories, included minutes, custom runner contracts, and larger-runner labels can affect real billing."
+  );
+
+  return capReportLength(`${lines.join("\n")}\n`);
+}
+
+function renderJobDeltaRows(jobs) {
+  if (jobs.length === 0) {
+    return ["| No comparable jobs | $0.00 | $0.00 | $0.00 | 0/0 |"];
+  }
+
+  return limitedRows(jobs, 12, (job) => `| ${escapeTableCell(job.name)} | ${formatUsd(job.currentCost)} | ${formatUsd(job.baselineCost)} | ${formatUsd(job.deltaCost)} (${formatPercent(job.deltaPercent)}) | ${job.currentMinutes}/${job.baselineMinutes} |`);
+}
+
+function renderUnknownRunnerRates(jobs) {
+  return renderRunnerRateJobs({
+    jobs,
+    heading: "Unknown Runner Rates",
+    description: "These jobs were counted as `$0.00` because their runner could not be mapped to a rate. Add `runner-rates` overrides for custom or larger runners.",
+    header: "| Run | Job | Labels | Runner |",
+    divider: "| --- | --- | --- | --- |",
+    row: (job) => `| ${runLabel(job)} | ${escapeTableCell(job.name)} | ${escapeTableCell(job.labels.join(", "))} | ${escapeTableCell(job.runnerName || "unknown")} |`
+  });
+}
+
+function renderAmbiguousRunnerRates(jobs) {
+  return renderRunnerRateJobs({
+    jobs,
+    heading: "Ambiguous Runner Rates",
+    description: "These jobs used a standard-runner fallback or broad class override, but their labels look custom or larger-runner-like. Add specific `runner-rates` overrides for accurate billing.",
+    header: "| Run | Job | SKU Used | Labels |",
+    divider: "| --- | --- | --- | --- |",
+    row: (job) => `| ${runLabel(job)} | ${escapeTableCell(job.name)} | ${escapeTableCell(job.sku)} | ${escapeTableCell(job.labels.join(", "))} |`
+  });
+}
+
+function renderRunnerRateJobs({ jobs, heading, description, header, divider, row }) {
+  if (jobs.length === 0) {
+    return [];
+  }
+
+  return [
+    "",
+    `## ${heading}`,
+    "",
+    description,
+    "",
+    header,
+    divider,
+    ...limitedRows(jobs, 20, row)
+  ];
+}
+
+function limitedRows(items, limit, row) {
+  const rows = items.slice(0, limit).map(row);
+  return items.length > limit
+    ? [...rows, `> ... and ${items.length - limit} more job(s) not shown.`]
+    : rows;
+}
+
+function renderBudgetFailures(failures) {
+  if (failures.length === 0) {
+    return [];
+  }
+
+  return ["", "## Budget Failures", "", ...failures.map((failure) => `- ${failure}`)];
+}
+
+function capReportLength(report) {
+  if (report.length <= MAX_REPORT_LENGTH) {
+    return report;
+  }
+
+  const bodyLength = MAX_REPORT_LENGTH - REPORT_TRUNCATION_NOTICE.length;
+  return `${report.slice(0, bodyLength).trimEnd()}${REPORT_TRUNCATION_NOTICE}`;
+}
+
+function runLabel(job) {
+  return escapeTableCell(job.runLabel ?? "current");
+}
+
+function renderConclusion(thresholdResult) {
+  if (thresholdResult.conclusion === "fail") {
+    return "**Conclusion:** budget check failed.";
+  }
+
+  return "**Conclusion:** budget check passed.";
+}
+
+function formatRun(run) {
+  if (!run) {
+    return "not found";
+  }
+
+  const label = `#${escapeInlineMarkdown(run.run_number ?? run.id)}`;
+  const branch = run.head_branch ? ` on ${codeSpan(run.head_branch)}` : "";
+  const link = run.html_url ? ` ([open](${linkDestination(run.html_url)}))` : "";
+  return `${label}${branch}${link}`;
+}
+
+function linkDestination(value) {
+  const url = truncateText(value, MAX_LINK_DESTINATION_LENGTH).replace(/\r?\n/g, "").replace(/</g, "%3C").replace(/>/g, "%3E");
+  return `<${url}>`;
+}
+
+function signedNumber(value) {
+  return value > 0 ? `+${value}` : String(value);
+}
+
+function escapeTableCell(value) {
+  return truncateText(value)
+    .replace(/&/g, "&amp;")
+    .replace(/\r?\n/g, " ")
+    .replace(/\|/g, "&#124;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/\\/g, "&#92;")
+    .replace(/`/g, "&#96;")
+    .replace(/!/g, "&#33;")
+    .replace(/\*/g, "&#42;")
+    .replace(/_/g, "&#95;")
+    .replace(/~/g, "&#126;")
+    .replace(/\[/g, "&#91;")
+    .replace(/\]/g, "&#93;")
+    .replace(/\(/g, "&#40;")
+    .replace(/\)/g, "&#41;");
+}
+
+function escapeInlineMarkdown(value) {
+  return truncateText(value)
+    .replace(/\r?\n/g, " ")
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/\\/g, "&#92;")
+    .replace(/`/g, "&#96;")
+    .replace(/!/g, "&#33;")
+    .replace(/\*/g, "&#42;")
+    .replace(/_/g, "&#95;")
+    .replace(/~/g, "&#126;")
+    .replace(/\[/g, "&#91;")
+    .replace(/\]/g, "&#93;")
+    .replace(/\(/g, "&#40;")
+    .replace(/\)/g, "&#41;");
+}
+
+function codeSpan(value) {
+  const text = truncateText(value).replace(/\r?\n/g, " ");
+  const backtickRuns = text.match(/`+/g) ?? [];
+  const delimiterLength = Math.max(1, ...backtickRuns.map((run) => run.length + 1));
+  const delimiter = "`".repeat(delimiterLength);
+  const padding = text.startsWith("`") || text.endsWith("`") || text.startsWith(" ") || text.endsWith(" ") ? " " : "";
+
+  return `${delimiter}${padding}${text}${padding}${delimiter}`;
+}
+
+function truncateText(value, limit = MAX_REPORT_FIELD_LENGTH) {
+  const text = String(value ?? "");
+  return text.length > limit ? `${text.slice(0, limit)}...` : text;
+}