Multi-Agent Collaboration for Team and Friends
TypeScript agent-automationagent-orchestrationagent-workflowai-agentsai-collaborationai-memoryai-workforceautonomous-agentsclaude-codeclaude-code-skillscodexcoding-agentmulti-agentmultiple-agentone-person-businessone-person-companyone-person-teamopencodesolopreneur
ci: bootstrap trusted API surface guard (#510)
Gustavo Yeef08ae9ba7e2
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERSindex 5fb7c8da0..085f384bd 100644--- a/.github/CODEOWNERS+++ b/.github/CODEOWNERS@@ -3,3 +3,15 @@# CI/CD workflows require review.github/ @alookai/core-dev++# Published agent-driver API entry points and their golden reports+/src/daemon/agent-driver/etc/api/ @alookai/core-dev+/src/daemon/agent-driver/src/index.ts @alookai/core-dev+/src/daemon/agent-driver/src/host.ts @alookai/core-dev+/src/daemon/agent-driver/src/adapter-author.ts @alookai/core-dev+/src/daemon/agent-driver/src/testing/ @alookai/core-dev+/src/daemon/agent-driver/src/public-contract.ts @alookai/core-dev+/src/daemon/agent-driver/src/public-sdk.ts @alookai/core-dev+/src/daemon/agent-driver/src/contract.ts @alookai/core-dev+/src/daemon/agent-driver/src/registry.ts @alookai/core-dev+/src/daemon/agent-driver/src/internal/adapter.ts @alookai/core-devdiff --git a/.github/api-surface-owners.json b/.github/api-surface-owners.jsonnew file mode 100644index 000000000..83a026a4d--- /dev/null+++ b/.github/api-surface-owners.json@@ -0,0 +1,3 @@+{+ "owners": ["gusye1234", "GenerQAQ", "LindsayLiu777"]+}diff --git a/.github/workflows/api-surface-guard.yml b/.github/workflows/api-surface-guard.ymlnew file mode 100644index 000000000..892afebd2--- /dev/null+++ b/.github/workflows/api-surface-guard.yml@@ -0,0 +1,38 @@+name: API Surface Guard++on:+ pull_request_target:+ branches: [main]+ types: [opened, synchronize, reopened, labeled, unlabeled]+ pull_request_review:+ types: [submitted, dismissed]++permissions:+ contents: read+ pull-requests: read++concurrency:+ group: api-surface-${{ github.event.pull_request.number }}+ cancel-in-progress: true++jobs:+ api-surface-guard:+ if: github.event.pull_request.base.ref == 'main'+ name: Current-head API Owner Approval+ runs-on: ubuntu-latest+ timeout-minutes: 5+ steps:+ - name: Checkout trusted base+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7+ with:+ ref: ${{ github.event.pull_request.base.sha }}+ - name: Enforce current-head independent approval+ env:+ API_BASE_SHA: ${{ github.event.pull_request.base.sha }}+ API_HEAD_SHA: ${{ github.event.pull_request.head.sha }}+ API_PR_AUTHOR: ${{ github.event.pull_request.user.login }}+ API_PR_NUMBER: ${{ github.event.pull_request.number }}+ API_REPOSITORY: ${{ github.repository }}+ API_GITHUB_TOKEN: ${{ github.token }}+ API_LABELS_JSON: ${{ toJSON(github.event.pull_request.labels) }}+ run: node scripts/ci/api-surface-guard.mjsdiff --git a/scripts/ci/api-surface-guard.mjs b/scripts/ci/api-surface-guard.mjsnew file mode 100644index 000000000..f2621a89f--- /dev/null+++ b/scripts/ci/api-surface-guard.mjs@@ -0,0 +1,291 @@+import { readFile } from "node:fs/promises";+import { dirname, resolve } from "node:path";+import { fileURLToPath } from "node:url";++const API_LABELS = ["api-additive", "api-breaking"];+const API_REPORT_PREFIX = "src/daemon/agent-driver/etc/api/";+const API_SOURCE_PATHS = new Set([+ "src/daemon/agent-driver/src/index.ts",+ "src/daemon/agent-driver/src/host.ts",+ "src/daemon/agent-driver/src/adapter-author.ts",+ "src/daemon/agent-driver/src/testing/index.ts",+ "src/daemon/agent-driver/src/testing/conformance.ts",+ "src/daemon/agent-driver/src/testing/fake-host.ts",+ "src/daemon/agent-driver/src/public-contract.ts",+ "src/daemon/agent-driver/src/public-sdk.ts",+ "src/daemon/agent-driver/src/contract.ts",+ "src/daemon/agent-driver/src/registry.ts",+ "src/daemon/agent-driver/src/internal/adapter.ts",+]);+const API_MECHANISM_PATHS = new Set([+ ".github/CODEOWNERS",+ ".github/api-surface-owners.json",+ ".github/workflows/api-surface-check.yml",+ ".github/workflows/api-surface-guard.yml",+ "package.json",+ "pnpm-lock.yaml",+ "pnpm-workspace.yaml",+ "scripts/ci/api-report-contract.test.ts",+ "scripts/ci/api-surface-guard.mjs",+ "scripts/ci/api-surface-guard.test.ts",+ "src/daemon/agent-driver/api-extractor.adapter-author.json",+ "src/daemon/agent-driver/api-extractor.host.json",+ "src/daemon/agent-driver/api-extractor.root.json",+ "src/daemon/agent-driver/api-extractor.testing.json",+ "src/daemon/agent-driver/package.json",+ "src/daemon/agent-driver/scripts/api-reports.mjs",+ "src/daemon/agent-driver/scripts/prepare-dist.mjs",+ "src/daemon/agent-driver/scripts/prune-dist.mjs",+ "src/daemon/agent-driver/tsconfig.build.json",+ "src/daemon/agent-driver/tsconfig.json",+ "vitest.config.ts",+]);++export function isApiSurfacePath(path) {+ return path.startsWith(API_REPORT_PREFIX) || API_SOURCE_PATHS.has(path);+}++export function isApiMechanismPath(path) {+ return API_MECHANISM_PATHS.has(path);+}++export function collectChangedPaths(files, expectedChangedFileCount) {+ if (!Array.isArray(files)) throw new Error("Invalid pull request files response");+ if (!Number.isSafeInteger(expectedChangedFileCount) || expectedChangedFileCount < 0) {+ throw new Error("Invalid pull request changed_files count");+ }++ const returnedFileNames = new Set();+ const changedPaths = new Set();+ for (const file of files) {+ if (!file || typeof file.filename !== "string" || file.filename.length === 0) {+ throw new Error("Invalid pull request file entry");+ }+ returnedFileNames.add(file.filename);+ changedPaths.add(file.filename);+ if (file.previous_filename !== undefined) {+ if (typeof file.previous_filename !== "string" || file.previous_filename.length === 0) {+ throw new Error("Invalid pull request previous filename");+ }+ changedPaths.add(file.previous_filename);+ }+ }++ if (returnedFileNames.size !== expectedChangedFileCount) {+ throw new Error(+ `Incomplete pull request files response: expected ${expectedChangedFileCount}, received ${returnedFileNames.size}`,+ );+ }+ return [...changedPaths];+}++export function parseAdapterAuthorContractVersion(source) {+ const identifier = "ADAPTER_AUTHOR_CONTRACT_VERSION";+ const occurrences = source.match(new RegExp(`\\b${identifier}\\b`, "g")) ?? [];+ if (occurrences.length === 0) return null;+ if (occurrences.length > 1) throw new Error("Multiple adapter-author contract version references");++ let offset = source.charCodeAt(0) === 0xfeff ? 1 : 0;+ while (offset < source.length) {+ const remainder = source.slice(offset);+ const whitespace = remainder.match(/^\s+/);+ if (whitespace) {+ offset += whitespace[0].length;+ continue;+ }+ if (remainder.startsWith("//")) {+ const newline = remainder.indexOf("\n");+ offset += newline === -1 ? remainder.length : newline + 1;+ continue;+ }+ if (remainder.startsWith("/*")) {+ const end = remainder.indexOf("*/", 2);+ if (end === -1) throw new Error("Unterminated leading comment in adapter-author contract source");+ offset += end + 2;+ continue;+ }+ break;+ }++ const declaration = source.slice(offset).match(+ /^export[\t ]+const[\t ]+ADAPTER_AUTHOR_CONTRACT_VERSION[\t ]*=[\t ]*(\d+)(?:[\t ]+as[\t ]+const)?[\t ]*;?[\t ]*(?:\r?\n|$)/,+ );+ if (!declaration) throw new Error("Invalid adapter-author contract version declaration");+ const version = Number(declaration[1]);+ if (!Number.isSafeInteger(version) || version < 1) {+ throw new Error("Invalid adapter-author contract version declaration");+ }+ return version;+}++export function evaluateApiSurfaceGuard(input) {+ const changedApiPaths = input.changedPaths.filter(isApiSurfacePath);+ const changedMechanismPaths = input.changedPaths.filter(isApiMechanismPath);+ if (changedApiPaths.length === 0 && changedMechanismPaths.length === 0) {+ return { ok: true, reason: "no_api_surface_change" };+ }++ const selectedLabels = API_LABELS.filter((label) => input.labels.includes(label));+ const adapterAuthorReportChanged = changedApiPaths.includes(`${API_REPORT_PREFIX}adapter-author.api.md`);+ let baseVersion;+ let headVersion;+ let baseHasVersion;+ let headHasVersion;+ if (changedApiPaths.length > 0) {+ baseVersion = input.baseContractVersion;+ headVersion = input.headContractVersion;+ baseHasVersion = Number.isSafeInteger(baseVersion) && baseVersion >= 1;+ headHasVersion = Number.isSafeInteger(headVersion) && headVersion >= 1;+ if ((baseVersion !== null && !baseHasVersion) || (headVersion !== null && !headHasVersion)) {+ return { ok: false, reason: "invalid_adapter_author_contract_version", changedApiPaths };+ }+ if (baseHasVersion && (!headHasVersion || headVersion < baseVersion)) {+ return { ok: false, reason: "adapter_author_contract_version_must_not_regress", changedApiPaths };+ }+ if (baseHasVersion && headHasVersion && headVersion > baseVersion) {+ const isBreakingReportChange = adapterAuthorReportChanged+ && selectedLabels.length === 1+ && selectedLabels[0] === "api-breaking";+ if (!isBreakingReportChange) {+ return { ok: false, reason: "adapter_author_contract_version_bump_requires_breaking_report", changedApiPaths };+ }+ }+ if (adapterAuthorReportChanged && !headHasVersion) {+ return { ok: false, reason: "adapter_author_contract_version_required", changedApiPaths };+ }+ if (baseVersion === null && headHasVersion) {+ const isBreakingBootstrap = adapterAuthorReportChanged+ && selectedLabels.length === 1+ && selectedLabels[0] === "api-breaking"+ && headVersion === 1;+ if (!isBreakingBootstrap) {+ return { ok: false, reason: "adapter_author_contract_version_bootstrap_requires_breaking_v1", changedApiPaths };+ }+ }+ if (selectedLabels.length !== 1) {+ return { ok: false, reason: "exactly_one_api_label_required", changedApiPaths };+ }+ }++ const latestByReviewer = new Map();+ for (const review of [...input.reviews].sort((a, b) => a.id - b.id)) {+ latestByReviewer.set(review.login.toLowerCase(), review);+ }+ const author = input.prAuthor.toLowerCase();+ const owners = new Set(input.owners.map((owner) => owner.toLowerCase()));+ const approver = [...latestByReviewer.values()].find((review) =>+ owners.has(review.login.toLowerCase())+ && review.login.toLowerCase() !== author+ && review.state === "APPROVED"+ && review.commitId === input.headSha+ );+ if (!approver) {+ return {+ ok: false,+ reason: "current_head_independent_owner_approval_required",+ changedApiPaths,+ changedMechanismPaths,+ };+ }++ if (selectedLabels[0] === "api-breaking" && adapterAuthorReportChanged) {+ const isInitialVersion = baseVersion === null && headVersion === 1;+ const isIncrement = baseHasVersion && headHasVersion && headVersion > baseVersion;+ if (!isInitialVersion && !isIncrement) {+ return { ok: false, reason: "adapter_author_contract_version_must_increase", changedApiPaths };+ }+ }++ return { ok: true, reason: "approved", approver: approver.login, changedApiPaths, changedMechanismPaths };+}++export async function githubJson(url, token, allowNotFound = false) {+ const response = await fetch(url, {+ headers: {+ Accept: "application/vnd.github+json",+ Authorization: `Bearer ${token}`,+ "X-GitHub-Api-Version": "2022-11-28",+ },+ });+ if (allowNotFound && response.status === 404) return null;+ if (!response.ok) throw new Error(`GitHub API failed: ${response.status}`);+ return response.json();+}++export async function fetchAllPages(repository, pullNumber, resource, token) {+ const values = [];+ for (let page = 1; ; page += 1) {+ const pageValues = await githubJson(+ `https://api.github.com/repos/${repository}/pulls/${pullNumber}/${resource}?per_page=100&page=${page}`,+ token,+ );+ values.push(...pageValues);+ if (pageValues.length < 100) break;+ }+ return values;+}++export async function fetchAllReviews(repository, pullNumber, token) {+ const reviews = await fetchAllPages(repository, pullNumber, "reviews", token);+ return reviews.filter((review) => review.user?.login).map((review) => ({+ id: review.id,+ login: review.user.login,+ state: review.state,+ commitId: review.commit_id,+ }));+}++export async function contractVersionAt(repository, sha, token) {+ const path = "src/daemon/agent-driver/src/adapter-author.ts";+ const value = await githubJson(+ `https://api.github.com/repos/${repository}/contents/${path}?ref=${sha}`,+ token,+ true,+ );+ if (!value?.content || value.encoding !== "base64") return null;+ const source = Buffer.from(value.content, "base64").toString("utf8");+ return parseAdapterAuthorContractVersion(source);+}++export async function main() {+ const required = ["API_BASE_SHA", "API_HEAD_SHA", "API_PR_AUTHOR", "API_PR_NUMBER", "API_REPOSITORY", "API_GITHUB_TOKEN"];+ for (const name of required) {+ if (!process.env[name]) throw new Error(`Missing ${name}`);+ }+ const baseSha = process.env.API_BASE_SHA;+ const headSha = process.env.API_HEAD_SHA;+ if (!/^[0-9a-f]{40}$/i.test(baseSha) || !/^[0-9a-f]{40}$/i.test(headSha)) {+ throw new Error("Invalid base/head SHA");+ }+ const repository = process.env.API_REPOSITORY;+ const pullNumber = process.env.API_PR_NUMBER;+ const token = process.env.API_GITHUB_TOKEN;+ const pull = await githubJson(`https://api.github.com/repos/${repository}/pulls/${pullNumber}`, token);+ if (pull.base.sha !== baseSha || pull.head.sha !== headSha || pull.user.login !== process.env.API_PR_AUTHOR) {+ throw new Error("Pull request identity changed while evaluating API approval");+ }+ const changedPaths = collectChangedPaths(+ await fetchAllPages(repository, pullNumber, "files", token),+ pull.changed_files,+ );+ const labels = JSON.parse(process.env.API_LABELS_JSON ?? "[]").map((label) =>+ typeof label === "string" ? label : label.name+ );+ const scriptRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");+ const ownerConfig = JSON.parse(await readFile(resolve(scriptRoot, ".github/api-surface-owners.json"), "utf8"));+ const reviews = await fetchAllReviews(repository, pullNumber, token);+ const result = evaluateApiSurfaceGuard({+ changedPaths,+ labels,+ reviews,+ owners: ownerConfig.owners,+ prAuthor: process.env.API_PR_AUTHOR,+ headSha,+ baseContractVersion: await contractVersionAt(repository, baseSha, token),+ headContractVersion: await contractVersionAt(repository, headSha, token),+ });+ process.stdout.write(`${JSON.stringify(result)}\n`);+ if (!result.ok) process.exitCode = 1;+}++if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();diff --git a/scripts/ci/api-surface-guard.test.ts b/scripts/ci/api-surface-guard.test.tsnew file mode 100644index 000000000..25f154777--- /dev/null+++ b/scripts/ci/api-surface-guard.test.ts@@ -0,0 +1,454 @@+import { afterEach, describe, expect, it, vi } from "vitest";+import { readFileSync } from "node:fs";+import { resolve } from "node:path";+import {+ collectChangedPaths,+ contractVersionAt,+ evaluateApiSurfaceGuard,+ fetchAllPages,+ fetchAllReviews,+ githubJson,+ main,+ parseAdapterAuthorContractVersion,+} from "./api-surface-guard.mjs";++const headSha = "b".repeat(40);+const publicSource = "src/daemon/agent-driver/src/adapter-author.ts";+const golden = "src/daemon/agent-driver/etc/api/adapter-author.api.md";+const ownerApproval = { id: 1, login: "independent-owner", state: "APPROVED", commitId: headSha };++const requiredCliEnv = {+ API_BASE_SHA: "a".repeat(40),+ API_HEAD_SHA: headSha,+ API_PR_AUTHOR: "author",+ API_PR_NUMBER: "510",+ API_REPOSITORY: "alookai/alook",+ API_GITHUB_TOKEN: "test-token",+};++function response(body: unknown, status = 200): Response {+ return {+ ok: status >= 200 && status < 300,+ status,+ json: async () => body,+ } as Response;+}++function stubCliEnv(labels?: unknown[]) {+ for (const [name, value] of Object.entries(requiredCliEnv)) vi.stubEnv(name, value);+ if (labels === undefined) delete process.env.API_LABELS_JSON;+ else vi.stubEnv("API_LABELS_JSON", JSON.stringify(labels));+}++function contractSource(version: number) {+ return Buffer.from(`export const ADAPTER_AUTHOR_CONTRACT_VERSION = ${version} as const;\n`).toString("base64");+}++afterEach(() => {+ vi.restoreAllMocks();+ vi.unstubAllEnvs();+ process.exitCode = undefined;+});++function evaluate(overrides: Record<string, unknown> = {}) {+ return evaluateApiSurfaceGuard({+ changedPaths: [publicSource],+ labels: ["api-additive"],+ reviews: [ownerApproval],+ owners: ["author", "independent-owner"],+ prAuthor: "author",+ headSha,+ baseContractVersion: 1,+ headContractVersion: 1,+ ...overrides,+ } as never);+}++describe("api surface approval guard", () => {+ it("requires exactly one API change label for public source", () => {+ expect(evaluate({ labels: [] })).toMatchObject({ ok: false, reason: "exactly_one_api_label_required" });+ expect(evaluate({ labels: ["api-additive", "api-breaking"] }))+ .toMatchObject({ ok: false, reason: "exactly_one_api_label_required" });+ });++ it("rejects source plus golden drift without an independent current-head owner approval", () => {+ expect(evaluate({ changedPaths: [publicSource, golden], reviews: [] }))+ .toMatchObject({ ok: false, reason: "current_head_independent_owner_approval_required" });+ expect(evaluate({ reviews: [{ ...ownerApproval, login: "author" }] }))+ .toMatchObject({ ok: false, reason: "current_head_independent_owner_approval_required" });+ expect(evaluate({ reviews: [{ ...ownerApproval, commitId: "a".repeat(40) }] }))+ .toMatchObject({ ok: false, reason: "current_head_independent_owner_approval_required" });+ });++ it("accepts an allow-listed independent approval on the exact head", () => {+ expect(evaluate({+ reviews: [+ { ...ownerApproval, id: 2 },+ { ...ownerApproval, id: 1, state: "CHANGES_REQUESTED" },+ ],+ })).toMatchObject({ ok: true, reason: "approved", approver: "independent-owner" });+ });++ it("allows only version 1 when bootstrapping the adapter-author contract", () => {+ expect(evaluate({+ changedPaths: [golden],+ labels: ["api-breaking"],+ baseContractVersion: null,+ headContractVersion: 1,+ })).toMatchObject({ ok: true });+ expect(evaluate({+ changedPaths: [golden],+ labels: ["api-breaking"],+ baseContractVersion: null,+ headContractVersion: 2,+ })).toMatchObject({ ok: false, reason: "adapter_author_contract_version_bootstrap_requires_breaking_v1" });+ expect(evaluate({+ changedPaths: [golden],+ labels: ["api-additive"],+ baseContractVersion: null,+ headContractVersion: 1,+ })).toMatchObject({ ok: false, reason: "adapter_author_contract_version_bootstrap_requires_breaking_v1" });+ expect(evaluate({+ changedPaths: [golden],+ labels: [],+ baseContractVersion: null,+ headContractVersion: 1,+ })).toMatchObject({ ok: false, reason: "adapter_author_contract_version_bootstrap_requires_breaking_v1" });+ });++ it("requires an established adapter-author contract version to increase for a breaking report", () => {+ expect(evaluate({+ changedPaths: [golden],+ labels: ["api-breaking"],+ baseContractVersion: 1,+ headContractVersion: 1,+ })).toMatchObject({ ok: false, reason: "adapter_author_contract_version_must_increase" });+ expect(evaluate({+ changedPaths: [golden],+ labels: ["api-breaking"],+ baseContractVersion: 1,+ headContractVersion: 2,+ })).toMatchObject({ ok: true });+ });++ it("forbids established contract removal or regression regardless of the API label", () => {+ for (const labels of [["api-additive"], ["api-breaking"], []]) {+ expect(evaluate({+ changedPaths: [golden],+ labels,+ baseContractVersion: 2,+ headContractVersion: 1,+ })).toMatchObject({ ok: false, reason: "adapter_author_contract_version_must_not_regress" });+ expect(evaluate({+ changedPaths: [golden],+ labels,+ baseContractVersion: 1,+ headContractVersion: null,+ })).toMatchObject({ ok: false, reason: "adapter_author_contract_version_must_not_regress" });+ }+ });++ it("allows established version bumps only for a breaking adapter-author report", () => {+ expect(evaluate({+ changedPaths: [golden],+ labels: ["api-additive"],+ baseContractVersion: 1,+ headContractVersion: 2,+ })).toMatchObject({ ok: false, reason: "adapter_author_contract_version_bump_requires_breaking_report" });+ expect(evaluate({+ changedPaths: [publicSource],+ labels: ["api-breaking"],+ baseContractVersion: 1,+ headContractVersion: 2,+ })).toMatchObject({ ok: false, reason: "adapter_author_contract_version_bump_requires_breaking_report" });+ expect(evaluate({+ changedPaths: [golden],+ labels: [],+ baseContractVersion: 1,+ headContractVersion: 2,+ })).toMatchObject({ ok: false, reason: "adapter_author_contract_version_bump_requires_breaking_report" });+ });++ it("reads one canonical contract declaration as the first non-comment statement", () => {+ expect(parseAdapterAuthorContractVersion([+ "/** Adapter-author contract version. */",+ "export const ADAPTER_AUTHOR_CONTRACT_VERSION = 1 as const;",+ "export type Example = string;",+ ].join("\n"))).toBe(1);+ expect(parseAdapterAuthorContractVersion([+ "\ufeff // leading line comment",+ "export const ADAPTER_AUTHOR_CONTRACT_VERSION = 2;",+ ].join("\n"))).toBe(2);+ expect(parseAdapterAuthorContractVersion("export type Example = string;\n")).toBeNull();+ });++ it("rejects comment and string decoys instead of reading them as a bump", () => {+ expect(() => parseAdapterAuthorContractVersion([+ "// ADAPTER_AUTHOR_CONTRACT_VERSION = 2",+ "export const ADAPTER_AUTHOR_CONTRACT_VERSION = 1 as const;",+ ].join("\n"))).toThrow("Multiple adapter-author contract version references");+ expect(() => parseAdapterAuthorContractVersion([+ "const decoy = `export const ADAPTER_AUTHOR_CONTRACT_VERSION = 2`;",+ "export const ADAPTER_AUTHOR_CONTRACT_VERSION = 1 as const;",+ ].join("\n"))).toThrow("Multiple adapter-author contract version references");+ expect(() => parseAdapterAuthorContractVersion(+ "const decoy = 'ADAPTER_AUTHOR_CONTRACT_VERSION = 2';",+ )).toThrow("Invalid adapter-author contract version declaration");+ });++ it("fails closed on multiple exported contract declarations", () => {+ expect(() => parseAdapterAuthorContractVersion([+ "export const ADAPTER_AUTHOR_CONTRACT_VERSION = 1",+ "export const ADAPTER_AUTHOR_CONTRACT_VERSION = 2",+ ].join("\n"))).toThrow("Multiple adapter-author contract version references");+ expect(() => parseAdapterAuthorContractVersion(+ "/* ADAPTER_AUTHOR_CONTRACT_VERSION",+ )).toThrow("Unterminated leading comment in adapter-author contract source");+ expect(() => parseAdapterAuthorContractVersion(+ "export const ADAPTER_AUTHOR_CONTRACT_VERSION = 0;",+ )).toThrow("Invalid adapter-author contract version declaration");+ expect(() => parseAdapterAuthorContractVersion(+ "export const ADAPTER_AUTHOR_CONTRACT_VERSION = 999999999999999999999999;",+ )).toThrow("Invalid adapter-author contract version declaration");+ });++ it("includes a rename's protected previous path without inflating the returned file count", () => {+ const changedPaths = collectChangedPaths([{+ filename: "src/daemon/agent-driver/src/internal/legacy-adapter-author.ts",+ previous_filename: publicSource,+ }], 1);+ expect(changedPaths).toEqual([+ "src/daemon/agent-driver/src/internal/legacy-adapter-author.ts",+ publicSource,+ ]);+ expect(evaluate({ changedPaths, labels: [], reviews: [] }))+ .toMatchObject({ ok: false, reason: "exactly_one_api_label_required" });+ });++ it("fails closed when the pull request files response is incomplete", () => {+ expect(() => collectChangedPaths([+ { filename: "src/daemon/agent-driver/src/adapters/claude/index.ts" },+ ], 2)).toThrow("Incomplete pull request files response: expected 2, received 1");+ expect(() => collectChangedPaths(null as never, 0)).toThrow("Invalid pull request files response");+ expect(() => collectChangedPaths([], -1)).toThrow("Invalid pull request changed_files count");+ expect(() => collectChangedPaths([null] as never, 1)).toThrow("Invalid pull request file entry");+ expect(() => collectChangedPaths([{ filename: publicSource, previous_filename: "" }], 1))+ .toThrow("Invalid pull request previous filename");+ });++ it("rejects invalid version values and a missing version on adapter-author report drift", () => {+ expect(evaluate({ baseContractVersion: 0 }))+ .toMatchObject({ ok: false, reason: "invalid_adapter_author_contract_version" });+ expect(evaluate({+ changedPaths: [golden],+ labels: ["api-breaking"],+ baseContractVersion: null,+ headContractVersion: null,+ })).toMatchObject({ ok: false, reason: "adapter_author_contract_version_required" });+ });++ it("does not require an API label or review for unrelated internal changes", () => {+ expect(evaluate({+ changedPaths: ["src/daemon/agent-driver/src/adapters/claude/index.ts"],+ labels: [],+ reviews: [],+ })).toEqual({ ok: true, reason: "no_api_surface_change" });+ });++ it("protects the API report generation chain and trusted guard mechanism itself", () => {+ const mechanismPaths = [+ ".github/CODEOWNERS",+ ".github/api-surface-owners.json",+ ".github/workflows/api-surface-check.yml",+ ".github/workflows/api-surface-guard.yml",+ "package.json",+ "pnpm-lock.yaml",+ "pnpm-workspace.yaml",+ "scripts/ci/api-report-contract.test.ts",+ "scripts/ci/api-surface-guard.mjs",+ "scripts/ci/api-surface-guard.test.ts",+ "src/daemon/agent-driver/api-extractor.adapter-author.json",+ "src/daemon/agent-driver/api-extractor.host.json",+ "src/daemon/agent-driver/api-extractor.root.json",+ "src/daemon/agent-driver/api-extractor.testing.json",+ "src/daemon/agent-driver/package.json",+ "src/daemon/agent-driver/scripts/api-reports.mjs",+ "src/daemon/agent-driver/scripts/prepare-dist.mjs",+ "src/daemon/agent-driver/scripts/prune-dist.mjs",+ "src/daemon/agent-driver/tsconfig.build.json",+ "src/daemon/agent-driver/tsconfig.json",+ "vitest.config.ts",+ ];+ for (const path of mechanismPaths) {+ expect(evaluate({ changedPaths: [path], labels: [], reviews: [] }))+ .toMatchObject({ ok: false, reason: "current_head_independent_owner_approval_required" });+ expect(evaluate({ changedPaths: [path], labels: [], reviews: [ownerApproval] }))+ .toMatchObject({ ok: true, reason: "approved", changedApiPaths: [], changedMechanismPaths: [path] });+ }+ });++ it("still requires one API label when surface and mechanism paths change together", () => {+ expect(evaluate({+ changedPaths: [publicSource, "scripts/ci/api-surface-guard.mjs"],+ labels: [],+ reviews: [ownerApproval],+ })).toMatchObject({ ok: false, reason: "exactly_one_api_label_required" });+ });++ it("keeps approval enforcement base-owned and never executes pull-request head code", () => {+ const workflow = readFileSync(resolve(process.cwd(), ".github/workflows/api-surface-guard.yml"), "utf8");+ const lfWorkflow = workflow.replaceAll("\r\n", "\n");+ for (const workflowSource of [lfWorkflow, lfWorkflow.replaceAll("\n", "\r\n")]) {+ const normalizedWorkflow = workflowSource.replaceAll("\r\n", "\n");+ expect(normalizedWorkflow).toContain("pull_request_target:");+ expect(normalizedWorkflow).toMatch(/pull_request_review:\n\s+types: \[submitted, dismissed\]/);+ expect(normalizedWorkflow).toContain("if: github.event.pull_request.base.ref == 'main'");+ expect(normalizedWorkflow).toContain("ref: ${{ github.event.pull_request.base.sha }}");+ expect(normalizedWorkflow).not.toContain("pnpm install");+ expect(normalizedWorkflow).not.toContain("pull request head");+ expect(normalizedWorkflow).not.toContain("if [[ ! -f");+ }+ });++ it("handles GitHub JSON success, not-found, and error responses", async () => {+ const fetchMock = vi.fn()+ .mockResolvedValueOnce(response({ ok: true }))+ .mockResolvedValueOnce(response({}, 404))+ .mockResolvedValueOnce(response({}, 500));+ vi.stubGlobal("fetch", fetchMock);++ await expect(githubJson("https://example.test/success", "token"))+ .resolves.toEqual({ ok: true });+ await expect(githubJson("https://example.test/missing", "token", true)).resolves.toBeNull();+ await expect(githubJson("https://example.test/error", "token"))+ .rejects.toThrow("GitHub API failed: 500");+ expect(fetchMock).toHaveBeenCalledWith("https://example.test/success", {+ headers: {+ Accept: "application/vnd.github+json",+ Authorization: "Bearer token",+ "X-GitHub-Api-Version": "2022-11-28",+ },+ });+ });++ it("paginates GitHub resources and normalizes review identities", async () => {+ const firstPage = Array.from({ length: 100 }, (_, id) => ({ id }));+ const fetchMock = vi.fn()+ .mockResolvedValueOnce(response(firstPage))+ .mockResolvedValueOnce(response([{ id: 100 }]))+ .mockResolvedValueOnce(response([+ { id: 1, user: { login: "owner" }, state: "APPROVED", commit_id: headSha },+ { id: 2, user: null, state: "COMMENTED", commit_id: headSha },+ ]));+ vi.stubGlobal("fetch", fetchMock);++ await expect(fetchAllPages("alookai/alook", "510", "files", "token"))+ .resolves.toHaveLength(101);+ await expect(fetchAllReviews("alookai/alook", "510", "token")).resolves.toEqual([{+ id: 1,+ login: "owner",+ state: "APPROVED",+ commitId: headSha,+ }]);+ expect(fetchMock.mock.calls.map(([url]) => url)).toEqual([+ "https://api.github.com/repos/alookai/alook/pulls/510/files?per_page=100&page=1",+ "https://api.github.com/repos/alookai/alook/pulls/510/files?per_page=100&page=2",+ "https://api.github.com/repos/alookai/alook/pulls/510/reviews?per_page=100&page=1",+ ]);+ });++ it("reads contract versions from GitHub contents and treats absent files as unversioned", async () => {+ vi.stubGlobal("fetch", vi.fn()+ .mockResolvedValueOnce(response({}, 404))+ .mockResolvedValueOnce(response({ content: "not-used", encoding: "utf8" }))+ .mockResolvedValueOnce(response({ content: contractSource(3), encoding: "base64" })));++ await expect(contractVersionAt("alookai/alook", requiredCliEnv.API_BASE_SHA, "token"))+ .resolves.toBeNull();+ await expect(contractVersionAt("alookai/alook", requiredCliEnv.API_BASE_SHA, "token"))+ .resolves.toBeNull();+ await expect(contractVersionAt("alookai/alook", requiredCliEnv.API_HEAD_SHA, "token"))+ .resolves.toBe(3);+ });++ it("runs the real CLI orchestration against validated pull identity", async () => {+ stubCliEnv([{ name: "api-additive" }]);+ const fetchMock = vi.fn(async (input: string | URL | Request) => {+ const url = String(input);+ if (url.endsWith("/pulls/510")) {+ return response({+ base: { sha: requiredCliEnv.API_BASE_SHA },+ head: { sha: requiredCliEnv.API_HEAD_SHA },+ user: { login: requiredCliEnv.API_PR_AUTHOR },+ changed_files: 1,+ });+ }+ if (url.includes("/files?")) return response([{ filename: publicSource }]);+ if (url.includes("/reviews?")) {+ return response([{+ id: 1,+ user: { login: "GenerQAQ" },+ state: "APPROVED",+ commit_id: requiredCliEnv.API_HEAD_SHA,+ }]);+ }+ if (url.includes(`/contents/${publicSource}?ref=${requiredCliEnv.API_BASE_SHA}`)) {+ return response({ content: contractSource(1), encoding: "base64" });+ }+ if (url.includes(`/contents/${publicSource}?ref=${requiredCliEnv.API_HEAD_SHA}`)) {+ return response({ content: contractSource(1), encoding: "base64" });+ }+ throw new Error(`Unexpected URL: ${url}`);+ });+ vi.stubGlobal("fetch", fetchMock);+ const write = vi.spyOn(process.stdout, "write").mockImplementation(() => true);++ await main();++ expect(write).toHaveBeenCalledWith(expect.stringContaining('"reason":"approved"'));+ expect(process.exitCode).toBeUndefined();+ });++ it("fails the CLI closed for invalid invocation, identity drift, and rejected policy", async () => {+ stubCliEnv();+ delete process.env.API_GITHUB_TOKEN;+ await expect(main()).rejects.toThrow("Missing API_GITHUB_TOKEN");++ vi.stubEnv("API_GITHUB_TOKEN", requiredCliEnv.API_GITHUB_TOKEN);+ vi.stubEnv("API_BASE_SHA", "not-a-sha");+ await expect(main()).rejects.toThrow("Invalid base/head SHA");++ vi.stubEnv("API_BASE_SHA", requiredCliEnv.API_BASE_SHA);+ vi.stubGlobal("fetch", vi.fn().mockResolvedValue(response({+ base: { sha: requiredCliEnv.API_BASE_SHA },+ head: { sha: requiredCliEnv.API_HEAD_SHA },+ user: { login: "different-author" },+ changed_files: 0,+ })));+ await expect(main()).rejects.toThrow("Pull request identity changed while evaluating API approval");++ vi.stubGlobal("fetch", vi.fn(async (input: string | URL | Request) => {+ const url = String(input);+ if (url.endsWith("/pulls/510")) {+ return response({+ base: { sha: requiredCliEnv.API_BASE_SHA },+ head: { sha: requiredCliEnv.API_HEAD_SHA },+ user: { login: requiredCliEnv.API_PR_AUTHOR },+ changed_files: 1,+ });+ }+ if (url.includes("/files?")) return response([{ filename: "scripts/ci/api-surface-guard.mjs" }]);+ if (url.includes("/reviews?")) return response([]);+ if (url.includes("/contents/")) return response({}, 404);+ throw new Error(`Unexpected URL: ${url}`);+ }));+ const write = vi.spyOn(process.stdout, "write").mockImplementation(() => true);++ await main();++ expect(write).toHaveBeenCalledWith(expect.stringContaining(+ '"reason":"current_head_independent_owner_approval_required"',+ ));+ expect(process.exitCode).toBe(1);+ });+});diff --git a/vitest.config.ts b/vitest.config.tsindex 07013da12..f1f38f1da 100644--- a/vitest.config.ts+++ b/vitest.config.ts@@ -5,7 +5,7 @@ export default defineConfig({projects: ["src/shared", "src/web", "src/cli", "src/daemon", "src/email-worker", "src/ws-do", "src/app", "tests/utils", "scripts/ci"],coverage: {provider: "v8",- include: ["src/**/*.{ts,tsx,js,jsx}"],+ include: ["src/**/*.{ts,tsx,js,jsx}", "scripts/ci/**/*.mjs"],exclude: ["**/*.test.*","**/*.spec.*",