flecto 3.0.1 → 3.1.0

package/index.js

@@ -1,10 +1,9 @@
 #!/usr/bin/env node
 
 import { program } from 'commander';
-import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync, realpathSync } from 'fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, realpathSync } from 'fs';
 import { resolve, relative, dirname, join } from 'path';
 import { fileURLToPath } from 'url';
-import { createHash } from 'crypto';
 import { execFileSync } from 'child_process';
 import chalk from 'chalk';
 
@@ -24,6 +23,7 @@ import {
   maskSensitiveValue,
 } from './src/renderer.js';
 import { deliverPrComment, renderPrComment } from './src/pr-comment.js';
+import { PR_PROVIDER_IDS } from './src/pr-providers.js';
 import {
   diffTerraformPlan,
   formatPlanSummary,
@@ -34,6 +34,25 @@ import { redactSecretString } from './src/secrets.js';
 import { fireAlerts } from './src/alerter.js';
 import { resolveWebhookFormat, WEBHOOK_FORMAT_CHOICES } from './src/notifiers.js';
 import { createEnvelope } from './src/envelope.js';
+import { buildSarif } from './src/sarif.js';
+import {
+  maskState,
+  resolveSnapshotStore,
+  SNAPSHOT_MASK_MODES,
+  SNAPSHOT_STORE_IDS,
+} from './src/snapshot-store.js';
+import {
+  loadBaseline,
+  applyBaseline,
+  buildBaselineFile,
+  writeBaselineFile,
+  baselineRelativePath,
+} from './src/baseline.js';
+import {
+  suppressionFormat,
+  parseSuppressions,
+  applySuppressions,
+} from './src/suppressions.js';
 import {
   evaluatePolicies,
   highestSeverity,
@@ -48,13 +67,14 @@ import {
   initRcFile,
   resolveProfileName,
   resolvePolicyOptions,
+  assertTargetContained,
+  assertWriteDestinationContained,
 } from './src/config.js';
 
 const PKG = JSON.parse(
   readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'package.json'), 'utf8'),
 );
 
-const SNAPSHOT_DIR = '.flecto-snapshots';
 const FAIL_ON_CHOICES = ['changed', 'added', 'removed', 'policy', 'error', 'warn'];
 
 /**
@@ -67,85 +87,42 @@ const FAIL_ON_CHOICES = ['changed', 'added', 'removed', 'policy', 'error', 'warn
 const PLAN_DEFAULT_FAIL_ON = 'error';
 const PLAN_DEFAULT_POLICIES = 'terraform';
 
-function snapshotIdForPath(absPath) {
-  const normalized = absPath.replaceAll('\\', '/');
-  return createHash('sha256').update(normalized).digest('hex').slice(0, 16);
-}
-
-function snapshotPathForFile(absPath) {
-  const id = snapshotIdForPath(absPath);
-  return resolve(`${SNAPSHOT_DIR}/${id}.json`);
-}
-
-function snapshotHistoryPathForFile(absPath) {
-  const id = snapshotIdForPath(absPath);
-  let timestamp = Date.now();
-  let path = resolve(`${SNAPSHOT_DIR}/${id}.${timestamp}.json`);
-  while (existsSync(path)) {
-    timestamp += 1;
-    path = resolve(`${SNAPSHOT_DIR}/${id}.${timestamp}.json`);
-  }
-  return path;
-}
-
 /**
- * Snapshot ids that already have at least one timestamped history entry.
+ * Put the live side of a diff in the same form the store recorded the baseline
+ * in.
  *
- * Listed once per run and threaded through the snapshot loop: probing the
- * directory per file made writing N baselines cost N listings of O(N) entries
- * each, which is quadratic in the number of tracked files.
- * @returns {Set<string>}
+ * A masked store holds `flecto:sha256:…` where a secret was. Diffing that
+ * against the plaintext on disk would report every secret in the file as changed
+ * on every single run — noise that would train a team to ignore the tool, from a
+ * store whose whole purpose is to be trusted. Masking both sides compares digest
+ * to digest, so a rotated credential still reports as changed and an untouched
+ * one reports nothing.
+ * @template T
+ * @param {T} state
+ * @param {import('./src/snapshot-store.js').SnapshotStore} store
+ * @returns {T}
  */
-function snapshotIdsWithHistory() {
-  /** @type {Set<string>} */
-  const ids = new Set();
-  if (!existsSync(SNAPSHOT_DIR)) return ids;
-  for (const name of readdirSync(SNAPSHOT_DIR)) {
-    const match = /^([a-f0-9]{16})\.\d+\.json$/.exec(name);
-    if (match) ids.add(match[1]);
-  }
-  return ids;
-}
-
-function preserveLegacySnapshotForHistory(absPath, snapshotPath, idsWithHistory) {
-  if (!existsSync(snapshotPath) || idsWithHistory.has(snapshotIdForPath(absPath))) return;
-
-  const legacy = JSON.parse(readFileSync(snapshotPath, 'utf8'));
-  writeFileSync(
-    snapshotHistoryPathForFile(absPath),
-    JSON.stringify({
-      file: legacy.file ?? absPath,
-      state: legacy.state ?? legacy,
-      ...(Array.isArray(legacy.documents) ? { documents: legacy.documents } : {}),
-      createdAt: legacy.createdAt ?? statSync(snapshotPath).mtime.toISOString(),
-    }, null, 2),
-    'utf8',
-  );
+function alignStateWithStore(state, store) {
+  return store.maskMode === 'hash' ? /** @type {T} */ (maskState(state)) : state;
 }
 
-function readLocalSnapshotHistory() {
-  if (!existsSync(SNAPSHOT_DIR)) return [];
-
-  const entries = readdirSync(SNAPSHOT_DIR, { withFileTypes: true })
-    .filter((entry) => entry.isFile() && entry.name.endsWith('.json'));
-  const historyEntries = entries.filter((entry) => /^[a-f0-9]{16}\.\d+\.json$/.test(entry.name));
-  const historyIds = new Set(historyEntries.map((entry) => entry.name.slice(0, 16)));
-  const legacyEntries = entries.filter((entry) =>
-    /^[a-f0-9]{16}\.json$/.test(entry.name) && !historyIds.has(entry.name.slice(0, 16)));
-  const snapshotEntries = [...historyEntries, ...legacyEntries];
-
-  return snapshotEntries.map((entry) => {
-    const path = resolve(SNAPSHOT_DIR, entry.name);
-    const snapshot = JSON.parse(readFileSync(path, 'utf8'));
-    const state = restoreSnapshotDocumentKeys(snapshot?.state ?? snapshot, snapshot);
-    if (typeof snapshot?.file !== 'string') {
-      throw new Error(`Invalid snapshot file: ${path}`);
-    }
-    return {
-      file: snapshot.file,
-      state,
-      createdAt: snapshot.createdAt ?? statSync(path).mtime.toISOString(),
-    };
+/**
+ * Resolve the snapshot store a command should read and write (#141).
+ *
+ * Every snapshot consumer goes through this, so `--snapshot-store shared` in
+ * `.flectorc` means the same thing to `watch`, `ci`, `history`, and `report` —
+ * a store the editor of the config and the runner gating it disagree about
+ * would be worse than having only the local one.
+ * @param {Record<string, unknown>} effective
+ * @returns {import('./src/snapshot-store.js').SnapshotStore}
+ */
+function snapshotStoreFromEffective(effective) {
+  return resolveSnapshotStore({
+    store: effective.snapshotStore,
+    dir: effective.snapshotDir,
+    mask: effective.snapshotMask,
+    retention: effective.snapshotRetention,
+    cwd: process.cwd(),
   });
 }
 
@@ -275,6 +252,18 @@ function maybeMaskFindings(findings, changes, maskSecrets) {
   });
 }
 
+/**
+ * Every command's targets pass through here, which makes it the one place the
+ * symlink-escape check has to run: a target that leaves the project through a
+ * link is refused before anything reads it.
+ * @param {string[]} files
+ * @returns {string[]} the same list
+ */
+function assertTargetsContained(files) {
+  for (const file of files) assertTargetContained(file, process.cwd());
+  return files;
+}
+
 async function resolveTargetFiles(cliFiles, rcConfig) {
   if (cliFiles && cliFiles.length > 0) {
     const direct = [];
@@ -294,15 +283,15 @@ async function resolveTargetFiles(cliFiles, rcConfig) {
         exclude: rcConfig?.exclude ?? [],
       });
     }
-    return [...new Set([...direct, ...expanded])];
+    return assertTargetsContained([...new Set([...direct, ...expanded])]);
   }
 
-  return resolveFiles({
+  return assertTargetsContained(await resolveFiles({
     cwd: process.cwd(),
     files: rcConfig?.files ?? [],
     include: rcConfig?.include ?? [],
     exclude: rcConfig?.exclude ?? [],
-  });
+  }));
 }
 
 /**
@@ -346,10 +335,28 @@ function gitRepoRelativePath(filePath) {
 /**
  * Resolve symlinks where possible, falling back to the input when the path does
  * not exist on disk.
+ *
+ * `realpathSync.native` is tried first because on Windows it asks the OS for the
+ * final path, which resolves 8.3 short names and normalizes case. Those are not
+ * cosmetic here: `git rev-parse --show-toplevel` reports the long form, while
+ * `os.tmpdir()` and many shells hand Flecto the short one
+ * (`C:\Users\RUNNER~1\...`). The JS `realpathSync` leaves both as written, so
+ * the two spellings of one directory compare as different and `relative()`
+ * produces a path that climbs out of the repository -- making
+ * `--snapshot-ref <git-ref>` fail on a file that is plainly tracked.
+ *
+ * On Linux and macOS the two agree for any path that exists, so this only ever
+ * changes the Windows result.
  * @param {string} path
  * @returns {string}
  */
 function canonicalPath(path) {
+  try {
+    return realpathSync.native(path);
+  } catch {
+    // Falls back for a path that does not exist yet, and for the rare platform
+    // where the native call is unavailable.
+  }
   try {
     return realpathSync(path);
   } catch {
@@ -357,8 +364,19 @@ function canonicalPath(path) {
   }
 }
 
-function readSnapshotStateFromRef(filePath, snapshotRef) {
-  if (!snapshotRef) return readSnapshotStateFromFile(snapshotPathForFile(filePath));
+function readSnapshotStateFromRef(filePath, snapshotRef, store) {
+  if (!snapshotRef) {
+    // Failing closed here is right — a diff with no baseline is not a clean
+    // diff — but an ENOENT on a hashed filename explains nothing. The default
+    // store is local to the working directory, so this is what an ephemeral CI
+    // runner hits on every run; the message names the store it looked in and
+    // the two ways to give it one (#141).
+    const record = store.readLatest(filePath);
+    if (!record) {
+      throw new Error(`no snapshot has been saved for this file (${store.emptyHint})`);
+    }
+    return record.state;
+  }
   const maybePath = resolve(snapshotRef);
   if (existsSync(maybePath)) {
     return readSnapshotStateFromFile(maybePath);
@@ -376,6 +394,40 @@ function shouldFailFromPolicy(findings, failOn) {
   return false;
 }
 
+/**
+ * Parse a file's inline suppressions and split its findings into active and
+ * suppressed. A directive missing its mandatory reason is a hard error: applying
+ * it would hide a finding with no justification, and skipping it silently would
+ * fail the build confusingly.
+ *
+ * A directive that resolves to nothing — an array element, or a file type with
+ * no comment syntax — is a warning instead of an error. It already fails closed,
+ * because the finding it meant to accept still fires and still gates, so failing
+ * the build a second time adds nothing; what was missing was any signal at all
+ * that the directive did not take effect.
+ * @param {string} filepath
+ * @param {import('./src/policy.js').PolicyFinding[]} findings
+ * @returns {{ active: any[], suppressed: Array<{ finding: any, reason: string }> }}
+ */
+function resolveSuppressed(filepath, findings) {
+  const format = suppressionFormat(filepath);
+
+  let raw;
+  try {
+    raw = readFileSync(filepath, 'utf8');
+  } catch {
+    return { active: findings, suppressed: [] };
+  }
+  const { suppressions, errors, warnings } = parseSuppressions(raw, format);
+  const rel = relative(process.cwd(), filepath) || filepath;
+  if (errors.length > 0) {
+    const detail = errors.map((e) => `  ${rel}:${e.line}: ${e.message}`).join('\n');
+    throw new Error(`Inline suppression is missing a required reason:\n${detail}`);
+  }
+  for (const warning of warnings) renderNote(`${rel}:${warning.line}: ${warning.message}`);
+  return applySuppressions(findings, suppressions);
+}
+
 function shouldFailFromChanges(events, failOn) {
   if (events.length === 0) return false;
   if (failOn.has('changed') && events.some((e) => e.type === 'changed')) return true;
@@ -397,32 +449,143 @@ function escapeWorkflowCommandProperty(value) {
     .replaceAll(',', '%2C');
 }
 
-function printCiOutput(results, format) {
+/**
+ * Write to stdout and resolve only once the bytes have actually left.
+ *
+ * `process.exit()` does not flush a pending stdout write, and Node writes to a
+ * pipe asynchronously. So `flecto ci --format json | jq`, or any CI harness
+ * capturing stdout, silently lost everything past the 64 KB pipe buffer -- and
+ * still saw exit 0. A truncated envelope stream that reports success is the
+ * worst shape a machine consumer can be handed: it does not look like a
+ * failure, it looks like a clean run over fewer files.
+ *
+ * Redirecting to a file hid this, because Node writes to a file descriptor
+ * synchronously. It only appeared through a pipe, which is how every consumer
+ * that matters reads it.
+ *
+ * The callback form fires when that specific chunk drains, and stream writes
+ * are ordered, so awaiting the last one means every earlier one is out too.
+ *
+ * The trailing newline is appended unconditionally, which is exactly what
+ * `console.log` did. Adding it only when one is missing would silently drop a
+ * byte from any payload that already ends in a newline -- `--format pr-comment`
+ * does -- and the point of this change is that the rendered output is identical.
+ * @param {string} text
+ * @returns {Promise<void>}
+ */
+function writeStdout(text) {
+  return new Promise((resolveWrite) => {
+    process.stdout.write(`${text}\n`, () => resolveWrite());
+  });
+}
+
+/**
+ * Collapse the envelopes for files that were scanned and had nothing to report
+ * into a single manifest entry.
+ *
+ * `ci` emits one envelope per *scanned* file rather than per *changed* file, so
+ * the output grows with the size of the repository instead of the size of the
+ * change -- measured on 250 service configs with one file edited, 113.4 KB of
+ * output for 0.2 KB of semantic content. For a human that is invisible, because
+ * the renderer already prints only what changed; it is the machine consumers
+ * (webhooks, NDJSON sinks, and any agent handed the JSON) that pay for it.
+ *
+ * Dropping those files outright is not safe. An envelope for a scanned but
+ * unchanged file is *evidence Flecto looked*, and a consumer diffing two runs
+ * can tell "checked and clean" from "not checked at all" -- silently removing
+ * that distinction would weaken a gate someone relies on, in the same way a
+ * silently skipped plugin would. So the evidence is kept, in the one place it
+ * costs almost nothing: a single `lifecycle` envelope carrying the list of
+ * paths, instead of a full envelope with its own pair of UUIDs, timestamp, and
+ * absolute path for every file.
+ *
+ * The path list rides on the result wrapper rather than the envelope, which is
+ * closed by schemas/flecto-envelope-2.0.json -- the same arrangement `baseline`
+ * already uses. Nothing about schema 2.0 changes, and the default output is
+ * untouched, so this is opt-in rather than a reshaping of a documented contract.
+ *
+ * Each envelope keeps its own `batch_id`: that field is documented as grouping
+ * the events from one file change, not one run.
+ * @param {any[]} results
+ * @returns {any[]}
+ */
+function collapseUnchangedResults(results) {
+  const reported = [];
+  /** @type {string[]} */
+  const scanned = [];
+
+  for (const result of results) {
+    const hasChanges = (result.envelope.changes?.length ?? 0) > 0;
+    const hasFindings = (result.envelope.policies?.length ?? 0) > 0;
+    if (hasChanges || hasFindings) reported.push(result);
+    else scanned.push(result.file);
+  }
+
+  if (scanned.length === 0) return reported;
+  return [
+    ...reported,
+    {
+      // No `file`: this entry is not about one file. Consumers discriminate on
+      // `envelope.event_type === "lifecycle"`, which schema 2.0 already carries.
+      scanned,
+      envelope: createEnvelope({
+        source: 'ci',
+        file: '',
+        lifecycle: {
+          type: 'scanned',
+          message:
+            `${scanned.length} file${scanned.length === 1 ? '' : 's'} scanned `
+            + 'with no changes and no policy findings',
+        },
+      }),
+      policies: [],
+    },
+  ];
+}
+
+/**
+ * Render the machine-readable CI output and wait for it to flush.
+ *
+ * The payload is assembled and written once rather than line by line, so a
+ * caller has a single write to await -- see {@link writeStdout} for why that
+ * matters. The rendered bytes are unchanged.
+ * @param {any[]} results
+ * @param {string} format
+ * @returns {Promise<void>}
+ */
+async function printCiOutput(results, format) {
   if (format === 'json') {
-    console.log(JSON.stringify(results, null, 2));
+    await writeStdout(JSON.stringify(results, null, 2));
     return;
   }
   if (format === 'ndjson') {
-    for (const result of results) {
-      console.log(JSON.stringify(result));
-    }
+    if (results.length === 0) return;
+    await writeStdout(results.map((result) => JSON.stringify(result)).join('\n'));
+    return;
+  }
+  if (format === 'sarif') {
+    const sarif = buildSarif(results, { cwd: process.cwd(), toolVersion: PKG.version });
+    await writeStdout(JSON.stringify(sarif, null, 2));
     return;
   }
   if (format === 'github-annotations') {
+    const lines = [];
     for (const result of results) {
       for (const event of result.envelope.changes) {
         const title = `flecto ${event.type}`;
         const detail = event.note ? `${event.path} (${event.note})` : event.path;
-        console.log(`::warning file=${escapeWorkflowCommandProperty(result.file)},title=${escapeWorkflowCommandProperty(title)}::${escapeWorkflowCommandData(detail)}`);
+        lines.push(`::warning file=${escapeWorkflowCommandProperty(result.file)},title=${escapeWorkflowCommandProperty(title)}::${escapeWorkflowCommandData(detail)}`);
       }
       for (const finding of result.policies) {
         const level = finding.severity === 'error' ? 'error' : 'warning';
         const pack = finding.pack ? ` [${finding.pack}]` : '';
         const title = `flecto policy ${finding.id}${pack}`;
         const detail = `${finding.path}: ${finding.message}`;
-        console.log(`::${level} file=${escapeWorkflowCommandProperty(result.file)},title=${escapeWorkflowCommandProperty(title)}::${escapeWorkflowCommandData(detail)}`);
+        lines.push(`::${level} file=${escapeWorkflowCommandProperty(result.file)},title=${escapeWorkflowCommandProperty(title)}::${escapeWorkflowCommandData(detail)}`);
       }
     }
+    if (lines.length === 0) return;
+    await writeStdout(lines.join('\n'));
   }
 }
 
@@ -431,11 +594,12 @@ function printCiOutput(results, format) {
  * delivery problem warns, and the exit code stays with the diff/policy result.
  * @param {string} body
  * @param {boolean} enabled
+ * @param {string} [provider] force a delivery adapter instead of detecting one
  */
-async function deliverPrCommentSafely(body, enabled) {
+async function deliverPrCommentSafely(body, enabled, provider) {
   if (!enabled) return;
   try {
-    const result = await deliverPrComment(body, { enabled: true });
+    const result = await deliverPrComment(body, { enabled: true, provider });
     if (result.posted) {
       renderNote(`PR comment ${result.action}${result.url ? `: ${result.url}` : ''}`);
       return;
@@ -479,6 +643,10 @@ program
   .option('--mask-secrets-webhooks', 'Also mask secrets in webhook payloads', false)
   .option('--snapshot', 'Save current state as baseline instead of watching')
   .option('--diff', 'Diff current file against saved baseline and exit')
+  .option('--snapshot-store <id>', `Snapshot store: ${SNAPSHOT_STORE_IDS.join(' | ')} (shared is repo-relative and meant to be committed)`)
+  .option('--snapshot-dir <path>', 'Directory holding the snapshot store (default: .flecto-snapshots local, .flecto/snapshots shared)')
+  .option('--snapshot-mask <mode>', `How the store records secret-like values: ${SNAPSHOT_MASK_MODES.join(' | ')} (default: hash for shared, none for local)`)
+  .option('--snapshot-retention <n>', 'Snapshots kept per file, 0 keeps every one (default: 20 for shared, unlimited for local)')
   .option('--allow-empty', 'Allow --snapshot to succeed when nothing was written', false)
   .action(async (files, opts, command) => {
     try {
@@ -502,11 +670,18 @@ program
       const maskSecretsWebhooks = Boolean(effective.maskSecretsWebhooks);
       const webhookFormat = resolveWebhookFormat(effective.webhookFormat, effective.webhook);
       const dOpts = diffOptionsFromEffective(effective, ignorePaths);
+      const snapshotStore = snapshotStoreFromEffective(effective);
 
       if (effective.snapshot) {
-        mkdirSync(SNAPSHOT_DIR, { recursive: true });
-        const idsWithHistory = snapshotIdsWithHistory();
+        mkdirSync(snapshotStore.root, { recursive: true });
+        // Snapshots carry config values, so a store directory that is itself a
+        // link out of the project would write them somewhere the repository does
+        // not control. Same rule as a target, checked after mkdir so an existing
+        // link is seen rather than a path that does not exist yet.
+        assertTargetContained(snapshotStore.root, process.cwd());
         let written = 0;
+        let pruned = 0;
+        const warnings = new Set();
         for (const filepath of targets) {
           if (!existsSync(filepath)) {
             renderWarn(`Skipping missing file: ${filepath}`);
@@ -517,25 +692,32 @@ program
             continue;
           }
           const state = parseFile(filepath);
-          const snapshotPath = snapshotPathForFile(filepath);
-          preserveLegacySnapshotForHistory(filepath, snapshotPath, idsWithHistory);
           // Only a multi-document file records `documents`, so an ordinary
           // snapshot is byte-for-byte what it was before this field existed.
-          const documents = documentKeysOf(state) ?? [];
-          const snapshot = {
-            file: filepath,
+          const result = snapshotStore.write(filepath, {
             state,
-            ...(documents.length > 0 ? { documents: [...documents] } : {}),
-            createdAt: new Date().toISOString(),
-          };
-          writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2), 'utf8');
-          writeFileSync(snapshotHistoryPathForFile(filepath), JSON.stringify(snapshot, null, 2), 'utf8');
-          // Keep the set in step with what this run has written, so a repeated
-          // target behaves exactly as it did when the check hit the disk.
-          idsWithHistory.add(snapshotIdForPath(filepath));
-          console.log(chalk.green(`✓ Snapshot saved: ${snapshotPath}`));
+            documents: documentKeysOf(state) ?? [],
+          });
+          if (result.warning) warnings.add(result.warning);
+          pruned += result.pruned;
+          console.log(chalk.green(`✓ Snapshot saved: ${result.path}`));
           written += 1;
         }
+        for (const warning of warnings) renderWarn(warning);
+        if (pruned > 0) {
+          renderNote(
+            `Pruned ${pruned} snapshot${pruned === 1 ? '' : 's'} beyond the`
+            + ` ${snapshotStore.retention}-entry retention of the ${snapshotStore.id} store.`,
+          );
+        }
+        if (written > 0 && snapshotStore.id === 'shared') {
+          renderNote(
+            `Shared store: commit ${snapshotStore.label} so every runner reads the same history.`
+            + (snapshotStore.maskMode === 'none'
+              ? ' Masking is off, so these files carry config values verbatim into git history.'
+              : ' Secret-like values are stored as digests, not plaintext.'),
+          );
+        }
         if (written === 0 && !effective.allowEmpty) {
           throw new Error(
             'No snapshots written — all targets were missing or unsupported.' +
@@ -547,18 +729,37 @@ program
 
       if (effective.diff) {
         let hasChanges = false;
+        let compared = 0;
+        let missing = 0;
         for (const filepath of targets) {
-          const snapshotPath = snapshotPathForFile(filepath);
-          if (!existsSync(snapshotPath)) {
-            renderWarn(`No snapshot found for "${filepath}"`);
+          const record = snapshotStore.readLatest(filepath);
+          if (!record) {
+            renderWarn(`No snapshot found for "${filepath}" in ${snapshotStore.label}`);
+            missing += 1;
             continue;
           }
-          const before = readSnapshotStateFromFile(snapshotPath);
-          const after = parseFile(filepath);
+          const before = record.state;
+          const after = alignStateWithStore(parseFile(filepath), snapshotStore);
           const events = diffTrees(before, after, dOpts);
           renderDiff(filepath, events, { maskSecrets });
+          compared += 1;
           if (events.length > 0) hasChanges = true;
         }
+        // Exiting 0 having compared nothing is the worst answer available: the
+        // caller reads it as "no drift" when the truth is "no baseline to drift
+        // from" (#141). Snapshot history lives in the working directory, so this
+        // is the normal state of a fresh CI runner.
+        if (compared === 0) {
+          throw new Error(
+            `No snapshot found for any target in ${snapshotStore.label}, so nothing was compared.`
+              + ' Run "flecto watch <file> --snapshot" first — no history is not no drift.',
+          );
+        }
+        if (missing > 0) {
+          renderNote(
+            `${missing} of ${targets.length} targets had no snapshot and were not compared.`,
+          );
+        }
         process.exit(hasChanges ? 1 : 0);
       }
 
@@ -668,8 +869,10 @@ program
 
 program
   .command('history [files...]')
-  .description('Summarize drift across local snapshots')
+  .description('Summarize drift across saved snapshots')
   .option('-l, --limit <n>', 'Number of recent snapshots to show', '10')
+  .option('--snapshot-store <id>', `Snapshot store to read: ${SNAPSHOT_STORE_IDS.join(' | ')}`)
+  .option('--snapshot-dir <path>', 'Directory holding the snapshot store (default: .flecto-snapshots local, .flecto/snapshots shared)')
   .option('-p, --profile <name>', 'Use profile from .flectorc (else FLECTO_PROFILE)')
   .option('--ignore <keys>', 'Comma-separated key paths to ignore (e.g. "updated_at,meta.ts")')
   .option('--array-id-key <key>', 'Diff arrays by this object identity key (opt-in)')
@@ -688,7 +891,8 @@ program
       const ignorePaths = parseCsv(effective.ignore);
       const dOpts = diffOptionsFromEffective(effective, ignorePaths);
 
-      const allSnapshots = readLocalSnapshotHistory();
+      const snapshotStore = snapshotStoreFromEffective(effective);
+      const allSnapshots = snapshotStore.readHistory();
       let snapshots = allSnapshots;
       if (files.length > 0) {
         const targets = new Set((await resolveTargetFiles(files, config)).map((file) => resolve(file)));
@@ -699,18 +903,42 @@ program
       if (summaries.length === 0) {
         if (files.length > 0 && allSnapshots.length > 0) {
           throw new Error(
-            'No local snapshots matched the given files. Omit files to view all saved snapshot history.',
+            `No snapshots in ${snapshotStore.label} matched the given files.`
+            + ' Omit files to view all saved snapshot history.',
           );
         }
-        throw new Error('No local snapshots found. Run "flecto watch <file> --snapshot" first.');
+        throw new Error(
+          `No snapshots found in ${snapshotStore.label}.`
+          + ` Run "flecto watch <file> --snapshot${snapshotStore.id === 'shared' ? ' --snapshot-store shared' : ''}" first`
+          + ' — no history is not no drift.',
+        );
       }
 
-      console.log(`Local snapshot history (${summaries.length} snapshots)`);
+      console.log(
+        `Snapshot history from ${snapshotStore.label} (${summaries.length} snapshots, ${snapshotStore.id} store)`,
+      );
+      let baselines = 0;
       for (const snapshot of summaries) {
         const file = relative(process.cwd(), snapshot.file) || snapshot.file;
-        const changes = `${snapshot.changeCount} change${snapshot.changeCount === 1 ? '' : 's'}`;
+        // A snapshot with nothing before it was never compared, so printing
+        // "0 changes" for it states a result that was never computed (#141).
+        if (!snapshot.previousCreatedAt) baselines += 1;
+        const changes = snapshot.previousCreatedAt
+          ? `${snapshot.changeCount} change${snapshot.changeCount === 1 ? '' : 's'}`
+          : 'baseline (no earlier snapshot to compare against)';
         console.log(`${snapshot.createdAt}  ${file} — ${changes}`);
       }
+      if (baselines === summaries.length) {
+        renderNote(
+          'Nothing was compared: every snapshot shown is the first of its file.'
+            + ' That is no history, not no drift.',
+        );
+      } else if (baselines > 0) {
+        renderNote(
+          `${baselines} of ${summaries.length} snapshots shown are the first of their file`
+            + ' and were not compared against anything.',
+        );
+      }
     } catch (err) {
       renderError(err.message);
       process.exit(1);
@@ -719,8 +947,10 @@ program
 
 program
   .command('report [files...]')
-  .description('Render local snapshot history as a self-contained HTML report')
+  .description('Render saved snapshot history as a self-contained HTML report')
   .option('-o, --output <path>', 'Write the report to this path', 'flecto-report.html')
+  .option('--snapshot-store <id>', `Snapshot store to read: ${SNAPSHOT_STORE_IDS.join(' | ')}`)
+  .option('--snapshot-dir <path>', 'Directory holding the snapshot store (default: .flecto-snapshots local, .flecto/snapshots shared)')
   .option('-l, --limit <n>', 'Number of recent snapshots to include', '10')
   .option('-p, --profile <name>', 'Use profile from .flectorc (else FLECTO_PROFILE)')
   .option('--ignore <keys>', 'Comma-separated key paths to ignore (e.g. "updated_at,meta.ts")')
@@ -746,10 +976,15 @@ program
       const dOpts = diffOptionsFromEffective(effective, ignorePaths);
       const maskSecrets = Boolean(effective.maskSecrets);
       const outputPath = resolve(String(effective.output ?? 'flecto-report.html'));
+      assertWriteDestinationContained(outputPath, {
+        option: '--output',
+        fromCli: cliOverrides.output !== undefined,
+      });
 
       // Same snapshot source, filtering, and errors as `flecto history` — this
       // command only changes how that history is rendered.
-      const allSnapshots = readLocalSnapshotHistory();
+      const snapshotStore = snapshotStoreFromEffective(effective);
+      const allSnapshots = snapshotStore.readHistory();
       let snapshots = allSnapshots;
       if (files.length > 0) {
         const targets = new Set((await resolveTargetFiles(files, config)).map((file) => resolve(file)));
@@ -760,10 +995,15 @@ program
       if (summaries.length === 0) {
         if (files.length > 0 && allSnapshots.length > 0) {
           throw new Error(
-            'No local snapshots matched the given files. Omit files to report on all saved snapshot history.',
+            `No snapshots in ${snapshotStore.label} matched the given files.`
+            + ' Omit files to report on all saved snapshot history.',
           );
         }
-        throw new Error('No local snapshots found. Run "flecto watch <file> --snapshot" first.');
+        throw new Error(
+          `No snapshots found in ${snapshotStore.label}.`
+          + ` Run "flecto watch <file> --snapshot${snapshotStore.id === 'shared' ? ' --snapshot-store shared' : ''}" first`
+          + ' — no history is not no drift.',
+        );
       }
 
       const reportSnapshots = [];
@@ -797,6 +1037,7 @@ program
         version: PKG.version,
         limit,
         maskSecrets,
+        store: snapshotStore.label,
       });
       mkdirSync(dirname(outputPath), { recursive: true });
       writeFileSync(outputPath, html, 'utf8');
@@ -814,9 +1055,14 @@ program
   .description('Run semantic diff in CI mode')
   .option('-p, --profile <name>', 'Use profile from .flectorc (else FLECTO_PROFILE)')
   .option('--snapshot-ref <ref>', 'Snapshot reference: snapshot path or git ref')
-  .option('--format <type>', 'Output format: json | ndjson | github-annotations | pr-comment', 'json')
-  .option('--pr-comment-post', 'With --format pr-comment, upsert the comment on the PR (needs GITHUB_TOKEN + PR context)', false)
+  .option('--snapshot-store <id>', `Snapshot store to read: ${SNAPSHOT_STORE_IDS.join(' | ')}`)
+  .option('--snapshot-dir <path>', 'Directory holding the snapshot store (default: .flecto-snapshots local, .flecto/snapshots shared)')
+  .option('--format <type>', 'Output format: json | ndjson | sarif | github-annotations | pr-comment', 'json')
+  .option('--pr-comment-post', 'With --format pr-comment, upsert the comment on the PR (needs a token + merge request context)', false)
+  .option('--pr-provider <name>', `Force the comment delivery target: ${PR_PROVIDER_IDS.join(' | ')} (default: detect from CI)`)
   .option('--fail-on <rules>', 'Comma-separated fail rules: changed,added,removed,policy,error,warn', 'changed,policy,error')
+  .option('--baseline <file>', 'Gate only on findings not already recorded in this baseline file')
+  .option('--update-baseline', 'Rewrite the --baseline file from the current findings (explicit, never automatic)', false)
   .option('--ignore <keys>', 'Comma-separated key paths to ignore')
   .option('--policies <ids>', 'Comma-separated policy pack ids')
   .option('--plugins <paths>', 'Comma-separated local ESM plugin paths')
@@ -824,6 +1070,8 @@ program
   .option('--no-array-id', 'Diff arrays by index instead of object identity')
   .option('--array-ignore-order', 'Treat array order as insignificant', false)
   .option('--mask-secrets', 'Mask secret-like values in CI output', false)
+  .option('--show-suppressed', 'List inline-suppressed findings instead of only counting them', false)
+  .option('--changed-only', 'With --format json|ndjson, replace envelopes for unchanged files with one scanned manifest', false)
   .option('--allow-empty', 'Allow CI to succeed when no files were diffed', false)
   .action(async (files, opts, command) => {
     try {
@@ -840,19 +1088,61 @@ program
       const ignorePaths = parseCsv(effective.ignore);
       const failOn = parseFailOn(effective.failOn ?? 'changed,policy,error');
       const format = String(effective.format ?? 'json');
-      if (!['json', 'ndjson', 'github-annotations', 'pr-comment'].includes(format)) {
-        throw new Error('--format must be json, ndjson, github-annotations, or pr-comment');
+      if (!['json', 'ndjson', 'sarif', 'github-annotations', 'pr-comment'].includes(format)) {
+        throw new Error('--format must be json, ndjson, sarif, github-annotations, or pr-comment');
       }
       const prCommentPost = Boolean(effective.prCommentPost);
+      if (effective.prProvider && !PR_PROVIDER_IDS.includes(String(effective.prProvider))) {
+        throw new Error(`--pr-provider must be one of: ${PR_PROVIDER_IDS.join(', ')}`);
+      }
       if (prCommentPost && format !== 'pr-comment') {
         renderWarn('Ignoring --pr-comment-post: it only applies to --format pr-comment.');
       }
       const maskSecrets = Boolean(effective.maskSecrets);
+      const showSuppressed = Boolean(effective.showSuppressed);
+      const changedOnly = Boolean(effective.changedOnly);
+      // github-annotations and pr-comment already render only what changed, so
+      // there is nothing for the flag to collapse there. Say so rather than
+      // accepting it and quietly doing nothing.
+      if (changedOnly && format !== 'json' && format !== 'ndjson') {
+        renderWarn(`Ignoring --changed-only: it only applies to --format json or ndjson (got ${format}).`);
+      }
       const dOpts = diffOptionsFromEffective(effective, ignorePaths);
 
-      /** @type {any[]} */
-      const results = [];
-      let shouldFail = false;
+      const snapshotStore = snapshotStoreFromEffective(effective);
+
+      const cwd = process.cwd();
+      const baselinePath = effective.baseline ? resolve(cwd, String(effective.baseline)) : null;
+      if (baselinePath) {
+        assertWriteDestinationContained(baselinePath, {
+          option: '--baseline',
+          fromCli: cliOverrides.baseline !== undefined,
+          cwd,
+        });
+      }
+      // `--update-baseline` accepts every finding this run produced, so honoring
+      // it from `.flectorc` would let a pull request turn its own failing gate
+      // green — including one whose `--fail-on` was set explicitly on the command
+      // line. It is an action, not a setting: the CLI is the only place it can
+      // come from, and a declaration in the rc file is refused rather than
+      // ignored, so a repository that meant it finds out.
+      if (effective.updateBaseline && cliOverrides.updateBaseline === undefined) {
+        throw new Error(
+          'updateBaseline is declared in .flectorc, and it is refused there: it accepts every'
+          + ' current finding, which would turn a failing gate green from a file a pull request'
+          + ' can edit. Pass --update-baseline on the command line when you mean to record a'
+          + ' baseline.',
+        );
+      }
+      const updateBaseline = Boolean(effective.updateBaseline);
+      if (updateBaseline && !baselinePath) {
+        throw new Error('--update-baseline requires --baseline <file> naming the file to write.');
+      }
+
+      /** @type {Array<{ filepath: string, relFile: string, outboundChanges: any[], outboundFindings: any[], changesFail: boolean }>} */
+      const perFile = [];
+      /** @type {Array<{ file: string, finding: any, reason: string }>} */
+      const allSuppressed = [];
       let diffed = 0;
 
       for (const filepath of targets) {
@@ -864,10 +1154,14 @@ program
           renderWarn(`Skipping unsupported file: ${filepath}`);
           continue;
         }
-        const after = parseFile(filepath);
+        // A `--snapshot-ref` baseline is read straight from git, so it is never
+        // masked; only a store-provided baseline needs the live side aligned.
+        const after = effective.snapshotRef
+          ? parseFile(filepath)
+          : alignStateWithStore(parseFile(filepath), snapshotStore);
         let before;
         try {
-          before = readSnapshotStateFromRef(filepath, effective.snapshotRef);
+          before = readSnapshotStateFromRef(filepath, effective.snapshotRef, snapshotStore);
         } catch (err) {
           throw new Error(
             `Failed to resolve snapshot baseline for "${filepath}"` +
@@ -875,8 +1169,8 @@ program
           );
         }
         const events = diffTrees(before, after, dOpts);
-        const policyFindings = await evaluatePolicies(events, {
-          cwd: process.cwd(),
+        const rawFindings = await evaluatePolicies(events, {
+          cwd,
           file: filepath,
           profile: profile ?? null,
           source: 'ci',
@@ -884,20 +1178,24 @@ program
           plugins,
           severityRemap,
         });
-        const outboundChanges = maybeMaskChanges(events, maskSecrets);
-        const outboundFindings = maybeMaskFindings(policyFindings, events, maskSecrets);
-        const envelope = createEnvelope({
-          source: 'ci',
-          file: filepath,
-          changes: outboundChanges,
-          policies: outboundFindings,
-        });
-        results.push({ file: filepath, envelope, policies: outboundFindings });
-        diffed += 1;
 
-        if (shouldFailFromChanges(events, failOn) || shouldFailFromPolicy(policyFindings, failOn)) {
-          shouldFail = true;
+        // Inline suppressions run first: a deliberately-accepted finding is
+        // removed before the baseline, the gate, and the output ever see it, so
+        // it is never also counted by a baseline. A directive missing its
+        // mandatory reason is refused loudly rather than applied.
+        const { active: policyFindings, suppressed } = resolveSuppressed(filepath, rawFindings);
+        for (const item of suppressed) {
+          allSuppressed.push({ file: filepath, finding: item.finding, reason: item.reason });
         }
+
+        perFile.push({
+          filepath,
+          relFile: baselineRelativePath(filepath, cwd),
+          outboundChanges: maybeMaskChanges(events, maskSecrets),
+          outboundFindings: maybeMaskFindings(policyFindings, events, maskSecrets),
+          changesFail: shouldFailFromChanges(events, failOn),
+        });
+        diffed += 1;
       }
 
       if (diffed === 0 && !effective.allowEmpty) {
@@ -907,12 +1205,100 @@ program
         );
       }
 
+      // Suppressed findings are still surfaced — a count by default, the full
+      // list with --show-suppressed — so a gate you cannot see the shape of does
+      // not quietly grow. All of this goes to stderr, leaving machine output clean.
+      if (allSuppressed.length > 0) {
+        renderNote(
+          `${allSuppressed.length} finding${allSuppressed.length === 1 ? '' : 's'} suppressed inline`
+          + `${showSuppressed ? ':' : ' (use --show-suppressed to list them).'}`,
+        );
+        if (showSuppressed) {
+          for (const { file, finding, reason } of allSuppressed) {
+            const rel = relative(cwd, file) || file;
+            renderNote(`  ${rel} ${finding.path}: ${finding.id} — ${reason}`);
+          }
+        }
+      }
+
+      // Every finding this run produced, paired with its repo-relative file, so
+      // the baseline can be matched, updated, and stale-checked on stable keys.
+      const located = perFile.flatMap((f) =>
+        f.outboundFindings.map((finding) => ({ file: f.relFile, finding })));
+
+      // Without a baseline, every finding is active — behavior is unchanged.
+      let activeByFile = new Map(perFile.map((f) => [f.relFile, f.outboundFindings]));
+      let baselineSummary = null;
+      if (baselinePath) {
+        const { entries: recorded } = loadBaseline(baselinePath);
+
+        if (updateBaseline) {
+          // Recording the current state accepts all of it: the file is rewritten
+          // from every finding, and nothing is "new" relative to what was just
+          // written, so the gate passes on the policy axis.
+          writeBaselineFile(baselinePath, buildBaselineFile(located, recorded));
+          renderNote(
+            `Baseline updated: ${baselineRelativePath(baselinePath, cwd)} `
+            + `(${located.length} finding${located.length === 1 ? '' : 's'} recorded)`,
+          );
+          activeByFile = new Map();
+          baselineSummary = { active: 0, accepted: located.length, stale: [] };
+        } else {
+          const { active, accepted, stale } = applyBaseline(located, recorded);
+          const activeMap = new Map();
+          for (const { file, finding } of active) {
+            if (!activeMap.has(file)) activeMap.set(file, []);
+            activeMap.get(file).push(finding);
+          }
+          activeByFile = activeMap;
+          baselineSummary = { active: active.length, accepted: accepted.length, stale };
+        }
+      }
+
+      // Results reflect the *active* findings: with a baseline in effect, an
+      // accepted finding is suppressed from output as well as from the gate, so a
+      // green run is not buried under hundreds of already-accepted findings.
+      const results = perFile.map((f) => {
+        const active = activeByFile.get(f.relFile) ?? [];
+        return {
+          file: f.filepath,
+          envelope: createEnvelope({
+            source: 'ci',
+            file: f.filepath,
+            changes: f.outboundChanges,
+            policies: active,
+          }),
+          policies: active,
+        };
+      });
+
+      // With --update-baseline everything is now accepted, so there are no active
+      // findings to gate on; the policy gate simply passes. Change-based triggers
+      // are about the diff, not the findings, so they still apply.
+      const activeFindings = results.flatMap((r) => r.policies);
+      const shouldFail = perFile.some((f) => f.changesFail)
+        || shouldFailFromPolicy(activeFindings, failOn);
+
+      if (baselineSummary) {
+        const parts = [`${baselineSummary.active} new`, `${baselineSummary.accepted} baselined`];
+        if (baselineSummary.stale.length > 0) parts.push(`${baselineSummary.stale.length} stale`);
+        renderNote(`Baseline: ${parts.join(', ')}.`);
+        if (baselineSummary.stale.length > 0 && !updateBaseline) {
+          renderWarn(
+            `${baselineSummary.stale.length} baseline `
+            + `${baselineSummary.stale.length === 1 ? 'entry no longer occurs' : 'entries no longer occur'}; `
+            + 're-run with --update-baseline to prune.',
+          );
+        }
+      }
+
       if (format === 'pr-comment') {
-        const body = renderPrComment(results, { cwd: process.cwd(), failed: shouldFail });
-        console.log(body);
-        await deliverPrCommentSafely(body, prCommentPost);
+        const body = renderPrComment(results, { cwd, failed: shouldFail });
+        await writeStdout(body);
+        await deliverPrCommentSafely(body, prCommentPost, effective.prProvider);
       } else {
-        printCiOutput(results, format);
+        const collapsible = changedOnly && (format === 'json' || format === 'ndjson');
+        await printCiOutput(collapsible ? collapseUnchangedResults(results) : results, format);
       }
       process.exit(shouldFail ? 1 : 0);
     } catch (err) {
@@ -926,7 +1312,8 @@ program
   .description('Diff Terraform plan JSON (terraform show -json) and run policies on it')
   .option('-p, --profile <name>', 'Use profile from .flectorc (else FLECTO_PROFILE)')
   .option('--format <type>', 'Output format: human | json | ndjson | github-annotations | pr-comment', 'human')
-  .option('--pr-comment-post', 'With --format pr-comment, upsert the comment on the PR (needs GITHUB_TOKEN + PR context)', false)
+  .option('--pr-comment-post', 'With --format pr-comment, upsert the comment on the PR (needs a token + merge request context)', false)
+  .option('--pr-provider <name>', `Force the comment delivery target: ${PR_PROVIDER_IDS.join(' | ')} (default: detect from CI)`)
   .option('--fail-on <rules>', 'Comma-separated fail rules: changed,added,removed,policy,error,warn', PLAN_DEFAULT_FAIL_ON)
   .option('--ignore <keys>', 'Comma-separated key paths to ignore, e.g. "**.tags_all,**.#action"')
   .option('--policies <ids>', `Comma-separated policy pack ids (default: ${PLAN_DEFAULT_POLICIES})`)
@@ -955,6 +1342,9 @@ program
         throw new Error('--format must be human, json, ndjson, github-annotations, or pr-comment');
       }
       const prCommentPost = Boolean(effective.prCommentPost);
+      if (effective.prProvider && !PR_PROVIDER_IDS.includes(String(effective.prProvider))) {
+        throw new Error(`--pr-provider must be one of: ${PR_PROVIDER_IDS.join(', ')}`);
+      }
       if (prCommentPost && format !== 'pr-comment') {
         renderWarn('Ignoring --pr-comment-post: it only applies to --format pr-comment.');
       }
@@ -1013,10 +1403,10 @@ program
 
       if (format === 'pr-comment') {
         const body = renderPrComment(results, { cwd: process.cwd(), failed: shouldFail });
-        console.log(body);
-        await deliverPrCommentSafely(body, prCommentPost);
+        await writeStdout(body);
+        await deliverPrCommentSafely(body, prCommentPost, effective.prProvider);
       } else if (format !== 'human') {
-        printCiOutput(results, format);
+        await printCiOutput(results, format);
       }
       process.exit(shouldFail ? 1 : 0);
     } catch (err) {
@@ -1099,7 +1489,7 @@ program
         // Same envelope and printer as `ci`, so machine consumers see one shape.
         // `baseline` rides on the result wrapper rather than the envelope, which
         // is closed by schemas/flecto-envelope-2.0.json.
-        printCiOutput(
+        await printCiOutput(
           [{ file: targetPath, baseline: baselinePath, envelope, policies: outboundFindings }],
           format,
         );