@vzn/vx 0.0.18 → 0.0.22

package/src/cli/why.ts

@@ -5,20 +5,25 @@
 // names the exact cache-key components that differ. Read-only over cache.db —
 // no config evaluation, no re-hash.
 
-import { Cache } from '../cache/index.js'
+import { Cache, noteSchemaReset } from '../cache/index.js'
+import { seeHelp } from './help.js'
 import { splitTaskId } from '../graph/index.js'
 import {
   cacheKeyDiff,
   explainCacheKeyQuery as explainCacheKey,
+  latestRunId,
   whyDidThisRerunQuery as whyDidThisRerun,
 } from '../orchestrator/index.js'
-import { UserError } from '../util/index.js'
-import { findWorkspaceRoot, loadWorkspaceConfig, resolveCacheDir } from '../workspace/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
 }
 
@@ -51,20 +56,37 @@ export function parseWhyArgs(args: readonly string[]): WhyArgs {
       out.format = fv
       continue
     }
-    if (a.startsWith('-')) return { ...out, error: `unknown flag: ${a}` }
+    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
 }
 
-/** Simple includes-match in both directions, case-insensitive. */
-function suggest(query: string, candidates: readonly string[]): string {
-  const q = query.toLowerCase()
-  const hits = candidates.filter((c) => {
-    const n = c.toLowerCase()
-    return n.includes(q) || q.includes(n)
-  })
+/**
+ * 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(', ')}?` : ''
 }
 
@@ -75,12 +97,21 @@ function suggest(query: string, candidates: readonly string[]): string {
  */
 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('#')) {
-    if (ids.includes(target)) return target
     throw new UserError(`vx why: no recorded runs for "${target}"${suggest(target, ids)}`)
   }
   const matches = ids.filter((id) => id.endsWith(`#${target}`))
@@ -94,19 +125,6 @@ function resolveTarget(cache: Cache, target: string): string {
   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> {
@@ -117,12 +135,12 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
   }
 
   const root = await findWorkspaceRoot(process.cwd())
-  const cacheDir = resolveCacheDir(root, await loadWorkspaceConfig(root))
-  const cache = new Cache(cacheDir)
+  const cache = Cache.inspect(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)
+    const runId = parsed.runId ?? latestRunId(cache.dbHandle(), taskId)
 
     if (runId === null) {
       // Runs exist (resolveTarget passed) but predate run ids — fall back to
@@ -155,9 +173,13 @@ export async function whyCmd(args: readonly string[]): Promise<number> {
     const lines: string[] = []
     const t = why.thisRun!
     lines.push(`${taskId} — run ${runId}`)
+    // A hit's status (`cache-hit`, `cache-hit-remote`) already names it and
+    // its tier; only an executed run needs the word. A skipped task never
+    // ran and has no key: it read `skipped · executed · key ` (item 898).
+    const ran = t.cacheHit === false && t.status !== 'skipped'
     lines.push(
       `  this run   ${fmtWhen(t.startedAt)} · ${t.status}` +
-        `${t.cacheHit === true ? ' · cache hit' : t.cacheHit === false ? ' · executed' : ''} · key ${t.hash}`,
+        `${ran ? ' · executed' : ''}${t.hash === '' ? ' · no key' : ` · key ${t.hash}`}`,
     )
     if (why.previousRun == null) {
       lines.push('  previous   (none — first recorded run of this task)')

package/src/cli/workspace-config.ts

@@ -0,0 +1,138 @@
+// 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 { existsSync } from 'node:fs'
+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) }
+}
+
+/**
+ * `--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 }
+}
+
+/**
+ * A reading verb's `--cache-dir`, resolved against the working directory.
+ * Named explicitly, a directory that is not there is a typo to report, not
+ * an empty cache to read (item 900).
+ */
+export function namedCacheDir(override: string): string {
+  const dir = path.resolve(process.cwd(), override)
+  if (!existsSync(dir)) throw new UserError(`--cache-dir ${override}: no such directory (${dir})`)
+  return dir
+}
+
+/**
+ * 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 namedCacheDir(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
+}
+
+/**
+ * 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).
+ */
+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, { read: true, write: true }, workspaceRoot)
+  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()
+  }
+}