@agilno-tech/rivet 0.1.0-alpha.0

package/src/quality/traceability.js

@@ -0,0 +1,215 @@
+import { claimApproval } from '../policy/approvals.js';
+import { assertQualityRun } from './runner.js';
+
+const ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const AC_ID = /^[A-Z][A-Z0-9]+-[1-9][0-9]*-AC[1-9][0-9]*$/;
+const traceabilityResults = new WeakSet();
+
+export class TraceabilityError extends Error {
+  constructor(reason = 'invalid-traceability-input') {
+    super('Acceptance traceability input is invalid.');
+    this.name = 'TraceabilityError';
+    this.code = 'ERR_TRACEABILITY';
+    this.safeMessage = this.message;
+    this.details = Object.freeze({ reason });
+  }
+}
+
+function fail(reason) { throw new TraceabilityError(reason); }
+
+function capture(value, allowed, required = []) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail('invalid-traceability-input');
+  let keys;
+  try { keys = Reflect.ownKeys(value); } catch { fail('invalid-traceability-input'); }
+  if (keys.some(key => typeof key !== 'string' || !allowed.has(key))) fail('invalid-traceability-input');
+  const result = Object.create(null);
+  for (const key of keys) {
+    let descriptor;
+    try { descriptor = Object.getOwnPropertyDescriptor(value, key); } catch { fail('invalid-traceability-input'); }
+    if (!descriptor?.enumerable || !Object.hasOwn(descriptor, 'value')) fail('invalid-traceability-input');
+    result[key] = descriptor.value;
+  }
+  if (required.some(key => !Object.hasOwn(result, key))) fail('invalid-traceability-input');
+  return result;
+}
+
+function array(value, maximum, convert) {
+  try {
+    if (!Array.isArray(value)) fail('invalid-traceability-input');
+    const length = Object.getOwnPropertyDescriptor(value, 'length')?.value;
+    if (!Number.isSafeInteger(length) || length < 0 || length > maximum
+      || Reflect.ownKeys(value).length !== length + 1) fail('invalid-traceability-input');
+    const result = [];
+    for (let index = 0; index < length; index += 1) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+      if (!descriptor?.enumerable || !Object.hasOwn(descriptor, 'value')) fail('invalid-traceability-input');
+      result.push(convert(descriptor.value));
+    }
+    return result;
+  } catch (error) {
+    if (error instanceof TraceabilityError) throw error;
+    fail('invalid-traceability-input');
+  }
+}
+
+function id(value) {
+  if (typeof value !== 'string' || value.length > 64 || !ID.test(value)) fail('invalid-traceability-input');
+  return value;
+}
+
+function acId(value) {
+  if (typeof value !== 'string' || value.length > 100 || !AC_ID.test(value)) fail('invalid-traceability-input');
+  return value;
+}
+
+function criterion(value) {
+  const input = capture(value, new Set(['id', 'inScope']), ['id', 'inScope']);
+  if (typeof input.inScope !== 'boolean') fail('invalid-traceability-input');
+  return Object.freeze({ id: acId(input.id), inScope: input.inScope });
+}
+
+function manualEvidence(value) {
+  const input = capture(value, new Set([
+    'id', 'acceptanceCriterion', 'expectedApproverId', 'approval',
+  ]), ['id', 'acceptanceCriterion', 'expectedApproverId', 'approval']);
+  return Object.freeze({
+    id: id(input.id),
+    acceptanceCriterion: acId(input.acceptanceCriterion),
+    expectedApproverId: id(input.expectedApproverId),
+    approval: input.approval,
+  });
+}
+
+export function assertTraceabilityResult(value) {
+  if (!traceabilityResults.has(value)) fail('invalid-traceability-input');
+}
+
+function immutable(value) {
+  if (Array.isArray(value)) return Object.freeze(value.map(immutable));
+  if (value && typeof value === 'object') {
+    return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, child]) => [key, immutable(child)])));
+  }
+  return value;
+}
+
+export function validateTraceability(input, options = {}) {
+  const value = capture(input, new Set([
+    'subjectId', 'qualityRun', 'acceptanceCriteria', 'manualReviews',
+  ]), ['subjectId', 'qualityRun', 'acceptanceCriteria', 'manualReviews']);
+  const configured = capture(options, new Set(['approvalRegistry', 'nowMs']), ['approvalRegistry', 'nowMs']);
+  const subjectId = id(value.subjectId);
+  try { assertQualityRun(value.qualityRun); } catch { fail('invalid-traceability-input'); }
+  if (!Number.isSafeInteger(configured.nowMs) || configured.nowMs < 0) fail('invalid-traceability-input');
+  const criteria = array(value.acceptanceCriteria, 2_000, criterion);
+  const tests = value.qualityRun.tests;
+  const manualReviews = array(value.manualReviews, 2_000, manualEvidence);
+  if (criteria.length === 0
+    || new Set(criteria.map(item => item.id.toLowerCase())).size !== criteria.length
+    || new Set(tests.map(item => item.id.toLowerCase())).size !== tests.length
+    || new Set(manualReviews.map(item => item.id.toLowerCase())).size !== manualReviews.length
+    || new Set(manualReviews.map(item => item.acceptanceCriterion.toLowerCase())).size !== manualReviews.length) {
+    fail('invalid-traceability-input');
+  }
+  const known = new Set(criteria.map(item => item.id));
+  if (tests.some(item => item.acceptanceCriteria.some(ac => !known.has(ac)))
+    || manualReviews.some(item => !known.has(item.acceptanceCriterion))) fail('unknown-acceptance-criterion');
+
+  const manualRequired = new Set(criteria
+    .filter(item => item.inScope && !tests.some(test => test.status === 'passed' && test.acceptanceCriteria.includes(item.id)))
+    .map(item => item.id));
+  if (manualReviews.some(review => !manualRequired.has(review.acceptanceCriterion))) {
+    fail('invalid-traceability-input');
+  }
+
+  const approvedManual = new Map();
+  const approvalErrors = new Map();
+  const claims = [];
+  for (const review of manualReviews) {
+    let claim = { valid: false };
+    try {
+      claim = claimApproval(review.approval, {
+          subjectId,
+          action: 'quality.manual-review',
+          resource: 'acceptance:' + review.acceptanceCriterion + ':manual-review:' + review.id,
+          policyId: 'quality.acceptance',
+        }, {
+          registry: configured.approvalRegistry,
+          expectedApproverId: review.expectedApproverId,
+          requireHumanApprover: true,
+          requireSingleUse: true,
+          nowMs: configured.nowMs,
+        });
+    } catch { claim = { valid: false }; }
+    if (claim.valid) {
+      claims.push({ claim, review });
+      approvedManual.set(review.acceptanceCriterion, review);
+    }
+    else approvalErrors.set(review.acceptanceCriterion, 'Acceptance criterion ' + review.acceptanceCriterion + ' lacks exact human approval.');
+  }
+
+  const coverage = [];
+  const errors = [];
+  const outOfScope = [];
+  for (const criterionEntry of [...criteria].sort((left, right) => left.id.localeCompare(right.id))) {
+    if (!criterionEntry.inScope) {
+      outOfScope.push(criterionEntry.id);
+      continue;
+    }
+    const passed = tests
+      .filter(item => item.status === 'passed' && item.acceptanceCriteria.includes(criterionEntry.id))
+      .sort((left, right) => left.id.localeCompare(right.id))[0];
+    if (passed) {
+      coverage.push({
+        acceptanceCriterion: criterionEntry.id,
+        method: 'test',
+        evidenceId: passed.id,
+        gateId: passed.gateId,
+        resultPath: passed.resultPath,
+        resultSha256: passed.resultSha256,
+      });
+      continue;
+    }
+    const manual = approvedManual.get(criterionEntry.id);
+    if (manual) {
+      coverage.push({
+        acceptanceCriterion: criterionEntry.id,
+        method: 'manual-review',
+        evidenceId: manual.id,
+        approvalReceiptId: manual.approval.id,
+        approverId: manual.approval.approverId,
+        approverPrincipal: manual.approval.approverPrincipal,
+      });
+      continue;
+    }
+    errors.push(approvalErrors.get(criterionEntry.id)
+      ?? 'Acceptance criterion ' + criterionEntry.id + ' lacks a passed deterministic test or exact human approval.');
+  }
+  if (errors.length > 0) {
+    for (const entry of claims) entry.claim.release();
+  } else {
+    const finalized = [];
+    try {
+      for (const entry of claims) {
+        if (!entry.claim.finalize()) fail('approval-transaction-failed');
+        finalized.push(entry);
+      }
+      for (const entry of claims) {
+        if (!entry.claim.publish()) fail('approval-transaction-failed');
+      }
+    } catch (error) {
+      for (const entry of finalized) entry.claim.rollback();
+      for (const entry of claims) if (!finalized.includes(entry)) entry.claim.release();
+      if (error instanceof TraceabilityError) throw error;
+      fail('approval-transaction-failed');
+    }
+  }
+  const output = immutable({
+    valid: errors.length === 0,
+    commitSha: value.qualityRun.commitSha,
+    coverage,
+    outOfScope,
+    errors,
+  });
+  traceabilityResults.add(output);
+  return output;
+}

package/src/repositories/identity.js

@@ -0,0 +1,59 @@
+import { resolve } from 'node:path';
+import { boundedString, captureRecord, failProvider } from '../adapters/contract.js';
+import { runArgv } from '../discovery/tools.js';
+
+const HOSTS = Object.freeze({ 'github.com': 'github', 'bitbucket.org': 'bitbucket', 'gitlab.com': 'gitlab' });
+const SEGMENT = /^[A-Za-z0-9_][A-Za-z0-9._-]{0,99}$/;
+
+export function parseRepositoryRemote(input) {
+  const value = boundedString(input, 2048);
+  // Parse before URL normalization, which would otherwise silently remove traversal.
+  const match = /^(?:https:\/\/|ssh:\/\/git@)([^/:?#]+)\/([^?#]+)$/.exec(value)
+    ?? /^git@([^/:?#]+):([^?#]+)$/.exec(value);
+  if (!match || !Object.hasOwn(HOSTS, match[1])) failProvider('invalid-request');
+  const host = match[1];
+  const fullName = match[2].replace(/\.git$/, '');
+  const segments = fullName.split('/');
+  if (segments.length < 2 || segments.length > 20 || fullName.length > 255
+    || (host !== 'gitlab.com' && segments.length !== 2)
+    || segments.some(part => !SEGMENT.test(part) || part === '.' || part === '..' || part.endsWith('.'))) failProvider('invalid-request');
+  return Object.freeze({ provider: HOSTS[host], host, namespace: segments.slice(0, -1).join('/'), name: segments.at(-1), fullName, url: `https://${host}/${fullName}` });
+}
+
+export function selectRepositoryRemote(input, options = {}) {
+  const { remoteName } = captureRecord(options, new Set(['remoteName']), []);
+  if (remoteName !== undefined) boundedString(remoteName, 100, /^[A-Za-z0-9][A-Za-z0-9._-]*$/);
+  if (!Array.isArray(input) || input.length < 1 || input.length > 100) failProvider('invalid-request');
+  const candidates = input.map(value => {
+    const remote = captureRecord(value, new Set(['name', 'url']), ['name', 'url']);
+    boundedString(remote.name, 100, /^[A-Za-z0-9][A-Za-z0-9._-]*$/);
+    return remote;
+  }).filter(remote => remoteName === undefined || remote.name === remoteName);
+  if (candidates.length === 0) failProvider('invalid-request');
+  const parsed = candidates.map(remote => ({ ...parseRepositoryRemote(remote.url), remoteName: remote.name }));
+  if (new Set(parsed.map(remote => remote.url)).size !== 1) failProvider('invalid-request');
+  return Object.freeze(parsed[0]);
+}
+
+export async function discoverRepositoryRemotes(projectRoot, { runner = runArgv } = {}) {
+  let result;
+  try { result = await runner('git', ['remote', '-v'], { cwd: resolve(projectRoot), shell: false, timeoutMs: 3000, maxOutputBytes: 32768 }); }
+  catch { failProvider('invalid-request'); }
+  if (result?.code !== 0 || result.timedOut === true || result.truncated?.stdout === true || typeof result.stdout !== 'string' || Buffer.byteLength(result.stdout) > 32768) failProvider('invalid-request');
+  const remotes = [];
+  for (const line of result.stdout.trim().split('\n').filter(Boolean)) {
+    const match = /^(\S+)\s+(\S+) \((fetch|push)\)$/.exec(line);
+    if (!match) failProvider('invalid-request');
+    if (match[3] === 'fetch') remotes.push(Object.freeze({ name: boundedString(match[1], 100, /^[A-Za-z0-9][A-Za-z0-9._-]*$/), url: boundedString(match[2], 2048) }));
+  }
+  if (remotes.length > 100) failProvider('invalid-request');
+  return Object.freeze(remotes);
+}
+
+// Explicit per-operation choices do not rewrite the tracked onboarding preference.
+export function selectConfiguredRepositoryRemote(remotes, preference, remoteName) {
+  const selected = selectRepositoryRemote(remotes, remoteName !== undefined ? {remoteName}
+    : preference ? {remoteName: preference.name} : {});
+  if (remoteName === undefined && preference && selected.url !== preference.url) failProvider('invalid-request');
+  return selected;
+}

package/src/repositories/index.js

@@ -0,0 +1,2 @@
+export { parseRepositoryRemote, selectRepositoryRemote, selectConfiguredRepositoryRemote, discoverRepositoryRemotes } from './identity.js';
+export { createRepositoryProvider } from './provider.js';

package/src/repositories/provider.js

@@ -0,0 +1,210 @@
+import { boundedString, captureRecord, failProvider, immutableRedactedJson, providerTimestamp } from '../adapters/contract.js';
+import { createGithubAdapter } from '../adapters/github.js';
+import { createProviderHttpClient } from '../adapters/http.js';
+import { parseRepositoryRemote } from './identity.js';
+
+const ENDPOINTS = Object.freeze({ github: 'https://api.github.com', bitbucket: 'https://api.bitbucket.org/2.0', gitlab: 'https://gitlab.com/api/v4' });
+const CAPABILITIES = Object.freeze({ read: Object.freeze(['repository', 'branch', 'review-request', 'checks', 'reviews']), write: Object.freeze([]) });
+const SHA = /^[a-f0-9]{40}$/;
+const BRANCH = /^[A-Za-z0-9_][A-Za-z0-9._/-]{0,254}$/;
+function remote(condition, provider) { if (!condition) failProvider('remote', { provider, retryClassification: 'permanent' }); }
+function record(value, provider) { remote(value !== null && typeof value === 'object' && !Array.isArray(value), provider); return value; }
+function text(value, provider, maximum = 1024) { remote(typeof value === 'string' && value.length > 0 && value.length <= maximum, provider); return value; }
+function sha(value, provider) { remote(typeof value === 'string' && SHA.test(value), provider); return value; }
+function ref(value, provider) { remote(typeof value === 'string' && BRANCH.test(value) && !value.includes('..') && !value.includes('//'), provider); return value; }
+function positive(value, provider) { remote(Number.isSafeInteger(value) && value > 0, provider); return value; }
+function boundUrl(value, expected, provider) { remote(value === expected, provider); return value; }
+function number(value) { if (!Number.isSafeInteger(value) || value < 1 || value > 1_000_000_000) failProvider('invalid-request'); return value; }
+
+export function createRepositoryProvider(input) {
+  const config = captureRecord(input, new Set(['repository', 'transport', 'headers', 'timeoutMs', 'maxResponseBytes', 'maxPages', 'maxItems', 'clock']), ['repository', 'transport'], 'invalid-config');
+  const supplied = captureRecord(config.repository, new Set(['provider', 'host', 'namespace', 'name', 'fullName', 'url', 'remoteName']), ['provider', 'host', 'namespace', 'name', 'fullName', 'url'], 'invalid-config');
+  const repository = parseRepositoryRemote(supplied.url);
+  for (const key of Object.keys(repository)) if (repository[key] !== supplied[key]) failProvider('invalid-config');
+  const provider = repository.provider;
+  const clock = config.clock ?? (() => new Date().toISOString());
+  if (typeof clock !== 'function') failProvider('invalid-config', { provider });
+  const limits = Object.fromEntries(['headers', 'timeoutMs', 'maxResponseBytes', 'maxPages', 'maxItems'].filter(key => config[key] !== undefined).map(key => [key, config[key]]));
+  const http = createProviderHttpClient({ provider, transport: config.transport, baseUrl: ENDPOINTS[provider], ...limits, allowEncodedSlash: true });
+  const github = provider === 'github' ? createGithubAdapter({ transport: config.transport, baseUrl: ENDPOINTS.github, ...limits, clock }) : null;
+  const root = provider === 'github' ? `/repos/${repository.fullName}` : provider === 'bitbucket' ? `/repositories/${repository.fullName}` : `/projects/${encodeURIComponent(repository.fullName)}`;
+  const reviewRoot = provider === 'github' ? 'pulls' : provider === 'bitbucket' ? 'pullrequests' : 'merge_requests';
+  const maxPages = config.maxPages ?? 20, maxItems = config.maxItems ?? 10_000;
+  const request = (path, signal) => http.request({ method: 'GET', path, ...(signal === undefined ? {} : { signal }) });
+
+  async function bitbucketPages(path, signal) {
+    const initial = new URL(http.urlFor(`${path}?pagelen=100`));
+    const output = [], seen = new Set();
+    let next = initial.href, declaredSize;
+    for (let page = 0; page < maxPages; page += 1) {
+      let url;
+      try { url = new URL(next); } catch { failProvider('remote', { provider }); }
+      remote(url.origin === initial.origin && url.pathname === initial.pathname && !url.username && !url.password && !url.hash, provider);
+      remote([...url.searchParams.keys()].every(key => ['page', 'pagelen'].includes(key)) && url.searchParams.getAll('pagelen').length === 1
+        && url.searchParams.get('pagelen') === '100' && url.searchParams.getAll('page').length <= 1
+        && (!url.searchParams.has('page') || /^[1-9][0-9]{0,8}$/.test(url.searchParams.get('page'))), provider);
+      remote(Number(url.searchParams.get('page') ?? 1) === page + 1, provider);
+      remote(!seen.has(url.href), provider); seen.add(url.href);
+      const response = await request(`${url.pathname.slice('/2.0'.length)}${url.search}`, signal);
+      remote(Array.isArray(response.data?.values), provider);
+      if (response.data.size !== undefined) {
+        remote(Number.isSafeInteger(response.data.size) && response.data.size >= 0 && (declaredSize === undefined || declaredSize === response.data.size), provider);
+        declaredSize = response.data.size;
+        if (declaredSize > maxItems) failProvider('pagination-limit', { provider });
+      }
+      if (response.data.page !== undefined) remote(response.data.page === page + 1, provider);
+      output.push(...response.data.values);
+      if (declaredSize !== undefined) remote(output.length <= declaredSize, provider);
+      if (output.length > maxItems) failProvider('pagination-limit', { provider });
+      if (response.data.next === undefined || response.data.next === null) {
+        if (declaredSize !== undefined) remote(output.length === declaredSize, provider);
+        return output;
+      }
+      remote(typeof response.data.next === 'string' && response.data.next.length <= 4096 && response.data.values.length > 0, provider);
+      next = response.data.next;
+    }
+    failProvider('pagination-limit', { provider });
+  }
+
+  async function repositoryInfo(signal) {
+    if (github) {
+      const value = (await github.read({ kind: 'repo', owner: repository.namespace, repo: repository.name, ...(signal === undefined ? {} : { signal }) })).normalized.repository;
+      return { ...repository, id: value.id, defaultBranch: value.defaultBranch, private: value.private };
+    }
+    const value = (await request(root, signal)).data;
+    if (provider === 'bitbucket') {
+      remote(value?.full_name === repository.fullName && typeof value.is_private === 'boolean', provider);
+      boundUrl(value.links?.html?.href, repository.url, provider);
+      return { ...repository, id: text(value.uuid, provider), defaultBranch: value.mainbranch === null ? null : ref(value.mainbranch?.name, provider), private: value.is_private };
+    }
+    remote(value?.path_with_namespace === repository.fullName && ['private', 'internal', 'public'].includes(value.visibility), provider);
+    boundUrl(value.web_url, repository.url, provider);
+    return { ...repository, id: positive(value.id, provider), defaultBranch: value.default_branch === null ? null : ref(value.default_branch, provider), private: value.visibility !== 'public' };
+  }
+
+  async function branchInfo(branch, signal) {
+    boundedString(branch, 255, BRANCH); if (branch.includes('..') || branch.includes('//')) failProvider('invalid-request');
+    if (github) {
+      const value = (await request(`${root}/branches/${encodeURIComponent(branch)}`, signal)).data;
+      remote(value?.name === branch && typeof value.protected === 'boolean', provider);
+      return { name: branch, commitSha: sha(value.commit?.sha, provider), protected: value.protected };
+    }
+    const value = (await request(`${root}/${provider === 'bitbucket' ? 'refs' : 'repository'}/branches/${encodeURIComponent(branch)}`, signal)).data;
+    remote(value?.name === branch, provider);
+    return { name: branch, commitSha: sha(provider === 'bitbucket' ? value.target?.hash : value.commit?.id, provider), protected: provider === 'bitbucket' ? null : typeof value.protected === 'boolean' ? value.protected : null };
+  }
+
+  async function reviewInfo(reviewNumber, signal) {
+    const value = (await request(`${root}/${reviewRoot}/${number(reviewNumber)}`, signal)).data;
+    let result;
+    if (provider === 'github') {
+      remote(value?.number === reviewNumber && ['open', 'closed'].includes(value.state) && typeof value.merged === 'boolean', provider);
+      result = { number: reviewNumber, state: value.merged ? 'merged' : value.state, title: text(value.title, provider), headSha: sha(value.head?.sha, provider), headBranch: ref(value.head?.ref, provider), baseBranch: ref(value.base?.ref, provider), url: boundUrl(value.html_url, `${repository.url}/pull/${reviewNumber}`, provider) };
+    } else if (provider === 'bitbucket') {
+      remote(value?.id === reviewNumber && ['OPEN', 'MERGED', 'DECLINED', 'SUPERSEDED'].includes(value.state) && value.destination?.repository?.full_name === repository.fullName, provider);
+      result = { number: reviewNumber, state: value.state === 'OPEN' ? 'open' : value.state === 'MERGED' ? 'merged' : 'closed', title: text(value.title, provider), headSha: sha(value.source?.commit?.hash, provider), headBranch: ref(value.source?.branch?.name, provider), baseBranch: ref(value.destination?.branch?.name, provider), url: boundUrl(value.links?.html?.href, `${repository.url}/pull-requests/${reviewNumber}`, provider) };
+    } else {
+      remote(value?.iid === reviewNumber && ['opened', 'closed', 'locked', 'merged'].includes(value.state), provider);
+      result = { number: reviewNumber, state: value.state === 'opened' ? 'open' : value.state, title: text(value.title, provider), headSha: sha(value.sha, provider), headBranch: ref(value.source_branch, provider), baseBranch: ref(value.target_branch, provider), url: boundUrl(value.web_url, `${repository.url}/-/merge_requests/${reviewNumber}`, provider) };
+    }
+    return { result, raw: value };
+  }
+
+  async function checksInfo(commitSha, signal) {
+    boundedString(commitSha, 40, SHA);
+    const options = signal === undefined ? {} : { signal };
+    let items;
+    if (provider === 'github') {
+      const checks = await http.paginate({ path: `${root}/commits/${commitSha}/check-runs?per_page=100`, itemsKey: 'check_runs', identityKey: 'id', totalKey: 'total_count', ...options });
+      const statuses = await http.paginate({ path: `${root}/commits/${commitSha}/statuses?per_page=100`, identityKey: 'id', ...options });
+      items = checks.map(value => {
+        record(value, provider);
+        positive(value.id, provider); sha(value.head_sha, provider);
+        if (value.head_sha !== commitSha) failProvider('state-conflict', { provider });
+        remote(['queued', 'in_progress', 'completed', 'pending', 'requested', 'waiting'].includes(value.status), provider);
+        const conclusions = { success: 'success', failure: 'failure', timed_out: 'failure', cancelled: 'cancelled', skipped: 'skipped', neutral: 'neutral', action_required: 'blocked', stale: 'stale' };
+        if (value.status === 'completed') remote(Object.hasOwn(conclusions, value.conclusion), provider);
+        return { id: `check:${value.id}`, name: text(value.name, provider), commitSha, state: value.status === 'completed' ? conclusions[value.conclusion] : 'pending' };
+      });
+      items.push(...statuses.map(value => {
+        record(value, provider);
+        positive(value.id, provider);
+        if (value.sha !== undefined && value.sha !== commitSha) failProvider('state-conflict', { provider });
+        remote(['success', 'failure', 'error', 'pending'].includes(value.state), provider);
+        return { id: `status:${value.id}`, name: text(value.context, provider), commitSha, state: value.state === 'error' ? 'failure' : value.state };
+      }));
+    } else if (provider === 'bitbucket') {
+      const values = await bitbucketPages(`${root}/commit/${commitSha}/statuses`, signal);
+      items = values.map(value => {
+        record(value, provider);
+        if (value.links?.commit?.href !== undefined && value.links.commit.href !== `${ENDPOINTS.bitbucket}${root}/commit/${commitSha}`) failProvider('state-conflict', { provider });
+        const states = { SUCCESSFUL: 'success', FAILED: 'failure', INPROGRESS: 'pending', STOPPED: 'cancelled' };
+        remote(Object.hasOwn(states, value.state), provider);
+        return { id: text(value.key, provider), name: text(value.name || value.key, provider), commitSha, state: states[value.state] };
+      });
+    } else {
+      const values = await http.paginate({ path: `${root}/repository/commits/${commitSha}/statuses?per_page=100`, identityKey: 'id', ...options });
+      items = values.map(value => {
+        record(value, provider);
+        positive(value.id, provider); sha(value.sha, provider);
+        if (value.sha !== commitSha) failProvider('state-conflict', { provider });
+        const states = { pending: 'pending', running: 'pending', success: 'success', failed: 'failure', canceled: 'cancelled', skipped: 'skipped', created: 'pending', manual: 'blocked', scheduled: 'pending', preparing: 'pending', waiting_for_resource: 'pending' };
+        remote(Object.hasOwn(states, value.status), provider);
+        return { id: String(value.id), name: text(value.name, provider), commitSha, state: states[value.status] };
+      });
+    }
+    remote(new Set(items.map(value => value.id)).size === items.length, provider);
+    return { commitSha, items, requiredPolicy: 'unknown' };
+  }
+
+  async function reviewsInfo(reviewNumber, signal) {
+    number(reviewNumber);
+    let items;
+    if (provider === 'github') {
+      const values = await http.paginate({ path: `${root}/pulls/${reviewNumber}/reviews?per_page=100`, identityKey: 'id', ...(signal === undefined ? {} : {signal}) });
+      items = values.map(value => {
+        record(value, provider);
+        positive(value.id, provider); remote(['PENDING', 'COMMENTED', 'APPROVED', 'CHANGES_REQUESTED', 'DISMISSED'].includes(value.state), provider);
+        return { id: String(value.id), reviewer: text(value.user?.login, provider), state: value.state.toLowerCase(), commitSha: value.commit_id == null ? null : sha(value.commit_id, provider) };
+      });
+    } else if (provider === 'bitbucket') {
+      const { raw } = await reviewInfo(reviewNumber, signal);
+      remote(Array.isArray(raw.participants) && raw.participants.length <= maxItems, provider);
+      items = raw.participants.map(value => {
+        record(value, provider);
+        remote(typeof value.approved === 'boolean', provider);
+        return { reviewer: text(value.user?.uuid, provider), state: value.approved ? 'approved' : value.state === 'changes_requested' ? 'changes_requested' : 'unapproved', commitSha: null };
+      });
+    } else {
+      const value = (await request(`${root}/merge_requests/${reviewNumber}/approvals`, signal)).data;
+      remote(value?.iid === reviewNumber && Array.isArray(value.approved_by) && value.approved_by.length <= maxItems, provider);
+      items = value.approved_by.map(entry => ({ reviewer: text(record(entry, provider).user?.username, provider), state: 'approved', commitSha: null }));
+    }
+    return { items, policy: 'unknown' };
+  }
+
+  async function read(inputRead) {
+    const value = captureRecord(inputRead, new Set(['kind', 'branch', 'number', 'commitSha', 'signal']), ['kind']);
+    if (!CAPABILITIES.read.includes(value.kind)) failProvider('invalid-request', { provider });
+    let normalized;
+    if (value.kind === 'repository') normalized = { repository: await repositoryInfo(value.signal) };
+    else if (value.kind === 'branch') normalized = { branch: await branchInfo(value.branch, value.signal) };
+    else if (value.kind === 'review-request') normalized = { reviewRequest: (await reviewInfo(value.number, value.signal)).result };
+    else if (value.kind === 'checks') normalized = { checks: await checksInfo(value.commitSha, value.signal) };
+    else normalized = { reviews: await reviewsInfo(value.number, value.signal) };
+    return immutableRedactedJson({ repository, ...normalized, observedAt: providerTimestamp(clock, provider), capabilities: CAPABILITIES });
+  }
+
+  async function inspect(inputInspect) {
+    const value = captureRecord(inputInspect, new Set(['number', 'signal']), ['number']);
+    number(value.number);
+    const info = await repositoryInfo(value.signal);
+    const review = (await reviewInfo(value.number, value.signal)).result;
+    const checks = await checksInfo(review.headSha, value.signal);
+    const reviews = await reviewsInfo(value.number, value.signal);
+    const latest = (await reviewInfo(value.number, value.signal)).result;
+    if (latest.headSha !== review.headSha || latest.state !== review.state || latest.baseBranch !== review.baseBranch) failProvider('state-conflict', { provider });
+    return immutableRedactedJson({ repository: info, reviewRequest: latest, checks, reviews, observedAt: providerTimestamp(clock, provider), consistency: 'head-rechecked', capabilities: CAPABILITIES });
+  }
+  return Object.freeze({ provider, repository, capabilities: CAPABILITIES, read, inspect, write() { failProvider('read-only', { provider }); } });
+}