programmatic-api.mdx

title	Programmatic API
description	Run a provider-neutral Bugbot review through the request-only package API.

Programmatic API

Import the API from @vypdev/copilot/bugbot. Construct BugbotReviewService with provider-neutral findings and SCM ports, then pass a single BugbotReviewRequest to review.

import {
  ApplicationError,
  BugbotReviewService,
  type BugbotReviewRequest,
  type BugbotScmGateway,
  type FindingsQueryPort,
  type MessageCatalogResolutionPort,
} from '@vypdev/copilot/bugbot';

const service = new BugbotReviewService(findingsPort, scmGateway);

const request: BugbotReviewRequest = {
  target: {
    kind: 'pull-request',
    number: 42,
    head: 'feature/42-checkout',
    base: 'develop',
  },
  agent: {
    provider: 'codex',
    modelProvider: 'openai',
    model: 'gpt-6-luna',
    executable: 'codex',
  },
  configuration: { publicationMode: 'dry-run', effort: 'high' },
};

try {
  const results = await service.review(request);
  for (const result of results) {
    for (const error of result.errors) console.error(error.toJSON());
  }
} catch (error) {
  if (error instanceof ApplicationError) console.error(error.toJSON());
  else throw error;
}

target is a discriminated union: use kind: 'pull-request' with a positive PR number and head branch, or kind: 'branch' with a branch name. Runtime input is validated and bounded even when JavaScript bypasses TypeScript.

The returned error array is readonly and contains only semantic ApplicationError values. toJSON() exposes the safe message, code, category, retry decision, impact, action, retained state, and correlation ID. It never includes a token, provider payload, raw cause, stack, prompt, command arguments, or local path.

locale.issue and locale.pullRequest accept canonicalizable BCP-47 tags and default independently to en-US. Branch or issue-only publication uses the issue locale; publication attached to a verified pull request uses the pull request locale. Invalid tags and unknown locale keys fail before analysis or publication.

The optional third constructor argument is a MessageCatalogResolutionPort. English and Spanish are bundled. For any other valid locale, the service asks that resolver for one complete catalog per review, including every cardinal plural category required by the locale, and reuses it across the status card, review snapshot, inline findings, overflow, and resolution notes. An absent resolver, failed request, or incomplete response falls back atomically to English; a review never mixes partially translated catalog entries. Dry-run, skipped, superseded, and issue-only no-mutation paths do not resolve a presentation catalog.

The API intentionally has no overload accepting the internal runtime aggregate and does not export Execution or Ai. It also never accepts a token in the request. Callers expose the bound { owner, name } repository identity on the BugbotScmGateway and keep its credentials closed inside the adapter before constructing the service; review workflows receive only capability methods. Internal orchestration and authority remain package-owned.

Construction validates, copies, and freezes the gateway's { owner, name } identity. Mutating the caller-owned gateway object later cannot redirect a review or desynchronize its operation context from the already-bound SCM methods. An incomplete identity fails immediately with a semantic validation error.

See Application error reference for the stable code meanings and operator actions.

Native dismissal re-verification

Custom SCM adapters may add listPullRequestReviewThreadStates to the bound publication and resolution ports (and the corresponding unbound port). It returns current native thread facts keyed by the original review-comment identity. The GitHub composition already supplies this query with its existing repository identity and credential binding.

The query is optional for existing adapters, preserving their existing operations. Re-adjudicating an explicitly reopened dismissal requires a fresh fact for that exact comment. A missing query, missing entry, invalid fact or failed read stops the mutation through the existing review-operation error; it never grants authority to overwrite the dismissed reason. A thread that is resolved again is preserved. Keep the original finding/review identity and use the normal recheck after repairing adapter access. No approval policy setting or permission expansion is needed.

Source-bound large reviews

Bugbot passes the selected head SHA as the optional second argument to context.getReviewDiffSnapshot. Gateways that read a mutable PR diff can use that argument to verify the revision and report coverage from the full changed-file inventory. Existing gateway implementations can continue to accept only the PR number.

To support the large framed profile, a custom gateway additionally supplies reviewSource.readCompleteSource and context.getSourceBoundPullRequest. The latter returns the complete current PR identity, including the separately queried live target branch baseRefSha, base ref/comparison SHA, head repository/ref/SHA and native changed-file count. A missing or failed identity read never establishes freshness.

The source port runs in the trusted host and returns complete immutable verified source for the pinned identity, not a model assertion or a workspace placeholder. It must prove full native/immutable path inventory, unique merge-base, regular UTF-8 object contents and patch binding under the closed limits in How it works. Keep credentials inside bound adapters and do not execute consumer source. The built-in GitHub composition supplies the canonical live-ref query and the bounded local read-only Git adapter.

If either capability is absent, an over-envelope review returns validation.evidence-unavailable / bugbot-review-incomplete with resource capability, without reviewer calls or SCM publication. It never silently uses an incomplete ordinary result. Framed dry-run follows all source, receipt and freshness checks while preserving the no-write contract. No request field can increase profile limits or bypass the independent approval policy.