@vzn/vx 0.0.16 → 0.0.21

package/src/workspace/config-cache.ts

@@ -0,0 +1,313 @@
+// Config evaluation cache — skip re-evaluating a `vx.config` that cannot
+// have changed.
+//
+// A config is a program, and evaluating a thousand of them is the largest
+// fixed cost of a warm run (measured 2026-09-02: ~80 ms to import 1000
+// synthetic configs, ~12 ms to read the same files as data). The cache
+// stores the VALIDATED, JSON-serialised result keyed by everything the
+// evaluation could have observed:
+//
+//   - the config's bytes and the bytes of every file it transitively imports
+//     by RELATIVE specifier (the closure), paths included;
+//   - the workspace fingerprint (lockfiles), which covers package imports;
+//   - Bun's version, vx's version and this module's own version. A stored
+//     evaluation is served WITHOUT re-validation, so it must never outlive
+//     the validator that accepted it — a vx upgrade that tightens a rule
+//     re-evaluates every config once.
+//
+// It applies only to configs that are PROVABLY pure by a conservative static
+// check: every import is relative or `@vzn/vx` (whose `defineProject` /
+// `defineWorkspace` are identity functions), and no file in the closure
+// mentions a global through which the environment can leak — `process`,
+// `Bun`, `Date`, `fetch`, `import.meta`, `require`, a dynamic `import()`,
+// `await`, … Anything else evaluates live, exactly as before. The check
+// fails SAFE, never fast: a false negative costs one evaluation, a false
+// positive would cost a stale key, so the deny-list is deliberately wide.
+//
+// JSON is already the contract for a config object — `hashTaskConfig` and
+// `vx lock` both go through `JSON.stringify` — so a cached config derives
+// the same cache key as a live evaluation of the same bytes.
+
+import { realpathSync } from 'node:fs'
+import path from 'node:path'
+import { xxh3 } from '../util/index.js'
+import { VERSION } from '../version.js'
+
+/** Bump when the key derivation or the stored shape changes. */
+export const CONFIG_EVAL_VERSION = 2
+
+/** Where cached evaluations live; `Cache` implements it over `cache.db`. */
+export interface ConfigEvalStore {
+  /**
+   * The warm fast path (all optional; a store without them keys by bytes).
+   * `hashFile` is the file's git blob id behind an mtime/size/ctime/inode
+   * memo — no read when unchanged; `getConfigClosures` / `putConfigClosure`
+   * keep each config's ORDERED closure (the config first, then every
+   * relative import in discovery order), so a warm load keys the config by
+   * stat-hashing that list instead of reading and scanning every file
+   * (1,000 configs: 5 ms against 15, measured 2026-09-03). Sound because
+   * closure membership can only change by editing a listed file, which
+   * changes that file's hash and so the key; the one exception, an
+   * extensionless relative import whose resolution a new file could
+   * shadow, is never indexed.
+   */
+  hashFile?(file: string): Promise<string>
+  /**
+   * `hashFile` over many paths with one memo query; a path that cannot be
+   * stat'ed is absent. The warm load identifies every indexed closure's
+   * files through this in a single call when the store offers it.
+   */
+  hashFiles?(files: readonly string[]): Promise<Map<string, string>>
+  getConfigClosures?(configPaths: readonly string[]): Map<string, string[]>
+  putConfigClosure?(configPath: string, files: readonly string[]): void
+  getConfigEval(key: string): string | null
+  /**
+   * Many keys in one round-trip (optional; a store without it is asked per
+   * key). A warm 1000-project run paid 3.6 ms for 1,000 point lookups where
+   * one `IN` query costs 0.7 (measured 2026-09-03).
+   */
+  getConfigEvals?(keys: readonly string[]): Map<string, string>
+  putConfigEval(key: string, json: string): void
+}
+
+/** What `configEvalKey` learned besides the key, for the store's closure index. */
+export interface ConfigEvalKeyResult {
+  key: string
+  /** The config first, then every relative import in discovery order. */
+  closure: string[]
+  /** False when a relative import is extensionless — a new file could change its resolution. */
+  indexable: boolean
+}
+
+export interface ConfigEvalKeyArgs {
+  configPath: string
+  /**
+   * Per-file identity, the same function the store's warm path uses. Absent
+   * (tests, a store without one), the git blob id is computed from the
+   * bytes in-process.
+   */
+  hashFile?: (file: string) => Promise<string>
+  bytes: Uint8Array
+  workspaceFingerprint: string
+}
+
+/** Closure files beyond this count evaluate live — a preset tree this deep is not the case this serves. */
+const MAX_CLOSURE_FILES = 32
+
+// Globals through which an evaluation can observe something the file bytes
+// do not capture. Tested against the source with string literals and
+// comments removed (`stripLiterals`), because `node -e "process.exit(0)"`
+// is an ordinary command, not an impure config.
+// `global` and `self` are live objects in Bun (aliases of `globalThis`), so
+// a computed `global['proc' + 'ess']` reaches process without ever
+// spelling it; `Temporal` is a clock. All three were CACHED AS PURE before
+// they were listed (2026-09-03). `constructor` reaches `Function` through a
+// property name (`({}).constructor.constructor('return process')()`, the
+// body hidden in a literal the strip removes) and `localeCompare` answers
+// by the host locale; both listed 2026-09-09.
+const IMPURE_RE =
+  /\b(?:process|Bun|globalThis|global|self|fetch|Date|Temporal|Intl|crypto|performance|navigator|require|eval|Function|constructor|localeCompare|await|toLocale\w*)\b|import\s*\.\s*meta|Math\s*\.\s*random|\bimport\s*\(/
+
+// Static `import … from '…'` / `export … from '…'` / `import '…'` forms.
+// `[^;'"]*?` spans newlines, so multi-line specifier lists match.
+const IMPORT_RE =
+  /(?:^|[\n;])\s*(?:import|export)\b[^;'"]*?\bfrom\s*['"]([^'"]+)['"]|(?:^|[\n;])\s*import\s*['"]([^'"]+)['"]/g
+
+/** The one bare specifier a pure config may import: core's identity helpers and types. */
+const PURE_PACKAGE = '@vzn/vx'
+
+const decoder = new TextDecoder()
+
+/**
+ * `source` with every string literal, template literal and comment removed
+ * (template `${…}` expressions are kept — they are code). Returns `null`
+ * when a `/` in code position is neither a comment nor a division the
+ * lexer can prove: a regex literal can contain a quote, and a lexer that
+ * misreads one would swallow real code as a string — a false SAFE, the one
+ * outcome this module must never produce. Configs do not need regexes;
+ * such a config evaluates live.
+ */
+export function stripLiterals(source: string): string | null {
+  let out = ''
+  let i = 0
+  const n = source.length
+  // Brace depth per open template expression, so a `}` closing the
+  // expression is told apart from one closing an object literal inside it.
+  const templateDepth: number[] = []
+  while (i < n) {
+    const c = source[i]!
+    const next = source[i + 1]
+    if (c === '/' && next === '/') {
+      while (i < n && source[i] !== '\n') i++
+      continue
+    }
+    if (c === '/' && next === '*') {
+      const end = source.indexOf('*/', i + 2)
+      if (end === -1) return null
+      i = end + 2
+      continue
+    }
+    if (c === '/') return null
+    if (c === "'" || c === '"') {
+      i++
+      while (i < n && source[i] !== c) {
+        if (source[i] === '\\') i++
+        if (source[i] === '\n') return null
+        i++
+      }
+      if (i >= n) return null
+      i++
+      out += ' '
+      continue
+    }
+    if (c === '`') {
+      i++
+      for (;;) {
+        if (i >= n) return null
+        const t = source[i]!
+        if (t === '\\') {
+          i += 2
+          continue
+        }
+        if (t === '`') {
+          i++
+          break
+        }
+        if (t === '$' && source[i + 1] === '{') {
+          templateDepth.push(0)
+          i += 2
+          out += ' '
+          break
+        }
+        i++
+      }
+      continue
+    }
+    if (templateDepth.length > 0) {
+      const top = templateDepth.length - 1
+      if (c === '{') templateDepth[top]!++
+      else if (c === '}') {
+        if (templateDepth[top] === 0) {
+          // Back into the template literal: resume scanning its text.
+          templateDepth.pop()
+          i++
+          for (;;) {
+            if (i >= n) return null
+            const t = source[i]!
+            if (t === '\\') {
+              i += 2
+              continue
+            }
+            if (t === '`') {
+              i++
+              break
+            }
+            if (t === '$' && source[i + 1] === '{') {
+              templateDepth.push(0)
+              i += 2
+              break
+            }
+            i++
+          }
+          out += ' '
+          continue
+        }
+        templateDepth[top]!--
+      }
+    }
+    out += c
+    i++
+  }
+  return out
+}
+
+/**
+ * The cache key for evaluating `configPath`, or `null` when the config is
+ * not provably pure (or its closure cannot be read), in which case the
+ * caller evaluates live and stores nothing.
+ */
+/** `git hash-object` of `bytes` (sha1 domain), the identity `Cache.hashFile` returns for a sha1 repo. */
+export function blobOidOf(bytes: Uint8Array): string {
+  const hasher = new Bun.CryptoHasher('sha1')
+  hasher.update(`blob ${bytes.byteLength}\0`)
+  hasher.update(bytes)
+  return hasher.digest('hex')
+}
+
+function keySeed(workspaceFingerprint: string): bigint {
+  return xxh3(
+    `vx-config-eval-v${CONFIG_EVAL_VERSION}\0${VERSION}\0${Bun.version}\0${workspaceFingerprint}\0`,
+  )
+}
+
+const EXPLICIT_EXT = /\.(?:m?[jt]s|cjs|cts)$/
+
+export async function configEvalKey(a: ConfigEvalKeyArgs): Promise<ConfigEvalKeyResult | null> {
+  let h = keySeed(a.workspaceFingerprint)
+  const hashOf = a.hashFile ?? (async (_file: string, bytes?: Uint8Array) => blobOidOf(bytes!))
+  const visited = new Set<string>([a.configPath])
+  const closure: string[] = []
+  let indexable = true
+  const queue: Array<{ file: string; bytes: Uint8Array }> = [{ file: a.configPath, bytes: a.bytes }]
+  while (queue.length > 0) {
+    const { file, bytes } = queue.shift()!
+    const source = decoder.decode(bytes)
+    const code = stripLiterals(source)
+    // A backslash in code position is an identifier escape (`\u0070rocess`
+    // IS `process`) — the one spelling the deny-list cannot see. Refuse it.
+    if (code === null || code.includes('\\') || IMPURE_RE.test(code)) return null
+    const identity = a.hashFile ? await a.hashFile(file) : await hashOf(file, bytes)
+    h = xxh3(`${file}\0${identity}`, h)
+    closure.push(file)
+    for (const m of source.matchAll(IMPORT_RE)) {
+      const spec = m[1] ?? m[2]!
+      if (spec === PURE_PACKAGE) continue
+      if (!spec.startsWith('./') && !spec.startsWith('../')) return null
+      if (!EXPLICIT_EXT.test(spec)) indexable = false
+      let resolved: string
+      try {
+        // Real-pathed: `Bun.resolveSync` answers with the symlinked spelling
+        // on one call and the real one on another (a tmp workspace under
+        // /var vs /private/var), and the key folds the path — a spelling
+        // that drifts between runs is a spurious miss and a duplicated
+        // memo row.
+        resolved = realpathSync(Bun.resolveSync(spec, path.dirname(file)))
+      } catch {
+        return null
+      }
+      if (visited.has(resolved)) continue
+      if (resolved.split(path.sep).includes('node_modules')) return null
+      visited.add(resolved)
+      if (visited.size > MAX_CLOSURE_FILES) return null
+      try {
+        queue.push({ file: resolved, bytes: await Bun.file(resolved).bytes() })
+      } catch {
+        return null
+      }
+    }
+  }
+  return { key: h.toString(16).padStart(16, '0'), closure, indexable }
+}
+
+/**
+ * The warm path: the key for a config whose ordered closure the store
+ * remembers, from per-file identities alone — no read, no scan. The fold is
+ * byte-identical to `configEvalKey`'s, so the two paths share entries. A
+ * changed or vanished file changes its identity and misses, and the slow
+ * path then re-indexes.
+ */
+export async function configEvalKeyFromClosure(a: {
+  closure: readonly string[]
+  hashFile: (file: string) => Promise<string>
+  workspaceFingerprint: string
+}): Promise<string | null> {
+  let h = keySeed(a.workspaceFingerprint)
+  let identities: string[]
+  try {
+    identities = await Promise.all(a.closure.map((f) => a.hashFile(f)))
+  } catch {
+    return null
+  }
+  for (let i = 0; i < a.closure.length; i++) h = xxh3(`${a.closure[i]}\0${identities[i]}`, h)
+  return h.toString(16).padStart(16, '0')
+}

package/src/workspace/config-eval.ts

@@ -0,0 +1,217 @@
+// Re-evaluating a project config, import closure included, inside a
+// long-lived process.
+//
+// The loader's query-string bust only changes the ENTRY's specifier.
+// Bun caches an evaluated module by its RESOLVED specifier, so an
+// `import './preset.js'` inside a config resolves to the same key no
+// matter what query the entry carries — a busted entry re-evaluates
+// against a STALE preset. Shared presets are the documented composition
+// mechanism (`vx migrate` generates one), so through a whole `vx watch`
+// session a preset edit was invisible; and because the resolved config
+// feeds the cache key, vx answered `up-to-date` for a command that had
+// changed on disk.
+//
+// A Worker gets its own module registry, so everything it imports is
+// read from disk NOW. It is the only mechanism for this that the
+// runtime exposes as public API: `globalThis.Loader.registry` — the
+// obvious place to evict from — exists on Bun 1.3.11 and is GONE on
+// 1.3.14, where an eviction-based fix degrades to no fix at all while
+// still reporting success.
+//
+// The worker source is an inline data: URL, not a sibling file, because
+// `bun build --compile` does NOT embed a Worker entry point — it
+// resolves the URL from disk at runtime, so a sibling file would make
+// the shipped standalone binary fail with ModuleNotFound.
+//
+// The config crosses back as JSON. That is already this project's
+// contract for a config object: `hashTaskConfig` derives the cache key
+// from `JSON.stringify(config)` and `vx lock` stores the same
+// round-trip, so a JSON round-trip cannot change how a config hashes,
+// locks or runs. `JSON.stringify(JSON.parse(s)) === s`, so a config
+// re-read through a worker derives the SAME cache key as the
+// in-process first load — which is why this needs no CACHE_VERSION bump.
+
+import path from 'node:path'
+import { MAX_TIMEOUT_MS } from '../util/index.js'
+
+const WORKER_SRC = `
+self.onmessage = async (e) => {
+  const { id, path } = e.data
+  try {
+    const ns = await import(path)
+    const mod = ns?.default
+    postMessage({
+      id,
+      ok: true,
+      json: mod !== null && typeof mod === 'object' ? JSON.stringify(mod) : null,
+    })
+  } catch (err) {
+    postMessage({
+      id,
+      ok: false,
+      name: err?.name ?? 'Error',
+      message: err?.message ?? String(err),
+      stack: err?.stack ?? null,
+      position:
+        err?.position && typeof err.position === 'object'
+          ? { file: err.position.file, line: err.position.line, column: err.position.column }
+          : null,
+    })
+  }
+}
+`
+
+const WORKER_URL = `data:text/javascript,${encodeURIComponent(WORKER_SRC)}`
+
+interface WorkerReply {
+  id: number
+  ok: boolean
+  json: string | null
+  name: string
+  message: string
+  stack: string | null
+  /** A transpile error's location — `BuildMessage.position`, trimmed to what the loader reads. */
+  position: { file?: string; line?: number; column?: number } | null
+}
+
+interface Pending {
+  resolve: (json: string | null) => void
+  reject: (err: Error) => void
+}
+
+/**
+ * How long a single config evaluation may take before we treat the worker as
+ * wedged. Real evaluations are ~10 ms; this exists only so a killed or hung
+ * worker cannot stall a long-lived process indefinitely. Read per call so a
+ * test can drive the deadline instead of waiting it out.
+ */
+function workerTimeoutMs(): number {
+  const raw = process.env['VX_CONFIG_WORKER_TIMEOUT_MS']
+  // Same kind of value as the teardown deadline, so the same treatment: a
+  // BOUND on a worker that may be wedged, with no "no limit" reading. Falls
+  // back rather than clamping, because honouring ~24.8 days would hang
+  // `vx watch` forever on a worker the OS killed — and unbounded makes it 1 ms,
+  // so EVERY config load times out instead. Both ends break the same feature.
+  if (raw !== undefined && /^[0-9]+$/.test(raw)) {
+    const n = Number(raw)
+    if (n <= MAX_TIMEOUT_MS) return n
+  }
+  return 30_000
+}
+
+const pending = new Map<number, Pending>()
+let worker: Worker | null = null
+let inFlight = 0
+let nextId = 0
+let workersCreated = 0
+
+/**
+ * Workers created so far. Exported solely so a test can pin that ONE
+ * worker serves a whole concurrent round — the property that keeps a
+ * 1000-project watch cycle at one worker instead of a thousand.
+ */
+export function configEvalWorkerCount(): number {
+  return workersCreated
+}
+
+function rejectAll(err: Error): void {
+  for (const p of pending.values()) p.reject(err)
+  pending.clear()
+}
+
+/**
+ * The worker serving the current round. Every load that is in flight at
+ * the same moment shares it, and it is retired once the last of them
+ * settles — so a `Promise.all` round costs ONE worker, and the next
+ * round (the next watch cycle) still starts from an empty registry.
+ *
+ * Sharing within a round is also the more faithful semantics: two
+ * configs importing the same preset evaluate it once, exactly as they
+ * would in a fresh `vx run` process.
+ */
+function acquireWorker(): Worker {
+  if (worker !== null) return worker
+  const w = new Worker(WORKER_URL)
+  workersCreated++
+  w.onmessage = (event: MessageEvent): void => {
+    const msg = event.data as WorkerReply
+    const p = pending.get(msg.id)
+    if (p === undefined) return
+    pending.delete(msg.id)
+    if (msg.ok) {
+      p.resolve(msg.json)
+      return
+    }
+    // Rebuild the error the config actually threw. Name, message, stack
+    // and a transpile error's position all survive the hop, so a broken
+    // config reports the same text it would from an in-process import.
+    const err = new Error(msg.message) as Error & { position?: WorkerReply['position'] }
+    err.name = msg.name
+    if (msg.stack !== null) err.stack = msg.stack
+    if (msg.position !== null) err.position = msg.position
+    p.reject(err)
+  }
+  w.onerror = (event: ErrorEvent): void => {
+    rejectAll(new Error(`config worker failed: ${String(event.message)}`))
+  }
+  // A reply that cannot be deserialized would otherwise leave its caller
+  // awaiting forever — every path off this worker must settle its pending
+  // promises, including the ones that carry no usable payload.
+  w.addEventListener('messageerror', () => {
+    rejectAll(new Error('config worker sent an undeserializable reply'))
+  })
+  worker = w
+  return w
+}
+
+/**
+ * Evaluate `configPath` against a fresh module registry and return its
+ * default export, JSON round-tripped. `null` means the module had no
+ * object default export — the caller owns that error message so it
+ * reads identically whichever path produced it.
+ */
+export async function evaluateConfigFresh(configPath: string): Promise<unknown> {
+  const abs = path.resolve(configPath)
+  const id = nextId++
+  inFlight++
+  // Declared out here so the `finally` can clear it on EVERY exit, including a
+  // rejection. See the note at the clear itself.
+  let timer: ReturnType<typeof setTimeout> | undefined
+  try {
+    const w = acquireWorker()
+    // A worker thread the OS kills — memory pressure on a loaded CI box, a
+    // hard crash — fires no `error` event, so without a deadline this await
+    // never settles and `vx watch` hangs forever on a cycle that would
+    // otherwise take milliseconds. Nothing else bounds it: there is no
+    // run-level timeout. The budget is enormous next to the ~10 ms a real
+    // evaluation costs, so it can only fire on a genuine wedge.
+    const budget = workerTimeoutMs()
+    const json = await new Promise<string | null>((resolve, reject) => {
+      pending.set(id, { resolve, reject })
+      timer = setTimeout(() => {
+        rejectAll(new Error(`config worker did not answer within ${budget}ms`))
+        if (worker !== null) {
+          worker.terminate()
+          worker = null
+        }
+      }, budget)
+      timer.unref?.()
+      w.postMessage({ id, path: abs })
+    })
+    return json === null ? null : (JSON.parse(json) as unknown)
+  } finally {
+    // In the `finally`, not after the await: a REJECTED evaluation — a config
+    // with a typo, the common case while editing — would otherwise skip the
+    // clear and leave its timer armed for the whole budget. When that orphan
+    // later fired it ran `rejectAll()` and terminated whatever worker was
+    // current by then, killing an unrelated healthy round with a timeout
+    // message naming a budget nobody set for it.
+    clearTimeout(timer)
+    pending.delete(id)
+    inFlight--
+    if (inFlight === 0 && worker !== null) {
+      worker.terminate()
+      worker = null
+    }
+  }
+}

package/src/workspace/config-imports.ts

@@ -0,0 +1,162 @@
+// The third `changed file → project` channel for `--affected`.
+//
+// Directory containment answers "which project owns this file", and
+// `cache.inputs.workspaceFiles` answers "which project declared it". Neither
+// can see the one remaining way a file reaches a task: a project's
+// `vx.config.*` IMPORTS it. Resolved-config hashing folds the imported values
+// into the cache key (architecture principle #4), so editing such a file
+// re-keys the task — and `affected.ts` states the rule this exists to keep:
+// "input hashing sees it, so `--affected` must too."
+//
+// This is a STATIC scan. Nothing is evaluated: `Bun.Transpiler.scanImports`
+// reads the specifiers and `Bun.resolveSync` turns them into paths. The
+// `project-loader.ts` note that a bust "cannot reach the config's import
+// closure" is about `import()` at runtime, not about reading the source.
+//
+// Two rules keep the walk small, and the second is the one that makes it
+// affordable at all:
+//
+//   - RELATIVE specifiers only. A bare specifier is a package; it moves when
+//     the lockfile moves, which the workspace fingerprint already covers.
+//   - Descend only through files owned by NO project. A config reaching into
+//     another project (say a site's `vx.config.ts` importing
+//     `../core/src/index.ts`) records that edge and STOPS there — following
+//     it would drag substantially all of that project's `src/` into the
+//     closure, and the containment channel already selects the project that
+//     owns it.
+
+import { realpath } from 'node:fs/promises'
+import path from 'node:path'
+import type { ProjectMeta } from './workspace.js'
+
+/**
+ * Absolute resolved targets of the RELATIVE specifiers in `source`.
+ *
+ * Paths come back realpath'd, because `Bun.resolveSync` realpaths them — see
+ * the caller, which realpaths everything it compares against for exactly that
+ * reason. `import type` is erased by `scanImports` and so contributes no edge,
+ * which is correct: an erased import cannot move a resolved value.
+ */
+function scanLocalImports(source: string, fromDir: string, loader: 'ts' | 'js'): string[] {
+  let specifiers: string[]
+  try {
+    specifiers = new Bun.Transpiler({ loader }).scanImports(source).map((i) => i.path)
+  } catch {
+    return [] // unparseable source contributes no edges
+  }
+  const out: string[] = []
+  for (const spec of specifiers) {
+    if (!spec.startsWith('./') && !spec.startsWith('../')) continue
+    try {
+      out.push(Bun.resolveSync(spec, fromDir))
+    } catch {
+      // Unresolvable (deleted, typo, extensionless miss) — a config that will
+      // not load cannot be shown to import anything, and failing selection
+      // over it would break a working build.
+    }
+  }
+  return out
+}
+
+export interface ConfigImportOwnersArgs {
+  /**
+   * Realpath'd HERE, not by the caller. `Bun.resolveSync` returns realpath'd
+   * targets, so a raw root silently fails every containment check and the
+   * scan reports "no imports" — indistinguishable from a clean tree. Owning
+   * the normalisation in one place makes that misuse unrepresentable.
+   */
+  workspaceRoot: string
+  projects: readonly ProjectMeta[]
+  /** Workspace-relative POSIX paths — the same list containment consumed. */
+  changed: readonly string[]
+  /** Already-selected projects; their configs need no scan. */
+  skip: ReadonlySet<string>
+}
+
+/**
+ * Project dir → name, REALPATH'D — which is why this cannot reuse the index
+ * the containment pass builds. `Bun.resolveSync` hands back realpath'd
+ * targets, and on darwin a workspace under `os.tmpdir()` lives at
+ * `/var/folders/…` while its realpath is `/private/var/folders/…`; comparing
+ * the two matches nothing and fails exactly like "found no imports".
+ */
+async function realDirIndex(projects: readonly ProjectMeta[]): Promise<Map<string, string>> {
+  const out = new Map<string, string>()
+  await Promise.all(
+    projects.map(async (p) => {
+      out.set(await realpath(p.dir).catch(() => p.dir), p.name)
+    }),
+  )
+  return out
+}
+
+const TS_EXT = new Set(['.ts', '.mts', '.cts'])
+
+/** The deepest project containing `file`, or undefined when none does. */
+function ownerOf(file: string, dirToName: ReadonlyMap<string, string>): string | undefined {
+  let dir = path.dirname(file)
+  for (;;) {
+    const name = dirToName.get(dir)
+    if (name !== undefined) return name
+    const parent = path.dirname(dir)
+    if (parent === dir) return undefined
+    dir = parent
+  }
+}
+
+/** Projects whose config file transitively imports one of `changed`. */
+export async function configImportOwners(a: ConfigImportOwnersArgs): Promise<Set<string>> {
+  const selected = new Set<string>()
+  if (a.changed.length === 0 || a.skip.size === a.projects.length) return selected
+  const workspaceRoot = await realpath(a.workspaceRoot).catch(() => a.workspaceRoot)
+
+  const roots = new Map<string, string>() // abs config path → project name
+  await Promise.all(
+    a.projects.map(async (p) => {
+      const cfg = p.configPath
+      if (cfg === null || cfg === '' || a.skip.has(p.name)) return
+      roots.set(await realpath(cfg).catch(() => path.resolve(cfg)), p.name)
+    }),
+  )
+  if (roots.size === 0) return selected
+  const dirToName = await realDirIndex(a.projects)
+
+  // target → the files that import it. Reversed up front so one BFS from the
+  // changed set answers every root at once, instead of a walk per root.
+  const importedBy = new Map<string, string[]>()
+  const visited = new Set<string>()
+  const queue = [...roots.keys()]
+  while (queue.length > 0) {
+    const file = queue.pop()!
+    if (visited.has(file)) continue
+    visited.add(file)
+    let source: string
+    try {
+      source = await Bun.file(file).text()
+    } catch {
+      continue // unreadable: no edges, and not this pass's problem to report
+    }
+    const loader = TS_EXT.has(path.extname(file)) ? 'ts' : 'js'
+    for (const target of scanLocalImports(source, path.dirname(file), loader)) {
+      if (!target.startsWith(workspaceRoot + path.sep)) continue
+      if (target.split(path.sep).includes('node_modules')) continue
+      const list = importedBy.get(target)
+      if (list) list.push(file)
+      else importedBy.set(target, [file])
+      // Descend ONLY through unowned files — see the header.
+      if (ownerOf(target, dirToName) === undefined) queue.push(target)
+    }
+  }
+
+  const seen = new Set<string>()
+  const walk = [...a.changed.map((rel) => path.resolve(workspaceRoot, rel))]
+  while (walk.length > 0) {
+    const file = walk.pop()!
+    if (seen.has(file)) continue
+    seen.add(file)
+    const owner = roots.get(file)
+    if (owner !== undefined) selected.add(owner)
+    for (const importer of importedBy.get(file) ?? []) walk.push(importer)
+  }
+  return selected
+}