@vzn/vx 0.0.646 → 0.0.648

package/src/workspace/workspace.ts

@@ -1,4 +1,4 @@
-// What a project is (owner, 2026-10-14): a directory holding a
+// What a project is (2026-10-14): a directory holding a
 // `vx.config.*`. `vx lock` finds them (`findProjectConfigs`) and records
 // each by directory; a run takes them from the lock (`lockedProjects`) and
 // never walks. A project is named by `name` in its config, else by a
@@ -13,13 +13,17 @@ import {
   executablePath,
   gitEnv,
   gitSpawnRefusal,
+  hasControl,
   isExecutableMissing,
   isOutOfFds,
+  printable,
   refusal,
   relPosix,
   UserError,
 } from '../util/index.js'
-import { gitTop, workspaceFile, workspaceRootOf } from '../handoff.js'
+import { gitTop, WORKSPACE_CONFIG_FILENAMES, workspaceFile, workspaceRootOf } from '../handoff.js'
+import { canonicalDir } from './canonical-dir.js'
+import { parseFilter } from './filter.js'
 import { repoIdOf } from './repo-id.js'
 
 export interface ProjectMeta {
@@ -57,7 +61,7 @@ export const PROJECT_CONFIG_FILENAMES = [
  * The workspace root for `start`: the directory holding the first
  * `.vx/workspace.*` from `start` up to the git top-level, or up to `/`
  * outside git ({@link workspaceFile}, shared with the hand-off). Nothing
- * else decides it (owner, 2026-10-13: "Workspace file is the ultimate"):
+ * else decides it (2026-10-13: "Workspace file is the ultimate"):
  * not a `package.json`, not `pnpm-workspace.yaml`, not a lockfile. Throws
  * `VX_E_NO_WORKSPACE` when there is none.
  *
@@ -138,7 +142,7 @@ export function resolveCacheDir(root: string, config: WorkspaceConfig | null): s
 
 /**
  * Where this repository's shared store lives: `~/.vx/<repo id>/cache`, as
- * Nx 23 keeps `~/.nx/<id>/cache` (owner, 2026-10-06), so every checkout of
+ * Nx 23 keeps `~/.nx/<id>/cache` (2026-10-06), so every checkout of
  * the repository hits what another saved and no other repository shares
  * it (`repoIdOf`). Null when the workspace names its cache (`cache.dir`,
  * `VX_CACHE_DIR`): that directory then holds everything, as one
@@ -192,7 +196,11 @@ export function linkDiscoveredEdges(
         // one that does not), so a target naming one needs no other check:
         // a plugin hands project dirs as they are, absolute, and resolving
         // and judging each of 5,000 edges was ~15 ms at 1,000 projects.
-        const name = byDir.get(target) ?? byDir.get(path.resolve(root, target))
+        let name = byDir.get(target) ?? byDir.get(path.resolve(root, target))
+        if (name === undefined) {
+          const real = canonicalDir(root, path.resolve(root, target))
+          if (real !== null) name = byDir.get(real)
+        }
         if (name === undefined) {
           const rel = relPosix(root, path.resolve(root, target))
           const where = `plugin '${edge.by}' gave project "${edge.meta.name}" an edge to ${target}`
@@ -220,6 +228,7 @@ export function pathName(root: string, dir: string): string {
 }
 
 const CONFIG_RANK = new Map(PROJECT_CONFIG_FILENAMES.map((n, i) => [n, i]))
+const WORKSPACE_RANK = new Map(WORKSPACE_CONFIG_FILENAMES.map((n, i) => [n, i]))
 
 /** A directory holding a vx config, and the config file precedence picked there. */
 export interface ConfigDir {
@@ -228,51 +237,132 @@ export interface ConfigDir {
   readonly configPath: string
 }
 
+/** `vx lock`'s review copy of a project's resolved config, beside its `vx.config`. */
+export const REVIEW_FILE = 'vx.lock.json'
+
+export interface ProjectConfigs {
+  readonly configs: ConfigDir[]
+  /** Absolute: review copies in a directory with no config, which no `vx lock` rewrites. */
+  readonly strayReviews: string[]
+  /** Absolute: config files a higher-precedence one beside them hides, the root's workspace config among them, by the one read. */
+  readonly shadowed: { file: string; read: string }[]
+}
+
 /**
  * Every project directory under `root`, for `vx lock` (a run reads the
  * lock and never walks). In git: `git ls-files` over the config names,
- * tracked and untracked, git's ignore rules applied, and each nested
- * repository's own listing. Outside git: a walk
- * that skips dot-directories and `node_modules`. A config at or under a
+ * tracked and untracked, git's ignore rules applied, none under
+ * `node_modules`, and each nested repository's own listing. Outside git: a walk
+ * that skips `node_modules` and vx's own `.vx`, and enters every other
+ * dot-directory, as git lists `.github/actions/x`. A config at or under a
  * nested `.vx/workspace.*` belongs to that workspace and is left out.
  * Where a directory holds several, `PROJECT_CONFIG_FILENAMES` order picks
  * the first that is a file.
  */
-export async function findProjectConfigs(root: string): Promise<ConfigDir[]> {
-  const rels = (await gitTop(root)) === null ? await scanConfigs(root) : await gitConfigs(root)
+export async function findProjectConfigs(root: string): Promise<ProjectConfigs> {
+  const inGit = (await gitTop(root)) !== null
+  const rels = inGit ? await gitConfigs(root) : await scanConfigs(root)
   const nested: string[] = []
   for (const rel of rels) {
-    const at = rel.lastIndexOf('.vx/workspace.')
-    if (at > 0 && rel[at - 1] === '/' && rel.lastIndexOf('/') === at + 3)
-      nested.push(rel.slice(0, at - 1))
+    const at = rel.lastIndexOf('/.vx/')
+    if (at > 0 && WORKSPACE_RANK.has(rel.slice(at + 1))) nested.push(rel.slice(0, at))
   }
+  if (inGit) nested.push(...(await unlistedNested(root, rels, nested)))
   const byDir = new Map<string, string[]>()
+  const reviewed: string[] = []
   for (const rel of rels) {
     const slash = rel.lastIndexOf('/')
     const base = rel.slice(slash + 1)
-    if (!CONFIG_RANK.has(base)) continue
     const dir = slash === -1 ? '' : rel.slice(0, slash)
     if (nested.some((n) => dir === n || dir.startsWith(`${n}/`))) continue
+    if (base === REVIEW_FILE) reviewed.push(dir)
+    if (!CONFIG_RANK.has(base)) continue
     const names = byDir.get(dir)
     if (names === undefined) byDir.set(dir, [base])
     else names.push(base)
   }
+  const shadowed: { file: string; read: string }[] = []
+  // The files among `names` (ranked), the first of them the one read: git
+  // lists a tracked config deleted from the worktree, and a directory may
+  // carry a config's name. Every other file is shadowed, said by `vx lock`.
+  const firstFile = async (
+    dir: string,
+    names: string[],
+    rank: ReadonlyMap<string, number>,
+  ): Promise<string | null> => {
+    names.sort((a, b) => rank.get(a)! - rank.get(b)!)
+    const files = (
+      await Promise.all(names.map(async (n) => ((await isFile(path.join(dir, n))) ? n : null)))
+    ).filter((n) => n !== null)
+    for (const n of files.slice(1))
+      shadowed.push({ file: path.join(dir, n), read: path.join(dir, files[0]!) })
+    return files[0] === undefined ? null : path.join(dir, files[0])
+  }
   const found = await Promise.all(
     [...byDir].map(async ([rel, names]) => {
       const dir = rel === '' ? root : path.join(root, rel)
-      names.sort((a, b) => CONFIG_RANK.get(a)! - CONFIG_RANK.get(b)!)
-      // A file each: git lists a tracked config deleted from the worktree,
-      // and a directory may carry a config's name.
-      for (const name of names) {
-        const configPath = path.join(dir, name)
-        if (await isFile(configPath)) return { dir, configPath }
-      }
-      return null
+      const configPath = await firstFile(dir, names, CONFIG_RANK)
+      return configPath === null ? null : { dir, configPath }
     }),
   )
-  return found
+  // The root's own, asked by name: a walk outside git lists no dot-directory.
+  await firstFile(root, [...WORKSPACE_CONFIG_FILENAMES], WORKSPACE_RANK)
+  shadowed.sort((a, b) => (a.file < b.file ? -1 : 1))
+  const configs = found
     .filter((f): f is ConfigDir => f !== null)
     .sort((a, b) => (a.dir < b.dir ? -1 : a.dir > b.dir ? 1 : 0))
+  const configured = new Set(configs.map((c) => c.dir))
+  // On disk only: git lists a tracked copy deleted with its project.
+  const strayReviews = (
+    await Promise.all(
+      reviewed
+        .map((rel) => (rel === '' ? root : path.join(root, rel)))
+        .filter((dir) => !configured.has(dir))
+        .map(async (dir) => {
+          const file = path.join(dir, REVIEW_FILE)
+          return (await isFile(file)) ? file : null
+        }),
+    )
+  )
+    .filter((f) => f !== null)
+    .sort()
+  return { configs, strayReviews, shadowed }
+}
+
+/**
+ * The nested workspace roots git did not list (an ignored `.vx/`) among the
+ * directories holding `rels` and their ancestors under `root`: a run from
+ * under one takes it as its root, so the outer lock must not claim it.
+ */
+async function unlistedNested(
+  root: string,
+  rels: readonly string[],
+  listed: readonly string[],
+): Promise<string[]> {
+  const dirs = new Set<string>()
+  for (const rel of rels) {
+    for (let d = rel.slice(0, Math.max(rel.lastIndexOf('/'), 0)); d !== '';) {
+      if (dirs.has(d)) break
+      dirs.add(d)
+      d = d.slice(0, Math.max(d.lastIndexOf('/'), 0))
+    }
+  }
+  for (const n of listed) dirs.delete(n)
+  // A stat, no descriptor: most directories have no `.vx`.
+  const found = await Promise.all(
+    [...dirs].map(async (d) =>
+      (await stat(path.join(root, d, '.vx')).then(
+        (st) => st.isDirectory(),
+        (err: unknown) => {
+          if (isOutOfFds(err)) throw err
+          return false
+        },
+      )) && (await workspaceFileIn(root, d))
+        ? d
+        : null,
+    ),
+  )
+  return found.filter((d) => d !== null)
 }
 
 async function isFile(p: string): Promise<boolean> {
@@ -302,10 +392,12 @@ async function gitConfigs(root: string): Promise<string[]> {
       '--',
       ':(glob)**/vx.config.*',
       ':(glob)**/.vx/workspace.*',
+      `:(glob)**/${REVIEW_FILE}`,
+      NOT_INSTALLS,
     ]),
-    gitZ(root, ['ls-files', '-z', '--stage']),
+    gitZ(root, ['ls-files', '-z', '--stage', '--', NOT_INSTALLS]),
     // An embedded repository is the one untracked entry git lists as `dir/`.
-    gitZ(root, ['ls-files', '-z', '--others', '--exclude-standard']),
+    gitZ(root, ['ls-files', '-z', '--others', '--exclude-standard', '--', NOT_INSTALLS]),
   ])
   // A submodule's `.git` is a file, an embedded repository's a directory.
   const isRepo = (rel: string): Promise<boolean> =>
@@ -329,6 +421,13 @@ async function gitConfigs(root: string): Promise<string[]> {
   return [...configs, ...prefixed]
 }
 
+/**
+ * An install is no project, tracked or not, as the walk outside git skips
+ * it: a repo whose .gitignore does not name `node_modules` listed each
+ * installed package's vx.config as one.
+ */
+const NOT_INSTALLS = ':(exclude,glob)**/node_modules/**'
+
 /** `git <args>`'s NUL-separated output at `cwd`. */
 async function gitZ(cwd: string, args: string[]): Promise<string[]> {
   let proc: Bun.Subprocess<'ignore', 'pipe', 'pipe'>
@@ -358,7 +457,7 @@ async function gitZ(cwd: string, args: string[]): Promise<string[]> {
     .filter((p) => p !== '')
 }
 
-/** The config paths under `root` outside git, root-relative: no dot-directory, no `node_modules`. */
+/** The config paths under `root` outside git, root-relative: none under `node_modules`, `.git` or `.vx`. */
 async function scanConfigs(root: string): Promise<string[]> {
   const out: string[] = []
   const walk = async (rel: string): Promise<void> => {
@@ -375,9 +474,8 @@ async function scanConfigs(root: string): Promise<string[]> {
     const below: string[] = []
     for (const e of entries) {
       const child = rel === '' ? e.name : `${rel}/${e.name}`
-      if (CONFIG_RANK.has(e.name)) out.push(child)
-      else if (e.isDirectory() && !e.name.startsWith('.') && e.name !== 'node_modules')
-        below.push(child)
+      if (CONFIG_RANK.has(e.name) || e.name === REVIEW_FILE) out.push(child)
+      else if (e.isDirectory() && !SCAN_SKIPS.has(e.name)) below.push(child)
     }
     await Promise.all(below.map(walk))
   }
@@ -385,9 +483,12 @@ async function scanConfigs(root: string): Promise<string[]> {
   return out
 }
 
+// `.vx` holds vx's state (the cache), which a checkout ignores.
+const SCAN_SKIPS = new Set(['node_modules', '.git', '.vx'])
+
 async function workspaceFileIn(root: string, rel: string): Promise<boolean> {
   const names = await readdir(path.join(root, rel, '.vx')).catch(() => [] as string[])
-  return names.some((n) => n.startsWith('workspace.'))
+  return names.some((n) => WORKSPACE_RANK.has(`.vx/${n}`))
 }
 
 /** How each project got its name, when not by its path: `config`, or the plugin's name. */
@@ -455,14 +556,24 @@ export async function discoveredProject(
     const bad = nameFault(name)
     if (bad !== null) throw new UserError(`${where} ${JSON.stringify(name)}: ${bad}`)
   }
-  const dir = path.resolve(root, entry.dir)
+  let dir = path.resolve(root, entry.dir)
   const rel = relPosix(root, dir)
   const named = name === undefined ? '' : ` "${name}"`
   if (rel === '..' || rel.startsWith('../') || path.isAbsolute(rel)) {
     throw new UserError(`${where}${named} at ${dir}: outside the workspace root`)
   }
   const shown = rel === '' ? '.' : rel
-  const meta = known.get(dir)
+  // Refused once the stage ended too, but naming no plugin and saying to set a `name`.
+  if (name === ROOT_NAME && rel !== '') {
+    throw new UserError(`${where} "//" at ${shown}: "//" names the workspace root`)
+  }
+  let meta = known.get(dir)
+  if (meta === undefined) {
+    // Only a directory no project holds is resolved: a locked one is
+    // already real, and a realpath per entry is a syscall per project.
+    dir = canonicalDir(root, dir) ?? dir
+    meta = known.get(dir)
+  }
   if (meta !== undefined) {
     const from = namedBy.get(meta)
     if (name === undefined || name === meta.name || from === 'config') return { meta, added: false }
@@ -493,6 +604,38 @@ function nameFault(name: string): string | null {
   if (name.trim() !== name) return 'the name has surrounding whitespace'
   // A task is `<project>#<task>` split at the first `#`.
   if (name.includes('#')) return 'the name holds "#" — vx addresses a task as <name>#<task>'
+  // Printed raw by the status line and summary: `ESC ]0;` retitled the terminal.
+  if (hasControl(name)) return 'the name holds a control character'
+  const why = projectNameProblem(name)
+  return why === null ? null : `the name ${why}`
+}
+
+/**
+ * Why `dependsOn` or `--filter` cannot name a project called `name`, or
+ * null; surrounding whitespace and `#` are each caller's own words. Each
+ * shape loaded and could not be addressed: `^ui#build` was refused as `^`
+ * with `pkg#task`, `--filter '!ui'` excluded it, `tag:ui` and `ui...` read
+ * as a tag and a walk. Asked of the filter parser itself, as `tagProblem`.
+ */
+export function projectNameProblem(name: string): string | null {
+  if (name.includes('*')) return "holds '*', which makes it a pattern"
+  if (name.startsWith('^')) return "starts with '^', which names dependencies' tasks"
+  if (name.startsWith('!')) return "starts with '!', which a filter reads as an exclusion"
+  // The root's own name, which the filter reads as the root's directory.
+  if (name === ROOT_NAME) return null
+  const walk = "starts or ends with '...', which a filter reads as a dependency walk"
+  let f: ReturnType<typeof parseFilter>
+  try {
+    f = parseFilter(name, '/')
+  } catch {
+    // `...` alone: the walk with no project between.
+    return walk
+  }
+  if (f.withDeps || f.withDependents || f.onlyDeps || f.onlyDependents) return walk
+  if (f.gitSince !== undefined)
+    return `ends in "[${f.gitSince}]", which a filter reads as a git range`
+  if (f.tag === true) return "starts with 'tag:', which a filter reads as a tag selector"
+  if (f.isPath) return 'reads as a directory to a filter'
   return null
 }
 
@@ -513,7 +656,7 @@ export function checkProjectNames(root: string, metas: ProjectMeta[]): ProjectMe
     const fault = namedBy.has(meta) ? null : nameFault(meta.name)
     if (fault !== null) {
       throw new UserError(
-        `${rel}: a project is named by its path unless named, and ${fault.replace('the name', 'this one')} — set \`name\` in its vx.config`,
+        `${printable(rel)}: a project is named by its path unless named, and ${fault.replace('the name', 'this one')} — set \`name\` in its vx.config`,
       )
     }
     const next = metas[i + 1]