@intentius/terragucci 0.3.1 → 0.4.1

package/dist/types.d.ts

@@ -1,24 +1,62 @@
 export declare const BINARIES: readonly ["terraform", "tofu", "choudoufu"];
 export declare const FORGES: readonly ["github", "gitlab", "forgejo"];
 export declare const GATES: readonly ["always", "on-destroy", "never"];
+/**
+ * What counts as the approval of a waiting wave (`approval:`). `ledger` (the
+ * default): any `chant approve` of the wave's set digest on chant/lifecycle,
+ * signed or not. `pr-review`: also the merged pull request's approving review
+ * of its head (on GitLab, an approval after its latest push), when the plans
+ * have not moved since (./review.ts). `sealed`: only one sealed with a key the signers file at base
+ * lists for its approver. Every mode binds the digest.
+ */
+export declare const APPROVALS: readonly ["ledger", "pr-review", "sealed"];
 /** Every stage runs on the forge's CI. */
 export declare const RUNTIMES: readonly ["forge"];
 export declare const DEPENDENTS: readonly ["follow", "plan"];
 export declare const POLICY_ENGINES: readonly ["conftest", "opa"];
 export declare const POLICY_INPUTS: readonly ["plan", "hcp"];
+/**
+ * When a pull request takes its root locks (`locks:`). `apply` (the default):
+ * when it applies before merge, or a writer comments `/terragucci lock`.
+ * `plan`: from its first plan, through the `pr-lock` job (GitHub and Forgejo;
+ * NO_GITLAB_PLAN_LOCKS), until it merges or closes, or a writer comments
+ * `/terragucci unlock`.
+ */
+export declare const LOCKS: readonly ["apply", "plan"];
 /** When a change applies: after it merges (default), or from its open pull request before it merges. */
 export declare const APPLY_WHEN: readonly ["merge", "pull-request"];
 /** With `apply.when: pull-request`, who merges once every wave applied: a person (default), or terragucci. */
 export declare const APPLY_MERGE: readonly ["manual", "auto"];
+/**
+ * With `apply.when: pull-request`, what an open pull request needs before a
+ * comment applies it: a reviewer's approval of its head (`approved`), a
+ * forge that says it can merge (`mergeable`: no conflicts, and on GitHub no
+ * branch protection blocking it), a head that contains the default branch
+ * (`undiverged`), and every status and check on the head passed (`checks`).
+ * All four by default.
+ */
+export declare const APPLY_REQUIRES: readonly ["approved", "mergeable", "undiverged", "checks"];
 export type Binary = (typeof BINARIES)[number];
 export type ForgeName = (typeof FORGES)[number];
 export type Gate = (typeof GATES)[number];
+export type Approval = (typeof APPROVALS)[number];
+/**
+ * `gitlab.token`: how a GitLab project keeps its forge token. `unprotected`
+ * (the default): the plan job posts its note with the token at once, so a
+ * merge request's code, which can rewrite the job, can use the token too.
+ * `protected`: the token is a protected variable that no merge request or
+ * branch pipeline sees, and the comments schedule's job posts the plan notes.
+ */
+export declare const TOKEN_PROTECTIONS: readonly ["unprotected", "protected"];
+export type GitLabToken = (typeof TOKEN_PROTECTIONS)[number];
 export type Runtime = (typeof RUNTIMES)[number];
 export type Dependents = (typeof DEPENDENTS)[number];
 export type PolicyEngine = (typeof POLICY_ENGINES)[number];
 export type PolicyInput = (typeof POLICY_INPUTS)[number];
 export type ApplyWhen = (typeof APPLY_WHEN)[number];
+export type Locks = (typeof LOCKS)[number];
 export type ApplyMerge = (typeof APPLY_MERGE)[number];
+export type ApplyRequire = (typeof APPLY_REQUIRES)[number];
 /**
  * `apply:`: when a change applies. `when: merge` (the default) applies the
  * default branch after a merge. `when: pull-request` applies an open pull
@@ -27,12 +65,19 @@ export type ApplyMerge = (typeof APPLY_MERGE)[number];
  * `merge: auto` merges the pull request once every wave applied, in a job of
  * its own, with the token in the secret `merge_token_env` names when it is
  * set (required on Forgejo, whose job token cannot push to the default
- * branch). Plain roots on GitHub and Forgejo only (NO_GITLAB_PR_APPLY).
+ * branch). `requires` lists what an open pull request needs before it
+ * applies (APPLY_REQUIRES, all by default). On every forge, for plain
+ * roots and Terragrunt units alike. On GitLab a merge request note starts no
+ * pipeline, so `when: pull-request` needs `comments:` (the schedule whose
+ * job reads `/terragucci apply`) and `merge_token_env`, a variable whose
+ * token may run pipelines on the default branch and merge there, with
+ * `merge: manual` too (PR_APPLY_NEEDS_ON_GITLAB).
  */
 export interface ApplySettings {
     when?: ApplyWhen;
     merge?: ApplyMerge;
     merge_token_env?: string;
+    requires?: ApplyRequire[];
 }
 /**
  * Policy as code, off unless set. `tf-plan` runs the engine over each planned
@@ -42,12 +87,24 @@ export interface ApplySettings {
 export interface PolicySettings {
     /** The engine. Default `conftest`, which terragucci installs on demand when it is not on the path. */
     engine?: PolicyEngine;
-    /** The directory of Rego policy, relative to the repo root. Default `policy`. */
+    /** The directory of Rego policy, relative to the repo root, or to the root of `source` when that is set. Default `policy`. */
     path?: string;
+    /**
+     * A shared policy repo, `git+https://<host>/<path>@<ref>`, read at that ref
+     * instead of the repo's own directory. The ref is a tag, a branch or a
+     * commit. Like the rest of the key, it is read at the base.
+     */
+    source?: string;
     /** The Rego package whose `deny`, `violation`, `deny_*` and `warn` rules count. conftest default: every namespace. opa default: `main`, or every package under `terraform.policies` with `input: hcp`. */
     namespace?: string;
     /** What `input` holds: `plan`, the bare plan JSON (default); `hcp`, `{plan, run}` as HCP Terraform's OPA policies read it. */
     input?: PolicyInput;
+    /**
+     * Who may override a denial: the forge identities or signers whose recorded
+     * override (`terragucci override`) lets `tf-apply` apply one denied plan.
+     * Read at base, like `approval:`. Unset, no override counts.
+     */
+    override?: string[];
 }
 /**
  * The jobs' cloud identities over the forge's OIDC token. `plan_role` and
@@ -193,16 +250,31 @@ export interface ProjectSettings {
     url?: string;
     /** When a wave waits for an approval. */
     gate?: Gate;
+    /** What counts as a waiting wave's approval; see APPROVALS. Read from the config at base, never the applied commit's own. */
+    approval?: Approval;
     /** When a change applies; see ApplySettings. */
     apply?: ApplySettings;
+    /** When a pull request takes its root locks; see LOCKS. */
+    locks?: Locks;
     waves?: {
         canary?: string[];
     };
     /** A cron schedule for tf-drift, or false. */
     drift?: string | false;
+    /**
+     * GitLab only: the cron of the comments schedule, or false. The pipeline
+     * gets a `comments` job that reads new merge request notes on that
+     * schedule (comment-gitlab.ts), since GitLab starts no pipeline for a note.
+     */
+    comments?: string | false;
+    /** GitLab only: how the project keeps its forge token; see TOKEN_PROTECTIONS. */
+    gitlab?: {
+        token?: GitLabToken;
+    };
     runtime?: Runtime;
     /**
-     * A bucket for plan reports. `url` is the address that serves the bucket's
+     * A bucket for plan reports: `s3://<bucket>`, `gs://<bucket>` or
+     * `az://<account>/<container>`. `url` is the address that serves the bucket's
      * objects to a browser (a static site, a CDN, the store's public endpoint);
      * with it, the note, the index and the dashboards link the bucket's copy.
      * `role` is an AWS role the job assumes with its OIDC token to write the
@@ -289,14 +361,43 @@ export declare function checkMode(mode: string): "dry-run" | "apply";
 export declare const CONFIG_NAMES: string[];
 /** The config file in `dir`, or undefined. Two of them is an error. */
 export declare function findConfig(dir: string): string | undefined;
+/** Why `comments` is GitLab's alone: the other forges start a job for each comment. */
+export declare const COMMENTS_GITLAB_ONLY = "comments is for GitLab, which starts no pipeline for a merge request note; GitHub and Forgejo start the comment jobs from the comment itself, so leave comments unset";
+/**
+ * What GitLab's apply before merge needs. A merge request's own pipeline
+ * runs its own `.gitlab-ci.yml`, so the apply runs in a pipeline of the
+ * default branch, which the comments job starts on a `/terragucci apply`
+ * note: so `comments:` must be set, and `apply.merge_token_env` must name the
+ * variable whose token may start a pipeline on the protected default branch
+ * (and, with `merge: auto`, merge there).
+ */
+export declare const PR_APPLY_NEEDS_ON_GITLAB: {
+    comments: string;
+    token: string;
+};
+/**
+ * Why `gitlab.token: protected` needs `comments:`: no merge request pipeline
+ * then holds a token that may post the plan note, so the comments schedule's
+ * job posts it.
+ */
+export declare const PROTECTED_TOKEN_NEEDS_COMMENTS = "protected needs comments: <cron>: a merge request's pipeline then holds no token that may post the plan note, so the comments schedule's job posts it";
+/** The problems with a GitLab project's `apply.when: pull-request` and `gitlab.token: protected`, when it has any. */
+export declare function gitlabPrApplyProblems(s: Record<string, unknown>, where: string): string[];
+/** Why GitLab has no plan-time locks: no merge request event runs a pipeline from the default branch. */
+export declare const NO_GITLAB_PLAN_LOCKS = "plan is not supported on GitLab, where no merge request event runs a job from the default branch that could hold the lock; leave locks unset, and with apply.when: pull-request a merge request locks its roots on `/terragucci apply` or `/terragucci lock`";
+/** Where a shared policy is fetched from: the git URL and the ref. */
+export interface PolicySource {
+    url: string;
+    ref: string;
+}
 /**
- * Why GitLab has no apply before merge. GitLab builds a merge request's
- * pipeline from the merge request's own `.gitlab-ci.yml`, so a job that
- * applies it would run the checks before the apply (approval, locks, the
- * pipeline file) inside a pipeline the merge request controls, and the apply
- * role would have to trust every branch of the project.
+ * Split `git+<scheme>://<host>/<path>@<ref>` into the URL git fetches and
+ * the ref. The ref is what follows the last `@` after the host, so a user
+ * name in the URL (`git+https://ci@host/...`) stays in the URL. https and
+ * http (a forge on a private network) and file (a repo on the job's disk).
+ * Undefined when it is not that shape.
  */
-export declare const NO_GITLAB_PR_APPLY = "pull-request is not supported on GitLab, where a merge request's pipeline is defined by the merge request itself, so nothing it runs can be trusted with the apply role; leave apply.when unset, and the change applies after it merges";
+export declare function parsePolicySource(source: string): PolicySource | undefined;
 /** Check a parsed config and return it typed, or throw with every problem listed. */
 export declare function validateConfig(raw: unknown, where: string): TerragucciConfig;
 export type ConfigMode = "fold" | "run" | "check";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/terragucci",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "The whole Terraform lifecycle, handled: one config file, generated pipelines for GitHub, GitLab and Forgejo.",
   "license": "Apache-2.0",
   "type": "module",
@@ -45,11 +45,11 @@
   },
   "devDependencies": {
     "@cdktn/hcl2json": "0.24.0",
-    "@intentius/chant": "0.107.1",
-    "@intentius/chant-lexicon-forgejo": "0.107.1",
-    "@intentius/chant-lexicon-github": "0.107.1",
-    "@intentius/chant-lexicon-gitlab": "0.107.1",
-    "@intentius/chant-lexicon-terraform": "0.107.1",
+    "@intentius/chant": "0.109.0",
+    "@intentius/chant-lexicon-forgejo": "0.109.0",
+    "@intentius/chant-lexicon-github": "0.109.0",
+    "@intentius/chant-lexicon-gitlab": "0.109.0",
+    "@intentius/chant-lexicon-terraform": "0.109.0",
     "@intentius/tsad-reference": "2.1.0"
   }
 }