@vodmal/vdx-cli 0.21.1 → 0.22.1

package/src/clone-checks.ts

@@ -0,0 +1,166 @@
+/**
+ * Checks of this clone that both `vdx doctor` (a row) and `vdx audit` (a note
+ * next to the axis that names it in `clone_check`) print — one check, two
+ * surfaces, so they cannot disagree.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import type { CheckResult } from './doctor.ts';
+import {
+  cloneHookStates,
+  detectHookFrameworks,
+  effectiveHooksDir,
+  missingMachinePaths,
+  unsetGatingVars,
+} from './hooks.ts';
+import { autoDetectStack, type Ctx } from './facts.ts';
+
+function gitConfig(root: string, key: string): string | null {
+  try {
+    const out = execFileSync('git', ['-C', root, 'config', '--get', key], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
+function isGitWorkTree(root: string): boolean {
+  return fs.existsSync(path.join(root, '.git'));
+}
+
+function executableHooks(dir: string): Map<string, string> {
+  const out = new Map<string, string>();
+  let names: string[] = [];
+  try {
+    names = fs.readdirSync(dir).filter((f) => !f.startsWith('.') && !f.endsWith('.sample'));
+  } catch {
+    return out;
+  }
+  for (const f of names) {
+    const file = path.join(dir, f);
+    try {
+      fs.accessSync(file, fs.constants.X_OK);
+      if (fs.statSync(file).isFile()) out.set(f, fs.readFileSync(file, 'utf8'));
+    } catch {
+      /* not executable — git skips it silently */
+    }
+  }
+  return out;
+}
+
+/**
+ * Git hooks: declared vs actually running in this clone.
+ *
+ * A framework leaves two separable traces: files in the repository (tracked,
+ * the same for every clone) and activation in the clone (`core.hooksPath`, or
+ * hooks written into the git hooks directory). The first says nothing about
+ * the second, and a hook that is declared but off fails exactly like success —
+ * nothing is printed, the commit goes through. So does a hook gated on a
+ * variable nobody set, or one that calls a path missing on this machine.
+ *
+ * Null (no row) when the repo declares no hooks — there is nothing to be wrong about.
+ */
+export function checkRepoHooks(root: string | null): CheckResult | null {
+  if (root === null || !isGitWorkTree(root)) return null;
+  const id = 'git-hooks';
+  const label = 'git hooks';
+  const ctx: Ctx = { projectRoot: root, stack: autoDetectStack(root), cache: new Map() };
+  const frameworks = detectHookFrameworks(ctx);
+  const hooksPath = gitConfig(root, 'core.hooksPath');
+
+  if (frameworks.length === 0) {
+    if (hooksPath === null) return null;
+    // Hooks in a directory no framework owns: read what is there.
+    const dir = path.resolve(root, hooksPath);
+    if (!fs.existsSync(dir)) {
+      return {
+        id,
+        label,
+        status: 'missing',
+        message: `core.hooksPath=${hooksPath} but that directory does not exist`,
+        remedy: `git -C ${root} config --unset core.hooksPath, or create ${hooksPath}/`,
+      };
+    }
+    const hooks = executableHooks(dir);
+    if (hooks.size === 0) {
+      return {
+        id,
+        label,
+        status: 'warning',
+        message: `core.hooksPath=${hooksPath} but it holds no executable hook`,
+        remedy: `chmod +x ${hooksPath}/*`,
+      };
+    }
+    return bodyProblems(id, label, [...hooks.values()]) ?? {
+      id,
+      label,
+      status: 'ok',
+      message: `${hooks.size} hook(s) active via ${hooksPath}`,
+    };
+  }
+
+  const states = cloneHookStates(root, ctx, frameworks);
+  const off = states.filter((s) => !s.enabled);
+  if (off.length > 0) {
+    return {
+      id,
+      label,
+      status: 'warning',
+      message: off.map((s) => `${s.framework.id} (${s.framework.declaredIn}): ${s.problem} — those hooks never run`).join('; '),
+      ...(off[0]!.remedy ? { remedy: off[0]!.remedy } : {}),
+    };
+  }
+
+  const commands = frameworks.flatMap((f) => [...f.hooks.values()].flat());
+  const problem = bodyProblems(id, label, commands);
+  if (problem) return problem;
+
+  const dir = effectiveHooksDir(root);
+  const where = dir ? path.relative(root, dir) || dir : 'the hooks directory';
+  const count = frameworks.reduce((n, f) => n + f.hooks.size, 0);
+  return {
+    id,
+    label,
+    status: 'ok',
+    message: `${frameworks.map((f) => f.id).join(', ')}: ${count} hook(s) active in ${where}`,
+  };
+}
+
+/** A body that looks installed but does nothing here: gated on an unset variable, or calling a missing path. */
+function bodyProblems(id: string, label: string, bodies: string[]): CheckResult | null {
+  const unset = unsetGatingVars(bodies);
+  if (unset.length > 0) {
+    return {
+      id,
+      label,
+      status: 'warning',
+      message: `hooks gated on unset ${unset.join(', ')} — those gates are no-ops`,
+      remedy: `export ${unset[0]}=... in your shell profile (see the tool that ships the hook)`,
+    };
+  }
+  const missing = missingMachinePaths(bodies);
+  if (missing.length > 0) {
+    return {
+      id,
+      label,
+      status: 'warning',
+      message: `hooks call ${missing.join(', ')} — not on this machine, the commit fails or the gate is skipped`,
+      remedy: 'install what the hook calls here, or move the hook out of the repository (a personal hook in git config)',
+    };
+  }
+  return null;
+}
+
+/** The checks an axis may name in `clone_check`. */
+export function cloneCheck(name: 'git-hooks', root: string): CheckResult | null {
+  switch (name) {
+    case 'git-hooks':
+      return checkRepoHooks(root);
+    default:
+      return null;
+  }
+}

package/src/conversations.ts

@@ -314,10 +314,13 @@ export function parseMachineReport(text: string): MachineReport {
   return { home: text.match(/^home=(.+)$/m)?.[1] ?? null, sessions: parseLiveSessions(text) };
 }
 
-/** "running on m3 now (t23b-program@m3, waiting)" — where a live session is, for a person choosing. */
-export function describeLive(machine: string, live: LiveSession, here: boolean): string {
+/**
+ * "running on m3 now (t23b-program@m3, waiting)" — where a live session is, for
+ * a person choosing; `place` is the machine as they see it: "here", "on m3".
+ */
+export function describeLive(place: string, live: LiveSession): string {
   const where = live.tmux ? live.tmux.replace(/:.*$/, '') : `pid ${live.pid}`;
-  return `running ${here ? 'here' : `on ${machine}`} now (${where}${live.status ? `, ${live.status}` : ''})`;
+  return `running ${place} now (${where}${live.status ? `, ${live.status}` : ''})`;
 }
 
 /** "3 min ago", "yesterday 14:05", "2026-09-30 14:05" — for a person choosing. */

package/src/doctor.ts

@@ -5,6 +5,8 @@ import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 import { effectiveAuthor, isGitRepo, rankAuthors, scanPool } from './author.ts';
 import { authorPoolDirs, loadEnvironment, resolveEnvironmentPath, shellQuote, type Environment } from './ai.ts';
+import { checkRepoHooks } from './clone-checks.ts';
+import { checkPersonalHooks, defaultPersonalHookDeps, fixPersonalHooks, type PersonalHookDeps } from './personal-hooks.ts';
 
 export type CheckStatus = 'ok' | 'warning' | 'missing';
 
@@ -380,134 +382,6 @@ export function checkClaudeCodePlugin(
   return { ...base, status: 'ok', message: label };
 }
 
-/**
- * Variables a hook body *gates on*: `[ -n "${VAR:-}" ]`, `[ -x "$VAR" ]` and
- * friends. Restricted to test-expression positions on purpose — a bare `$VAR`
- * anywhere in a script says nothing about whether the hook still does its job,
- * while an unset variable inside the guard means the guarded block never runs.
- */
-const GATING_VAR_RE =
-  /\[\s+-[nxfse]\s+"\$\{([A-Z][A-Z0-9_]*)(?::-[^}]*)?\}"|\[\s+-[nxfse]\s+"\$([A-Z][A-Z0-9_]*)"/g;
-
-/**
- * Git hooks: declared vs actually wired.
- *
- * A hook framework leaves two separable traces: files in the repository
- * (tracked, same for every clone) and activation in `.git/config` (per-clone,
- * never committed). Presence of the first says nothing about the second, and a
- * hook that is present but inert fails exactly like success — nothing is
- * printed, the commit goes through. Same for a hook whose body is gated on an
- * environment variable nobody set: the guard short-circuits and the gate is a
- * no-op.
- *
- * Returns null (row omitted) when the repo declares no hooks at all — there is
- * nothing to be wrong about.
- */
-function checkGitHooks(ctx: DoctorCtx): CheckResult | null {
-  const root = ctx.projectRoot;
-  if (root === null) return null;
-  if (!fs.existsSync(path.join(root, '.git'))) return null;
-
-  const id = 'git-hooks';
-  const label = 'git hooks';
-
-  let hooksPath: string | null = null;
-  try {
-    const out = execFileSync('git', ['-C', root, 'config', '--get', 'core.hooksPath'], {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-    });
-    hooksPath = out.trim() || null;
-  } catch {
-    hooksPath = null;
-  }
-
-  // Directories a framework would have written into the repo.
-  const declaredDirs = ['.githooks', '.husky'].filter((d) =>
-    fs.existsSync(path.join(root, d)),
-  );
-
-  if (hooksPath === null) {
-    if (declaredDirs.length === 0) return null; // nothing declared — not applicable
-    return {
-      id,
-      label,
-      status: 'warning',
-      message: `${declaredDirs.join(', ')} present but core.hooksPath is unset — hooks never run`,
-      remedy: `git -C ${root} config core.hooksPath ${declaredDirs[0]}`,
-    };
-  }
-
-  const dir = path.resolve(root, hooksPath);
-  if (!fs.existsSync(dir)) {
-    return {
-      id,
-      label,
-      status: 'missing',
-      message: `core.hooksPath=${hooksPath} but that directory does not exist`,
-      remedy: `git -C ${root} config --unset core.hooksPath, or create ${hooksPath}/`,
-    };
-  }
-
-  let entries: string[] = [];
-  try {
-    entries = fs.readdirSync(dir).filter((f) => !f.startsWith('.') && !f.endsWith('.sample'));
-  } catch {
-    entries = [];
-  }
-  const executable = entries.filter((f) => {
-    try {
-      fs.accessSync(path.join(dir, f), fs.constants.X_OK);
-      return true;
-    } catch {
-      return false;
-    }
-  });
-
-  if (executable.length === 0) {
-    return {
-      id,
-      label,
-      status: 'warning',
-      message: `core.hooksPath=${hooksPath} but it holds no executable hook`,
-      remedy: `chmod +x ${hooksPath}/*`,
-    };
-  }
-
-  // A hook gated on an unset variable is inert while looking installed.
-  const unresolved = new Set<string>();
-  for (const f of executable) {
-    let body = '';
-    try {
-      body = fs.readFileSync(path.join(dir, f), 'utf8');
-    } catch {
-      continue;
-    }
-    for (const m of body.matchAll(GATING_VAR_RE)) {
-      const name = m[1] ?? m[2];
-      if (name && !process.env[name]) unresolved.add(name);
-    }
-  }
-
-  if (unresolved.size > 0) {
-    const names = [...unresolved].sort();
-    return {
-      id,
-      label,
-      status: 'warning',
-      message: `${executable.length} hook(s) via ${hooksPath}, but gated on unset ${names.join(', ')} — those gates are no-ops`,
-      remedy: `export ${names[0]}=... in your shell profile (see the tool that ships the hook)`,
-    };
-  }
-
-  return {
-    id,
-    label,
-    status: 'ok',
-    message: `${executable.length} hook(s) active via ${hooksPath}`,
-  };
-}
-
 /**
  * The project's commit author. With `user.useConfigOnly` git refuses to commit
  * in a repo that has none; the remedy names the likely one, as `vdx ai` does.
@@ -552,7 +426,8 @@ const CHECKS: Array<(ctx: DoctorCtx) => CheckResult | null> = [
   checkMise,
   checkNpmAuth,
   checkContainerRuntime,
-  checkGitHooks,
+  (ctx) => checkRepoHooks(ctx.projectRoot),
+  (ctx) => checkPersonalHooks(ctx.projectRoot),
   checkGitAuthor,
 ];
 
@@ -568,6 +443,37 @@ export function runDoctor(ctx: DoctorCtx = resolveDoctorCtx()): DoctorReport {
   return { cliVersion: readCliVersion(), checks, ok, warning, missing };
 }
 
+/**
+ * For the agent's own session (the vdx plugin's SessionStart hook): one line
+ * per hook that is declared but does not run — in this clone, or a personal
+ * hook on this machine. Nothing when they are in order; the fix is the user's
+ * call, so the line names it rather than applying it.
+ */
+export function runDoctorCheck(
+  ctx: DoctorCtx = resolveDoctorCtx(),
+  deps: PersonalHookDeps = defaultPersonalHookDeps(),
+): string {
+  const rows = [checkRepoHooks(ctx.projectRoot), checkPersonalHooks(ctx.projectRoot, deps)].filter(
+    (c): c is CheckResult => c !== null && c.status !== 'ok',
+  );
+  return rows
+    .map(
+      (c) =>
+        `vdx doctor: ${c.label} — ${c.message}.` +
+        (c.remedy ? ` Fix, on the user's word: \`${c.remedy}\`.` : ''),
+    )
+    .join('\n');
+}
+
+/**
+ * `vdx doctor --fix`: what doctor can put right without installing anything —
+ * the profile's personal hooks in ~/.gitconfig. Repository hooks are switched
+ * on by the project's own install step; doctor names it and leaves it to you.
+ */
+export function runDoctorFix(deps: PersonalHookDeps = defaultPersonalHookDeps()): string[] {
+  return fixPersonalHooks(deps);
+}
+
 const PROJECT_MARKER_FILES = [
   'package.json',
   'composer.json',

package/src/evaluator.ts

@@ -1,6 +1,8 @@
 import type { Predicate } from './rubric.ts';
 import type { Ctx } from './facts.ts';
-import { REGISTRY } from './predicates.ts';
+import { REGISTRY, isUnknown, type Unknown, type Verdict } from './predicates.ts';
+
+export { isUnknown, type Unknown, type Verdict };
 
 /**
  * Sugar shorthand: `{ has_task: "up" }` → `{ fn: "has_task", args: { task: "up" } }`
@@ -15,7 +17,20 @@ const SUGAR_ARG_KEY: Record<string, string> = {
   phpstan_level_at_least: 'n',
 };
 
-export function evalPredicate(p: Predicate, ctx: Ctx): boolean {
+export const COMBINATORS = ['all_of', 'any_of', 'at_least_n_of', 'not'] as const;
+
+/** The first unknown among verdicts, for the reason a combination cannot be decided. */
+function firstUnknown(vs: Verdict[]): Unknown | undefined {
+  return vs.find(isUnknown);
+}
+
+/**
+ * Three-valued: true, false, or unknown with the reason the fact could not be
+ * read (a CI system or a hosting vdx does not inspect). Unknown never turns
+ * into true: `any_of` is true only on a true branch, `all_of` false on any
+ * false branch, otherwise unknown.
+ */
+export function evalVerdict(p: Predicate, ctx: Ctx): Verdict {
   if (p === null || p === undefined) return false;
   if (typeof p === 'boolean') return p;
 
@@ -23,21 +38,27 @@ export function evalPredicate(p: Predicate, ctx: Ctx): boolean {
     const obj = p as Record<string, any>;
 
     if ('all_of' in obj) {
-      const list = obj.all_of as Predicate[];
-      return list.every((q) => evalPredicate(q, ctx));
+      const vs = (obj.all_of as Predicate[]).map((q) => evalVerdict(q, ctx));
+      if (vs.some((v) => v === false)) return false;
+      return firstUnknown(vs) ?? true;
     }
     if ('any_of' in obj) {
-      const list = obj.any_of as Predicate[];
-      return list.some((q) => evalPredicate(q, ctx));
+      const vs = (obj.any_of as Predicate[]).map((q) => evalVerdict(q, ctx));
+      if (vs.some((v) => v === true)) return true;
+      return firstUnknown(vs) ?? false;
     }
     if ('at_least_n_of' in obj) {
       const { n, predicates } = obj.at_least_n_of as { n: number; predicates: Predicate[] };
-      let matched = 0;
-      for (const q of predicates) if (evalPredicate(q, ctx)) matched += 1;
-      return matched >= n;
+      const vs = predicates.map((q) => evalVerdict(q, ctx));
+      const matched = vs.filter((v) => v === true).length;
+      if (matched >= n) return true;
+      const open = vs.filter(isUnknown).length;
+      if (matched + open < n) return false;
+      return firstUnknown(vs)!;
     }
     if ('not' in obj) {
-      return !evalPredicate(obj.not, ctx);
+      const v = evalVerdict(obj.not, ctx);
+      return isUnknown(v) ? v : !v;
     }
     if ('fn' in obj) {
       const fn = REGISTRY[String(obj.fn)];
@@ -70,3 +91,32 @@ export function evalPredicate(p: Predicate, ctx: Ctx): boolean {
   process.stderr.write(`warning: malformed predicate ${JSON.stringify(p)}\n`);
   return false;
 }
+
+/** Two-valued view: unknown counts as not met (applies_when, flags, profile rules). */
+export function evalPredicate(p: Predicate, ctx: Ctx): boolean {
+  return evalVerdict(p, ctx) === true;
+}
+
+/**
+ * Predicate names a tree refers to, for load-time validation. Sugar keys and
+ * `fn:` both count; combinators are walked, not reported.
+ */
+export function predicateNames(p: Predicate): string[] {
+  const out: string[] = [];
+  const walk = (q: Predicate): void => {
+    if (q === null || q === undefined || typeof q !== 'object' || Array.isArray(q)) return;
+    const obj = q as Record<string, any>;
+    if ('all_of' in obj) return (obj.all_of as Predicate[]).forEach(walk);
+    if ('any_of' in obj) return (obj.any_of as Predicate[]).forEach(walk);
+    if ('at_least_n_of' in obj) return (obj.at_least_n_of?.predicates as Predicate[] ?? []).forEach(walk);
+    if ('not' in obj) return walk(obj.not);
+    if ('fn' in obj) {
+      out.push(String(obj.fn));
+      return;
+    }
+    const keys = Object.keys(obj);
+    if (keys.length === 1) out.push(keys[0]!);
+  };
+  walk(p);
+  return out;
+}

package/src/gha.ts

@@ -0,0 +1,211 @@
+/**
+ * GitHub Actions workflows as the `ci` axis reads them: which ones run on a
+ * push to the main branch, which steps run tests, which failures are masked,
+ * and which jobs ship something. Other CI systems are read as "present" (L1)
+ * and answer "unknown" above it — vdx does not inspect them yet.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import YAML from 'js-yaml';
+import { fileExists, readText, type Ctx } from './facts.ts';
+import { projectTaskCalls } from './vocabulary.ts';
+
+export interface GhaStep {
+  run?: string;
+  uses?: string;
+  continueOnError: boolean;
+}
+
+export interface GhaJob {
+  id: string;
+  name?: string;
+  needs: string[];
+  steps: GhaStep[];
+  continueOnError: boolean;
+  matrix: boolean;
+}
+
+export interface GhaWorkflow {
+  file: string;
+  pushesMain: boolean;
+  jobs: GhaJob[];
+}
+
+const MAIN_BRANCHES = ['main', 'master'];
+
+/** GitHub's branch filter glob: `**` crosses `/`, `*` does not. */
+function filterMatches(pattern: string, branch: string): boolean {
+  const re = pattern
+    .split('**')
+    .map((part) =>
+      part
+        .split('*')
+        .map((s) => s.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
+        .join('[^/]*'),
+    )
+    .join('.*');
+  return new RegExp(`^${re}$`).test(branch);
+}
+
+function branchSelected(filters: unknown, branch: string): boolean {
+  const list = Array.isArray(filters) ? filters : [filters];
+  let selected = false;
+  for (const f of list) {
+    if (typeof f !== 'string') continue;
+    if (f.startsWith('!')) {
+      if (filterMatches(f.slice(1), branch)) selected = false;
+    } else if (filterMatches(f, branch)) {
+      selected = true;
+    }
+  }
+  return selected;
+}
+
+/** Does `on:` start the workflow on a push to main/master? */
+export function pushesMain(on: unknown): boolean {
+  if (on === 'push') return true;
+  if (Array.isArray(on)) return on.includes('push');
+  if (!on || typeof on !== 'object') return false;
+  if (!('push' in on)) return false;
+  const push = (on as Record<string, any>).push;
+  if (push === null || push === undefined || typeof push !== 'object') return true;
+  const hasBranchFilter = push.branches !== undefined || push['branches-ignore'] !== undefined;
+  if (!hasBranchFilter && (push.tags !== undefined || push['tags-ignore'] !== undefined)) return false;
+  return MAIN_BRANCHES.some((b) => {
+    if (push.branches !== undefined) return branchSelected(push.branches, b);
+    if (push['branches-ignore'] !== undefined) return !branchSelected(push['branches-ignore'], b);
+    return true;
+  });
+}
+
+function truthy(v: unknown): boolean {
+  return v === true || v === 'true';
+}
+
+export function parseWorkflow(file: string, text: string): GhaWorkflow | null {
+  let data: any;
+  try {
+    data = YAML.load(text);
+  } catch {
+    return null;
+  }
+  if (!data || typeof data !== 'object') return null;
+  const jobs: GhaJob[] = [];
+  for (const [id, job] of Object.entries((data.jobs ?? {}) as Record<string, any>)) {
+    if (!job || typeof job !== 'object') continue;
+    const needs = job.needs === undefined ? [] : Array.isArray(job.needs) ? job.needs : [job.needs];
+    const steps: GhaStep[] = (Array.isArray(job.steps) ? job.steps : [])
+      .filter((s: unknown) => s && typeof s === 'object')
+      .map((s: any) => ({
+        ...(typeof s.run === 'string' ? { run: s.run } : {}),
+        ...(typeof s.uses === 'string' ? { uses: s.uses } : {}),
+        continueOnError: truthy(s['continue-on-error']),
+      }));
+    jobs.push({
+      id,
+      ...(typeof job.name === 'string' ? { name: job.name } : {}),
+      needs: needs.filter((n: unknown): n is string => typeof n === 'string'),
+      steps,
+      continueOnError: truthy(job['continue-on-error']),
+      matrix: Boolean(job.strategy?.matrix),
+    });
+  }
+  return { file, pushesMain: pushesMain(data.on), jobs };
+}
+
+export function readWorkflows(ctx: Ctx): GhaWorkflow[] {
+  const key = 'gha:workflows';
+  if (ctx.cache.has(key)) return ctx.cache.get(key) as GhaWorkflow[];
+  const dir = path.join(ctx.projectRoot, '.github', 'workflows');
+  const out: GhaWorkflow[] = [];
+  let files: string[] = [];
+  try {
+    files = fs.readdirSync(dir).filter((f) => /\.ya?ml$/.test(f)).sort();
+  } catch {
+    files = [];
+  }
+  for (const f of files) {
+    const rel = path.join('.github', 'workflows', f);
+    const text = readText(ctx, rel);
+    const wf = text === null ? null : parseWorkflow(rel, text);
+    if (wf) out.push(wf);
+  }
+  ctx.cache.set(key, out);
+  return out;
+}
+
+/** CI systems vdx sees but does not read beyond "a config exists". */
+const OTHER_CI: Array<[string, string]> = [
+  ['.gitlab-ci.yml', 'GitLab CI'],
+  ['.circleci/config.yml', 'CircleCI'],
+];
+
+/** The CI systems a repository configures: `gha` for GitHub Actions workflows, others by name. */
+export function ciSystems(ctx: Ctx): string[] {
+  const out: string[] = [];
+  if (readWorkflows(ctx).length > 0) out.push('gha');
+  for (const [file, name] of OTHER_CI) if (fileExists(ctx, file)) out.push(name);
+  return out;
+}
+
+/** `|| true` and its relatives: the step reports success whatever the command did. */
+const MASK_RE = /\|\|\s*(true|:|exit\s+0)\b/;
+
+export function stepMasked(step: GhaStep, job: GhaJob): boolean {
+  if (job.continueOnError || step.continueOnError) return true;
+  return step.run !== undefined && MASK_RE.test(step.run);
+}
+
+/** Unmasked `run:` steps of jobs in workflows started by a push to main. */
+export function mainPushSteps(ctx: Ctx): Array<{ wf: GhaWorkflow; job: GhaJob; step: GhaStep }> {
+  const out: Array<{ wf: GhaWorkflow; job: GhaJob; step: GhaStep }> = [];
+  for (const wf of readWorkflows(ctx)) {
+    if (!wf.pushesMain) continue;
+    for (const job of wf.jobs) {
+      for (const step of job.steps) {
+        if (step.run === undefined || stepMasked(step, job)) continue;
+        out.push({ wf, job, step });
+      }
+    }
+  }
+  return out;
+}
+
+/** Project tasks CI calls on a push to main, unmasked. */
+export function ciTaskCalls(ctx: Ctx): Set<string> {
+  const out = new Set<string>();
+  for (const { step } of mainPushSteps(ctx)) for (const t of projectTaskCalls(step.run!, ctx)) out.add(t);
+  return out;
+}
+
+/** Jobs that check: an unmasked step runs tests (`pattern`) or a `test`/`check` task. */
+export function checkingJobs(ctx: Ctx, pattern: RegExp): Set<GhaJob> {
+  const out = new Set<GhaJob>();
+  for (const { job, step } of mainPushSteps(ctx)) {
+    if (pattern.test(step.run!) || projectTaskCalls(step.run!, ctx).some((t) => /^(test|check)(:|$)/.test(t))) {
+      out.add(job);
+    }
+  }
+  return out;
+}
+
+const SHIP_RE = /deploy|release|publish/i;
+
+/** Jobs that ship: deploy, release, publish — by id or name. */
+export function shippingJobs(wf: GhaWorkflow): GhaJob[] {
+  return wf.jobs.filter((j) => SHIP_RE.test(j.id) || (j.name !== undefined && SHIP_RE.test(j.name)));
+}
+
+/** Every job `job` waits for, transitively, within its workflow. */
+export function upstream(wf: GhaWorkflow, job: GhaJob): Set<GhaJob> {
+  const byId = new Map(wf.jobs.map((j) => [j.id, j] as const));
+  const seen = new Set<GhaJob>();
+  const queue = [...job.needs];
+  while (queue.length > 0) {
+    const j = byId.get(queue.shift()!);
+    if (!j || seen.has(j)) continue;
+    seen.add(j);
+    queue.push(...j.needs);
+  }
+  return seen;
+}