flecto 3.0.1 → 3.1.0

package/CHANGELOG.md

@@ -7,6 +7,540 @@ The format is based on [Keep a Changelog], and this project adheres to
 
 ## [Unreleased]
 
+## [3.1.0] - 2026-09-15
+
+### Added
+
+- **A shared, git-tracked snapshot store** ([#141]). Snapshot history lived in
+  `.flecto-snapshots/`, keyed by each file's *absolute* path — right for a laptop
+  and meaningless anywhere else. An ephemeral runner starts with that directory
+  empty on every run, so `history` and `report` were local-only by construction
+  and `ci` had to be handed `--snapshot-ref`.
+
+  `--snapshot-store shared` (or `"snapshotStore": "shared"` in `.flectorc`, which
+  is the better place for it) writes `.flecto/snapshots/` instead: keyed by
+  repo-relative path, one file per config file with its history inside, keys
+  sorted at every level. Commit it and every runner reads the baseline the author
+  saved, with no cache, no ref, and no setup step. `watch`, `ci`, `history`, and
+  `report` all read whichever store is selected, and every "nothing found"
+  message names the store it looked in.
+
+  **Committing snapshots commits config values into git history permanently**, so
+  the shared store masks by default: values that trip Flecto's secret detection —
+  by shape *or* by key name, the same names `--mask-secrets` recognizes — are
+  stored as `flecto:sha256:<digest>`. The digest is a change detector, not a
+  vault — a rotated credential still reports as drift, because a store that
+  silently missed one would be worse than no store, and the live side of a diff is
+  masked the same way so an untouched secret produces no change.
+  `--snapshot-mask none` opts out and says so.
+
+  Retention (`--snapshot-retention`, 20 per file in the shared store) prunes
+  oldest-first, because an append-forever store inside a repository becomes its
+  own problem. The `local` store is untouched: same filenames, same JSON, same
+  unbounded history, still the default.
+
+### Security
+
+- **The merge gate could be turned green from `.flectorc`** ([#121]).
+  `--update-baseline` accepts every finding of the current run, and it resolved
+  through the ordinary options merge — so a pull request that added four lines of
+  `.flectorc` turned a failing `flecto ci --fail-on error` into a passing one,
+  overriding a `--fail-on` given on the command line. `updateBaseline` is now
+  refused from `.flectorc` (and from a profile) rather than honored: it is an
+  action, not a setting. `--update-baseline` on the command line is unchanged.
+
+- **Write destinations could be redirected out of the repository** ([#121]).
+  `--output` (`flecto report`) and `--baseline` (`flecto ci`) can both be declared
+  in `.flectorc`, so a pull request could point them at any file the job could
+  reach — through `..`, or through a symlink — and both files carry content that
+  pull request partly wrote. A destination declared in `.flectorc` must now
+  resolve inside the project (`FLECTO_ALLOW_RC_WRITES=1` opts out), and a
+  destination that leaves the project through a symlink is refused whoever named
+  it (`FLECTO_ALLOW_SYMLINK_TARGETS=1` opts out) — including a link whose target
+  does not exist yet, which `existsSync` reports as absent and which would have
+  Flecto *create* a file outside the repository rather than overwrite one. A
+  destination named on the command line is operator intent and is unchanged.
+
+- **The GitLab token followed redirects** ([#121]). `fetch` strips
+  `Authorization` when a redirect crosses origins and strips only that header;
+  GitLab authenticates with `PRIVATE-TOKEN`, which was forwarded to the redirect
+  target in full — verified against a local server. Provider API requests are now
+  issued with `redirect: 'manual'` and refuse a 3xx, naming the origin it pointed
+  at. Bitbucket workspace and repository segments are URL-encoded alongside,
+  matching GitLab's project id.
+
+  The API host comes from runner environment rather than pull request content, so
+  this needed a hostile or misconfigured API host to reach.
+
+## [3.0.2] - 2026-09-06
+
+### Security
+
+- **Assessed 2.x against GHSA-wq8m-fc3q-8m5x and corrected the advisory range**
+  ([#125]). The advisory's own proof-of-concept was run against a clean install
+  of every released version: 2.0.0, 2.1.0, and 3.0.0 execute an rc-declared
+  plugin; 1.0.x predate the `plugins` option, and 3.0.1 is fixed. So the true
+  affected range is `>= 2.0.0, <= 3.0.0`, not the `<= 3.0.0` the draft advisory
+  recorded — which wrongly swept in 1.x. The 2.x backport is merged on
+  `release/2.x` (2.1.1) and blocks both the exploit and its path-traversal
+  variant, but **2.1.1 was never published**, so the highest installable 2.x is
+  the still-vulnerable 2.1.0. `SECURITY.md` now says so, and the full matrix and
+  publish recommendation are in
+  [`docs/ghsa-wq8m-fc3q-8m5x-2x.md`](docs/ghsa-wq8m-fc3q-8m5x-2x.md).
+
+### Added
+
+- **Inline suppressions in JSON** ([#158]). `.json` and `.jsonc` are parsed as
+  JSONC, so they carry comments — but `flecto-ignore-next-line` was still skipped
+  there, and skipped silently: the directive parsed as an ordinary comment, the
+  finding fired anyway, and nothing told the author their suppression had been
+  ignored. That is the failure mode inline suppressions exist to avoid, pointed
+  the wrong way.
+
+  The JSON resolver reuses the parser's comment stripper rather than recognising
+  `//` and block comments a second time — comments are blanked in place, so line
+  numbers still line up — and then walks the brace/bracket depth and enclosing
+  key stack to the same dotted path the differ reports.
+
+  Anything inside an **array** is refused, as it already is in YAML: an array
+  element's diff path is its index or its `--array-id-key` identity depending on
+  how the run is configured, so resolving one would suppress the wrong finding
+  under the other. Over-suppression is the dangerous direction for a security
+  tool, and the refusal is covered per array mode rather than by one happy path.
+
+- **Coverage measurement in CI, focused on the modules where a gap is a security
+  question** ([#149]). CI ran `npm test` and `npm run pack:check` and nothing
+  else, so "is the plugin-loading path from GHSA-wq8m-fc3q-8m5x covered, and is
+  every branch of it covered?" was answered by reading `test/security.test.js`
+  and hoping.
+
+  `npm run coverage` runs the suite under `node --test
+  --experimental-test-coverage` — a flag, not a dependency — and prints a report
+  for `config.js` (plugin resolution), `policy.js` (pack loading), `secrets.js`,
+  `encrypted.js`, `pr-comment.js`, and `pr-providers.js` (token handling), worst
+  branch coverage first, with the count of branches that never executed.
+  Reporting those separately is the point: one repo-wide average is the number
+  that hides them.
+
+  **No threshold gates the job.** A number chosen before anyone has read the
+  report is arbitrary, and the usual outcome is tests written to satisfy the gate
+  rather than to find defects. The report prints in the job log, so reading it
+  needs no artifact download. The one thing that *does* fail the job is a focused
+  module missing from the report — a renamed module would otherwise drop out of
+  the table silently, leaving a report that covers less than it claims to.
+
+  No linter. The style argument is the weak one, the project is consistent
+  without it, and a rule set worth having is a separate decision from this one.
+  See [security review](docs/security-review.md#knowing-what-has-been-exercised).
+
+- `afterAnyMatches`, a policy matcher that applies a regular expression to the
+  elements of an array value. `afterMatches` requires a string, so the edit that
+  widens a scalar into a list — `runs-on: ubuntu-latest` →
+  `runs-on: [self-hosted, linux]` — was invisible to every value predicate: the
+  differ reports it as one `changed` event whose `after` is an array and does not
+  descend into a type change, so no per-element leaf exists to match either. The
+  scan is flat and array-only: a non-array value never matches, non-string
+  elements are skipped, and it does not recurse into nested arrays or objects, so
+  what a rule matches stays readable from the rule text. `afterMatches` keeps its
+  exact meaning, so no existing pack changes behavior. The `github-actions` pack's
+  `github-actions-self-hosted-runner` rule now pairs the two in an `anyOf` and
+  covers the fourth `runs-on` shape it previously documented as a limitation.
+  ([#159])
+
+- **Merge request comments on GitLab and Bitbucket.** The sticky review comment
+  was GitHub-only: `src/pr-comment.js` and both composite actions spoke
+  `GITHUB_TOKEN`, `GITHUB_EVENT_PATH`, and the issue-comments API directly, so
+  the flagship review experience was unavailable to every team not on GitHub.
+
+  Delivery is now an adapter (`src/pr-providers.js`); everything upstream of it —
+  the differ, the policy engine, the envelope, and the rendered markdown body —
+  was already provider-agnostic. The host is detected from CI variables and
+  `--pr-provider github|gitlab|bitbucket` forces one. All three upsert a single
+  sticky comment by marker, skip the write when the body is unchanged, redact
+  the token from error text, and leave the exit code to the diff and policy
+  result.
+
+  **GitLab's `CI_JOB_TOKEN` cannot post merge request notes.** Flecto does not
+  attempt it, because the resulting 401 reads like a broken setup rather than a
+  missing permission; it names `FLECTO_GITLAB_TOKEN` and the `api` scope
+  instead. See [CI](docs/ci.md#providers). ([#138])
+
+- Inline suppressions: `# flecto-ignore-next-line <rule> — <reason>` on the line
+  above a deliberate finding accepts that one finding in place, the companion to
+  the baseline's bulk acceptance. **A reason is mandatory** — a directive without
+  one is refused with a pointer to the file and line, never silently applied or
+  dropped — so a repo does not accumulate unexplained suppressions. It is scoped
+  to the next line and the named rule, and resolves to that line's full key path
+  (nesting for YAML, section/table for INI/TOML, flat for dotenv), so a
+  suppression on one `pool_size` cannot hide an uncommented `pool_size` elsewhere
+  in the file. Works in every commented format Flecto parses — YAML, TOML, INI,
+  dotenv, and (since [#158]) JSON. Suppressed findings
+  are still surfaced — a count by default, the full list with `--show-suppressed`
+  — so the gate stays legible. ([#119])
+
+- Adoption baseline for `flecto ci`: `--baseline <file>` gates only on findings
+  not already recorded, and `--update-baseline` rewrites the file from the
+  current findings. This is how a repo with years of pre-existing config turns on
+  enforcement without first fixing everything or silencing rules it still wants
+  on new config. A finding is keyed on `(rule id, file, path)` — not its value —
+  so an accepted `pool-size-jump` stays accepted as the number drifts, and the
+  file does not churn. Recorded findings are suppressed from the gate and the
+  output; new ones still fail. The file is diff-friendly (one sorted entry per
+  finding, with severity, message, `acceptedAt`, and an optional hand-written
+  `reason` that updates preserve). Stale entries — recorded findings that no
+  longer occur — are reported so the file shrinks; updating is always explicit,
+  never automatic, so a run cannot launder new risk into the accepted set.
+  Change-based `--fail-on` triggers still fire, since the baseline accepts policy
+  findings, not the diff. ([#118])
+
+- `flecto ci --format sarif` emits SARIF 2.1.0 for upload to GitHub code
+  scanning (`github/codeql-action/upload-sarif`). Policy findings render on the
+  pull request diff and in the Security tab, with GitHub handling dedup,
+  new-vs-existing, and fixed-finding tracking. Each pack rule maps to a
+  `reportingDescriptor` (id, short description, pack, level); `severity` maps to
+  SARIF `level` (`error`/`warning`/`note`). `--mask-secrets` applies, since a
+  SARIF file is uploaded and retained. Results are **file-level** for now —
+  Flecto reports a semantic path, not a source line, so each result anchors at
+  the top of the file and preserves the full path as a SARIF logical location;
+  GitHub still renders and tracks the alert. Recipe and required
+  `security-events: write` permission are in [docs/ci.md](docs/ci.md). ([#120])
+
+- `flecto init` now detects Kubernetes manifests and SOPS usage — the two file
+  shapes 3.0 was built around — and enables the `kubernetes` and `sops` packs
+  accordingly. Detection is content-based: a YAML document must actually carry
+  `apiVersion` + `kind` to count as a manifest (a config with a bare `kind:`
+  field does not), and SOPS is recognized from a top-level metadata block or a
+  `.sops.yaml` creation-rules file. Sniffing is bounded — the repo root plus the
+  conventional `k8s/` / `kubernetes/` / `manifests/` / `deploy/` directories, a
+  cap on files read, and files over 256 KB skipped — so `init` never turns into
+  a full-tree scan. The "detected nothing" generic fallback is unchanged. ([#123])
+
+- **JSON with comments and trailing commas is parsed** ([#152]). `.json` was
+  read with bare `JSON.parse`, so a single `//` failed the whole file — and a
+  config watcher installed into a JavaScript repository could not read the
+  `tsconfig.json`, `.vscode/settings.json`, `jsconfig.json`, or
+  `devcontainer.json` sitting next to it. Worse, it failed with a *parse error*
+  rather than an unsupported-format skip, so it looked broken rather than out of
+  scope.
+
+  Both comment styles and trailing commas are now accepted, and `.jsonc` is a
+  recognised extension. No new dependency: comments are blanked in place, one
+  space per stripped character, with newlines kept — so byte offsets and line
+  numbers in a genuine syntax error still point at the line in your file.
+
+  The strip tracks string state, because the naive version corrupts exactly the
+  values config files carry: `{"url": "https://example.com"}` is a URL, not a
+  comment. Comments are not preserved on the parsed value; Flecto never rewrites
+  config, and a comment-only edit is not a semantic change. See
+  [JSON with comments](docs/configuration.md#json-with-comments).
+
+  Inline suppressions followed, in [#158] — a directive written in a file that
+  visibly supports comments no longer does nothing.
+- **`ci --changed-only`** ([#151]). `ci --format json` emitted an envelope for
+  every **scanned** file, not every **changed** one, so the output grew with the
+  size of the repository rather than the size of the change. Each envelope
+  carries `schema_version`, two UUIDs, an ISO timestamp, and an absolute path —
+  on 250 service configs with one file edited, roughly 88% of the output
+  described files that did not change.
+
+  For a human that is invisible, since the terminal renderer already prints only
+  what changed. It is the machine consumers that pay: webhook sinks, NDJSON
+  readers, and any agent handed the JSON.
+
+  | change (250 configs) | default | `--changed-only` | reduction |
+  |---|---|---|---|
+  | nothing changed | 112.8 KB | 13.3 KB | 88% |
+  | one file changed | 113.4 KB | 14.3 KB | 87% |
+  | every 10th file changed | 126.8 KB | 37.3 KB | 71% |
+
+  **The evidence that Flecto looked is kept.** An envelope for a scanned but
+  unchanged file tells a consumer diffing two runs that a file was *checked and
+  clean* rather than *not checked at all*, and dropping it would quietly weaken
+  a gate someone relies on. Those files collapse into a single `lifecycle`
+  envelope carrying the list of paths, so what is removed is the per-file
+  overhead rather than the signal.
+
+  **Off by default**, so `schema_version` stays `2.0` and existing consumers see
+  byte-for-byte identical output. A file with policy findings but no changes is
+  never collapsed. Settable as `changedOnly` in `.flectorc`. See
+  [CI usage](docs/ci.md#--changed-only).
+
+- **`github-actions` policy pack** ([#139]). Workflow YAML is the one config
+  file in most repositories where a bad change is a security incident rather
+  than an outage, and Flecto already parses it. Eleven declarative rules over
+  the CI-takeover shapes: `pull_request_target` added, a new scheduled, manual,
+  or reusable-workflow trigger, the `permissions` block removed or widened to
+  `write-all` or to `write` on one scope, an action referenced by mutable tag
+  instead of a commit SHA, a checkout of the pull-request head, `secrets.*`
+  interpolated into `run:`, and a job moved to a self-hosted runner. Enabled by
+  `flecto init` when `.github/workflows/` exists. No engine change — the pack
+  auto-registers from `src/packs/`.
+
+  It reports **what the pull request changed**, not what the workflow already
+  contained; `actionlint` and `zizmor` already lint the state well. Two limits
+  are documented rather than papered over: severity cannot depend on the
+  trigger, because a rule sees one change event and cannot consult the rest of
+  the document, and `runs-on` changing from a string to a list produces one
+  event whose value is an array, which no matcher inspects. Every rule carries
+  its reasoning in [policy packs](docs/policy-packs.md#github-actions-workflows),
+  and four fixtures pin the boundary — including one asserting **zero** findings
+  for changes that only look risky.
+
+- **Context-savings measurement in the benchmark harness.** Section 5 of
+  `npm run bench` reports the size of the semantic diff against the size of the
+  config it describes, in bytes, at three mutation rates plus a single-file
+  crossover table. Published in [performance](docs/performance.md#context-savings).
+
+  The result is more qualified than the claim it was written to check. A sparse
+  change in a large file is 50x to 1270x cheaper to read as a diff than as the
+  file, and the advantage compounds because a change event plus its envelope
+  costs a fixed ~600 bytes while the file grows. But a *dense* change is not
+  cheaper at all — at roughly a quarter of a file's keys the payload runs about
+  3x the size of the files it covers — and `ci --format json` currently emits an
+  envelope for every **scanned** file rather than every changed one, so with one
+  file changed out of 250 roughly 98% of the output is boilerplate for files that
+  did not change. ([#137])
+
+### Changed
+- The 3.0 integrations were verified against the real tools they integrate with,
+  not only fixtures ([#122]). The HTML report was opened in a real browser — both
+  themes render with no JS errors, and the filter, expand/collapse, and
+  disclosure triangle work. The encrypted-file path is now tested against output
+  from the real `age` binary (`test/fixtures/encrypted-real/`), confirming a real
+  age file is detected and never leaks ciphertext through a diff. The
+  `flecto-pr-risk` Action was statically reviewed (no runner here to execute a
+  live PR) and its flagged mechanics are correct. What was verified, and what
+  still needs a real runner / `terraform` / `sops`, is recorded in
+  [docs/integration-verification.md](docs/integration-verification.md) — which
+  also notes that `flecto report` has no `--mask-secrets` yet, so it renders
+  secret values in the clear (a follow-up). ([#122])
+
+- **CI runs on Windows and macOS** ([#148]). The matrix varied the Node version
+  and nothing else, so every job ran on `ubuntu-latest` — for a tool whose
+  primary local mode is watching files by glob, the two platforms where that
+  behavior differs had never been tested. Linux keeps the full Node matrix;
+  Windows and macOS run one version each, since what they add is the operating
+  system rather than the runtime.
+
+- **Fuzzing for the boundary an untrusted pull request controls** ([#150]).
+  `flecto ci` runs on a pull request, and everything it reads there is
+  attacker-supplied: the config files, their names, `.flectorc`, and the regexes
+  inside a policy pack the same pull request can add. GHSA-wq8m-fc3q-8m5x came
+  out of that surface, and the two DoS vectors fixed after it were found by hand
+  — which finds what someone thought to look for.
+
+  `npm run fuzz` runs eleven structure-aware targets over it: `parseContent` per
+  format, `diffTrees`, `expandChangeSubtrees`, Flecto's own regexes in
+  `secrets.js` and `encrypted.js`, and pack loading and evaluation. The shared
+  invariant is that each either succeeds or throws a clean `Error` — never hangs,
+  never exhausts memory, never returns a prototype-polluted object.
+
+  **No fuzzing dependency.** The inputs are config text, trees, and regex sources
+  rather than binary protocols, so the generators are hand-written over a seeded
+  PRNG in `test/fuzz/`. That is also what makes a case `(target, seed, index)`
+  and nothing else, so `--case N` replays one case without walking the N-1 before
+  it.
+
+  **The time budget is enforced from outside the process.** A hang cannot be
+  observed from inside the process that hung, so cases run in a child that writes
+  its case index before running the case, and the driver kills the child when the
+  heartbeat stops. A failing input is then shrunk — each candidate in its own
+  child, so a candidate that hangs shrinks like any other failure.
+
+  **A finding becomes a regression test by moving one file.** The minimized input
+  lands in `test/fuzz/findings/`; moving it to `test/fixtures/fuzz/` is the whole
+  procedure, because `test/fuzz-regressions.test.js` replays everything there as
+  part of `npm test`. The corpus ships seeded with the already-fixed vectors from
+  the security review record.
+
+  Scheduled nightly, never on a pull request — a fuzz run is a wall-clock budget
+  against a random seed, and gating a merge on one is a flaky merge gate — and it
+  files nothing automatically, because a finding on this boundary may be
+  exploitable rather than merely a hang and those go private per `SECURITY.md`.
+
+### Fixed
+
+- **"No snapshot history" no longer renders as "no drift"** ([#141]).
+  `.flecto-snapshots/` lives in the working directory and is not committed, so on
+  an ephemeral CI runner it is empty on every run — and the drift commands read
+  that emptiness as an all-clear. For a tool whose job is making risk visible,
+  rendering a clean result from a missing input is the worst failure available.
+
+  - `flecto watch --diff` exited **0** when no target had a snapshot: nothing
+    was compared, and the caller was told the files match their baseline. It now
+    errors, and a run where only *some* targets lack a snapshot reports how many
+    were skipped instead of quietly diffing the rest.
+  - `flecto history` printed `0 changes` for the first snapshot of a file — a
+    result that was never computed. First snapshots now read as
+    `baseline (no earlier snapshot to compare against)`, and a listing with no
+    comparisons in it says so.
+  - `flecto report` said "No semantic changes from the previous snapshot" on
+    cards that had no previous snapshot. Those now name themselves as first
+    snapshots, the summary gains a **Comparisons** tile beside **Changes**, and a
+    report in which nothing was compared carries a banner saying so above the
+    fold.
+  - `flecto ci` already failed closed on a missing baseline, but did it with a
+    raw `ENOENT` on a hashed filename. The error now names both ways out —
+    save a snapshot, or pass `--snapshot-ref <git-ref>`.
+
+  The shared snapshot store the issue also asks for is not part of this change;
+  what is fixed here is every consumer's answer when the history is empty.
+
+- **Symlinked targets could read files from outside the repository** ([#121]).
+  A pull request adding a config file that is a symlink out of the checkout had
+  that file parsed and its **values** emitted — into the job log, the JSON
+  envelope, and the `--format pr-comment` markdown that `--pr-comment-post`
+  writes to a comment on the pull request. The attacker never controls the
+  linked-to file, which is what makes it worth reading: on a CI runner that
+  includes `~/.npmrc`, `~/.docker/config.json`, and `~/.aws/credentials` — which
+  is INI, and parses perfectly. Opening a pull request is the whole attack.
+
+  Every resolved target, and `.flecto-snapshots/` before a snapshot is written,
+  is now checked for escape rather than for location, so the legitimate cases are
+  untouched: a link that stays inside the project still resolves, and a path
+  *named* from outside the project (`flecto compare /a.yaml /b.yaml`) is operator
+  intent. Only a path inside the project that resolves out of it is refused —
+  loudly, naming `FLECTO_ALLOW_SYMLINK_TARGETS=1` for a checkout that links
+  config in from a sibling directory on purpose.
+
+- **Prototype pollution in the INI parser** ([#121]). A `.ini` file containing a
+  `[__proto__]` section wrote every key in that section onto `Object.prototype`
+  for the rest of the process: `parseIni` looked the section up as
+  `out[section]`, which resolves to `Object.prototype` for that name — and
+  `Object.prototype` passes `isPlainObject`, because its own prototype is
+  `null`, so the existing guard did not catch it.
+
+  The blast radius went past the attacker's own file. `severityRemap[rule.id]`
+  is a plain-object lookup, so `dangerous-toggle-enabled=off` under
+  `[__proto__]` silenced that rule for **every file in the same run**, turning a
+  failing `flecto ci --fail-on error` green. Config file contents are
+  attacker-controlled on a pull request, which is the case `flecto ci` exists
+  to run in.
+
+  Sections are now read with `Object.hasOwn` and every key written with
+  `Object.defineProperty`, so a reserved name is an ordinary own key holding
+  ordinary data — and stays *visible* in the diff, rather than being dropped.
+  Two same-class sites were hardened alongside it, neither exploitable: the
+  masking walk in `src/renderer.js` and the copy loops in `src/encrypted.js`
+  moved a `__proto__` subtree onto the result's prototype, dropping the key from
+  the output instead of rendering it. Both now rebuild with
+  `Object.fromEntries`.
+
+  Found by the fuzz harness added in [#150] on its first full-length run.
+
+- **A `flecto-ignore-next-line` that resolves to nothing now says so** ([#158]).
+  A directive on an array element, in a multi-document YAML file, or in a file
+  type with no comment syntax at all was accepted, resolved to no path, matched
+  nothing, and produced no output — the operator believed a finding was accepted
+  and had no way to learn otherwise. Every such directive now warns on stderr,
+  naming the file, the line, and `--baseline` as the way to accept the finding.
+
+  A warning rather than an error, deliberately: the case already fails closed,
+  because the finding the directive meant to accept still fires and still gates
+  the build. Failing it a second time adds nothing the first failure did not
+  already say. What was missing was the signal, not the gate. (The
+  mandatory-reason check stays a hard error — there, a suppression *would* have
+  hidden a finding, with no justification recorded.)
+
+- Adding a second YAML document beside an existing one no longer re-paths the
+  whole file. A lone Kubernetes-shaped document (`apiVersion` + `kind` +
+  `metadata.name`) is now keyed by identity — `kind/namespace/name` — exactly as
+  it is inside a multi-document file, so a `Service` added next to a `Deployment`
+  reads as one addition instead of reporting the untouched Deployment as removed
+  and re-added. Ordinary single-document YAML (anything without both
+  `apiVersion` and `kind`) is unchanged. ([#124])
+
+  **Migration:** paths for a *single*-document manifest change from bare
+  (`spec.replicas`) to identity-prefixed (`Deployment/prod/api.spec.replicas`).
+  Snapshots and CI baselines taken of a single manifest before this release will
+  show one-time churn on the next diff; `--ignore` entries and custom pack path
+  regexes written against the bare paths need the prefix. Multi-document files
+  and non-manifest config are unaffected.
+
+- `flecto policies test` now resolves packs installed by `flecto policies add`.
+  The harness searched only the fixture directory's `policies/`, while
+  `policies add` writes to the invoking project's — so the two commands added in
+  the same release did not compose. A fixture's own `policies/` still wins, so
+  self-contained fixtures are unaffected; the project is a fallback. The
+  "unknown pack" error now names every directory it searched instead of
+  suggesting a path that already existed. ([#114])
+
+- **`--snapshot-ref <git-ref>` no longer fails on Windows** ([#148]). The
+  repository-relative path is derived by comparing `git rev-parse
+  --show-toplevel` against the file's own path, and Windows spells one directory
+  two ways: git reports the long form, while `os.tmpdir()` and many shells hand
+  Flecto the 8.3 short form (`C:\Users\RUNNER~1\...`). Node's JS `realpathSync`
+  reconciles neither, so the two compared as different directories and the
+  computed relative path climbed out of the repository — `git show` then failed
+  on a file that was plainly tracked. Canonicalization now prefers
+  `realpathSync.native`, which asks the OS for the final path and so resolves
+  short names and normalizes case. Linux and macOS are unaffected: the two calls
+  agree for any path that exists. Found by the new Windows runner.
+
+- **Glob patterns written with Windows separators now match** ([#148]).
+  `resolveFiles` passed user patterns straight to `fast-glob`, which requires
+  POSIX separators and reads `\\` as an escape character — so on Windows
+  `config\\*.yaml` asked for a file literally named `config*.yaml`, matched
+  nothing, and reported `No files matched`, blaming the user for a platform bug.
+  Since PowerShell and cmd tab-completion produce backslash paths, that was the
+  default way a Windows user would invoke Flecto.
+
+  Patterns are now rewritten to POSIX separators **on Windows only** — on Linux
+  and macOS a backslash is a legal filename character and a meaningful glob
+  escape, so rewriting there would break patterns that work today. `exclude`
+  patterns get the same rewrite, since an exclude that silently stops excluding
+  widens what Flecto reports on. Resolved paths stay native.
+- **`ci --format json` no longer truncates at 64 KB through a pipe** ([#155]).
+  Output was printed with `console.log` and followed immediately by
+  `process.exit()`, which does not flush a pending write — and Node writes to a
+  pipe asynchronously. Everything past the 64 KB pipe buffer was dropped, and
+  the command still exited with its normal status.
+
+  Redirecting to a file hid it, because Node writes to a file descriptor
+  synchronously. It appeared only through a pipe — which is how every consumer
+  that matters reads it: `| jq`, `$(...)` capture, and any CI harness collecting
+  stdout.
+
+  A truncated envelope stream that exits normally is the worst shape for a
+  consumer: it reads as a clean run over fewer files rather than as a failure.
+  With `ndjson` it is quieter still, since every line before the cut is valid
+  JSON, so a line-by-line reader consumes a clean prefix and never learns the
+  rest existed.
+
+  Affected `ci`, `plan`, and `diff`/`compare` on `--format json`, `ndjson`,
+  `sarif`, and `github-annotations`. A truncated SARIF document is rejected
+  outright by `upload-sarif`, but only after the gate has already reported
+  success. `--format pr-comment` was never affected — its body is capped at
+  60,000 characters to fit GitHub's comment limit, which lands under one pipe
+  buffer.
+
+### Security
+
+- **Two denial-of-service vectors fixed, found while resuming the 3.0 security
+  review** ([#121]). (1) Secret detection (`src/secrets.js`), which runs on every
+  changed string value under the `default` pack, had two `O(n²)` regexes — the
+  PEM private-key and URL-credential patterns — so a single ~500 KB value in a
+  pull request could hang the CI job. Both are now linear; 1 MB scans in under a
+  second, and detection of real (including unterminated) keys is unchanged. (2) A
+  YAML alias bomb ("billion laughs") — a few hundred bytes of nested aliases that
+  `normalizeParsedValue` expanded into an exponentially large tree — now fails
+  fast against a node budget instead of exhausting memory. Regression tests for
+  both in `test/security.test.js`. The review's findings and its "checked, solid"
+  list are recorded in [docs/security-review.md](docs/security-review.md); a
+  residual limitation (attacker-supplied regexes in custom packs, which Node
+  cannot time out) is noted in [SECURITY.md](SECURITY.md).
+
+- **Terraform plan JSON is refused by every command except `flecto plan`.**
+  Terraform's `before_sensitive` / `after_sensitive` redaction is applied only by
+  `flecto plan`; a plan file is ordinary JSON, so `ci`, `watch`, `compare`,
+  `report`, and snapshot writes read it as a plain config tree and printed the
+  values Terraform itself refuses to print. `--mask-secrets` was not a backstop —
+  it fires on the attribute *name*, and `user_data` does not match. Realistic
+  ways to hit it: `flecto ci "**/*.json"`, a committed `tfplan.json`, or
+  `.flectorc` `files` patterns that sweep JSON. Those commands now fail with a
+  pointer to `flecto plan`, mirroring the guard `flecto plan` already had in the
+  other direction. ([#113])
+
 ## [3.0.1] - 2026-08-07
 
 ### Security
@@ -503,7 +1037,9 @@ fixed — those runs were never actually gated — but the failure is new.
 - Misconfigured policy packs/plugins cause `watch` to exit non-zero instead of
   continuing with no policies.
 
-[Unreleased]: https://github.com/myselfsiddharth/Flecto/compare/v3.0.1...HEAD
+[Unreleased]: https://github.com/myselfsiddharth/Flecto/compare/v3.1.0...HEAD
+[3.1.0]: https://github.com/myselfsiddharth/Flecto/compare/v3.0.2...v3.1.0
+[3.0.2]: https://github.com/myselfsiddharth/Flecto/compare/v3.0.1...v3.0.2
 [3.0.1]: https://github.com/myselfsiddharth/Flecto/compare/v3.0.0...v3.0.1
 [3.0.0]: https://github.com/myselfsiddharth/Flecto/compare/v2.1.0...v3.0.0
 [2.1.0]: https://github.com/myselfsiddharth/Flecto/compare/v2.0.0...v2.1.0
@@ -561,6 +1097,36 @@ fixed — those runs were never actually gated — but the failure is new.
 [#108]: https://github.com/myselfsiddharth/Flecto/pull/108
 [#109]: https://github.com/myselfsiddharth/Flecto/issues/109
 [#110]: https://github.com/myselfsiddharth/Flecto/issues/110
+[#122]: https://github.com/myselfsiddharth/Flecto/issues/122
+
+[#121]: https://github.com/myselfsiddharth/Flecto/issues/121
+
+[#119]: https://github.com/myselfsiddharth/Flecto/issues/119
+
+[#118]: https://github.com/myselfsiddharth/Flecto/issues/118
+
+[#120]: https://github.com/myselfsiddharth/Flecto/issues/120
+
+[#123]: https://github.com/myselfsiddharth/Flecto/issues/123
+
+[#124]: https://github.com/myselfsiddharth/Flecto/issues/124
+
+[#113]: https://github.com/myselfsiddharth/Flecto/issues/113
+
+[#114]: https://github.com/myselfsiddharth/Flecto/issues/114
+[#148]: https://github.com/myselfsiddharth/Flecto/issues/148
+[#152]: https://github.com/myselfsiddharth/Flecto/issues/152
+[#151]: https://github.com/myselfsiddharth/Flecto/issues/151
+[#155]: https://github.com/myselfsiddharth/Flecto/issues/155
+[#139]: https://github.com/myselfsiddharth/Flecto/issues/139
+[#137]: https://github.com/myselfsiddharth/Flecto/issues/137
+[#149]: https://github.com/myselfsiddharth/Flecto/issues/149
+[#158]: https://github.com/myselfsiddharth/Flecto/issues/158
+[#159]: https://github.com/myselfsiddharth/Flecto/issues/159
+[#150]: https://github.com/myselfsiddharth/Flecto/issues/150
+[#125]: https://github.com/myselfsiddharth/Flecto/issues/125
+[#141]: https://github.com/myselfsiddharth/Flecto/issues/141
 [Keep a Changelog]: https://keepachangelog.com/en/1.1.0/
+[#138]: https://github.com/myselfsiddharth/Flecto/issues/138
 [Semantic Versioning]: https://semver.org/spec/v2.0.0.html
 [GHSA-wq8m-fc3q-8m5x]: https://github.com/myselfsiddharth/Flecto/security/advisories/GHSA-wq8m-fc3q-8m5x

package/README.md

@@ -200,6 +200,9 @@ steps:
   - uses: myselfsiddharth/Flecto/.github/actions/flecto-pr-risk@main
 ```
 
+GitLab and Bitbucket work the same way — Flecto detects the host from CI
+variables, or `--pr-provider` forces one. See [CI](docs/ci.md#providers).
+
 A fork's pull request gets a read-only token, so the comment is skipped with a
 warning there — the check itself still runs and still fails on risky changes.
 
@@ -260,7 +263,10 @@ flecto history config/prod.yaml --limit 10
 ```
 
 Snapshots stay on your machine in `.flecto-snapshots/`. Nothing is uploaded and
-no account is required. → **[CLI reference](docs/cli-reference.md#flecto-history-files)**
+no account is required. To read the same history on a CI runner, save it to the
+git-tracked store instead — `--snapshot-store shared` writes a committable
+`.flecto/snapshots/`, masking secret-like values into digests as it goes.
+→ **[CLI reference](docs/cli-reference.md#flecto-history-files)**
 
 ### Share what changed before the incident
 
@@ -370,6 +376,7 @@ services doesn't read as a wall of changes.
 | `node-runtime` | Dropped engine requirements, TLS verification bypasses, debug/inspector flags |
 | `terraform` | Replaced and destroyed stateful resources, ingress opened to `0.0.0.0/0`, IAM wildcards, public S3, capacity jumps |
 | `sops` | Decryption recipients added or removed, a MAC that moved on its own, a file that stopped being encrypted |
+| `github-actions` | Changed workflow triggers, widened permissions, self-hosted runners, unpinned actions, pull-request head checkout, and secrets interpolated into `run` |
 
 ```bash
 flecto policies list          # see what resolves here, built-in and local
@@ -401,13 +408,18 @@ and runs no code from the package. →
 
 | Format | Extensions |
 |---|---|
-| JSON | `.json` |
+| JSON / JSONC | `.json`, `.jsonc` |
 | YAML | `.yaml`, `.yml` |
 | TOML | `.toml` |
 | INI | `.ini` |
 | dotenv | `.env`, `.env.*`, `*.env` |
 | age (armored) | `.age`, or any file whose contents are one armored blob |
 
+`.json` accepts comments and trailing commas, so `tsconfig.json`,
+`.vscode/settings.json`, `jsconfig.json`, and `devcontainer.json` are read as
+written. →
+**[JSON with comments](docs/configuration.md#json-with-comments)**
+
 Terraform plan JSON (`terraform show -json`) is read by **`flecto plan`**, which
 applies Terraform's own sensitivity marking. Point `plan` at it rather than `ci`
 or `watch` — those treat it as ordinary JSON and will print values Terraform
@@ -511,6 +523,7 @@ Explicit CLI flags win over profiles, which win over `defaults`.
 | **[Configuration](docs/configuration.md)** | `.flectorc`, profiles, ignore patterns, array identity, masking |
 | **[Encrypted files](docs/encrypted-files.md)** | SOPS and age: what is detected, what is reported, why nothing is decrypted |
 | **[CI](docs/ci.md)** | Baselines, fail triggers, output formats, the bundled GitHub Actions |
+| **[Performance](docs/performance.md)** | Where time goes at scale, and how much smaller a diff is than the config |
 | **[Kubernetes](docs/kubernetes.md)** | Diffing rendered Helm/Kustomize manifests before they reach a cluster |
 | **[Terraform plans](docs/terraform.md)** | Reviewing `terraform show -json` output and the `terraform` pack |
 | **[Webhooks and commands](docs/webhooks.md)** | Envelope shape, delivery modes, command environment |