@intentius/chant-lexicon-terraform 0.102.0 → 0.104.0

package/dist/op/activity-contracts.d.ts

@@ -43,6 +43,7 @@ export declare const terraformPlanContract: import("@intentius/chant/op").Activi
     cwd?: string | undefined;
     planFile?: string | undefined;
     destroy?: boolean | undefined;
+    vars?: Record<string, unknown> | undefined;
 }, {
     adds: number;
     changes: number;
@@ -53,6 +54,14 @@ export declare const terraformPlanContract: import("@intentius/chant/op").Activi
     json: unknown;
     text: string;
     planDigest: string;
+    changeSet: {
+        member: {
+            [x: string]: unknown;
+            member: string;
+            planDigest: string | null;
+        };
+        entries: unknown[];
+    };
 }>;
 export declare const terraformApplyContract: import("@intentius/chant/op").ActivityContract<{
     root: string;
@@ -146,4 +155,43 @@ export declare const choudoufuAdoptContract: import("@intentius/chant/op").Activ
     ambiguous: number;
     dir: string;
 }>;
+/**
+ * `terraformPinRollout` (#3189). It names no `terraform.roots` key: a rollout
+ * moves a module's pin across many roots, found by directory, so it carries no
+ * `rootEntity`. `status` and `summary` are the fields an Op reads: the run's
+ * outcome and a body for a report step.
+ */
+export declare const terraformPinRolloutContract: import("@intentius/chant/op").ActivityContract<{
+    module: string;
+    from: string;
+    to: string;
+    roots?: {
+        root: string;
+        dependsOn?: string[] | undefined;
+        tsSource?: string | undefined;
+    }[] | undefined;
+    canaries?: string[] | undefined;
+    wavesFrom?: string | undefined;
+    wavesPrefix?: string | undefined;
+    mode?: "pull-request" | "report" | undefined;
+    base?: string | undefined;
+    remote?: string | undefined;
+    appliedCheck?: string | undefined;
+    cwd?: string | undefined;
+}, {
+    module: string;
+    from: string;
+    to: string;
+    mode: "pull-request" | "report";
+    base: string;
+    status: "complete" | "opened" | "stopped" | "waiting" | "would-open";
+    roots: {
+        [x: string]: unknown;
+    }[];
+    waves: {
+        [x: string]: unknown;
+    }[];
+    stop?: string | undefined;
+    summary: string;
+}>;
 //# sourceMappingURL=activity-contracts.d.ts.map

package/dist/op/activity-contracts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"activity-contracts.d.ts","sourceRoot":"","sources":["../../src/op/activity-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AA+BH,eAAO,MAAM,qBAAqB;;;;;;;;EASjC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;EAiBjC,CAAC;AAEF,eAAO,MAAM,sBAAsB;;;;;;;;;;EAWlC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;EAYjC,CAAC;AAEF,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;EAwBrC,CAAC;AAEF,eAAO,MAAM,uBAAuB;;;;;;;;;EASnC,CAAC;AAEF,eAAO,MAAM,0BAA0B;;;;;;;;EAKtC,CAAC;AAEF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;EAgBlC,CAAC"}
+{"version":3,"file":"activity-contracts.d.ts","sourceRoot":"","sources":["../../src/op/activity-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AA+BH,eAAO,MAAM,qBAAqB;;;;;;;;EASjC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;EAoBjC,CAAC;AAEF,eAAO,MAAM,sBAAsB;;;;;;;;;;EAWlC,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;EAYjC,CAAC;AAEF,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;EAwBrC,CAAC;AAEF,eAAO,MAAM,uBAAuB;;;;;;;;;EASnC,CAAC;AAEF,eAAO,MAAM,0BAA0B;;;;;;;;EAKtC,CAAC;AAEF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;EAgBlC,CAAC;AAKF;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4BvC,CAAC"}

package/dist/op/builders.d.ts

@@ -16,6 +16,7 @@
  */
 import { type ActivityStep, type NamedActivityStep, type WithStepRefs } from "@intentius/chant/op";
 import type { TerraformInitArgs, TerraformPlanArgs, TerraformApplyArgs, TerraformShowArgs, ChoudoufuLivePlanArgs, ChoudoufuLiveLsArgs, ChoudoufuLiveCheckArgs, ChoudoufuAdoptArgs } from "./activities/terraform.js";
+import type { TerraformPinRolloutArgs } from "./activities/pin-rollout.js";
 /** Extra opts every wrapper below accepts alongside its activity's own fields. */
 type StepOpts = {
     profile?: ActivityStep["profile"];
@@ -94,5 +95,13 @@ export declare const choudoufuAdopt: (root: string, opts: WithStepRefs<Omit<Chou
  * provider.
  */
 export declare const terraformShow: (root: string, opts?: WithStepRefs<Omit<TerraformShowArgs, "root">> & StepOpts) => NamedActivityStep;
+/**
+ * One run of a pin-bump rollout (#3189). `opts` is
+ * {@link TerraformPinRolloutArgs} itself. It names no root: the rollout finds
+ * the roots that call the module. Defaults to the `fastIdempotent` profile: a
+ * repeated run reads the forge again and finds the PR an earlier attempt
+ * opened.
+ */
+export declare const terraformPinRollout: (opts: WithStepRefs<TerraformPinRolloutArgs> & StepOpts) => NamedActivityStep;
 export {};
 //# sourceMappingURL=builders.d.ts.map

package/dist/op/builders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../src/op/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,EACtB,kBAAkB,EACnB,MAAM,wBAAwB,CAAC;AAEhC,kFAAkF;AAClF,KAAK,QAAQ,GAAG;IAAE,OAAO,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnE;;;;;GAKG;AACH,eAAO,MAAM,aAAa,SAClB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAC9D,iBAGF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,SAClB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAC9D,iBAGF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,SACnB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAC/D,iBAGF,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,SACtB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAClE,iBAOF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,SACpB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAChE,iBAOF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,SACvB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,sBAAsB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KACnE,iBAOF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,SACnB,MAAM,QACN,YAAY,CAAC,IAAI,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAC9D,iBAOF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,SAClB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAC9D,iBAOF,CAAC"}
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../src/op/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,EACtB,kBAAkB,EACnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAExE,kFAAkF;AAClF,KAAK,QAAQ,GAAG;IAAE,OAAO,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnE;;;;;GAKG;AACH,eAAO,MAAM,aAAa,SAClB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAC9D,iBAGF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,SAClB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAC9D,iBAGF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,SACnB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAC/D,iBAGF,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,SACtB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAClE,iBAOF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,SACpB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAChE,iBAOF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,SACvB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,sBAAsB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KACnE,iBAOF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,SACnB,MAAM,QACN,YAAY,CAAC,IAAI,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAC9D,iBAOF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,SAClB,MAAM,SACL,YAAY,CAAC,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC,GAAG,QAAQ,KAC9D,iBAOF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,SAAU,YAAY,CAAC,uBAAuB,CAAC,GAAG,QAAQ,KAAG,iBAG5F,CAAC"}

package/dist/pin/edit-ts.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The pin edit for a root chant generates (#3189): move the pin in the
+ * module declaration of its TypeScript source, not in the `.tf` a build
+ * writes from it.
+ *
+ * A module declaration in TypeScript is an object literal with the same
+ * arguments the HCL block has: a `source` string, and a `version` string
+ * beside a registry source. Any object literal whose `source` is a plain
+ * string naming the module counts, whatever function or constructor receives
+ * it. The TypeScript compiler parses the file, so a `source:` inside a
+ * comment, a template with substitutions, or another string is never a
+ * match, and the edit replaces the string literal's content only. Every other
+ * byte of the file stays as it was.
+ *
+ * It needs the TypeScript compiler, so `./index.ts` (the bundled subpath,
+ * #3421) does not import it. The rollout takes it as `editTs`.
+ */
+import type { PinEditResult, PinRequest } from "./edit.js";
+/** Move `request.module`'s pin in one TypeScript file. */
+export declare function editPinsInTs(text: string, file: string, request: PinRequest): PinEditResult;
+//# sourceMappingURL=edit-ts.d.ts.map

package/dist/pin/edit-ts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit-ts.d.ts","sourceRoot":"","sources":["../../src/pin/edit-ts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAiB,aAAa,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAwBvE,0DAA0D;AAC1D,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,aAAa,CAgC3F"}

package/dist/pin/edit.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The pin edit for hand-written HCL (#3189): move one module's pin from an old
+ * version to a new one in a `.tf` file or a `terragrunt.hcl`, and leave every
+ * other byte of the file as it was.
+ *
+ * Three steps, each one a check on the last:
+ *
+ * 1. The HCL reader (`@cdktn/hcl2json`, the parser the rest of this lexicon
+ *    reads `.tf` with) parses the file. Its tree says which calls exist and
+ *    what each one's `source` and `version` are: `module "<name>"` blocks in a
+ *    `.tf`, and the `terraform` block's `source` in a `terragrunt.hcl`.
+ * 2. `./source.ts` decides, per call, whether it names the module and how its
+ *    pin moves. `./scan.ts` finds the byte offsets of the literal to rewrite,
+ *    and its unescaped content has to equal the value the reader returned, or
+ *    the call is refused rather than guessed at.
+ * 3. The edited text is parsed again. Its tree has to equal the first tree
+ *    with only the moved values changed. Anything else throws, and nothing is
+ *    written.
+ *
+ * The parser is passed in rather than imported. It is a 1.8 MB wasm package
+ * that core loads lazily (`loadHcl2json`), and a caller that bundles this
+ * module (terragucci's `tf-rollout` stage, #3421) decides how it is loaded.
+ */
+import type { Hcl2Json } from "@intentius/chant/terraform/hcl2json";
+import { type PinMove } from "./source.js";
+/** What to move: a module, named by its source without the pin, from one pin to another. */
+export interface PinRequest {
+    module: string;
+    from: string;
+    to: string;
+}
+/** One module call the edit looked at, and what happened to it. */
+export type PinCallResult = PinMove & {
+    /** The file, as the caller named it. */
+    file: string;
+    /** `module.<name>` in a `.tf`, `terraform` in a `terragrunt.hcl`, or `line <n>` in TypeScript source. */
+    call: string;
+};
+/** The edited text and every call that names the module. */
+export interface PinEditResult {
+    content: string;
+    calls: PinCallResult[];
+}
+/** Whether a file is read as a Terragrunt configuration rather than a `.tf` file. */
+export declare function isTerragruntFile(file: string): boolean;
+/**
+ * Move `request.module`'s pin in one file. Calls that name another module are
+ * left alone and not reported. A call that names the module and cannot move
+ * is reported with its reason and left as it was.
+ */
+export declare function editPins(text: string, file: string, request: PinRequest, parser: Hcl2Json): Promise<PinEditResult>;
+//# sourceMappingURL=edit.d.ts.map

package/dist/pin/edit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit.d.ts","sourceRoot":"","sources":["../../src/pin/edit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qCAAqC,CAAC;AACpE,OAAO,EAAW,KAAK,OAAO,EAAE,MAAM,UAAU,CAAC;AAGjD,4FAA4F;AAC5F,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,mEAAmE;AACnE,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG;IACpC,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,yGAAyG;IACzG,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,4DAA4D;AAC5D,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,aAAa,EAAE,CAAC;CACxB;AAED,qFAAqF;AACrF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AA2CD;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC,CAgDxH"}

package/dist/pin/forge.d.ts

@@ -0,0 +1,39 @@
+/**
+ * What a pin-bump rollout asks the forge (#3189): find a wave's pull request
+ * by its branch, open one, and read the checks on the commit a merge made.
+ *
+ * The default answers through `gh`, the way core's `proposeWorkspaceUpgrade`
+ * (#2550) opens its pull request: `gh pr list --head`, `gh pr create`, and
+ * `gh api` for the commit's check runs and statuses. A test, or a caller with
+ * its own forge client, passes a {@link PinForge} instead.
+ */
+import type { CommandRunner } from "@intentius/chant/op/activities/propose-upgrade";
+/** A wave's pull request, as the forge reports it. */
+export interface PinPullRequest {
+    url: string;
+    state: "open" | "merged" | "closed";
+    body: string;
+    /** The commit the merge made on the base branch, once merged. */
+    mergeCommit?: string;
+}
+/** One check or status on a commit. */
+export interface PinCommitCheck {
+    name: string;
+    state: "success" | "pending" | "failure";
+}
+export interface PinForge {
+    /** The newest pull request whose head is `branch`, in any state, or null. */
+    findPullRequest(branch: string): Promise<PinPullRequest | null>;
+    /** Open a pull request and return its URL. */
+    createPullRequest(input: {
+        base: string;
+        head: string;
+        title: string;
+        body: string;
+    }): Promise<string>;
+    /** The checks and statuses on a commit. */
+    commitChecks(sha: string): Promise<PinCommitCheck[]>;
+}
+/** A {@link PinForge} over `gh`, run in `repo`. */
+export declare function ghPinForge(run: CommandRunner, repo: string): PinForge;
+//# sourceMappingURL=forge.d.ts.map

package/dist/pin/forge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forge.d.ts","sourceRoot":"","sources":["../../src/pin/forge.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gDAAgD,CAAC;AAEpF,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,uCAAuC;AACvC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;CAC1C;AAED,MAAM,WAAW,QAAQ;IACvB,6EAA6E;IAC7E,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAChE,8CAA8C;IAC9C,iBAAiB,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvG,2CAA2C;IAC3C,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;CACtD;AAgBD,mDAAmD;AACnD,wBAAgB,UAAU,CAAC,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,CAiCrE"}

package/dist/pin/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Pin-bump rollouts (#3189): the pin edit, the wave plan, and the run that
+ * opens one pull request per wave.
+ *
+ * This subpath, `@intentius/chant-lexicon-terraform/pin`, bundles without the
+ * TypeScript toolchain, zod, or chant's fold, lint and codegen modules, so
+ * terragucci's `tf-rollout` stage can run it from one bundled file (#3421).
+ * `./bundle.test.ts` holds it to that. The HCL parser is passed in, and the
+ * TypeScript editor for generated roots lives in `./edit-ts.ts`, which this
+ * index does not import.
+ */
+export { readModulePin, movePin, moduleOf, exactVersion, isPinValue, checkPinRequest } from "./source.js";
+export type { ModuleCallPin, PinMove, PinParam } from "./source.js";
+export { editPins, isTerragruntFile } from "./edit.js";
+export type { PinRequest, PinCallResult, PinEditResult } from "./edit.js";
+export { planPinWaves, wavesFromChoudoufu, restrictWaves, terragruntDependencies, PinWavePlanError } from "./waves.js";
+export type { PinRoot, PinWave } from "./waves.js";
+export { ghPinForge } from "./forge.js";
+export type { PinForge, PinPullRequest, PinCommitCheck } from "./forge.js";
+export { runPinRollout, renderPinRollout, pinWaveBranch } from "./rollout.js";
+export type { PinRolloutOptions, PinRolloutResult, PinRolloutMode, PinRootState, PinWaveState, PinWaveStatus, TsPinEditor } from "./rollout.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/pin/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pin/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AACvG,YAAY,EAAE,aAAa,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACjE,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AACpD,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AACpH,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC3E,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,cAAc,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC"}

package/dist/pin/rollout.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Roll a module version out as pin-bump pull requests, one wave at a time
+ * (#3189, choudoufu#1749).
+ *
+ * Each run reads where the rollout stands and does at most one thing:
+ *
+ * 1. It checks out the base branch in a temporary worktree and reads every
+ *    root's pin there: at the old version, at the new one, refused (a
+ *    floating constraint, no pin, an expression), or pinned at something
+ *    else. Only roots at the old or the new version are in the rollout, so
+ *    the wave plan is the same on every run.
+ * 2. It splits those roots into waves (`./waves.ts`).
+ * 3. It walks the waves in order, reading each wave's pull request by its
+ *    branch. A wave whose PR merged, and whose every moved root reports its
+ *    apply check as passed on the merge commit, is done. The first wave that
+ *    is not done decides the run:
+ *    - no PR yet: open it (one branch, one PR, the pin moved for that wave's
+ *      roots only), or in `report` mode say it would;
+ *    - PR open, or merged with an apply still pending: report where it
+ *      stands and open nothing;
+ *    - PR closed without merging, or a root whose apply check failed: stop,
+ *      naming it. The waves after it do not open.
+ *
+ * That is #2119's gate as a fact: nothing waits. The next run reads the
+ * forge again and either moves on or reports the same place.
+ *
+ * The PR's branch is built from the base branch in a worktree and pushed.
+ * The default branch, and whatever the caller has checked out, are never
+ * written, as with core's `proposeWorkspaceUpgrade` (#2550). Each PR changes
+ * only the files of its wave's roots, so a path-diff selection (GitLab's
+ * `rules: changes:`, #3183's affected members) plans exactly those roots.
+ *
+ * An "applied" root is one whose apply check, named by `appliedCheck`
+ * (default `apply/{root}`), passed on the merge commit. That is how a
+ * per-root apply job on the merged commit reports today; when the per-PR
+ * loop (#3183) lands, its per-member check name is the one to pass.
+ */
+import type { Hcl2Json } from "@intentius/chant/terraform/hcl2json";
+import type { CommandRunner } from "@intentius/chant/op/activities/propose-upgrade";
+import { type PinCallResult, type PinEditResult, type PinRequest } from "./edit.js";
+import { type PinRoot, type PinWave } from "./waves.js";
+import { type PinForge } from "./forge.js";
+/** Edits the module declaration in a generated root's TypeScript source (`./edit-ts.ts`). */
+export type TsPinEditor = (text: string, file: string, request: PinRequest) => PinEditResult;
+export type PinRolloutMode = "report" | "pull-request";
+export interface PinRolloutOptions extends PinRequest {
+    /** A directory inside the repository. Default: the working directory. */
+    cwd?: string;
+    /** The roots to roll out. Default: every directory under the repository with a `.tf` file or a `terragrunt.hcl` that calls the module. */
+    roots?: PinRoot[];
+    /** Roots that form wave 1. */
+    canaries?: string[];
+    /** A wave plan to use instead of canaries and dependency order, such as {@link wavesFromChoudoufu}'s. */
+    waves?: PinWave[];
+    /** `report` (default) opens nothing; `pull-request` opens the next wave's PR when it is due. */
+    mode?: PinRolloutMode;
+    /** The branch PRs target. Default: the remote's default branch. */
+    base?: string;
+    /** Default `origin`. */
+    remote?: string;
+    /** The check each moved root's apply reports on the merge commit. `{root}` is the root's directory. Default `apply/{root}`. */
+    appliedCheck?: string;
+    /** The HCL reader, `loadHcl2json()` from `@intentius/chant/terraform/hcl2json`. */
+    parser: Hcl2Json;
+    /** The forge. Default: `gh`, through `run`. */
+    forge?: PinForge;
+    /** Runs `git` (and `gh`, for the default forge). For tests. */
+    run?: CommandRunner;
+    /** The TypeScript editor for generated roots. Without it, a root with `tsSource` is refused. */
+    editTs?: TsPinEditor;
+    /** Markdown appended to a wave's PR body, such as the grouped plan summary of #3188 once a caller has the wave's plans. */
+    planSummary?: (wave: PinWave) => Promise<string | undefined>;
+}
+/** Where one root's pin stood on the base branch. */
+export interface PinRootState {
+    root: string;
+    /** `from`: at least one call moves; `to`: every call is already moved; the rest are not in the rollout. */
+    state: "from" | "to" | "refused" | "elsewhere" | "absent";
+    files: string[];
+    calls: PinCallResult[];
+    reason?: string;
+}
+export type PinWaveState = "applied" | "nothing-to-move" | "opened" | "would-open" | "open" | "waiting-apply" | "failed" | "closed" | "not-reached";
+export interface PinWaveStatus extends PinWave {
+    branch: string;
+    state: PinWaveState;
+    pr?: string;
+    /** Roots whose apply check has not reported yet. */
+    pending?: string[];
+    /** Roots whose apply check failed. */
+    failed?: string[];
+    /** Files the wave's PR changes (`opened` and `would-open`). */
+    files?: string[];
+}
+export interface PinRolloutResult extends PinRequest {
+    mode: PinRolloutMode;
+    base: string;
+    /**
+     * `complete`: every wave applied. `opened`/`would-open`: the next wave's PR
+     * was opened, or would be. `waiting`: a PR is open or an apply has not
+     * reported. `stopped`: a root failed or a PR closed unmerged, and `stop` says
+     * which.
+     */
+    status: "complete" | "opened" | "would-open" | "waiting" | "stopped";
+    roots: PinRootState[];
+    waves: PinWaveStatus[];
+    stop?: string;
+    summary: string;
+}
+/** The branch a wave's PR is opened from. */
+export declare function pinWaveBranch(request: PinRequest, wave: number): string;
+/** Read where a rollout stands, and open the next wave's PR when it is due and `mode` is `pull-request`. */
+export declare function runPinRollout(options: PinRolloutOptions): Promise<PinRolloutResult>;
+/** The rollout for a terminal or a run log. */
+export declare function renderPinRollout(result: Omit<PinRolloutResult, "summary">): string;
+//# sourceMappingURL=rollout.d.ts.map

package/dist/pin/rollout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollout.d.ts","sourceRoot":"","sources":["../../src/pin/rollout.ts"],"names":[],"mappings":"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"}

package/dist/pin/scan.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Byte offsets for the attribute values the pin edit rewrites (#3189).
+ *
+ * `@cdktn/hcl2json` is the reader that says what a file means, and the pin
+ * edit asks it first (`./edit.ts`). It gives back values and no positions
+ * (`../hcl/value.ts` says why), so it cannot say WHERE in the file a
+ * `source` or `version` literal sits. This lexer answers only that: it walks
+ * the raw text token by token, skipping comments, quoted strings, template
+ * interpolations and heredocs, counts braces, and records each top-level
+ * block and the plain string literal of each of its own attributes, with the
+ * literal's offsets.
+ *
+ * It is an HCL tokenizer, not a pattern match over lines: a `source =` inside
+ * a comment, a heredoc or another string is never a match, and a block opened
+ * on the same line as its attributes reads the same as one split over lines.
+ * What it finds is checked against the reader before anything is written:
+ * the literal's unescaped value has to equal what hcl2json read for that
+ * attribute, and the edited file has to parse to the same tree with only the
+ * pinned values changed.
+ */
+/** One plain string literal: the offsets of its content, quotes excluded. */
+export interface ScannedLiteral {
+    start: number;
+    end: number;
+    /** The content as written, escapes included. */
+    raw: string;
+}
+/** One attribute of a block body. `literal` is set when the value is a single string with no interpolation. */
+export interface ScannedAttribute {
+    name: string;
+    literal?: ScannedLiteral;
+}
+/** One top-level block: `module "vpc" { ... }`, `terraform { ... }`. */
+export interface ScannedBlock {
+    type: string;
+    labels: string[];
+    /** Offset of the block's type keyword. */
+    start: number;
+    /** Offset just past the closing brace. */
+    end: number;
+    /** The block body's own attributes, in file order. Nested blocks' attributes are not included. */
+    attributes: ScannedAttribute[];
+}
+/** Thrown when the text is not well-formed enough to place an edit in. */
+export declare class HclScanError extends Error {
+    constructor(file: string, message: string);
+}
+/** Every top-level block in `text`, with its own attributes' literals. */
+export declare function scanBlocks(text: string, file: string): ScannedBlock[];
+/** Undo HCL's string escapes, so a literal's raw text compares to the value the reader returned. */
+export declare function unescapeHcl(raw: string): string;
+/** Write a value as the content of an HCL string literal. */
+export declare function escapeHcl(value: string): string;
+//# sourceMappingURL=scan.d.ts.map

package/dist/pin/scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../../src/pin/scan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,6EAA6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;CACb;AAED,+GAA+G;AAC/G,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,kGAAkG;IAClG,UAAU,EAAE,gBAAgB,EAAE,CAAC;CAChC;AAYD,0EAA0E;AAC1E,qBAAa,YAAa,SAAQ,KAAK;IACrC,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAGxC;CACF;AAmID,0EAA0E;AAC1E,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,EAAE,CAgCrE;AAkDD,oGAAoG;AACpG,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAyB/C;AAED,6DAA6D;AAC7D,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C"}

package/dist/pin/source.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Where a module call keeps its pin, and how the pin moves (#3189).
+ *
+ * A module call names a module and, if it is pinned, one exact version of it.
+ * The version sits in one of two places:
+ *
+ * - the `version` argument, beside a registry `source`
+ *   (`source = "app.terraform.io/acme/vpc/aws"`, `version = "1.3.0"`);
+ * - a query argument of the `source` itself: OpenTofu's `oci://` sources take
+ *   `?tag=` or `?digest=`, a git source takes `?ref=`, and Terragrunt's
+ *   `tfr://` source takes `?version=`.
+ *
+ * The module's identity is the source with the pin taken out, so
+ * `oci://r.example.com/m/vpc?tag=1.3.0` and `oci://r.example.com/m/vpc?tag=1.4.0`
+ * call the same module.
+ *
+ * A `version` constraint (`~> 1.4`, `>= 1.4, < 2`) is not a pin. An upstream
+ * release changes what such a root runs with no diff to review, and there is
+ * no single version to move, so the call is refused with that reason. The
+ * same holds for a call with no pin at all.
+ *
+ * OpenTofu writes an OCI pin as a query argument
+ * (https://opentofu.org/docs/language/modules/sources/#oci-distribution-registries),
+ * not as a `:tag` or `@sha256:` suffix on the repository, so the query form is
+ * the one read here.
+ *
+ * This module is pure string work over values the HCL reader has already
+ * parsed. Finding those values in a file, and writing the new ones back, is
+ * `./edit.ts`. #3190 adds an `oci` kind to the lint classifier
+ * (`../lint/post-synth/module-source.ts`) with the same parse; the two can
+ * share one once both have landed.
+ */
+/** The query arguments that carry a pin. */
+export type PinParam = "tag" | "digest" | "ref" | "version";
+/** What a module call pins, read from its `source` and `version`. */
+export interface ModuleCallPin {
+    /** The module the call names: its `source` with the pin argument taken out. */
+    module: string;
+    /** Where the pin is: the `version` argument, or a query argument of `source`. */
+    at: "version" | "source";
+    /** The query argument holding the pin, when `at` is `source`. */
+    param?: PinParam;
+    /** The pinned version, tag, digest or ref. Null when there is no pin to move. */
+    pin: string | null;
+    /** Why the call has no pin to move, when `pin` is null. */
+    unpinned?: string;
+}
+/** The outcome of moving one call's pin. */
+export type PinMove = {
+    outcome: "moved";
+    from: string;
+    to: string;
+    source: string;
+    version?: string;
+} | {
+    outcome: "already";
+    pin: string;
+} | {
+    outcome: "elsewhere";
+    pin: string;
+} | {
+    outcome: "refused";
+    reason: string;
+};
+/**
+ * The exact version a `version` argument pins, or null when it is a
+ * constraint. `1.4.0` and `= 1.4.0` are exact; `~> 1.4`, `>= 1.4` and
+ * `1.4.0, < 2` are not.
+ */
+export declare function exactVersion(constraint: string): string | null;
+/** Whether a value can be a pin's new value: an exact version, a tag, a ref or a digest, never a constraint. */
+export declare function isPinValue(value: string): boolean;
+/** Read the pin a module call carries. `version` is the call's `version` argument, when it has one. */
+export declare function readModulePin(source: string, version?: string): ModuleCallPin;
+/**
+ * Move a call's pin from `from` to `to`, when the call names `module`.
+ * Returns null when it names another module. `version` keeps any `=` it was
+ * written with, so `= 1.3.0` becomes `= 1.4.0`.
+ */
+export declare function movePin(source: string, version: string | undefined, request: {
+    module: string;
+    from: string;
+    to: string;
+}): PinMove | null;
+/** The module a source names, with any pin taken out, so a caller may name the module by a pinned source. */
+export declare function moduleOf(source: string): string;
+/** Refuse a request whose `to` is not something a pin can hold. */
+export declare function checkPinRequest(request: {
+    module: string;
+    from: string;
+    to: string;
+}): void;
+//# sourceMappingURL=source.d.ts.map

package/dist/pin/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../src/pin/source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,4CAA4C;AAC5C,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;AAE5D,qEAAqE;AACrE,MAAM,WAAW,aAAa;IAC5B,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,EAAE,EAAE,SAAS,GAAG,QAAQ,CAAC;IACzB,iEAAiE;IACjE,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,iFAAiF;IACjF,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,4CAA4C;AAC5C,MAAM,MAAM,OAAO,GACf;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAChF;IAAE,OAAO,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,OAAO,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,OAAO,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAQ3C;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG9D;AAED,gHAAgH;AAChH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEjD;AA6CD,uGAAuG;AACvG,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,aAAa,CAO7E;AA4CD;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,GAAG,IAAI,CAa1I;AAED,6GAA6G;AAC7G,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,mEAAmE;AACnE,wBAAgB,eAAe,CAAC,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAM3F"}

package/dist/pin/waves.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The wave plan for a pin-bump rollout (#3189): which roots move in which PR.
+ *
+ * Two sources give the same shape, an ordered list of root lists:
+ *
+ * - **Declared canaries, then dependency order.** The canaries form wave 1.
+ *   Every other root lands in the earliest wave after every root it depends
+ *   on. That is the Kahn layering `chant components fan-out` uses
+ *   (`resolveComponentGraph`, `@intentius/chant/components/layers`), and the
+ *   order #3049 gives its gated waves. A canary that depends on a root outside
+ *   the canaries is refused, since wave 1 would apply before what it reads.
+ * - **choudoufu's wave planner** (`choudoufu live-waves -json`, choudoufu#1754).
+ *   It reads cross-estate references from the estates' own configuration, puts
+ *   `-canary` roots in wave 1, and emits each wave's roots on their own, so
+ *   {@link wavesFromChoudoufu} takes its document as it is.
+ *
+ * A root's dependencies come from the caller (`dependsOn`) and, for a
+ * Terragrunt unit, from its `dependency` and `dependencies` blocks
+ * ({@link terragruntDependencies}). A dependency on a root outside the
+ * rollout orders nothing: it is not moving.
+ */
+import type { Hcl2Json } from "@intentius/chant/terraform/hcl2json";
+/** One root in a rollout. `root` is its directory, relative to the repository, with `/` separators. */
+export interface PinRoot {
+    root: string;
+    /** Roots this one reads, by directory. They land in an earlier wave. */
+    dependsOn?: string[];
+    /**
+     * The TypeScript file a generated root is built from. The pin edit then
+     * goes to the module declaration there rather than to the `.tf` chant
+     * writes (`./edit-ts.ts`).
+     */
+    tsSource?: string;
+}
+/** One wave: its number from 1, whether the declared canaries form it, and its roots, sorted. */
+export interface PinWave {
+    wave: number;
+    canary: boolean;
+    roots: string[];
+}
+/** Thrown when the roots cannot be split into waves. The message names the roots. */
+export declare class PinWavePlanError extends Error {
+    constructor(message: string);
+}
+/** Canaries first, then dependency order. */
+export declare function planPinWaves(roots: readonly PinRoot[], canaries?: readonly string[]): PinWave[];
+/**
+ * The waves of a `choudoufu live-waves -json` document (format version 1).
+ * `prefix` is the directory choudoufu ran in, relative to the repository,
+ * when its roots are named relative to that rather than to the repository.
+ */
+export declare function wavesFromChoudoufu(doc: unknown, prefix?: string): PinWave[];
+/**
+ * Keep only the roots in `keep`, renumbering the waves and dropping any left
+ * empty. A wave plan from choudoufu covers every root it was given; the
+ * rollout moves only the roots that call the module at the old or new pin.
+ */
+export declare function restrictWaves(waves: readonly PinWave[], keep: ReadonlySet<string>): PinWave[];
+/**
+ * The roots a Terragrunt unit depends on: each `dependency` block's
+ * `config_path` and the `dependencies` block's `paths`, resolved against the
+ * unit's directory. A path that is an expression is skipped, since it names
+ * no directory until Terragrunt evaluates it.
+ */
+export declare function terragruntDependencies(root: string, text: string, parser: Hcl2Json): Promise<string[]>;
+//# sourceMappingURL=waves.d.ts.map

package/dist/pin/waves.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"waves.d.ts","sourceRoot":"","sources":["../../src/pin/waves.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qCAAqC,CAAC;AAGpE,uGAAuG;AACvG,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,iGAAiG;AACjG,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,qFAAqF;AACrF,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED,6CAA6C;AAC7C,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,EAAE,QAAQ,GAAE,SAAS,MAAM,EAAO,GAAG,OAAO,EAAE,CAqBnG;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,SAAK,GAAG,OAAO,EAAE,CAUvE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,EAAE,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,OAAO,EAAE,CAO7F;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAS5G"}