@zuke/ai

The failure context handed to an AgentRunner, plus a ready prompt.

Construct an AgentFixer from an AgentRunner and apply the configuration lambda. Plug the result into a target with .recoverWith(...).

A fluent agent fixer. Construct one via agentFixer with a runner, and attach it to a target with .recoverWith(...). Diagnose/report defaults are on; file changes happen through the agent, gated to local runs unless .runOnly(...) says otherwise.

What an AgentRunner may resolve to: a CommandOutput (its stdout is captured for the report), a string, or nothing.

Runs the coding agent against the assembled AgentContext. The agent is expected to edit files in place; the executor then re-runs the target. Throw (or let the underlying command throw) to signal the agent could not run.

Construct an AiCache, applying an optional configure lambda so it can be set up inline — e.g. aiCache((c) => c.dir(".cache").ttl(3600)).

A best-effort cache of AI provider responses, keyed by a stableHash of each call's salient parts and persisted through a CacheStore (the default writes JSON files under AiCache.dir). Configure it inline with aiCache: set the AiCache.dir, the AiCache.ttl, or AiCache.disable it entirely, then read with AiCache.get_ and write with AiCache.put_.

Construct an AiFixer and apply the configuration lambda. Plug the result into a target with .recoverWith(...):

test = target()
  .executes(() => DenoTasks.test((s) => s.allowAll()))
  .recoverWith(aiFixer((f) => f.provider("claude").apiKey(this.key)));

A fluent AI fixer. Construct one via aiFixer, configure it, and attach it to a target with .recoverWith(...). Only .provider(...) and .apiKey(...) are required; everything else defaults.

Raised when a reviewer is misconfigured, the API fails, or the gate trips.

Declare a generated AI-review workflow on the build. The returned CiFile is automatically discovered by discoverCiFiles and kept on disk by syncCiFiles. Default host: "github"; pass "gitlab" or "azure" to target those hosts.

class Pipeline extends Build {
  openaiKey = parameter("OpenAI key").secret().env("OPENAI_API_KEY");
  review = securityReviewer((r) =>
    r.provider("openai").apiKey(this.openaiKey).comment()
  );
  reviewTarget = target().validateBefore(this.review).executes(() => {});
  ghWorkflow = aiReviewWorkflow({ reviewers: [this.review] });
  glWorkflow = aiReviewWorkflow({ host: "gitlab", reviewers: [this.review] });
}

What to generate — only reviewers is required.

The structured result of a review.

A single issue reported by the model.

The kind of review an assessment performs.

Construct a Budget, applying an optional configure lambda so caps can be set inline — e.g. budget((b) => b.maxTokens(100_000).maxCost(1)).

A running token and cost budget for AI provider calls. Build one with budget, set caps with the fluent setters, then fold each call's usage in with Budget.record_ and gate further calls on Budget.exhausted_.

A snapshot of what a Budget has consumed so far.

A cached provider response.

A pluggable backing store for the cache (the default is file-backed).

Where a reviewer's comment-posting token comes from: a secret parameter (for its env var), a literal, or a function that produces the token when a post first needs it — the shape for a token minted by the build itself, such as a GitHub App installation token, so the comments carry the app's identity.

The model's confidence that a fix is correct.

A reviewer that scores the diff for correctness bugs and regressions.

The base-branch fetch a DiffSettings.fetchBase requested — the remote to fetch from and the branch (auto-detected from CI when unset).

Fluent diff source configuration passed to "./reviewer.ts".Reviewer.diff.

Fluent settings for "./reviewer.ts".Reviewer.discussion — who the reviewer listens to on the PR thread, and how much of it the model may see.

The thinking-depth hint passed to providers that support it (Claude).

Read an environment variable, tolerating an absent --allow-env permission.

A whole-file edit: the complete new contents of one file.

A stable fingerprint for a finding: hash of the assessment kind, the normalised title (trimmed, lowercased, whitespace collapsed), and the file. Independent of line number so a finding keeps its id as code shifts.

The structured result of a fix attempt.

A specific code location the fix targets: the exact offending source quoted verbatim, its file and line(s), and the suggested replacement. Rendered as a diff in the report so the comment shows real code, not just prose.

A configured rule for "./reviewer.ts".Reviewer.failWhen.

Fluent gate configuration passed to "./reviewer.ts".Reviewer.failWhen.

A general-purpose reviewer scored on code quality and maintainability. Pair with .criteria(...) to add project-specific notes (idioms, conventions, a coding-style document); the built-in rubric is sufficient without them.

A reviewer that scores the diff for license and compliance risk.

Per-model price in USD per 1,000,000 tokens.

A supported model provider.

What happened before a retry, for RetryOptions.onRetry.

Configurable knobs for retryingFetch.

The comment command that runs the review on demand, configured through AiReviewWorkflowSpec.command.

The job it adds runs on issue_comment, which GitHub delivers for comments on pull requests too, always from the default branch and always with the repository's secrets — so its if: is the whole access control. It fires only when the comment is on a pull request, starts with text, was written by a human (not a bot account), and its author's author_association is OWNER, MEMBER or COLLABORATOR. The comment body is matched in the expression and never interpolated into a run: line. Then, before the review runs, the job asks the collaborators API whether the commenter has push access, and stops if not — an association alone admits read-only members and collaborators.

What runs is the default branch's build, never the pull request's: the job passes ZUKE_REVIEW_PR, and the reviewers fetch that pull request's merge as data and diff it. That is what makes the flow safe for a fork — the code under review is read, not executed — and it is why a pull request cannot change the rules it is judged by from this flow: its zuke.ts, suppressions and criteria never load. The maintainer's comment is the human gate, as it is for Dependabot's @dependabot commands.

A fluent AI reviewer. Construct one via securityReviewer (and the sibling factories), configure it, and attach it to a target with .validateBefore(...) / .validateAfter(...). .provider(...) and .apiKey(...) are required; everything else has a default.

Where a fixer may run, set with .runOnly(...).

- "local" — apply on a developer's machine, refuse on CI. The default, and what a fixer has when .runOnly(...) is never called. - "ci" — apply on CI, and do not run at all off it. The scope a repository's own build wants: heal a pull request without ever rewriting a working tree someone is editing. - "both" — apply on either host. What .allowCI() selects.

"On CI" means any CI system, not only the four Zuke names it can generate pipelines for: isCI recognises GitHub Actions, GitLab CI, Azure Pipelines and Bitbucket Pipelines by their own variables, and Jenkins, Buildkite, CircleCI, Travis, TeamCity and the generic CI convention by theirs.

Reading one of those as a developer's machine would fail in the dangerous direction for both of the other scopes, which is why the broader test is the right one: "ci" would silently skip every run, and "local" — the default — would apply and commit changes to what it believed was a working tree someone was editing. Jenkins is the case that matters most, since it sets none of the four and does not set CI either.

A reviewer that scans the diff for leaked secrets and credentials.

A reviewer that scores the diff for security vulnerabilities.

A severity level, ordered none < low < medium < high < critical.

Construct a Suppressions, applying an optional configure lambda so the file and inline fingerprints can be set inline — e.g. suppressions((s) => s.file(".zuke/suppress.json").add("abc")).

A file-backed set of suppressed finding fingerprints. The effective set is the union of the fingerprints read from Suppressions.file and any added inline with Suppressions.add; the reviewer drops a finding whose findingFingerprint is in that set.

Token counts a provider reported for a review call, when the response carries them. Each field is optional because not every provider reports every count.