flecto 3.0.0 → 3.0.2

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}`;
+}

package/src/secrets.js

@@ -57,15 +57,22 @@ const KNOWN_FORMATS = [
   { kind: 'stripe-secret-key', re: /\b[sr]k_live_[0-9A-Za-z]{16,}\b/g },
   // JWT: base64url header starting with "eyJ" ('{"'), payload, signature.
   { kind: 'jwt', re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g },
-  // PEM private key blocks, including PGP blocks and unterminated fragments.
-  {
-    kind: 'private-key-block',
-    re: /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----[\s\S]*?(?:-----END (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----|$)/g,
-  },
 ];
 
-/** Credentials embedded in a URL authority: scheme://user:PASSWORD@host. */
-const URL_CREDENTIALS_RE = /[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+:([^\s/@]+)@/gi;
+// PEM/PGP private-key block markers, matched linearly. A single regex spanning
+// BEGIN…END with `[\s\S]*?…$` backtracks quadratically on a long BEGIN-prefixed
+// value with no END — a denial-of-service vector, since secret detection runs
+// on every changed string value. Instead we find the markers with anchored,
+// non-spanning regexes and pair them by position (see findPrivateKeyBlocks).
+const PRIVATE_KEY_BEGIN_RE = /-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----/g;
+const PRIVATE_KEY_END_RE = /-----END (?:[A-Z0-9]+ )*PRIVATE KEY(?: BLOCK)?-----/g;
+
+// Credentials embedded in a URL authority: scheme://user:PASSWORD@host. The
+// scheme run is length-bounded ({0,32}); an unbounded `*` before the required
+// `://` backtracks quadratically on a long value that never contains `://`. No
+// real URL scheme approaches 32 characters, so the bound changes nothing that
+// matters and removes the ReDoS.
+const URL_CREDENTIALS_RE = /[a-z][a-z0-9+.-]{0,32}:\/\/[^\s/:@]+:([^\s/@]+)@/gi;
 
 /**
  * Values that only *reference* a secret. Redacting these adds noise and, worse,
@@ -205,6 +212,31 @@ function isHighEntropySecret(value) {
   return true;
 }
 
+/**
+ * PEM/PGP private-key spans, found linearly. Each BEGIN marker pairs with the
+ * next END marker after it; a BEGIN with no following END runs to end of string
+ * (an unterminated fragment is still a leaked key). Pairing by position avoids
+ * the quadratic backtracking a single BEGIN…END regex incurs.
+ * @param {string} value
+ * @returns {SecretMatch[]}
+ */
+function findPrivateKeyBlocks(value) {
+  /** @type {SecretMatch[]} */
+  const spans = [];
+  PRIVATE_KEY_BEGIN_RE.lastIndex = 0;
+  let begin;
+  while ((begin = PRIVATE_KEY_BEGIN_RE.exec(value)) !== null) {
+    const bodyStart = begin.index + begin[0].length;
+    PRIVATE_KEY_END_RE.lastIndex = bodyStart;
+    const end = PRIVATE_KEY_END_RE.exec(value);
+    const spanEnd = end ? end.index + end[0].length : value.length;
+    spans.push({ kind: 'private-key-block', start: begin.index, end: spanEnd });
+    // Resume scanning past this block so overlapping BEGINs inside it are skipped.
+    PRIVATE_KEY_BEGIN_RE.lastIndex = spanEnd;
+  }
+  return spans;
+}
+
 /**
  * Locate every secret-shaped span inside a string, sorted and non-overlapping.
  * @param {string} value
@@ -223,6 +255,8 @@ function findSecretMatches(value) {
     }
   }
 
+  matches.push(...findPrivateKeyBlocks(value));
+
   URL_CREDENTIALS_RE.lastIndex = 0;
   let credentials;
   while ((credentials = URL_CREDENTIALS_RE.exec(value)) !== null) {

package/src/suppressions.js

@@ -0,0 +1,431 @@
+import { basename, extname } from 'path';
+
+import { stripJsonComments } from './parser.js';
+
+/**
+ * Inline suppressions: `# flecto-ignore-next-line <rule> — <reason>` on the line
+ * above a deliberate finding. The companion to the baseline (#118) — a baseline
+ * accepts findings in bulk, a suppression accepts one, in place, next to the
+ * thing being accepted.
+ *
+ * Two rules keep it from decaying into a wall of unexplained `# noqa`:
+ *
+ * - **A reason is mandatory.** A directive without one is refused, loudly,
+ *   naming the file and line — never silently applied and never silently
+ *   dropped.
+ * - **It is scoped to the next line and a named rule.** No bare "ignore
+ *   everything here"; `--ignore` and `severityRemap` already do that, at the
+ *   level where they belong.
+ *
+ * Resolving a directive to a finding is the hard part, because a finding carries
+ * a *semantic path*, not a line. We reconstruct the full path of the key on the
+ * suppressed line from the raw source — nesting for YAML, section/table for
+ * INI/TOML, flat for dotenv — and match a finding whose path equals it (or ends
+ * with it, so a multi-document identity prefix does not defeat the match). Using
+ * the *full* path, not just the leaf, is what stops a suppression on one
+ * `pool_size` from silently hiding an uncommented `pool_size` elsewhere in the
+ * file — over-suppression being the dangerous failure for a security tool.
+ *
+ * JSON is included, because `.json` and `.jsonc` are parsed as JSONC (#152) and
+ * so do carry comments. Its resolver reuses the parser's comment stripper rather
+ * than recognising line and block comments a second time: they are blanked in
+ * place, preserving every line number, and the key scan then walks a
+ * comment-free copy.
+ *
+ * A directive that cannot be resolved to a key — an array element in any format,
+ * or a file type with no comment syntax at all — produces a **warning naming the
+ * file and line**. That case fails closed (the finding still fires and still
+ * gates), so it is not a second build failure on top of the first; but a
+ * suppression the author believes is applied and which is quietly absent is
+ * exactly the failure mode this file exists to avoid, so it is never silent.
+ */
+
+const DIRECTIVE = /flecto-ignore-next-line\b[ \t]*(.*)$/;
+// Strip a leading reason separator: an em dash, one or more hyphens, or a colon.
+const REASON_SEPARATOR = /^(?:—|-{1,2}|:)[ \t]*/;
+
+/**
+ * @typedef {'yaml' | 'json' | 'toml' | 'ini' | 'dotenv' | null} SuppressionFormat
+ *
+ * @typedef {{
+ *   rule: string,
+ *   reason: string,
+ *   line: number,
+ *   path: string | null
+ * }} Suppression
+ *
+ * @typedef {{ line: number, message: string }} SuppressionError
+ *
+ * @typedef {{ line: number, message: string }} SuppressionWarning
+ */
+
+/**
+ * Which comment-bearing format a file is, or null when inline suppression does
+ * not apply to it — an encrypted file, or an extension with no comment syntax.
+ * @param {string} filepath
+ * @returns {SuppressionFormat}
+ */
+export function suppressionFormat(filepath) {
+  const base = basename(filepath);
+  if (base === '.env' || base.startsWith('.env.') || base.endsWith('.env')) return 'dotenv';
+  switch (extname(filepath).toLowerCase()) {
+    case '.yaml':
+    case '.yml':
+      return 'yaml';
+    case '.json':
+    case '.jsonc':
+      return 'json';
+    case '.toml':
+      return 'toml';
+    case '.ini':
+      return 'ini';
+    default:
+      return null;
+  }
+}
+
+/**
+ * Leading indentation width (spaces; a tab counts as one).
+ * @param {string} line
+ * @returns {number}
+ */
+function indentOf(line) {
+  const match = /^[ \t]*/.exec(line);
+  return match ? match[0].length : 0;
+}
+
+/**
+ * Whether a line carries no config. JSON is scanned on a comment-blanked copy,
+ * so its comments are already whitespace by the time this runs — treating a `#`
+ * there as a comment would misread a line whose value merely starts with one.
+ * @param {string} raw
+ * @param {SuppressionFormat} [format]
+ * @returns {boolean}
+ */
+function isBlankOrComment(raw, format) {
+  const trimmed = raw.trim();
+  if (trimmed === '') return true;
+  if (format === 'json') return false;
+  return trimmed.startsWith('#') || trimmed.startsWith(';');
+}
+
+/**
+ * Reconstruct the dotted path of the key defined on `targetIndex`, walking the
+ * lines above it for context. Returns null when the line is not a plain
+ * `key: value` / `key = value` mapping entry (e.g. an array item), which the
+ * caller treats as "cannot resolve" rather than guessing.
+ * @param {string[]} lines
+ * @param {number} targetIndex
+ * @param {SuppressionFormat} format
+ * @returns {string | null}
+ */
+function pathAtLine(lines, targetIndex, format) {
+  if (format === 'dotenv') return dotenvKey(lines[targetIndex]);
+  if (format === 'ini' || format === 'toml') return sectionedKey(lines, targetIndex, format);
+  if (format === 'json') return jsonPath(lines, targetIndex);
+  return yamlPath(lines, targetIndex);
+}
+
+/**
+ * @param {string} line
+ * @returns {string | null}
+ */
+function dotenvKey(line) {
+  const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_.]*)\s*=/.exec(line);
+  return match ? match[1] : null;
+}
+
+/**
+ * INI/TOML share a section/table header + `key = value` shape.
+ * @param {string[]} lines
+ * @param {number} targetIndex
+ * @param {'ini' | 'toml'} format
+ * @returns {string | null}
+ */
+function sectionedKey(lines, targetIndex, format) {
+  const target = lines[targetIndex];
+  const keyMatch = /^\s*([A-Za-z0-9_.\-"']+)\s*=/.exec(target);
+  if (!keyMatch) return null;
+  const key = unquote(keyMatch[1].trim());
+
+  let section = null;
+  for (let i = 0; i < targetIndex; i++) {
+    const line = lines[i].trim();
+    // TOML arrays-of-tables ([[x]]) do not map onto a single dotted path.
+    if (format === 'toml' && /^\[\[.+\]\]$/.test(line)) { section = null; continue; }
+    const header = /^\[([^\]]+)\]$/.exec(line);
+    if (header) section = header[1].trim();
+  }
+  return section ? `${section}.${key}` : key;
+}
+
+/** Key of a `"key":` entry, capturing the raw (still-escaped) name. */
+const JSON_KEY = /^\s*"((?:[^"\\]|\\.)*)"\s*:/;
+
+/**
+ * Reconstruct a nested JSON object path from the enclosing key stack. `lines`
+ * are already comment-blanked, so what is scanned is config and nothing else.
+ *
+ * Anything inside an **array** yields null. That is the same refusal YAML makes
+ * for a sequence item, and for the same reason: an array element's diff path is
+ * either its index or its `arrayIdKey` identity depending on how the run is
+ * configured, so a resolver that guessed one would suppress the wrong finding
+ * under the other — over-suppression being the dangerous direction here. The
+ * caller warns rather than dropping it quietly.
+ * @param {string[]} lines
+ * @param {number} targetIndex
+ * @returns {string | null}
+ */
+function jsonPath(lines, targetIndex) {
+  const key = jsonKeyOnLine(lines[targetIndex]);
+  if (key === null) return null;
+  const enclosing = jsonContainerKeys(lines.slice(0, targetIndex).join('\n'));
+  if (enclosing === null) return null;
+  return [...enclosing, key].join('.');
+}
+
+/**
+ * @param {string} line
+ * @returns {string | null}
+ */
+function jsonKeyOnLine(line) {
+  const match = JSON_KEY.exec(line);
+  return match ? decodeJsonString(match[1]) : null;
+}
+
+/**
+ * A JSON key is an escaped string, so `\u00e9` and `\"` have to be decoded to
+ * the name the differ reports rather than compared raw.
+ * @param {string} inner
+ * @returns {string | null}
+ */
+function decodeJsonString(inner) {
+  try {
+    return JSON.parse(`"${inner}"`);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The object keys enclosing the end of `text`, outermost first, or null when
+ * the position sits inside an array or the structure cannot be read. The root
+ * container contributes no segment, matching how the differ builds a path.
+ * @param {string} text
+ * @returns {string[] | null}
+ */
+function jsonContainerKeys(text) {
+  /** @type {{ array: boolean, key: string | null }[]} */
+  const stack = [];
+  let lastKey = null;
+  let i = 0;
+
+  while (i < text.length) {
+    const ch = text[i];
+
+    if (ch === '"') {
+      // Strings are opaque: a brace or bracket inside one is data, not structure.
+      let end = i + 1;
+      while (end < text.length) {
+        if (text[end] === '\\') { end += 2; continue; }
+        if (text[end] === '"') break;
+        end += 1;
+      }
+      const inner = text.slice(i + 1, end);
+      i = end + 1;
+      let next = i;
+      while (next < text.length && /\s/.test(text[next])) next += 1;
+      // A string followed by a colon names the value that follows; otherwise it
+      // is itself a value, and names nothing.
+      if (text[next] === ':') {
+        lastKey = decodeJsonString(inner);
+        i = next + 1;
+      }
+      continue;
+    }
+
+    if (ch === '{' || ch === '[') {
+      stack.push({ array: ch === '[', key: lastKey });
+      lastKey = null;
+    } else if (ch === '}' || ch === ']') {
+      stack.pop();
+      lastKey = null;
+    } else if (ch === ',') {
+      lastKey = null;
+    }
+    i += 1;
+  }
+
+  if (stack.length === 0) return null;
+  if (stack.some((frame) => frame.array)) return null;
+  const keys = stack.slice(1).map((frame) => frame.key);
+  return keys.some((key) => key === null) ? null : /** @type {string[]} */ (keys);
+}
+
+/**
+ * Reconstruct a nested YAML mapping path via indentation. Array items and
+ * multi-document separators yield null, so those are left to the baseline rather
+ * than resolved by guesswork.
+ * @param {string[]} lines
+ * @param {number} targetIndex
+ * @returns {string | null}
+ */
+function yamlPath(lines, targetIndex) {
+  const target = lines[targetIndex];
+  const targetKey = yamlKey(target);
+  if (targetKey === null) return null;
+
+  /** @type {{ indent: number, key: string }[]} */
+  const stack = [];
+  for (let i = 0; i <= targetIndex; i++) {
+    const line = lines[i];
+    if (isBlankOrComment(line, 'yaml')) continue;
+    if (line.trim() === '---') return null; // multi-document: identity-prefixed, skip
+    const trimmed = line.trim();
+    if (trimmed.startsWith('- ')) return null; // inside a sequence
+    const key = yamlKey(line);
+    if (key === null) continue;
+    const indent = indentOf(line);
+    while (stack.length > 0 && stack[stack.length - 1].indent >= indent) stack.pop();
+    stack.push({ indent, key });
+  }
+  return stack.map((entry) => entry.key).join('.');
+}
+
+/**
+ * The key of a `key:` or `key: value` YAML line, or null.
+ * @param {string} line
+ * @returns {string | null}
+ */
+function yamlKey(line) {
+  const match = /^\s*([^\s:#][^:]*):(?:\s|$)/.exec(line);
+  return match ? unquote(match[1].trim()) : null;
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function unquote(value) {
+  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+/**
+ * Parse every `flecto-ignore-next-line` directive in a file's raw text.
+ * @param {string} raw
+ * @param {SuppressionFormat} format
+ * @returns {{
+ *   suppressions: Suppression[],
+ *   errors: SuppressionError[],
+ *   warnings: SuppressionWarning[]
+ * }}
+ */
+export function parseSuppressions(raw, format) {
+  /** @type {Suppression[]} */
+  const suppressions = [];
+  /** @type {SuppressionError[]} */
+  const errors = [];
+  /** @type {SuppressionWarning[]} */
+  const warnings = [];
+
+  const text = String(raw);
+  const lines = text.split(/\r?\n/);
+  // Directives are read from the raw text, and keys from a comment-blanked copy
+  // of it. stripJsonComments() replaces each stripped character with a space and
+  // keeps newlines, so the two are line-for-line identical.
+  const code = format === 'json' ? stripJsonComments(text).split(/\r?\n/) : lines;
+
+  for (let i = 0; i < lines.length; i++) {
+    const match = DIRECTIVE.exec(lines[i]);
+    if (!match) continue;
+    // Directives are scanned on the raw line so `// flecto-ignore-next-line`
+    // is visible. For JSON, comments have already been blanked on `code`, so a
+    // match still present there lived inside a string — data, not a comment.
+    // Treating it as a suppression would hide the next key, the over-suppression
+    // this resolver exists to refuse.
+    if (format === 'json') {
+      const blanked = code[i].slice(match.index, match.index + match[0].length);
+      if (blanked.trim() !== '') continue;
+    }
+    const lineNo = i + 1;
+
+    // A directive in a file whose format cannot carry one does nothing. Saying
+    // so is the whole point: the author believes the finding is accepted.
+    if (!format) {
+      warnings.push({
+        line: lineNo,
+        message: 'inline suppressions do not apply to this file type and this directive has no effect — use --baseline to accept the finding',
+      });
+      continue;
+    }
+
+    const rest = match[1].trim();
+    const ruleMatch = /^(\S+)([\s\S]*)$/.exec(rest);
+    if (!ruleMatch) {
+      errors.push({ line: lineNo, message: 'flecto-ignore-next-line needs a rule id and a reason' });
+      continue;
+    }
+    const rule = ruleMatch[1];
+    const reason = ruleMatch[2].trim().replace(REASON_SEPARATOR, '').trim();
+    if (!reason) {
+      errors.push({
+        line: lineNo,
+        message: `flecto-ignore-next-line ${rule} needs a reason (e.g. "# flecto-ignore-next-line ${rule} — why this is intended")`,
+      });
+      continue;
+    }
+
+    // The suppressed line is the next line that carries config, not another
+    // comment or a blank.
+    let target = -1;
+    for (let j = i + 1; j < code.length; j++) {
+      if (!isBlankOrComment(code[j], format)) { target = j; break; }
+    }
+    const path = target === -1 ? null : pathAtLine(code, target, format);
+    if (path === null) {
+      warnings.push({
+        line: lineNo,
+        message: `flecto-ignore-next-line ${rule} does not resolve to a config key, so it suppresses nothing — array elements and multi-document files are not addressable inline; use --baseline`,
+      });
+    }
+    suppressions.push({ rule, reason, line: lineNo, path });
+  }
+  return { suppressions, errors, warnings };
+}
+
+/**
+ * True when `findingPath` is the suppression's path, or ends with it on a
+ * dotted-segment boundary (tolerating a document-identity prefix).
+ * @param {string} findingPath
+ * @param {string} suppressionPath
+ * @returns {boolean}
+ */
+function pathMatches(findingPath, suppressionPath) {
+  if (!suppressionPath) return false;
+  if (findingPath === suppressionPath) return true;
+  return findingPath.endsWith(`.${suppressionPath}`);
+}
+
+/**
+ * Partition findings against a file's suppressions.
+ * @param {import('./policy.js').PolicyFinding[]} findings
+ * @param {Suppression[]} suppressions
+ * @returns {{
+ *   active: import('./policy.js').PolicyFinding[],
+ *   suppressed: Array<{ finding: import('./policy.js').PolicyFinding, reason: string }>
+ * }}
+ */
+export function applySuppressions(findings, suppressions) {
+  const active = [];
+  const suppressed = [];
+  for (const finding of findings) {
+    const hit = suppressions.find((s) =>
+      s.path && String(finding.id) === s.rule && pathMatches(String(finding.path ?? ''), s.path));
+    if (hit) suppressed.push({ finding, reason: hit.reason });
+    else active.push(finding);
+  }
+  return { active, suppressed };
+}

package/src/terraform.js

@@ -416,6 +416,34 @@ export function assertTerraformPlan(value, label) {
   );
 }
 
+/**
+ * The inverse guard: refuse a Terraform plan on the *generic config* path.
+ *
+ * Terraform's `before_sensitive` / `after_sensitive` redaction is applied by
+ * diffTerraformPlan(), which only `flecto plan` calls. A plan file is ordinary
+ * JSON, so every other command would read it as a plain config tree and print
+ * the values Terraform itself refuses to print. `--mask-secrets` is not a
+ * backstop: it only fires when an attribute name matches the secret pattern,
+ * and `user_data` does not (#113).
+ *
+ * Failing closed rather than skipping is deliberate and matches how the rest of
+ * Flecto behaves — a plan file swept up by a repo-wide glob is a real
+ * misconfiguration, and silently omitting the file would leave an operator
+ * believing it had been gated.
+ * @param {unknown} value
+ * @param {string} label
+ */
+export function assertNotTerraformPlan(value, label) {
+  if (!isTerraformPlan(value)) return;
+  throw new Error(
+    `"${label}" is Terraform plan JSON, which this command cannot read safely.\n`
+    + 'Terraform marks sensitive attributes in before_sensitive/after_sensitive, and that\n'
+    + 'redaction is only applied by "flecto plan". Reading the plan as a plain config file\n'
+    + 'would print those values.\n'
+    + `Use: flecto plan ${label}`,
+  );
+}
+
 /**
  * Read and validate a Terraform plan JSON file.
  * @param {string} filepath