diff --git a/public/llms-full.txt b/public/llms-full.txt index 8f1f963..f3d062e 100644 --- a/public/llms-full.txt +++ b/public/llms-full.txt @@ -622,6 +622,9 @@ function validateGraph(targets: Map): void const AnnounceTasks: AnnounceTasksApi Announcement task functions for posting build status to chat platforms. +const CHECKOUT_ACTION: "actions/checkout" + The action a {@link CiCheckout} is generated from when pins are resolved. + const CONFIG_FILE: "zuke.json" The Zuke config file name; its presence marks a repository root. @@ -637,6 +640,9 @@ const DEFAULT_TOOLS_DIR: ".zuke/tools" const FileTasks: FileTasksApi Filesystem task functions for build scripts. +const HARDEN_RUNNER_ACTION: "step-security/harden-runner" + The action a {@link CiHardenRunner} is generated from when pins are resolved. + const REDACTED: "[redacted]" The placeholder a {@link Redactor} substitutes for each secret value. @@ -913,14 +919,25 @@ class CiFile readonly provider: CiProvider The provider this file renders for. readonly path: string - The output path. + The output path, once resolved. + readonly explicitPath: boolean + Whether {@link path} came from the spec rather than a default. readonly pipeline: CiPipeline The base pipeline (pipeline-level fields, and the jobs unless fanning out). readonly fanOut?: FanOutOptions Fan-out options, when this file expands the build's targets into jobs. + readonly invokes?: readonly CiInvokes[] + The targets this file runs as jobs, when declared with `invokes`. + readonly pins?: CiPinResolver + Resolves pinned action references, so a SHA is stated once per repository. + get derived(): boolean + Whether this file's jobs are derived from the build rather than declared. pipelineFor(targets: Map): CiPipeline - The pipeline this file renders. With fan-out, the build's `targets` are - expanded into one job per target; otherwise the declared {@link pipeline}. + The pipeline this file renders. Jobs come from the invoked targets, or from + a full fan-out of the graph, or — failing both — from the declared + {@link pipeline}. + at(path: string): CiFile + The same file bound to `path` — used to name a file from its field. render(): string Render the file's YAML content (the base pipeline; fan-out is resolved at discovery). @@ -2034,13 +2051,26 @@ interface CancelResult failures: CompensationFailure[] Compensations that threw (recorded, non-fatal). +interface CiActionRef + A pinned action reference, and the version its commit corresponds to. + + The version is emitted as a trailing `# v1.2.3` comment, which is not + decoration: Dependabot reads it to know which version a pinned SHA is, and + rewrites both together when it bumps. A generated workflow that dropped it + would leave automated bumps with no version to track. + + ref: string + The pinned reference, `owner/repo@`. + version?: string + The version the SHA corresponds to, e.g. `v7.0.1`. + interface CiCheckout The repository checkout, emitted as an `actions/checkout` step after any {@link CiHardenRunner} and before the job's own steps. Like hardening, the pinned {@link action} reference is required. - action: string - The pinned action reference, e.g. `actions/checkout@`. + action?: CiUses + The pinned action reference. Omit it when the file supplies a `pins` resolver. persistCredentials?: boolean Keep the token in git config so a later step can push. Defaults to `false`: a job that does not push should not leave a credential behind. @@ -2063,12 +2093,29 @@ interface CiConcurrency interface CiFileSpec A CI configuration file declared on a build: a pipeline bound to a path. - provider: CiProvider - The provider to render for — the one field you must choose. + provider?: CiProvider + The provider to render for. Defaults to `"github"`, which is what the + `.github/workflows` default path assumes anyway. + pins?: CiPinResolver + Resolves each action's pinned reference by name, so hardening and checkout + can be requested without restating a SHA. + + With a resolver, every job is hardened and checked out by default — the + prelude nearly every job needs — and a job opts out with `harden: false` or + adjusts the policy without naming the action again. path?: string - The output path (relative to the working directory). Defaults to the - provider's conventional location (`.github/workflows/ci.yml`, - `.gitlab-ci.yml`, or `azure-pipelines.yml`). + The output path (relative to the working directory). + + Defaults to the field name the file is declared on, in the provider's + conventional directory: `releaseWorkflow = cicd({...})` writes + `.github/workflows/release.yml`. A trailing `Workflow`/`Ci`/`Yaml` is + dropped, and camelCase becomes kebab-case. Recovering the name from the + field is how `target()` works too, so a workflow needs no more ceremony + than a target. + + Falls back to the provider's single conventional file + (`.github/workflows/ci.yml`, `.gitlab-ci.yml`, …) when the name is not + available — a file built outside a build class. pipeline?: CiPipeline The pipeline to render. Defaults to a single `build` job that runs the build. fanOut?: boolean | FanOutOptions @@ -2076,6 +2123,28 @@ interface CiFileSpec dependencies (see {@link fanOutPipeline}). `true` uses the defaults; pass {@link FanOutOptions} to customise. When set, {@link pipeline} supplies the pipeline-level fields (name, triggers, …) and its `jobs` are ignored. + invokes?: readonly CiInvokes[] + The targets this workflow runs — one job each, in place of hand-written + {@link CiPipeline.jobs}. + + This is the intended way to declare a workflow. A job is almost entirely + implied by its target, so naming the targets is usually the whole + declaration: the id, the display name, the `./zuke ` command, and + the `needs:` edges between jobs all come from the build graph. Pass a + {@link CiInvocation} instead of a bare target only for what the runner + decides rather than the build — a matrix, token scopes, an egress policy. + + Each job runs its target's whole subgraph in one process, exactly as + `./zuke ` does locally — so dependencies inside a target run + in-process and need no cache to share their output. Use {@link fanOut} + instead to give every target in the graph its own job, which does need a + remote cache. + + Targets are passed as references (`this.ci`), not names, so a rename is a + compile error rather than a workflow that silently runs nothing. As with + `dependsOn`, that means the declaration must appear below the targets it + invokes — class fields initialise top-to-bottom, so a forward reference is + `undefined`. Declaring workflows last is the simplest way to satisfy it. interface CiHardenRunner Runner hardening, emitted as a `step-security/harden-runner` step before @@ -2092,8 +2161,11 @@ interface CiHardenRunner between releases. Passing it makes the pin the caller's — and lets a build source it from wherever its bumps are automated. - action: string + action?: CiUses The pinned action reference, e.g. `step-security/harden-runner@`. + Omit it when the file supplies a {@link CiFileSpec.pins} resolver, which is + the better arrangement: the SHA is then stated once for the repository + rather than at every use. egress?: "audit" | "block" `"audit"` records outbound connections; `"block"` drops everything outside {@link allowedEndpoints}. Defaults to `"audit"` — the safe choice for a job @@ -2104,6 +2176,58 @@ interface CiHardenRunner name?: string The step name. Defaults to `"Harden the runner"`. +interface CiInvocation + One job's worth of a workflow, derived from a target. + + A job's shape is almost entirely implied by the target it runs: the id and + display name come from the target, the command is `./zuke `, and the + `needs:` edges come from the target's `dependsOn`. So an invoked target + usually needs nothing said about it at all — pass the target and the job is + generated. + + The fields here are the residue that genuinely cannot be inferred, because + they are properties of the runner rather than of the work: which OS matrix + to fan out over, which token scopes the job needs, how much egress to permit, + how long to allow. Set one only when the default is wrong. + + target: TargetBuilder + The target this job runs. + id?: string + Override the job id (defaults to the target's name, CI-sanitised). + name?: string + Override the display name (defaults to the target's description, else its name). + runsOn?: string + The runner, when it differs from the pipeline default. + matrix?: Record> + A build matrix — fanning one target out over several OSes, say. + failFast?: boolean + Let the other matrix legs finish when one fails. + permissions?: Record + The token permissions this job needs (see {@link CiJob.permissions}). + timeoutMinutes?: number + Fail the job after this many minutes. + harden?: CiHardenRunner | false + Harden this job's runner, overriding the pipeline default. + checkout?: CiCheckout | false + Check out in this job, overriding the pipeline default. + if?: string + A condition gating the job. + env?: Record + Environment variables for the target's own step — where a secret is mapped + in, e.g. `{ GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}" }`. + after?: readonly TargetBuilder[] + Extra `needs:` edges beyond those implied by the target's `dependsOn`. Use + it to order two invoked targets that are independent in the build graph but + must not run concurrently in CI. + before?: CiStep[] + Steps to run before the target, for something no target can do (see below). + then?: CiStep[] + Steps to run after the target. + steps?: CiStep[] + Replace the generated `./zuke ` step entirely. The escape hatch of + last resort — prefer {@link before}/{@link then}, and prefer moving the work + into the target over either. + interface CiJob A job: a named unit of work with steps, optionally fanned out by a matrix. @@ -2155,6 +2279,11 @@ interface CiPipeline permissions?: Record Workflow-level token permissions (GitHub only), e.g. `{ contents: "read", "pull-requests": "write" }`. Ignored elsewhere. + + Defaults to `{ contents: "read" }` — least privilege, and what a workflow + that only reads the repository needs. A job that needs more declares it, so + the wider scope sits next to the job that justifies it. Pass `{}` for no + permissions at all, which is stricter than the default rather than absent. concurrency?: CiConcurrency Limit concurrent runs (GitHub only). Ignored elsewhere. harden?: CiHardenRunner @@ -2185,7 +2314,7 @@ interface CiStep Continue the job even when this step fails (`continue-on-error`). GitHub only. run?: string A shell command to run. Portable across all providers. - uses?: string + uses?: CiUses A GitHub Action reference (e.g. `actions/checkout@v4`). Rendered only for GitHub; skipped for GitLab and Azure. with?: Record @@ -3373,12 +3502,25 @@ type CiHost = "github" | "gitlab" | "azure" | "bitbucket" | "local" match {@link CiProvider} so they compose with CI generation and per-host integrations (e.g. posting a review to the right pull-request API). +type CiInvokes = TargetBuilder | CiInvocation + A target to invoke, bare when the derived job needs no adjustment. + +type CiPinResolver = (action: string) => CiUses + Resolves an action's pinned reference by name, e.g. `"actions/checkout"`. + + Supplying one is what lets a workflow declare hardening and checkout by + intent rather than by repeating a SHA at every use. Without it each + {@link CiHardenRunner} and {@link CiCheckout} must carry its own `action`. + type CiProvider = "github" | "gitlab" | "azure" | "bitbucket" The CI providers {@link generateCi} can target. type CiSyncStatus = "written" | "unchanged" | "stale" What {@link syncCiFiles} did to a file. +type CiUses = string | CiActionRef + A step's `uses:` value — a bare reference, or one carrying its version. + type Condition = () => boolean | Promise A predicate gating whether a target runs; may be synchronous or async. @@ -10493,6 +10635,21 @@ interface AiReviewWorkflowSpec the workflow drops the step, and the reviewers use their own configured base rather than the fetched `FETCH_HEAD`. Preferable where it applies: the same `zuke review` then works locally, where no workflow step exists to run. + hardenRunner?: string + The pinned `step-security/harden-runner@` to harden the runner with. + Defaults to a pin baked in here. + + Pass it when the build sources pins from somewhere that stays current — a + generated workflow whose SHA comes from a constant in a published package is + a trap: a bot bumps the committed file, the next run regenerates it from the + stale constant, and the bump is silently reverted. + + A bare `owner/repo@`, without the `# vX.Y.Z` comment the other + generated workflows carry: attaching one needs a core newer than this + package's declared floor, and Dependabot bumps a comment-less pin anyway. + Adopt the richer form once the floor moves past that release. + checkout?: string + The pinned `actions/checkout@` to check the repository out with. path?: string Output path. Defaults to the host's conventional location. name?: string diff --git a/src/data/api.json b/src/data/api.json index 6a20499..aca616f 100644 --- a/src/data/api.json +++ b/src/data/api.json @@ -1134,6 +1134,13 @@ "signature": "async function checkBuildRegistry(make: BuildRegistryFactory): Promise", "deprecated": false }, + { + "name": "CHECKOUT_ACTION", + "kind": "variable", + "doc": "The action a {@link CiCheckout} is generated from when pins are resolved.", + "signature": "const CHECKOUT_ACTION: actions/checkout", + "deprecated": false + }, { "name": "checkStateStore", "kind": "function", @@ -1141,6 +1148,29 @@ "signature": "async function checkStateStore(make: StateStoreFactory, options?: ConformanceOptions): Promise", "deprecated": false }, + { + "name": "CiActionRef", + "kind": "interface", + "doc": "A pinned action reference, and the version its commit corresponds to.\n\nThe version is emitted as a trailing `# v1.2.3` comment, which is not\ndecoration: Dependabot reads it to know which version a pinned SHA is, and\nrewrites both together when it bumps. A generated workflow that dropped it\nwould leave automated bumps with no version to track.", + "signature": "interface CiActionRef", + "deprecated": false, + "members": [ + { + "name": "ref", + "kind": "property", + "optional": false, + "signature": "ref: string", + "doc": "The pinned reference, `owner/repo@`." + }, + { + "name": "version", + "kind": "property", + "optional": true, + "signature": "version?: string", + "doc": "The version the SHA corresponds to, e.g. `v7.0.1`." + } + ] + }, { "name": "cicd", "kind": "function", @@ -1158,9 +1188,9 @@ { "name": "action", "kind": "property", - "optional": false, - "signature": "action: string", - "doc": "The pinned action reference, e.g. `actions/checkout@`." + "optional": true, + "signature": "action?: CiUses", + "doc": "The pinned action reference. Omit it when the file supplies a `pins` resolver." }, { "name": "persistCredentials", @@ -1222,12 +1252,26 @@ "signature": "class CiFile", "deprecated": false, "members": [ + { + "name": "derived", + "kind": "method", + "optional": false, + "signature": "derived(): boolean", + "doc": "Whether this file's jobs are derived from the build rather than declared." + }, { "name": "pipelineFor", "kind": "method", "optional": false, "signature": "pipelineFor(targets: Map): CiPipeline", - "doc": "The pipeline this file renders. With fan-out, the build's `targets` are\nexpanded into one job per target; otherwise the declared {@link pipeline}." + "doc": "The pipeline this file renders. Jobs come from the invoked targets, or from\na full fan-out of the graph, or — failing both — from the declared\n{@link pipeline}." + }, + { + "name": "at", + "kind": "method", + "optional": false, + "signature": "at(path: string): CiFile", + "doc": "The same file bound to `path` — used to name a file from its field." }, { "name": "render", @@ -1248,7 +1292,14 @@ "kind": "property", "optional": false, "signature": "path: string", - "doc": "The output path." + "doc": "The output path, once resolved." + }, + { + "name": "explicitPath", + "kind": "property", + "optional": false, + "signature": "explicitPath: boolean", + "doc": "Whether {@link path} came from the spec rather than a default." }, { "name": "pipeline", @@ -1263,6 +1314,20 @@ "optional": true, "signature": "fanOut?: FanOutOptions", "doc": "Fan-out options, when this file expands the build's targets into jobs." + }, + { + "name": "invokes", + "kind": "property", + "optional": true, + "signature": "invokes?: unknown", + "doc": "The targets this file runs as jobs, when declared with `invokes`." + }, + { + "name": "pins", + "kind": "property", + "optional": true, + "signature": "pins?: CiPinResolver", + "doc": "Resolves pinned action references, so a SHA is stated once per repository." } ] }, @@ -1276,16 +1341,23 @@ { "name": "provider", "kind": "property", - "optional": false, - "signature": "provider: CiProvider", - "doc": "The provider to render for — the one field you must choose." + "optional": true, + "signature": "provider?: CiProvider", + "doc": "The provider to render for. Defaults to `\"github\"`, which is what the\n`.github/workflows` default path assumes anyway." + }, + { + "name": "pins", + "kind": "property", + "optional": true, + "signature": "pins?: CiPinResolver", + "doc": "Resolves each action's pinned reference by name, so hardening and checkout\ncan be requested without restating a SHA.\n\nWith a resolver, every job is hardened and checked out by default — the\nprelude nearly every job needs — and a job opts out with `harden: false` or\nadjusts the policy without naming the action again." }, { "name": "path", "kind": "property", "optional": true, "signature": "path?: string", - "doc": "The output path (relative to the working directory). Defaults to the\nprovider's conventional location (`.github/workflows/ci.yml`,\n`.gitlab-ci.yml`, or `azure-pipelines.yml`)." + "doc": "The output path (relative to the working directory).\n\nDefaults to the **field name** the file is declared on, in the provider's\nconventional directory: `releaseWorkflow = cicd({...})` writes\n`.github/workflows/release.yml`. A trailing `Workflow`/`Ci`/`Yaml` is\ndropped, and camelCase becomes kebab-case. Recovering the name from the\nfield is how `target()` works too, so a workflow needs no more ceremony\nthan a target.\n\nFalls back to the provider's single conventional file\n(`.github/workflows/ci.yml`, `.gitlab-ci.yml`, …) when the name is not\navailable — a file built outside a build class." }, { "name": "pipeline", @@ -1300,6 +1372,13 @@ "optional": true, "signature": "fanOut?: boolean | FanOutOptions", "doc": "Fan the build's targets out into one CI job per target, wired by their\ndependencies (see {@link fanOutPipeline}). `true` uses the defaults; pass\n{@link FanOutOptions} to customise. When set, {@link pipeline} supplies the\npipeline-level fields (name, triggers, …) and its `jobs` are ignored." + }, + { + "name": "invokes", + "kind": "property", + "optional": true, + "signature": "invokes?: unknown", + "doc": "The targets this workflow runs — one job each, in place of hand-written\n{@link CiPipeline.jobs}.\n\nThis is the intended way to declare a workflow. A job is almost entirely\nimplied by its target, so naming the targets is usually the whole\ndeclaration: the id, the display name, the `./zuke ` command, and\nthe `needs:` edges between jobs all come from the build graph. Pass a\n{@link CiInvocation} instead of a bare target only for what the runner\ndecides rather than the build — a matrix, token scopes, an egress policy.\n\nEach job runs its target's *whole* subgraph in one process, exactly as\n`./zuke ` does locally — so dependencies inside a target run\nin-process and need no cache to share their output. Use {@link fanOut}\ninstead to give every target in the graph its own job, which does need a\nremote cache.\n\nTargets are passed as references (`this.ci`), not names, so a rename is a\ncompile error rather than a workflow that silently runs nothing. As with\n`dependsOn`, that means the declaration must appear **below** the targets it\ninvokes — class fields initialise top-to-bottom, so a forward reference is\n`undefined`. Declaring workflows last is the simplest way to satisfy it." } ] }, @@ -1313,9 +1392,9 @@ { "name": "action", "kind": "property", - "optional": false, - "signature": "action: string", - "doc": "The pinned action reference, e.g. `step-security/harden-runner@`." + "optional": true, + "signature": "action?: CiUses", + "doc": "The pinned action reference, e.g. `step-security/harden-runner@`.\nOmit it when the file supplies a {@link CiFileSpec.pins} resolver, which is\nthe better arrangement: the SHA is then stated once for the repository\nrather than at every use." }, { "name": "egress", @@ -1354,6 +1433,134 @@ "signature": "type CiHost = github | gitlab | azure | bitbucket | local", "deprecated": false }, + { + "name": "CiInvocation", + "kind": "interface", + "doc": "One job's worth of a workflow, derived from a target.\n\nA job's shape is almost entirely implied by the target it runs: the id and\ndisplay name come from the target, the command is `./zuke `, and the\n`needs:` edges come from the target's `dependsOn`. So an invoked target\nusually needs nothing said about it at all — pass the target and the job is\ngenerated.\n\nThe fields here are the residue that genuinely cannot be inferred, because\nthey are properties of the *runner* rather than of the work: which OS matrix\nto fan out over, which token scopes the job needs, how much egress to permit,\nhow long to allow. Set one only when the default is wrong.", + "signature": "interface CiInvocation", + "deprecated": false, + "members": [ + { + "name": "target", + "kind": "property", + "optional": false, + "signature": "target: TargetBuilder", + "doc": "The target this job runs." + }, + { + "name": "id", + "kind": "property", + "optional": true, + "signature": "id?: string", + "doc": "Override the job id (defaults to the target's name, CI-sanitised)." + }, + { + "name": "name", + "kind": "property", + "optional": true, + "signature": "name?: string", + "doc": "Override the display name (defaults to the target's description, else its name)." + }, + { + "name": "runsOn", + "kind": "property", + "optional": true, + "signature": "runsOn?: string", + "doc": "The runner, when it differs from the pipeline default." + }, + { + "name": "matrix", + "kind": "property", + "optional": true, + "signature": "matrix?: Record>", + "doc": "A build matrix — fanning one target out over several OSes, say." + }, + { + "name": "failFast", + "kind": "property", + "optional": true, + "signature": "failFast?: boolean", + "doc": "Let the other matrix legs finish when one fails." + }, + { + "name": "permissions", + "kind": "property", + "optional": true, + "signature": "permissions?: Record", + "doc": "The token permissions this job needs (see {@link CiJob.permissions})." + }, + { + "name": "timeoutMinutes", + "kind": "property", + "optional": true, + "signature": "timeoutMinutes?: number", + "doc": "Fail the job after this many minutes." + }, + { + "name": "harden", + "kind": "property", + "optional": true, + "signature": "harden?: CiHardenRunner | false", + "doc": "Harden this job's runner, overriding the pipeline default." + }, + { + "name": "checkout", + "kind": "property", + "optional": true, + "signature": "checkout?: CiCheckout | false", + "doc": "Check out in this job, overriding the pipeline default." + }, + { + "name": "if", + "kind": "property", + "optional": true, + "signature": "if?: string", + "doc": "A condition gating the job." + }, + { + "name": "env", + "kind": "property", + "optional": true, + "signature": "env?: Record", + "doc": "Environment variables for the target's own step — where a secret is mapped\nin, e.g. `{ GITHUB_TOKEN: \"${{ secrets.GITHUB_TOKEN }}\" }`." + }, + { + "name": "after", + "kind": "property", + "optional": true, + "signature": "after?: unknown", + "doc": "Extra `needs:` edges beyond those implied by the target's `dependsOn`. Use\nit to order two invoked targets that are independent in the build graph but\nmust not run concurrently in CI." + }, + { + "name": "before", + "kind": "property", + "optional": true, + "signature": "before?: CiStep[]", + "doc": "Steps to run before the target, for something no target can do (see below)." + }, + { + "name": "then", + "kind": "property", + "optional": true, + "signature": "then?: CiStep[]", + "doc": "Steps to run after the target." + }, + { + "name": "steps", + "kind": "property", + "optional": true, + "signature": "steps?: CiStep[]", + "doc": "Replace the generated `./zuke ` step entirely. The escape hatch of\nlast resort — prefer {@link before}/{@link then}, and prefer moving the work\ninto the target over either." + } + ] + }, + { + "name": "CiInvokes", + "kind": "typeAlias", + "doc": "A target to invoke, bare when the derived job needs no adjustment.", + "signature": "type CiInvokes = TargetBuilder | CiInvocation", + "deprecated": false + }, { "name": "CiJob", "kind": "interface", @@ -1454,6 +1661,13 @@ } ] }, + { + "name": "CiPinResolver", + "kind": "typeAlias", + "doc": "Resolves an action's pinned reference by name, e.g. `\"actions/checkout\"`.\n\nSupplying one is what lets a workflow declare hardening and checkout by\n*intent* rather than by repeating a SHA at every use. Without it each\n{@link CiHardenRunner} and {@link CiCheckout} must carry its own `action`.", + "signature": "type CiPinResolver = unknown", + "deprecated": false + }, { "name": "CiPipeline", "kind": "interface", @@ -1480,7 +1694,7 @@ "kind": "property", "optional": true, "signature": "permissions?: Record", - "doc": "Workflow-level token permissions (GitHub only), e.g.\n`{ contents: \"read\", \"pull-requests\": \"write\" }`. Ignored elsewhere." + "doc": "Workflow-level token permissions (GitHub only), e.g.\n`{ contents: \"read\", \"pull-requests\": \"write\" }`. Ignored elsewhere.\n\nDefaults to `{ contents: \"read\" }` — least privilege, and what a workflow\nthat only reads the repository needs. A job that needs more declares it, so\nthe wider scope sits next to the job that justifies it. Pass `{}` for no\npermissions at all, which is stricter than the default rather than absent." }, { "name": "concurrency", @@ -1572,7 +1786,7 @@ "name": "uses", "kind": "property", "optional": true, - "signature": "uses?: string", + "signature": "uses?: CiUses", "doc": "A GitHub Action reference (e.g. `actions/checkout@v4`). Rendered only for\nGitHub; skipped for GitLab and Azure." }, { @@ -1702,6 +1916,13 @@ } ] }, + { + "name": "CiUses", + "kind": "typeAlias", + "doc": "A step's `uses:` value — a bare reference, or one carrying its version.", + "signature": "type CiUses = string | CiActionRef", + "deprecated": false + }, { "name": "CliCommandInfo", "kind": "interface", @@ -3183,6 +3404,13 @@ "signature": "async function gzip(data: Uint8Array): Promise", "deprecated": false }, + { + "name": "HARDEN_RUNNER_ACTION", + "kind": "variable", + "doc": "The action a {@link CiHardenRunner} is generated from when pins are resolved.", + "signature": "const HARDEN_RUNNER_ACTION: step-security/harden-runner", + "deprecated": false + }, { "name": "hostPlatform", "kind": "function", @@ -20877,6 +21105,20 @@ "signature": "fetchBase?: boolean", "doc": "Emit the `git fetch` step that makes the base branch available, and point\nthe reviewers at what it fetched. Defaults to `true`, because a pull-request\ncheckout is shallow and has no base to diff against.\n\nSet it to `false` when the build's review target fetches its own base — then\nthe workflow drops the step, and the reviewers use their own configured base\nrather than the fetched `FETCH_HEAD`. Preferable where it applies: the same\n`zuke review` then works locally, where no workflow step exists to run." }, + { + "name": "hardenRunner", + "kind": "property", + "optional": true, + "signature": "hardenRunner?: string", + "doc": "The pinned `step-security/harden-runner@` to harden the runner with.\nDefaults to a pin baked in here.\n\nPass it when the build sources pins from somewhere that stays current — a\ngenerated workflow whose SHA comes from a constant in a published package is\na trap: a bot bumps the committed file, the next run regenerates it from the\nstale constant, and the bump is silently reverted.\n\nA bare `owner/repo@`, without the `# vX.Y.Z` comment the other\ngenerated workflows carry: attaching one needs a core newer than this\npackage's declared floor, and Dependabot bumps a comment-less pin anyway.\nAdopt the richer form once the floor moves past that release." + }, + { + "name": "checkout", + "kind": "property", + "optional": true, + "signature": "checkout?: string", + "doc": "The pinned `actions/checkout@` to check the repository out with." + }, { "name": "path", "kind": "property",