@vzn/vx 0.0.16 → 0.0.21

package/src/cli/why.ts

@@ -0,0 +1,223 @@
+// `vx why [pkg#task | task]` — answer "why did this task re-run?" from the
+// terminal. The same persisted data the MCP `whyDidThisRerun` tool reads:
+// the runs table names the
+// run-over-run hash change, and `entry_inputs` (the input-fingerprint moat)
+// names the exact cache-key components that differ. Read-only over cache.db —
+// no config evaluation, no re-hash.
+
+import { Cache, noteSchemaReset } from '../cache/index.js'
+import { seeHelp } from './help.js'
+import { splitTaskId } from '../graph/index.js'
+import {
+  cacheKeyDiff,
+  explainCacheKeyQuery as explainCacheKey,
+  whyDidThisRerunQuery as whyDidThisRerun,
+} from '../orchestrator/index.js'
+import { nearMatches, UserError } from '../util/index.js'
+import { findWorkspaceRoot } from '../workspace/index.js'
+import { cliCacheDir, parseCacheDirFlag, warnToStderr } from './workspace-config.js'
+
+interface WhyArgs {
+  target?: string
+  runId?: string
+  format: 'pretty' | 'json'
+  /** `--cache-dir`: read the history a run with the same flag wrote. */
+  cacheDir?: string
+  error?: string
+}
+
+export function parseWhyArgs(args: readonly string[]): WhyArgs {
+  const out: WhyArgs = { format: 'pretty' }
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!
+    // Match on the flag NAME first. Reading the value into the same
+    // `undefined` that means "not this flag" conflated the two: a trailing
+    // `--run` (value omitted) consumed a non-existent argv slot, fell through,
+    // and was reported as `unknown flag: --run` — false, since `--run` is very
+    // much known, and silent about the real mistake. The `=` spelling of the
+    // same mistake already said `invalid --run: empty`, so one omitted value
+    // got two different diagnoses depending on how it was typed.
+    if (a === '--run' || a.startsWith('--run=')) {
+      const rv = a === '--run' ? args[++i] : a.slice(6)
+      if (rv === undefined || rv === '') return { ...out, error: 'invalid --run: empty' }
+      out.runId = rv
+      continue
+    }
+    if (a === '--format' || a.startsWith('--format=')) {
+      const fv = a === '--format' ? args[++i] : a.slice(9)
+      if (fv !== 'pretty' && fv !== 'json') {
+        // An omitted value reads as empty, not as the literal word "undefined".
+        return {
+          ...out,
+          error: `invalid --format: ${fv ?? ''} (expected pretty | json)`,
+        }
+      }
+      out.format = fv
+      continue
+    }
+    const cd = parseCacheDirFlag(args, i)
+    if (cd !== null) {
+      if ('error' in cd) return { ...out, error: cd.error }
+      out.cacheDir = cd.cacheDir
+      i = cd.next
+      continue
+    }
+    if (a.startsWith('-')) return { ...out, error: `unknown flag: ${a}${seeHelp('why')}` }
+    if (out.target !== undefined) return { ...out, error: `unexpected argument: ${a}` }
+    out.target = a
+  }
+  return out
+}
+
+/**
+ * A bare query is a TASK name, so it is matched against the task half of
+ * every recorded id (the same rule `vx run` hints with) and the hint is
+ * the runnable `project#task`; an anchored query is matched whole.
+ */
+function suggest(query: string, ids: readonly string[]): string {
+  let hits: string[]
+  if (query.includes('#')) {
+    hits = nearMatches(query, ids)
+  } else {
+    const byTask = new Map<string, string[]>()
+    for (const id of ids) {
+      const task = splitTaskId(id)[1]
+      byTask.set(task, [...(byTask.get(task) ?? []), id])
+    }
+    hits = nearMatches(query, byTask.keys()).flatMap((t) => byTask.get(t) ?? [])
+  }
+  return hits.length > 0 ? ` — did you mean ${hits.slice(0, 3).join(', ')}?` : ''
+}
+
+/**
+ * Resolve a positional target to a full `project#task` id against the runs
+ * table. A `pkg#task` form is used as-is; a bare task name matches every
+ * project that ran it — unique → resolved, several → error listing them.
+ */
+function resolveTarget(cache: Cache, target: string): string {
+  const db = cache.dbHandle()
+  if (target.includes('#')) {
+    // An exact id needs one row, and its newest is where a scan from the
+    // top of the table finds it first — the full DISTINCT walk below is for
+    // the error's suggestions and the bare-name form only.
+    const [project, task] = splitTaskId(target)
+    const hit = db
+      .query('SELECT 1 FROM runs WHERE project = ? AND task = ? ORDER BY id DESC LIMIT 1')
+      .get(project, task)
+    if (hit !== null) return target
+  }
+  const pairs = db
+    .query('SELECT DISTINCT project, task FROM runs ORDER BY project, task')
+    .all() as Array<{ project: string; task: string }>
+  const ids = pairs.map((p) => `${p.project}#${p.task}`)
+  if (target.includes('#')) {
+    throw new UserError(`vx why: no recorded runs for "${target}"${suggest(target, ids)}`)
+  }
+  const matches = ids.filter((id) => id.endsWith(`#${target}`))
+  if (matches.length === 1) return matches[0]!
+  if (matches.length > 1) {
+    throw new UserError(
+      `vx why: "${target}" ran in ${matches.length} projects — pick one:\n` +
+        matches.map((m) => `  ${m}`).join('\n'),
+    )
+  }
+  throw new UserError(`vx why: no recorded runs for task "${target}"${suggest(target, ids)}`)
+}
+
+/** The latest recorded run of a task (run_id may be NULL on very old rows). */
+function latestRunId(cache: Cache, taskId: string): string | null {
+  const [project, task] = splitTaskId(taskId)
+  const row = cache
+    .dbHandle()
+    .query(
+      `SELECT run_id AS runId FROM runs WHERE project = ? AND task = ?
+       ORDER BY started_at DESC LIMIT 1`,
+    )
+    .get(project, task) as { runId: string | null } | undefined
+  return row?.runId ?? null
+}
+
+const fmtWhen = (ms: number): string => new Date(ms).toISOString()
+
+export async function whyCmd(args: readonly string[]): Promise<number> {
+  const parsed = parseWhyArgs(args)
+  if (parsed.error !== undefined) throw new UserError(`vx why: ${parsed.error}`)
+  if (parsed.target === undefined) {
+    throw new UserError('vx why: <task> required (e.g. vx why app#build, or vx why build)')
+  }
+
+  const root = await findWorkspaceRoot(process.cwd())
+  const cache = new Cache(await cliCacheDir(root, parsed.cacheDir))
+  noteSchemaReset(cache, warnToStderr)
+  try {
+    const db = cache.dbHandle()
+    const taskId = resolveTarget(cache, parsed.target)
+    const runId = parsed.runId ?? latestRunId(cache, taskId)
+
+    if (runId === null) {
+      // Runs exist (resolveTarget passed) but predate run ids — fall back to
+      // the persisted entry metadata so the verb still says something useful.
+      const explanation = explainCacheKey(db, taskId)
+      if (parsed.format === 'json') {
+        process.stdout.write(`${JSON.stringify({ taskId, why: null, diff: null, explanation })}\n`)
+      } else {
+        process.stdout.write(
+          `${taskId}: recorded runs carry no run id — showing the latest cache entry instead\n` +
+            (explanation.latestEntry !== null
+              ? `  hash ${explanation.latestEntry.hash} · $ ${explanation.latestEntry.command}\n`
+              : '  (no cache entry either)\n'),
+        )
+      }
+      return 0
+    }
+
+    const why = whyDidThisRerun(db, runId, taskId)
+    if (!why.found) {
+      throw new UserError(`vx why: run ${runId} has no row for ${taskId}`)
+    }
+    const diff = cacheKeyDiff(db, runId, taskId)
+
+    if (parsed.format === 'json') {
+      process.stdout.write(`${JSON.stringify({ taskId, runId, why, diff })}\n`)
+      return 0
+    }
+
+    const lines: string[] = []
+    const t = why.thisRun!
+    lines.push(`${taskId} — run ${runId}`)
+    lines.push(
+      `  this run   ${fmtWhen(t.startedAt)} · ${t.status}` +
+        `${t.cacheHit === true ? ' · cache hit' : t.cacheHit === false ? ' · executed' : ''} · key ${t.hash}`,
+    )
+    if (why.previousRun == null) {
+      lines.push('  previous   (none — first recorded run of this task)')
+    } else {
+      const p = why.previousRun
+      lines.push(`  previous   ${fmtWhen(p.startedAt)} · ${p.status} · key ${p.hash}`)
+      lines.push(`  verdict    ${why.note}`)
+    }
+
+    if (diff.entries.length > 0) {
+      lines.push('')
+      lines.push(
+        `  what changed (${diff.entries.length} component${diff.entries.length === 1 ? '' : 's'}, ${diff.unchangedCount} unchanged):`,
+      )
+      const kindW = Math.max(...diff.entries.map((e) => e.kind.length), 4)
+      for (const e of diff.entries) {
+        const beforeAfter =
+          e.change === 'added'
+            ? `+ ${e.after}`
+            : e.change === 'removed'
+              ? `- ${e.before}`
+              : `${e.before} → ${e.after}`
+        lines.push(`    ${e.change.padEnd(7)} ${e.kind.padEnd(kindW)}  ${e.name}  ${beforeAfter}`)
+      }
+    } else if (why.hashChanged === true) {
+      lines.push(`  detail     ${diff.note}`)
+    }
+    process.stdout.write(`${lines.join('\n')}\n`)
+    return 0
+  } finally {
+    cache.close()
+  }
+}

package/src/cli/workspace-config.ts

@@ -0,0 +1,126 @@
+// The workspace as every verb must see it: the config with the plugin
+// `config` stage applied, and the cache dir derived from THAT. The stage
+// is documented to shape `cacheDir`; a verb that read the file raw opened
+// a directory the run never used — `vx last` found no runs, `vx cache
+// prune` pruned nothing, `vx watch` ignored the wrong path.
+
+import path from 'node:path'
+import type { WorkspaceConfig } from '../config.js'
+import { UserError } from '../util/index.js'
+import { Cache, noteSchemaReset } from '../cache/index.js'
+import { loadProjects, loadWorkspacePlugins } from '../orchestrator/index.js'
+import type { VxPlugin } from '../orchestrator/index.js'
+import {
+  buildPackageGraph,
+  computeWorkspaceFingerprint,
+  FROZEN_WITHOUT_LOCK,
+  type ProjectEntry,
+  type ProjectMeta,
+  readLockfile,
+  resolveCacheDir,
+} from '../workspace/index.js'
+
+export interface CliWorkspace {
+  workspaceConfig: WorkspaceConfig | null
+  plugins: readonly VxPlugin[]
+  cacheDir: string
+}
+
+export const warnToStderr = (message: string): void => {
+  process.stderr.write(`${message}\n`)
+}
+
+export async function loadCliWorkspace(workspaceRoot: string): Promise<CliWorkspace> {
+  const { workspaceConfig, plugins } = await loadWorkspacePlugins(workspaceRoot, warnToStderr)
+  return { workspaceConfig, plugins, cacheDir: resolveCacheDir(workspaceRoot, workspaceConfig) }
+}
+
+/**
+ * The run path's project-config load (`loadProjects`) for a verb that only
+ * reads: the plugin `project` stage applies, and the local cache opens only
+ * to serve cached evaluations — a pure config costs a stat, not an
+ * evaluation. `scope` is every project or a list of names; no closure, no
+ * lock (a verb reads live, as a default run does).
+ */
+/**
+ * `--cache-dir <path>` / `--cache-dir=<path>` for a verb that reads the
+ * cache a run wrote — `why`, `last`, `info`, `cache prune`. Same rules as
+ * `vx run`'s: a value is required, and the space form refuses a value
+ * that looks like a flag (an unquoted empty shell variable would otherwise
+ * swallow the next flag as the path). Returns null when `args[i]` is not
+ * this flag; `next` is the index of the last argv slot consumed.
+ */
+export function parseCacheDirFlag(
+  args: readonly string[],
+  i: number,
+): { cacheDir: string; next: number } | { error: string } | null {
+  const a = args[i]!
+  if (a !== '--cache-dir' && !a.startsWith('--cache-dir=')) return null
+  const v = a === '--cache-dir' ? args[i + 1] : a.slice('--cache-dir='.length)
+  if (v === undefined || v === '') return { error: '--cache-dir requires a path' }
+  if (a === '--cache-dir' && v.startsWith('-')) {
+    return { error: `--cache-dir requires a path, got flag: ${v}` }
+  }
+  return { cacheDir: v, next: a === '--cache-dir' ? i + 1 : i }
+}
+
+/**
+ * The cache directory a reading verb opens: `--cache-dir` resolved against
+ * cwd exactly as `vx run` resolves it (prepare.ts), else the workspace's —
+ * so `vx run --cache-dir X` and `vx last --cache-dir X` read one history.
+ */
+export async function cliCacheDir(
+  workspaceRoot: string,
+  override: string | undefined,
+): Promise<string> {
+  if (override !== undefined) return path.resolve(process.cwd(), override)
+  return (await loadCliWorkspace(workspaceRoot)).cacheDir
+}
+
+/** The run flags a verb's staged load must honour to see what the run sees. */
+export interface CliLoadOptions {
+  /** `--cache-dir`: where the cached evaluations live. */
+  cacheDir?: string
+  /** `--frozen`: configs come from `vx-lock.json`, not evaluation. */
+  frozen?: boolean
+}
+
+export async function loadCliProjects(
+  workspaceRoot: string,
+  metas: readonly ProjectMeta[],
+  scope: 'all' | readonly string[] = 'all',
+  opts: CliLoadOptions = {},
+): Promise<Map<string, ProjectEntry>> {
+  const ws = await loadCliWorkspace(workspaceRoot)
+  const { plugins } = ws
+  // The cached evaluations live where the run's do: a verb given
+  // `--cache-dir` must not open (and create) the workspace's default one.
+  const cacheDir = opts.cacheDir ?? ws.cacheDir
+  // A frozen run reads its configs from the lock; what it SELECTS must be
+  // decided from the same configs, or an env-dependent `workspaceFiles`
+  // glob could select live what the run then treats otherwise.
+  const lock = opts.frozen === true ? await readLockfile(workspaceRoot) : null
+  if (opts.frozen === true && lock === null) throw new UserError(FROZEN_WITHOUT_LOCK)
+  const cache = new Cache(cacheDir)
+  noteSchemaReset(cache, warnToStderr)
+  try {
+    const loaded = await loadProjects({
+      workspaceRoot,
+      cacheDir,
+      plugins,
+      projectMetas: metas,
+      packageGraph: buildPackageGraph([...metas]),
+      seeds: scope,
+      closure: false,
+      lock,
+      evalCache: {
+        store: cache,
+        workspaceFingerprint: await computeWorkspaceFingerprint(workspaceRoot),
+      },
+      warn: warnToStderr,
+    })
+    return loaded.projects
+  } finally {
+    cache.close()
+  }
+}