Skip to content

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

ci: escalate Windows on a lockfile change only when a platform-sensitive package moved

[._.]/ Adam Eivy1f55b91151f3
diff --git a/docs/GITHUB_ACTIONS.md b/docs/GITHUB_ACTIONS.md
index bf3ff57c42..4c0b104d54 100644
--- a/docs/GITHUB_ACTIONS.md
+++ b/docs/GITHUB_ACTIONS.md
@@ -617,7 +617,7 @@ reason `windows-server` cannot observe:
| targeted test set exceeded safety cap (no longer full; see "Full-suite sharding") | 17 | no — capacity, not risk |
| wide change (>30 executable files) | 6 | no — capacity, not risk |
| client composition root / build config / lint config / test setup | 1 | no — client-only |
-| dependency manifest, server contract, CI pipeline script, workflow, … | 40 | yes |
+| dependency manifest, server contract, CI pipeline script, workflow, … | 40 | yes at the time — manifests and server contracts are now narrowed (below) |
So each full trigger in `FULL_TRIGGER_RULES` carries a `windowsEscalates` flag,
and `fullPlan()` escalates Windows to the complete server suite only when **any**
@@ -629,6 +629,42 @@ edits `App.jsx` *and* bumps a lockfile escalates. Otherwise the job drops to **o
`WINDOWS_CONTRACT_TESTS`** — reduced, never skipped, and exactly the depth a
Windows-risk scoped PR already gets.
+**Dependency manifests decide per package.** The planner's 32-PR sample in
+October 2026 traced every full plan to a lockfile/manifest change (4),
+`server/lib/validation.js` (2) or `.github/workflows/ci.yml` (2). A lockfile
+bump that swapped one pure-JS Gmail client still ran the whole suite on three
+Windows shards (~11 min each), although nothing it installs differs by
+platform. A changed `package.json`/`package-lock.json` (root, `server`,
+`client`, `autofixer`) therefore still forces a full plan, but its trigger
+carries `windowsEscalates: 'dependencies'`: `collectPlanInputs()` reads each
+file at `CI_BASE_SHA` (`git show`; the base is inside the depth-2 checkout)
+and in the tree under test, and `classifyDependencyChange()` diffs them.
+Windows escalates when any added, removed or changed lockfile entry (either
+side) has `hasInstallScript`, `os`, `cpu`, `libc`, `optional` or
+`devOptional`, or matches `PLATFORM_PACKAGE_RES` — every `TRUSTED_REBUILDS`
+package (mirrored rather than imported, so the pre-install planner does not
+load the rebuild script's spawn helpers; a test fails on drift) plus the
+native/platform families (`sharp`,
+`@img/*`, `esbuild`, `@rollup/rollup-*`, `rolldown`, `@biomejs/*`,
+`playwright*`, …: dispatchers whose own entry carries no platform
+metadata); when the lockfile's top-level fields or its root entry's non-dependency
+fields (`engines`) change; when a `package.json` field other than metadata
+and the dependency maps changes (`engines`, `overrides`,
+`optionalDependencies`, `scripts`, …); and whenever a version cannot be read
+or parsed (fail closed: a new or deleted manifest, an unavailable base, or no
+verdict at all). Any `.npmrc` change escalates on its own trigger. Otherwise
+Windows runs the contract baseline, and `suite_reasons.windows` names the
+decision and the packages behind it. Replayed against recent server bumps:
+zod, express, undici and the Gmail swap keep the baseline; playwright-core
+and Vitest (rolldown bindings) escalate.
+
+`server/lib/validation.js` and `server/lib/schemaVersions.js` stay full-plan
+triggers for their import fan-out but no longer escalate Windows: they are pure
+schema logic with no spawn, path or filesystem semantics, and neither is in
+`WINDOWS_RISK_RULES`. `Full CI Gate` still requires `windows_mode == 'full'`,
+so none of these baseline plans can stand in for the complete Windows suite a
+release relies on.
+
**Measured full trigger: `server/services/worktreeManager.js` (#9999).** A
two-file change to this module expanded through Vitest's import-consumer
traversal to 57 explicit selectors and a ~941-file, ~40-minute local run
diff --git a/scripts/ci-test-plan.js b/scripts/ci-test-plan.js
index 9f2e7c19c8..552cb93ca4 100644
--- a/scripts/ci-test-plan.js
+++ b/scripts/ci-test-plan.js
@@ -91,6 +91,118 @@ const fansOut = (runner, { mode, files }, excludedFiles) => {
return files.length > MAX_TARGETED_TEST_FILES || (runner === 'server' && mode === 'related');
};
+const DEPENDENCY_MANIFEST_RE = /^(?:package|server\/package|client\/package|autofixer\/package)(?:-lock)?\.json$/;
+
+// 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
@@ -101,11 +213,20 @@ const fansOut = (runner, { mode, files }, excludedFiles) => {
// 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 = [
// Defines the windows-server job itself.
{ re: /^\.github\/workflows\//, reason: 'workflow definition changed', windowsEscalates: true },
- // Native rebuilds and platform-conditional resolution differ on Windows.
- { re: /^(?:package|server\/package|client\/package|autofixer\/package)(?:-lock)?\.json$/, reason: 'dependency manifest changed', windowsEscalates: true },
+ { 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 },
@@ -119,7 +240,9 @@ const FULL_TRIGGER_RULES = [
// 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 },
- { re: /^server\/lib\/(?:schemaVersions|validation)\.js$/, reason: 'shared server contract 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.
@@ -725,12 +848,13 @@ const suiteReasonsFor = (plan, { appRouteOnly = false } = {}) => ({
// 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'
+ ? `${plan.windowsMode === 'full'
? `full matrix: ${plan.reason}`
- : `Windows contract baseline (full matrix elsewhere): ${plan.reason}`)
+ : `Windows contract baseline (full matrix elsewhere): ${plan.reason}`}${plan.windowsNote ? `; ${plan.windowsNote}` : ''}`
: 'Windows-sensitive surface changed',
});
@@ -758,6 +882,9 @@ export function buildCiTestPlan(changedFiles, {
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);
@@ -780,12 +907,19 @@ export function buildCiTestPlan(changedFiles, {
// (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 }) => ({ path, reason, windowsEscalates })));
+ .map(({ reason, windowsEscalates }) => {
+ if (windowsEscalates !== 'dependencies') 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) {
@@ -795,6 +929,7 @@ export function buildCiTestPlan(changedFiles, {
appRouteOnly,
trackedSet,
windowsEscalates: triggersEscalateWindows,
+ windowsNote,
});
}
@@ -803,6 +938,7 @@ export function buildCiTestPlan(changedFiles, {
appRouteOnly,
trackedSet,
windowsEscalates: triggersEscalateWindows,
+ windowsNote,
});
}
@@ -1034,9 +1170,10 @@ const finishPlan = (plan, { linuxRunnerExcludes = new Set(), ...options } = {})
*
* `windowsEscalates` (default true, so an unlisted caller fails closed) is
* false only for a trigger windows-server cannot observe: a client-only
- * surface, 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.
+ * 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.
@@ -1047,7 +1184,7 @@ const finishPlan = (plan, { linuxRunnerExcludes = new Set(), ...options } = {})
* `options` is also forwarded to finishPlan(), which reads only appRouteOnly.
*/
function fullPlan(changedFiles, reason, options = {}) {
- const { trackedSet = new Set(), windowsEscalates = true } = 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;
@@ -1069,6 +1206,7 @@ function fullPlan(changedFiles, reason, options = {}) {
windowsMode: windowsFull ? 'full' : 'files',
windowsFiles: windowsFull ? [] : baseline,
windowsSources: [],
+ windowsNote,
}, options);
}
@@ -1325,8 +1463,30 @@ export function collectPlanInputs({ baseSha, forceFull = false, changedFiles, cw
collectTestDependencies([suite], dependencyFiles, cwd, importCache)]))
: {};
+ // 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))]));
+
return { changedFiles: collectedChangedFiles, trackedFiles: presentFiles, appDiff, pathContractTests,
- clientDependencies, dbDependencies, browserDependencies };
+ clientDependencies, dbDependencies, browserDependencies, dependencyChanges };
}
function main() {
@@ -1350,7 +1510,7 @@ function main() {
&& (!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, dbDependencies, browserDependencies } = collectPlanInputs({
+ const { changedFiles, trackedFiles, appDiff, pathContractTests, clientDependencies, dbDependencies, browserDependencies, dependencyChanges } = collectPlanInputs({
baseSha: base,
forceFull,
changedFiles: changedFilesOverride,
@@ -1364,6 +1524,7 @@ function main() {
clientDependencies,
dbDependencies,
browserDependencies,
+ dependencyChanges,
}));
}
diff --git a/scripts/ci-test-plan.test.js b/scripts/ci-test-plan.test.js
index 137edc7dfc..27397672e1 100644
--- a/scripts/ci-test-plan.test.js
+++ b/scripts/ci-test-plan.test.js
@@ -6,17 +6,20 @@ import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { resolveDbTestFiles } from './lib/dbTestFiles.js';
import { staticImportClosure } from '../server/lib/staticImportGraph.js';
+import { TRUSTED_REBUILDS } from './trusted-rebuilds.js';
import {
ALWAYS_RUN_TESTS,
BROWSER_SUITES,
buildCiTestPlan,
+ classifyDependencyChange,
collectPlanInputs,
forceFullReasonFor,
FULL_SUITE_SHARDS,
isRouteOnlyAppDiff,
MAX_TARGETED_TEST_FILES,
needsSlashdoSubmodule,
+ PLATFORM_PACKAGE_RES,
shardIndexes,
SLASHDO_GITLINK_PATH,
sourceReferencePattern,
@@ -1481,7 +1484,8 @@ describe('Windows escalation on a full plan (#7440)', () => {
// touches server/index.js downgrades Windows on a diff that must escalate.
expect(plan(['client/src/App.jsx']).windowsMode).toBe('files');
- for (const escalating of ['server/index.js', 'package-lock.json', 'server/lib/validation.js']) {
+ // package-lock.json carries no manifest comparison here, so it fails closed.
+ for (const escalating of ['server/index.js', 'package-lock.json', '.npmrc']) {
const combined = plan(['client/src/App.jsx', escalating]);
expect(combined.reason, escalating).toContain('client composition root changed');
expect(combined.windowsMode, escalating).toBe('full');
@@ -1729,3 +1733,139 @@ describe('cross-workspace browser suites (#10312)', () => {
expect(plan.browserFiles).toEqual([BROWSER_SUITES[0]]);
});
});
+
+describe('dependency manifest Windows escalation', () => {
+ const TRACKED_WITH_CONTRACTS = [...TRACKED, ...WINDOWS_CONTRACT_TESTS];
+ const LOCK = 'server/package-lock.json';
+ const lockfile = (packages, root = {}) => JSON.stringify({
+ name: 'portos-server',
+ version: '1.0.0',
+ lockfileVersion: 3,
+ requires: true,
+ packages: { '': { name: 'portos-server', version: '1.0.0', ...root }, ...packages },
+ });
+ const BASE_PACKAGES = {
+ 'node_modules/@googleapis/gmail': { version: '16.1.1', resolved: 'https://registry.example.com/g-16.1.1.tgz' },
+ 'node_modules/node-pty': { version: '1.2.0', hasInstallScript: true },
+ };
+ const BASE = lockfile(BASE_PACKAGES);
+ const planFor = (files, dependencyChanges) => buildCiTestPlan(files, {
+ trackedFiles: TRACKED_WITH_CONTRACTS,
+ dependencyChanges,
+ });
+ const lockPlan = (headText, baseText = BASE) => planFor([LOCK], { [LOCK]: classifyDependencyChange(LOCK, baseText, headText) });
+
+ it('keeps a pure-JS version bump on the Windows contract baseline and names the package', () => {
+ const plan = lockPlan(lockfile({
+ ...BASE_PACKAGES,
+ 'node_modules/@googleapis/gmail': { version: '17.0.0', resolved: 'https://registry.example.com/g-17.0.0.tgz' },
+ }));
+
+ // The Linux side stays complete; only Windows narrows.
+ expect(plan.full).toBe(true);
+ expect(plan.server.mode).toBe('full');
+ expect(plan.windowsMode).toBe('files');
+ expect(plan.windowsFiles).toEqual(WINDOWS_CONTRACT_TESTS);
+ expect(plan.shards.windows).toEqual([1]);
+ expect(plan.suiteReasons.windows).toContain('Windows contract baseline');
+ expect(plan.suiteReasons.windows).toContain('@googleapis/gmail');
+ });
+
+ it('escalates Windows for a native, install-script, platform-gated or optional package', () => {
+ const cases = {
+ 'install script': { 'node_modules/fresh-addon': { version: '1.0.0', hasInstallScript: true } },
+ 'os field': { 'node_modules/@scope/binding-win32-x64': { version: '1.0.0', os: ['win32'], cpu: ['x64'] } },
+ optional: { 'node_modules/maybe-native': { version: '1.0.0', optional: true } },
+ // Removing a trusted rebuild escalates too: either side of the diff counts.
+ 'trusted rebuild removed': { 'node_modules/node-pty': undefined },
+ // sharp's entry carries no platform metadata; the family list catches it.
+ 'platform family': { 'node_modules/sharp': { version: '0.35.6' } },
+ };
+ for (const [label, change] of Object.entries(cases)) {
+ const packages = Object.fromEntries(Object.entries({ ...BASE_PACKAGES, ...change })
+ .filter(([, entry]) => entry !== undefined));
+ const plan = lockPlan(lockfile(packages));
+ expect(plan.full, label).toBe(true);
+ expect(plan.windowsMode, label).toBe('full');
+ expect(plan.shards.windows, label).toEqual(shardIndexes('full', FULL_SUITE_SHARDS.windows));
+ expect(plan.suiteReasons.windows, label).toContain('escalates Windows: platform-sensitive package changed');
+ }
+ });
+
+ it('treats every trusted-rebuild package as platform-sensitive', () => {
+ // The planner mirrors the allowlist instead of importing it (see
+ // PLATFORM_PACKAGE_RES); this keeps the two from drifting.
+ const trusted = Object.values(TRUSTED_REBUILDS).flatMap((groups) => groups.flatMap(({ pkgs }) => pkgs));
+ expect(trusted.length).toBeGreaterThan(0);
+ expect(trusted.filter((name) => !PLATFORM_PACKAGE_RES.some((re) => re.test(name)))).toEqual([]);
+ });
+
+ it('fails closed when the lockfile cannot be compared', () => {
+ for (const [label, baseText, headText] of [
+ ['unparsable head', BASE, '{ "packages": '],
+ ['missing base', null, BASE],
+ ['deleted head', BASE, null],
+ ['no packages map', JSON.stringify({ lockfileVersion: 1 }), BASE],
+ ]) {
+ expect(classifyDependencyChange(LOCK, baseText, headText).escalate, label).toBe(true);
+ expect(lockPlan(headText, baseText).windowsMode, label).toBe('full');
+ }
+ // No verdict at all — a caller that skipped the comparison — escalates too.
+ expect(planFor([LOCK], {}).windowsMode).toBe('full');
+ });
+
+ it('escalates Windows for engines, overrides and npm configuration changes', () => {
+ const manifest = { name: 'portos-server', dependencies: { express: '^5.2.1' }, engines: { node: '>=24.14' } };
+ const verdict = (head) => classifyDependencyChange('server/package.json', JSON.stringify(manifest), JSON.stringify(head));
+
+ expect(verdict({ ...manifest, dependencies: { express: '^5.3.0' } })).toMatchObject({ escalate: false, packages: ['express'] });
+ expect(verdict({ ...manifest, engines: { node: '>=26' } }).escalate).toBe(true);
+ expect(verdict({ ...manifest, overrides: { braces: '3.0.3' } }).escalate).toBe(true);
+ expect(verdict({ ...manifest, dependencies: { ...manifest.dependencies, 'node-pty': '^1.2.0' } }).escalate).toBe(true);
+ // The lockfile mirrors engines into its root entry.
+ expect(classifyDependencyChange(LOCK, BASE, lockfile(BASE_PACKAGES, { engines: { node: '>=26' } })).escalate).toBe(true);
+
+ for (const npmrc of ['.npmrc', 'server/.npmrc']) {
+ const plan = planFor([npmrc], {});
+ expect(plan.full, npmrc).toBe(true);
+ expect(plan.reason, npmrc).toContain('npm configuration changed');
+ expect(plan.windowsMode, npmrc).toBe('full');
+ }
+ });
+
+ it('runs the shared server contracts as a full plan on the Windows baseline', () => {
+ for (const path of ['server/lib/validation.js', 'server/lib/schemaVersions.js']) {
+ const plan = planFor([path], {});
+ expect(plan.full, path).toBe(true);
+ expect(plan.server.mode, path).toBe('full');
+ // ci.yml publishes Full CI Gate only for windows_mode 'full' (pinned in
+ // ci-base-sha.test.js), so this plan cannot vouch for Windows coverage.
+ expect(plan.windowsMode, path).toBe('files');
+ expect(plan.windowsFiles, path).toEqual(WINDOWS_CONTRACT_TESTS);
+ }
+ });
+
+ it('compares the manifest at the real diff base through git', () => {
+ const root = mkdtempSync(join(tmpdir(), 'portos-ci-lockfile-'));
+ const git = (...args) => execFileSync('git', ['-c', 'user.name=CI', '-c', '[email protected]',
+ '-c', 'commit.gpgsign=false', ...args], { cwd: root, encoding: 'utf8' }).trim();
+ try {
+ git('init', '-q');
+ mkdirSync(join(root, 'server'));
+ writeFileSync(join(root, LOCK), BASE);
+ git('add', '--all');
+ git('commit', '-q', '--no-verify', '-m', 'base');
+ const bumped = lockfile({ ...BASE_PACKAGES, 'node_modules/@googleapis/gmail': { version: '17.0.0' } });
+ writeFileSync(join(root, LOCK), bumped);
+
+ const inputs = collectPlanInputs({ baseSha: 'HEAD', changedFiles: [LOCK], cwd: root });
+ expect(inputs.dependencyChanges[LOCK]).toMatchObject({ escalate: false, packages: ['@googleapis/gmail'] });
+
+ // A base commit that does not exist in the checkout fails closed.
+ const missing = collectPlanInputs({ baseSha: '0'.repeat(40), changedFiles: [LOCK], cwd: root });
+ expect(missing.dependencyChanges[LOCK]).toMatchObject({ escalate: true, reason: 'base version unavailable' });
+ } finally {
+ rmSync(root, { recursive: true, force: true });
+ }
+ });
+});