Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
#!/usr/bin/env node
import { execFileSync } from 'child_process';
import { existsSync, readFileSync } from 'fs';
import { join, posix, relative } from 'path';
import { staticImportClosure, staticImportSpecifiersFromSource, toModuleKey } from '../server/lib/staticImportGraph.js';
import { escapeRegExp } from '../server/lib/textUtils.js';
import { isDirectlyInvoked } from './lib/directInvocation.js';
import { writeStepOutput } from './lib/githubOutput.js';
import { resolveDbTestFiles } from './lib/dbTestFiles.js';
import { BROWSER_SUITES } from './lib/browserSuites.js';
import { ATTESTABLE_STAGES, selectAttestation } from './lib/pregateAttestation.js';
import { formatReachSummary, measureRepoImportReach } from './lib/importReach.js';
import { declaresPromptHashes, isNumberedMigrationFile } from './migrations/shippedPromptHistory.js';
const TEST_FILE_RE = /\.(?:test|spec)\.[cm]?[jt]sx?$/i;
const MODULE_SOURCE_RE = /\.[cm]?[jt]sx?$/i;
// `git grep` pathspecs matching every extension TEST_FILE_RE recognizes. A
// hardcoded `*.test.js`/`.jsx` pair would silently stop finding a `.test.ts(x)`
// or `.spec.*` contract test added later, reopening the exact under-selection
// bug the basename lookup below exists to close — the later trackedSet +
// runnerForTest(isTestFile) filter already narrows a broad hit back down, so
// over-matching here costs nothing.
const TEST_FILE_GLOBS = ['*.test.*', '*.spec.*'];
// The server tree is linted whole (fast, ~1s) by the same Biome the client installs,
// so any server JavaScript or its lint config selects the lint job.
const CLIENT_LINT_RE = /^client\/src\/.*\.(?:js|jsx)$/i;
const SERVER_LINT_RE = /^server\/(?!node_modules\/).*\.(?:m?js)$|^server\/biome\.jsonc$/i;
const isLintSurface = (path) => CLIENT_LINT_RE.test(path) || SERVER_LINT_RE.test(path);
const EXECUTABLE_RE = /\.(?:cjs|css|html|js|jsx|json|mjs|sql|ts|tsx|ya?ml)$/i;
const MAX_CHANGED_CODE_FILES = 30;
// Explicit selectors one runner carries before its scoped plan fans out across
// the full-suite shard matrix. It used to escalate the whole repository to a
// full plan; over-selection is a capacity limit, not a risk signal, so the
// selection now stays exactly as computed and only execution is partitioned
// (#11871). 125 is that former full-plan threshold (#10312).
export const MAX_TARGETED_TEST_FILES = 125;
// Preserve the planner's public registry export for existing callers.
export { BROWSER_SUITES } from './lib/browserSuites.js';
const browserSuitesIn = (paths) => uniqueSorted(paths.filter((path) => BROWSER_SUITES.includes(path)));
// Python sidecar scripts (`scripts/generate_ltx2.py`, …). Vitest's import graph
// cannot reach into them, but their contracts are pinned by suites that read
// the .py source as text, so main() finds the suites naming each changed script
// with `git grep` and the plan runs exactly those — failing closed to the full
// suite for a script nothing names.
const PYTHON_SCRIPT_RE = /^scripts\/[^/]+\.py$/;
// Contract tests read a subject file with `readFileSync` (a cross-tree mirror
// parity test, `server/lib/navManifest.js` reading 20+ client files by path)
// instead of importing it, so no `vitest related` import edge reaches them
// either. `main()` finds the tests naming a changed file's basename with
// `git grep`, the same mechanism the python case below uses, and generalizes
// it to every changed source — not only `.py` (issue #6363).
/** `git grep -E` pattern for a test that names this one source file by basename. */
export const sourceReferencePattern = (sourcePath) => (
`(^|[^A-Za-z0-9_])${sourcePath.slice(sourcePath.lastIndexOf('/') + 1).replace(/[.]/g, '\\.')}([^A-Za-z0-9_]|$)`
);
// Parallel runners per test job on a full plan. Decided here rather than in
// ci.yml because a job-level `if` cannot read the matrix context, so the
// planner emits the matrix for scoped plans too. Sizing rationale:
// docs/GITHUB_ACTIONS.md "Full-suite sharding".
export const FULL_SUITE_SHARDS = { server: 2, client: 3, windows: 3 };
/** Matrix values for one runner: every shard on a full run, one otherwise. */
export const shardIndexes = (mode, count) => (
mode === 'full' ? Array.from({ length: count }, (_, index) => index + 1) : [1]
);
/**
* Whether a scoped Linux runner fans out across its full-suite shard count.
*
* - Over MAX_TARGETED_TEST_FILES explicit selectors: either runner, either mode.
* - Server `related` mode: always. Its import-graph fan-out is unbounded by the
* explicit count (#9999: 57 selectors became ~941 files), and scoped server
* runs took 6.1 min median / 9.4 p90 on one runner. Each shard repeats
* Vitest's related-graph pass, which is the Windows job's existing trade.
* Client related plans stay on one runner unless over the cap.
* - Exact-file plans under the cap stay on one runner: they run in seconds.
*
* Vitest throws when the shard count exceeds the files it resolved
* (`--shard <count> must be a smaller than count of test files`). Every
* explicit selector is in the resolved set — `vitest related` selects a test
* file passed as input — so the floor counts explicit files the Linux runner
* does not exclude (DB suites run in their own job, browser suites in theirs).
* Below the floor the runner stays on one shard.
*/
const fansOut = (runner, { mode, files }, excludedFiles) => {
if (mode === 'skip' || mode === 'full') return false;
const runnable = files.filter((path) => !excludedFiles.has(path));
if (runnable.length < FULL_SUITE_SHARDS[runner]) return false;
return files.length > MAX_TARGETED_TEST_FILES || (runner === 'server' && mode === 'related');
};
const DEPENDENCY_MANIFEST_RE = /^(?:package|server\/package|client\/package|autofixer\/package)(?:-lock)?\.json$/;
// Workspaces the windows-server job installs (`npm ci --prefix <dir>`). Only
// their manifests and .npmrc can change what that job runs, so a dependency or
// npm-config change elsewhere keeps the Windows baseline. ci-test-plan.test.js
// pins this list to the job's install steps in ci.yml.
export const WINDOWS_INSTALLED_WORKSPACES = ['server'];
const windowsInstalls = (path) => WINDOWS_INSTALLED_WORKSPACES.some((dir) => path.startsWith(`${dir}/`));
// Packages whose installed files differ per platform although their lockfile
// entry may carry no os/cpu/install-script metadata: runtime dispatchers that
// pick a prebuilt binary (their per-platform children ARE os/cpu-tagged, and
// usually move with them), browser-binary downloaders, and native addons.
//
// The first row is every TRUSTED_REBUILDS package (scripts/trusted-rebuilds.js).
// It is matched here rather than imported: that module's spawn helpers would
// pull ~20 server modules into a planner that runs before any install.
// ci-test-plan.test.js fails when the allowlist names a package this list misses.
export const PLATFORM_PACKAGE_RES = [
/^node-pty$/, /^sharp$/, /^onnxruntime-/, /^protobufjs$/,
/^@img\//, /^esbuild$/, /^@esbuild\//,
/^rollup$/, /^@rollup\/rollup-/, /^rolldown$/, /^@rolldown\//, /^@biomejs\//,
/^lightningcss(?:-|$)/, /^@tailwindcss\/oxide/, /^playwright(?:-core)?$/, /^@playwright\//,
/^@swc\//, /^fsevents$/, /^bufferutil$/, /^utf-8-validate$/,
];
// Lockfile entry metadata npm uses to install a package conditionally per
// platform, or to run code at install time.
const PLATFORM_ENTRY_FIELDS = ['hasInstallScript', 'os', 'cpu', 'libc', 'optional', 'devOptional'];
// package.json fields whose change installs the same files on every platform.
// Dependency maps are checked per changed name; any other field (engines,
// overrides, optionalDependencies, scripts, os, cpu, …) escalates.
const PLATFORM_NEUTRAL_MANIFEST_FIELDS = new Set([
'name', 'version', 'description', 'keywords', 'author', 'license', 'homepage', 'repository', 'bugs', 'private',
]);
const MANIFEST_DEPENDENCY_FIELDS = ['dependencies', 'devDependencies', 'peerDependencies'];
// Lockfile root entry ("") fields that mirror the dependency maps; the
// node_modules/* entries carry the real change.
const LOCKFILE_ROOT_NEUTRAL_FIELDS = new Set(['name', 'version', 'license', ...MANIFEST_DEPENDENCY_FIELDS]);
const isPlatformPackageName = (name) => PLATFORM_PACKAGE_RES.some((re) => re.test(name));
const sameJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);
const changedKeys = (base = {}, head = {}) => uniqueSorted([...Object.keys(base), ...Object.keys(head)])
.filter((key) => !sameJson(base[key], head[key]));
const packageNameFromLockKey = (key, entry) => entry?.name
?? key.slice(key.lastIndexOf('node_modules/') + 'node_modules/'.length);
const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
const escalated = (reason, packages = []) => ({ escalate: true, reason, packages: uniqueSorted(packages) });
function classifyLockfile(base, head) {
if (!isPlainObject(base.packages) || !isPlainObject(head.packages)) {
return escalated('lockfile has no packages map to compare');
}
const topLevel = changedKeys(base, head).filter((key) => !['packages', 'name', 'version'].includes(key));
if (topLevel.length > 0) return escalated(`lockfile ${topLevel.join(', ')} changed`);
const rootFields = changedKeys(base.packages[''], head.packages[''])
.filter((key) => !LOCKFILE_ROOT_NEUTRAL_FIELDS.has(key));
if (rootFields.length > 0) return escalated(`root ${rootFields.join(', ')} changed`);
const changed = changedKeys(base.packages, head.packages).filter((key) => key !== '').map((key) => {
const entries = [base.packages[key], head.packages[key]].filter(isPlainObject);
const name = packageNameFromLockKey(key, head.packages[key] ?? base.packages[key]);
const sensitive = isPlatformPackageName(name) || entries.some((entry) => PLATFORM_ENTRY_FIELDS
.some((field) => entry[field] !== undefined && entry[field] !== false));
return { name, sensitive };
});
const sensitive = changed.filter((pkg) => pkg.sensitive).map((pkg) => pkg.name);
if (sensitive.length > 0) return escalated('platform-sensitive package changed', sensitive);
return { escalate: false, reason: 'no platform-sensitive package changed', packages: uniqueSorted(changed.map((pkg) => pkg.name)) };
}
function classifyManifest(base, head) {
const fields = changedKeys(base, head).filter((key) => !PLATFORM_NEUTRAL_MANIFEST_FIELDS.has(key));
const unsafe = fields.filter((key) => !MANIFEST_DEPENDENCY_FIELDS.includes(key));
if (unsafe.length > 0) return escalated(`${unsafe.join(', ')} changed`);
const names = uniqueSorted(fields.flatMap((field) => changedKeys(
isPlainObject(base[field]) ? base[field] : {},
isPlainObject(head[field]) ? head[field] : {},
)));
const sensitive = names.filter(isPlatformPackageName);
if (sensitive.length > 0) return escalated('platform-sensitive package changed', sensitive);
return { escalate: false, reason: 'no platform-sensitive package changed', packages: names };
}
/**
* Should a change to one dependency manifest run the complete Windows suite?
*
* `baseText`/`headText` are the file's contents at the diff base and in the
* tree under test; null means unavailable (new, deleted, or unreadable). Any
* input the planner cannot read and compare fails closed to escalation, so
* only a proven platform-neutral change downgrades Windows.
*
* Returns { escalate, reason, packages } — `packages` names what drove the
* decision: the platform-sensitive packages when escalating, every changed
* package otherwise.
*/
export function classifyDependencyChange(path, baseText, headText) {
if (baseText == null) return escalated('base version unavailable');
if (headText == null) return escalated('removed or unreadable in the tree under test');
let base;
let head;
try {
base = JSON.parse(baseText);
head = JSON.parse(headText);
} catch {
return escalated('could not be parsed');
}
if (!isPlainObject(base) || !isPlainObject(head)) return escalated('could not be parsed');
return path.endsWith('-lock.json') ? classifyLockfile(base, head) : classifyManifest(base, head);
}
const MAX_NAMED_PACKAGES = 8;
const describeDependencyVerdict = (path, { escalate, reason, packages }) => {
const named = packages.length > MAX_NAMED_PACKAGES
? `${packages.slice(0, MAX_NAMED_PACKAGES).join(', ')} and ${packages.length - MAX_NAMED_PACKAGES} more`
: packages.join(', ');
return `${path} ${escalate ? 'escalates Windows' : 'keeps the Windows baseline'}: ${reason}${named ? ` (${named})` : ''}`;
};
// `windowsEscalates` decides whether a trigger widens the WINDOWS job too, not
// only the Linux ones. Three windows-server shards are 3 of a full run's 12
// jobs and 41% of its runner-minutes (58% at GitHub's 2x windows-latest
// multiplier, which this public repo does not pay but a privately-billed fork
// does), so a trigger that widens CI for a reason windows-server cannot
// observe — a client build/lint/test-setup file it never loads — spends that
// on coverage which does not exist. Those run the WINDOWS_CONTRACT_TESTS
// baseline instead, the depth a Windows-risk scoped PR already gets. `true` is
// the fail-closed default for anything unlisted, and a diff touching
// WINDOWS_RISK_RULES escalates regardless of this flag (issue #7440).
//
// `windowsEscalates: 'dependencies'` defers the decision to the diff of the
// manifest itself (classifyDependencyChange): a pure-JS version bump installs
// the same files on every platform, so the full Linux matrix covers it and
// Windows runs the baseline. A native, install-script, os/cpu-gated or optional
// package, an `engines`/`overrides`/non-dependency field change, or a manifest
// the planner could not read and compare escalates Windows.
const FULL_TRIGGER_RULES = [
// ci.yml defines the windows-server job itself. The other workflows (release,
// acceptance, cancel recovery) never run on windows-latest.
{ re: /^\.github\/workflows\/ci\.yml$/, reason: 'workflow definition changed', windowsEscalates: true },
{ re: /^\.github\/workflows\//, reason: 'workflow definition changed', windowsEscalates: false },
{ re: DEPENDENCY_MANIFEST_RE, reason: 'dependency manifest changed', windowsEscalates: 'dependencies' },
// Every workspace's .npmrc pins ignore-scripts and install behavior; npm reads
// it on the Windows install too.
{ re: /(?:^|\/)\.npmrc$/, reason: 'npm configuration changed', windowsEscalates: true },
{ re: /^(?:server|client)\/vitest\.config(?:\.db)?\.js$/, reason: 'test runner configuration changed', windowsEscalates: true },
{ re: /^scripts\/vitestCiPool(?:\.test)?\.js$/, reason: 'test runner pool configuration changed', windowsEscalates: true },
{ re: /^server\/vitest\.setup\.js$/, reason: 'server test setup changed', windowsEscalates: true },
// Client-only: windows-server never loads the client setup file.
{ re: /^client\/src\/test\/setup\.js$/, reason: 'client test setup changed', windowsEscalates: false },
// Biome config + its GritQL plugins (the former client/eslint.config.js). The
// .grit files carry real enforced rules — notably the crypto.randomUUID ban —
// so a change there is as load-bearing as a change to the config itself. It
// is still a client-lint surface, and the Windows job runs no lint.
{ re: /^client\/(?:biome\.jsonc|[^/]+\.grit)$/, reason: 'lint configuration changed', windowsEscalates: false },
// Client-only: the Windows job builds no client bundle.
{ re: /^client\/vite\.config\.js$/, reason: 'client build configuration changed', windowsEscalates: false },
{ re: /^server\/index\.js$/, reason: 'server composition root changed', windowsEscalates: true },
// Widely imported, but pure cross-platform schema logic: no spawn, path or
// filesystem semantics that pinPlatform() stubs cannot cover on Linux.
{ re: /^server\/lib\/(?:schemaVersions|validation)\.js$/, reason: 'shared server contract changed', windowsEscalates: false },
// Measured hotspot (#9999): a two-file worktreeManager change expanded through
// import consumers to 57 selectors and a ~941-file local run, yet counted as
// a "scoped" plan because MAX_TARGETED_TEST_FILES only sees explicit selectors.
// Own the cost honestly: a full plan, sharded in CI. It also owns cross-platform
// worktree lifecycle, so Windows escalates (matches WINDOWS_RISK_RULES).
{ re: /^server\/services\/worktreeManager\.js$/, reason: 'worktree manager source changed (broad import fanout)', windowsEscalates: true },
// Measured log socket hotspot (#10030): changing this source fans out through
// nearly the full server suite, so make the cost explicit in CI. The socket
// starts and supervises a real PM2 child process; keep Windows at full depth.
{ re: /^server\/sockets\/logs\.js$/, reason: 'log socket source changed (broad import fanout)', windowsEscalates: true },
// The scripts that decide what CI runs, run it, and gate the release on it.
// A bug in any of them can make a scoped plan silently test nothing, so they
// prove themselves against the complete suite rather than their own scope.
// Only the ones the windows-server job itself executes (ci-base-sha,
// run-ci-tests and the githubOutput helper it imports) escalate Windows; the
// planner, lint runner, hidden-content scan and status verifier run on Linux
// jobs only, so a Windows run would observe nothing they change.
{ re: /^scripts\/(?:lib\/githubOutput|ci-base-sha|run-ci-tests)(?:\.test)?\.js$/, reason: 'CI pipeline script changed', windowsEscalates: true },
{ re: /^scripts\/(?:ci-test-plan|run-ci-lint|scan-diff-hidden-content|verify-ci-status)(?:\.test)?\.js$/, reason: 'CI pipeline script changed', windowsEscalates: false },
];
// Files whose Windows behavior is not faithfully exercised by pinPlatform()
// stubs on Linux: real .cmd spawn, PowerShell BOM, PTY wrap, path.basename
// on backslashes. A PR that does not touch these still gets a full Windows
// run nightly, on the main -> release PR, and on release.
export const WINDOWS_RISK_RULES = [
/\.(?:ps1|cmd|bat)$/i,
/^scripts\/fix-windows-console(?:\.test)?\.js$/,
/^scripts\/ps1-bom\.test\.js$/,
// Shell32 recycling and its opt-in real-bin smoke require an actual Windows runner.
/^server\/lib\/nativeTrash(?:\.(?:smoke\.)?test)?\.js$/,
/^server\/lib\/(?:bufferedSpawn|detachedSpawn|childProcess|bashResolver|processEnv|platform|spawnCwd|cliProviderRun|grok)\b/,
// The cmd.exe wrap and npm-shim bypass every Windows CLI launch goes through.
/^server\/lib\/aiToolkit\/internal\/windowsSafeSpawn\.js$/,
// Path SEMANTICS differ per platform in ways pinPlatform() cannot fake: NTFS
// and APFS are case-insensitive while ext4 is not, and git reports paths its
// own way (drive-letter case, 8.3 short names like C:\Users\RUNNER~1). A
// case-sensitive containment check therefore passed on Linux while reporting a
// managed worktree as unmanaged on Windows, and the reaper silently skipped it
// — green everywhere CI looked. These modules decide containment and worktree
// identity, so they need a real Windows run.
/^server\/lib\/(?:pathSafety|worktreeOwnership)(?:\.test)?\.js$/,
// Fail-fast fixture removal raced continuing writes on Windows (#11641).
// Exercise the ownership helper and affected fixture on the real filesystem.
/^server\/lib\/mockPathsDataRoot(?:\.test)?\.js$/,
/^server\/services\/cosAgentIndex\.completionOrder\.test\.js$/,
// Same class, different mechanism: staticImportGraph keys its module map by
// string-concatenating entry names with "/" but resolves edge targets with
// path.relative, which answers with "\\" on Windows. Every edge into a
// subdirectory module then missed the lookup and vanished — reddening the
// cluster guards' positive assertions while their acyclicity assertions
// passed VACUOUSLY. Nothing here was Windows-risk-tagged, so the Windows job
// skipped the PR that introduced it and main went red for every later PR
// (#5909). The graph's consumers ride along: their expectations are spelled
// in "/" and only a real Windows run can tell.
/^server\/lib\/staticImportGraph(?:\.test)?\.js$/,
/^server\/services\/(?:agent|twin)ImportCycles\.test\.js$/,
/^server\/services\/worktree(?:Manager|Reap)\b/,
/^server\/lib\/shell(?:Cd|Exit|LivenessProbe|ReadinessProbe)(?:\.test)?\.js$/,
/^server\/lib\/agentGuard\//,
/^server\/cos-runner\//,
/^server\/services\/(?:shell|pm2|appBuilder)\b/,
/^server\/services\/agentTuiSpawning(?:\.test)?\.js$/,
/^server\/services\/htmlComposition\/ownedBrowser(?:\.test)?\.js$/,
/^server\/services\/autonomousJobs\/execution\.shellSpawn/,
// The voice fine-tuning service spawns a real Python trainer and settles the
// job from its `close`/`error` events, so its assertions are the child-process
// contract, not platform-independent logic. Nothing here was Windows-tagged,
// so the shard only saw it on a full-matrix run — which is where it failed,
// with an interpreter-startup budget mistaken for a state-machine defect
// (#6268).
/^server\/services\/voice\/fineTuning(?:\.test)?\.js$/,
/^server\/services\/imageGen\/codex(?:\.test)?\.js$/,
/^server\/routes\/apps\//,
/^server\/routes\/scaffoldVite\.js$/,
];
// These are the cross-platform contracts that cannot be faithfully simulated
// by pinning process.platform on Linux. For a Windows-risk PR, Vitest also
// adds import-graph-related tests for the diff; this stable baseline catches
// spawn, shell, PowerShell, PTY, and path regressions without rerunning every
// platform-independent server assertion. Full CI still runs the entire suite.
export const WINDOWS_CONTRACT_TESTS = [
'server/services/htmlComposition/ownedBrowser.test.js',
'scripts/ps1-bom.test.js',
'server/cos-runner/allowedCommands.parity.test.js',
'server/cos-runner/allowedCommands.test.js',
'server/cos-runner/index.test.js',
'server/cos-runner/processStats.test.js',
'server/cos-runner/runnerState.test.js',
'server/cos-runner/streamJsonParser.test.js',
'server/lib/agentGuard/index.test.js',
'server/lib/bashResolver.test.js',
'server/lib/bufferedSpawn.test.js',
'server/lib/childProcess.guards.test.js',
'server/lib/childProcess.promisify.test.js',
'server/lib/childProcess.test.js',
'server/lib/cliProviderRun.test.js',
'server/lib/detachedSpawn.test.js',
'server/lib/grok.test.js',
'server/lib/grokVideoClip.test.js',
'server/lib/platform.test.js',
'server/lib/processEnv.spawnOptions.test.js',
'server/lib/processEnv.test.js',
'server/lib/spawnCwd.test.js',
'server/lib/staticImportGraph.test.js',
'server/lib/shellCd.test.js',
'server/routes/apps/crud.test.js',
'server/routes/apps/icons.test.js',
'server/routes/apps/issues.test.js',
'server/routes/apps/launch.test.js',
'server/routes/apps/lifecycle.test.js',
'server/routes/apps/taskTypes.test.js',
'server/routes/apps/viteTls.test.js',
'server/routes/apps/xcode.test.js',
'server/services/appBuilder.test.js',
'server/services/autonomousJobs/execution.shellSpawn.test.js',
'server/services/pm2.launch.test.js',
'server/services/pm2.parseJlist.test.js',
'server/services/pm2Standardizer.test.js',
'server/services/shell.test.js',
'server/services/shellImageDrop.test.js',
'server/services/agentTuiSpawning.test.js',
'server/services/agentImportCycles.test.js',
'server/services/twinImportCycles.test.js',
'server/services/voice/fineTuning.test.js',
];
// Contract guards that run on EVERY plan, whatever the impact scope selects.
//
// Two kinds of test land here, and both share one property: no impact scope can
// be trusted to select them, because what they assert is not reachable through
// the import graph the scoped modes walk.
//
// 1. Cross-install contract snapshots. `taskPromptDefaults.test.js` pins the
// prompt-upgrade contract (AGENTS.md "Distribution model"): edit a
// preserved historical default and other installs stop recognizing their
// stored prompt, so they are treated as having customized it and stay on
// it forever. Nothing else in the suite notices.
//
// 2. Repo-hygiene guards that enumerate the tracked tree with `git grep` /
// `git ls-files` and assert over files they never import (issue #5055).
// Impact selection is import-graph-driven by construction, so it has no
// edge that can reach them: the violating file is some *other* file, in
// some other directory, that the guard only ever sees as a path string.
// They sat structurally unselectable — `agent-instructions-files.test.js`
// went red on `main` and stayed there while every PR reported green — and
// the always-run list is the only mechanism that can reach them at all.
// `repo-scan-guards.test.js` keeps this half of the list honest: it
// re-derives the scanner set from the tree and fails when a new one is
// added without being registered here or named as structurally selected.
//
// Everything here is deliberately cheap — the whole set runs in ~3s and reads
// only prompt data or `git` output, which is affordable on every PR including
// documentation-only ones, where the alternative is reasoning per-scope about
// what can reach it.
export const ALWAYS_RUN_TESTS = [
// Doc-parity guards: each compares a .md next to it against source it reads
// rather than imports. The .md is documentation-only to the planner and the
// source has no import edge to the guard, so neither side of the comparison
// can select it — a docs-only PR that documented a removed endpoint would
// otherwise merge green.
'docs/api-doc.test.js',
'docs/auth-public-paths-doc.test.js',
'docs/doc-endpoint-methods.test.js',
'docs/docs-index.test.js',
'docs/deps-doc.test.js',
'docs/features/product-surfaces.test.js',
'scripts/agent-instructions-files.test.js',
'scripts/doc-code-pointers.test.js',
// Whole-tree scanner: a new browser suite can adopt the gate with no import
// edge back to the registry it must join (#10312).
'scripts/browser-suite-registry.test.js',
// The union-merged catalogs are `.md` to the planner — documentation-only —
// so a rebase that doubled a row would otherwise never be re-checked.
'scripts/catalog-merge-union.test.js',
// Walks the client→server/lib import graph; any server/lib file can add a
// Node-only import and break the client build with no edge back to here.
'scripts/client-server-import-purity.test.js',
'scripts/direct-invocation-drift.test.js',
'scripts/ensure-deps.test.js',
'scripts/migrations/promptBumpMigrations.guard.test.js',
'scripts/migrations/shippedPromptHistory.guard.test.js',
// Sweeps every migration export against independent prompt-hash baselines;
// migration files have no import edge back to this guard.
'scripts/setup-data-drift.test.js',
'scripts/node-version-drift.test.js',
// Whole-tree markdown scanner: a docs-only PR can reintroduce the stale band
// in prose with no import edge back to this test (#11851).
'scripts/port-band-docs.test.js',
'scripts/repo-scan-guards.test.js',
// Whole-tree scanner: any server file can add an import of client source.
'scripts/server-imports-no-client.test.js',
'scripts/tailnet-identity-leak.test.js',
'server/dependency-overrides.test.js',
// Whole-tree scanner: a caller can disappear from any file without touching its export.
'server/deadExports.test.js',
// Whole-tree scanner: any server file can add a `process.env` read, and
// `.env.example` itself is not a scope the selector routes to a runner.
'server/envExampleDrift.test.js',
// Whole-tree scanner (#12093): any rename or deletion can strand a backticked
// file name in an AGENTS.md, which is documentation-only to the planner.
'server/instructionFileReferences.test.js',
// Whole-tree scanners over the shared collectServerSources/collectClientSources
// walkers (#8723): the offending file is never imported by the guard, so
// impact selection only reaches them when the guard itself changes.
'server/lib/apiRouteGraph.test.js',
// Route inventories and write-back scans depend on independently changed files (#13224).
'server/lib/hostControlRoutes.test.js',
'server/jsonWritebackConventions.test.js',
// Whole-tree scanner (#9982): any server module can start taking backup
// admission with no import edge back to the owner inventory it must join.
'server/lib/backupAssetOwners.test.js',
'server/lib/childProcess.guards.test.js',
'server/lib/cliChildEnv.test.js',
'server/lib/editorial/proseTics.test.js',
'server/lib/generatedManifests.test.js',
// Whole-tree scanner over git-tracked test files (#9000): a suite anywhere
// in server/scripts/lib/autofixer can add a leaked mkdtemp call with no
// import edge back to this guard.
'server/lib/mkdtempCleanup.guards.test.js',
// Base-relative server import-growth guard (#7993). A new eager edge in a
// widely reached module multiplies across suites this file does not import,
// so impact selection would not reach it unless the diff touched this file.
// Docs-only plans and rebases onto a moved base still need the comparison. It reads
// CI_BASE_SHA — the same variable main() requires for a pull request that
// is not forced full — and fails closed when that commit cannot be read.
// Pregate copies the sha into the test process so the local run uses this
// plan's base, not a second guess.
'server/lib/importScoping.test.js',
// Whole-tree scanner over collectServerSources: every cwd-passing spawn pins PWD (#8723).
'server/lib/spawnCwd.test.js',
// Whole-tree scanner: any server/client file can add a hardcoded "Models →"
// breadcrumb, with no import edge back to this file.
'server/lib/localProviderRuntime.test.js',
'server/lib/qwenAgentParsers.test.js',
'server/lib/testDataIsolation.guards.test.js',
'server/lib/testHelper.test.js',
// Whole-tree scanner: any server/client file can re-inline a RegExp escape (#8723).
'server/lib/textUtils.test.js',
// Whole-tree scanner: any server file can log a failure through
// `console.log`, and the guard only ever sees it as a path string.
'server/logLevelConventions.test.js',
// Whole-tree scanner: a module moved between directories leaves a stale cited
// path in some comment, with no import edge to this guard (#12408).
'server/sourceFileReferences.test.js',
// Whole-tree scanner: a renamed export in any module leaves a dead key in some
// suite's vi.mock factory, with no import edge from that suite to this guard (#11891).
'server/mockContractConventions.test.js',
// Whole-tree scanner over git-tracked tests (#12047): any suite can add a
// real sleep before a not-called assertion with no import edge to this guard.
'server/negativeProofSleepConventions.test.js',
// Whole-tree scanner: any server file can spawn a child and await before
// attaching its error/exit listener (#11761), with no import edge to this file.
'server/childListenerOrderConventions.test.js',
// Whole-tree scanner: any server/autofixer file can re-implement raw
// `pm2 jlist` execution/parsing outside the two designated readers (#8164).
'server/pm2JlistOwnership.guard.test.js',
'server/services/imageGen/renderTargets.guard.test.js',
// Whole-tree scanners over collectServerSources (#8723).
'server/services/gitlab.glabFlags.test.js',
'server/services/orphanedPartialGc.test.js',
'server/services/providers.shape.test.js',
'server/services/taskPromptDefaults.test.js',
// Base-relative retired history guard: JSON edits have no import edge here.
// Pregate and CI forward the planner's exact CI_BASE_SHA.
'server/services/taskPromptDefaults/integritySnapshot.guard.test.js',
// Whole-tree scanner (#12048): server/index.js can mount a new router that no
// test imports, with no import edge from that router to this guard.
'server/routeTestCoverageConventions.test.js',
// Whole-tree scanner (#12952): server/index.js can mount a mutating route that
// no host-control classification names, with no import edge to this guard.
'server/hostControlCoverage.test.js',
'server/routeValidationConventions.test.js',
'server/floatingAsyncConventions.test.js',
'server/timerCallbackConventions.test.js',
// Whole-tree scanner (#12815): any server file can bind a bare JSON.stringify to
// a jsonb parameter, with no import edge to this guard.
'server/pgJsonConventions.test.js',
];
const DB_RISK_RULES = [
/^server\/lib\/db(?:\/|\.|$)/i,
/^server\/scripts\/.*db/i,
/^server\/services\/(?:.*\/)?[^/]*DB(?:\/|\.|$)/i,
/^server\/services\/.*\.db\.test\.js$/i,
/^server\/routes\/catalog\.js$/i,
/^scripts\/(?:init-db\.sql|migrations\/.*(?:db|postgres|catalog|privacy))/i,
];
const DOCUMENTATION_RULES = [
/^\.changelog\//,
/^docs\//,
/^(?:README|CHANGELOG|CONTRIBUTING|LICENSE)(?:\.|$)/i,
/\.(?:md|mdx|png|jpe?g|gif|webp|svg|ico)$/i,
];
// Generated data no code or test reads from this checkout: the repo-root
// `.quality.json` is the numeric snapshot `appQualitySnapshotFile.js` lands
// through its own immediately-merged PR. A PR touching only these skips every
// runner, the always-run guards included — there is nothing for them to check.
// The hidden-content diff scan in the impact job still reads it.
const GENERATED_DATA_RULES = [
/^\.quality\.json$/,
];
// Text snapshots are executable test inputs, but their extension is deliberately
// outside EXECUTABLE_RE. Keep this mapping explicit rather than treating every
// `.txt` file as a test fixture: an unmapped text artifact must still widen CI.
// `dir` names the directory the test memo (scripts/lib/testMemo.js) hashes for
// an owning test. `fileRe`, when set, keeps only that directory's direct
// children — `scripts/` is past the memo's directory limit, and hashing the
// whole tree would fail the installer suites closed instead of keying the pins.
export const FIXTURE_OWNERS = [
{
re: /^server\/services\/promptSections\/__snapshots__\/reviewLoopMatrix\/[^/]+\.txt$/,
dir: 'server/services/promptSections/__snapshots__/reviewLoopMatrix',
tests: ['server/services/promptSections/reviewLifecycleMatrix.test.js'],
},
// Pip pins consumed only by an explicit Install/Repair (`setup-image-video.sh`).
// No Vitest suite reads the files; the installer-contract tests are the suites
// that exercise that script and server/lib/pythonSetup.js.
{
re: /^scripts\/requirements-[^/]+\.txt$/,
dir: 'scripts',
fileRe: /^requirements-[^/]+\.txt$/,
tests: [
'scripts/setup-image-video.test.js',
'server/lib/pythonSetup.install.test.js',
'server/lib/pythonSetup.test.js',
],
},
];
const fixtureOwnerFor = (path) => FIXTURE_OWNERS.find(({ re }) => re.test(path));
// The bundled slashdo submodule (see AGENTS.md "Slashdo Commands") ships no
// source into the tree the planner scans — `git diff` reports only the gitlink
// pointer at this path, never the files inside it — so it can't be detected the
// way an ordinary source change is. The contract suites below exercise the
// real bundled renderer and only mean anything with the submodule checked out,
// so CI initializes it (see ci.yml) exactly when one of them is set to run.
export const SLASHDO_GITLINK_PATH = 'lib/slashdo';
export const SLASHDO_CONTRACT_TEST_FILES = [
'server/lib/slashdoLoader.test.js',
'server/lib/slashdoInvocation.test.js',
'server/lib/auditCatalog.test.js',
];
const SLASHDO_CONTRACT_SOURCE_FILES = [
'server/lib/slashdoLoader.js',
'server/lib/slashdoInvocation.js',
];
/**
* Whether this plan's server job needs `lib/slashdo` initialized.
*
* The `changedFiles` check is currently unreachable from `buildCiTestPlan`
* itself: `SLASHDO_GITLINK_PATH` has no recognized extension, so a real
* gitlink change already hits the "unclassified changed file" rule and forces
* `plan.full = true` first, which the `plan.full` clause above already
* covers. It stays as a direct, defense-in-depth check — independent of that
* incidental classification — and is what the unit tests below exercise
* against a hand-built plan.
*
* This only catches a literal edit to the two source files, not an indirect
* one: a shared dependency of `slashdoLoader.js`/`slashdoInvocation.js`
* changing would not set this, even though Vitest's real `related` selection
* can still transitively pull the contract tests in — in which case they run
* without the submodule and take the documented skip. In practice a
* sufficiently shared dependency changing also tends to select more than
* MAX_TARGETED_TEST_FILES explicit server tests, which does trigger this (as
* the full plan that cap used to force did); a narrowly-shared one is the
* remaining gap.
*/
export const needsSlashdoSubmodule = (plan) => Boolean(
plan.full
|| plan.server.files.length > MAX_TARGETED_TEST_FILES
|| plan.changedFiles.includes(SLASHDO_GITLINK_PATH)
|| plan.server.files.some((path) => SLASHDO_CONTRACT_TEST_FILES.includes(path))
|| plan.server.sources.some((path) => SLASHDO_CONTRACT_SOURCE_FILES.includes(path))
);
// Three narrow CI jobs observe a small, enumerable input set, so a pull request
// that touches none of it skips them (non-PR and release-base runs are forced
// full and always run all three). Each gate is the head tree's static import
// closure of the job's entry points, computed per run so it cannot drift from
// a hand-kept list, plus the non-module inputs named by the pattern. ci.yml is
// in both patterns so a workflow edit proves the job still runs.
export const PROMPT_HISTORY_GUARD = 'scripts/migrations/check-shipped-prompt-history.js';
// The guard reads git history of data.reference/prompts/stages and imports the
// migrations that declare prompt hashes. The whole migrations directory is
// listed (not just today's declaring modules) so a diff that removes a
// declaration still runs the guard. taskPromptDefaults and the snapshot
// regenerator are the other half of a prompt-default bump.
export const PROMPT_HISTORY_PATH_RE = /^(?:scripts\/migrations\/|data\.reference\/prompts\/|server\/services\/taskPromptDefaults(?:\/|\.js$)|scripts\/regen-prompt-integrity-snapshot(?:\.test)?\.js$|\.github\/workflows\/ci\.yml$)/;
// The files the `linux-containment` job passes to `npm test --prefix server`.
export const LINUX_CONTAINMENT_TESTS = [
'autofixer/sandbox.verify.test.js',
'server/lib/codeAnimationContainment.test.js',
'server/routes/codeAnimationExecution.test.js',
'server/services/codeAnimation/containedWorker.test.js',
];
// The server Vitest config and its setup files load around every one of those
// tests; vitestTempRootSetup.js is named by URL, not by an import edge.
const LINUX_CONTAINMENT_ENTRIES = [
...LINUX_CONTAINMENT_TESTS,
'server/vitest.config.js',
'server/vitest.setup.js',
'scripts/vitestTempRootSetup.js',
];
// The job installs server dependencies from these before running anything.
export const LINUX_CONTAINMENT_PATH_RE = /^(?:server\/package(?:-lock)?\.json|\.github\/workflows\/ci\.yml)$/;
// The `supercollider-live` job builds docker/supercollider/ through the setup
// script and runs the opt-in live suite on native amd64 and arm64 runners. The
// setup script and the live test reach the runtime, render service and the
// spawn/kill plumbing through static imports, so the closure — not a literal
// path list — selects the job. The server Vitest config and setup files load
// around the live test; vitestTempRootSetup.js is named by URL, not import.
export const SUPERCOLLIDER_LIVE_ENTRIES = [
'server/services/superColliderRender.live.test.js',
'scripts/setup-supercollider.js',
'server/vitest.config.js',
'server/vitest.setup.js',
'scripts/vitestTempRootSetup.js',
];
// The recipe directory and the dependency manifests the job installs from are
// not modules, so the closure cannot see them.
export const SUPERCOLLIDER_LIVE_PATH_RE = /^(?:docker\/supercollider\/|server\/package(?:-lock)?\.json|package(?:-lock)?\.json|\.github\/workflows\/ci\.yml$)/;
// The `docker-containment-live` job runs the opt-in live suite of the Docker
// containment profile (#12844) against the runner's native Docker Engine. The
// suite reaches the profile, the executor, the egress proxy and the engine
// resolver through static imports, so the closure selects the job.
export const DOCKER_CONTAINMENT_LIVE_ENTRIES = [
'server/services/dockerContainment.live.test.js',
'server/vitest.config.js',
'server/vitest.setup.js',
'scripts/vitestTempRootSetup.js',
];
// The job installs server dependencies from these before running anything.
export const DOCKER_CONTAINMENT_LIVE_PATH_RE = /^(?:server\/package(?:-lock)?\.json|\.github\/workflows\/ci\.yml)$/;
/**
* Repository-relative static import closure of `entries` in `cwd`, or null
* when a module cannot be read — the caller then runs the gated job rather
* than trusting a partial walk. Every entry is an input even when absent, so
* deleting or renaming one still runs the job that names it.
*/
const staticClosureOf = (entries, cwd) => {
try {
const files = new Set(entries);
for (const entry of entries) {
if (!existsSync(join(cwd, entry))) continue;
for (const file of staticImportClosure(join(cwd, entry)).files) files.add(toModuleKey(relative(cwd, file)));
}
return uniqueSorted([...files]);
} catch {
return null;
}
};
/** Static closure of the prompt-history guard and every migration it imports. */
export function collectPromptHistoryInputs(files, cwd) {
try {
const declaring = files.filter((path) => path.startsWith('scripts/migrations/')
&& !path.slice('scripts/migrations/'.length).includes('/')
&& isNumberedMigrationFile(basenameOf(path))
&& declaresPromptHashes(readFileSync(join(cwd, path), 'utf8')));
return staticClosureOf([PROMPT_HISTORY_GUARD, ...declaring], cwd);
} catch {
return null;
}
}
/** Static closure of the linux-containment tests and their Vitest harness. */
export const collectLinuxContainmentInputs = (cwd) => staticClosureOf(LINUX_CONTAINMENT_ENTRIES, cwd);
/** Static closure of the SuperCollider live suite, its setup script and their Vitest harness. */
export const collectSuperColliderLiveInputs = (cwd) => staticClosureOf(SUPERCOLLIDER_LIVE_ENTRIES, cwd);
/** Static closure of the Docker containment live suite and its Vitest harness. */
export const collectDockerContainmentLiveInputs = (cwd) => staticClosureOf(DOCKER_CONTAINMENT_LIVE_ENTRIES, cwd);
/** True when the diff reaches a gated job's inputs; null inputs fail open to running it. */
const touchesJobInputs = (changed, inputs, pattern) => inputs === null
|| changed.some((path) => pattern.test(path) || inputs.includes(path));
const RUNNER_ROOTS = {
server: [
'server/',
'scripts/',
'lib/',
'autofixer/',
// server/vitest.config.js globs ../docs/**/*.test.js for the doc-parity
// guards colocated with the documents they check.
'docs/',
],
client: ['client/src/'],
};
const FEATURE_DIRECTORY_RULES = [
/^server\/(?:integrations|lib|routes|services|sockets)\/([^/]+)\//,
/^client\/src\/components\/([^/]+)\//,
];
const normalizeFeature = (value) => String(value || '')
.replace(/\.(?:test|spec)$/i, '')
.replace(/[^a-z0-9]/gi, '')
.toLowerCase();
const featureVariants = (feature) => {
const normalized = normalizeFeature(feature);
const singular = normalized.endsWith('s') ? normalized.slice(0, -1) : normalized;
return new Set([normalized, singular].filter(Boolean));
};
const normalizedPathParts = (path) => path
.split('/')
.flatMap((part) => {
const withoutExt = part.replace(/\.[^.]+$/, '').replace(/\.(?:test|spec)$/i, '');
const camelParts = withoutExt.split(/[-_.]|(?=[A-Z])/).filter(Boolean);
const normalized = normalizeFeature(withoutExt);
const withoutPrefix = normalizeFeature(withoutExt.replace(/^(?:api|use)/i, ''));
return [normalized, withoutPrefix, ...camelParts.map(normalizeFeature)].filter(Boolean);
});
const pathMatchesFeature = (path, feature) => {
const variants = featureVariants(feature);
return normalizedPathParts(path).some((part) => variants.has(part));
};
const isTestFile = (path) => TEST_FILE_RE.test(path);
const isPythonScript = (path) => PYTHON_SCRIPT_RE.test(path);
const isExecutable = (path) => EXECUTABLE_RE.test(path) || isPythonScript(path);
// A documentation directory can also contain runnable contracts and helpers.
const isDocumentationOnly = (path) => !isExecutable(path) && DOCUMENTATION_RULES.some((rule) => rule.test(path));
const isGeneratedData = (path) => GENERATED_DATA_RULES.some((rule) => rule.test(path));
const isServerRunnerFile = (path) => RUNNER_ROOTS.server.some((root) => path.startsWith(root));
const isClientRunnerFile = (path) => RUNNER_ROOTS.client.some((root) => path.startsWith(root));
// Model-capability fixtures ship deliberately broken `*.test.mjs` sandboxes that
// a model is asked to repair. They are data, not suites: no runner collects them,
// and a feature-name match ("models") must not hand one to vitest as a target.
const RUNNER_EXCLUDED_FIXTURES = /^server\/fixtures\//;
const runnerForTest = (path) => {
if (!isTestFile(path) || RUNNER_EXCLUDED_FIXTURES.test(path)) return null;
if (isClientRunnerFile(path)) return 'client';
if (resolveDbTestFiles([path]).length > 0) return 'db';
if (isServerRunnerFile(path)) return 'server';
return null;
};
const featureDirectory = (path) => {
for (const rule of FEATURE_DIRECTORY_RULES) {
const match = path.match(rule);
if (match) return normalizeFeature(match[1]);
}
return null;
};
// The cache boundary copies configs/helpers into synthetic checkouts and reads
// launcher arguments as data. Those runtime edges are invisible to Vitest's
// import graph; select their shared contract explicitly instead of running its
// subprocesses on every unrelated or documentation-only change.
const WORKSPACE_CACHE_COMMON_INPUTS = new Set([
'.github/workflows/ci.yml', 'package.json', 'scripts/lib/workspaceCacheFixture.js',
'scripts/lib/vitestTempRootFixture.js', 'scripts/lib/vitestTempRoot.js',
'scripts/lib/vitestWatch.js', 'scripts/lib/testProcessAttribution.js', 'scripts/lib/testOwnedProcesses.js', 'scripts/lib/darwinTestProcesses.py',
'scripts/lib/vitestStaleRunRoots.js', 'scripts/lib/dbTestFiles.js', 'scripts/lib/workspaceTests.js',
'scripts/vitestCiPool.js', 'scripts/vitestTempRootSetup.js', 'server/lib/killWithEscalation.js',
'server/test/ownedBrowserDiagnostics.js', 'server/lib/mockPathsDataRoot.js',
]);
const WORKSPACE_CACHE_SERVER_INPUTS = new Set([
'server/package.json', 'server/package-lock.json',
'server/vitest.config.js', 'server/vitest.config.db.js', 'server/vitest.setup.js',
'server/test/admissionSetup.js', 'server/test/mediaRegistryEnvironment.js',
]);
const WORKSPACE_CACHE_CLIENT_INPUTS = new Set([
'ecosystem.config.cjs', 'client/package.json', 'client/package-lock.json',
'client/vite.config.js', 'client/vite.buildEnv.js', 'client/vite.chunkGroups.js',
'client/vitest.config.js', 'client/src/test/timeouts.js', 'scripts/vitestProcessEnvironment.js',
'scripts/dev-start.js', 'scripts/publish-client-build.js',
'scripts/lib/envFile.cjs', 'scripts/lib/databaseSettings.cjs',
'lib/portosAuthCore.js', 'server/lib/eidoverseProxyRoutes.js',
]);
export const structuralTestsFor = (changedFiles, trackedSet) => {
const selected = [];
const add = (path) => {
if (trackedSet.has(path)) selected.push(path);
};
const sharedCacheInputChanged = changedFiles.some((path) => WORKSPACE_CACHE_COMMON_INPUTS.has(path));
if (sharedCacheInputChanged || changedFiles.some((path) => WORKSPACE_CACHE_SERVER_INPUTS.has(path))) {
add('scripts/workspaceCaches.test.js');
}
if (sharedCacheInputChanged || changedFiles.some((path) => WORKSPACE_CACHE_CLIENT_INPUTS.has(path))) {
add('client/src/test/workspaceCaches.test.js');
// The runner's client enumeration is pinned against `vitest list` from the client workspace, where the client job runs it.
add('client/src/test/workspaceTests.test.js');
}
if (changedFiles.some((path) => /^server\/lib\//.test(path))) {
add('server/lib/index.test.js');
}
// These guards read the tree rather than importing it, so no import edge
// selects them: the route-graph guard catches a route file nothing mounts,
// the parity guard a client wrapper stranded by a renamed mount, and the
// prompt-stage drift test a stale manifest — which is what a scoped plan
// let merge before this rule existed (#5898).
if (changedFiles.some((path) => /^server\/.*\.js$/.test(path) || /^server\/lib\/.*\.generated\.json$/.test(path))) {
add('server/lib/apiRouteGraph.test.js');
add('server/lib/apiRouteParity.test.js');
add('scripts/generate-prompt-stage-call-sites.test.js');
}
// The socket guard readdir-scans server/sockets/ rather than importing it, so
// no import edge reaches it — a handler added there would otherwise only be
// checked on a full suite.
if (changedFiles.some((path) => /^server\/sockets\//.test(path))) {
add('server/sockets/asyncHandlerGuard.test.js');
}
if (changedFiles.some((path) => /^client\/src\/lib\//.test(path))) {
add('client/src/lib/index.test.js');
}
if (changedFiles.some((path) => /^client\/src\/hooks\//.test(path))) {
add('client/src/hooks/index.test.js');
}
if (changedFiles.some((path) => /^client\/src\/utils\//.test(path))) {
add('client/src/utils/index.test.js');
}
if (changedFiles.some((path) => /^client\/src\/.*\.jsx$/.test(path))) {
add('client/src/a11yConventions.test.js');
}
// Both `.js` and `.jsx`: the StrictMode mounted-ref bug the first guard covers
// reached its widest blast radius through a plain-`.js` hook (`useAsyncAction`),
// so a `.jsx`-only trigger would miss the case that matters most, and the
// responsive-grid, popover-clamp, pre-wrap/break, safe-storage, heading-truncation,
// sub-nav, dashboard-widget container-query, and global-shadow guards read class
// strings, storage accesses, declarations, and JSX markup out of both extensions.
// None of these files has a source sibling or imports an app module, so nothing
// else selects them — without this entry they only ever run on a full suite.
if (changedFiles.some((path) => /^client\/src\/.*\.jsx?$/.test(path))) {
add('client/src/apiWrapperOptionsConventions.test.js');
add('client/src/asyncEffectDisposalConventions.test.js');
add('client/src/dashboardWidgetContainerConventions.test.js');
add('client/src/globalShadowConventions.test.js');
add('client/src/headingTruncationConventions.test.js');
add('client/src/hooks/mountedRefConventions.test.js');
add('client/src/listFetchConventions.test.js');
add('client/src/moduleContractConventions.test.js');
add('client/src/numberFormattingConventions.test.js');
add('client/src/pageShellConventions.test.js');
add('client/src/pollingConventions.test.js');
add('client/src/popoverClampConventions.test.js');
add('client/src/preWrapClasses.test.js');
add('client/src/providerSelectConventions.test.js');
add('client/src/responsiveGridConventions.test.js');
add('client/src/socketSubscriptionConventions.test.js');
add('client/src/storageConventions.test.js');
add('client/src/subNavConventions.test.js');
// Same trigger, different subject: this one scans the TEST files for an
// inline async bound the per-test budget would cut short, and a changed
// `*.test.jsx` matches the `.jsx?` pattern above.
add('client/src/test/timeouts.test.js');
}
return selected;
};
const uniqueSorted = (values) => [...new Set(values)].sort();
// Guarded by trackedSet like every other selector: an untracked path handed to
// Vitest as an exact selector makes the run exit non-zero.
const alwaysRunTests = (trackedSet) => ALWAYS_RUN_TESTS.filter((path) => trackedSet.has(path));
/**
* Split a set of always-run selectors across the two Vitest runners.
*
* The docs-only plan names its files directly instead of going through the
* runner split the scoped branches use, so it has to do that split itself: an
* entry added to ALWAYS_RUN_TESTS under client/src would otherwise be handed to
* the server runner, which does not glob client/, and the guard would report
* green having run nowhere.
*/
export const splitByRunner = (paths) => ({
server: paths.filter((path) => runnerForTest(path) === 'server'),
client: paths.filter((path) => runnerForTest(path) === 'client'),
});
const windowsContractTests = (trackedSet) => WINDOWS_CONTRACT_TESTS.filter((path) => trackedSet.has(path));
/**
* Does this diff touch a surface only a real Windows runner can prove?
*
* Deliberately NOT restricted to isExecutable() paths: .ps1/.cmd/.bat are not
* in EXECUTABLE_RE, so a PowerShell change used to reach the Windows job only
* as a side effect of being an "unclassified changed file". This answers the
* question directly, and is what overrides a trigger's windowsEscalates:false.
*/
const hasWindowsRiskFile = (paths) => paths.some((path) => (
!isDocumentationOnly(path) && WINDOWS_RISK_RULES.some((rule) => rule.test(path))
));
const skippedRunner = () => ({ mode: 'skip', files: [], sources: [] });
// Catalog barrels are validated by structural export guards. Feeding one to
// Vitest's import graph selects nearly every consumer even though the barrel
// contains no behavior; PR #5296 changed server/lib/index.js and consequently
// selected 1,244 files / 27,491 tests. Behavioral source files in the same diff
// still drive related-test selection normally.
//
// Also the set `.gitattributes` merges with `union` — scripts/catalog-merge-union.test.js
// pins the two lists to each other.
export const STRUCTURAL_BARRELS = [
'server/lib/index.js',
'client/src/lib/index.js',
'client/src/hooks/index.js',
'client/src/utils/index.js',
];
const isStructuralBarrel = (path) => STRUCTURAL_BARRELS.includes(path);
/**
* A route declaration is a safe, client-only subset of the App composition
* root. Everything else in App.jsx can alter providers, boot hooks, lazy
* imports, or authentication boundaries and must retain the complete matrix.
*
* This intentionally accepts only one-line Route additions/removals. Unknown
* diff shapes (including comments, formatting, or multiline JSX) are unsafe
* by default, so a future route style cannot silently narrow CI.
*/
export const isRouteOnlyAppDiff = (diff) => {
if (typeof diff !== 'string' || !diff.trim()) return false;
const changedLines = diff.split('\n').filter((line) => /^[+-]/.test(line) && !/^(?:\+\+\+|---)/.test(line));
return changedLines.length > 0 && changedLines.every((line) => /^[-+]\s*<\/?Route\b.*>(?:\s*)$/.test(line));
};
// A scoped runner spread over several shards says why, so the summary never
// reads as a full run.
const fanOutNote = (plan, runner) => {
const count = plan.shards[runner].length;
if (plan.full || count === 1) return '';
return plan[runner].files.length > MAX_TARGETED_TEST_FILES
? `; ${plan[runner].files.length} selected test files exceed the ${MAX_TARGETED_TEST_FILES}-file cap, sharded ${count} ways`
: `; related import graph sharded ${count} ways`;
};
const suiteReasonsFor = (plan, { appRouteOnly = false } = {}) => ({
server: plan.server.mode === 'skip'
? 'skipped: no server-impacting source changed'
: plan.full
? `full matrix: ${plan.reason}`
: `always-run cross-install and repository guards${fanOutNote(plan, 'server')}`,
client: plan.client.mode === 'skip'
? 'skipped: no client-impacting source changed'
: appRouteOnly
? `route-only client App.jsx change: related client contracts${fanOutNote(plan, 'client')}`
: plan.full
? `full matrix: ${plan.reason}`
: `client-impacting source changed${fanOutNote(plan, 'client')}`,
browser: plan.browserFiles.length > 0
? (plan.full ? `full matrix: ${plan.reason}` : `${plan.browserFiles.length} cross-workspace browser suite(s) selected`)
: 'skipped: no cross-workspace browser suite selected',
db: plan.db ? (plan.full ? `full matrix: ${plan.reason}` : 'database-risk source changed') : 'skipped: no database-risk source changed',
lint: plan.lint.mode === 'skip' ? 'skipped: no changed source needs linting' : plan.full ? `full matrix: ${plan.reason}` : 'changed lintable source',
build: plan.build ? (plan.full ? `full matrix: ${plan.reason}` : 'client-impacting source changed') : 'skipped: no client-impacting source changed',
smoke: plan.smoke ? (plan.full ? `full matrix: ${plan.reason}` : 'server-impacting source changed') : 'skipped: no server-impacting source changed',
// A full plan whose Windows job stayed at the contract baseline says so
// explicitly, so the CI summary never reads "full matrix" beside a one-shard
// Windows run (issue #7440).
// A dependency-manifest plan names the packages behind its Windows decision.
windows: !plan.windows
? 'skipped: no Windows-sensitive surface changed'
: plan.full
? `${plan.windowsMode === 'full'
? `full matrix: ${plan.reason}`
: `Windows contract baseline (full matrix elsewhere): ${plan.reason}`}${plan.windowsNote ? `; ${plan.windowsNote}` : ''}`
: 'Windows-sensitive surface changed',
});
/**
* Build a conservative PR test plan.
*
* "files" mode is used only when every executable change belongs to a
* directory-scoped feature (for example services/sprites + components/sprites).
* Flat/shared files fall back to Vitest's import-graph-aware "related" mode,
* while composition roots and test configuration force the complete suite.
*/
/**
* The CI plan for a diff: the test-suite selection plus whether each
* path-gated job (prompt history, Linux containment, SuperCollider live,
* Docker containment live) runs.
*
* `promptHistoryInputs` / `linuxContainmentInputs` / `supercolliderLiveInputs` are the jobs' static
* import closures from collectPlanInputs(); null (the default) runs the job.
*/
export function buildCiTestPlan(changedFiles, options = {}) {
const plan = buildSuitePlan(changedFiles, options);
const {
forceFull = false, promptHistoryInputs = null, linuxContainmentInputs = null, supercolliderLiveInputs = null,
dockerContainmentLiveInputs = null, serverReach = null,
} = options;
// Informational: names the changed source behind a large related selection
// (#12285). It never changes what runs.
const reachNote = !plan.full && plan.server.mode === 'related' ? formatReachSummary(serverReach) : '';
return {
...plan,
...(reachNote ? { suiteReasons: { ...plan.suiteReasons, server: `${plan.suiteReasons.server}; ${reachNote}` } } : {}),
promptHistory: forceFull || touchesJobInputs(plan.changedFiles, promptHistoryInputs, PROMPT_HISTORY_PATH_RE),
linuxContainment: forceFull
|| touchesJobInputs(plan.changedFiles, linuxContainmentInputs, LINUX_CONTAINMENT_PATH_RE),
supercolliderLive: forceFull
|| touchesJobInputs(plan.changedFiles, supercolliderLiveInputs, SUPERCOLLIDER_LIVE_PATH_RE),
dockerContainmentLive: forceFull
|| touchesJobInputs(plan.changedFiles, dockerContainmentLiveInputs, DOCKER_CONTAINMENT_LIVE_PATH_RE),
};
}
function buildSuitePlan(changedFiles, {
trackedFiles = [],
forceFull = false,
forceFullReason = 'full CI requested',
appRouteOnly = false,
// Changed source path → tracked test files naming its basename (see
// sourceReferencePattern). Covers every changed source, not only python
// scripts — see rule 1 of issue #6363.
pathContractTests = {},
// Repository-derived browser dependencies; null means discovery failed and
// a shared-source change must retain conservative full coverage.
clientDependencies = [],
// Client test → shared dependencies; null conservatively retains that test.
// Kept separate from production dependencies so fixtures never force a build.
clientTestDependencies = {},
// Includes literal deferred imports; null means discovery was inconclusive.
dbDependencies = [],
// Registered suite → reachable files; null retains that suite conservatively.
browserDependencies = {},
// Changed dependency manifest → classifyDependencyChange() verdict. A
// manifest with no verdict escalates Windows (fail closed).
dependencyChanges = {},
} = {}) {
const changed = uniqueSorted(changedFiles.filter(Boolean));
const trackedSet = new Set(trackedFiles);
// Nightly, the main -> release PR, release, and an explicit "full CI"
// request keep the complete Windows matrix. ci.yml has no push trigger, so
// these ARE the discovery net for a Windows regression on a surface nobody
// has tagged — the same net every PR that touches no WINDOWS_RISK_RULES file
// already relies on. A downgrade below widens that existing population; it
// does not invent a new risk class.
if (forceFull) {
return fullPlan(changed, forceFullReason, { appRouteOnly, trackedSet, windowsEscalates: true });
}
// EVERY matching trigger, not just the reported one, and computed BEFORE the
// first full-plan branch. The reason line is the first match in sorted-path
// order, but the Windows decision is the OR over all of them, so a diff that
// trips two triggers must escalate if EITHER does. Two ways this goes wrong
// if the OR is skipped: an alphabetically earlier client-only trigger
// (client/vite.config.js) reported ahead of server/index.js, and the App.jsx
// branch below returning before the triggers are even looked at — which
// downgraded Windows for an App.jsx PR that also bumped a lockfile.
const dependencyVerdicts = [];
const fullTriggers = changed
.flatMap((path) => FULL_TRIGGER_RULES
.filter(({ re }) => re.test(path))
.map(({ reason, windowsEscalates }) => {
const scopedToWindows = windowsEscalates === 'dependencies' || (windowsEscalates === true && /(?:^|\/)\.npmrc$/.test(path));
if (!scopedToWindows) return { path, reason, windowsEscalates };
if (!windowsInstalls(path)) {
dependencyVerdicts.push(`${path} keeps the Windows baseline: the Windows job does not install that workspace`);
return { path, reason, windowsEscalates: false };
}
if (windowsEscalates === true) return { path, reason, windowsEscalates };
const verdict = dependencyChanges[path] ?? escalated('no manifest comparison available');
dependencyVerdicts.push(describeDependencyVerdict(path, verdict));
return { path, reason, windowsEscalates: verdict.escalate };
}));
const fullTrigger = fullTriggers.at(0);
const triggersEscalateWindows = fullTriggers.some((trigger) => trigger.windowsEscalates);
const windowsNote = dependencyVerdicts.join('; ');
const appCompositionChanged = changed.includes('client/src/App.jsx');
if (appCompositionChanged && !appRouteOnly) {
// The composition root itself is client-only, but the rest of the diff may
// not be.
return fullPlan(changed, 'client composition root changed: client/src/App.jsx', {
appRouteOnly,
trackedSet,
windowsEscalates: triggersEscalateWindows,
windowsNote,
});
}
if (fullTrigger) {
return fullPlan(changed, `${fullTrigger.reason}: ${fullTrigger.path}`, {
appRouteOnly,
trackedSet,
windowsEscalates: triggersEscalateWindows,
windowsNote,
});
}
const dataOnly = changed.length > 0 && changed.every(isGeneratedData);
const alwaysRun = dataOnly ? [] : alwaysRunTests(trackedSet);
const relevant = changed.filter((path) => !isDocumentationOnly(path) && !isGeneratedData(path));
if (relevant.length === 0) {
const { server: alwaysRunServer, client: alwaysRunClient } = splitByRunner(alwaysRun);
const reason = dataOnly ? 'generated data-only change'
: changed.length ? 'documentation-only change' : 'no changed files';
const plan = {
full: false,
reason,
changedFiles: changed,
server: alwaysRunServer.length > 0 ? { mode: 'files', files: alwaysRunServer, sources: [] } : skippedRunner(),
client: alwaysRunClient.length > 0 ? { mode: 'files', files: alwaysRunClient, sources: [] } : skippedRunner(),
browserFiles: browserSuitesIn(alwaysRun),
db: false,
lint: { mode: 'skip', files: [] },
build: false,
smoke: false,
windows: false,
windowsMode: 'skip',
windowsFiles: [],
windowsSources: [],
};
return finishPlan(plan, { appRouteOnly });
}
const executable = relevant.filter(isExecutable);
const fixtureTests = [];
const unknown = [];
const missingFixtureOwners = [];
for (const path of relevant) {
if (isExecutable(path)) continue;
const owner = fixtureOwnerFor(path);
if (!owner) {
unknown.push(path);
continue;
}
if (owner.tests.some((test) => !trackedSet.has(test) || !runnerForTest(test))) {
missingFixtureOwners.push(path);
continue;
}
fixtureTests.push(...owner.tests);
}
if (unknown.length > 0) {
return fullPlan(changed, `unclassified changed file: ${unknown[0]}`, { appRouteOnly, trackedSet });
}
if (missingFixtureOwners.length > 0) {
return fullPlan(changed, `fixture owner not tracked: ${missingFixtureOwners[0]}`, { appRouteOnly, trackedSet });
}
if (executable.length > MAX_CHANGED_CODE_FILES) {
return fullPlan(changed, `wide change (${executable.length} executable files)`, { appRouteOnly, trackedSet, windowsEscalates: false });
}
// `changed` includes deleted paths (diff-filter ACMRD), but a deleted test
// file passed as an exact Vitest selector makes the runner exit non-zero on
// an otherwise-valid deletion PR — trackedSet (git ls-files) excludes it.
const directTests = executable.filter(isTestFile).filter((path) => trackedSet.has(path));
const sourceFiles = executable.filter((path) => !isTestFile(path));
const unsupportedSources = sourceFiles.filter((path) => (
!isServerRunnerFile(path) && !path.startsWith('client/')
));
if (unsupportedSources.length > 0) {
return fullPlan(changed, `unmapped executable surface: ${unsupportedSources[0]}`, { appRouteOnly, trackedSet });
}
const deletedSources = sourceFiles.filter((path) => !trackedSet.has(path));
if (deletedSources.length > 0) {
// `vitest related` needs a real source path. A deleted module can still
// affect importers, so widening is safer than silently dropping its side of
// the graph.
return fullPlan(changed, `deleted executable source: ${deletedSources[0]}`, { appRouteOnly, trackedSet });
}
// Python scripts never enter the import graph or a feature directory: their
// only selector is the per-script contract list, so they leave the JS-only
// scoping below.
const pythonSources = sourceFiles.filter(isPythonScript);
const jsSources = sourceFiles.filter((path) => !isPythonScript(path));
if (clientDependencies === null && jsSources.some((path) => path.startsWith('server/lib/'))) {
return fullPlan(changed, 'client dependency discovery unresolved', { appRouteOnly, trackedSet });
}
const clientDependencySet = new Set(clientDependencies || []);
const isClientSource = (path) => path.startsWith('client/') || clientDependencySet.has(path);
const features = uniqueSorted(jsSources.map(featureDirectory).filter(Boolean));
const selectedTests = [
...directTests,
...fixtureTests,
...structuralTestsFor(changed, trackedSet),
...alwaysRun,
...Object.entries(clientTestDependencies)
.filter(([test, dependencies]) => trackedSet.has(test) && runnerForTest(test) === 'client'
&& jsSources.some((source) => isSharedClientDependency(source)
&& (dependencies === null || dependencies.includes(source))))
.map(([test]) => test),
];
for (const script of pythonSources) {
const pythonTests = (pathContractTests[script] || [])
.filter((path) => trackedSet.has(path) && runnerForTest(path));
if (pythonTests.length === 0) {
return fullPlan(changed, `python script with no parsing contract: ${script}`, { appRouteOnly, trackedSet });
}
selectedTests.push(...pythonTests);
}
// Every other changed source rides the same basename `git grep` lookup, but
// additively: unlike python, a JS/TS source is already reachable through the
// import graph or a feature directory, so an empty hit list here is not an
// error — it just means nothing reads this file as text.
for (const source of jsSources) {
const namedTests = (pathContractTests[source] || [])
.filter((path) => trackedSet.has(path) && runnerForTest(path));
selectedTests.push(...namedTests);
}
for (const testFile of trackedFiles.filter(isTestFile)) {
if (features.some((feature) => pathMatchesFeature(testFile, feature))) {
selectedTests.push(testFile);
}
}
const serverFiles = uniqueSorted(selectedTests.filter((path) => runnerForTest(path) === 'server'));
const clientFiles = uniqueSorted(selectedTests.filter((path) => runnerForTest(path) === 'client'));
const hasServerSource = jsSources.some(isServerRunnerFile);
const hasClientSource = jsSources.some(isClientSource);
const serverSources = jsSources
.filter(isServerRunnerFile)
.filter((path) => !isStructuralBarrel(path));
const clientSources = jsSources
.filter(isClientSource)
.filter((path) => clientDependencySet.has(path) || !isStructuralBarrel(path));
// Feature-name matches, basename contracts, direct tests and guards are
// additive explicit selectors; they never replace import-graph traversal. A
// nested feature leaf can be consumed by a differently named test in another
// area, so any behavioral source in a runner takes one 'related' invocation.
// Only a barrel-only edit (fully covered by the structural export guard) or a
// test-only diff keeps exact-file selection.
const serverMode = serverSources.length > 0 ? 'related' : 'files';
const clientMode = clientSources.length > 0 ? 'related' : 'files';
const server = serverFiles.length > 0
? { mode: serverMode, files: serverFiles, sources: serverMode === 'related' ? serverSources : [] }
: hasServerSource
? { mode: serverSources.length > 0 ? 'related' : 'files', files: [], sources: serverSources }
: skippedRunner();
const client = clientFiles.length > 0
? { mode: clientMode, files: clientFiles, sources: clientMode === 'related' ? clientSources : [] }
: hasClientSource
? { mode: clientSources.length > 0 ? 'related' : 'files', files: [], sources: clientSources }
: skippedRunner();
const dbTests = new Set(resolveDbTestFiles(trackedFiles));
const db = selectedTests.some((path) => dbTests.has(path))
|| executable.some((path) => DB_RISK_RULES.some((rule) => rule.test(path)))
|| serverSources.some((path) => dbDependencies === null || dbDependencies.includes(path));
const windows = hasWindowsRiskFile(changed);
const windowsMode = windows
? (serverSources.length > 0 ? 'related' : 'files')
: 'skip';
let reason = 'Vitest related-test fallback';
if (features.length) reason = `targeted features: ${features.join(', ')}`;
else if (jsSources.length === 0 && pythonSources.length > 0) reason = 'python script parsing contracts';
else if (jsSources.length === 0 && fixtureTests.length > 0) reason = 'text fixture owners';
return finishPlan({
full: false,
reason,
changedFiles: changed,
server,
client,
browserFiles: browserSuitesIn([
...serverFiles,
...BROWSER_SUITES.filter((suite) => trackedSet.has(suite)
&& serverSources.some((source) => browserDependencies[suite] === null
|| browserDependencies[suite]?.includes(source))),
]),
db,
lint: {
// Same deleted-path guard as directTests above — ESLint given a
// nonexistent explicit path exits non-zero instead of skipping it.
mode: changed.some((path) => isLintSurface(path) && trackedSet.has(path)) ? 'files' : 'skip',
files: changed.filter((path) => isLintSurface(path) && trackedSet.has(path)),
},
build: hasClientSource,
smoke: hasServerSource,
windows,
windowsMode,
windowsFiles: windows ? uniqueSorted([
...windowsContractTests(trackedSet),
// Test-only changes have no source path for `vitest related` to follow.
// A risk tag must select the changed contract itself as well as baseline.
...directTests.filter(path => isServerRunnerFile(path) && hasWindowsRiskFile([path])),
]) : [],
windowsSources: windowsMode === 'related' ? serverSources : [],
}, { appRouteOnly, linuxRunnerExcludes: new Set([...dbTests, ...BROWSER_SUITES]) });
}
/**
* The derived fields every plan carries: per-suite reasons and shard matrices.
*
* `linuxRunnerExcludes` names selected files the Linux test jobs never run
* (DB and browser suites have their own jobs); fansOut() keeps them out of the
* shard-count floor.
*/
const finishPlan = (plan, { linuxRunnerExcludes = new Set(), ...options } = {}) => {
const linuxShards = (runner) => shardIndexes(
fansOut(runner, plan[runner], linuxRunnerExcludes) ? 'full' : plan[runner].mode,
FULL_SUITE_SHARDS[runner],
);
const shards = {
server: linuxShards('server'),
client: linuxShards('client'),
// Related mode can reach most of the server graph through one shared
// source. The explicit selector count does not bound that work: one Windows
// runner exceeded the unchanged 15-minute step budget on a TUI handshake
// edit. Split execution across the existing matrix without widening or
// reducing related-test selection; exact-file plans stay on one runner.
windows: shardIndexes(plan.windowsMode === 'related' ? 'full' : plan.windowsMode, FULL_SUITE_SHARDS.windows),
};
return {
...plan,
slashdo: needsSlashdoSubmodule(plan),
suiteReasons: suiteReasonsFor({ ...plan, shards }, options),
shards,
};
};
/**
* A full plan for every Linux suite — with the Windows job at the depth the
* diff actually justifies.
*
* `windowsEscalates` (default true, so an unlisted caller fails closed) is
* false only for a trigger windows-server cannot observe: a client-only
* surface, pure cross-platform schema logic, a dependency-manifest change
* classifyDependencyChange() proved platform-neutral, or a CAPACITY escalation
* (a wide diff) that says the planner ran out of scoping headroom, not that
* anything risky changed. A touched WINDOWS_RISK_RULES path overrides it back to full.
*
* Downgraded does not mean skipped: the job still runs WINDOWS_CONTRACT_TESTS,
* the curated cross-platform baseline a Windows-risk scoped PR already gets.
* The complete Windows matrix stays the discovery net for surfaces nobody has
* tagged yet — it just runs nightly, on the main -> release PR, and on
* release, instead of on every capacity-widened PR (issue #7440).
*
* `options` is also forwarded to finishPlan(), which reads only appRouteOnly.
*/
function fullPlan(changedFiles, reason, options = {}) {
const { trackedSet = new Set(), windowsEscalates = true, windowsNote = '' } = options;
// An empty `files` list makes run-ci-tests.js print "No server tests
// selected" and exit 0 — a green Windows job that ran nothing. So the
// baseline is only a downgrade while it actually resolves to tracked tests;
// otherwise this falls back to the complete suite rather than to silence.
const baseline = windowsContractTests(trackedSet);
const windowsFull = windowsEscalates || hasWindowsRiskFile(changedFiles) || baseline.length === 0;
return finishPlan({
full: true,
reason,
changedFiles,
server: { mode: 'full', files: [], sources: [] },
client: { mode: 'full', files: [], sources: [] },
browserFiles: browserSuitesIn([...trackedSet]),
db: true,
lint: { mode: 'full', files: [] },
build: true,
smoke: true,
windows: true,
windowsMode: windowsFull ? 'full' : 'files',
windowsFiles: windowsFull ? [] : baseline,
windowsSources: [],
windowsNote,
}, options);
}
// Git's display output quotes non-ASCII/control characters; trimming also
// changes valid paths. Read raw NUL-delimited paths so selectors stay exact.
const gitPaths = (args, cwd) => execFileSync('git', args, { cwd, encoding: 'utf8' })
.split('\0')
.filter(Boolean);
/** Tracked test files whose text matches `pattern`; `git grep` exit 1 is "none". */
const gitGrepFiles = (pattern, pathspecs, cwd) => {
try {
return gitPaths(['grep', '-z', '-l', '-E', pattern, '--', ...pathspecs], cwd);
} catch (err) {
if (err.status === 1) return [];
throw err;
}
};
const basenameOf = (path) => path.slice(path.lastIndexOf('/') + 1);
/** Basenames carried by more than one present, executable, non-test source. */
const sharedSourceBasenames = (files) => {
const seen = new Set();
const shared = new Set();
for (const path of files) {
if (!isExecutable(path) || isTestFile(path)) continue;
const name = basenameOf(path);
(seen.has(name) ? shared : seen).add(name);
}
return shared;
};
/**
* Keep the basename hits that plausibly mean THIS copy of a shared basename:
* a test inside the source's directory subtree (it reaches the file as
* `./name` or `../name`), or one whose text also names the source's parent
* directory as a token (`cos-runner`, `aiToolkit`, `join(…, 'imageGen', …)`).
* A test naming only another directory's `index.js` is dropped; Vitest's
* import graph still selects every real importer. A repo-root source has no
* parent to tell copies apart, so it keeps every hit (#11870).
*/
const narrowSharedBasenameHits = (source, hits, cwd) => {
const dir = posix.dirname(source);
if (dir === '.' || hits.length === 0) return hits;
const parent = basenameOf(dir);
const naming = new Set(gitGrepFiles(
`(^|[^A-Za-z0-9_])${escapeRegExp(parent)}([^A-Za-z0-9_]|$)`,
hits.map((path) => `:(literal)${path}`),
cwd,
));
return hits.filter((path) => path.startsWith(`${dir}/`) || naming.has(path));
};
export function emitGitHubPlan(plan) {
const outputs = {
full: plan.full,
reason: plan.reason.replace(/[`<>\r\n]+/g, ' '),
server_mode: plan.server.mode,
server_files: JSON.stringify(plan.server.files),
server_sources: JSON.stringify(plan.server.sources),
client_mode: plan.client.mode,
client_files: JSON.stringify(plan.client.files),
client_sources: JSON.stringify(plan.client.sources),
browser_files: JSON.stringify(plan.browserFiles),
db: plan.db,
lint_mode: plan.lint.mode,
lint_files: JSON.stringify(plan.lint.files),
build: plan.build,
smoke: plan.smoke,
slashdo: plan.slashdo,
prompt_history: plan.promptHistory,
linux_containment: plan.linuxContainment,
supercollider_live: plan.supercolliderLive,
docker_containment_live: plan.dockerContainmentLive,
windows: plan.windows,
windows_mode: plan.windowsMode,
windows_files: JSON.stringify(plan.windowsFiles),
windows_sources: JSON.stringify(plan.windowsSources),
server_shards: JSON.stringify(plan.shards.server),
client_shards: JSON.stringify(plan.shards.client),
windows_shards: JSON.stringify(plan.shards.windows),
suite_reasons: JSON.stringify(plan.suiteReasons),
// The pregate attestation this plan honored (see applyAttestation), or
// why none was: `{"attested": false, "reason": …}` is still a decision.
attestation: JSON.stringify(plan.attestation ?? { attested: false, reason: 'no attestation resolved' }),
attested_stages: JSON.stringify(plan.attestedStages ?? []),
};
Object.entries(outputs).forEach(([name, value]) => {
writeStepOutput(name, value);
});
console.log(JSON.stringify({ ...outputs, changed_files: plan.changedFiles }, null, 2));
}
/**
* Why this run cannot be scoped, or null when it can be.
*
* A pull request into `release` is the single gate a release ships behind —
* release.yml skips its own suite on the strength of it — so it always runs
* complete, whatever its diff touches.
*/
export function forceFullReasonFor({ forceFull, baseRef }) {
if (forceFull) return 'full CI requested';
if (baseRef === 'release') return 'release gate: pull request into release';
return null;
}
// A collection owns its snapshot: each source is read and each prerequisite
// edge is resolved once, even when many browser suites reach the same module.
// Never retain this across collections: local pregate must see the next edit.
function createDependencySnapshot(files, cwd) {
const known = new Set(files);
const sources = new Map();
const staticEdges = new Map();
const testEdges = new Map();
const extensions = ['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.mts', '.cts', '.json'];
const readText = (file) => {
if (!sources.has(file)) {
try {
sources.set(file, { text: readFileSync(join(cwd, file), 'utf8') });
} catch (error) {
sources.set(file, { error });
}
}
const source = sources.get(file);
if (source.error) throw source.error;
return source.text;
};
const resolve = (file, specifiers) => {
const dependencies = [];
let inconclusive = false;
for (const specifier of specifiers) {
if (!specifier.startsWith('.')) continue;
const path = posix.normalize(posix.join(posix.dirname(file), specifier.split(/[?#]/)[0]));
// Preserve all candidates when extensions collide, not a guessed bundler precedence.
const candidates = [path, ...extensions.map((extension) => `${path}${extension}`),
...extensions.map((extension) => `${path}/index${extension}`)].filter((candidate) => known.has(candidate));
if (candidates.length === 0) inconclusive = true;
dependencies.push(...candidates);
}
return { dependencies, inconclusive };
};
const staticDependencies = (file) => {
if (!staticEdges.has(file)) {
staticEdges.set(file, resolve(file, staticImportSpecifiersFromSource(readText(file))));
}
return staticEdges.get(file);
};
const testDependencies = (file) => {
if (!testEdges.has(file)) {
const deferred = [];
let computed = false;
// Nonliterals and extra matches in comments widen prerequisites safely.
for (const match of readText(file).matchAll(/\bimport\s*\(\s*([^)]*)\)/g)) {
const literal = match[1].trim().match(/^(['"`])([^'"`]*?)\1\s*(?:,.*)?$/s);
if (!literal || literal[2].includes('${')) computed = true;
else deferred.push(literal[2]);
}
const statics = staticDependencies(file);
const dynamic = resolve(file, deferred);
testEdges.set(file, {
dependencies: [...statics.dependencies, ...dynamic.dependencies],
inconclusive: computed || statics.inconclusive || dynamic.inconclusive,
});
}
return testEdges.get(file);
};
return { readText, staticDependencies, testDependencies };
}
function isSharedClientDependency(path) {
return path.startsWith('server/lib/') || path.startsWith('scripts/lib/');
}
// Start from every browser source, including lazy-loaded pages, then follow
// relative static imports and re-exports across directory boundaries. Unresolved
// edges must widen CI rather than disappearing from a negative graph walk.
function collectClientDependencies(files, snapshot) {
const entries = files.filter((path) => path.startsWith('client/src/')
&& MODULE_SOURCE_RE.test(path) && !isTestFile(path));
const closure = collectTestDependencies(entries, snapshot.staticDependencies);
return closure?.filter((path) => path.startsWith('server/lib/')) ?? null;
}
// Project DB and browser consumers without importing test code or Vitest (the
// planner runs before npm installation). Deferred literals participate; unreadable,
// unresolved and computed imports retain conservative prerequisite coverage.
function collectTestDependencies(entries, dependenciesFor) {
const pending = [...entries];
const seen = new Set();
let inconclusive = false;
try {
for (let index = 0; index < pending.length; index++) {
const file = pending[index];
if (seen.has(file)) continue;
seen.add(file);
if (!MODULE_SOURCE_RE.test(file)) continue;
const edges = dependenciesFor(file);
if (edges.inconclusive) inconclusive = true;
pending.push(...edges.dependencies);
}
} catch {
return null;
}
return inconclusive ? null : uniqueSorted([...seen]);
}
/**
* Collect the repository-derived inputs that surround the pure plan builder.
*
* CI leaves `changedFiles` unset and keeps deriving its diff from baseSha. A
* local caller may supply the complete committed + working-tree path list; in
* that mode files present but not yet tracked are plan inputs too, while paths
* deleted from the working tree are deliberately absent from trackedFiles.
*/
export function collectPlanInputs({ baseSha, forceFull = false, changedFiles, cwd = process.cwd() }) {
const hasChangedFilesOverride = changedFiles !== undefined;
const collectedChangedFiles = forceFull
? []
: hasChangedFilesOverride
? changedFiles
: gitPaths(['diff', '-z', '--name-only', '--diff-filter=ACMRD', `${baseSha}...HEAD`], cwd);
const trackedFiles = gitPaths(['ls-files', '-z'], cwd);
const presentFiles = hasChangedFilesOverride
? uniqueSorted([
...trackedFiles,
...collectedChangedFiles.filter((path) => existsSync(join(cwd, path))),
]).filter((path) => existsSync(join(cwd, path)))
: trackedFiles;
// Present, non-ignored untracked sources are real local imports: without them
// a tracked importer of a not-yet-staged module looks unresolved and the
// dependency walk fails closed to a full plan. Local override mode only —
// committed CI inputs stay tracked-only.
const untrackedFiles = hasChangedFilesOverride
? gitPaths(['ls-files', '-z', '--others', '--exclude-standard'], cwd).filter((path) => existsSync(join(cwd, path)))
: [];
let appDiff = null;
if (!forceFull && collectedChangedFiles.includes('client/src/App.jsx')) {
const committedDiff = execFileSync(
'git', ['diff', '--unified=0', `${baseSha}...HEAD`, '--', 'client/src/App.jsx'],
{ cwd, encoding: 'utf8' },
);
const workingTreeDiff = hasChangedFilesOverride
? execFileSync('git', ['diff', '--unified=0', 'HEAD', '--', 'client/src/App.jsx'], { cwd, encoding: 'utf8' })
: '';
appDiff = `${committedDiff}${workingTreeDiff}`;
}
// Every changed executable, non-test source — not only python scripts — gets
// a basename lookup: `git grep`-ing tracked test files for its filename finds
// the text-reading contract tests (mirror parity, navManifest.js's 20+ client
// reads) that no import edge or feature-directory match can reach. Basename
// matching is deliberate: a mirror test names the client copy only as e.g.
// 'canonPrompt.js', never by its full path. Under-selection is the bug this
// closes (issue #6363), but over-selection is not free: every hit is an
// explicit selector, and a broad selection fans the runner out across shards.
// A basename several tracked sources share (42 `index.js`) is narrowed by
// narrowSharedBasenameHits (#11870).
const changedSources = collectedChangedFiles.filter((path) => isExecutable(path) && !isTestFile(path));
const sharedBasenames = changedSources.length > 0 ? sharedSourceBasenames(presentFiles) : new Set();
const pathContractTests = Object.fromEntries(changedSources.map((path) => {
const hits = gitGrepFiles(sourceReferencePattern(path), TEST_FILE_GLOBS, cwd);
return [path, sharedBasenames.has(basenameOf(path)) ? narrowSharedBasenameHits(path, hits, cwd) : hits];
}));
const dependencyFiles = hasChangedFilesOverride ? uniqueSorted([...presentFiles, ...untrackedFiles]) : presentFiles;
const snapshot = createDependencySnapshot(dependencyFiles, cwd);
const clientDependencies = collectedChangedFiles.some((path) => path.startsWith('server/lib/')
&& isExecutable(path) && !isTestFile(path))
? collectClientDependencies(dependencyFiles, snapshot)
: [];
// Include test fixtures and literal deferred imports, unlike the production
// projection. Keep uncertainty per test so one unresolved/computed fixture
// retains its consumer without widening every resolved test.
const clientTestDependencies = collectedChangedFiles.some((path) => isSharedClientDependency(path)
&& isExecutable(path) && !isTestFile(path))
? Object.fromEntries(dependencyFiles.filter((path) => path.startsWith('client/src/')
&& isTestFile(path)).map((test) => [test,
collectTestDependencies([test], snapshot.testDependencies)?.filter(isSharedClientDependency) ?? null]))
: {};
const hasRelatedServerSource = collectedChangedFiles.some((path) => isServerRunnerFile(path)
&& MODULE_SOURCE_RE.test(path) && !isTestFile(path) && !isStructuralBarrel(path));
const dbDependencies = hasRelatedServerSource
? collectTestDependencies(resolveDbTestFiles(dependencyFiles), snapshot.testDependencies)
: [];
const browserDependencies = hasRelatedServerSource
? Object.fromEntries(browserSuitesIn(presentFiles).map((suite) => [suite,
collectTestDependencies([suite], snapshot.testDependencies)]))
: {};
// Each changed manifest at the diff base vs the tree under test (the working
// tree: HEAD in CI, HEAD plus local edits under pregate). The base commit is
// inside the depth-2 checkout, so `git show` resolves it; any read failure
// becomes null, which classifyDependencyChange() treats as escalation.
const readAtBase = (path) => {
try {
return execFileSync('git', ['show', `${baseSha}:${path}`], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024 });
} catch {
return null;
}
};
const readInTree = (path) => {
try {
return readFileSync(join(cwd, path), 'utf8');
} catch {
return null;
}
};
const dependencyChanges = Object.fromEntries(collectedChangedFiles
.filter((path) => DEPENDENCY_MANIFEST_RE.test(path))
.map((path) => [path, classifyDependencyChange(path, baseSha ? readAtBase(path) : null, readInTree(path))]));
// `vitest related` follows dynamic imports too; report that fan-out per
// changed server source so the selection size is attributable. A failed
// walk only loses the note.
let serverReach = null;
if (hasRelatedServerSource) {
try {
serverReach = measureRepoImportReach({
cwd,
files: dependencyFiles,
readText: snapshot.readText,
sources: collectedChangedFiles.filter((path) => isServerRunnerFile(path)
&& MODULE_SOURCE_RE.test(path) && !isTestFile(path)),
});
} catch (err) {
console.warn(`⚠️ Dynamic-aware reach not measured: ${err.message}`);
}
}
// A forced-full run always runs every gated job, so it skips the walks.
const promptHistoryInputs = forceFull ? null : collectPromptHistoryInputs(dependencyFiles, cwd);
const linuxContainmentInputs = forceFull ? null : collectLinuxContainmentInputs(cwd);
const supercolliderLiveInputs = forceFull ? null : collectSuperColliderLiveInputs(cwd);
const dockerContainmentLiveInputs = forceFull ? null : collectDockerContainmentLiveInputs(cwd);
return { changedFiles: collectedChangedFiles, trackedFiles: presentFiles, appDiff, pathContractTests,
clientDependencies, clientTestDependencies, dbDependencies, browserDependencies, dependencyChanges, promptHistoryInputs, linuxContainmentInputs, supercolliderLiveInputs,
dockerContainmentLiveInputs, serverReach };
}
// ---------------------------------------------------------------------------
// Pregate attestation (docs/GITHUB_ACTIONS.md "Pregate attestation")
//
// A local `npm run pregate` that ran a stage to green, followed by
// `node scripts/pregate-attest.js` after the push, leaves a `pregate` commit
// status on the head whose description names the validated TREE, the platform
// and Node major it ran on, and the stages that passed
// (scripts/lib/pregateAttestation.js). This section reads that status back
// and lets the plan skip those stages — never Windows, the Linux containment
// job, or the Node-minimum check, which have no local run.
//
// Fail closed at every step: anything other than a same-repository pull
// request into a non-release base, with a head commit the owner attested
// whose tree is exactly the head commit's tree, leaves the plan untouched and
// the reason in the outputs. The planner never has to be right about a fork
// or a bot for this to be safe — a fork's token cannot create a status here
// and a bot's login is not the owner's — but it refuses them explicitly so
// the summary says why.
//
// What the receipt vouches for is the HEAD COMMIT's tree; what CI tests is
// the merge ref, that tree plus whatever the base branch gained since the
// branch forked. `attestationDrift` closes that gap per stage: a base-side
// change that could reach a stage's runner refuses the attestation for that
// stage, and docs-only or other-runner movement keeps it.
// ---------------------------------------------------------------------------
/** Stages a receipt may attest to, mapped to the plan fields they clear. */
const ATTESTATION_SKIPS = Object.freeze({
lint: (plan) => ({ lint: { ...plan.lint, mode: 'skip' } }),
client: (plan) => ({ client: { ...plan.client, mode: 'skip' } }),
build: () => ({ build: false }),
smoke: () => ({ smoke: false }),
browser: () => ({ browserFiles: [] }),
db: () => ({ db: false }),
'prompt-history': () => ({ promptHistory: false }),
});
/**
* Whether this run may honor an attestation at all, and the head it would
* read it from. Reads only the `CI_*` inputs ci.yml passes to the plan step.
*
* @param {NodeJS.ProcessEnv} env
* @returns {{eligible: boolean, reason: string, headSha?: string, repository?: string, owner?: string}}
*/
export function attestationEligibility(env) {
const trim = (value) => (typeof value === 'string' ? value.trim() : '');
const eventName = trim(env.CI_EVENT_NAME);
const repository = trim(env.CI_REPOSITORY);
const owner = trim(env.CI_REPOSITORY_OWNER);
const headRepo = trim(env.CI_PR_HEAD_REPO);
const headSha = trim(env.CI_PR_HEAD_SHA);
const author = trim(env.CI_PR_AUTHOR);
if (eventName !== 'pull_request') return { eligible: false, reason: `event ${eventName || '(none)'} is not a pull request` };
if (env.CI_FORCE_FULL === 'true') return { eligible: false, reason: 'full CI requested' };
if (trim(env.CI_BASE_REF) === 'release') return { eligible: false, reason: 'release gate: pull request into release' };
if (!repository || !owner) return { eligible: false, reason: 'repository or owner unknown' };
if (headRepo.toLowerCase() !== repository.toLowerCase()) return { eligible: false, reason: `head repository ${headRepo || '(unknown)'} is not ${repository}` };
if (!author || /\[bot\]$/i.test(author)) return { eligible: false, reason: `pull request author ${author || '(unknown)'} is a bot or unknown` };
if (!/^[0-9a-f]{40}$/.test(headSha)) return { eligible: false, reason: 'head sha unknown' };
return { eligible: true, reason: 'same-repository pull request', headSha, repository, owner };
}
const isRunnerConfig = (path) => FULL_TRIGGER_RULES.some((rule) => rule.re.test(path)) || WORKSPACE_CACHE_COMMON_INPUTS.has(path);
const isSourceUnder = (path, prefixes) => isExecutable(path) && !isTestFile(path) && !isDocumentationOnly(path)
&& prefixes.some((prefix) => path.startsWith(prefix));
// A full-mode runner selects every test it owns, so `files` is empty there and
// the membership check alone would let a base-side test change slip through.
const selectsTest = (selection, runner, path) => selection.files.includes(path) || (selection.mode === 'full' && runnerForTest(path) === runner);
/**
* Per stage, whether a base-side path could change that stage's outcome:
* (a) a test file the plan selected for the runner, (b) a non-test source
* under the runner's roots, or (c) a runner config or setup file. Each entry
* is the first offending path, for the refusal reason.
*/
const STAGE_DRIFT_RULES = Object.freeze({
server: (plan, path) => selectsTest(plan.server, 'server', path) || isSourceUnder(path, RUNNER_ROOTS.server) || WORKSPACE_CACHE_SERVER_INPUTS.has(path),
client: (plan, path) => selectsTest(plan.client, 'client', path) || isSourceUnder(path, RUNNER_ROOTS.client) || WORKSPACE_CACHE_CLIENT_INPUTS.has(path),
lint: (plan, path) => isLintSurface(path),
build: (plan, path) => isSourceUnder(path, ['client/']) || WORKSPACE_CACHE_CLIENT_INPUTS.has(path),
smoke: (plan, path) => isSourceUnder(path, ['server/']) || path === 'scripts/smoke-boot.js' || WORKSPACE_CACHE_SERVER_INPUTS.has(path),
browser: (plan, path) => plan.browserFiles.includes(path) || BROWSER_SUITES.includes(path)
|| isSourceUnder(path, ['server/', 'client/src/']) || WORKSPACE_CACHE_SERVER_INPUTS.has(path) || WORKSPACE_CACHE_CLIENT_INPUTS.has(path),
db: (plan, path) => resolveDbTestFiles([path]).length > 0 || isSourceUnder(path, ['server/']) || WORKSPACE_CACHE_SERVER_INPUTS.has(path),
'prompt-history': (plan, path) => PROMPT_HISTORY_PATH_RE.test(path),
});
/**
* The stages a base-side diff refuses, each with the path that refuses it.
*
* `driftPaths` is `git diff --name-only HEAD^2 HEAD` on the merge ref: exactly
* what the base branch added since the branch forked. A runner config or
* workflow change refuses every stage; otherwise each stage answers for its
* own runner. Null (the diff could not be read) refuses everything.
*
* @param {object} plan - the finished plan
* @param {string[]|null} driftPaths
* @returns {Record<string, string>} stage → reason
*/
export function attestationDrift(plan, driftPaths) {
const refused = {};
if (!Array.isArray(driftPaths)) {
for (const stage of Object.keys(STAGE_DRIFT_RULES)) refused[stage] = 'base movement could not be read';
return refused;
}
const paths = uniqueSorted(driftPaths.filter((path) => typeof path === 'string' && path.length > 0));
const config = paths.find(isRunnerConfig);
for (const [stage, touches] of Object.entries(STAGE_DRIFT_RULES)) {
const hit = config ?? paths.find((path) => touches(plan, path));
if (hit) refused[stage] = `base branch moved: ${hit}`;
}
return refused;
}
/**
* The attestation on the pull request's head, or null and why.
*
* The checkout is the merge ref at depth 2, which carries the head commit as
* `HEAD^2`: that is what makes `<head>^{tree}` resolvable without a wider
* fetch, and the first check — the event's head must BE that second parent,
* or the attested tree would be compared with some other commit's. It is NOT
* the tree under test: the merge ref also carries the base branch's movement,
* which `attestationDrift` weighs per stage in applyAttestation from the
* `baseDrift` returned here.
*
* Focused local validation intentionally posts no attestation. Read once; a
* missing or late receipt leaves broad hosted checks enabled immediately.
*
* `log` defaults to stderr: the planner's stdout is the JSON plan pregate
* and the tests parse, so every human-readable line here stays off it.
*
* @param {{env?: NodeJS.ProcessEnv, exec?: typeof execFileSync, cwd?: string, log?: (line: string) => void}} [options]
* @returns {{attested: boolean, reason: string, sha?: string, tree?: string, os?: string, node?: number, stages?: string[], creator?: string, createdAt?: string, baseDrift?: string[]|null, waitedMs?: number}}
*/
export function resolveCiAttestation({ env = process.env, exec = execFileSync, cwd = process.cwd(), log = console.warn } = {}) {
const none = (reason) => {
log(`⏭️ Pregate attestation not honored: ${reason}.`);
return { attested: false, reason };
};
const eligibility = attestationEligibility(env);
if (!eligibility.eligible) return none(eligibility.reason);
const { headSha, repository, owner } = eligibility;
const capture = (command, args) => {
try {
return exec(command, args, { cwd, encoding: 'utf8', env, stdio: ['ignore', 'pipe', 'pipe'] }).trim();
} catch (error) {
return { error: error?.stderr?.toString().trim() || error?.message || 'command failed' };
}
};
const mergeHead = capture('git', ['rev-parse', '--verify', '--quiet', 'HEAD^2']);
if (typeof mergeHead !== 'string' || mergeHead !== headSha) {
return none(`checkout is not the merge ref of head ${headSha.slice(0, 9)}`);
}
const headTree = capture('git', ['rev-parse', '--verify', '--quiet', `${headSha}^{tree}`]);
if (typeof headTree !== 'string') return none(`cannot resolve the tree of head ${headSha.slice(0, 9)}`);
const readStatuses = () => {
const body = capture('gh', ['api', `repos/${repository}/commits/${headSha}/statuses?per_page=100`]);
if (typeof body !== 'string') return { error: `statuses API failed: ${body.error}` };
try {
return { statuses: JSON.parse(body) };
} catch {
return { error: 'statuses API returned unreadable JSON' };
}
};
const read = readStatuses();
if (read.error) return none(read.error);
const selected = selectAttestation(read.statuses, { owner, headTree });
if (!selected.attestation) return none(selected.reason);
const drift = capture('git', ['diff', '--name-only', 'HEAD^2', 'HEAD']);
const baseDrift = typeof drift === 'string' ? drift.split('\n').filter(Boolean) : null;
const { attestation, reason } = selected;
log(`✅ Pregate attestation on ${headSha.slice(0, 9)} (tree ${attestation.tree.slice(0, 12)}): ${attestation.stages.join(', ')} — ${reason}; base moved by ${baseDrift ? `${baseDrift.length} file(s)` : 'an unreadable diff'}.`);
return { attested: true, reason, sha: headSha, ...attestation, baseDrift, waitedMs: 0 };
}
/**
* The plan with every attested stage skipped and the decision recorded.
*
* Stages the base-side drift refuses (`attestationDrift`) stay as planned and
* say why. The server job owns the boot smoke (`smoke == 'true' &&
* matrix.shard == 1` on a job gated by `server_mode != 'skip'`), so `server`
* is skipped only when the smoke is attested too or was never selected;
* otherwise skipping the job would drop an unattested smoke on the floor.
* `full` is forced false so the `Full CI Gate` is never published for a run
* that skipped anything on the strength of a local receipt. Windows, Linux
* containment, the Node-minimum check and the shard matrices are left as the
* plan computed them.
*
* @param {object} plan - a finished plan (buildCiTestPlan)
* @param {{attested: boolean, reason: string, stages?: string[], sha?: string, tree?: string, os?: string, node?: number, creator?: string, createdAt?: string, baseDrift?: string[]|null}} attestation
*/
export function applyAttestation(plan, attestation) {
const base = { ...plan, attestation, attestedStages: [] };
if (!attestation?.attested) {
return { ...base, suiteReasons: { ...plan.suiteReasons, attestation: `not honored: ${attestation?.reason ?? 'unknown'}` } };
}
const refused = attestationDrift(plan, attestation.baseDrift ?? null);
const attested = new Set((attestation.stages ?? []).filter((stage) => !refused[stage]));
const smokeCovered = attested.has('smoke') || !plan.smoke;
const skips = { ...ATTESTATION_SKIPS, server: smokeCovered ? (current) => ({ server: { ...current.server, mode: 'skip' } }) : null };
let next = base;
const skipped = [];
for (const stage of ATTESTABLE_STAGES) {
if (!attested.has(stage) || !skips[stage]) continue;
next = { ...next, ...skips[stage](next) };
skipped.push(stage);
}
const label = `attested by pregate on ${String(attestation.sha ?? '').slice(0, 9)} (tree ${String(attestation.tree ?? '').slice(0, 12)}, ${attestation.os ?? '?'}/node ${attestation.node ?? '?'})`;
const driftRefused = Object.fromEntries((attestation.stages ?? []).filter((stage) => refused[stage]).map((stage) => [stage, refused[stage]]));
const suiteReasons = { ...plan.suiteReasons, attestation: `${label}: skipping ${skipped.join(', ') || 'nothing'}` };
const reasonKey = (stage) => (stage === 'prompt-history' ? 'promptHistory' : stage);
for (const stage of skipped) suiteReasons[reasonKey(stage)] = `skipped: ${label}`;
for (const [stage, reason] of Object.entries(driftRefused)) {
if (stage !== 'scan') suiteReasons[reasonKey(stage)] = `${plan.suiteReasons[reasonKey(stage)] ?? 'planned'}; attestation refused: ${reason}`;
}
if (attested.has('server') && !smokeCovered) {
suiteReasons.server = `${plan.suiteReasons.server}; server job kept: the boot smoke was not attested`;
}
return { ...next, full: false, attestedStages: skipped, attestation: { ...attestation, driftRefused }, suiteReasons };
}
function main() {
const forceFullReason = forceFullReasonFor({
forceFull: process.env.CI_FORCE_FULL === 'true',
baseRef: process.env.CI_BASE_REF,
});
const forceFull = Boolean(forceFullReason);
// scripts/ci-base-sha.js exports this from the checkout: on a pull request
// HEAD is the merge ref and CI_BASE_SHA is its first parent, so the
// three-dot diff below resolves against a commit git already has. That is
// what lets every job clone at depth 2 instead of full history.
const base = process.env.CI_BASE_SHA;
if (!forceFull && !base) {
throw new Error('CI_BASE_SHA is required unless the run is forced full (CI_FORCE_FULL=true or CI_BASE_REF=release).');
}
const changedFilesOverride = process.env.CI_CHANGED_FILES === undefined
? undefined
: JSON.parse(process.env.CI_CHANGED_FILES);
if (changedFilesOverride !== undefined
&& (!Array.isArray(changedFilesOverride) || changedFilesOverride.some((path) => typeof path !== 'string'))) {
throw new Error('CI_CHANGED_FILES must be a JSON array of repository-relative path strings.');
}
const {
changedFiles, trackedFiles, appDiff, pathContractTests, clientDependencies, clientTestDependencies, dbDependencies, browserDependencies,
dependencyChanges, promptHistoryInputs, linuxContainmentInputs, supercolliderLiveInputs, dockerContainmentLiveInputs, serverReach,
} = collectPlanInputs({
baseSha: base,
forceFull,
changedFiles: changedFilesOverride,
});
const plan = buildCiTestPlan(changedFiles, {
trackedFiles,
forceFull,
forceFullReason,
appRouteOnly: isRouteOnlyAppDiff(appDiff),
pathContractTests,
clientDependencies,
clientTestDependencies,
dbDependencies,
browserDependencies,
dependencyChanges,
promptHistoryInputs,
linuxContainmentInputs,
supercolliderLiveInputs,
dockerContainmentLiveInputs,
serverReach,
});
// Last, over the finished plan: the attestation only ever removes work.
emitGitHubPlan(applyAttestation(plan, resolveCiAttestation()));
}
if (isDirectlyInvoked(import.meta.url)) main();