@intentius/chant 0.124.28 → 0.124.30

package/dist/workspace/ci-run.d.ts

@@ -0,0 +1,222 @@
+/**
+ * `chant ci run plan|apply` (#4094, epic #4101): run one pull-request job as
+ * a pipeline Op, the first slice of the chant runner.
+ *
+ * The job is the typed value `prLoopJobs` (../components/pr-pipeline.ts)
+ * returns, the one the github, gitlab and forgejo generators wrap in a
+ * workflow, so the runner and a generated workflow run the same command with
+ * the same values. Nothing reads generated YAML.
+ *
+ * The job runs as an Op on the local executor (../op/local-executor.ts):
+ *
+ * - a `setup` phase with the setup lines the default image needs,
+ * - a `build` phase with the lines given to run before the command
+ *   (`--before-script`, which a generated workflow runs in the same place),
+ *   then the job's build and lint lines with `--pr-build` (#4088),
+ * - and a phase named for the job, `plan` or `apply`, with the job's own
+ *   setup lines and its command in one shell.
+ *
+ * Each line is one shell step with a clean environment: a short list of the
+ * runner's variables (PATH, HOME and the like), the forge's connection and
+ * token variables the commands read, any `--pass-env` names, and the job's
+ * own variables. The forge values a generated job reads from `${{ ... }}`
+ * expressions or GitLab's predefined variables come from flags here:
+ * `BASE_SHA` from `--base`, `PR_NUMBER` from `--pr`, and the commit from
+ * `--commit`.
+ *
+ * The steps run in a fresh checkout of the commit: a detached `git worktree`
+ * in a temporary directory outside the repository, removed when the run
+ * ends. A worktree shares the repository's refs, so what the job records on
+ * `chant/lifecycle` (pr-apply's pending gate facts) and the remote it pushes
+ * to are the repository's own, as in a forge job's checkout. The report the
+ * job writes under `.chant/pr` is copied out of the worktree before it goes,
+ * where a forge would keep it as an artifact.
+ *
+ * The run is recorded as Op `pr-plan` or `pr-apply` in the run ledger
+ * (`<env>/runs__<op>.jsonl` on `chant/lifecycle`), and signed when a runner
+ * key is given, so `chant ci tick --source runs` (#4044) judges the commit
+ * from it. Its events are `kind: "pipeline"` and `runtime: "ci"`, and the
+ * record and the events carry `runOrigin: { forge: "chant" }`.
+ */
+import { type PrLoopJob, type PrLoopPipelineOptions } from "../components/pr-pipeline.js";
+import { type ForgeKind } from "../pr-forge.js";
+import type { CommandContext } from "../cli/registry.js";
+import type { RunOrigin } from "../lifecycle/release-ledger.js";
+import { type OpRunResult, type StepRecord } from "../op/local-executor.js";
+import type { OpRunFailureReason, OpRunRecord } from "../op/runtime.js";
+import type { OpConfig } from "../op/types.js";
+/** The two jobs a pull-request pipeline has. */
+export type CiJobName = PrLoopJob["jobName"];
+export declare const CI_JOB_NAMES: readonly CiJobName[];
+/** The Op each job is recorded as, which `ci.green` phases match. */
+export declare const CI_JOB_OPS: Record<CiJobName, string>;
+/** Where a job the chant runner ran says it ran (#4094). */
+export declare const CHANT_RUNNER_ORIGIN: RunOrigin;
+/** The runner's variables every job gets, when the runner has them. */
+export declare const CI_RUN_BASE_ENV: readonly ["PATH", "HOME", "USER", "LOGNAME", "SHELL", "LANG", "LC_ALL", "LC_CTYPE", "TMPDIR", "TZ"];
+/**
+ * The forge's connection and token variables the pull-request commands read
+ * (`forgeFromEnv` in ../pr-forge.ts), which a forge job gets from the forge
+ * and a job here gets from the runner's environment.
+ */
+export declare const CI_RUN_FORGE_ENV: readonly ["CHANT_FORGE_TOKEN", "GITHUB_TOKEN", "GH_TOKEN", "GITHUB_REPOSITORY", "GITHUB_SERVER_URL", "GITHUB_API_URL", "GITLAB_TOKEN", "CI_API_V4_URL", "CI_PROJECT_ID", "CI_SERVER_HOST", "CI_SERVER_URL"];
+/** The forge values a job reads, given on the command line in place of a forge's expressions. */
+export interface CiRunValues {
+    /** `--base`: the commit the change is measured from, `BASE_SHA`. */
+    base?: string;
+    /** `--pr`: the pull request, `PR_NUMBER`. The plan needs it. */
+    pr?: number;
+    /** The full commit the job runs at. */
+    commit: string;
+}
+export declare class CiRunError extends Error {
+    constructor(message: string);
+}
+/**
+ * The job's environment: the runner's base variables, the forge variables
+ * and `passEnv` names it has, `CHANT_ENV` as a generated workflow sets it,
+ * the commit as the forge spells it, and the job's own variables. A job
+ * variable the forge fills from an expression comes from a flag, or from
+ * the runner's environment for a token such as `GITHUB_TOKEN`; a literal
+ * one, such as `CHANT_RUN_EVENTS_DIR`, is kept as it is.
+ */
+export declare function ciJobEnv(job: PrLoopJob, input: {
+    forge: ForgeKind;
+    env: string;
+    values: CiRunValues;
+    hostEnv: Record<string, string | undefined>;
+    passEnv?: readonly string[];
+}): Record<string, string>;
+/** What {@link ciJobOp} builds the Op from. */
+export interface CiJobOpInput {
+    job: PrLoopJob;
+    env: string;
+    /** The directory the steps run in, inside the fresh checkout. */
+    cwd: string;
+    /** The job's environment, from {@link ciJobEnv}. */
+    jobEnv: Record<string, string>;
+    /** Setup lines, from `prLoopSetup`. */
+    setup: readonly string[];
+    /** Lines to run before the command, in order: `--before-script`, then the job's build and lint lines (#4088). */
+    build: readonly string[];
+    /** What runs chant, in place of `chant` at the start of the command. */
+    chant?: string;
+}
+/** `line` with a `chant` at its start replaced by the command the caller names, when it names one. */
+export declare function withChant(line: string, chant?: string): string;
+/** The job's own setup lines and its command, as one shell script, with `chant` at its start replaced by the command the caller names. */
+export declare function ciJobCommand(job: PrLoopJob, chant?: string): string;
+/**
+ * The job as an Op: `setup`, `build` and the job's own phase, each line one
+ * shell step in `cwd` with the job's environment and nothing else. A phase
+ * with no lines is left out.
+ */
+export declare function ciJobOp(input: CiJobOpInput): OpConfig;
+/**
+ * Why a failed job failed (#4094), from its step records and, when the
+ * command wrote one, its pull-request report (`pr-plan.json` or
+ * `pr-apply.json` under `reportDir`):
+ *
+ * - a failed setup or build line: `setup-failed` or `build-failed`, the line
+ *   and its exit code as the reason, and the phase;
+ * - a failed command with a report: the report's `refusal`, else its
+ *   `status`, with its `message` as the reason, else the members that failed;
+ * - a failed command with no report: `command-failed` and the step's error.
+ *
+ * Undefined when no step failed, such as a run that stopped on an error of
+ * its own before any step ran.
+ */
+export declare function ciJobFailure(input: {
+    job: CiJobName;
+    op: OpConfig;
+    records: readonly StepRecord[];
+    reportDir: string;
+}): OpRunFailureReason | undefined;
+/** What `chant ci run` runs. */
+export interface CiRunRequest {
+    /** Where the command was run: the project, or a workspace member's directory. */
+    cwd: string;
+    job: CiJobName;
+    /** `--env`: the environment the pipeline is for. */
+    env: string;
+    forge: ForgeKind;
+    /** `--base`, `--pr` and `--commit` (default `HEAD`). */
+    base?: string;
+    pr?: number;
+    commit?: string;
+    /** The generator's options: `--gate`, `--branch`, `--events-json`, `--report-url`, `--pr-build` and `--pr-build-command`. */
+    loop?: PrLoopPipelineOptions;
+    /** `--image`: the image a generated pipeline names. Only the default gets setup lines. */
+    image?: string;
+    /** `--before-script` lines, run in the build phase before the job's build lines. */
+    beforeScript?: readonly string[];
+    /** `--chant`: what runs chant in the job. Default `chant`. */
+    chant?: string;
+    /** `--pass-env`: more of the runner's variables the job gets. */
+    passEnv?: readonly string[];
+    /** The runner's environment. Default `process.env`. */
+    hostEnv?: Record<string, string | undefined>;
+    /** `--output`: where the job's report is copied, from `cwd`. Default `.chant/pr`. */
+    output?: string;
+    /** A runner key, PEM, that signs the run's record. */
+    runnerKey?: string;
+    /**
+     * The key came from `CHANT_RUNNER_KEY`, not `--key`: one `.chant/trust.json`
+     * does not list leaves the run unsigned with a warning, as `chant run` does,
+     * where `--key` refuses the run.
+     */
+    runnerKeyFromEnv?: boolean;
+    /** The run id. Default `chant-<epoch ms>`. */
+    runId?: string;
+    /** Where the run's events go as they happen (`--events-json`). They are kept on this host either way. */
+    runEvents?: (line: string) => void;
+    /** Where each line a step prints goes. */
+    stepOutput?: (line: string) => void;
+    /** Push `chant/lifecycle` once the record is written. Default true. */
+    push?: boolean;
+    /**
+     * The apply's resume record on this host (#4095), in place of the forge's
+     * CI cache: copied into the checkout at `PR_APPLY_RECORD` before the job,
+     * when it exists, and the job's record copied back to it after, passed or
+     * failed. `chant ci serve` names one per `prApplyRecordKey`.
+     */
+    resumeRecord?: string;
+    signal?: AbortSignal;
+}
+export interface CiRunResult {
+    op: string;
+    /** The executor's outcome: `ok` or `fail` for a job. */
+    status: OpRunResult["status"];
+    record: OpRunRecord;
+    /** The step that failed and why, for a failed run. */
+    failure?: {
+        phase: string;
+        error: string;
+    };
+    /** Where the job's report was copied, or null when it wrote none. */
+    report: string | null;
+    /** The runner the record was signed as, or null. */
+    signer: string | null;
+    pushed: boolean;
+    pushWarning?: string;
+    /** What went wrong beside the job, such as a record the key could not sign. */
+    warnings: string[];
+    /** The checkout the job ran in, removed by now. */
+    checkout: string;
+}
+/** The member a job runs for, and its directory from the repository root, as the generator decides it. */
+export declare function ciJobPlace(cwd: string, top: string): {
+    member?: string;
+    dir: string;
+};
+/**
+ * Run one pull-request job as a pipeline Op in a fresh checkout of the
+ * commit, record it, and copy its report out. Throws {@link CiRunError}
+ * before anything runs when the request can't be run.
+ */
+export declare function ciRun(req: CiRunRequest): Promise<CiRunResult>;
+/** The text `chant ci run` prints when the run settles. */
+export declare function formatCiRun(r: CiRunResult): string;
+/** `chant ci run plan|apply` (#4094). */
+export declare function runCiRun(ctx: CommandContext): Promise<number>;
+//# sourceMappingURL=ci-run.d.ts.map

package/dist/workspace/ci-run.d.ts.map

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