From faa3e04fc4dad1bcb60280a27e1e1250f49327ea Mon Sep 17 00:00:00 2001 From: Speculator55005 <50082482+fas89@users.noreply.github.com> Date: Wed, 21 Oct 2026 22:04:15 +0200 Subject: [PATCH] docs: a bundle records a retargeted overlay patch, and fluid validate --strict fails on it (forge-cli #735) --- docs/cli/bundle.md | 4 +++- docs/cli/validate.md | 20 +++++++++++++++++++- docs/concepts/environments-and-overlays.md | 2 ++ 3 files changed, 24 insertions(+), 2 deletions(-) diff --git a/docs/cli/bundle.md b/docs/cli/bundle.md index 91ad677..9dcccc6 100644 --- a/docs/cli/bundle.md +++ b/docs/cli/bundle.md @@ -190,6 +190,7 @@ The file itself is compact JSON with sorted keys. | `source.contract` | The source contract, relative to the directory the bundle was written to. | | `source.env` | The `--env` the bundle was built with, or `null`. | | `source.overlay` | The overlay file that was merged, relative to the contract's directory, or `null`. | +| `source.overlayWarnings` | *(unreleased, [forge-cli #735](https://github.com/Agenticstiger/forge-cli/pull/735))* The overlay merge warnings `fluid validate --strict` fails on, one message each: a patch that landed on another entry. Present only when the merge raised one. | The `source` block is outside the digest, so the digest names the resolved contract alone: the same contract bundled into two directories keeps one @@ -207,7 +208,8 @@ done | shasum -a 256 Later stages use `source` to resolve relative `binding.location.path` values against the source contract's directory, and to refuse a mismatched -environment. +environment. `fluid validate` reports the overlay warnings it records, with +any character that is not printable escaped. ## Environments diff --git a/docs/cli/validate.md b/docs/cli/validate.md index e6f524d..e39ce1d 100644 --- a/docs/cli/validate.md +++ b/docs/cli/validate.md @@ -176,7 +176,7 @@ Validation Warnings: - Workspace mode lists it under the product, and `--strict` fails the product. - `fluid contract-validation --env` and `fluid test --env` (the native engine) report it too; `fluid test` shows it as an "Environment overlay" row. - `overlay_entry_added`, an overlay entry the base does not have, stays a log line and does not fail `--strict`: a build only one environment runs is often intended. -- A bundle does not carry it: `fluid bundle --env` merged the overlay before, so `fluid validate .tgz --strict` (pipeline stage 2) passes. Validate the contract file with `--env` to catch it. +- *(unreleased, [forge-cli #735](https://github.com/Agenticstiger/forge-cli/pull/735))* A bundle carries it. `fluid bundle --env --format tgz` records it in the bundle's manifest, so `fluid validate .tgz` reports it as an `OVERLAY-WARNING` finding and `--strict` (pipeline stage 2) fails on it: see [Validating a bundle](#validating-a-bundle-tgz). A bundle built before that change records none and passes. `fluid contract-validation` and `fluid test` do not read the record, so run them on the contract file with `--env`. ## Contracts split into fragments @@ -280,6 +280,7 @@ What it checks: - **The files in the bundle.** The resolved contract against the JSON Schema, SQL fragments with a SQL parser, and OpenAPI fragments with an OpenAPI validator. When the SQL parser or the OpenAPI validator is not installed, those fragments are reported as an info (an error under `--strict`) instead of being checked. - **The contract rules.** The resolved contract goes through the same rules a contract file does: sovereignty, agent policy, binding prerequisites, packaging, semantics, composition and plugin validators. Each finding is reported with code `CONTRACT-RULE`. - **The environment.** `--env` must match the environment the bundle was built for. +- **The overlay warnings.** *(unreleased, [forge-cli #735](https://github.com/Agenticstiger/forge-cli/pull/735))* An overlay patch that `fluid bundle --env` merged onto another entry is recorded in the manifest and reported as a warning, `OVERLAY-WARNING`, so `--strict` fails on it. A bundle is never re-overlaid, so the record is how validate sees it. A bundle is never re-overlaid, so a mismatched `--env` is an error, `BUNDLE-ENV-MISMATCH`, and exits `1`: @@ -304,6 +305,22 @@ A bundle built from the governance example above fails on its contract rules, th [error] contract: contract.resolved.yaml: exposes[exports] is a GCP gcs_bucket binding and declares lifecycle.expire, ... ``` +A bundle built with `--env prod` from the 0.7.5 contract in [`--env` and environment overlays](#env-and-environment-overlays), whose overlay patches the wrong build, fails under `--strict`: + +```bash +fluid validate runtime/bundle.tgz --env prod --strict +``` + +```text +❌ Bundle fail: /path/to/proj/runtime/bundle.tgz + digest: sha256:6238f9c15525142e3b67ff343171cf10631c0e5f85504608bec05ad8e2380db7 + issues: 1 total (0 error, 1 warning, 0 info) + [warning] overlay: MANIFEST.json: overlay_patch_retargeted: in network.service-instances, the overlay's builds[1] names id transform but patches the base's builds[1], id ingest, because lists merge by position. Put the overlay's entries in the base's order, or set fluidVersion 0.7.6 or later to merge builds by id. +❌ Validation failed: warnings treated as errors (--strict) +``` + +*(unreleased, [forge-cli #735](https://github.com/Agenticstiger/forge-cli/pull/735))* Without `--strict` the same bundle passes and still lists the warning: a bundle that passes lists its warnings, not only their count. `--quiet`, which printed nothing for a bundle, prints each error as `ERROR: `, a recorded overlay warning as `WARNING: `, and under `--strict` each warning as `ERROR (--strict): `. + `--report PATH` writes the full structured report as JSON, on pass and on fail, so a CI job can upload it as an artifact. The report has `bundleDigest`, `input`, `strict`, `status`, `summary` and `issues[]`; each issue carries `file`, `validator`, `severity`, `message` and a `code`. The `BUNDLE-ENV-MISMATCH` finding is written to the report like any other. `--report` has an effect only for a `.tgz` bundle: `fluid validate contract.fluid.yaml --report out.json` writes no file as of 0.18.1. Codes you will meet in a report: @@ -312,6 +329,7 @@ Codes you will meet in a report: | --- | --- | | `MANIFEST-TAMPER` | A file's hash does not match the manifest. | | `BUNDLE-ENV-MISMATCH` | `--env` differs from the environment the bundle was built for. | +| `OVERLAY-WARNING` | `fluid bundle --env` recorded an overlay patch that landed on another entry (a warning; `--strict` fails on it). | | `CONTRACT-RULE` | A contract rule failed or warned on the resolved contract. | | `CONTRACT-LOAD` | The resolved contract inside the bundle could not be loaded. | | `RESOLVED-PARSE` | The resolved contract could not be parsed. | diff --git a/docs/concepts/environments-and-overlays.md b/docs/concepts/environments-and-overlays.md index 466f660..abe021a 100644 --- a/docs/concepts/environments-and-overlays.md +++ b/docs/concepts/environments-and-overlays.md @@ -107,6 +107,8 @@ not name the file. *(unreleased, [forge-cli #734](https://github.com/Agenticstiger/forge-cli/pull/734))* `fluid validate --env`, `fluid contract-validation --env` and `fluid test --env` report it as a warning instead, and `--strict` fails on it; see [`fluid validate`: `--env` and environment overlays](../cli/validate.md#env-and-environment-overlays). + *(unreleased, [forge-cli #735](https://github.com/Agenticstiger/forge-cli/pull/735))* `fluid bundle --env --format tgz` records it in the + bundle, so `fluid validate .tgz --strict` fails on it too. - Base keys an overlay does not set survive inside a patched map. A base `binding.location.path` is still present in the resolved binding of an overlay that sets `project`, `dataset` and `table`: `fluid bundle --env gcp` shows