Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

38.6 KB
Raw Blame
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))
}