@intentius/chant 0.124.28 → 0.124.30

package/dist/workspace/status.schema.json

@@ -123,6 +123,10 @@
           "type": "array",
           "items": { "$ref": "#/$defs/acceptance" }
         },
+        "overlap": {
+          "description": "Added in contract 1 by #4025, written by chant 0.124.29 and newer; absent from older output, so a reader treats a missing field as unknown. Overlap between in-flight work items: a work item (a current record of a declared work kind) is in flight unless it implements at least one decision and every one is confirmed (in one of its kind's closed states and superseded by nothing, as featureFlags reads it). Its commits are the ones linked to it as #4029 defines linked (a Chant-Record: <work kind>:<id> trailer, or a Chant-Lease trailer that resolves to it), read from every local and remote-tracking branch and HEAD, the chant/ ledger branches left out, merges skipped, and never fetched. Two items overlap when their commits touch the same file, or when one entry of a change set a pending or approved gate binds is attributed to both: an entry is attributed to an item when a commit linked to the item changed the entry's source file (recorded on the stored change set) and that commit is in the history the change set was planned from. A report only: nothing is locked or refused. Null when the workspace declares no work kind, or the work records or history can't be read.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/overlap" }]
+        },
         "summary": {
           "type": "object",
           "required": ["members", "released", "unreadable", "differing"],
@@ -266,9 +270,97 @@
               }
             }
           }
+        },
+        "featureFlags": {
+          "description": "The member's feature flags (#4024): each record of a declared flag kind whose member field names this member, sorted by id. A flag is a workspace record the member's build reads as one build-time parameter, with chant build --env <env>; its value in an environment is recorded on the build, and on a release's target, as a param whose source is flag:<id>. Named featureFlags because a release record's flags already holds legacy-digest. Empty when no flag names the member, and null when the flag records could not be read. Optional: written from chant 0.124.29, absent from older output.",
+          "type": ["array", "null"],
+          "items": { "$ref": "#/$defs/featureFlag" }
         }
       }
     },
+    "overlap": {
+      "type": "object",
+      "required": ["items", "pairs", "changeSets", "unattributed"],
+      "properties": {
+        "items": {
+          "type": "array",
+          "description": "Each in-flight work item with at least one linked commit, sorted by item.",
+          "items": {
+            "type": "object",
+            "required": ["item", "path", "state", "commits"],
+            "properties": {
+              "item": { "type": "string", "description": "<work kind>:<id>, as a Chant-Record trailer names it." },
+              "path": { "type": "string", "description": "The work record file, from the repository root." },
+              "state": { "type": ["string", "null"] },
+              "commits": { "type": "array", "items": { "type": "string" }, "description": "The commits linked to the item, newest first." }
+            }
+          }
+        },
+        "pairs": {
+          "type": "array",
+          "description": "Each pair of items that share a file or a change-set entry, sorted by the first item and then the second. Empty when nothing overlaps.",
+          "items": {
+            "type": "object",
+            "required": ["items", "files", "addresses"],
+            "properties": {
+              "items": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 2, "description": "The two items, in sorted order." },
+              "files": { "type": "array", "items": { "type": "string" }, "description": "The paths, from the repository root, that both items' linked commits add, change or delete, sorted. A rename counts as a delete and an add." },
+              "addresses": {
+                "type": "array",
+                "description": "The change-set entries attributed to both items, by change set, member and address.",
+                "items": {
+                  "type": "object",
+                  "required": ["changeSet", "ledgerMember", "member", "address", "node", "source"],
+                  "properties": {
+                    "changeSet": { "type": "string", "description": "The change set's digest, for chant change-set show." },
+                    "ledgerMember": { "type": ["string", "null"], "description": "The workspace member whose ledger stores the change set, or null for the flat ledger." },
+                    "member": { "type": "string", "description": "The entry's change-set member." },
+                    "address": { "type": "string", "description": "The entry's planner address." },
+                    "node": { "type": ["string", "null"], "description": "The entry's graph node." },
+                    "source": { "type": "string", "description": "The entry's source file, from the repository root, that both items' commits changed." }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "changeSets": { "type": "array", "items": { "type": "string" }, "description": "The digests of the stored change sets read: those a pending or approved gate binds, sorted." },
+        "unattributed": { "type": "integer", "minimum": 0, "description": "Entries of those change sets with no source (stored by a chant before 0.124.29, or mapped onto no node with a source location), so attributed to no item." }
+      }
+    },
+    "featureFlag": {
+      "type": "object",
+      "required": ["id", "param", "owner", "values", "work", "implements", "stale", "kind", "path"],
+      "properties": {
+        "id": { "type": "string", "description": "The flag's name, its record's id." },
+        "param": { "type": "string", "description": "The build parameter of the member the flag sets: a key of buildParams in its chant.config.ts." },
+        "owner": { "type": "string", "description": "Who owns the flag, and removes it when its work is settled." },
+        "values": {
+          "type": "object",
+          "description": "The flag's value per environment, as the record writes it. An environment it leaves out builds with the parameter's declared default.",
+          "additionalProperties": { "oneOf": [{ "type": "string" }, { "type": "number" }, { "type": "boolean" }] }
+        },
+        "work": {
+          "description": "The work item the flag hides, with that item's state, which is null when no record of the flag kind's work kind has the id. Null when the record names none.",
+          "oneOf": [
+            { "type": "null" },
+            { "type": "object", "required": ["id", "state"], "properties": { "id": { "type": "string" }, "state": { "type": ["string", "null"] } } }
+          ]
+        },
+        "implements": {
+          "type": "array",
+          "description": "Each decision the work item implements, with its state, and confirmed: true when the decision is in one of its kind's closed states and nothing supersedes it.",
+          "items": {
+            "type": "object",
+            "required": ["id", "state", "confirmed"],
+            "properties": { "id": { "type": "string" }, "state": { "type": ["string", "null"] }, "confirmed": { "type": "boolean" } }
+          }
+        },
+        "stale": { "type": "boolean", "description": "True when the work item implements at least one decision and every one is confirmed: the flag is due for removal, and chant workspace check reports it (WSP118)." },
+        "kind": { "type": "string", "description": "The flag kind file, from the workspace root." },
+        "path": { "type": "string", "description": "The flag record file, from the workspace root." }
+      }
+    },
     "stewardForm": { "enum": ["local", "fountain"] },
     "steward": {
       "type": "object",
@@ -357,11 +449,22 @@
                         "required": ["forge"],
                         "description": "Added in contract 1 by #4020, written by chant 0.124.28 and newer. The CI run the Op ran in, the shape a release's runOrigin has: the forge (github for GitHub and Forgejo, gitlab), the repo or project, and a link to the run. Absent outside CI.",
                         "properties": {
-                          "forge": { "enum": ["github", "gitlab", "op", "local"] },
+                          "forge": { "enum": ["github", "gitlab", "op", "local", "chant"], "description": "chant: a pull-request job the chant runner ran (chant ci run, #4094), added within contract 1 and written by chant 0.124.30 and newer." },
                           "repo": { "type": "string" },
                           "url": { "type": "string" }
                         }
                       },
+                      "failure": {
+                        "type": "object",
+                        "required": ["code", "reason"],
+                        "description": "Added in contract 1 by #4094, written by chant 0.124.30 and newer. Why a failed run failed: code is a pull-request report's refusal or status (not-approved, plan-changed, not-a-reviewer, no-pull-request, plan-failed, failed, refused) or command-failed, setup-failed or build-failed, and a reader keeps a case for a code it does not know. reason is one line for a person, phase the phase that failed, exitCode the failed command's exit code. chant ci run writes it on every failed job; absent otherwise.",
+                        "properties": {
+                          "code": { "type": "string", "minLength": 1 },
+                          "reason": { "type": "string" },
+                          "phase": { "type": "string" },
+                          "exitCode": { "type": "integer" }
+                        }
+                      },
                       "gate": {
                         "oneOf": [
                           { "type": "null" },
@@ -874,13 +977,14 @@
         "planDigest": { "type": ["string", "null"], "description": "The plan the run reached the gate with (#2300), or null for a gate that binds no plan. An approval counts only for this plan." },
         "state": {
           "enum": ["pending", "approved", "expired", "superseded"],
-          "description": "Read from the newest pending fact for the gate in env, as a run reads it. approved: the approvals recorded since it, for its plan, pass the gate (its quorum, or a policy permit in enforce mode). expired: not approved, and the pending fact is past expiresAt, so the next run records a fresh one. superseded: not approved, and an approval recorded since it names a different plan, so it doesn't count. pending: none of these."
+          "description": "Read from the newest pending fact for the gate in env, as a run reads it. approved: the approvals recorded since it, for its plan, pass the gate (its quorum, or a policy permit in enforce mode). expired: not approved, and the pending fact is past expiresAt, so the next run records a fresh one. superseded: not approved, and an approval recorded since it names a different plan, so it doesn't count; or, on a release gate that is not expired, its release was cut from a revoked commit (#4033, ws-105), so chant approve refuses it with release-revoked and revoked is set. pending: none of these."
         },
         "recordedAt": { "type": "string", "description": "When the run recorded the pending fact." },
         "gitSha": { "type": "string", "description": "Added in contract 1 by #4020, written by chant 0.124.28 and newer. The commit the run reached the gate at, from the pending fact. Absent on a fact recorded by an older chant, and when the run knew no commit. It joins the gate to a release's gitSha and to a run's." },
         "runId": { "type": "string", "description": "Added in contract 1 by #4020, written by chant 0.124.28 and newer. The run that reached the gate: an Op run id, or the CI run id for a component gate that ran in CI. Absent when the run had none." },
         "changeSet": { "type": "string", "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$", "description": "Added in contract 1 by #4022, written by chant 0.124.28 and newer. The change set the gate binds: planDigest, when a change-set document is stored under it in the member's _change-sets/ on chant/lifecycle, as a pull-request gate's apply and a release gate (#4045) store it. chant change-set show <changeSet> --json prints it, each entry with its graph node. Absent when none is stored, as for a component gate, which binds a lifecycle-plan digest." },
         "releaseDigest": { "type": "string", "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$", "description": "Added in contract 1 by #4045, written by chant 0.124.28 and newer. The release the gate binds, from the pending fact: set on a release gate, the gate chant components promote --release passes for an environment, whose component is the op release. An approval counts toward it only when it was recorded for this release, environment and planDigest. Absent on every other gate." },
+        "revoked": { "$ref": "#/$defs/revocation", "description": "Added in contract 1 by #4033 (ws-105), written by chant 0.124.29 and newer. Set on a release gate whose release was cut from a commit with a ci/revoked/<sha> tag, judged as release cut judges it: the tag. The gate's state is then superseded, or expired when its pending fact has expired. Absent otherwise." },
         "expiresAt": { "type": "string" },
         "approvals": {
           "description": "The approvals that count toward the gate for its plan, oldest first.",
@@ -957,6 +1061,59 @@
               }
             }
           ]
+        },
+        "mixed": { "$ref": "#/$defs/mixed" }
+      }
+    },
+    "mixed": {
+      "type": "object",
+      "description": "Added in contract 1 by #4035, written by chant 0.124.29 and newer. Set when the environment runs a mix: a components promote, rollback or redeploy left a component failed or gated (its <env>/outcomes.jsonl on chant/lifecycle says so) and the release ledger has recorded nothing for it since, or the latest records of its components name more than one release, a record of no release counting as one, with at least one naming a release. Derived when read. Absent otherwise.",
+      "required": ["components", "redeploy", "rollback"],
+      "properties": {
+        "components": {
+          "description": "Every component the ledger records in the environment or a run left unsettled, sorted by name.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["component", "digest", "releaseDigest", "releaseLabel", "state", "attempt"],
+            "properties": {
+              "component": { "type": "string" },
+              "digest": { "type": ["string", "null"], "description": "The digest the release ledger records the component running, or null when it has no record in the environment." },
+              "releaseDigest": { "type": ["string", "null"], "description": "The release that record names, or null." },
+              "releaseLabel": { "type": ["string", "null"], "description": "That release's label, or null." },
+              "state": {
+                "enum": ["settled", "failed", "gated"],
+                "description": "settled: the record is what the component runs. failed or gated: the newest run that named it failed on it or stopped at its gate after the steps before the gate ran, and nothing has been recorded for it since, so what it runs is not known."
+              },
+              "attempt": {
+                "description": "For an unsettled component, the run that left it so and what it was deploying. Null when settled.",
+                "oneOf": [
+                  { "type": "null" },
+                  {
+                    "type": "object",
+                    "required": ["verb", "runId", "timestamp", "digest", "releaseDigest", "releaseLabel"],
+                    "properties": {
+                      "verb": { "enum": ["promote", "rollback", "redeploy"] },
+                      "runId": { "type": "string" },
+                      "timestamp": { "type": "string" },
+                      "digest": { "type": "string" },
+                      "releaseDigest": { "type": ["string", "null"] },
+                      "releaseLabel": { "type": ["string", "null"] }
+                    }
+                  }
+                ]
+              }
+            }
+          }
+        },
+        "redeploy": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "chant components redeploy <env> --component <component> for each unsettled component the ledger records, run in the member's directory: it puts the component's recorded release back. Empty when no component is unsettled."
+        },
+        "rollback": {
+          "type": ["string", "null"],
+          "description": "chant components rollback <env> --release <label|digest>, run in the member's directory: it restores every component of the newest release the environment ran, other than the one it was moving to, that is still kept and not revoked. Null when there is none."
         }
       }
     },
@@ -987,13 +1144,64 @@
             }
           ]
         },
+        "releaseDigest": { "type": ["string", "null"], "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$", "description": "Added in contract 1 by #4043, written by chant 0.124.29 and newer. The release this deploy was made from: the releaseDigest of _releases/<releaseDigest>.json. A promote with --release writes it, a run --components with --release writes it, and a rollback or redeploy copies it from the record it restores. Null for a deploy that named no release. With the item's environment it names the release target." },
+        "releaseLabel": { "type": ["string", "null"], "description": "Added in contract 1 by #4043, written by chant 0.124.29 and newer. The label that release was cut with, from _releases/cuts.jsonl. Null when releaseDigest is null, when the release has no label, and when the cuts can't be read." },
         "flags": { "type": "array", "items": { "enum": ["legacy-digest"] } },
         "plan": {
           "type": ["object", "null"],
           "description": "The release plan digest names, read from _plans/<digest>.json on chant/lifecycle (ws-055, #2733): the work items and evidence this release shipped. Null when this checkout has no plan stored under that digest — most releases carry no plan, and a plan not yet fetched also reads null."
+        },
+        "revoked": {
+          "description": "Added in contract 1 by #4033 (ws-105), written by chant 0.124.29 and newer. Set when the deploy record names a release in releaseDigest and that release was cut from a commit with a ci/revoked/<sha> tag: the environment runs a revoked release. Read from local tags at read time and judged as release cut judges them, so with ci.green.signedSince an unsigned revoked tag is ignored. Absent when the release is not revoked, when the record names no release, and when the ci tags can't be judged.",
+          "allOf": [
+            { "$ref": "#/$defs/revocation" },
+            {
+              "type": "object",
+              "required": ["releaseDigest", "label", "rollback"],
+              "properties": {
+                "releaseDigest": { "type": "string", "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$", "description": "The revoked release the environment runs." },
+                "label": { "type": ["string", "null"], "description": "The release's label, or null when its cuts gave it none." },
+                "rollback": { "type": "string", "description": "The line that rolls the environment back, run in the member's directory. Since #4035 (chant 0.124.29): chant components rollback <env> --release <label|digest>, naming the newest release the environment ran before this one that is still kept and not revoked. When there is none, and from chant 0.124.28: chant components rollback <env> --component <component>." }
+              }
+            }
+          ]
         }
       }
     },
+    "revocation": {
+      "type": "object",
+      "description": "The ci/revoked/<sha> tag on a release's commit (#4033, ws-105), as chant ci list --json shows a commit's revoked tag, with the commit.",
+      "required": ["commit", "tag", "tagged", "phase", "run", "signer"],
+      "properties": {
+        "commit": { "type": "string", "description": "The release's commit, which the tag names." },
+        "tag": { "type": "string", "description": "ci/revoked/<sha>." },
+        "tagged": { "type": ["string", "null"], "description": "When the tag was made, ISO 8601, or null for a lightweight tag." },
+        "phase": { "type": ["string", "null"], "description": "The phase the annotation names as failed, or null when the annotation can't be read." },
+        "run": {
+          "description": "The run the annotation names as failed, or null.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["name", "id", "conclusion", "url"],
+              "properties": {
+                "name": { "type": "string" },
+                "id": { "type": ["integer", "null"], "description": "The check run's id, or null for a chant Op run." },
+                "conclusion": { "type": ["string", "null"] },
+                "url": { "type": ["string", "null"] },
+                "opRun": {
+                  "type": "object",
+                  "required": ["id", "env", "signer"],
+                  "properties": { "id": { "type": "string" }, "env": { "type": "string" }, "signer": { "type": "string" } },
+                  "description": "Present only when the run is a chant Op run (ci.green.source runs, #4044): its id, the env it is recorded under and the runner whose statement it carries. id is then null."
+                }
+              }
+            }
+          ]
+        },
+        "signer": { "type": ["string", "null"], "description": "The runner principal whose statement the tag carries, or null when it counts unsigned." }
+      }
+    },
     "compare": {
       "type": "object",
       "required": ["differs", "components"],

package/dist/workspace/wip.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wip.d.ts","sourceRoot":"","sources":["../../src/workspace/wip.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"wip.d.ts","sourceRoot":"","sources":["../../src/workspace/wip.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAOH,OAAO,EAA6E,KAAK,YAAY,EAAE,KAAK,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAO5K,wDAAwD;AACxD,eAAO,MAAM,cAAc,oBAAoB,CAAC;AAChD,uGAAuG;AACvG,eAAO,MAAM,kBAAkB,wBAAwB,CAAC;AACxD,iFAAiF;AACjF,eAAO,MAAM,sBAAsB,2BAA2B,CAAC;AAC/D,yBAAyB;AACzB,eAAO,MAAM,UAAU,+BAA+B,CAAC;AAEvD,+DAA+D;AAC/D,eAAO,MAAM,oBAAoB,IAAI,CAAC;AACtC,eAAO,MAAM,aAAa,wEAAwE,CAAC;AACnG,eAAO,MAAM,mBAAmB,oFAAoF,CAAC;AAErH,wCAAwC;AACxC,eAAO,MAAM,eAAe,uNAAsE,CAAC;AACnG,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5D,iEAAiE;AACjE,eAAO,MAAM,qBAAqB,sYAWQ,CAAC;AAC3C,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvE,4HAA4H;AAC5H,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,aAAa,CAAC;AAErD,+CAA+C;AAC/C,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,eAAe,CAAC;IACtB,6DAA6D;IAC7D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,sDAAsD;IACtD,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,mCAAmC;IACnC,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,sHAAsH;AACtH,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,iBAAiB,EAAE,CAAC;IAC1B,EAAE,EAAE,gBAAgB,EAAE,CAAC;IACvB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,iBAAiB,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,wIAAwI;IACxI,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,OAAO,CAAC;IACpB,yGAAyG;IACzG,KAAK,EAAE,MAAM,CAAC;CACf;AAED,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,mBAAmB,CAAC;IAC5B,kEAAkE;IAClE,gBAAgB,EAAE,OAAO,CAAC;IAC1B,8EAA8E;IAC9E,UAAU,EAAE,OAAO,CAAC;IACpB,IAAI,EAAE,eAAe,EAAE,CAAC;CACzB;AAED,mDAAmD;AACnD,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,yBAAyB;AACzB,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,KAAK,IAAI,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjE,gDAAgD;AAChD,MAAM,MAAM,WAAW,GACnB,CAAC,IAAI,GAAG;IACN,QAAQ,EAAE;QAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACzD,QAAQ,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,WAAW,EAAE,CAAA;KAAE,EAAE,CAAC;IACnF,WAAW,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACtC,CAAC,GACF,CAAC,IAAI,GAAG;IAAE,KAAK,EAAE;QAAE,IAAI,EAAE,YAAY,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC,CAAC;AAEhE,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AAE9D,yEAAyE;AACzE,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,iBAAiB,CAAC;IACzB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,SAAS,GAAG,cAAc,GAAG,YAAY,GAAG,OAAO,GAAG,UAAU,GAAG,aAAa,CAAC;CAC1F;AAED,iEAAiE;AACjE,MAAM,MAAM,gBAAgB,GACxB,CAAC,IAAI,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAC;IAAC,WAAW,EAAE,eAAe,GAAG,IAAI,CAAA;CAAE,CAAC,GACtI,CAAC,IAAI,GAAG;IACN,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,WAAW,CAAC;IACtB,UAAU,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,WAAW,CAAA;KAAE,CAAC;IACxD,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC,GACF,CAAC,IAAI,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAC;IAAC,WAAW,EAAE,eAAe,CAAA;CAAE,CAAC,GACtF,CAAC,IAAI,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAC;IAAC,IAAI,EAAE,UAAU,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,GACpG,CAAC,IAAI,GAAG;IAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IAAC,KAAK,EAAE;QAAE,IAAI,EAAE,iBAAiB,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC,CAAC;AAiD/F,4CAA4C;AAC5C,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,sDAAsD;AACtD,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,wEAAwE;AACxE,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAM9D;AAsDD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE,CAgBrF;AA0FD,+DAA+D;AAC/D,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,YAAY,GAAG,mBAAmB,CAE5E;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAW3E;AAMD,wFAAwF;AACxF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,mBAAmB,GAAG,gBAAgB,CAa3F;AAED,mGAAmG;AACnG,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,mBAAmB,GAAG,eAAe,CA+BtF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAS3F;AAID,gHAAgH;AAChH,wBAAgB,YAAY,CAAC,GAAG,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,CAwB/E;AAkBD,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,0IAA0I;AAC1I,wBAAgB,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,gBAAgB,CAwB7D;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,mHAAmH;IACnH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,iBAAiB,GAAG,gBAAgB,CAoCnE;AA4CD,iIAAiI;AACjI,wBAAgB,OAAO,CAAC,GAAG,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,gBAAgB,CAQ9D;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,gBAAgB,CAiD/D"}

package/dist/workspace/wip.js

@@ -37,7 +37,7 @@
  * policy says.
  */
 import { spawnSync } from "node:child_process";
-import { copyFileSync, existsSync, lstatSync, mkdtempSync, rmSync, unlinkSync } from "node:fs";
+import { copyFileSync, existsSync, lstatSync, mkdtempSync, rmSync, statSync, unlinkSync, utimesSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { KEPT_REF_PREFIX } from "../lifecycle/work-lease.js";
@@ -219,8 +219,16 @@ function worktreeTree(top) {
         const index = join(dir, "index");
         // Start from the checkout's index so git reuses its stat data; the original is never written.
         const own = out(top, ["rev-parse", "--git-path", "index"]);
-        if (own && existsSync(resolve(top, own)))
-            copyFileSync(resolve(top, own), index);
+        if (own && existsSync(resolve(top, own))) {
+            const source = resolve(top, own);
+            copyFileSync(source, index);
+            // Keep the index's own timestamps on the copy. git treats an entry whose
+            // file is as new as the index as racily clean and reads its content; a
+            // copy stamped now would make a same-size edit made in the same second as
+            // the last index write look unchanged, and the snapshot would miss it.
+            const { atime, mtime } = statSync(source);
+            utimesSync(index, atime, mtime);
+        }
         const env = { GIT_INDEX_FILE: index };
         const add = git(top, ["add", "--all", "--", ":/"], { env });
         if (!add.ok)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.124.28",
+  "version": "0.124.30",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/build-params.test.ts

@@ -194,3 +194,49 @@ describe("buildParamValues", () => {
     expect(buildParamValues([])).toEqual({});
   });
 });
+
+describe("resolveBuildParams — workspace flags (#4024)", () => {
+  const defs: BuildParamsConfig = { newCheckout: { type: "boolean", default: false, env: "NEW_CHECKOUT" }, tier: { type: "string", default: "light" } };
+  const flags = (value: boolean | undefined, gated = false) => ({ env: "prod", byParam: { newCheckout: { flag: "new-checkout", value } }, ...(gated ? { gated: true } : {}) });
+
+  test("a flag's value for the environment is recorded with source flag:<name>, ahead of the default", () => {
+    const r = resolveBuildParams(defs, { flags: flags(true) });
+    expect(r.errors).toEqual([]);
+    expect(r.provenance).toEqual([
+      { name: "newCheckout", value: true, source: "flag:new-checkout" },
+      { name: "tier", value: "light", source: "default" },
+    ]);
+  });
+
+  test("a flag that gives the environment no value leaves the parameter at its default", () => {
+    expect(resolveBuildParams(defs, { flags: flags(undefined) }).provenance[0]).toEqual({ name: "newCheckout", value: false, source: "default" });
+  });
+
+  test("where the environment has no gate, --param, --params-file and the env var still win over the flag", () => {
+    expect(resolveBuildParams(defs, { cli: { newCheckout: "false" }, flags: flags(true) }).provenance[0].source).toBe("cli");
+    expect(resolveBuildParams(defs, { fromFile: { newCheckout: false }, flags: flags(true) }).provenance[0].source).toBe("params-file");
+    expect(resolveBuildParams(defs, { env: { NEW_CHECKOUT: "false" }, flags: flags(true) }).provenance[0].source).toBe("env");
+  });
+
+  test("where the environment has a gate, --param, --params-file and the env var can't set a flag-backed parameter", () => {
+    const viaCli = resolveBuildParams(defs, { cli: { newCheckout: "true" }, flags: flags(false, true) });
+    expect(viaCli.errors).toEqual([
+      'build parameter "newCheckout" is backed by the flag "new-checkout", and "prod" has a gate, so --param can\'t set it; change the flag record and let the change go through the gate',
+    ]);
+    expect(viaCli.provenance.map((p) => p.name)).toEqual(["tier"]);
+    expect(resolveBuildParams(defs, { fromFile: { newCheckout: true }, flags: flags(false, true) }).errors[0]).toMatch(/so --params-file can't set it/);
+    expect(resolveBuildParams(defs, { env: { NEW_CHECKOUT: "true" }, flags: flags(false, true) }).errors[0]).toMatch(/so the env var NEW_CHECKOUT can't set it/);
+    // A parameter no flag backs is not affected.
+    expect(resolveBuildParams(defs, { cli: { tier: "big" }, flags: flags(false, true) }).errors).toEqual([]);
+  });
+
+  test("a flag that sets a parameter the config does not declare is an error", () => {
+    const r = resolveBuildParams({}, { flags: flags(true) });
+    expect(r.errors).toEqual([`flag "new-checkout" sets build parameter "newCheckout", which chant.config.ts's buildParams does not declare`]);
+  });
+
+  test("a flag value of the wrong type, or outside the enum, fails like any other source", () => {
+    const strict: BuildParamsConfig = { newCheckout: { type: "string", enum: ["a", "b"] } };
+    expect(resolveBuildParams(strict, { flags: { env: "prod", byParam: { newCheckout: { flag: "new-checkout", value: "c" } } } }).errors[0]).toMatch(/must be one of "a", "b", got "c"/);
+  });
+});

package/src/build-params.ts

@@ -73,6 +73,28 @@ export interface BuildParamsInput {
   fromFile?: Record<string, unknown>;
   /** The process environment, consulted only for a parameter that declares an `env` mapping, and only once `cli`/`fromFile` have no value for it. */
   env?: Record<string, string | undefined>;
+  /**
+   * The workspace flags that back parameters in this build's environment
+   * (#4024), read by `./flag-params.ts`. A flag-backed parameter takes the
+   * flag's value for the environment, recorded with `source: "flag:<id>"`,
+   * ahead of its `env` mapping and its default. Absent outside a workspace
+   * and without `--env`.
+   */
+  flags?: BuildParamFlags;
+}
+
+/** The flags that back parameters in one environment (#4024). */
+export interface BuildParamFlags {
+  /** The environment the build is for. */
+  env: string;
+  /** Each flag-backed parameter by name: the flag's name, and its value in `env` (undefined when the flag gives it none). */
+  byParam: Record<string, { flag: string; value: BuildParamValue | undefined }>;
+  /**
+   * The environment has a gate (#4024's precedence rule): a `--param`,
+   * `--params-file` or env-var value for a flag-backed parameter is refused,
+   * so no path flips a flag around the gate.
+   */
+  gated?: boolean;
 }
 
 /** Result of resolving a project's declared parameters against one build invocation's inputs. */
@@ -118,7 +140,11 @@ function coerce(name: string, raw: BuildParamValue, def: BuildParamDef, errors:
  * Resolve a project's declared build-time parameters against one build's
  * supplied inputs. Precedence per parameter, most to least specific:
  * `cli` (`--param name=value`) > `fromFile` (`--params-file`) > the
- * parameter's own declared `env` mapping (only if set) > `def.default`.
+ * parameter's own declared `env` mapping (only if set) > a workspace flag's
+ * value for the build's environment (`input.flags`, #4024) > `def.default`.
+ * When `input.flags.gated` is set, a flag-backed parameter takes none of the
+ * first three: a value from any of them is a build error, so a flag can't be
+ * flipped around the environment's gate.
  *
  * A parameter with no declared `default` and no value from any source is a
  * build error, not a silently-`undefined` value — a build-time parameter
@@ -153,9 +179,26 @@ export function resolveBuildParams(defs: BuildParamsConfig | undefined, input: B
     }
   }
 
+  const flags = input.flags;
+  for (const [name, binding] of Object.entries(flags?.byParam ?? {})) {
+    if (!(name in declared)) {
+      errors.push(`flag "${binding.flag}" sets build parameter "${name}", which chant.config.ts's buildParams does not declare`);
+    }
+  }
+
   for (const [name, def] of Object.entries(declared)) {
     let raw: BuildParamValue | undefined;
     let source: BuildParamProvenance["source"] | undefined;
+    const binding = flags?.byParam[name];
+
+    if (binding && flags?.gated) {
+      // #4024: in an environment with a gate, the flag record is the only way to set the parameter.
+      const around = name in cli ? "--param" : name in fromFile ? "--params-file" : def.env && env[def.env] !== undefined ? `the env var ${def.env}` : null;
+      if (around !== null) {
+        errors.push(flagGateRefusal(name, binding.flag, flags.env, around));
+        continue;
+      }
+    }
 
     if (name in cli) {
       raw = cli[name];
@@ -171,6 +214,9 @@ export function resolveBuildParams(defs: BuildParamsConfig | undefined, input: B
     } else if (def.env && env[def.env] !== undefined) {
       raw = env[def.env];
       source = "env";
+    } else if (binding && binding.value !== undefined) {
+      raw = binding.value;
+      source = `flag:${binding.flag}`;
     } else if (def.default !== undefined) {
       raw = def.default;
       source = "default";
@@ -201,6 +247,14 @@ export function resolveBuildParams(defs: BuildParamsConfig | undefined, input: B
   return { provenance, errors };
 }
 
+/**
+ * The build error for a flag-backed parameter that `around` (`--param`,
+ * `--params-file` or an env var) set in an environment with a gate (#4024).
+ */
+export function flagGateRefusal(name: string, flag: string, env: string, around: string): string {
+  return `build parameter "${name}" is backed by the flag "${flag}", and "${env}" has a gate, so ${around} can't set it; change the flag record and let the change go through the gate`;
+}
+
 /** Project the resolved provenance records down to a plain `{ name: value }` map — what actually gets bound to `params.<name>` (see ./params.ts). */
 export function buildParamValues(provenance: readonly BuildParamProvenance[]): Record<string, BuildParamValue> {
   return Object.fromEntries(provenance.map((p) => [p.name, p.value]));

package/src/change-set-graph.ts

@@ -13,7 +13,8 @@
  * {@link changeSetNodeCandidates} lists the ids an entry's address can have,
  * by planner. {@link mapChangeSetToGraph} keeps the first that the graph
  * holds and puts the member's name in front, as `chant workspace graph`
- * does. An entry whose address the graph does not hold gets `node: null`:
+ * does, with the node's source file as `source` when the graph gives one
+ * (#4025). An entry whose address the graph does not hold gets `node: null`:
  * a delete of a block the source no longer declares, or a warden or sql
  * change outside the graph.
  *
@@ -31,6 +32,12 @@ export interface ChangeSetGraphNodes {
   at: string | null;
   /** Every node id of the member's `chant graph --format ir`, without the member in front. */
   ids: Iterable<string>;
+  /**
+   * The source file of each node that has one (#4025), by the same ids, as a
+   * path from the repository root. An entry mapped onto such a node gets it
+   * as `source`.
+   */
+  sources?: ReadonlyMap<string, string>;
 }
 
 /**
@@ -126,7 +133,8 @@ export function mapChangeSetToGraph(doc: ChangeSetDocument, graph: ChangeSetGrap
     ...doc,
     entries: doc.entries.map((e) => {
       const id = changeSetNodeCandidates(e).find((c) => ids.has(c));
-      return { ...e, node: id === undefined ? null : `${prefix}${id}` };
+      const source = id === undefined ? undefined : graph.sources?.get(id);
+      return { ...e, node: id === undefined ? null : `${prefix}${id}`, ...(source !== undefined ? { source } : {}) };
     }),
     graph: { member: graph.member, at: graph.at },
   };

package/src/change-set.ts

@@ -122,6 +122,16 @@ export interface ChangeSetEntry {
    * part of the digest.
    */
   node?: string | null;
+  /**
+   * The source file that declares the entry's node, from the repository
+   * root (#4025): the node's `sourceLoc.file` in the member's graph IR, with
+   * the member's directory in front. Set beside `node` when a stored change
+   * set is mapped onto a graph whose node has a source location, absent
+   * otherwise. Like `node`, never part of the digest. The overlap report
+   * attributes the entry to a work item through the commits that changed
+   * this file.
+   */
+  source?: string;
 }
 
 /** Something a planner could not read, so the plan says nothing about it. */
@@ -288,12 +298,13 @@ export function changeSetDocumentDigest(
     .filter((m) => !provisional.has(m.member))
     .map((m) => ({ member: m.member, status: m.status, holes: m.holes }))
     .sort((a, b) => byString(a.member, b.member));
-  // An entry's graph node (#4022) says where on the graph the change is,
-  // not what the plan does, so it stays outside the digest: mapping a stored
+  // An entry's graph node (#4022) and its source file (#4025) say where on
+  // the graph the change is, not what the plan does, so they stay outside
+  // the digest: mapping a stored
   // document onto a graph never moves the value its gate bound.
   const entries = doc.entries
     .filter((e) => !provisional.has(e.member))
-    .map(({ node: _node, ...e }) => e)
+    .map(({ node: _node, source: _source, ...e }) => e)
     .sort((a, b) => byString(entryKey(a), entryKey(b)));
   const sideEffects = (doc.sideEffects ?? []).filter((s) => !provisional.has(s.member)).sort(bySideEffect);
   const planned =