flecto 3.0.1 → 3.1.0

package/src/pr-providers.js

@@ -0,0 +1,268 @@
+/**
+ * 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 }),
+};
+
+/**
+ * Comments collection for the pull request. The workspace and slug are encoded
+ * for the same reason GitLab's project id is: they are interpolated into a URL
+ * path, and a value carrying `/`, `?`, or `#` would otherwise restructure the
+ * request rather than name a repository.
+ */
+function bitbucketCommentsBase(c) {
+  return `${c.apiUrl}/repositories/${encodeURIComponent(c.workspace)}`
+    + `/${encodeURIComponent(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

@@ -1,20 +1,8 @@
 import chalk from 'chalk';
-import { redactSecretString } from './secrets.js';
+import { looksLikeSecretPath, redactSecretString } from './secrets.js';
 import { ENCRYPTED_DISPLAY, displayEncrypted, isEncryptedSentinel } from './encrypted.js';
 import { secretMatchPath } from './differ.js';
 
-/**
- * Key names that mean "this value is a credential".
- *
- * Matched against the *configuration* path only. A multi-document file prefixes
- * every path with the document's identity — `Deployment/prod/token-service.…` —
- * and that identity is a resource name the user chose, not a key name. Letting
- * it match here masked every value in the document, numbers and booleans
- * included, so the path reaching this regex is always the one
- * {@link secretMatchPath} produced.
- */
-const SECRET_PATH_RE = /(secret|token|password|api[_-]?key|private[_-]?key|credential)/i;
-
 /**
  * Format a scalar value for display. Strings get quoted; others are JSON-stringified.
  * @param {unknown} v
@@ -28,7 +16,7 @@ function fmt(v, opts = {}) {
   if (isEncryptedSentinel(v)) return chalk.dim(ENCRYPTED_DISPLAY);
   let value = displayEncrypted(v);
   if (opts.maskSecrets) {
-    if (opts.path && SECRET_PATH_RE.test(opts.path)) {
+    if (opts.path && looksLikeSecretPath(opts.path)) {
       return chalk.dim('"***"');
     }
     // The changed path itself can look benign while the value carries secrets,
@@ -202,7 +190,7 @@ export function renderPolicyFindings(findings) {
  * @returns {unknown}
  */
 export function maskSensitiveValue(value, path = '') {
-  if (SECRET_PATH_RE.test(path)) return '***';
+  if (looksLikeSecretPath(path)) return '***';
   if (Array.isArray(value)) {
     return value.map((v, i) => maskSensitiveValue(v, `${path}[${i}]`));
   }
@@ -211,13 +199,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

@@ -31,7 +31,8 @@ import { isAbsolute, relative } from 'path';
  *   cwd?: string,
  *   version?: string,
  *   limit?: number,
- *   maskSecrets?: boolean
+ *   maskSecrets?: boolean,
+ *   store?: string
  * }} ReportData
  */
 
@@ -245,6 +246,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 +265,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 +453,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 +532,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 +580,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 +641,7 @@ export function renderReportHtml(data = {}) {
   return htmlDocument([
     head,
     stats,
+    noHistoryBanner,
     findingsSection,
     `<h2>Snapshot timeline (${escapeHtml(plural(snapshots.length, 'snapshot'))})</h2>`,
     controls,
@@ -619,7 +658,8 @@ function footer(data) {
   const limit = Number.isInteger(data.limit)
     ? ` Limited to the ${escapeHtml(plural(data.limit, 'most recent snapshot'))}.`
     : '';
-  return '<footer>Generated by Flecto from <code>.flecto-snapshots/</code>.'
+  const store = escapeHtml(String(data.store ?? '.flecto-snapshots/'));
+  return `<footer>Generated by Flecto from <code>${store}</code>.`
     + ' This file is self-contained: no external scripts, fonts, or images, and nothing'
     + ` is sent anywhere when you open it.${limit}</footer>`;
 }

package/src/sarif.js

@@ -0,0 +1,144 @@
+import { relative } from 'path';
+
+/**
+ * SARIF 2.1.0 output for `flecto ci --format sarif`, for upload to GitHub code
+ * scanning (github/codeql-action/upload-sarif) and any other SARIF consumer.
+ *
+ * What Flecto emits as SARIF *results* is its policy findings — a finding has a
+ * rule id, a severity, a file, and a path, which is exactly the shape SARIF
+ * models. Raw change events are not results: they carry no rule id, so they have
+ * nothing to be a `ruleId` of. A run that gates on changes alone (`--fail-on
+ * changed`) still exits non-zero; SARIF simply reports the policy findings.
+ *
+ * Line numbers: Flecto reports a *semantic path* (`Deployment/prod/api.spec.
+ * replicas`), not a source line, and resolving one to the other means a
+ * line-tracking parser for every format. Until that exists, results are
+ * file-level: the physical location is the file with `startLine: 1`, and the
+ * semantic path is preserved losslessly as a SARIF `logicalLocation`. GitHub
+ * still renders the alert, dedupes it, and tracks when it is fixed — the
+ * file-level tradeoff the issue (#120) calls out. The logical location means the
+ * path a reviewer needs is never lost, only not yet a clickable line.
+ */
+
+const SARIF_SCHEMA = 'https://json.schemastore.org/sarif-2.1.0.json';
+const INFORMATION_URI = 'https://github.com/myselfsiddharth/Flecto';
+
+/**
+ * Map a Flecto severity to a SARIF result level.
+ * @param {string} severity
+ * @returns {'error' | 'warning' | 'note'}
+ */
+function sarifLevel(severity) {
+  if (severity === 'error') return 'error';
+  if (severity === 'info') return 'note';
+  return 'warning';
+}
+
+/**
+ * A repo-relative, POSIX-slashed URI for a file. SARIF consumers (GitHub in
+ * particular) map results onto the tree by relative URI; an absolute path does
+ * not resolve, so anything outside the working directory falls back to its base
+ * name rather than leaking an absolute path that would not map anyway.
+ * @param {string} file
+ * @param {string} cwd
+ * @returns {string}
+ */
+function artifactUri(file, cwd) {
+  const rel = relative(cwd, file);
+  if (!rel || rel.startsWith('..') || rel.includes(`..${'/'}`)) {
+    return file.split(/[\\/]/).pop() ?? file;
+  }
+  return rel.split('\\').join('/');
+}
+
+/**
+ * Build a SARIF 2.1.0 log from CI results.
+ *
+ * `results` is the same array `printCiOutput` receives: each entry is
+ * `{ file, policies }`, where `policies` is the already-mask-processed finding
+ * list. Because SARIF is built from that same masked list, `--mask-secrets`
+ * applies to the SARIF file with no extra work — which matters, since a SARIF
+ * file is uploaded to GitHub and retained.
+ * @param {Array<{ file: string, policies: import('./policy.js').PolicyFinding[] }>} results
+ * @param {{ cwd?: string, toolVersion?: string }} [options]
+ * @returns {object}
+ */
+export function buildSarif(results, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const version = options.toolVersion ?? '0.0.0';
+
+  /** @type {Map<string, { index: number, descriptor: object }>} */
+  const ruleIndex = new Map();
+  /** @type {object[]} */
+  const sarifResults = [];
+
+  for (const result of results) {
+    for (const finding of result.policies ?? []) {
+      const ruleId = String(finding.id);
+      if (!ruleIndex.has(ruleId)) {
+        ruleIndex.set(ruleId, {
+          index: ruleIndex.size,
+          descriptor: {
+            id: ruleId,
+            name: ruleId,
+            shortDescription: { text: shortDescriptionFor(finding) },
+            defaultConfiguration: { level: sarifLevel(finding.severity) },
+            ...(finding.pack ? { properties: { pack: String(finding.pack) } } : {}),
+          },
+        });
+      }
+      const path = String(finding.path ?? '');
+      const uri = artifactUri(result.file, cwd);
+      sarifResults.push({
+        ruleId,
+        ruleIndex: ruleIndex.get(ruleId).index,
+        level: sarifLevel(finding.severity),
+        message: { text: String(finding.message ?? `Policy ${ruleId} matched`) },
+        locations: [{
+          physicalLocation: {
+            artifactLocation: { uri },
+            region: { startLine: 1 },
+          },
+          ...(path
+            ? { logicalLocations: [{ fullyQualifiedName: path, kind: 'member' }] }
+            : {}),
+        }],
+        // Keeps a finding stable across runs as its line would drift, so GitHub
+        // dedupes and tracks fixes by (rule, file, semantic path) rather than by
+        // a line number Flecto does not have.
+        partialFingerprints: { flectoPathV1: `${ruleId}::${uri}::${path}` },
+      });
+    }
+  }
+
+  const rules = [...ruleIndex.values()].map((entry) => entry.descriptor);
+
+  return {
+    $schema: SARIF_SCHEMA,
+    version: '2.1.0',
+    runs: [{
+      tool: {
+        driver: {
+          name: 'Flecto',
+          informationUri: INFORMATION_URI,
+          version,
+          rules,
+        },
+      },
+      results: sarifResults,
+    }],
+  };
+}
+
+/**
+ * A stable short description for a rule descriptor. The finding's message is
+ * per-occurrence (it can interpolate values), so it is not ideal as a rule-level
+ * description, but it is the most specific text available and reads better than a
+ * generic placeholder. Trimmed to a single line.
+ * @param {import('./policy.js').PolicyFinding} finding
+ * @returns {string}
+ */
+function shortDescriptionFor(finding) {
+  const message = String(finding.message ?? '').split('\n')[0].trim();
+  return message || `Policy rule ${finding.id}`;
+}