flecto 3.0.0 → 3.0.2

package/src/pr-comment.js

@@ -1,6 +1,8 @@
 import { readFileSync } from 'fs';
 import { isAbsolute, relative } from 'path';
 
+import { PR_PROVIDERS, selectPrProvider } from './pr-providers.js';
+
 /**
  * Hidden marker embedded in every rendered body. Flecto finds its own comment by
  * searching for this string, so repeated runs update one sticky comment instead
@@ -8,21 +10,23 @@ import { isAbsolute, relative } from 'path';
  */
 export const PR_COMMENT_MARKER = '<!-- flecto:pr-comment -->';
 
-const DEFAULT_API_URL = 'https://api.github.com';
 const DEFAULT_TIMEOUT_MS = 10_000;
 /** GitHub rejects comment bodies longer than 65536 characters. */
 const MAX_BODY_CHARS = 60_000;
 const MAX_INLINE_CHANGES = 10;
 const MAX_VALUE_CHARS = 120;
 const MAX_COMMENT_PAGES = 10;
-const COMMENTS_PER_PAGE = 100;
 const SEVERITY_ORDER = ['error', 'warn', 'info'];
 const SEVERITY_HEADINGS = { error: 'Errors', warn: 'Warnings', info: 'Notices' };
 const SEVERITY_NOUNS = { error: 'error', warn: 'warning', info: 'notice' };
 
 /**
  * @typedef {{ file: string, envelope: import('./envelope.js').FlectoEnvelope, policies?: import('./policy.js').PolicyFinding[] }} CiResult
- * @typedef {{ repo: string, prNumber: number, token: string, apiUrl: string }} PrCommentContext
+ * @typedef {{ provider?: string, prNumber: number, token: string, apiUrl: string,
+ *   repo?: string, projectId?: string, webUrl?: string, workspace?: string, repoSlug?: string
+ * }} PrCommentContext The fields a delivery adapter resolved; which ones are
+ *   present depends on the provider. A context built by hand carries no
+ *   `provider` and is treated as GitHub.
  */
 
 /**
@@ -233,70 +237,30 @@ export function renderPrComment(results, options = {}) {
 }
 
 /**
- * @param {Record<string, string | undefined>} env
- * @param {(path: string) => string} readEventFile
- * @returns {number | null}
- */
-function resolvePrNumber(env, readEventFile) {
-  const fromRef = /^refs\/pull\/(\d+)\/(?:merge|head)$/u.exec(env.GITHUB_REF ?? '');
-  if (fromRef) return Number(fromRef[1]);
-
-  const eventPath = env.GITHUB_EVENT_PATH;
-  if (!eventPath) return null;
-
-  let event;
-  try {
-    event = JSON.parse(readEventFile(eventPath));
-  } catch {
-    return null;
-  }
-
-  const candidates = [
-    event?.pull_request?.number,
-    // issue_comment events on a PR carry the PR number under `issue`, but a
-    // plain issue must not be mistaken for one.
-    event?.issue?.pull_request ? event?.issue?.number : undefined,
-    event?.number,
-  ];
-  for (const candidate of candidates) {
-    const value = Number(candidate);
-    if (Number.isInteger(value) && value > 0) return value;
-  }
-  return null;
-}
-
-/**
- * Resolve the GitHub API context needed to post a pull request comment.
+ * Resolve the API context needed to post a merge request comment.
  *
- * Only `GITHUB_TOKEN` is honored — `GH_TOKEN` is deliberately ignored because
- * `gh auth login` exports it on developer machines, where posting would be a
- * surprise.
+ * The provider is detected from CI environment variables, or forced with
+ * `provider`. GitHub is the fallback, so an unrecognized environment reports
+ * the message it always did rather than a new one about detection.
  * @param {Record<string, string | undefined>} [env]
- * @param {{ readEventFile?: (path: string) => string }} [options]
+ * @param {{ readEventFile?: (path: string) => string, provider?: string }} [options]
  * @returns {{ ok: true, context: PrCommentContext } | { ok: false, reason: string }}
  */
 export function resolvePrCommentContext(env = process.env, options = {}) {
   const readEventFile = options.readEventFile ?? ((path) => readFileSync(path, 'utf8'));
-  const token = String(env.GITHUB_TOKEN ?? '').trim();
-  if (!token) {
-    return { ok: false, reason: 'GITHUB_TOKEN is not set' };
-  }
-
-  const repo = String(env.GITHUB_REPOSITORY ?? '').trim();
-  if (!/^[^/\s]+\/[^/\s]+$/u.test(repo)) {
-    return { ok: false, reason: 'GITHUB_REPOSITORY is not set to "owner/repo"' };
-  }
-
-  const prNumber = resolvePrNumber(env, readEventFile);
-  if (!prNumber) {
-    return {
-      ok: false,
-      reason: 'no pull request number in GITHUB_REF or GITHUB_EVENT_PATH (not a pull request run)',
-    };
-  }
+  const selected = selectPrProvider(env, options.provider);
+  if (!selected.ok) return selected;
+  return selected.provider.resolve(env, { readEventFile });
+}
 
-  const apiUrl = String(env.GITHUB_API_URL || DEFAULT_API_URL).replace(/\/+$/u, '');
-  return { ok: true, context: { repo, prNumber, token, apiUrl } };
+/**
+ * The adapter a resolved context belongs to. Contexts built by hand — as tests
+ * and embedders do — carry no provider and are GitHub, which is what they were
+ * before there was a choice.
+ * @param {{ provider?: string }} context
+ */
+function providerFor(context) {
+  return PR_PROVIDERS.find((p) => p.id === context?.provider) ?? PR_PROVIDERS[0];
 }
 
 /**
@@ -333,10 +297,10 @@ async function errorDetail(response, token) {
 }
 
 /**
- * @param {{ fetchImpl: typeof fetch, url: string, method: string, token: string, body?: unknown, timeoutMs: number }} request
+ * @param {{ fetchImpl: typeof fetch, provider: object, url: string, method: string, token: string, body?: unknown, timeoutMs: number }} request
  * @returns {Promise<Response>}
  */
-async function githubRequest({ fetchImpl, url, method, token, body, timeoutMs }) {
+async function apiRequest({ fetchImpl, provider, url, method, token, body, timeoutMs }) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   let response;
@@ -344,11 +308,10 @@ async function githubRequest({ fetchImpl, url, method, token, body, timeoutMs })
     response = await fetchImpl(url, {
       method,
       headers: {
-        Accept: 'application/vnd.github+json',
-        Authorization: `Bearer ${token}`,
+        Accept: provider.accept ?? 'application/json',
         'Content-Type': 'application/json',
         'User-Agent': 'flecto',
-        'X-GitHub-Api-Version': '2022-11-28',
+        ...provider.authHeaders(token),
       },
       body: body === undefined ? undefined : JSON.stringify(body),
       signal: controller.signal,
@@ -357,14 +320,14 @@ async function githubRequest({ fetchImpl, url, method, token, body, timeoutMs })
     const reason = err?.name === 'AbortError'
       ? `timed out after ${timeoutMs}ms`
       : redact(err?.message ?? String(err), token);
-    throw new Error(`GitHub API ${method} failed: ${reason}`);
+    throw new Error(`${provider.label} API ${method} failed: ${reason}`);
   } finally {
     clearTimeout(timer);
   }
 
   if (!response.ok) {
     throw new Error(
-      `GitHub API ${method} returned HTTP ${response.status}${await errorDetail(response, token)}`,
+      `${provider.label} API ${method} returned HTTP ${response.status}${await errorDetail(response, token)}`,
     );
   }
   return response;
@@ -374,20 +337,19 @@ async function githubRequest({ fetchImpl, url, method, token, body, timeoutMs })
  * Find the sticky Flecto comment on a pull request, if one exists.
  * @param {PrCommentContext} context
  * @param {{ fetchImpl: typeof fetch, marker: string, timeoutMs: number }} options
- * @returns {Promise<{ id: number, body?: string, html_url?: string } | null>}
+ * @returns {Promise<{ id: string | number, body?: string, url?: string } | null>}
  */
 async function findStickyComment(context, { fetchImpl, marker, timeoutMs }) {
+  const provider = providerFor(context);
   for (let page = 1; page <= MAX_COMMENT_PAGES; page += 1) {
-    const url = `${context.apiUrl}/repos/${context.repo}/issues/${context.prNumber}`
-      + `/comments?per_page=${COMMENTS_PER_PAGE}&page=${page}`;
-    const response = await githubRequest({
-      fetchImpl, url, method: 'GET', token: context.token, timeoutMs,
+    const response = await apiRequest({
+      fetchImpl, provider, url: provider.listUrl(context, page), method: 'GET', token: context.token, timeoutMs,
     });
-    const comments = await response.json();
-    if (!Array.isArray(comments) || comments.length === 0) return null;
+    const comments = provider.readList(await response.json());
+    if (comments.length === 0) return null;
     const match = comments.find((c) => typeof c?.body === 'string' && c.body.includes(marker));
     if (match) return match;
-    if (comments.length < COMMENTS_PER_PAGE) return null;
+    if (comments.length < provider.perPage) return null;
   }
   return null;
 }
@@ -404,6 +366,7 @@ export async function upsertPrComment(body, context, options = {}) {
   const fetchImpl = options.fetchImpl ?? globalThis.fetch;
   const marker = options.marker ?? PR_COMMENT_MARKER;
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const provider = providerFor(context);
   if (typeof fetchImpl !== 'function') {
     throw new Error('Global fetch unavailable. Use Node.js >= 20.19.0.');
   }
@@ -411,39 +374,41 @@ export async function upsertPrComment(body, context, options = {}) {
   const existing = await findStickyComment(context, { fetchImpl, marker, timeoutMs });
 
   if (!existing) {
-    const response = await githubRequest({
+    const response = await apiRequest({
       fetchImpl,
-      url: `${context.apiUrl}/repos/${context.repo}/issues/${context.prNumber}/comments`,
+      provider,
+      url: provider.createUrl(context),
       method: 'POST',
       token: context.token,
-      body: { body },
+      body: provider.payload(body),
       timeoutMs,
     });
     const created = await response.json().catch(() => ({}));
-    return { action: 'created', url: created?.html_url };
+    return { action: 'created', url: provider.readOne(created, context).url };
   }
 
   // Rendering is deterministic, so an identical body means nothing moved since
   // the last run — skip the write and the "edited" noise it creates.
   if (existing.body === body) {
-    return { action: 'unchanged', url: existing.html_url };
+    return { action: 'unchanged', url: existing.url };
   }
 
-  const response = await githubRequest({
+  const response = await apiRequest({
     fetchImpl,
-    url: `${context.apiUrl}/repos/${context.repo}/issues/comments/${existing.id}`,
-    method: 'PATCH',
+    provider,
+    url: provider.updateUrl(context, existing.id),
+    method: provider.updateMethod,
     token: context.token,
-    body: { body },
+    body: provider.payload(body),
     timeoutMs,
   });
   const updated = await response.json().catch(() => ({}));
-  return { action: 'updated', url: updated?.html_url ?? existing.html_url };
+  return { action: 'updated', url: provider.readOne(updated, context).url ?? existing.url };
 }
 
 /**
  * Post the sticky comment when — and only when — posting was explicitly enabled
- * and a complete GitHub pull request context is present.
+ * and a complete merge request context is present.
  *
  * Never throws and never reports the token: a delivery problem must not change
  * the CI exit code, which belongs to the diff and policy result alone.
@@ -454,7 +419,8 @@ export async function upsertPrComment(body, context, options = {}) {
  *   fetchImpl?: typeof fetch,
  *   marker?: string,
  *   timeoutMs?: number,
- *   readEventFile?: (path: string) => string
+ *   readEventFile?: (path: string) => string,
+ *   provider?: string
  * }} [options]
  * @returns {Promise<{ posted: boolean, action?: 'created' | 'updated' | 'unchanged', url?: string, reason?: string }>}
  */

package/src/pr-providers.js

@@ -0,0 +1,261 @@
+/**
+ * Delivery adapters for the sticky review comment.
+ *
+ * Everything upstream of delivery — the differ, the policy engine, the
+ * envelope, and the rendered comment body — is provider-agnostic markdown.
+ * Only the last step differs, so only the last step lives here: which
+ * environment variables identify a merge request, how the host authenticates,
+ * and the three URLs needed to list, create, and update a comment.
+ *
+ * Adding a provider means adding one object to {@link PR_PROVIDERS}. Nothing
+ * else in Flecto needs to know it exists.
+ */
+
+const GITHUB_API_URL = 'https://api.github.com';
+const GITLAB_API_URL = 'https://gitlab.com/api/v4';
+const BITBUCKET_API_URL = 'https://api.bitbucket.org/2.0';
+
+/**
+ * @typedef {{
+ *   id: string,
+ *   label: string,
+ *   perPage: number,
+ *   detect: (env: Record<string, string | undefined>) => boolean,
+ *   resolve: (
+ *     env: Record<string, string | undefined>,
+ *     helpers: { readEventFile: (path: string) => string },
+ *   ) => { ok: true, context: object } | { ok: false, reason: string },
+ *   authHeaders: (token: string) => Record<string, string>,
+ *   accept?: string,
+ *   listUrl: (context: any, page: number) => string,
+ *   readList: (payload: unknown) => { id: string | number, body: string, url?: string }[],
+ *   createUrl: (context: any) => string,
+ *   updateUrl: (context: any, id: string | number) => string,
+ *   updateMethod: string,
+ *   payload: (body: string) => object,
+ *   readOne: (payload: any, context: any) => { url?: string },
+ * }} PrProvider
+ */
+
+/** Trim trailing slashes from a base URL. */
+function trimUrl(value, fallback) {
+  return String(value || fallback).replace(/\/+$/u, '');
+}
+
+/**
+ * Pull request number from the GitHub ref, then the event payload.
+ * @param {Record<string, string | undefined>} env
+ * @param {(path: string) => string} readEventFile
+ * @returns {number | null}
+ */
+function githubPrNumber(env, readEventFile) {
+  const fromRef = /^refs\/pull\/(\d+)\/(?:merge|head)$/u.exec(env.GITHUB_REF ?? '');
+  if (fromRef) return Number(fromRef[1]);
+
+  const eventPath = env.GITHUB_EVENT_PATH;
+  if (!eventPath) return null;
+
+  let event;
+  try {
+    event = JSON.parse(readEventFile(eventPath));
+  } catch {
+    return null;
+  }
+
+  const candidates = [
+    event?.pull_request?.number,
+    // issue_comment events on a PR carry the PR number under `issue`, but a
+    // plain issue must not be mistaken for one.
+    event?.issue?.pull_request ? event?.issue?.number : undefined,
+    event?.number,
+  ];
+  for (const candidate of candidates) {
+    const value = Number(candidate);
+    if (Number.isInteger(value) && value > 0) return value;
+  }
+  return null;
+}
+
+/** @type {PrProvider} */
+const github = {
+  id: 'github',
+  label: 'GitHub',
+  perPage: 100,
+  accept: 'application/vnd.github+json',
+  detect: (env) => Boolean(env.GITHUB_ACTIONS || env.GITHUB_REPOSITORY || env.GITHUB_EVENT_PATH),
+
+  resolve(env, { readEventFile }) {
+    // Only GITHUB_TOKEN is honored — GH_TOKEN is deliberately ignored because
+    // `gh auth login` exports it on developer machines, where posting would be
+    // a surprise.
+    const token = String(env.GITHUB_TOKEN ?? '').trim();
+    if (!token) return { ok: false, reason: 'GITHUB_TOKEN is not set' };
+
+    const repo = String(env.GITHUB_REPOSITORY ?? '').trim();
+    if (!/^[^/\s]+\/[^/\s]+$/u.test(repo)) {
+      return { ok: false, reason: 'GITHUB_REPOSITORY is not set to "owner/repo"' };
+    }
+
+    const prNumber = githubPrNumber(env, readEventFile);
+    if (!prNumber) {
+      return {
+        ok: false,
+        reason: 'no pull request number in GITHUB_REF or GITHUB_EVENT_PATH (not a pull request run)',
+      };
+    }
+
+    return {
+      ok: true,
+      context: { provider: 'github', repo, prNumber, token, apiUrl: trimUrl(env.GITHUB_API_URL, GITHUB_API_URL) },
+    };
+  },
+
+  authHeaders: (token) => ({ Authorization: `Bearer ${token}`, 'X-GitHub-Api-Version': '2022-11-28' }),
+  listUrl: (c, page) => `${c.apiUrl}/repos/${c.repo}/issues/${c.prNumber}/comments?per_page=${github.perPage}&page=${page}`,
+  readList: (payload) => (Array.isArray(payload) ? payload : []).map((c) => ({ id: c?.id, body: c?.body, url: c?.html_url })),
+  createUrl: (c) => `${c.apiUrl}/repos/${c.repo}/issues/${c.prNumber}/comments`,
+  updateUrl: (c, id) => `${c.apiUrl}/repos/${c.repo}/issues/comments/${id}`,
+  updateMethod: 'PATCH',
+  payload: (body) => ({ body }),
+  readOne: (payload) => ({ url: payload?.html_url }),
+};
+
+/** @type {PrProvider} */
+const gitlab = {
+  id: 'gitlab',
+  label: 'GitLab',
+  perPage: 100,
+  detect: (env) => Boolean(env.GITLAB_CI || env.CI_MERGE_REQUEST_IID),
+
+  resolve(env) {
+    // CI_JOB_TOKEN is present on every GitLab job and cannot write notes, so
+    // silently trying it would produce a 401 that reads like a broken setup.
+    // Name the fix instead.
+    const token = String(env.FLECTO_GITLAB_TOKEN ?? env.GITLAB_TOKEN ?? '').trim();
+    if (!token) {
+      return {
+        ok: false,
+        reason: env.CI_JOB_TOKEN
+          ? 'no GitLab API token: CI_JOB_TOKEN cannot post merge request notes. '
+            + 'Set FLECTO_GITLAB_TOKEN to a project or group access token with the "api" scope.'
+          : 'FLECTO_GITLAB_TOKEN (or GITLAB_TOKEN) is not set',
+      };
+    }
+
+    const projectId = String(env.CI_PROJECT_ID ?? '').trim();
+    if (!projectId) return { ok: false, reason: 'CI_PROJECT_ID is not set' };
+
+    const iid = Number(env.CI_MERGE_REQUEST_IID);
+    if (!Number.isInteger(iid) || iid <= 0) {
+      return { ok: false, reason: 'CI_MERGE_REQUEST_IID is not set (not a merge request pipeline)' };
+    }
+
+    return {
+      ok: true,
+      context: {
+        provider: 'gitlab',
+        projectId,
+        prNumber: iid,
+        token,
+        apiUrl: trimUrl(env.CI_API_V4_URL, GITLAB_API_URL),
+        webUrl: String(env.CI_MERGE_REQUEST_PROJECT_URL ?? '').replace(/\/+$/u, ''),
+      },
+    };
+  },
+
+  authHeaders: (token) => ({ 'PRIVATE-TOKEN': token }),
+  listUrl: (c, page) => `${gitlabNotesBase(c)}?per_page=${gitlab.perPage}&page=${page}`,
+  readList: (payload) => (Array.isArray(payload) ? payload : []).map((n) => ({ id: n?.id, body: n?.body })),
+  createUrl: (c) => gitlabNotesBase(c),
+  updateUrl: (c, id) => `${gitlabNotesBase(c)}/${id}`,
+  updateMethod: 'PUT',
+  payload: (body) => ({ body }),
+  readOne: (payload, c) => (c?.webUrl && payload?.id
+    ? { url: `${c.webUrl}/-/merge_requests/${c.prNumber}#note_${payload.id}` }
+    : {}),
+};
+
+/** Notes collection for the merge request. Project ids may be paths, so encode. */
+function gitlabNotesBase(c) {
+  return `${c.apiUrl}/projects/${encodeURIComponent(c.projectId)}/merge_requests/${c.prNumber}/notes`;
+}
+
+/** @type {PrProvider} */
+const bitbucket = {
+  id: 'bitbucket',
+  label: 'Bitbucket',
+  perPage: 100,
+  detect: (env) => Boolean(env.BITBUCKET_PR_ID || env.BITBUCKET_REPO_SLUG),
+
+  resolve(env) {
+    const token = String(env.FLECTO_BITBUCKET_TOKEN ?? env.BITBUCKET_TOKEN ?? '').trim();
+    if (!token) return { ok: false, reason: 'FLECTO_BITBUCKET_TOKEN (or BITBUCKET_TOKEN) is not set' };
+
+    const workspace = String(env.BITBUCKET_WORKSPACE ?? '').trim();
+    const repoSlug = String(env.BITBUCKET_REPO_SLUG ?? '').trim();
+    if (!workspace || !repoSlug) {
+      return { ok: false, reason: 'BITBUCKET_WORKSPACE and BITBUCKET_REPO_SLUG must both be set' };
+    }
+
+    const prId = Number(env.BITBUCKET_PR_ID);
+    if (!Number.isInteger(prId) || prId <= 0) {
+      return { ok: false, reason: 'BITBUCKET_PR_ID is not set (not a pull request pipeline)' };
+    }
+
+    return {
+      ok: true,
+      context: {
+        provider: 'bitbucket',
+        workspace,
+        repoSlug,
+        prNumber: prId,
+        token,
+        apiUrl: trimUrl(env.BITBUCKET_API_URL, BITBUCKET_API_URL),
+      },
+    };
+  },
+
+  authHeaders: (token) => ({ Authorization: `Bearer ${token}` }),
+  listUrl: (c, page) => `${bitbucketCommentsBase(c)}?pagelen=${bitbucket.perPage}&page=${page}`,
+  readList: (payload) => (Array.isArray(payload?.values) ? payload.values : []).map((c) => ({
+    id: c?.id,
+    body: c?.content?.raw,
+    url: c?.links?.html?.href,
+  })),
+  createUrl: (c) => bitbucketCommentsBase(c),
+  updateUrl: (c, id) => `${bitbucketCommentsBase(c)}/${id}`,
+  updateMethod: 'PUT',
+  payload: (body) => ({ content: { raw: body } }),
+  readOne: (payload) => ({ url: payload?.links?.html?.href }),
+};
+
+function bitbucketCommentsBase(c) {
+  return `${c.apiUrl}/repositories/${c.workspace}/${c.repoSlug}/pullrequests/${c.prNumber}/comments`;
+}
+
+/** Detection order. GitHub stays first so its behavior is unchanged. */
+export const PR_PROVIDERS = [github, gitlab, bitbucket];
+
+export const PR_PROVIDER_IDS = PR_PROVIDERS.map((p) => p.id);
+
+/**
+ * Pick the delivery adapter.
+ *
+ * An explicit id always wins. Otherwise the first provider whose CI variables
+ * are present is used, and GitHub is the fallback so an unrecognized
+ * environment produces the same message it always did rather than a new one
+ * about provider detection.
+ * @param {Record<string, string | undefined>} env
+ * @param {string} [explicit]
+ * @returns {{ ok: true, provider: PrProvider } | { ok: false, reason: string }}
+ */
+export function selectPrProvider(env, explicit) {
+  if (explicit) {
+    const found = PR_PROVIDERS.find((p) => p.id === explicit);
+    if (!found) {
+      return { ok: false, reason: `unknown pr provider "${explicit}" (expected ${PR_PROVIDER_IDS.join(', ')})` };
+    }
+    return { ok: true, provider: found };
+  }
+  return { ok: true, provider: PR_PROVIDERS.find((p) => p.detect(env)) ?? github };
+}

package/src/renderer.js

@@ -211,13 +211,13 @@ export function maskSensitiveValue(value, path = '') {
     && typeof value === 'object'
     && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)
   ) {
-    /** @type {Record<string, unknown>} */
-    const out = {};
-    for (const [k, v] of Object.entries(value)) {
-      const child = path ? `${path}.${k}` : k;
-      out[k] = maskSensitiveValue(v, child);
-    }
-    return out;
+    // Object.fromEntries rather than `out[k] = ...`: assigning a key literally
+    // named "__proto__" runs the prototype setter instead of creating an own
+    // property, so that whole subtree would vanish from the masked output
+    // rather than being rendered masked.
+    return Object.fromEntries(
+      Object.entries(value).map(([k, v]) => [k, maskSensitiveValue(v, path ? `${path}.${k}` : k)]),
+    );
   }
   if (typeof value === 'string') return redactSecretString(value);
   return value;

package/src/report.js

@@ -245,6 +245,13 @@ function snapshotCard(snapshot, index) {
   } else if (count > 0) {
     // changeCount without events: the caller summarized but did not diff.
     body.push(`<p class="empty">${escapeHtml(plural(count, 'change'))} recorded.</p>`);
+  } else if (!previous) {
+    // Nothing was compared here, so "no changes" would be a claim this card
+    // cannot support (#141). Say what actually happened instead.
+    body.push(
+      '<p class="empty">First snapshot of this file — there is no earlier state to'
+      + ' compare it against. That is <strong>no history</strong>, not no drift.</p>',
+    );
   } else {
     body.push('<p class="empty">No semantic changes from the previous snapshot.</p>');
   }
@@ -257,11 +264,14 @@ function snapshotCard(snapshot, index) {
   }
 
   const countClass = count > 0 ? 'count count-active' : 'count';
+  // A first snapshot is labelled "baseline" rather than "0 changes": the count
+  // is only meaningful once there is something on the other side of it.
+  const countLabel = previous ? plural(count, 'change') : 'baseline';
   return [
     `<details class="card" open id="snapshot-${escapeHtml(String(index))}">`,
     '<summary>',
     `<time class="stamp" datetime="${escapeHtml(time.iso)}">${escapeHtml(time.label)}</time>`,
-    `<span class="${countClass}">${escapeHtml(plural(count, 'change'))}</span>`,
+    `<span class="${countClass}">${escapeHtml(countLabel)}</span>`,
     baselineNote,
     '</summary>',
     `<div class="card-body">${body.join('')}</div>`,
@@ -442,6 +452,14 @@ tr:last-child td { border-bottom: 0; }
 .sev-warn { color: var(--warn); }
 .sev-info { color: var(--info); }
 .empty { color: var(--muted); margin: 8px 0; }
+.banner {
+  border: 1px solid var(--warn);
+  border-left-width: 4px;
+  border-radius: 6px;
+  background: var(--panel);
+  padding: 10px 14px;
+  margin: 0 0 24px;
+}
 .no-matches { color: var(--muted); margin: 16px 0; }
 footer { margin-top: 40px; padding-top: 14px; border-top: 1px solid var(--border); color: var(--muted); font-size: 0.82rem; }
 .hidden { display: none !important; }
@@ -513,8 +531,13 @@ export function renderReportHtml(data = {}) {
   /** @type {Array<{ file: string, snapshot: ReportSnapshot, finding: import('./policy.js').PolicyFinding }>} */
   const allFindings = [];
   let totalChanges = 0;
+  // How many of these snapshots actually had an earlier one to be compared
+  // against. Zero means the report compared nothing, which is a different
+  // statement from "compared everything and found nothing" (#141).
+  let comparisons = 0;
   for (const snapshot of snapshots) {
     const changes = changesOf(snapshot);
+    if (snapshot.previousCreatedAt) comparisons += 1;
     // Prefer the events actually carried; fall back to the count for callers
     // that summarized without diffing.
     totalChanges += Array.isArray(snapshot.changes)
@@ -556,12 +579,26 @@ export function renderReportHtml(data = {}) {
     '<section class="stats">',
     statTile('Snapshots', String(snapshots.length)),
     statTile('Files', String(groups.length)),
+    // "Changes" alone reads as an all-clear at 0 whether or not anything was
+    // ever compared, so the number of comparisons behind it sits next to it.
+    statTile('Comparisons', String(comparisons)),
     statTile('Changes', String(totalChanges)),
     statTile('Policy errors', String(severityCounts.error), 'error'),
     statTile('Policy warnings', String(severityCounts.warn), 'warn'),
     '</section>',
   ].join('');
 
+  // The failure mode this guards against: a CI job takes its first snapshot and
+  // renders a report from it, and the page reads as "nothing drifted" when the
+  // truth is that there was no history to look at. Say so above the fold.
+  const noHistoryBanner = comparisons === 0
+    ? '<p class="banner">Nothing in this report was compared. Every snapshot here is'
+      + ' the first one of its file, so there is no earlier state to measure drift'
+      + ' against — this is <strong>no history</strong>, not <strong>no drift</strong>.'
+      + ' Snapshot history is local to the working directory, so a fresh CI runner'
+      + ' starts with none of it.</p>'
+    : '';
+
   const findingsSection = allFindings.length === 0
     ? '<h2>Policy findings</h2><p class="empty">No policy findings across these snapshots.</p>'
     : [
@@ -603,6 +640,7 @@ export function renderReportHtml(data = {}) {
   return htmlDocument([
     head,
     stats,
+    noHistoryBanner,
     findingsSection,
     `<h2>Snapshot timeline (${escapeHtml(plural(snapshots.length, 'snapshot'))})</h2>`,
     controls,