Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

ci: bootstrap trusted API surface guard (#510)

Gustavo Yeef08ae9ba7e2
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index 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-dev
diff --git a/.github/api-surface-owners.json b/.github/api-surface-owners.json
new file mode 100644
index 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.yml
new file mode 100644
index 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.mjs
diff --git a/scripts/ci/api-surface-guard.mjs b/scripts/ci/api-surface-guard.mjs
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.*",