flecto 4.1.0 → 4.2.0

package/CHANGELOG.md

@@ -7,6 +7,125 @@ The format is based on [Keep a Changelog], and this project adheres to
 
 ## [Unreleased]
 
+## [4.2.0] - 2026-10-05
+
+The first npm release since 4.1.1. The `v4.1.2` tag moved the documented Action
+pins but its npm publish failed (the version was never bumped), so the fixes
+below reach npm for the first time here.
+
+### Added
+
+- **`--new-files added`: a pull request that adds a config file no longer has to
+  fail the gate.** `flecto ci --snapshot-ref` stopped with "Failed to resolve
+  snapshot baseline" whenever a target was not in the base commit, so any PR
+  that added a values file or a manifest matched by the gate's glob went red,
+  whatever `--fail-on` said. With `--new-files added` (Action input
+  `new-files: added`), such a file is reported as new, every key `added`, and
+  policies still run on it.
+
+  The default is unchanged and still fails closed, and the error now names the
+  flag. A renamed file looks exactly like a new one, and would turn every
+  `changed` into an `added`, which the Action's `policy,error` does not gate,
+  so this is opt-in and refused from `.flectorc`, as `snapshotRef` is.
+
+  Found by replaying Flecto over a real repository's infra history, where one
+  commit in twelve added a values file.
+
+### Changed
+
+- **`KEY=VALUE` lists diff by KEY, so one inserted variable is one addition**
+  ([#226]). Compose writes `environment`, `labels` and `build.args` as a map or
+  as a list of `KEY=VALUE` strings, and means the same by both. The list form
+  diffed by position: a real pull request that inserted ten `OIDC_*` variables
+  read as 31 `changed` rows, each pairing two unrelated variables. It now reads
+  as 9 additions under `environment["OIDC_ISSUER_URL"]` and so on, and the
+  language server places diagnostics on the right line.
+
+  Paths for these lists change from `environment[3]` to `environment["KEY"]`.
+  `--no-array-id` restores index paths. A list counts only when every item is a
+  `KEY=VALUE` or bare `KEY` with unique keys and at least one `=`, so `command:
+  [python, app.py]` and `args: [--a=1]` keep their order-sensitive diff.
+
+[#226]: https://github.com/myselfsiddharth/Flecto/issues/226
+
+### Fixed
+
+- **A connection string whose password is a reference is no longer reported as
+  a leaked credential** ([#225]). `postgres://app:$(DB_PASSWORD)@db/app`, the
+  Kubernetes form of env-var expansion, and `{{ .Values.x }}` Helm expressions
+  were flagged `url-credentials` (error), although `${DB_PASSWORD}` already
+  was not. A literal password in the same position is still caught. Found on
+  a real repository's ConfigMap during outreach.
+
+- **The symlinked-baseline check never fired below the repository root.** It
+  asked `git ls-tree` for a root-relative path from inside the file's own
+  directory, so for `config/app.yaml` it looked up `config/config/app.yaml`,
+  found nothing, and let the baseline through as the link's target path. Only
+  files at the root were protected.
+
+- **Pointing Flecto at a Helm chart says so, instead of reporting broken YAML**
+  ([#210]). `flecto ci "helm/**/*.yaml"` is the first thing a Helm user tries,
+  and it failed with a syntax error pointing inside a chart template that is
+  perfectly valid — sending them to debug their chart rather than their command.
+
+  A YAML file that **fails to parse** and carries Go template delimiters now
+  reports what it is and the two ways to read it: render the chart, or point at
+  `values.yaml`. The check runs only after a parse failure, so valid YAML
+  holding `{{ ... }}` in a string — a Prometheus alert rule, say — is untouched.
+
+  Found by running Flecto against real repositories instead of our own fixtures.
+
+- **`flecto ci --format human` now explains itself** ([#211], fixed by
+  [@DYNOSuprovo](https://github.com/DYNOSuprovo) in [#212]). `human` is the
+  default for `plan` and `compare` and what `watch` prints, so reaching for it on
+  `ci` is the natural mistake — especially when running `ci` locally to see what
+  the gate will say. The old error listed the valid values without saying that
+  `human` was deliberately excluded, so it read as a typo or an inconsistency. It
+  now names the reason and both ways out: `pr-comment` to read a run, `json` to
+  parse it. An actual typo still gets the list.
+
+- **A command killed by a signal is a failed delivery, not a success**
+  ([#185], fixed by [@nova-loop](https://github.com/nova-loop) in [#214]).
+  `watch --command` checked only the exit code, which is `null` when a signal
+  ends the process, so an OOM-killed or timed-out hook counted as delivered:
+  `--on-alert-failure` never fired and at-least-once deliveries were marked done.
+  The warning now names the signal.
+
+[#210]: https://github.com/myselfsiddharth/Flecto/issues/210
+[#185]: https://github.com/myselfsiddharth/Flecto/issues/185
+[#211]: https://github.com/myselfsiddharth/Flecto/issues/211
+[#212]: https://github.com/myselfsiddharth/Flecto/pull/212
+[#214]: https://github.com/myselfsiddharth/Flecto/pull/214
+[#225]: https://github.com/myselfsiddharth/Flecto/issues/225
+
+## [4.1.1] - 2026-09-29
+
+### Fixed
+
+- **The root `action.yml` description was too long to list on the Marketplace.**
+  GitHub rejects a listing whose description is 125 characters or more; 4.1.0
+  shipped 194. It is now 119, and a test pins the limit — the constraint is not
+  in GitHub's metadata-syntax documentation and the publish form only reports it
+  at publish time, by which point the release is already cut.
+
+  The rest of the pitch — that Flecto never runs `terraform`, `helm`, or `sops`,
+  and never decrypts — lives in the README, which has room for it.
+
+- **Documented Action pins moved from `@v4.0.0` to `@v4.1.0`.** Tags are
+  immutable, and the fix that stopped the bundled Actions installing the pre-4.0
+  CLI shipped *in* 4.1.0 — so while the examples said `@v4.0.0` they pointed at a
+  tag whose `flecto-ci` and `flecto-pr-risk` still run `flecto@3`, the line
+  exposed to the baseline-shadowing bypass 4.0 closed.
+
+  **If you pinned `@v4.0.0` following an earlier example, repin to `@v4.1.0`.**
+  The CLI at `flecto@4.0.0` is fine; it is only the bundled Action metadata at
+  that tag that is not. [docs/ci.md](docs/ci.md#pinning) now warns against it.
+
+  [RELEASE.md](RELEASE.md) gained a step that repins the documented Actions as
+  part of every release. That step is the real fix — the bug was not the pin, it
+  was that nothing tied the documented pin to the release that fixed what it
+  pointed at.
+
 ## [4.1.0] - 2026-09-29
 
 ### Added
@@ -1292,7 +1411,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/v4.1.0...HEAD
+[Unreleased]: https://github.com/myselfsiddharth/Flecto/compare/v4.2.0...HEAD
+[4.2.0]: https://github.com/myselfsiddharth/Flecto/compare/v4.1.1...v4.2.0
+[4.1.1]: https://github.com/myselfsiddharth/Flecto/compare/v4.1.0...v4.1.1
 [4.1.0]: https://github.com/myselfsiddharth/Flecto/compare/v4.0.0...v4.1.0
 [4.0.0]: https://github.com/myselfsiddharth/Flecto/compare/v3.1.0...v4.0.0
 [3.1.0]: https://github.com/myselfsiddharth/Flecto/compare/v3.0.2...v3.1.0

package/README.md

@@ -1,192 +1,103 @@
-<p align="center">
-  <img src="docs/assets/flecto-hero.png" alt="Flecto — semantic config watcher" width="920"/>
-</p>
-
 <h1 align="center">Flecto</h1>
 
 <p align="center">
-  <strong>Know what your config actually changed — and whether it's risky.</strong>
+  <strong>Flecto reads your Terraform plan and Kubernetes changes and posts a
+  plain-English risk summary on every pull request, blocking the dangerous ones.</strong>
 </p>
 
 <p align="center">
+  <a href="https://github.com/marketplace/actions/flecto-pr-risk"><img alt="GitHub Marketplace" src="https://img.shields.io/badge/marketplace-Flecto%20PR%20Risk-34d399?style=flat-square&logo=github&labelColor=0b1220"/></a>
   <a href="https://www.npmjs.com/package/flecto"><img alt="npm" src="https://img.shields.io/npm/v/flecto?style=flat-square&color=34d399&labelColor=0b1220"/></a>
   <a href="https://github.com/myselfsiddharth/Flecto/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/myselfsiddharth/Flecto/ci.yml?branch=main&style=flat-square&label=CI&labelColor=0b1220"/></a>
   <a href="LICENSE"><img alt="MIT" src="https://img.shields.io/badge/license-MIT-8fa3bf?style=flat-square&labelColor=0b1220"/></a>
   <a href="#documentation"><img alt="Docs" src="https://img.shields.io/badge/docs-read-34d399?style=flat-square&labelColor=0b1220"/></a>
 </p>
 
-<p align="center">
-  <img src="docs/assets/demo-watch.svg" alt="Flecto reporting semantic config changes in the terminal" width="920"/>
-</p>
-
----
-
-Config drives the parts of a system that break loudest: connection pools, feature
-flags, TLS, retries, secrets. But we still review it as text — so a reordered key
-looks identical to a doubled pool size, and `debug: true` slips through in a
-40-line formatting diff.
-
-Flecto reads config as structure, not lines. It tells you what changed in plain
-English, flags what looks risky, and gives you an exit code to gate on.
-
-| Reviewing config without Flecto | With Flecto |
-|---|---|
-| `+ 40 lines of YAML noise` | `~ database.pool_size: 5 → 20` |
-| Hope someone notices `debug: true` | Policy finding → build fails |
-| "Something in `.env` changed" | The exact keys, with secrets masked |
-
-The same engine reads whatever your change actually lives in:
-
-| You are reviewing | Flecto reads |
-|---|---|
-| App config — YAML, JSON, TOML, INI, dotenv | the files directly |
-| A Terraform change | `terraform show -json` output, via `flecto plan` |
-| A Kubernetes change | rendered manifests from `helm`, `kustomize`, or anything else |
-| A SOPS-encrypted file | its structure and recipients — **never its plaintext** |
-
-It never invokes `terraform`, `helm`, `kustomize`, `sops`, or `age`, so nothing
-extra has to exist on the CI runner.
-
----
-
-## Install
-
-```bash
-npm install -g flecto
-```
-
-Requires **Node.js 20.19.0+**. Verify:
-
-```bash
-flecto --version
-flecto doctor
-```
-
-Prefer not to install globally? Every example below works with
-`npx --yes flecto@4` instead of `flecto`.
-
 ---
 
-## Quick start
-
-A complete walkthrough, start to finish. Copy-paste it anywhere.
-
-**1. Create a config file to track.**
-
-```bash
-mkdir flecto-demo && cd flecto-demo && mkdir config
-cat > config/prod.yaml <<'EOF'
-database:
-  host: db.internal
-  pool_size: 5
-  ssl: true
-logging:
-  level: info
-  debug: false
-EOF
-```
+## What lands on the pull request
 
-**2. Save it as your baseline.**
+<p align="center">
+  <img src="docs/assets/flecto-pr-comment.png" alt="Flecto's comment on a pull request: check failing, six policy errors naming an IAM wildcard, a disabled S3 public-access block, and security group ingress opened to 0.0.0.0/0" width="960"/>
+</p>
 
-```bash
-flecto watch config/prod.yaml --snapshot
-```
+That is a real comment on a
+**[real pull request](https://github.com/myselfsiddharth/flecto-example-terraform/pull/1)**
+you can open right now. The PR says it is about partner access and changes eight
+lines; it opens the web tier to the internet, turns off the bucket's
+public-access protection, and widens an IAM policy to `s3:*` on `*`.
 
-```
-✓ Snapshot saved: /path/to/flecto-demo/.flecto-snapshots/4b8cbbd70d1832a2.json
-```
+One sticky comment, updated in place on every push. Exit code `1`, so the build
+fails before the change ships.
 
-**3. Make the kind of edit that causes incidents.**
-
-```bash
-cat > config/prod.yaml <<'EOF'
-database:
-  host: db.internal
-  pool_size: 20
-  ssl: true
-logging:
-  level: info
-  debug: true
-EOF
-```
+**[The same gate on an ordinary change](https://github.com/myselfsiddharth/flecto-example-terraform/pull/2)**
+reports *no findings* and passes. That matters as much: a check that fires on
+everything gets uninstalled in a week.
 
-**4. Ask what changed.**
+<details>
+<summary>The same report as text, and what a plan with existing state adds</summary>
 
-```bash
-flecto watch config/prod.yaml --diff
-```
+The comment above, as `flecto plan` prints it:
 
 ```
-/path/to/flecto-demo/config/prod.yaml — 2 changes from snapshot:
-  ~ database.pool_size: 5 → 20
-  ~ logging.debug: false → true
-```
+❌ Check failing — 30 changes in 1 file — 0 changed, 30 added, 0 removed.
+Policy: 6 errors.
 
-Two sentences instead of a diff you have to interpret. Now let Flecto judge it:
+aws_security_group.web.ingress[0].cidr_blocks[0]
+  terraform-security-group-open-ingress
+  Security group ingress will accept traffic from the whole internet
+  (0.0.0.0/0). Restrict the source to a known CIDR, a prefix list, or
+  another security group.
 
-```bash
-flecto ci config/prod.yaml --format github-annotations
-```
+aws_s3_bucket_public_access_block.uploads.block_public_acls        (+3 more)
+  terraform-s3-public-access-block-disabled
+  S3 public access block is being turned off or removed.
 
+aws_iam_role_policy.app.policy
+  terraform-iam-wildcard
+  IAM policy grants a wildcard action or resource ("*").
 ```
-::warning title=flecto changed::database.pool_size
-::warning title=flecto changed::logging.debug
-::warning title=flecto policy pool-size-jump [default]::database.pool_size: Pool size increased from 5 to 20 (>=2x).
-::error title=flecto policy dangerous-toggle-enabled [default]::logging.debug: Potentially dangerous toggle enabled.
-```
-
-Exit code `1`. In CI, that's a failed build — before the change ships.
 
-**5. Watch it live.** Leave this running and edit the file in another window:
+The example repository has no Terraform state, so every resource shows as
+`create`. With existing state, a plan that replaces a database also reports:
 
-```bash
-flecto watch config/prod.yaml
 ```
-
-```
-flecto watching /path/to/flecto-demo/config/prod.yaml
-Press Ctrl+C to stop.
-
-[18:24:48] /path/to/flecto-demo/config/prod.yaml — 2 changes
-  ~ database.pool_size: 5 → 20
-  ~ logging.debug: false → true
-  ! policy(warn) [default] database.pool_size: Pool size increased from 5 to 20 (>=2x).
-  ! policy(error) [default] logging.debug: Potentially dangerous toggle enabled.
+aws_db_instance.main.#action
+  terraform-stateful-resource-destroyed
+  Terraform will destroy a stateful resource. Its data does not survive.
+  Take a final snapshot, or add a prevent_destroy lifecycle block, before
+  applying.
 ```
 
-That's the whole product. Everything below is depth.
+</details>
 
 ---
 
-## What you can do with it
+## Add it in 60 seconds
 
-### Catch risky changes before they merge
+Flecto PR Risk is on the
+[GitHub Marketplace](https://github.com/marketplace/actions/flecto-pr-risk), so
+`myselfsiddharth/Flecto@v4.1.2` is the whole reference.
 
-Add one step to your workflow and risky config edits show up as annotations on
-the pull request:
+**Terraform** — point it at the plan JSON:
 
 ```yaml
 permissions:
   contents: read
+  pull-requests: write
 
 steps:
   - uses: actions/checkout@v7
+  - run: |
+      terraform plan -out=tf.plan
+      terraform show -json tf.plan > plan.json
+  - uses: myselfsiddharth/Flecto@v4.1.2
     with:
-      fetch-depth: 2
-  - uses: myselfsiddharth/Flecto/.github/actions/flecto-ci@v4.0.0
-    with:
-      targets: config/**/*.{yaml,yml,json,toml,ini}
-      snapshot-ref: HEAD~1
+      terraform-plan: plan.json
+      fail-on: error
 ```
 
-Prefer a summary nobody can miss? `--format pr-comment` renders the changes and
-policy findings as markdown and, when you opt in with `--pr-comment-post` inside
-a GitHub PR run, keeps **one** sticky comment up to date instead of adding a new
-one per push. Without that flag it just prints the markdown, so it can't post
-from your laptop.
-
-The `flecto-pr-risk` Action is that, packaged — the whole adoption is one
-`uses:`, with the baseline resolved from the pull request rather than `HEAD~1`:
+**Kubernetes** — render your manifests, then diff them against the PR's base:
 
 ```yaml
 permissions:
@@ -197,324 +108,64 @@ steps:
   - uses: actions/checkout@v7
     with:
       fetch-depth: 0
-  - uses: myselfsiddharth/Flecto/.github/actions/flecto-pr-risk@v4.0.0
-```
-
-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.
-
-Works on any CI runner — it's a plain CLI with meaningful exit codes.
-→ **[CI guide](docs/ci.md)**
-
-### Trigger automation on change
-
-Restart a service, reload a process, or notify an endpoint whenever config moves:
-
-```bash
-flecto watch .env --command "docker-compose restart app"
-
-flecto watch config/prod.yaml \
-  --webhook https://hooks.example.com/notify \
-  --delivery-mode at-least-once
-```
-
-Changes arrive as a versioned JSON envelope, and `at-least-once` persists and
-retries failed deliveries.
-
-Posting straight to chat needs no receiver of your own — `--webhook-format`
-shapes the body for Slack, Discord, or Teams, colored by the highest policy
-severity:
-
-```bash
-flecto watch config/prod.yaml \
-  --webhook "https://hooks.slack.com/services/T000/B000/XXXX" \
-  --webhook-format slack
-```
-
-→ **[Webhooks and commands](docs/webhooks.md)**
-
-### Compare two environments
-
-"Works in staging, fails in prod" is usually one key apart:
-
-```bash
-flecto compare config/prod.yaml config/staging.yaml
-```
-
-```
-"+" exists only in the compared file, "-" only in the baseline, "~" differs
-/path/to/config/staging.yaml — 2 changes from /path/to/config/prod.yaml:
-  - only_in_prod: true
-  ~ database.pool_size: 5 → 20
-  ! policy(warn) [default] database.pool_size: Pool size increased from 5 to 20 (>=2x).
-```
-
-The first file is the baseline, the files don't have to share a format, and
-`--format json` gives you the same output `flecto ci` produces.
-→ **[CLI reference](docs/cli-reference.md#flecto-compare-filea-fileb)**
-
-### Track drift over time
-
-```bash
-flecto history config/prod.yaml --limit 10
-```
-
-Snapshots stay on your machine in `.flecto-snapshots/`. Nothing is uploaded and
-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
-
-```bash
-flecto report --limit 20 --mask-secrets --output drift.html
-```
-
-One HTML file from that same local history: a timeline per file, every change
-with its UTC timestamp, and policy findings grouped by severity. Fully
-self-contained — inline styles, no fonts, no CDN scripts, no analytics — so you
-can attach it to an incident thread and it renders offline. No server and no
-account, same as everything else here.
-→ **[CLI reference](docs/cli-reference.md#flecto-report-files)**
-
-### Review a Kubernetes change before it reaches a cluster
-
-ArgoCD, Flux, and `helm diff` compare the cluster to the repo — which needs a
-cluster, and an apply that already happened. Flecto compares the manifests *this
-pull request would produce* against the ones `main` produces:
-
-```bash
-helm template api ./charts/api -f values/prod.yaml > /tmp/head.yaml
-flecto compare /tmp/base.yaml /tmp/head.yaml --policies kubernetes --fail-on error
-```
-
-```
-~ Service/prod/api.spec.type: "ClusterIP" → "LoadBalancer"
-  ! policy(error) [kubernetes] Service type is LoadBalancer, which exposes the
-    workload outside the cluster. Confirm the exposure is intended.
-```
-
-Multi-document YAML is keyed by `kind/namespace/name`, so findings name the
-resource. Flecto never runs `helm` or `kustomize` — you render, it diffs, so any
-renderer works and no binary is needed in CI.
-→ **[Kubernetes](docs/kubernetes.md)**
-
-### Read a Terraform plan in plain English
-
-`terraform plan` output is precise and long. Flecto turns it into the handful of
-lines a reviewer actually needs to argue about:
-
-```bash
-terraform show -json plan.tfplan > plan.json
-flecto plan plan.json --fail-on error
-```
-
-```
-plan.json — plan format 1.2
-Plan: 0 to add, 1 to change, 0 to destroy, 1 to replace.
-  ~ aws_security_group.web.ingress[0].cidr_blocks[0]: "10.0.0.0/8" → "0.0.0.0/0"
-  - aws_db_instance.main.#action: "replace" [terraform will destroy and recreate aws_db_instance.main]
-  ~ aws_db_instance.main.password: "(sensitive value)" → "(sensitive value)" [sensitive]
-  ! policy(error) [terraform] …cidr_blocks[0]: Security group ingress will accept
-    traffic from the whole internet (0.0.0.0/0). Restrict the source to a known CIDR…
-  ! policy(error) [terraform] …#action: Terraform will destroy a stateful resource.
-    Its data does not survive. Take a final snapshot, or add a prevent_destroy…
-```
-
-A **replace reads as a removal**, not a benign update — a recreated database
-should never look like a config tweak. Values Terraform marks sensitive are
-redacted during parsing, before the policy engine or any formatter sees them, and
-`after_unknown` renders as `(known after apply)` rather than `null`.
-
-**Flecto never runs `terraform`** — you produce the JSON, it reads it, so nothing
-extra has to exist on the CI runner.
-→ **[Terraform plans](docs/terraform.md)**
-
-### Encode your own rules
-
-Beyond the built-in packs, write rules as declarative JSON or YAML — no code:
-
-```json
-{
-  "id": "risky-feature-enable",
-  "severity": "error",
-  "allOf": [
-    { "match": { "pathPrefix": "features." } },
-    { "afterTruthy": true }
-  ]
-}
-```
-
-For anything a predicate can't express, a local ESM plugin exporting
-`evaluate(changes, ctx)` gets the full change set.
-→ **[Writing policy packs](docs/policy-packs.md)** · **[Plugins](docs/plugins.md)**
-
-### Cut the noise
-
-```bash
-flecto watch config/prod.yaml --ignore "updated_at,**.meta.timestamp"
+  - run: helm template ./chart > rendered.yaml
+  - uses: myselfsiddharth/Flecto@v4.1.2
+    with:
+      targets: rendered.yaml
+      policies: kubernetes
 ```
 
-Arrays of objects are matched by `id` or `name`, so reordering a list of named
-services doesn't read as a wall of changes.
-→ **[Configuration](docs/configuration.md)**
+Flecto **never invokes** `terraform`, `helm`, `kustomize`, `sops`, or `age`, so
+nothing extra has to exist on the runner. → **[CI guide](docs/ci.md)**
 
 ---
 
-## Built-in policy packs
-
-| Pack | Catches |
-|---|---|
-| `default` | Secret-like keys added or changed, secret-shaped *values* under any key, dangerous toggles, pool-size jumps |
-| `strict-prod` | The same ground, with production-grade severities and matching |
-| `compose` | Privileged services, host networking, Docker socket mounts, sensitive bind mounts |
-| `kubernetes` | Privileged containers, host namespaces, weakened `runAsNonRoot`, added `SYS_ADMIN`, unpinned images, replica jumps, dropped limits, `LoadBalancer`/`NodePort` exposure |
-| `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
-flecto ci "config/**/*.yaml" --policies "default,strict-prod" --fail-on policy
-```
-
-Pass files or glob patterns, quoted so your shell doesn't expand them first — a
-bare directory is not a valid target.
-
-A local `policies/<id>.json` overrides the built-in pack of the same id, and
-`severityRemap` raises or silences individual rules per profile without forking
-anything. → **[Policy packs](docs/policy-packs.md)**
-
-Community packs ship on npm as `flecto-pack-<id>` packages — a package name and
-one declarative JSON file, nothing else:
-
-```bash
-npm install --save-dev flecto-pack-deployment-safety
-flecto policies add deployment-safety
-```
-
-`policies add` validates the pack, writes it to `policies/deployment-safety.json`,
-and runs no code from the package. →
-**[Installing community packs](docs/policy-packs.md#installing-a-community-pack)**
+## What it catches
+
+- **A database about to be destroyed** — `terraform plan` says `replace`, the
+  diff says the data does not survive
+- **Ingress widened to the world** — `10.0.0.0/8` → `0.0.0.0/0` on a security
+  group
+- **An IAM policy gone wildcard** — `Action: "*"` where it used to be scoped
+- **S3 public-access protection switched off** — the block removed, not just
+  loosened
+- **A container turned privileged**, or `runAsNonRoot` quietly weakened
+- **Resource limits removed** from a Deployment, so one pod can starve a node
+- **An image tag unpinned** — `:1.4.0` → `:latest`
+- **A new recipient on a SOPS file** — someone who could not decrypt it now can
+- **`debug: true` in a 40-line formatting diff**, or a connection pool
+  quadrupled
+
+Rules live in [policy packs](docs/policy-packs.md) you can extend, remap, or
+replace.
 
 ---
 
-## Supported formats
+## Also works as
 
-| Format | Extensions |
+| | |
 |---|---|
-| 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
-marks sensitive ([#113](https://github.com/myselfsiddharth/Flecto/issues/113)).
-
-Multi-document YAML (`---`-separated, the usual shape of a Kubernetes manifest)
-is supported. Each document is diffed under its own key — `kind/name` for
-Kubernetes-shaped documents, so a document inserted at the top of the file does
-not renumber every other path. →
-**[Multi-document YAML](docs/configuration.md#multi-document-yaml)**
-
----
-
-## Encrypted files
-
-A `sops`- or age-encrypted file is detected from its **contents**, and diffed
-structurally:
-
-```
-  + cache: {"ttl_seconds":300}
-  ~ database.password: <encrypted value changed>
-  + sops.age.age1exampleexample…: {"recipient":"age1exampleexample…","enc":"<encrypted value>"}
-```
-
-You get keys added and removed, which encrypted values moved, and — the useful
-part — who can decrypt the file. A recipient added is a genuine security event
-and the `sops` pack raises it as one.
-
-**Flecto never decrypts.** It never shells out to `sops` or `age`, never reads a
-key file or agent socket, and never prints ciphertext — not even without
-`--mask-secrets`. Ciphertext is replaced with an opaque sentinel in the parser,
-so no diff, snapshot, webhook, or report can carry it. →
-**[Encrypted files](docs/encrypted-files.md)**
+| **A CLI** | `flecto ci`, `flecto plan`, `flecto compare` — plain exit codes, any runner → **[CLI reference](docs/cli-reference.md)** |
+| **A file watcher** | `flecto watch` reports changes as you edit → **[Getting started](docs/getting-started.md)** |
+| **A webhook / command trigger** | Restart a service or notify an endpoint on change → **[Webhooks](docs/webhooks.md)** |
+| **An MCP server** | Read-only `diff`, `check`, `explain` tools for agents → **[MCP](docs/mcp.md)** |
+| **An editor language server** | `flecto lsp` — diagnostics while you type → **[Editor](docs/editor.md)** |
+| **A drift detector** | `flecto-drift` compares declared config against what is running → **[Drift](docs/drift.md)** |
 
 ---
 
-## Configuration
-
-Most teams commit a `.flectorc` so local runs and CI agree:
-
-```bash
-flecto init
-```
-
-```json
-{
-  "defaults": {
-    "policies": ["default"],
-    "ignore": ["**.updated_at"]
-  },
-  "profiles": {
-    "dev": { "mode": "verbose" },
-    "ci": { "failOn": "policy,error" },
-    "prod": {
-      "policies": ["default", "strict-prod"],
-      "severityRemap": { "pool-size-jump": "error" },
-      "maskSecrets": true
-    }
-  },
-  "files": ["config/**/*.{yaml,yml,json,toml,ini}", ".env"]
-}
-```
-
-```bash
-flecto watch --profile dev
-flecto ci --profile ci
-```
+## Stability
 
-Explicit CLI flags win over profiles, which win over `defaults`.
-→ **[Full configuration reference](docs/configuration.md)**
+Flecto runs inside your merge path. The **JSON envelope**
+(`schema_version: "2.0"`), **exit codes** (`0` clean, `1` failed — it fails
+closed), **`.flectorc`** keys, and **command and flag names** follow
+[semver](https://semver.org/), and no breaking change to them ships without a
+minor release that warns first. The one exception is a security fix.
 
----
+Terminal output, message wording, and anything under `src/` are deliberately
+**not** stable — parse `--format json`.
 
-## Commands
-
-| Command | What it does |
-|---|---|
-| `flecto watch [files...]` | Watch for changes and print them as they happen |
-| `flecto watch --snapshot` | Save the current state as a baseline |
-| `flecto watch --diff` | Compare against the baseline and exit |
-| `flecto ci [files...]` | One-shot check with a gate-able exit code |
-| `flecto explain [files...]` | Advisory, model-generated narration of the masked diff (opt-in, your own key) |
-| `flecto compare <fileA> <fileB>` | Diff two files against each other (`fileA` is the baseline) |
-| `flecto plan <planFiles...>` | Review `terraform show -json` output and gate on it |
-| `flecto history [files...]` | Summarize drift across local snapshots |
-| `flecto report [files...]` | Render that history as a self-contained HTML file |
-| `flecto policies add <name>` | Install a pack from an `flecto-pack-*` npm package |
-| `flecto policies list` | List available policy packs |
-| `flecto policies test <dir>` | Assert pack and plugin findings from fixtures |
-| `flecto init` | Create a `.flectorc` from detected stack signals |
-| `flecto mcp` | Serve read-only diff/check/explain tools to an agent over MCP |
-| `flecto lsp` | Show findings and changes as diagnostics while a config file is edited |
-| `flecto doctor` | Check setup, config, and environment |
-
-→ **[Every flag, every command](docs/cli-reference.md)**
+→ **[Full stability policy](docs/stability.md)**
 
 ---
 
@@ -522,75 +173,30 @@ Explicit CLI flags win over profiles, which win over `defaults`.
 
 | Guide | Covers |
 |---|---|
-| **[CLI reference](docs/cli-reference.md)** | Every command, flag, and exit code |
-| **[Configuration](docs/configuration.md)** | `.flectorc`, profiles, ignore patterns, array identity, masking |
-| **[Editor diagnostics](docs/editor.md)** | `flecto lsp` setup for Neovim, Helix, Emacs, and where diagnostics land |
-| **[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 |
+| **[Getting started](docs/getting-started.md)** | A full walkthrough, from install to a failing build |
+| **[CI](docs/ci.md)** | Baselines, fail triggers, output formats, the bundled Actions, pinning |
 | **[Terraform plans](docs/terraform.md)** | Reviewing `terraform show -json` output and the `terraform` pack |
+| **[Kubernetes](docs/kubernetes.md)** | Diffing rendered Helm/Kustomize manifests before they reach a cluster |
+| **[Comparison](docs/comparison.md)** | Honest comparison with Checkov, Trivy/tfsec, conftest/OPA, tf-summarize, dyff |
+| **[Supported formats](docs/formats.md)** | YAML, JSON, TOML, INI, dotenv, age — and what each one accepts |
+| **[Encrypted files](docs/encrypted-files.md)** | SOPS and age: what is detected, why nothing is decrypted |
+| **[Configuration](docs/configuration.md)** | `.flectorc`, profiles, ignore patterns, array identity, masking |
+| **[CLI reference](docs/cli-reference.md)** | Every command, flag, and exit code |
+| **[Policy packs](docs/policy-packs.md)** | Writing declarative rules |
+| **[Plugins](docs/plugins.md)** · **[Cookbook](docs/plugin-cookbook.md)** | Rules that need real code |
 | **[Webhooks and commands](docs/webhooks.md)** | Envelope shape, delivery modes, command environment |
 | **[MCP server](docs/mcp.md)** | Read-only diff/check/explain tools for agents, and the security posture |
 | **[Explain](docs/explain.md)** | Opt-in model narration of a diff: what is sent, what it can never do, cost |
-| **[Policy packs](docs/policy-packs.md)** | Writing declarative rules |
-| **[Plugins](docs/plugins.md)** · **[Cookbook](docs/plugin-cookbook.md)** | Rules that need real code |
-| **[Live drift](docs/drift.md)** | `flecto-drift`: comparing a declared config against what is actually running |
+| **[Editor diagnostics](docs/editor.md)** | `flecto lsp` setup for Neovim, Helix, Emacs |
+| **[Live drift](docs/drift.md)** | `flecto-drift`: declared config versus what is actually running |
+| **[Performance](docs/performance.md)** | Where time goes at scale |
+| **[Stability](docs/stability.md)** | What you can build against, and the deprecation sequence |
 | **[Troubleshooting](docs/troubleshooting.md)** | When something doesn't behave |
-| **[Stability](docs/stability.md)** | What you can build against, what you cannot, and the deprecation sequence |
-| **[Migrating to 4.0](docs/migrating-to-4.md)** | The five breaking changes, and how to tell whether they affect you |
+| **[Migrating to 4.0](docs/migrating-to-4.md)** | The five breaking changes, and whether they affect you |
 | **[Changelog](CHANGELOG.md)** | Release history and migration notes |
 
 ---
 
-## How it works
-
-1. **Parse** — format detected by extension or dotenv naming → structured values
-2. **Watch** — [chokidar](https://github.com/paulmillr/chokidar) with debounce
-3. **Diff** — semantic tree comparison with ignore rules and array identity
-4. **Evaluate** — policy packs and plugins → severity-tagged findings
-5. **Emit** — a versioned envelope (`schema_version: "2.0"`)
-6. **Deliver** — terminal output, shell command, webhook, or CI annotations
-
-Flecto runs entirely on your machine. Snapshots are local files, and nothing
-leaves the process unless you configure a webhook or command.
-
----
-
-## Stability
-
-Flecto runs inside your merge path, so here is what you can build against.
-These follow [semver](https://semver.org/) and are covered by the deprecation
-sequence below:
-
-- **The JSON envelope** (`schema_version: "2.0"`) — existing fields keep their
-  name, type, and meaning; new fields are additive. Schemas in [`schemas/`](schemas).
-- **Exit codes** — `0` clean, `1` a fail trigger matched or the run could not
-  complete. That is the whole set, and Flecto fails closed.
-- **`.flectorc`** — documented keys keep their name, meaning, and default.
-- **Command and flag names**, and what a flag accepts.
-
-**No breaking change to those ships without a minor release that warns first**,
-names the replacement, and says which version removes the old form. The one
-exception is a security fix: if a surface can make `flecto ci` report a clean run
-on a change that is not clean, it gets closed in the next release with an
-advisory. 4.0 was exactly that — five breaking changes, every one a bypass.
-
-Deliberately **not** stable: terminal and `pr-comment` output (presentation —
-parse `--format json` instead), message wording, anything under `src/`, and
-snapshot file internals. Built-in packs gain rules in minor releases; rule IDs
-never change meaning.
-
-Flecto reached 4.0 in four months, which is fast. That churn was front-loaded
-into a period with no real users, and 4.0 was forced by a
-[security review](docs/security-review.md) finding real bypasses. The intent now
-is minor releases only — anything needing a 5.0 waits in
-[`docs/v5-proposals.md`](docs/v5-proposals.md).
-
-→ **[Full stability policy](docs/stability.md)**
-
----
-
 ## Project
 
 - **Questions and ideas** — [Discussions](https://github.com/myselfsiddharth/Flecto/discussions)

package/index.js

@@ -385,18 +385,51 @@ function gitRepoRelativePath(filePath) {
  * @returns {boolean}
  */
 function baselineEntryIsSymlink(commit, rel, dir) {
+  return baselineEntryMode(commit, rel, dir) === '120000';
+}
+
+/**
+ * The git mode of the entry at this path in this commit: '' when the commit
+ * has no such path, null when git could not answer.
+ * @param {string} commit
+ * @param {string} rel
+ * @param {string} dir
+ * @returns {string | null}
+ */
+function baselineEntryMode(commit, rel, dir) {
   try {
-    const entry = execFileSync(
+    // `rel` is relative to the repository root, and without --full-tree
+    // ls-tree resolves it against `dir`: for any file below the root it looked
+    // up `sub/sub/file`, found nothing, and the symlink check never fired.
+    return execFileSync(
       'git',
-      ['-C', dir, 'ls-tree', '--format=%(objectmode)', '--end-of-options', commit, '--', rel],
+      ['-C', dir, 'ls-tree', '--full-tree', '--format=%(objectmode)', '--end-of-options', commit, '--', rel],
       { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
     ).trim();
-    return entry === '120000';
   } catch {
-    return false;
+    return null;
   }
 }
 
+/**
+ * Returned in place of a baseline state when `--new-files added` is set and the
+ * baseline commit does not contain the file. A distinct value rather than an
+ * empty document, so the caller cannot mistake "this file is new" for "this
+ * file was empty" (#186), and has to say which one it is reporting.
+ */
+const NEW_FILE = Symbol('new file');
+
+/**
+ * An empty baseline of the same shape as the head document, so every key
+ * diffs as `added`. Not `parseContent(path, '')`: JSON has no empty document.
+ * @param {unknown} after
+ */
+function emptyBaselineLike(after) {
+  if (Array.isArray(after)) return [];
+  if (after !== null && typeof after === 'object') return {};
+  return null;
+}
+
 /**
  * Resolve symlinks where possible, falling back to the input when the path does
  * not exist on disk.
@@ -518,7 +551,7 @@ function isExplicitPath(value) {
     || value.startsWith('..\\');
 }
 
-function readSnapshotStateFromRef(filePath, snapshotRef, store, snapshotFile) {
+function readSnapshotStateFromRef(filePath, snapshotRef, store, snapshotFile, { newFiles = 'fail' } = {}) {
   if (snapshotRef === '') {
     // The same unset-CI-variable case readSnapshotFile refuses. Falling back to
     // the store here would compare against something the operator did not
@@ -576,6 +609,19 @@ function readSnapshotStateFromRef(filePath, snapshotRef, store, snapshotFile) {
   }
 
   const rel = gitRepoRelativePath(filePath);
+  // A file the baseline commit does not have is a file this change adds. The
+  // default is still to fail closed: a rename reads as a new file too, and
+  // turns every `changed` into an `added` that the Action's default --fail-on
+  // does not gate. `--new-files added` is the explicit, CLI-only opt-in. The
+  // commit is the operator's, so the change under review cannot fake absence.
+  if (baselineEntryMode(commit, rel, repoDir) === '') {
+    if (newFiles === 'added') return NEW_FILE;
+    throw new Error(
+      `"${rel}" is not in ${ref}, so there is no baseline to diff it against.`
+      + ' If this change adds the file, pass --new-files added to report every key as added'
+      + ' (policies still run); the default fails closed because a rename looks the same.',
+    );
+  }
   if (baselineEntryIsSymlink(commit, rel, repoDir)) {
     throw new Error(
       `"${rel}" is a symbolic link in ${ref}, so the baseline there is a path, not a configuration.`
@@ -1309,6 +1355,7 @@ program
   .option('-p, --profile <name>', 'Use profile from .flectorc (else FLECTO_PROFILE)')
   .option('--snapshot-ref <ref>', 'Baseline git revision (a snapshot path also works if it is path-shaped)')
   .option('--snapshot-file <path>', 'Baseline snapshot file, never consulted as a git revision')
+  .option('--new-files <mode>', 'A file not in the --snapshot-ref commit: fail (default) | added (every key reported as added)')
   .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')
@@ -1347,9 +1394,23 @@ program
 
       const ignorePaths = parseCsv(effective.ignore);
       const failOn = parseFailOn(effective.failOn ?? 'changed,policy,error');
+      const newFiles = String(effective.newFiles ?? 'fail');
+      if (newFiles !== 'fail' && newFiles !== 'added') {
+        throw new Error(`--new-files must be fail or added (got ${newFiles})`);
+      }
       const format = String(effective.format ?? 'json');
-      if (!['json', 'ndjson', 'sarif', 'github-annotations', 'pr-comment'].includes(format)) {
-        throw new Error('--format must be json, ndjson, sarif, github-annotations, or pr-comment');
+      if (format === 'human') {
+        throw new Error(
+          '--format human is not available for `ci`, whose output is meant to be consumed by a machine. Use pr-comment to read it yourself, or json to parse it. (human is the default for `plan` and `compare`.)',
+        );
+      }
+      // Listed once: the check and the message drift apart otherwise, and the
+      // message is the only place a user finds out what is allowed. The wording
+      // is unchanged -- this is a dedup, not a rewording.
+      const CI_FORMATS = ['json', 'ndjson', 'sarif', 'github-annotations', 'pr-comment'];
+      if (!CI_FORMATS.includes(format)) {
+        const listed = `${CI_FORMATS.slice(0, -1).join(', ')}, or ${CI_FORMATS.at(-1)}`;
+        throw new Error(`--format must be ${listed}`);
       }
       const prCommentPost = Boolean(effective.prCommentPost);
       if (effective.prProvider && !PR_PROVIDER_IDS.includes(String(effective.prProvider))) {
@@ -1421,13 +1482,22 @@ program
           : alignStateWithStore(parseFile(filepath), snapshotStore);
         let before;
         try {
-          before = readSnapshotStateFromRef(filepath, effective.snapshotRef, snapshotStore, effective.snapshotFile);
+          before = readSnapshotStateFromRef(
+            filepath, effective.snapshotRef, snapshotStore, effective.snapshotFile, { newFiles },
+          );
         } catch (err) {
           throw new Error(
             `Failed to resolve snapshot baseline for "${filepath}"` +
             `${effective.snapshotRef ? ` (ref: ${effective.snapshotRef})` : ''}: ${err.message}`
           );
         }
+        if (before === NEW_FILE) {
+          renderWarn(
+            `${relative(cwd, filepath).replaceAll('\\', '/')} is not in ${effective.snapshotRef}: reporting it as a new file,`
+            + ' every key added (--new-files added).',
+          );
+          before = emptyBaselineLike(after);
+        }
         const events = diffTrees(before, after, dOpts);
         const rawFindings = await evaluatePolicies(events, {
           cwd,

package/package.json

@@ -4,7 +4,7 @@
     "access": "public",
     "provenance": true
   },
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "Reads your Terraform plan and Kubernetes changes and posts a plain-English risk summary on every pull request, blocking the dangerous ones",
   "license": "MIT",
   "keywords": [

package/src/alerter.js

@@ -204,7 +204,12 @@ export function runCommand(command, envelope) {
         renderWarn(`Command failed to start: ${err.message}`);
         settle(false);
       });
-      child.on('close', (code) => {
+      child.on('close', (code, signal) => {
+        if (signal) {
+          renderWarn(`Command failed (signal ${signal}): ${command}`);
+          settle(false);
+          return;
+        }
         if (code && code !== 0) {
           renderWarn(`Command failed (exit ${code}): ${command}`);
           settle(false);

package/src/config.js

@@ -519,7 +519,11 @@ export function assertSnapshotRefFromCli(effective, cliOverrides) {
   if (rcBaselineAllowed()) return;
   // `snapshotFile` picks the baseline just as directly, so it is gated with it
   // rather than left as the way around it.
-  for (const option of ['snapshotRef', 'snapshotFile']) {
+  // `newFiles` decides what a file missing from the baseline is compared
+  // against, and a rename is a missing file: from .flectorc it would let a pull
+  // request move prod.yaml and have every `changed` reported as `added`.
+  const flags = { snapshotRef: 'snapshot-ref', snapshotFile: 'snapshot-file', newFiles: 'new-files' };
+  for (const [option, flag] of Object.entries(flags)) {
     if (effective[option] === undefined || cliOverrides[option] !== undefined) continue;
     throw new Error(
       `Refusing "${option}" declared in .flectorc: it chooses the baseline every change is`
@@ -527,7 +531,7 @@ export function assertSnapshotRefFromCli(effective, cliOverrides) {
       + ' pointing it at "HEAD", or at a file it committed, compares every file against itself'
       + ' and exits 0.\n'
       + `Declared: ${JSON.stringify(effective[option])}\n`
-      + `Pass --${option === 'snapshotRef' ? 'snapshot-ref' : 'snapshot-file'} on the command line`
+      + `Pass --${flag} on the command line`
       + ' instead, or set FLECTO_ALLOW_RC_BASELINE=1 if this config is trusted.',
     );
   }

package/src/differ.js

@@ -361,6 +361,48 @@ function identityMap(items, idKey) {
   return map;
 }
 
+// `KEY=VALUE`, or a bare `KEY` (Compose's pass-through from the host).
+export const ASSIGNMENT_RE = /^([A-Za-z_][A-Za-z0-9_.-]*)(?:=|$)/;
+
+/**
+ * Key a list of `KEY=VALUE` strings by KEY, or return null when it is not one.
+ *
+ * Compose writes `environment`, `labels` and `build.args` either as a map or as
+ * a list of assignments, and means the same thing by both. Diffed by position,
+ * one inserted variable turned every later line into a `changed` pairing two
+ * unrelated variables (#226). At least one item must carry an `=`, so a plain
+ * word list such as `command: [python, app.py]` keeps its order-sensitive diff.
+ * @param {unknown[]} items
+ * @returns {Map<string, { value: unknown, index: number }> | null}
+ */
+function assignmentMap(items) {
+  /** @type {Map<string, { value: unknown, index: number }>} */
+  const map = new Map();
+  for (let i = 0; i < items.length; i++) {
+    const item = items[i];
+    if (typeof item !== 'string') return null;
+    const match = ASSIGNMENT_RE.exec(item);
+    if (!match || map.has(match[1])) return null;
+    map.set(match[1], { value: item, index: i });
+  }
+  return map;
+}
+
+/**
+ * Both sides are assignment lists and at least one item assigns a value.
+ * @param {unknown[]} before
+ * @param {unknown[]} after
+ * @returns {{ beforeMap: Map<string, { value: unknown, index: number }>, afterMap: Map<string, { value: unknown, index: number }> } | null}
+ */
+function assignmentMaps(before, after) {
+  const beforeMap = assignmentMap(before);
+  const afterMap = beforeMap && assignmentMap(after);
+  if (!beforeMap || !afterMap) return null;
+  const assigns = (item) => typeof item === 'string' && item.includes('=');
+  if (!before.some(assigns) && !after.some(assigns)) return null;
+  return { beforeMap, afterMap };
+}
+
 /**
  * Select a configured identity key, or auto-detect id then name.
  * @param {unknown[]} before
@@ -425,10 +467,11 @@ function arraySignature(value) {
  */
 function diffArrays(before, after, basePath, events, options = {}, ancestors = newAncestors()) {
   const idKey = resolveArrayIdKey(before, after, options);
+  const assignments = !idKey && options.arrayIdentity !== false ? assignmentMaps(before, after) : null;
 
-  if (idKey) {
-    const beforeMap = identityMap(before, idKey);
-    const afterMap = identityMap(after, idKey);
+  if (idKey || assignments) {
+    const { beforeMap, afterMap } = assignments
+      ?? { beforeMap: identityMap(before, idKey), afterMap: identityMap(after, idKey) };
 
     if (beforeMap && afterMap) {
       for (const [key, afterItem] of afterMap) {

package/src/parser.js

@@ -435,6 +435,30 @@ export function yamlDocumentKeys(docs) {
  * @returns {unknown}
  * @throws {Error} on unsupported format or parse failure
  */
+/**
+ * Whether a file that failed to parse as YAML looks like a Helm chart template.
+ *
+ * Only ever consulted **after** a parse failure, which is what keeps it from
+ * firing on valid YAML that happens to contain braces -- a Prometheus rule
+ * holding `{{ $labels.instance }}` in a string parses fine and never reaches
+ * here. Go template delimiters in a file that did not parse are close to
+ * conclusive, and `{{-`, `nindent`, `include "` and a `templates/` path are the
+ * shapes that only a chart has.
+ *
+ * @param {string} raw
+ * @param {string} filepath
+ * @returns {boolean}
+ */
+function looksLikeHelmTemplate(raw, filepath) {
+  if (!/\{\{/u.test(raw) || !/\}\}/u.test(raw)) return false;
+  const path = filepath.replace(/\\/gu, '/');
+  return /\/templates\//u.test(path)
+    || /\{\{-/u.test(raw)
+    || /\|\s*nindent\b/u.test(raw)
+    || /\{\{[^}]*\binclude\s+"/u.test(raw)
+    || /\{\{[^}]*\.Values\./u.test(raw);
+}
+
 export function parseContent(filepath, raw) {
   const ext = extname(filepath).toLowerCase();
   const envLike = isEnvFilename(filepath);
@@ -469,6 +493,19 @@ export function parseContent(filepath, raw) {
       parsed = TOML.parse(raw);
     }
   } catch (err) {
+    // A chart template is not YAML, and saying so beats a column number. Without
+    // this, `flecto ci "helm/**/*.yaml"` -- the first thing a Helm user tries --
+    // reports a syntax error inside a file that is perfectly valid, and sends
+    // them to debug their chart instead of their command.
+    if ((ext === '.yaml' || ext === '.yml') && looksLikeHelmTemplate(raw, filepath)) {
+      throw new Error(
+        `"${filepath}" looks like a Helm template, not YAML.\n` +
+        'Flecto reads rendered manifests, so render the chart first:\n' +
+        '  helm template ./chart > rendered.yaml && flecto ci rendered.yaml\n' +
+        'Or point Flecto at the values file, which is plain YAML:\n' +
+        '  flecto ci chart/values.yaml'
+      );
+    }
     const lineMatch = err.message?.match(/line (\d+)/i);
     const lineInfo = lineMatch ? ` (line ${lineMatch[1]})` : '';
     throw new Error(

package/src/positions.js

@@ -3,6 +3,7 @@ import yaml from 'js-yaml';
 
 import { isArmoredAgeFile } from './encrypted.js';
 import { isEnvFilename, isIniFilename, stripJsonComments, yamlDocumentKeys } from './parser.js';
+import { ASSIGNMENT_RE } from './differ.js';
 
 /**
  * Where a config path lives in the source text (#142).
@@ -247,6 +248,12 @@ function itemByIdentity(items, quoted, arrayIdKey) {
       if (String(id) === target) matches.add(item);
     }
   }
+  // A `KEY=VALUE` list (Compose `environment`, `labels`) is keyed by KEY.
+  if (matches.size === 0 && !arrayIdKey) {
+    for (const item of items) {
+      if (typeof item.value === 'string' && ASSIGNMENT_RE.exec(item.value)?.[1] === target) matches.add(item);
+    }
+  }
   return matches.size === 1 ? [...matches][0] : null;
 }
 

package/src/secrets.js

@@ -78,8 +78,13 @@ 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,
  * would make the policy rule fire on configs that correctly keep secrets out of
  * the file.
+ *
+ * `$(NAME)` is Kubernetes' env-var expansion in a container's env and args, and
+ * `{{ ... }}` a Helm or Jinja template expression: in a connection string such
+ * as `postgres://app:$(DB_PASSWORD)@db/app` both are the reference, not the
+ * credential.
  */
-const PLACEHOLDER_RE = /^(?:\$\{[^}]*\}|\$[A-Za-z_][A-Za-z0-9_]*|%[A-Za-z0-9_]+%|<[^>]*>|\*+)$/;
+const PLACEHOLDER_RE = /^(?:\$\{[^}]*\}|\$\([A-Za-z_][A-Za-z0-9_]*\)|\{\{[^}]*\}\}|\$[A-Za-z_][A-Za-z0-9_]*|%[A-Za-z0-9_]+%|<[^>]*>|\*+)$/;
 
 /**
  * High-entropy fallback gates. Every one of these must pass: