@vzn/vx 0.0.638 → 0.0.639

package/src/util/git-ignored.ts

@@ -0,0 +1,143 @@
+// Whether git ignores everything an output glob can write (M, 2026-10-15):
+// a key reads only what git lists, so such an output never reaches a
+// reader's key. Asked of git, never read from a `.gitignore`: git alone
+// knows every rule source (nested files, `info/exclude`, `core.excludesFile`)
+// and that a directory holding a tracked file is not ignored.
+
+import { gitEnv } from './hide-env.js'
+import { isLiteralPattern, normalizeGlob } from './paths.js'
+import { executablePath } from './which.js'
+
+/** A directory name no ignore rule names, standing for one a task may create. */
+const FRESH = '__vx_probe__'
+
+/**
+ * The paths git is asked about for a root-relative output glob: when git
+ * ignores each, it ignores every untracked path the glob can match. `deep`:
+ * the glob reaches below them (a `dist` at any depth is asked as `dist/` and
+ * a fresh `__vx_probe__/dist/`), so a listed file it matches must be looked
+ * for too (a tracked one, or one a `!` rule takes back). Null when no few paths
+ * stand for the glob (`*.js`): undecided, the output overlaps as before.
+ * `dir`: the glob's literal directory, where a listed file it matches lies.
+ */
+export function ignoreProbes(glob: string): { paths: string[]; deep: boolean; dir: string } | null {
+  const segs = normalizeGlob(glob).split('/')
+  let i = 0
+  while (i < segs.length && isLiteralPattern(segs[i]!)) i++
+  const lit = segs.slice(0, i).join('/')
+  if (i === segs.length) return { paths: [lit], deep: false, dir: lit }
+  const at = lit === '' ? '' : `${lit}/`
+  const name = segs[i + 1]
+  if (segs[i] === '**' && name !== undefined && isLiteralPattern(name)) {
+    const leaf = i + 2 < segs.length ? `${name}/` : name
+    return { paths: [at + leaf, `${at}${FRESH}/${leaf}`], deep: true, dir: lit }
+  }
+  return lit === '' ? null : { paths: [`${lit}/`], deep: false, dir: lit }
+}
+
+const CHECK_IGNORE = ['check-ignore', '--stdin', '-z']
+
+function ignoredOf(exitCode: number, stdout: Uint8Array): Set<string> | null {
+  // 0: some ignored; 1: none; anything else (no work tree): undecided.
+  if (exitCode === 1) return new Set()
+  if (exitCode !== 0) return null
+  return new Set(
+    new TextDecoder()
+      .decode(stdout)
+      .split('\0')
+      .filter((p) => p !== ''),
+  )
+}
+
+/** The `paths` (relative to `cwd`) git ignores; null when git cannot say. */
+export async function checkIgnore(
+  cwd: string,
+  paths: readonly string[],
+): Promise<Set<string> | null> {
+  if (paths.length === 0) return new Set()
+  try {
+    const proc = Bun.spawn({
+      cmd: [executablePath('git'), ...CHECK_IGNORE],
+      env: gitEnv(),
+      cwd,
+      stdin: Buffer.from(paths.map((p) => `${p}\0`).join('')),
+      stdout: 'pipe',
+      stderr: 'ignore',
+    })
+    const stdout = await new Response(proc.stdout).bytes()
+    return ignoredOf(await proc.exited, stdout)
+  } catch {
+    return null
+  }
+}
+
+/** {@link checkIgnore} for `vx lock`, which builds its graph synchronously. */
+export function checkIgnoreSync(cwd: string, paths: readonly string[]): Set<string> | null {
+  if (paths.length === 0) return new Set()
+  try {
+    const r = Bun.spawnSync({
+      cmd: [executablePath('git'), ...CHECK_IGNORE],
+      env: gitEnv(),
+      cwd,
+      stdin: Buffer.from(paths.map((p) => `${p}\0`).join('')),
+      stdout: 'pipe',
+      stderr: 'ignore',
+    })
+    return ignoredOf(r.exitCode, r.stdout)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * What git lists under `dirs` (relative to `cwd`): tracked files and the
+ * untracked ones it does not ignore, the set a key filters. Null when git
+ * cannot say. A run has it from its enumeration; this is `vx lock`'s.
+ */
+export function listedSync(cwd: string, dirs: readonly string[]): string[] | null {
+  try {
+    const r = Bun.spawnSync({
+      cmd: [
+        executablePath('git'),
+        'ls-files',
+        '-z',
+        '--cached',
+        '--others',
+        '--exclude-standard',
+        '--',
+        ...dirs.map((d) => (d === '' ? '.' : `:(literal)${d}`)),
+      ],
+      env: gitEnv(),
+      cwd,
+      stdout: 'pipe',
+      stderr: 'ignore',
+    })
+    if (r.exitCode !== 0) return null
+    return new TextDecoder()
+      .decode(r.stdout)
+      .split('\0')
+      .filter((p) => p !== '')
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Of `globs` (root-relative), those git ignores whole: each probe ignored
+ * and, for a deep glob, no listed file it matches (`listedMatch`).
+ */
+export function wholeIgnored(
+  globs: Iterable<string>,
+  ignored: ReadonlySet<string> | null,
+  listedMatch: (glob: string) => boolean,
+): Set<string> {
+  const out = new Set<string>()
+  if (ignored === null) return out
+  for (const g of globs) {
+    const ask = ignoreProbes(g)
+    if (ask === null || !ask.paths.every((p) => ignored.has(p))) continue
+    if (ask.deep && listedMatch(g)) continue
+    out.add(g)
+  }
+  return out
+}

package/src/util/index.ts

@@ -24,8 +24,17 @@ export {
   wantsJson,
 } from './errors.js'
 export { configErrorFrame, configRefusal } from './config-frame.js'
-export { detectColors, ERROR, paint, SUCCESS, WARN, type ColorSupport } from './colors.js'
-export { gradientRule } from './report.js'
+export {
+  detectColors,
+  dumbTerminal,
+  ERROR,
+  identityColor,
+  paint,
+  SUCCESS,
+  WARN,
+  type ColorSupport,
+} from './colors.js'
+export { barWidth, gradientRule } from './report.js'
 import * as ui from './ui.js'
 export { refusalNotice, sayLine, sayNotice } from './refusal-notice.js'
 export { ui }
@@ -67,10 +76,9 @@ export {
   claimExitForSignal,
   exitClaimedBySignal,
   killGraceMs,
-  setSettleBounds,
-  type SettleBound,
   settleWithin,
   teardownTimeoutMs,
+  testTimerMs,
 } from './settle.js'
 export { formatBytes, parseDuration, parseSize, treeBytes } from './size.js'
 export {
@@ -91,6 +99,13 @@ export { procfsIsOwn } from './procfs.js'
 export { hangupIgnored } from './hangup.js'
 export { ESSENTIAL_ENV } from './essential-env.js'
 export { gitEnv, helperEnv, hideEnvFromTasks } from './hide-env.js'
+export {
+  checkIgnore,
+  checkIgnoreSync,
+  ignoreProbes,
+  listedSync,
+  wholeIgnored,
+} from './git-ignored.js'
 export { realPath, realpathOf } from './real-path.js'
 export {
   maskedCommand,

package/src/util/report.ts

@@ -5,16 +5,24 @@ import { paint, type ColorSupport } from './colors.js'
 // are off.
 const GRADIENT_FROM = [0xa7, 0x8b, 0xfa] as const
 const GRADIENT_TO = [0xf4, 0x72, 0xb6] as const
-// Rule ends flush with the bars: 2 indent + 8 label + 2 gap + 50 cells.
-const RULE_DASHES = 57
+// The bars' label column: 2 indent + 8 label + 2 gap.
+const LABEL = 12
 
-/** Total visible rule width: `─ <mark> ` + dashes. Shared by the run summary and every report. */
+/** A meter's cells: 50, or fewer so the bar fits a narrower terminal. */
+export function barWidth(colors: ColorSupport): number {
+  const columns = colors.columns
+  return columns === undefined ? 50 : Math.max(10, Math.min(50, columns - LABEL))
+}
+
+/** `─ <mark> ` + dashes, flush with the bars. Shared by the run summary and every report. */
 export function gradientRule(colors: ColorSupport, mark = 'vx'): string {
   const head = `─ `
-  const dashes = '─'.repeat(Math.max(8, RULE_DASHES + 2 - mark.length))
+  const width = LABEL + barWidth(colors)
+  const dashes = '─'.repeat(Math.max(8, width - 3 - mark.length))
   if (!colors.enabled) return `${head}${mark} ${dashes}`
   const chunks = 8
-  const per = Math.ceil(RULE_DASHES / chunks)
+  // The gradient spans the rule as if its mark were `vx`.
+  const per = Math.ceil((width - 5) / chunks)
   let out = ''
   for (let i = 0; i < chunks; i++) {
     const seg = dashes.slice(i * per, (i + 1) * per)

package/src/util/settle.ts

@@ -7,54 +7,29 @@ import { parseDuration } from './size.js'
 /** Default upper bound on one end-of-run flush/teardown await. */
 const DEFAULT_TIMEOUT_MS = 3000
 
-/** A bound the run resolved from its flag or `.vx/workspace`. */
-export interface SettleBound {
-  readonly ms: number
-  readonly from: 'flag' | 'workspace'
-}
-
-let teardownSet: SettleBound | undefined
-let killGraceSet: SettleBound | undefined
-
-/**
- * The run's `run.teardownTimeout` and `run.killGrace` from its flag or
- * workspace (the orchestrator resolves them; util sits below settings).
- * The variable, read per call, sits between the two, so a test drives the
- * deadline instead of waiting it out.
- */
-export function setSettleBounds(b: { teardown?: SettleBound; killGrace?: SettleBound }): void {
-  teardownSet = b.teardown
-  killGraceSet = b.killGrace
-}
-
 /**
- * A flag's bound, else the variable's (a positive duration inside the
- * timer's range: the CLI refuses any other before a run, and an embedder's
- * falls back), else the workspace's.
+ * A timer a test shortens: `VX_TEST_<name>`, a duration. Undocumented and
+ * in no settings table: the suites that prove a deadline drive it instead
+ * of waiting the real one out. Zero only where `zero` allows it.
  */
-function bound(name: string, set: SettleBound | undefined, zero = false): number | undefined {
-  if (set?.from === 'flag') return set.ms
-  const raw = process.env[name]
-  if (raw !== undefined && raw !== '') {
-    const n = parseDuration(raw)
-    if (n !== null && (n > 0 || zero) && n <= MAX_TIMEOUT_MS) return n
-  }
-  return set?.ms
+export function testTimerMs(name: string, defaultMs: number, zero = false): number {
+  const raw = process.env[`VX_TEST_${name}`]
+  if (raw === undefined || raw === '') return defaultMs
+  const n = parseDuration(raw)
+  return n !== null && (n > 0 || (zero && n === 0)) && n <= MAX_TIMEOUT_MS ? n : defaultMs
 }
 
 /**
- * The bound on one end-of-run flush or teardown (`run.teardownTimeout`).
- * There is no "no limit": the deadline exists so a plugin's flush cannot
- * hold the run's exit hostage, so a timer past the platform's range (which
- * would fire at once and drop every buffered record) is no value.
+ * The bound on one end-of-run flush or teardown: a plugin's flush cannot
+ * hold the run's exit hostage.
  */
 export function teardownTimeoutMs(): number {
-  return bound('VX_RUN_TEARDOWN_TIMEOUT', teardownSet, true) ?? DEFAULT_TIMEOUT_MS
+  return testTimerMs('TEARDOWN_TIMEOUT', DEFAULT_TIMEOUT_MS, true)
 }
 
 /**
- * The SIGTERM→SIGKILL grace a run grants a child that ignores SIGTERM
- * (`run.killGrace`): the one-shot timeout escalation (`exec/runner.ts`),
+ * The SIGTERM→SIGKILL grace a run grants a child that ignores SIGTERM:
+ * the one-shot timeout escalation (`exec/runner.ts`),
  * the signal teardown (`orchestrator/signals.ts`) and the end-of-run
  * persistent shutdown (`orchestrator/persistent.ts`) share it. Two seconds
  * is generous for a real server's cleanup and is what every run waits when
@@ -63,7 +38,7 @@ export function teardownTimeoutMs(): number {
  * 200 ms grace proves too.
  */
 export function killGraceMs(defaultMs: number): number {
-  return bound('VX_RUN_KILL_GRACE', killGraceSet) ?? defaultMs
+  return testTimerMs('KILL_GRACE', defaultMs)
 }
 
 /**

package/src/util/tail.ts

@@ -6,7 +6,7 @@
 // needs a cap, and the cap has to be honest — a truncated log that reads as
 // complete is worse than one that says what it lost.
 //
-// `orchestrator/logger.ts` is the sole holder: it registers a tail per
+// `report/logger.ts` is the sole holder: it registers a tail per
 // persistent task at taskStart and keeps one for the rest of the run, so a
 // single mechanism covers both the pre-ready window and everything after.
 // `exec/runner.ts` used to keep a SECOND pre-ready copy fed from the same

package/src/util/ui.ts

@@ -3,14 +3,20 @@
 // color, indent and spacing, so every surface shares one look. Colors
 // are decided at print time, per stream.
 
-import { detectColors, ERROR, paint, SUCCESS, WARN, type ColorSupport } from './colors.js'
+import {
+  detectColors,
+  ERROR,
+  identityColor,
+  paint,
+  SUCCESS,
+  WARN,
+  type ColorSupport,
+} from './colors.js'
 import { gradientRule } from './report.js'
 
 export type Tone = 'ok' | 'warn' | 'error' | 'info'
 
 const INFO = '#06b6d4'
-const PROJECT = '#a78bfa'
-const TASK = '#f472b6'
 const HUE: Record<Tone, string> = { ok: SUCCESS, warn: WARN, error: ERROR, info: INFO }
 const SYMBOL: Record<Tone, string> = { ok: '✓', warn: '!', error: '✗', info: '›' }
 const INDENT = '  '
@@ -26,7 +32,7 @@ export interface Block {
   readonly lines: (colors: ColorSupport) => string[]
 }
 
-/** A `project#task` id, in the run's project and task hues. */
+/** A `project` or `project#task` id, each half in its name's hue, the `#` dim. */
 export const id = (text: string): Inline => ({ style: 'id', text })
 /** A path, glob or file: bold. */
 export const path = (text: string): Inline => ({ style: 'bold', text })
@@ -48,8 +54,13 @@ function inline(x: Inline, c: ColorSupport): string {
       return paint('', text, c, { bold: true })
     case 'id': {
       const hash = text.lastIndexOf('#')
-      if (hash < 0) return paint(PROJECT, text, c)
-      return paint(PROJECT, text.slice(0, hash), c) + paint(TASK, text.slice(hash), c)
+      if (hash < 0) return paint(identityColor(text), text, c)
+      const task = text.slice(hash + 1)
+      return (
+        paint(identityColor(text.slice(0, hash)), text.slice(0, hash), c) +
+        paint('', '#', c, { dim: true }) +
+        paint(identityColor(task), task, c)
+      )
     }
     default:
       return paint(HUE[style], text, c)

package/schemas/summary.json

@@ -1,133 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "vx run --summarize",
-  "description": "Every task's outcome in one run: <cacheDir>/runs/<runId>.json, or the --summarize=<path> file.",
-  "type": "object",
-  "additionalProperties": false,
-  "required": [
-    "runId",
-    "ok",
-    "exitCode",
-    "startedAt",
-    "endedAt",
-    "totalMs",
-    "savedMs",
-    "tasks",
-    "aborted",
-    "summary"
-  ],
-  "properties": {
-    "runId": { "type": "string" },
-    "ok": { "type": "boolean", "description": "the run's verdict: exitCode is 0" },
-    "exitCode": { "type": "integer" },
-    "startedAt": { "type": "string", "description": "ISO 8601" },
-    "endedAt": { "type": "string", "description": "ISO 8601" },
-    "totalMs": { "type": "number" },
-    "savedMs": {
-      "type": "number",
-      "description": "what the cache hits skipped: the sum of their storedDurationMs"
-    },
-    "tasks": {
-      "type": "array",
-      "description": "every counted task: not a group, not aborted",
-      "items": { "$ref": "#/$defs/task" }
-    },
-    "aborted": {
-      "type": "array",
-      "description": "tasks a shutdown signal killed; in no bucket and no total",
-      "items": { "$ref": "#/$defs/task" }
-    },
-    "summary": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": [
-        "successful",
-        "failed",
-        "skipped",
-        "cachedLocal",
-        "restoredLocal",
-        "restoredRemote",
-        "upToDate",
-        "cachedRemote",
-        "aborted",
-        "total"
-      ],
-      "properties": {
-        "successful": { "type": "integer" },
-        "failed": { "type": "integer" },
-        "skipped": { "type": "integer" },
-        "cachedLocal": { "type": "integer" },
-        "restoredLocal": { "type": "integer" },
-        "restoredRemote": { "type": "integer" },
-        "upToDate": { "type": "integer" },
-        "cachedRemote": { "type": "integer" },
-        "aborted": { "type": "integer" },
-        "total": { "type": "integer" }
-      }
-    }
-  },
-  "$defs": {
-    "task": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["id", "project", "task", "status", "exitCode", "durationMs", "hash"],
-      "properties": {
-        "id": { "type": "string" },
-        "project": { "type": "string" },
-        "task": { "type": "string" },
-        "status": {
-          "enum": ["success", "cache-hit", "cache-hit-remote", "failed", "skipped", "aborted"]
-        },
-        "exitCode": { "type": "integer" },
-        "durationMs": { "type": "number" },
-        "hash": { "type": ["string", "null"] },
-        "restored": {
-          "type": "boolean",
-          "description": "on a hit only: true when outputs were restored, false when they were already up to date"
-        },
-        "noCache": {
-          "const": true,
-          "description": "the task declares no cache block: it could never hit"
-        },
-        "flaky": {
-          "type": "object",
-          "description": "this key both passed and failed on record, or the task needed a retry",
-          "additionalProperties": false,
-          "required": ["passes", "failures", "attempts"],
-          "properties": {
-            "passes": { "type": "integer" },
-            "failures": { "type": "integer" },
-            "attempts": { "type": "integer" }
-          }
-        },
-        "cpuMs": { "type": "number" },
-        "peakRssBytes": { "type": "integer" },
-        "storedDurationMs": {
-          "type": "number",
-          "description": "a hit: how long the producing execution ran, what the hit skipped"
-        },
-        "storedCpuMs": {
-          "type": "number",
-          "description": "a hit: what the producing execution used"
-        },
-        "storedPeakRssBytes": { "type": "integer" },
-        "admissionHeldMs": {
-          "type": "number",
-          "description": "an admit policy held it with a worker free"
-        },
-        "blockedBy": {
-          "type": "string",
-          "description": "a skipped task: the failed task at the root of what blocked it"
-        },
-        "timedOut": { "const": true },
-        "sandboxViolations": { "type": "integer" },
-        "notReady": { "enum": ["timeout", "exited", "spawn"] },
-        "wallclockStartNs": {
-          "type": "string",
-          "description": "decimal nanoseconds from the run's start"
-        },
-        "wallclockEndNs": { "type": "string" }
-      }
-    }
-  }
-}