@vzn/vx 0.0.12 → 0.0.14

package/src/graph/task-graph.ts

@@ -1,7 +1,13 @@
 import type { TaskConfig } from '../config.js'
 import { UserError } from '../util/index.js'
 import type { PackageGraph, ProjectEntry } from '../workspace/index.js'
-import { DependencySpecError, parseDependencySpec, type DependencySpec } from './dependency-spec.js'
+import {
+  DependencySpecError,
+  compileTaskPattern,
+  isTaskPattern,
+  parseDependencySpec,
+  type DependencySpec,
+} from './dependency-spec.js'
 
 // Re-exported so existing importers keep working while the type's home
 // moves to workspace (it's the joint product of discovery + loading).
@@ -204,28 +210,50 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
       }
 
       // dependsOn is about which tasks to ADD to the graph, not which
-      // to filter. Wildcards and negation aren't meaningful here —
-      // they're cache.inputs.tasks operations.
+      // to filter. BARE wildcards ("*"/"^*" = "everything upstream") and
+      // negation aren't meaningful here — they're cache.inputs.tasks
+      // operations. PARTIAL patterns (`build.*`, `^build.*`) are legal:
+      // they name a namespace of tasks to add (Nx 19.5 parity).
       if (spec.kind === 'wildcardSelf' || spec.kind === 'wildcardDeps') {
-        throw new UserError(`Task ${id}: dependsOn does not accept wildcards (got "${raw}")`)
+        throw new UserError(`Task ${id}: dependsOn does not accept bare wildcards (got "${raw}")`)
       }
       if (spec.negated) {
         throw new UserError(`Task ${id}: dependsOn does not accept negation (got "${raw}")`)
       }
+      if (spec.kind === 'cross' && (isTaskPattern(spec.task) || isTaskPattern(spec.project))) {
+        throw new UserError(
+          `Task ${id}: dependsOn patterns are not supported in the "pkg#task" form (got "${raw}")`,
+        )
+      }
       // CLI `--excludeDependencies=name1,name2` drops edges whose target
       // task name matches, regardless of bucket (self / deps / cross).
+      // Pattern specs re-apply the filter per EXPANDED name below.
       if (skipNames?.has(spec.task)) continue
 
       if (spec.kind === 'self') {
-        // Missing target is a hard error — the user typed a name that
-        // doesn't resolve in this project.
-        const child = addNode(projectName, spec.task, false)
-        if (!child) {
-          throw new UserError(
-            `Task ${id} depends on ${taskId(projectName, spec.task)} but no such task is declared`,
-          )
+        if (isTaskPattern(spec.task)) {
+          // `build.*` — every OTHER same-project task matching the
+          // pattern (the declaring task never matches itself — that
+          // would be an instant self-cycle). Zero matches is legal: a
+          // preset-spread pattern needn't match in every project.
+          const re = compileTaskPattern(spec.task)
+          for (const name of Object.keys(project.config.tasks ?? {})) {
+            if (name === taskName || !re.test(name)) continue
+            if (skipNames?.has(name)) continue
+            const child = addNode(projectName, name, false)
+            if (child) node.deps.push(child.id)
+          }
+        } else {
+          // Missing target is a hard error — the user typed a name that
+          // doesn't resolve in this project.
+          const child = addNode(projectName, spec.task, false)
+          if (!child) {
+            throw new UserError(
+              `Task ${id} depends on ${taskId(projectName, spec.task)} but no such task is declared`,
+            )
+          }
+          node.deps.push(child.id)
         }
-        node.deps.push(child.id)
       } else if (spec.kind === 'deps') {
         // Nearest-holder frontier (Turbo/Nx direct-deps parity +
         // sparse bridging): walk the package dep graph from this
@@ -235,15 +263,36 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
         // through so a sparse dep doesn't break ordering to deeper
         // holders. The visited set both dedupes shared subtrees and
         // terminates on package-graph cycles (legal in PMs).
+        //
+        // With a pattern (`^build.*`), a holder is a package declaring
+        // AT LEAST ONE matching task and it receives edges to ALL its
+        // matches — holder-ness is about declaration, so a holder still
+        // stops the walk even when every match is --excludeDependencies'd.
+        const re = isTaskPattern(spec.task) ? compileTaskPattern(spec.task) : null
         const visited = new Set<string>()
         const frontier = [...packageGraph.directDeps(projectName)]
         while (frontier.length > 0) {
           const target = frontier.pop()!
           if (visited.has(target)) continue
           visited.add(target)
-          const child = addNode(target, spec.task, false)
-          if (child) node.deps.push(child.id)
-          else frontier.push(...packageGraph.directDeps(target))
+          if (re === null) {
+            const child = addNode(target, spec.task, false)
+            if (child) node.deps.push(child.id)
+            else frontier.push(...packageGraph.directDeps(target))
+          } else {
+            const names = Object.keys(projects.get(target)?.config.tasks ?? {}).filter((n) =>
+              re.test(n),
+            )
+            if (names.length > 0) {
+              for (const name of names) {
+                if (skipNames?.has(name)) continue
+                const child = addNode(target, name, false)
+                if (child) node.deps.push(child.id)
+              }
+            } else {
+              frontier.push(...packageGraph.directDeps(target))
+            }
+          }
         }
       } else {
         // Cross-project edge: pkg#task. Missing target is a hard error
@@ -258,8 +307,11 @@ export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode
       }
     }
 
-    // Stable ordering for deterministic scheduling and cache keys.
-    node.deps.sort()
+    // Stable ordering for deterministic scheduling and cache keys — deduped:
+    // a target named twice (an exact entry + a pattern matching it, or a
+    // literal duplicate) must contribute ONE edge, not a double-folded
+    // upstream hash and a doubled DOT edge.
+    node.deps = [...new Set(node.deps)].sort()
     return node
   }
 

package/src/index.ts

@@ -21,6 +21,7 @@ export type {
   CacheConfig,
   CacheInputs,
   CacheOutputs,
+  ResourcesConfig,
   SandboxConfig,
   SandboxNetworkConfig,
 } from './config.js'
@@ -52,7 +53,16 @@ export type {
 } from './orchestrator/index.js'
 export { defaultLogger, resolveOutputView } from './orchestrator/index.js'
 export { buildTaskGraph, expandRequested, isGroupTask, markSurfacedDeps } from './graph/index.js'
-export type { TaskNode, TaskOutcome, TaskStatus, VerifyVerdict } from './graph/index.js'
+export type {
+  OutputFingerprint,
+  TaskNode,
+  TaskOutcome,
+  TaskStatus,
+  VerifyVerdict,
+} from './graph/index.js'
+// The one output-tree diff implementation (verify verdicts + a serve's
+// cross-machine fingerprint diff both name rels through it).
+export { diffOutputTrees } from './orchestrator/index.js'
 
 // Cache classes + the layer interface (the `cache` capability's currency)
 // and input-output resolution. The blob-CAS/digest substrate
@@ -63,16 +73,29 @@ export type { TaskNode, TaskOutcome, TaskStatus, VerifyVerdict } from './graph/i
 export {
   Cache,
   LayeredCache,
-  RemoteCache,
   GitFilesCache,
   cleanOutputs,
   resolveInputs,
   resolveOutputs,
 } from './cache/index.js'
-export type { CacheLayer, RunRecord, InvocationRecord } from './cache/index.js'
+export type { CacheLayer, RemoteCacheLayer, RunRecord, InvocationRecord } from './cache/index.js'
 
-// Workspace discovery — an out-of-process service/CLI needs these.
+// Workspace discovery + the project/config catalog surface — an
+// out-of-process service/CLI needs these. `readLockfile` is THE one reader
+// of vx-lock.json (the format carries its own version sentinel; a second
+// parser in a sibling package would drift), and the loader chain
+// (`loadWorkspace` → `listProjectMetas` → `loadProjectConfig`) is the same
+// one `vx show` uses. Workspace's `listProjects` re-exports as
+// `listProjectMetas` — the bare name belongs to the metrics query below.
 export { findWorkspaceRoot, loadWorkspaceConfig, resolveCacheDir } from './workspace/index.js'
+export { readLockfile, LOCKFILE_NAME } from './workspace/index.js'
+export type { Lockfile, LockfileEntry } from './workspace/index.js'
+export {
+  loadWorkspace,
+  loadProjectConfig,
+  listProjects as listProjectMetas,
+} from './workspace/index.js'
+export type { ProjectMeta } from './workspace/index.js'
 
 // Plugin API — the run-level extension points. Behavior capabilities
 // (backend / cache) change WHAT/HOW work runs; the observe-only `telemetry`
@@ -181,8 +204,10 @@ export {
   getHitRateSplit,
   getInvocation,
   getParallelismHistory,
+  getPeriodComparison,
   getPrunableEntries,
   getRecentFailures,
+  getRegressions,
   getRun,
   getRunHeatmap,
   getRunTrends,

package/src/orchestrator/execute-task.ts

@@ -26,6 +26,7 @@ import { isGroupTask, type TaskNode, type TaskOutcome, type VerifyVerdict } from
 import {
   classifyDeterminism,
   diffOutputTrees,
+  foldFingerprint,
   hashOutputTree,
   outputRefs,
   undeclaredInputPaths,
@@ -83,13 +84,17 @@ export interface ExecuteArgs {
    * save and its outputs are content-compared; a divergence flags the task
    * non-hermetic. When `inputs` is set, an executed + cacheable task is
    * forced through the declared-input baseline sandbox and any read outside
-   * those inputs flags the declared `cache.inputs` as incomplete. `allow`
-   * exempts known-nondeterministic task ids from failing the run. Pure
-   * side-channel — the re-run never saves, nothing is hashed. Undefined = off.
+   * those inputs flags the declared `cache.inputs` as incomplete. When
+   * `fingerprint` is set, the executed task's output tree is fingerprinted
+   * and attached to the outcome (no re-run — the cross-machine diff feed).
+   * `allow` exempts known-nondeterministic task ids from failing the run.
+   * Pure side-channel — the re-run never saves, nothing is hashed.
+   * Undefined = off.
    */
   verify?: {
     determinism: boolean
     inputs: boolean
+    fingerprint: boolean
     allow: ReadonlySet<string>
   }
   /** Per-run memo for `git ls-files` (one entry per project dir). */
@@ -537,12 +542,23 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
         stdout: result.stdout,
       },
     })
-    // --verify: fingerprint attempt 1's outputs by CONTENT (mtime-independent,
-    // reusing the input-hashing OID primitive) so the determinism re-run below
-    // can prove the cached bytes are a pure function of the declared inputs.
-    if (args.verify?.determinism && outputFiles.length + wsOutputFiles.length > 0) {
+    // --verify: fingerprint attempt 1's outputs by CONTENT (raw bytes, never
+    // the mtime+size memo). The determinism re-run below compares against it,
+    // and the fingerprinting modes (`--verify`/`=all`/`=fingerprint`) fold it
+    // into the shipped `outputFp` — the cross-machine diff feed.
+    //
+    // Gate on DECLARED outputs (`outputs`/`wsOutputs` globs), not the
+    // RESOLVED file count: a task that declares `dist/**` but produces zero
+    // files this run must still ship the EMPTY tree, or the cross-machine
+    // diff can't pair it against a platform where the same glob DID match —
+    // a platform-conditional glob producing nothing on one OS is exactly
+    // the divergence Phase 4 exists to catch. The empty fold is well-defined
+    // (a fixed sentinel tree), so two both-empty platforms stay silent.
+    if (
+      (args.verify?.fingerprint || args.verify?.determinism) &&
+      outputs.length + wsOutputs.length > 0
+    ) {
       verifyFp1 = await hashOutputTree(
-        cache,
         outputRefs(node.projectDir, outputFiles, args.workspaceRoot, wsOutputFiles),
       )
     }
@@ -618,7 +634,14 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     willWrite &&
     !result.timedOut
   ) {
-    if (verifyFp1 === undefined) {
+    // Determinism verdict is keyed on RESOLVED outputs (unchanged): a task
+    // that declares outputs but produced none this run has nothing to
+    // content-compare, so it stays `no-outputs` with no re-run — even though
+    // `verifyFp1` is now the (empty) declared-outputs fingerprint that
+    // `--verify=fingerprint` ships for the cross-machine diff. `verifyFp1`
+    // is keyed by resolved output file, so an empty map means "declared but
+    // produced nothing" — the in-scope stand-in for the resolved-zero count.
+    if (verifyFp1 === undefined || verifyFp1.size === 0) {
       verify = { kind: 'no-outputs' } // cacheable but nothing to replay (e.g. lint)
     } else {
       const rerun = await runAttempt()
@@ -626,7 +649,6 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
         verify = { kind: 'rerun-failed', exitCode: rerun.exitCode }
       } else {
         const fp2 = await hashOutputTree(
-          cache,
           outputRefs(
             node.projectDir,
             await resolveOutputs({
@@ -646,14 +668,47 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
           args.verify.allow.has(node.id),
         )
       }
+      // Put attempt 1's saved bytes back so disk == the cached artifact
+      // REGARDLESS of the verdict. Mirror the restoreHit sequence exactly:
+      // clean the declared globs FIRST (a nondeterministic re-run may have
+      // written a stray filename the restore would never overwrite), then
+      // restore, then record the exact changed paths so a downstream
+      // same-project task's git snapshot can't go stale. fp1's keys ARE
+      // attempt 1's saved rels (bare project rels + workspace-outputs/-
+      // prefixed ws rels — the artifact namespace).
+      let cleanedRels: string[] = []
+      let cleanedWsRels: string[] = []
+      if (outputs.length > 0) cleanedRels = await cleanOutputs(cleanArgs)
+      if (wsOutputs.length > 0) cleanedWsRels = await cleanWorkspaceOutputs(wsCleanArgs)
       await cache.restoreOutputs(
         hash,
         node.projectDir,
         wsOutputs.length > 0 ? args.workspaceRoot : undefined,
       )
+      const savedKeys = [...verifyFp1.keys()]
+      if (outputs.length > 0) {
+        args.gitFilesCache?.markOutputsChanged(node.projectDir, [
+          ...cleanedRels,
+          ...savedKeys.filter((k) => !k.startsWith(WORKSPACE_OUTPUT_PREFIX)),
+        ])
+      }
+      if (wsOutputs.length > 0) {
+        args.gitFilesCache?.markWorkspaceOutputsChanged(args.workspaceRoot, [
+          ...cleanedWsRels,
+          ...savedKeys
+            .filter((k) => k.startsWith(WORKSPACE_OUTPUT_PREFIX))
+            .map((k) => k.slice(WORKSPACE_OUTPUT_PREFIX.length)),
+        ])
+      }
     }
   }
 
+  // Cross-machine diff feed: ship attempt 1's fingerprint (the SAVED bytes —
+  // the determinism re-run above never clobbers verifyFp1) so a connected
+  // serve can pair it with other platforms' reports for the same cache key.
+  const outputFp =
+    args.verify?.fingerprint && verifyFp1 !== undefined ? foldFingerprint(verifyFp1) : undefined
+
   return {
     node,
     status: effectiveExitCode === 0 ? 'success' : 'failed',
@@ -666,6 +721,7 @@ async function executeCachedTask(args: ExecuteArgs): Promise<TaskOutcome> {
     wallclockStartNs,
     wallclockEndNs,
     ...(verify !== undefined ? { verify } : {}),
+    ...(outputFp !== undefined ? { outputFp } : {}),
     ...(finalViolations.length > 0
       ? {
           sandboxViolations: finalViolations.length,

package/src/orchestrator/index.ts

@@ -95,6 +95,9 @@ export type {
   TelemetrySink,
   TelemetrySource,
 } from './telemetry.js'
+// `diffOutputTrees` is the ONE tree-diff implementation — the verify verdict
+// and a serve's cross-machine fingerprint diff must never drift on it.
+export { diffOutputTrees } from './verify.js'
 export { deriveStableKeys } from './stable-keys.js'
 export type { DeriveStableKeysArgs, StableKey } from './stable-keys.js'
 export { captureGitContext, captureWorkspaceIdentity, resolveCacheScope } from './run-context.js'
@@ -112,8 +115,10 @@ export {
   getHitRateSplit,
   getInvocation,
   getParallelismHistory,
+  getPeriodComparison,
   getPrunableEntries,
   getRecentFailures,
+  getRegressions,
   getRun,
   getRunHeatmap,
   getRunTrends,
@@ -149,8 +154,14 @@ export type {
   ListInvocationsArgs,
   ListRunsArgs,
   ParallelismPoint,
+  PeriodComparison,
+  PeriodComparisonArgs,
+  PeriodStats,
   PrunableEntry,
   ProjectRollup,
+  RegressedTask,
+  RegressionArgs,
+  TaskMover,
   RunDetail,
   RunSummaryRow,
   StoragePoint,