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
import { execFileSync } from "node:child_process"
import { createHash } from "node:crypto"
import {
appendFileSync,
readFileSync,
statSync,
writeFileSync,
} from "node:fs"
import { resolve } from "node:path"
import { fileURLToPath } from "node:url"
import { createE2eMatrix, queryNativeUiFacts, resolvePlaywrightImage, validateNativeUiFacts } from "./e2e-shards.mjs"
import { isolatedRepositoryGitEnvironment } from "./report-changed-patch-coverage.mjs"
const ROOT = resolve(fileURLToPath(new URL("../..", import.meta.url)))
const MANIFEST_URL = new URL("./change-scope-manifest.json", import.meta.url)
const BLOG_ROOT = /^src\/web\/blog(?:\/|$)/
const AUTH_ROOT = /^src\/web\/auth(?:\/|$)/
const BLOG_CONTENT = /^src\/web\/blog\/src\/content\/[^/]+\.mdx$/
const BLOG_ASSET = /^src\/web\/blog\/public\/blog(?:\/|$)/
const MARKDOWN = /(?:^|\/)\w[^/]*\.md$/i
const WORKFLOW = /^\.github\/workflows\//
const GLOBAL_PATHS = new Set([
"codecov.yml",
"package.json",
"pnpm-lock.yaml",
"pnpm-workspace.yaml",
"turbo.json",
"tsconfig.json",
"vitest.config.ts",
])
const KNOWN_PREFIXES = [".claude/", ".openai/", "docs/"]
const COVERAGE_EXCLUDES = [
/(?:^|\/)\w[^/]*\.(?:test|spec)\.[cm]?[jt]sx?$/,
// Project/workspace configs execute before coverage instrumentation and are
// excluded by Vitest itself; their behavior is enforced by contract tests.
/(?:^|\/)vitest(?:\.[^/]+)?\.config\.[cm]?[jt]sx?$/,
/^src\/web\/open-next\.config\.ts$/,
/^src\/web\/public\/(?:sw\.js(?:\.map)?$|community-shell\/)/,
/(?:^|\/)node_modules\//,
/(?:^|\/)(?:\.next|\.open-next|\.wrangler|dist|bundled|__mocks__)\//,
/(?:^|\/)test-runtime\//,
/(?:^|\/)test-harness\.ts$/,
/(?:^|\/)react-dom-(?:harness|setup)\.ts$/,
/\.d\.ts$/,
/^src\/shared\/src\/index\.ts$/,
/^src\/web\/scripts\//,
/^src\/web\/readme-capture\//,
/^src\/web\/src\/.*\.tsx$/,
/^src\/web\/src\/components\/community\/bots\/bot-list-types\.ts$/,
/^src\/web\/src\/test\/fixtures\//,
/^src\/web\/src\/test\/(?:e2e|e2e-ui)\//,
/^src\/web\/src\/hooks\/(?:use-agent-chat|use-chat-sheets|use-file-attachments|use-message-flags|use-text-selection-quote)\.ts$/,
/^src\/web\/src\/components\/agent-chat\/use-rotating-placeholder\.ts$/,
]
function normalizePath(path) {
return path.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, "")
}
function sorted(values) {
return [...new Set(values.filter((value) => value !== null && value !== undefined))].sort()
}
function stableValue(value) {
if (Array.isArray(value)) return value.map(stableValue)
if (value && typeof value === "object") {
return Object.fromEntries(
Object.keys(value).sort().map((key) => [key, stableValue(value[key])]),
)
}
return value
}
export function stablePlanJson(plan) {
return JSON.stringify(stableValue(plan))
}
function hashPlan(plan) {
const { plan_hash: _ignored, ...unsigned } = plan
return createHash("sha256").update(stablePlanJson(unsigned)).digest("hex")
}
function isBlogContent(path) {
return BLOG_CONTENT.test(path) || BLOG_ASSET.test(path)
}
function isMarkdown(path) {
return MARKDOWN.test(path)
}
function pathWithin(path, root) {
return path === root || path.startsWith(`${root}/`)
}
function coverageRootPrefix(glob) {
return glob.split("/**")[0]
}
function coverageRootMatches(path, glob) {
if (!pathWithin(path, coverageRootPrefix(glob))) return false
const extensionSet = glob.match(/\.\{([^}]+)\}$/)?.[1]
if (extensionSet) {
return extensionSet.split(",").some((extension) => path.endsWith(`.${extension}`))
}
const extension = glob.match(/\.([0-9A-Za-z]+)$/)?.[1]
return extension ? path.endsWith(`.${extension}`) : false
}
function isCoverable(path, coverageRoots) {
return coverageRoots.some((root) => coverageRootMatches(path, root))
&& COVERAGE_EXCLUDES.every((pattern) => !pattern.test(path))
}
function changePaths(change) {
return change.old_path ? [change.old_path, change.path] : [change.path]
}
function normalizedChanges(changes) {
return changes
.map((change) => ({
status: String(change.status || "M"),
...(change.old_path ? { old_path: normalizePath(change.old_path) } : {}),
path: normalizePath(change.path),
}))
.filter((change) => change.path)
.sort((left, right) => (
left.path.localeCompare(right.path)
|| (left.old_path || "").localeCompare(right.old_path || "")
|| left.status.localeCompare(right.status)
))
}
export function loadScopeManifest(path = MANIFEST_URL) {
return JSON.parse(readFileSync(path, "utf8"))
}
function packageManifest(scopePackage, root = ROOT) {
return JSON.parse(readFileSync(resolve(root, scopePackage.root, "package.json"), "utf8"))
}
const CHECK_TASKS = [
"typecheck", "typecheck:blog", "typecheck:auth",
"lint", "lint:blog", "lint:auth", "knip",
"test", "test:contracts", "test:tooling", "test:blog", "test:auth", "test:runtime", "test:auth:runtime",
"build", "build:blog", "build:auth",
]
function checkTasks(items, manifest) {
const packages = new Map(manifest.packages.map((entry) => [entry.name, entry]))
return items.filter((task) => {
const owner = packages.get(task.package.name)
if (!owner || !task.command || !CHECK_TASKS.includes(task.name)) return false
if (task.name === "build") return owner.build || owner.app_artifact
if (task.name.startsWith("typecheck") || task.name.startsWith("lint")) return owner.static
if (task.name === "knip") return owner.knip
return true
}).sort((left, right) => left.fullName.localeCompare(right.fullName))
}
export function queryNativeTasks({ root = ROOT, baseSha, headSha, manifest = loadScopeManifest(), execute = execFileSync } = {}) {
const fields = "fullName name command package { name path } allDependencies { items { fullName } }"
const query = (source) => {
const result = JSON.parse(execute(process.platform === "win32" ? "pnpm.cmd" : "pnpm",
["exec", "turbo", "query", source], {
cwd: root, encoding: "utf8", maxBuffer: 16 * 1024 * 1024,
env: { ...isolatedRepositoryGitEnvironment(), GIT_OPTIONAL_LOCKS: "0" },
stdio: ["ignore", "pipe", "pipe"],
}))
if (result.errors?.length || !result.data) throw new Error("native Turbo task query failed")
return result.data
}
const packagesQuery = "packages { items { tasks { items { " + fields + " } } } }"
const affectedQuery = baseSha && headSha
? "affectedTasks(base: " + JSON.stringify(baseSha) + ", head: " + JSON.stringify(headSha)
+ ", tasks: " + JSON.stringify(CHECK_TASKS)
+ ") { items { " + fields + " reason { __typename ... on TaskAllChanged { description } } } }"
: ""
const selection = query("query { " + packagesQuery + " " + affectedQuery + " }")
const inventory = checkTasks(selection.packages.items.flatMap((entry) => entry.tasks.items), manifest)
if (!inventory.length) throw new Error("native Turbo task inventory is empty")
if (!affectedQuery) return { inventory, affected: inventory, reason: "unresolved_native_base" }
const fallback = selection.affectedTasks.items.find(task => task.reason?.__typename === "TaskAllChanged" && task.reason.description === "conservative affectedness fallback")
return { inventory, affected: checkTasks(selection.affectedTasks.items, manifest),
reason: fallback ? "native_affected_fallback" : null,
...(fallback ? { detail: fallback.reason.description } : {}),
}
}
function validateCodecovTargets(manifest, root) {
const source = readFileSync(resolve(root, "codecov.yml"), "utf8").replaceAll("\r\n", "\n")
const projectSection = source.match(/^[ ]{4}project:\n([\s\S]*?)^[ ]{4}patch:/m)?.[1]
if (!projectSection) throw new Error("codecov.yml project status section is missing")
const configuredNames = [...projectSection.matchAll(/^[ ]{6}([^\s:\n][^:\n]*):$/gm)]
.map((match) => match[1])
.sort()
const manifestNames = Object.keys(manifest.codecov_targets).sort()
if (JSON.stringify(configuredNames) !== JSON.stringify(manifestNames)) {
throw new Error("scope manifest Codecov project target names do not match codecov.yml")
}
for (const [name, target] of Object.entries(manifest.codecov_targets)) {
const escapedName = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
const escapedPath = target.path.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
const contract = new RegExp(
`^[ ]{6}${escapedName}:\\n[ ]{8}informational: true\\n[ ]{8}target: auto\\n[ ]{8}paths:\\n[ ]{10}- ${escapedPath}/\\*\\*$`,
"m",
)
if (!contract.test(projectSection)) {
throw new Error(`scope manifest Codecov target does not match codecov.yml: ${name}`)
}
}
}
export function validateScopeManifest(manifest, options = {}) {
const root = options.root || ROOT
if (manifest.schema_version !== 2 || manifest.policy_version !== 3) {
throw new Error("scope manifest schema/policy version must be 1/2")
}
if (!Array.isArray(manifest.packages) || manifest.packages.length === 0) {
throw new Error("scope manifest packages are required")
}
const names = manifest.packages.map((entry) => entry.name)
const roots = manifest.packages.map((entry) => normalizePath(entry.root))
if (new Set(names).size !== names.length) throw new Error("package names must be unique")
if (new Set(roots).size !== roots.length) throw new Error("package root must be unique")
const workspaceRoots = [...readFileSync(resolve(root, "pnpm-workspace.yaml"), "utf8")
.matchAll(/^[ ]{2}- ["']([^"']+)["']$/gm)]
.map((match) => normalizePath(match[1]))
.sort()
if (JSON.stringify([...roots].sort()) !== JSON.stringify(workspaceRoots)) {
throw new Error("scope manifest package roots must exactly match pnpm-workspace.yaml")
}
for (const [kind, registry] of Object.entries(manifest.suites)) {
if (new Set(registry).size !== registry.length) throw new Error(`${kind} suite IDs must be unique`)
for (const entry of manifest.packages) {
for (const suite of entry[`${kind}_suites`]) {
if (!registry.includes(suite)) throw new Error(`unknown ${kind} suite: ${suite}`)
}
}
const declared = sorted(manifest.packages.flatMap((entry) => entry[`${kind}_suites`]))
if (JSON.stringify([...registry].sort()) !== JSON.stringify(declared)) {
throw new Error(`${kind} suite registry must exactly match package declarations`)
}
}
const pathSuiteRoots = manifest.path_suites.map((entry) => normalizePath(entry.root))
if (new Set(pathSuiteRoots).size !== pathSuiteRoots.length) {
throw new Error("path suite roots must be unique")
}
for (const entry of manifest.path_suites) {
for (const suite of entry.integration_suites) {
if (!manifest.suites.integration.includes(suite)) {
throw new Error(`unknown path integration suite: ${suite}`)
}
}
}
for (const entry of manifest.packages) {
const workspacePackage = packageManifest(entry, root)
if (workspacePackage.name !== entry.name) {
throw new Error(`package manifest mismatch for ${entry.root}`)
}
if (entry.codecov_target && !manifest.codecov_targets[entry.codecov_target]) {
throw new Error(`unknown Codecov target: ${entry.codecov_target}`)
}
for (const script of entry.unit_root ? ["test"] : []) {
if (!workspacePackage.scripts?.[script]) {
throw new Error(`${entry.name} declares ${script} scope without a package script`)
}
}
}
const knownSpec = (spec) => typeof spec === "string" && !spec.includes("..") && !spec.includes("\\")
&& spec.endsWith(".spec.ts") && (options.specs
? options.specs.includes(spec)
: statSync(resolve(root, manifest.ui.root, spec), { throwIfNoEntry: false })?.isFile())
for (const contractSpecs of Object.values(manifest.ui.contracts)) {
for (const spec of contractSpecs) {
if (!knownSpec(spec)) throw new Error(`unknown UI spec: ${spec}`)
}
}
const groups = manifest.ui.groups
if (!Array.isArray(manifest.ui.full_prefixes) || manifest.ui.full_prefixes.length === 0
|| manifest.ui.full_prefixes.some((prefix) => typeof prefix !== "string"
|| !prefix.startsWith("src/") || prefix.includes("..") || prefix.includes("\\"))) {
throw new Error("UI full-scope prefixes must be repository source paths")
}
if (!Array.isArray(groups) || new Set(groups.map((group) => group.name)).size !== groups.length) {
throw new Error("UI feature group names must be unique")
}
for (const group of groups) {
if (!group.name || !Array.isArray(group.prefixes) || group.prefixes.length === 0
|| !Array.isArray(group.specs) || group.specs.length === 0) {
throw new Error("UI feature groups require a name, prefixes and specs")
}
for (const prefix of group.prefixes) {
if (typeof prefix !== "string" || !/^src\/(?:web|ws-do)\//.test(prefix)
|| prefix.includes("..") || prefix.includes("\\")) {
throw new Error(`invalid UI feature prefix: ${prefix}`)
}
}
for (const spec of group.specs) {
if (!knownSpec(spec)) throw new Error(`unknown UI spec: ${spec}`)
}
}
if (!Array.isArray(manifest.smoke_tests) || manifest.smoke_tests.length === 0
|| new Set(manifest.smoke_tests).size !== manifest.smoke_tests.length
|| manifest.smoke_tests.some((path) => typeof path !== "string" || path.includes("..")
|| !/^(?:scripts\/ci|src\/(?:shared|web))\/.+\.test\.[cm]?[jt]sx?$/.test(path))) {
throw new Error("main smoke tests must be unique repository test paths")
}
for (const path of manifest.smoke_tests) {
if (!statSync(resolve(root, path), { throwIfNoEntry: false })?.isFile()) {
throw new Error(`missing main smoke test: ${path}`)
}
}
validateCodecovTargets(manifest, root)
sorted(manifest.integrity_paths)
return manifest
}
function findPackage(path, manifest) {
return [...manifest.packages]
.sort((left, right) => right.root.length - left.root.length)
.find((entry) => pathWithin(path, entry.root))
}
function isKnownPath(path, manifest) {
return isMarkdown(path)
|| GLOBAL_PATHS.has(path)
|| manifest.packages.some((entry) => pathWithin(path, entry.root))
|| manifest.path_suites.some((entry) => pathWithin(path, normalizePath(entry.root)))
|| KNOWN_PREFIXES.some((prefix) => path.startsWith(prefix))
}
function fullReason(paths, { forceFull, benchmarkOnly, fallbackReason }) {
if (fallbackReason) return "classifier_error"
if (forceFull) return "forced"
if (benchmarkOnly) return null
if (paths.length === 0) return "empty_diff"
const docsOnly = paths.every(isMarkdown)
const blogOnly = paths.every(isBlogContent)
if (!docsOnly && !blogOnly && paths.every((path) => isMarkdown(path) || isBlogContent(path))) {
return "mixed_content"
}
if (paths.some((path) => WORKFLOW.test(path) || GLOBAL_PATHS.has(path) || path.startsWith("scripts/") || (path.startsWith(".github/") && !isMarkdown(path)))) {
return "policy_change"
}
if (paths.some((path) => [".claude/", ".openai/", "docs/"]
.some((prefix) => path.startsWith(prefix)) && !isMarkdown(path))) return "policy_change"
return null
}
function emptyJobs() {
return {
app_packed_artifact: false,
auth_build: false,
worker_build: false,
blog_build: false,
e2e: false,
lighthouse: false,
merge_reports: false,
resizable_panels_compat: false,
rust: false,
static_checks: false,
test_linux: false,
test_windows: false,
ui_e2e: false,
}
}
function packageSets(packages) {
return {
static: sorted(packages.filter((entry) => entry.static).map((entry) => entry.name)),
build: sorted(packages.filter((entry) => entry.build).map((entry) => entry.name)),
knip: sorted(packages.filter((entry) => entry.knip).map((entry) => entry.name)),
unit: sorted(packages.map((entry) => entry.unit_root).filter(Boolean)),
windows: sorted(packages.flatMap((entry) => entry.windows_suites)),
integration: sorted(packages.flatMap((entry) => entry.integration_suites)),
linux: sorted(packages.flatMap((entry) => entry.linux_suites)),
}
}
function coverageSets(packages) {
return {
targets: sorted(packages.map((entry) => entry.codecov_target).filter(Boolean)),
include_roots: sorted(packages.flatMap((entry) => entry.coverage_roots)),
}
}
function requiredCoverageFiles(changes, coverageRoots) {
return sorted(changes.flatMap((change) => {
const status = change.status[0]
if (!["A", "M", "R", "C"].includes(status)) return []
return isCoverable(change.path, coverageRoots) ? [change.path] : []
}))
}
function affectedUiSpecs(paths, manifest) {
const selected = new Set(manifest.ui.contracts.smoke)
const relevant = paths.filter((path) => {
const owner = findPackage(path, manifest)?.name
return ["@alook/web", "@alook/ws-do", "@alook/shared", "@alook/test-utils"].includes(owner)
&& !isMarkdown(path)
&& (!/\.(?:test|spec)\.[cm]?[jt]sx?$/.test(path) || pathWithin(path, manifest.ui.root))
})
if (relevant.length === 0) return []
for (const path of relevant) {
if (pathWithin(path, manifest.ui.root)) {
const spec = path.slice(manifest.ui.root.length + 1)
if (!spec.endsWith(".spec.ts") || !statSync(resolve(ROOT, path), { throwIfNoEntry: false })?.isFile()) return [manifest.ui.all]
selected.add(spec)
continue
}
if (manifest.ui.full_prefixes.some((prefix) => path.startsWith(prefix))) return [manifest.ui.all]
const groups = manifest.ui.groups.filter((group) => group.prefixes.some((prefix) => path.startsWith(prefix)))
if (groups.length === 0) return [manifest.ui.all]
for (const group of groups) for (const spec of group.specs) selected.add(spec)
}
return sorted([...selected])
}
function planClass({ full, benchmarkOnly, docsOnly, blogPathsOnly, authPathsOnly, direct }) {
if (full) return "full"
if (benchmarkOnly) return "benchmark"
if (docsOnly) return "docs"
if (blogPathsOnly) return "blog"
if (authPathsOnly) return "auth"
if (direct.length === 1 && direct[0] === "@alook/shared") return "shared"
if (direct.length === 1) return "package"
return "mixed"
}
function browserZonesForSpecs(specs, manifest) {
const names = specs.map(spec => spec.replace(/^src\/test\/e2e-ui\//, ""))
return names.length ? ["web", ...(names.includes(manifest.ui.all) || names.some(spec => manifest.ui.contracts.blog.includes(spec)) ? ["blog"] : [])] : []
}
export function buildExecutionPlan(inputChanges, options = {}) {
const manifest = validateScopeManifest(options.manifest || loadScopeManifest())
const changes = normalizedChanges(inputChanges)
const allPaths = sorted(changes.flatMap(changePaths))
const paths = allPaths.filter((path) => !pathWithin(path, "src/benchmark"))
const benchmarkOnly = allPaths.length > 0 && paths.length === 0
const docsOnly = paths.length > 0 && paths.every(isMarkdown)
const blogContentOnly = paths.length > 0 && paths.every(isBlogContent)
const blogPathsOnly = paths.length > 0 && paths.every((path) => BLOG_ROOT.test(path))
const authPathsOnly = paths.length > 0 && paths.every((path) => AUTH_ROOT.test(path))
const unknown = paths.some((path) => !isKnownPath(path, manifest))
const nativeTasks = options.nativeTasks
const nativeUnavailable = !nativeTasks && !docsOnly && !benchmarkOnly
const reason = fullReason(paths, { ...options, benchmarkOnly }) || (unknown ? "unknown_path" : null)
|| (nativeUnavailable ? "native_tasks_unavailable" : nativeTasks?.reason || null)
const full = reason !== null
const executionMode = full ? "full" : options.mainSmoke === true ? "main-smoke" : "affected"
const mainSmoke = executionMode === "main-smoke" && !docsOnly && !benchmarkOnly
const direct = sorted(paths.map((path) => findPackage(path, manifest)?.name).filter(Boolean))
let affectedNames
if (full) affectedNames = sorted(manifest.packages.map((entry) => entry.name))
else if (docsOnly || benchmarkOnly) affectedNames = []
else affectedNames = sorted(nativeTasks.affected.map((task) => task.package.name))
const byName = new Map(manifest.packages.map((entry) => [entry.name, entry]))
const affectedPackages = affectedNames.map((name) => byName.get(name))
const selectedTasks = full ? nativeTasks?.inventory || [] : docsOnly || benchmarkOnly ? [] : nativeTasks.affected
const suites = packageSets(affectedPackages)
const tasks = (prefix) => selectedTasks.filter((task) => task.name === prefix || task.name.startsWith(prefix + ":"))
const buildTasks = tasks("build").filter((task) => task.reason?.__typename !== "TaskAllChanged"
|| task.reason.description !== "required by an affected task")
suites.static_tasks = tasks("typecheck").concat(tasks("lint")).map((task) => task.fullName)
suites.build_tasks = buildTasks.map((task) => task.fullName)
suites.knip_tasks = tasks("knip").map((task) => task.fullName)
suites.unit_tasks = tasks("test").map((task) => task.fullName)
const unitDependencies = new Set(tasks("test").flatMap((task) => task.allDependencies?.items.map((dependency) => dependency.fullName) || []))
suites.unit_build_tasks = (nativeTasks?.inventory || []).filter((task) => unitDependencies.has(task.fullName)
&& (task.name === "build" || task.name.startsWith("build:"))).map((task) => task.fullName)
if (nativeTasks) {
suites.static = sorted(tasks("typecheck").concat(tasks("lint")).map((task) => task.package.name))
suites.build = sorted(buildTasks.map((task) => task.package.name))
suites.knip = sorted(tasks("knip").map((task) => task.package.name))
suites.unit = sorted(tasks("test").map((task) => task.package.path))
}
suites.smoke = []
const testOwners = nativeTasks
? new Set(tasks("test").map((task) => task.package.name))
: new Set(affectedNames)
const testedPackages = affectedPackages.filter((entry) => testOwners.has(entry.name))
const testSuites = packageSets(testedPackages)
for (const kind of ["windows", "integration", "linux"]) suites[kind] = testSuites[kind]
const coverage = coverageSets(testedPackages)
suites.integration = sorted([
...suites.integration,
...manifest.path_suites
.filter((entry) => paths.some((path) => pathWithin(path, normalizePath(entry.root))))
.flatMap((entry) => entry.integration_suites),
])
if (full) {
suites.unit = sorted([...suites.unit, "scripts/ci"])
coverage.include_roots = sorted([...coverage.include_roots, "scripts/ci/**/*.mjs"])
}
const jobs = emptyJobs()
let uiSpecs = []
if (full) {
uiSpecs = [manifest.ui.all]
} else if (blogContentOnly || blogPathsOnly) {
uiSpecs = [...manifest.ui.contracts.blog]
suites.integration = blogPathsOnly && !blogContentOnly ? [] : suites.integration
} else if (authPathsOnly) {
suites.integration = []
} else if ([...affectedPackages, ...direct.map((name) => byName.get(name))].some((entry) => entry.ui)) {
uiSpecs = affectedUiSpecs(paths, manifest)
}
if (blogPathsOnly && !blogContentOnly) {
suites.integration = []
suites.windows = []
suites.linux = []
}
const authBuild = full || suites.build_tasks.includes("@alook/web#build:auth")
const blogBuild = full || suites.build_tasks.includes("@alook/web#build:blog")
if (!full && blogBuild && uiSpecs.length > 0 && !uiSpecs.includes(manifest.ui.all)
&& paths.some((path) => !/\.(?:test|spec)\.[cm]?[jt]sx?$/.test(path))) {
uiSpecs = sorted([...uiSpecs, ...manifest.ui.contracts.blog])
}
const directWebRuntime = paths.some((path) => (
pathWithin(path, "src/web") && !BLOG_ROOT.test(path) && !AUTH_ROOT.test(path)
))
const lighthouse = full || (blogPathsOnly && !blogContentOnly) || directWebRuntime
const rust = full || [...affectedPackages, ...direct.map((name) => byName.get(name))].some((entry) => entry.rust)
const directPackages = direct.map((name) => byName.get(name))
const appArtifact = full || (!blogPathsOnly && !authPathsOnly && [...affectedPackages, ...directPackages]
.some((entry) => entry.app_artifact))
const requiredChangedFiles = requiredCoverageFiles(changes, coverage.include_roots)
if (mainSmoke) {
suites.static = []
suites.build = []
suites.knip = []
suites.unit = []
suites.windows = []
suites.integration = []
suites.linux = []
for (const key of ["static_tasks", "build_tasks", "knip_tasks", "unit_tasks", "unit_build_tasks"]) suites[key] = []
suites.smoke = [...manifest.smoke_tests]
coverage.targets = []
coverage.include_roots = []
requiredChangedFiles.length = 0
uiSpecs = uiSpecs.length > 0
? blogPathsOnly ? [...manifest.ui.contracts.blog] : [...manifest.ui.contracts.smoke]
: []
}
jobs.auth_build = authBuild
jobs.blog_build = blogBuild
jobs.static_checks = suites.static.length > 0
jobs.test_linux = suites.unit.length > 0 || suites.linux.length > 0 || suites.smoke.length > 0
jobs.test_windows = suites.windows.length > 0
jobs.app_packed_artifact = appArtifact
jobs.e2e = suites.integration.length > 0
jobs.rust = rust
jobs.lighthouse = lighthouse && !mainSmoke
jobs.ui_e2e = uiSpecs.length > 0
jobs.merge_reports = jobs.ui_e2e
const browserZones = browserZonesForSpecs(uiSpecs, manifest)
const workerZones = ["web", "blog"].filter(zone => browserZones.includes(zone)
|| (zone === "web" ? suites.build_tasks.includes("@alook/web#build") : blogBuild))
jobs.worker_build = workerZones.length > 0
jobs.resizable_panels_compat = options.resizablePanelsChanged === true && !mainSmoke
const basePlan = {
schema_version: manifest.schema_version,
policy_version: manifest.policy_version,
base_sha: options.baseSha || "",
head_sha: options.headSha || "",
diagnostic_only: options.diagnosticOnly === true,
execution_mode: executionMode,
changes,
paths: allPaths,
change_class: planClass({ full, benchmarkOnly, docsOnly, blogPathsOnly, authPathsOnly, direct }),
full,
full_reason: reason,
fallback_detail: options.fallbackReason || nativeTasks?.detail || nativeTasks?.reason || "",
docs_only: docsOnly && !full,
auth_only: authPathsOnly && !full,
blog_only: blogContentOnly && !full,
compatibility: {
resizable_panels: options.resizablePanelsChanged === true && !mainSmoke,
},
workflow_changed: paths.some((path) => WORKFLOW.test(path)),
native_tasks: nativeTasks || null,
packages: {
direct,
affected: affectedNames,
},
suites,
ui: { specs: sorted(uiSpecs), zones: browserZones, native: options.nativeUi || null },
artifacts: { worker_zones: workerZones },
coverage: {
...coverage,
required_changed_files: requiredChangedFiles,
},
jobs,
}
return { ...basePlan, plan_hash: hashPlan(basePlan) }
}
export function classifyPaths(inputPaths, options = {}) {
return buildExecutionPlan(
inputPaths.map((path) => ({ status: "M", path })),
options,
)
}
export function validateExecutionPlan(plan, options = {}) {
const manifest = validateScopeManifest(options.manifest || loadScopeManifest())
if (plan.schema_version !== manifest.schema_version || plan.policy_version !== manifest.policy_version) {
throw new Error("execution plan schema/policy version mismatch")
}
if (hashPlan(plan) !== plan.plan_hash) throw new Error("execution plan hash mismatch")
if (!["affected", "main-smoke", "full"].includes(plan.execution_mode)
|| (plan.execution_mode === "full") !== plan.full) {
throw new Error("execution plan mode does not match its full-scope decision")
}
if (!Array.isArray(plan.suites.smoke)
|| plan.suites.smoke.some((path) => !manifest.smoke_tests.includes(path))
|| (plan.execution_mode !== "main-smoke" && plan.suites.smoke.length > 0)) {
throw new Error("execution plan smoke tests do not match its mode")
}
if (plan.execution_mode === "main-smoke" && !plan.docs_only && plan.change_class !== "benchmark") {
if (JSON.stringify(plan.suites.smoke) !== JSON.stringify(manifest.smoke_tests)
|| ["static", "build", "knip", "unit", "windows", "integration", "linux"].some((kind) => plan.suites[kind].length > 0)
|| plan.coverage.targets.length > 0 || plan.coverage.include_roots.length > 0) {
throw new Error("main smoke plan must keep the complete smoke set without full package suites")
}
const sourcePlan = buildExecutionPlan(plan.changes, { nativeTasks: plan.native_tasks })
const expectedUi = sourcePlan.ui.specs.length > 0
? sorted(sourcePlan.change_class === "blog" ? manifest.ui.contracts.blog : manifest.ui.contracts.smoke) : []
if (JSON.stringify(plan.ui.specs) !== JSON.stringify(expectedUi)
|| sourcePlan.full || stablePlanJson(plan.packages) !== stablePlanJson(sourcePlan.packages)
|| !plan.jobs.test_linux || plan.jobs.static_checks || plan.jobs.test_windows
|| plan.jobs.e2e || plan.jobs.lighthouse || plan.jobs.resizable_panels_compat
|| plan.jobs.ui_e2e !== (expectedUi.length > 0) || plan.jobs.merge_reports !== (expectedUi.length > 0)) {
throw new Error("main smoke jobs must execute the complete selected behavior checks")
}
}
if (typeof plan.compatibility?.resizable_panels !== "boolean") {
throw new Error("execution plan resizable-panels compatibility flag is required")
}
if (plan.jobs.resizable_panels_compat !== plan.compatibility.resizable_panels) {
throw new Error("execution plan resizable-panels job does not match its compatibility flag")
}
const packageNames = new Set(manifest.packages.map((entry) => entry.name))
for (const name of [...plan.packages.direct, ...plan.packages.affected, ...plan.suites.static, ...plan.suites.build, ...plan.suites.knip]) {
if (!packageNames.has(name)) throw new Error(`unknown execution-plan package: ${name}`)
}
for (const suite of plan.suites.windows) {
if (!manifest.suites.windows.includes(suite)) throw new Error(`unknown execution-plan windows suite: ${suite}`)
}
for (const suite of plan.suites.integration) {
if (!manifest.suites.integration.includes(suite)) throw new Error(`unknown execution-plan integration suite: ${suite}`)
}
for (const suite of plan.suites.linux) {
if (!manifest.suites.linux.includes(suite)) throw new Error(`unknown execution-plan linux suite: ${suite}`)
}
for (const spec of plan.ui.specs) {
if (spec !== manifest.ui.all && (!spec.endsWith(".spec.ts") || spec.includes("..") || !statSync(resolve(ROOT, manifest.ui.root, spec), { throwIfNoEntry: false })?.isFile())) throw new Error(`unknown execution-plan UI spec: ${spec}`)
}
if (plan.ui.native) validateNativeUiFacts(plan.ui.native, plan.ui.specs)
if (!plan.jobs.ui_e2e && plan.ui.native) throw new Error("inactive UI plan contains native partitions")
const expected = buildExecutionPlan(plan.changes, {
manifest,
nativeTasks: plan.native_tasks,
nativeUi: plan.ui.native,
baseSha: plan.base_sha,
headSha: plan.head_sha,
forceFull: plan.full_reason === "forced",
fallbackReason: plan.full_reason === "classifier_error" ? plan.fallback_detail || "classifier failure" : "",
mainSmoke: plan.execution_mode === "main-smoke",
diagnosticOnly: plan.diagnostic_only,
resizablePanelsChanged: plan.compatibility.resizable_panels,
})
if (stablePlanJson(expected) !== stablePlanJson(plan)) throw new Error("execution plan projections do not match native tasks and event policy")
return plan
}
export function projectPlan(plan) {
validateExecutionPlan(plan)
if (plan.jobs.ui_e2e && !plan.ui.native) throw new Error("UI execution requires native partitions")
const e2eMatrix = plan.ui.native ? createE2eMatrix(plan.ui.native) : { include: [] }
const manifest = loadScopeManifest()
e2eMatrix.include = e2eMatrix.include.map(entry => ({ ...entry, zones: browserZonesForSpecs(entry.specs, manifest) }))
return {
plan_hash: plan.plan_hash,
plan_schema_version: String(plan.schema_version),
full: String(plan.full),
execution_mode: plan.execution_mode,
base_sha: plan.base_sha,
head_sha: plan.head_sha,
auth_only: String(plan.auth_only),
blog_only: String(plan.blog_only),
run_auth_build: String(plan.jobs.auth_build),
run_blog_build: String(plan.jobs.blog_build),
run_worker_build: String(plan.jobs.worker_build),
worker_zones: JSON.stringify(plan.artifacts.worker_zones),
browser_zones: JSON.stringify(plan.ui.zones),
worker_build_image: resolvePlaywrightImage(),
run_code_checks: String(plan.jobs.static_checks || plan.jobs.test_linux),
run_static_checks: String(plan.jobs.static_checks),
run_linux: String(plan.jobs.test_linux),
run_windows: String(plan.jobs.test_windows),
run_e2e: String(plan.jobs.e2e),
run_ui_e2e: String(plan.jobs.ui_e2e),
run_resizable_panels_compat: String(plan.jobs.resizable_panels_compat),
run_rust: String(plan.jobs.rust),
run_lighthouse: String(plan.jobs.lighthouse),
run_knip: String(plan.suites.knip.length > 0),
run_app_packed_artifact: String(plan.jobs.app_packed_artifact),
static_tasks: JSON.stringify(plan.suites.static_tasks),
build_tasks: JSON.stringify(plan.suites.build_tasks),
knip_tasks: JSON.stringify(plan.suites.knip_tasks),
unit_tasks: JSON.stringify(plan.suites.unit_tasks),
unit_build_tasks: JSON.stringify(plan.suites.unit_build_tasks),
static_packages: JSON.stringify(plan.suites.static),
build_packages: JSON.stringify(plan.suites.build),
knip_packages: JSON.stringify(plan.suites.knip),
unit_test_roots: JSON.stringify(plan.suites.unit),
smoke_test_files: JSON.stringify(plan.suites.smoke),
windows_suites: JSON.stringify(plan.suites.windows),
integration_suites: JSON.stringify(plan.suites.integration),
linux_suites: JSON.stringify(plan.suites.linux),
coverage_targets: JSON.stringify(plan.coverage.targets),
coverage_include_roots: JSON.stringify(plan.coverage.include_roots),
coverage_required_changed_files: JSON.stringify(plan.coverage.required_changed_files),
ui_specs: JSON.stringify(plan.ui.specs),
e2e_matrix: JSON.stringify(e2eMatrix),
}
}
export function parseNameStatus(buffer) {
const fields = buffer.toString("utf8").split("\0")
const changes = []
for (let index = 0; index < fields.length;) {
const status = fields[index++]
if (!status) continue
const firstPath = fields[index++]
if (!firstPath) throw new Error(`missing path for git status ${status}`)
if (status.startsWith("R") || status.startsWith("C")) {
const secondPath = fields[index++]
if (!secondPath) throw new Error(`missing destination for git status ${status}`)
changes.push({ status, old_path: firstPath, path: secondPath })
} else {
changes.push({ status, path: firstPath })
}
}
return normalizedChanges(changes)
}
function readChangedFiles(args) {
if (args.forceFull) return []
if (!args.base || !args.head) throw new Error("Both --base and --head are required")
const diff = execFileSync(
"git",
["diff", "--name-status", "-z", "--find-renames", "--find-copies", `${args.base}...${args.head}`],
{ cwd: ROOT, stdio: ["ignore", "pipe", "pipe"] },
)
return parseNameStatus(diff)
}
function dependencySpecifier(source, dependency) {
const manifest = JSON.parse(source)
return manifest.dependencies?.[dependency]
?? manifest.devDependencies?.[dependency]
?? manifest.optionalDependencies?.[dependency]
?? manifest.peerDependencies?.[dependency]
}
export function packageDependencyVersionChanged(baseSource, headSource, dependency) {
return dependencySpecifier(baseSource, dependency) !== dependencySpecifier(headSource, dependency)
}
function readPackageAtRef(ref, path) {
return execFileSync("git", ["show", `${ref}:${path}`], {
cwd: ROOT,
encoding: "utf8",
stdio: ["ignore", "pipe", "pipe"],
})
}
function resizablePanelsVersionChanged(args) {
if (!args.base || !args.head || args.base === args.head) return false
return packageDependencyVersionChanged(
readPackageAtRef(args.base, "src/web/package.json"),
readPackageAtRef(args.head, "src/web/package.json"),
"react-resizable-panels",
)
}
function parseArgs(argv) {
const args = { forceFull: false, diagnosticOnly: false }
for (let index = 0; index < argv.length; index += 1) {
const arg = argv[index]
if (arg === "--force-full") {
args.forceFull = true
continue
}
if (arg === "--main-smoke") {
args.mainSmoke = true
continue
}
if (arg === "--diagnostic-only") {
args.diagnosticOnly = true
continue
}
const key = arg.replace(/^--/, "").replace(/-([a-z])/g, (_, letter) => letter.toUpperCase())
args[key] = argv[++index]
}
return args
}
function writeOutputs(path, projection) {
appendFileSync(path, `${Object.entries(projection).map(([key, value]) => `${key}=${value}`).join("\n")}\n`)
}
function writeSummary(path, plan, fallbackReason) {
const projection = projectPlan(plan)
const flags = Object.entries(projection)
.filter(([key]) => key.startsWith("run_") || key === "full" || key === "plan_hash")
.map(([key, value]) => `| \`${key}\` | \`${value}\` |`)
.join("\n")
const changed = plan.changes.map((change) => (
`- \`${change.status}\` ${change.old_path ? `\`${change.old_path}\` → ` : ""}\`${change.path}\``
)).join("\n") || "- none"
const fallback = fallbackReason ? `\nFail-closed reason: ${fallbackReason}\n` : ""
appendFileSync(
path,
`## CI execution plan\n${fallback}\nSchema/policy: \`${plan.schema_version}/${plan.policy_version}\` \nPlan hash: \`${plan.plan_hash}\` \nClass: \`${plan.change_class}\` \nDiagnostic only: \`${plan.diagnostic_only}\`\n\n| Projection | Value |\n| --- | --- |\n${flags}\n\n<details><summary>Changed paths</summary>\n\n${changed}\n\n</details>\n`,
)
}
export function runCli(argv) {
const args = parseArgs(argv)
let plan
let fallbackReason = ""
try {
plan = buildExecutionPlan(readChangedFiles(args), {
baseSha: args.base || "",
headSha: args.head || "",
forceFull: args.forceFull,
mainSmoke: args.mainSmoke,
diagnosticOnly: args.diagnosticOnly,
resizablePanelsChanged: resizablePanelsVersionChanged(args),
nativeTasks: queryNativeTasks({ baseSha: args.base, headSha: args.head }),
})
} catch (error) {
fallbackReason = error instanceof Error ? error.message : String(error)
plan = buildExecutionPlan([], {
baseSha: args.base || "",
headSha: args.head || "",
forceFull: true,
fallbackReason,
nativeTasks: queryNativeTasks(),
diagnosticOnly: args.diagnosticOnly,
resizablePanelsChanged: true,
})
}
if (plan.jobs.ui_e2e) {
const nativeUi = queryNativeUiFacts(plan.ui.specs, { shardCount: args.uiShards })
const { plan_hash: _ignored, ...unsigned } = plan
unsigned.ui = { ...plan.ui, native: nativeUi }
plan = { ...unsigned, plan_hash: hashPlan(unsigned) }
}
validateExecutionPlan(plan)
const projection = projectPlan(plan)
if (args.output) writeOutputs(args.output, projection)
if (args.planFile) writeFileSync(resolve(args.planFile), `${stablePlanJson(plan)}\n`)
if (args.summary) writeSummary(args.summary, plan, fallbackReason)
if (!args.output) process.stdout.write(`${JSON.stringify(plan, null, 2)}\n`)
}
if (process.argv[1] === fileURLToPath(import.meta.url)) {
runCli(process.argv.slice(2))
}