@visulima/task-runner 1.0.0-alpha.7 → 1.0.0-alpha.9

package/dist/packem_shared/containsBlob-CwGB0a_q.js

@@ -0,0 +1,125 @@
+import { createRequire as __cjs_createRequire } from "node:module";
+
+const __cjs_require = __cjs_createRequire(import.meta.url);
+
+const __cjs_getProcess = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" ? globalThis.process : process;
+
+const __cjs_getBuiltinModule = (module) => {
+    // Check if we're in Node.js and version supports getBuiltinModule
+    if (typeof __cjs_getProcess !== "undefined" && __cjs_getProcess.versions && __cjs_getProcess.versions.node) {
+        const [major, minor] = __cjs_getProcess.versions.node.split(".").map(Number);
+        // Node.js 20.16.0+ and 22.3.0+
+        if (major > 22 || (major === 22 && minor >= 3) || (major === 20 && minor >= 16)) {
+            return __cjs_getProcess.getBuiltinModule(module);
+        }
+    }
+    // Fallback to createRequire
+    return __cjs_require(module);
+};
+
+const {
+  createReadStream,
+  createWriteStream
+} = __cjs_getBuiltinModule("node:fs");
+const {
+  stat,
+  mkdir,
+  writeFile,
+  rename,
+  rm,
+  utimes
+} = __cjs_getBuiltinModule("node:fs/promises");
+const {
+  pipeline
+} = __cjs_getBuiltinModule("node:stream/promises");
+import { dirname } from '@visulima/path';
+import { u as uniqueId } from './utils-Bmnj-H2J.js';
+import { digestFile } from './digestBuffer-CPdI2E1d.js';
+import { casBlobPath, tmpDirectory } from './V2_ROOT-DKBLxKo4.js';
+
+const containsBlob = async (root, digest) => {
+  try {
+    const stats = await stat(casBlobPath(root, digest.hash));
+    return stats.isFile() && stats.size === digest.sizeBytes;
+  } catch {
+    return false;
+  }
+};
+const putBlobFromFile = async (root, digest, sourcePath) => {
+  const finalPath = casBlobPath(root, digest.hash);
+  if (await containsBlob(root, digest)) {
+    await touchBlob(root, digest).catch(() => {
+    });
+    return;
+  }
+  const stagingPath = await stageBlob(root, sourcePath);
+  try {
+    await mkdir(dirname(finalPath), { recursive: true });
+    await rename(stagingPath, finalPath);
+  } catch (error) {
+    await rm(stagingPath, { force: true }).catch(() => {
+    });
+    if (!isAlreadyExistsError(error)) {
+      throw error;
+    }
+  }
+};
+const putBlobFromBytes = async (root, digest, bytes) => {
+  const finalPath = casBlobPath(root, digest.hash);
+  if (await containsBlob(root, digest)) {
+    await touchBlob(root, digest).catch(() => {
+    });
+    return;
+  }
+  const tmpDirectoryPath = tmpDirectory(root);
+  const stagingPath = `${tmpDirectoryPath}/${uniqueId()}`;
+  await mkdir(tmpDirectoryPath, { recursive: true });
+  await writeFile(stagingPath, bytes);
+  try {
+    await mkdir(dirname(finalPath), { recursive: true });
+    await rename(stagingPath, finalPath);
+  } catch (error) {
+    await rm(stagingPath, { force: true }).catch(() => {
+    });
+    if (!isAlreadyExistsError(error)) {
+      throw error;
+    }
+  }
+};
+const fetchBlobToFile = async (root, digest, destinationPath) => {
+  const sourcePath = casBlobPath(root, digest.hash);
+  try {
+    await stat(sourcePath);
+  } catch {
+    return false;
+  }
+  await mkdir(dirname(destinationPath), { recursive: true });
+  await pipeline(createReadStream(sourcePath), createWriteStream(destinationPath));
+  await touchBlob(root, digest).catch(() => {
+  });
+  return true;
+};
+const verifyBlob = async (filePath, expected) => {
+  const computed = await digestFile(filePath);
+  return computed?.hash === expected.hash && computed.sizeBytes === expected.sizeBytes;
+};
+const touchBlob = async (root, digest) => {
+  const now = /* @__PURE__ */ new Date();
+  await utimes(casBlobPath(root, digest.hash), now, now);
+};
+const stageBlob = async (root, sourcePath) => {
+  const tmpDirectoryPath = tmpDirectory(root);
+  const stagingPath = `${tmpDirectoryPath}/${uniqueId()}`;
+  await mkdir(tmpDirectoryPath, { recursive: true });
+  await pipeline(createReadStream(sourcePath), createWriteStream(stagingPath));
+  return stagingPath;
+};
+const isAlreadyExistsError = (error) => {
+  if (typeof error !== "object" || error === null) {
+    return false;
+  }
+  const { code } = error;
+  return code === "EEXIST" || code === "ENOTEMPTY";
+};
+
+export { containsBlob, fetchBlobToFile, putBlobFromBytes, putBlobFromFile, touchBlob, verifyBlob };

package/dist/packem_shared/{createTaskGraph-B7nH0kY_.js → createTaskGraph-Bwl4hwAf.js}

@@ -16,6 +16,13 @@ const parseTaskId = (taskId) => {
     target: parts[1]
   };
 };
+const normalizeWarningPattern = (value) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  const list = typeof value === "string" ? [value] : value;
+  return list.length === 0 ? void 0 : list;
+};
 const getTaskOutputs = (projectName, targetName, workspace, targetDefaults) => {
   const project = workspace.projects[projectName];
   const targetConfig = project?.targets?.[targetName];
@@ -38,13 +45,20 @@ const getSameProjectTask = (projectName, targetName, overrides, workspace, targe
   };
   return [
     {
+      always: project.targets?.[targetName]?.always ?? targetDefaults?.[targetName]?.always,
       cache: project.targets?.[targetName]?.cache ?? targetDefaults?.[targetName]?.cache,
+      cacheOnWarning: project.targets?.[targetName]?.cacheOnWarning ?? targetDefaults?.[targetName]?.cacheOnWarning,
+      cacheRestore: project.targets?.[targetName]?.cacheRestore ?? targetDefaults?.[targetName]?.cacheRestore,
       id: getTaskId(target),
       outputs: getTaskOutputs(projectName, targetName, workspace, targetDefaults),
       overrides,
       parallelism: project.targets?.[targetName]?.parallelism ?? targetDefaults?.[targetName]?.parallelism,
       projectRoot: project.root,
-      target
+      target,
+      warningPattern: normalizeWarningPattern(
+        project.targets?.[targetName]?.warningPattern ?? targetDefaults?.[targetName]?.warningPattern
+      ),
+      when: project.targets?.[targetName]?.when ?? targetDefaults?.[targetName]?.when
     }
   ];
 };
@@ -63,13 +77,20 @@ const getDependencyProjectTasks = (projectName, targetName, overrides, workspace
         target: targetName
       };
       tasks.push({
+        always: depProject.targets?.[targetName]?.always ?? targetDefaults?.[targetName]?.always,
         cache: depProject.targets?.[targetName]?.cache ?? targetDefaults?.[targetName]?.cache,
+        cacheOnWarning: depProject.targets?.[targetName]?.cacheOnWarning ?? targetDefaults?.[targetName]?.cacheOnWarning,
+        cacheRestore: depProject.targets?.[targetName]?.cacheRestore ?? targetDefaults?.[targetName]?.cacheRestore,
         id: getTaskId(target),
         outputs: getTaskOutputs(dep.target, targetName, workspace, targetDefaults),
         overrides,
         parallelism: depProject.targets?.[targetName]?.parallelism ?? targetDefaults?.[targetName]?.parallelism,
         projectRoot: depProject.root,
-        target
+        target,
+        warningPattern: normalizeWarningPattern(
+          depProject.targets?.[targetName]?.warningPattern ?? targetDefaults?.[targetName]?.warningPattern
+        ),
+        when: depProject.targets?.[targetName]?.when ?? targetDefaults?.[targetName]?.when
       });
     }
   }

package/dist/packem_shared/{defaultTaskRunner-Cp7jCmIl.js → defaultTaskRunner-BaX4ZbFv.js}

@@ -1,12 +1,42 @@
-import { x as xxh3Hash } from './utils-zO0ZRgtf.js';
-import { Cache } from './Cache-CWaX_c8U.js';
-import { inferFrameworkEnvPatterns } from './detectFrameworks-CeFzKE6J.js';
-import { IncrementalFileHasher } from './IncrementalFileHasher-BRS76-mb.js';
-import { RemoteCache } from './RemoteCache-DSU3lc87.js';
-import { InProcessTaskHasher } from './computeTaskHash-DYqfrDGq.js';
-import { TaskOrchestrator } from './TaskOrchestrator-rf45vW5c.js';
+import { x as xxh3Hash } from './utils-Bmnj-H2J.js';
+import { createRemoteCacheBackend } from './resolveCacheMode-CsmHT_0o.js';
+import { Cache } from './Cache-CbhoA268.js';
+import { inferFrameworkEnvPatterns } from './detectFrameworks-D7nyTc-o.js';
+import { IncrementalFileHasher } from './IncrementalFileHasher-BBhVK491.js';
+import { InProcessTaskHasher } from './computeTaskHash-DHoBJ_-V.js';
+import { TaskOrchestrator } from './TaskOrchestrator-CdRaQhTO.js';
 import { TaskScheduler } from './parsePartition-BfLbHGAx.js';
 
+const partitionAlwaysTasks = (taskGraph) => {
+  const alwaysTasks = [];
+  const remaining = {};
+  for (const [id, task] of Object.entries(taskGraph.tasks)) {
+    if (task.always) {
+      alwaysTasks.push(task);
+    } else {
+      remaining[id] = task;
+    }
+  }
+  if (alwaysTasks.length === 0) {
+    return { alwaysTasks: [], graph: taskGraph };
+  }
+  const alwaysIds = new Set(alwaysTasks.map((t) => t.id));
+  const dependencies = {};
+  for (const [id, deps] of Object.entries(taskGraph.dependencies)) {
+    if (alwaysIds.has(id)) {
+      continue;
+    }
+    dependencies[id] = deps.filter((dep) => !alwaysIds.has(dep));
+  }
+  return {
+    alwaysTasks,
+    graph: {
+      dependencies,
+      roots: taskGraph.roots.filter((id) => !alwaysIds.has(id)),
+      tasks: remaining
+    }
+  };
+};
 const computeGlobalEnvNamespace = (globalEnv) => {
   if (!globalEnv || globalEnv.length === 0) {
     return void 0;
@@ -56,21 +86,23 @@ const defaultTaskRunner = async (_tasks, options, context) => {
     targetDefaults: options.targetDefaults,
     workspaceRoot
   });
+  const { alwaysTasks, graph: scheduledGraph } = partitionAlwaysTasks(taskGraph);
   const maxParallel = resolveParallel(options.parallel);
-  const scheduler = new TaskScheduler(taskGraph, projectGraph, maxParallel);
+  const scheduler = new TaskScheduler(scheduledGraph, projectGraph, maxParallel);
   const resolveCommand = (task) => {
     const project = projectGraph.nodes[task.target.project];
     const targetConfig = project?.data.targets?.[task.target.target];
     const defaultConfig = options.targetDefaults?.[task.target.target];
     return targetConfig?.command ?? defaultConfig?.command;
   };
-  const remoteCache = options.remoteCache ? new RemoteCache(options.remoteCache) : void 0;
+  const remoteCache = options.remoteCache ? createRemoteCacheBackend(options.remoteCache) : void 0;
   let fingerprintEnvPatterns = options.fingerprintEnvPatterns ?? [];
   if (options.frameworkInference && options.autoFingerprint) {
     const inferredPatterns = await inferFrameworkEnvPatterns(workspaceRoot, projects);
     fingerprintEnvPatterns = [.../* @__PURE__ */ new Set([...fingerprintEnvPatterns, ...inferredPatterns])];
   }
   const orchestrator = new TaskOrchestrator({
+    alwaysTasks,
     autoFingerprint: options.autoFingerprint,
     cache,
     cacheDiagnostics: options.cacheDiagnostics,
@@ -78,23 +110,34 @@ const defaultTaskRunner = async (_tasks, options, context) => {
     dryRun: options.dryRun,
     fingerprintEnvPatterns,
     lifeCycle,
+    // Bridge-local upload errors (tar/digest in hash-bridge) flow back
+    // through the same callback the wire-level backend uses, so a user
+    // observes upload failures regardless of where they originate.
+    onRemoteUploadError: options.remoteCache?.onUploadError,
     remoteCache,
     resolveCommand: options.autoFingerprint ? resolveCommand : void 0,
     scheduler,
     skipCache: options.skipNxCache,
     summarize: options.summarize,
     taskExecutor,
-    taskGraph,
+    taskGraph: scheduledGraph,
     taskHasher,
     untrackedEnvVars: options.untrackedEnvVars,
     workspaceRoot
   });
-  const results = await orchestrator.run();
-  if (incrementalHasher) {
-    await incrementalHasher.save().catch(() => {
-    });
+  try {
+    const results = await orchestrator.run();
+    if (incrementalHasher) {
+      await incrementalHasher.save().catch(() => {
+      });
+    }
+    return results;
+  } finally {
+    if (remoteCache) {
+      await remoteCache.close().catch(() => {
+      });
+    }
   }
-  return results;
 };
 
 export { defaultTaskRunner };

package/dist/packem_shared/{detectFrameworks-CeFzKE6J.js → detectFrameworks-D7nyTc-o.js}

@@ -1,5 +1,5 @@
 import { join } from '@visulima/path';
-import { r as readPackageDeps } from './utils-zO0ZRgtf.js';
+import { r as readPackageDeps } from './utils-Bmnj-H2J.js';
 
 const FRAMEWORK_DEFINITIONS = [
   {

package/dist/packem_shared/{detectScriptShell-CR-xXKA4.js → detectScriptShell-CzxCM9-t.js}

@@ -37,7 +37,7 @@ const detectScriptShell = () => {
       stdio: ["ignore", "pipe", "ignore"],
       timeout: 5e3
     }).trim();
-    if (result && result !== "undefined" && result !== "") {
+    if (result && result !== "undefined" && result !== "null" && result !== "") {
       cachedShellPath = result;
       return result;
     }

package/dist/packem_shared/digestBuffer-CPdI2E1d.js

@@ -0,0 +1,48 @@
+import { createRequire as __cjs_createRequire } from "node:module";
+
+const __cjs_require = __cjs_createRequire(import.meta.url);
+
+const __cjs_getProcess = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" ? globalThis.process : process;
+
+const __cjs_getBuiltinModule = (module) => {
+    // Check if we're in Node.js and version supports getBuiltinModule
+    if (typeof __cjs_getProcess !== "undefined" && __cjs_getProcess.versions && __cjs_getProcess.versions.node) {
+        const [major, minor] = __cjs_getProcess.versions.node.split(".").map(Number);
+        // Node.js 20.16.0+ and 22.3.0+
+        if (major > 22 || (major === 22 && minor >= 3) || (major === 20 && minor >= 16)) {
+            return __cjs_getProcess.getBuiltinModule(module);
+        }
+    }
+    // Fallback to createRequire
+    return __cjs_require(module);
+};
+
+const {
+  createHash
+} = __cjs_getBuiltinModule("node:crypto");
+const {
+  createReadStream
+} = __cjs_getBuiltinModule("node:fs");
+const {
+  stat
+} = __cjs_getBuiltinModule("node:fs/promises");
+
+const digestBuffer = (bytes) => {
+  const hash = createHash("sha256").update(bytes).digest("hex");
+  return { hash, sizeBytes: bytes.byteLength };
+};
+const digestFile = async (filePath) => {
+  try {
+    const { size } = await stat(filePath);
+    const hasher = createHash("sha256");
+    const source = createReadStream(filePath);
+    for await (const chunk of source) {
+      hasher.update(chunk);
+    }
+    return { hash: hasher.digest("hex"), sizeBytes: size };
+  } catch {
+    return void 0;
+  }
+};
+
+export { digestBuffer, digestFile };

package/dist/packem_shared/{expandArguments-0AwD2BIA.js → expandArguments-Ba-hHYff.js}

@@ -1,5 +1,6 @@
+import { s as shellQuote } from './shell-quote-DWJJbt21.js';
+
 const PLACEHOLDER_REGEX = /\\?\{([@*]|[1-9]\d*)\}/g;
-const shellQuote = (s) => `'${s.replaceAll("'", String.raw`'\''`)}'`;
 const expandArguments = (config, additionalArguments) => {
   if (additionalArguments.length === 0) {
     return config;

package/dist/packem_shared/expandTokensInString-Bb7nYehP.js

@@ -0,0 +1,47 @@
+import { s as shellQuote } from './shell-quote-DWJJbt21.js';
+
+const TOKEN_PATHS = {
+  "affected.files": "affectedFiles",
+  changed_files: "affectedFiles"
+};
+const TOKEN_REGEX = /\\?\$\{\s*([\w.]+)\s*(?:\|\s*flag\s+(["'])(.*?)\2\s*)?\}/g;
+const rewriteForProjectRoot = (filePath, projectRoot) => {
+  if (filePath === projectRoot) {
+    return ".";
+  }
+  const prefix = `${projectRoot}/`;
+  if (filePath.startsWith(prefix)) {
+    return filePath.slice(prefix.length);
+  }
+  return void 0;
+};
+const expandTokensInString = (command, context) => command.replaceAll(TOKEN_REGEX, (match, name, _quote, flagValue) => {
+  if (match.startsWith("\\")) {
+    return match.slice(1);
+  }
+  const sourceKey = TOKEN_PATHS[name];
+  if (!sourceKey) {
+    return match;
+  }
+  const rawFiles = context[sourceKey] ?? [];
+  const files = context.projectRoot ? rawFiles.map((f) => rewriteForProjectRoot(f, context.projectRoot)).filter((f) => f !== void 0) : rawFiles;
+  if (files.length === 0) {
+    return "";
+  }
+  if (flagValue !== void 0 && flagValue.length > 0) {
+    return files.map((file) => `${flagValue} ${shellQuote(file)}`).join(" ");
+  }
+  return files.map(shellQuote).join(" ");
+});
+const expandTokens = (config, context) => {
+  if (!config.command.includes("${")) {
+    return config;
+  }
+  const command = expandTokensInString(config.command, context);
+  if (command === config.command) {
+    return config;
+  }
+  return { ...config, command };
+};
+
+export { expandTokens, expandTokensInString };

package/dist/packem_shared/{extractPackageName-BllKetnz.js → extractPackageName-CMHjqGj_.js}

@@ -20,7 +20,7 @@ const __cjs_getBuiltinModule = (module) => {
 const {
   readFile
 } = __cjs_getBuiltinModule("node:fs/promises");
-import { r as readPackageDeps, e as createXxh3Hasher } from './utils-zO0ZRgtf.js';
+import { r as readPackageDeps, e as createXxh3Hasher } from './utils-Bmnj-H2J.js';
 import { join } from '@visulima/path';
 
 const extractPackageName = (path) => {
@@ -44,8 +44,7 @@ const parseNpmLockfile = (content) => {
           continue;
         }
         const name = extractPackageName(path);
-        if (name && // Use the first (top-level) occurrence
-        !versions.has(name)) {
+        if (name && !versions.has(name)) {
           versions.set(name, entry.version);
         }
       }

package/dist/packem_shared/{generateRunSummary-BE1jnQ3H.js → generateRunSummary-Bah7CFay.js}

@@ -23,7 +23,7 @@ const {
   writeFile
 } = __cjs_getBuiltinModule("node:fs/promises");
 import { join } from '@visulima/path';
-import { u as uniqueId } from './utils-zO0ZRgtf.js';
+import { u as uniqueId } from './utils-Bmnj-H2J.js';
 
 const getCacheStatus = (result) => {
   switch (result.status) {

package/dist/packem_shared/getCurrentBranch-DVNikt0P.js

@@ -0,0 +1,156 @@
+import { createRequire as __cjs_createRequire } from "node:module";
+
+const __cjs_require = __cjs_createRequire(import.meta.url);
+
+const __cjs_getProcess = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" ? globalThis.process : process;
+
+const __cjs_getBuiltinModule = (module) => {
+    // Check if we're in Node.js and version supports getBuiltinModule
+    if (typeof __cjs_getProcess !== "undefined" && __cjs_getProcess.versions && __cjs_getProcess.versions.node) {
+        const [major, minor] = __cjs_getProcess.versions.node.split(".").map(Number);
+        // Node.js 20.16.0+ and 22.3.0+
+        if (major > 22 || (major === 22 && minor >= 3) || (major === 20 && minor >= 16)) {
+            return __cjs_getProcess.getBuiltinModule(module);
+        }
+    }
+    // Fallback to createRequire
+    return __cjs_require(module);
+};
+
+const {
+  execFileSync
+} = __cjs_getBuiltinModule("node:child_process");
+
+const normalisePlatform = (value) => value === "windows" ? "win32" : value;
+const matchPlatform = (clause, current) => {
+  const list = Array.isArray(clause) ? clause : [clause];
+  return list.some((p) => normalisePlatform(p) === normalisePlatform(current));
+};
+const matchBranch = (clause, current) => {
+  if (current === "") {
+    return false;
+  }
+  const list = Array.isArray(clause) ? clause : [clause];
+  return list.includes(current);
+};
+const matchSingleEnv = (matcher, env) => {
+  if (typeof matcher === "string") {
+    const value2 = env[matcher];
+    return value2 !== void 0 && value2 !== "";
+  }
+  const value = env[matcher.name];
+  if (matcher.equals !== void 0) {
+    return value === matcher.equals;
+  }
+  if (matcher.exists !== void 0) {
+    const present = value !== void 0 && value !== "";
+    return matcher.exists ? present : !present;
+  }
+  return value !== void 0 && value !== "";
+};
+const matchEnv = (clause, env) => {
+  const list = Array.isArray(clause) ? clause : [clause];
+  return list.some((m) => matchSingleEnv(m, env));
+};
+const detectCi = (env) => {
+  const value = env.CI;
+  return value !== void 0 && value !== "" && value !== "false" && value !== "0";
+};
+const branchCache = /* @__PURE__ */ new Map();
+const getCurrentBranch = (cwd) => {
+  const cached = branchCache.get(cwd);
+  if (cached !== void 0) {
+    return cached;
+  }
+  try {
+    const out = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd, stdio: ["ignore", "pipe", "ignore"] });
+    let branch = out.toString("utf8").trim();
+    if (branch === "HEAD") {
+      branch = "";
+    }
+    branchCache.set(cwd, branch);
+    return branch;
+  } catch {
+    branchCache.set(cwd, "");
+    return "";
+  }
+};
+const resetBranchCache = () => {
+  branchCache.clear();
+};
+const resolveWhenContext = (context) => {
+  const env = context.env ?? process.env;
+  return {
+    branch: context.branch ?? "",
+    ci: context.ci ?? detectCi(env),
+    currentPlatform: context.platform ?? process.platform,
+    env
+  };
+};
+const evaluateWhen = (when, context = {}) => {
+  if (!when) {
+    return true;
+  }
+  const { branch, ci, currentPlatform, env } = resolveWhenContext(context);
+  if (when.os !== void 0 && !matchPlatform(when.os, currentPlatform)) {
+    return false;
+  }
+  if (when.env !== void 0 && !matchEnv(when.env, env)) {
+    return false;
+  }
+  if (when.branch !== void 0 && !matchBranch(when.branch, branch)) {
+    return false;
+  }
+  if (when.ci !== void 0 && when.ci !== ci) {
+    return false;
+  }
+  if (when.not) {
+    if (when.not.os !== void 0 && matchPlatform(when.not.os, currentPlatform)) {
+      return false;
+    }
+    if (when.not.env !== void 0 && matchEnv(when.not.env, env)) {
+      return false;
+    }
+    if (when.not.branch !== void 0 && matchBranch(when.not.branch, branch)) {
+      return false;
+    }
+    if (when.not.ci !== void 0 && when.not.ci === ci) {
+      return false;
+    }
+  }
+  return true;
+};
+const explainWhen = (when, context = {}) => {
+  if (!when || evaluateWhen(when, context)) {
+    return "";
+  }
+  const { branch, ci, currentPlatform, env } = resolveWhenContext(context);
+  const reasons = [];
+  if (when.os !== void 0 && !matchPlatform(when.os, currentPlatform)) {
+    reasons.push(`os=${currentPlatform} does not match ${JSON.stringify(when.os)}`);
+  }
+  if (when.env !== void 0 && !matchEnv(when.env, env)) {
+    reasons.push(`env clause did not match`);
+  }
+  if (when.branch !== void 0 && !matchBranch(when.branch, branch)) {
+    reasons.push(`branch=${branch || "(unknown)"} does not match ${JSON.stringify(when.branch)}`);
+  }
+  if (when.ci !== void 0 && when.ci !== ci) {
+    reasons.push(`ci=${ci} does not match required ci=${when.ci}`);
+  }
+  if (when.not?.os !== void 0 && matchPlatform(when.not.os, currentPlatform)) {
+    reasons.push(`os=${currentPlatform} matches excluded ${JSON.stringify(when.not.os)}`);
+  }
+  if (when.not?.env !== void 0 && matchEnv(when.not.env, env)) {
+    reasons.push(`env clause matches excluded matcher`);
+  }
+  if (when.not?.branch !== void 0 && matchBranch(when.not.branch, branch)) {
+    reasons.push(`branch=${branch} matches excluded ${JSON.stringify(when.not.branch)}`);
+  }
+  if (when.not?.ci !== void 0 && when.not.ci === ci) {
+    reasons.push(`ci=${ci} matches excluded ci=${when.not.ci}`);
+  }
+  return reasons.join("; ");
+};
+
+export { evaluateWhen, explainWhen, getCurrentBranch, resetBranchCache };