@vzn/vx 0.0.492 → 0.0.493

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vzn/vx",
-  "version": "0.0.492",
+  "version": "0.0.493",
   "description": "The fastest task runner and build cache for JavaScript monorepos.",
   "type": "module",
   "exports": {
@@ -21,10 +21,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@vzn/vx-linux-x64": "0.0.492",
-    "@vzn/vx-linux-arm64": "0.0.492",
-    "@vzn/vx-darwin-x64": "0.0.492",
-    "@vzn/vx-darwin-arm64": "0.0.492"
+    "@vzn/vx-linux-x64": "0.0.493",
+    "@vzn/vx-linux-arm64": "0.0.493",
+    "@vzn/vx-darwin-x64": "0.0.493",
+    "@vzn/vx-darwin-arm64": "0.0.493"
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "^0.0.76"

package/src/cli/select.ts

@@ -254,6 +254,16 @@ export async function resolveFilters(
       return { error: err instanceof Error ? err.message : String(err) }
     }
   }
+  // A tag lives in the config, so a `tag:` selector needs the staged load
+  // (a `project` plugin may have given or edited the tags).
+  let tags: Map<string, readonly string[]> | undefined
+  if (parsed.some((f) => f.tag === true)) {
+    try {
+      tags = new Map([...(await stagedOnce()).values()].map((p) => [p.name, p.config.tags ?? []]))
+    } catch (err) {
+      return { error: err instanceof Error ? err.message : String(err) }
+    }
+  }
   const graph = buildPackageGraph(projects, edges)
   // The graph a run reusing this discovery builds is this one when no task
   // edge went into it.
@@ -290,6 +300,7 @@ export async function resolveFilters(
     projects,
     graph,
     affectedByFilter,
+    ...(tags !== undefined ? { tags } : {}),
     // A `[<since>]` selector matching nothing is the ordinary "nothing
     // changed" outcome, reported below; only a name/path pattern that
     // matched nothing is worth flagging as a probable typo.
@@ -332,14 +343,14 @@ export async function resolveFilters(
     // the patterns are in the error, and the nearest project name is the
     // hint a typo needs.
     return {
-      error: `no projects matched filter(s): ${raw.join(', ')}${didYouMeanProject(unmatched, projects)}`,
+      error: `no projects matched filter(s): ${raw.join(', ')}${didYouMean(unmatched, projects, tags)}`,
     }
   }
   // Something matched, so the run proceeds; a pattern that matched nothing
   // alongside it is still worth a line — it is probably a typo.
   for (const f of unmatched)
     process.stderr.write(
-      `vx: filter "${f}" matched no projects${didYouMeanProject([f], projects)}\n`,
+      `vx: filter "${f}" matched no projects${didYouMean([f], projects, tags)}\n`,
     )
   let staged: Map<string, ProjectEntry> | undefined
   if (stagedPromise !== undefined) {
@@ -447,6 +458,20 @@ export async function pickTask(
   }
 }
 
+/** The hint for the first unmatched pattern: a near tag for a `tag:` one, else a near project name. */
+function didYouMean(
+  unmatched: readonly string[],
+  projects: Iterable<{ name: string }>,
+  tags: ReadonlyMap<string, readonly string[]> | undefined,
+): string {
+  const first = unmatched[0]?.replace(/^!|\.\.\.$|^\.\.\.|\^/g, '')
+  if (first?.startsWith('tag:') !== true) return didYouMeanProject(unmatched, projects)
+  const known = [...new Set([...(tags?.values() ?? [])].flat())].sort()
+  if (known.length === 0) return '. No project declares tags'
+  const best = nearest(first.slice(4), known)
+  return best !== undefined ? `. Did you mean tag:${best}?` : `. Tags: ${listed(known)}`
+}
+
 /** `. Did you mean @acme/app?` for the first unmatched pattern within two edits of a project name. */
 function didYouMeanProject(
   unmatched: readonly string[],

package/src/cli/show.ts

@@ -224,12 +224,13 @@ function renderList(
   const rows = metas.map((meta) => ({
     name: meta.name,
     dir: projectDir(root, meta),
+    tags: projects.get(meta.name)?.config.tags ?? [],
     tasks: Object.keys(projects.get(meta.name)?.config.tasks ?? {}),
     configured: meta.configPath !== null,
   }))
   if (format === 'json') {
     return `${JSON.stringify(
-      rows.map(({ name, dir, tasks }) => ({ name, dir, tasks })),
+      rows.map(({ name, dir, tags, tasks }) => ({ name, dir, tags, tasks })),
       null,
       2,
     )}\n`
@@ -245,7 +246,8 @@ function renderList(
       : n > 0
         ? `${count} (no vx config; from plugins)`
         : '(no vx config)'
-    return `${r.name.padEnd(nameW)}  ${r.dir.padEnd(dirW)}  ${tasks}`
+    const tags = r.tags.length > 0 ? `  [${r.tags.join(', ')}]` : ''
+    return `${r.name.padEnd(nameW)}  ${r.dir.padEnd(dirW)}  ${tasks}${tags}`
   })
   return `${lines.join('\n')}\n`
 }
@@ -263,7 +265,8 @@ function renderProject(
     const shown = shownConfig(config)
     return `${JSON.stringify(JSON.parse(JSON.stringify({ name, dir, config: shown })), null, 2)}\n`
   }
-  const head = `${name} — ${dir}`
+  const tags = config?.tags ?? []
+  const head = `${name} — ${dir}${tags.length > 0 ? `\n  tags: ${tags.join(', ')}` : ''}`
   const tasks = Object.entries(config?.tasks ?? {})
   if (tasks.length === 0)
     return `${head}\n  ${hasConfigFile ? '(no tasks declared)' : '(no vx config)'}\n`

package/src/config.ts

@@ -130,6 +130,11 @@ const _pluginHooksMatch: [HooksNotListed, HooksNotOnPlugin] extends [never, neve
 void _pluginHooksMatch
 
 export interface ProjectConfig {
+  /**
+   * Labels for selection: `--filter tag:<name>` picks the projects that
+   * carry one. Not in any cache key: a tag changes no task's behaviour.
+   */
+  tags?: readonly string[]
   /** Tasks declared by this project, keyed by task name. */
   tasks?: Record<string, TaskConfig>
 }

package/src/workspace/config-schema.ts

@@ -287,6 +287,13 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
   // The top level too: `task:` (singular) loaded as a project with no
   // tasks and every request against it said "no projects declare".
   assertKnownFields(config, PROJECT_FIELDS, configPath)
+  const tags: unknown = config.tags
+  if (
+    tags !== undefined &&
+    (!Array.isArray(tags) || tags.some((t) => typeof t !== 'string' || t.trim() === ''))
+  ) {
+    throw new UserError(`${configPath}: \`tags\` must be an array of non-empty strings`)
+  }
   const tasks = config.tasks
   if (tasks === undefined) return
   if (typeof tasks !== 'object' || tasks === null || Array.isArray(tasks)) {
@@ -728,7 +735,9 @@ export function validateProjectConfig(config: ProjectConfig, configPath: string)
 // discarded, so the task hashes as if the field were never written and vx
 // serves a stale artifact — the same reasoning `sandbox` already
 // encodes. A new field must be added here deliberately.
-const PROJECT_FIELDS = new Set(['tasks'])
+// `tasks` first: `nearest` breaks a tie by order, and `taks` is one edit
+// from both.
+const PROJECT_FIELDS = new Set(['tasks', 'tags'])
 const TASK_FIELDS = new Set(['description', 'exec', 'dependsOn', 'cache'])
 const EXEC_FIELDS = new Set([
   'command',
@@ -867,7 +876,7 @@ const FOREIGN_FIELDS: ReadonlyMap<ReadonlySet<string>, Readonly<Record<string, s
     },
   ],
   // A package's turbo.json and Nx's project.json keys, written into a
-  // project's vx.config (D-56). `tags` had read as a typo of `tasks`.
+  // project's vx.config (D-56).
   [
     PROJECT_FIELDS,
     {
@@ -875,7 +884,6 @@ const FOREIGN_FIELDS: ReadonlyMap<ReadonlySet<string>, Readonly<Record<string, s
       extends: 'an imported module spread into `tasks` (a vx.config is code; nothing is inherited)',
       implicitDependencies: 'a `dependsOn` entry `pkg#task`, or a package.json dependency',
       name: 'the package.json `name` (a project is named by its package)',
-      tags: '`--filter` (a name glob or a directory) to select projects',
       // A package.json's, turbo.json's and project.json's keys, and a
       // task's fields one level too high (D-99).
       scripts:

package/src/workspace/filter.ts

@@ -4,6 +4,7 @@
 //   ./<dir>          the package at <dir>, else the packages under it (relative to workspace root)
 //   {<dir>}          same as ./<dir>
 //   //               the workspace-root project only (Turbo's name for the root)
+//   tag:<pattern>    the projects whose config `tags` hold a match (Nx's `tag:`)
 //   <pattern>...     pattern + its transitive workspace dependencies
 //   ...<pattern>     pattern + its transitive workspace dependents
 //   <pattern>^...    only the transitive deps of pattern (excluding the matched package)
@@ -55,6 +56,8 @@ export interface ParsedFilter {
   pathRoot?: string
   /** `//`: the project at `matcher` itself, never the ones under it. */
   exactDir?: true
+  /** `tag:<pattern>`: `matcher` is a glob over the projects' tags, not their names. */
+  tag?: true
 }
 
 export function parseFilter(raw: string, workspaceRoot: string): ParsedFilter {
@@ -141,6 +144,24 @@ export function parseFilter(raw: string, workspaceRoot: string): ParsedFilter {
     }
   }
 
+  if (s.startsWith('tag:')) {
+    const tag = s.slice(4)
+    if (tag === '') throw new UserError(`filter "${raw}" names no tag`)
+    return {
+      raw,
+      negate,
+      withDeps,
+      withDependents,
+      onlyDeps,
+      onlyDependents,
+      isPath: false,
+      matcher: tag,
+      tag: true,
+      ...(gitSince !== undefined ? { gitSince } : {}),
+      ...(sinceViaDeps ? { sinceViaDeps: true as const } : {}),
+    }
+  }
+
   let isPath = false
   let matcher = s
   let pathGlob: Bun.Glob | undefined
@@ -187,6 +208,7 @@ function matchProjects(
   projects: ProjectMeta[],
   affectedByFilter: Map<ParsedFilter, Set<string>> | undefined,
   graph: PackageGraph,
+  tags: ProjectTags | undefined,
 ): string[] {
   // `[<since>]` selectors are pre-resolved by the caller (the parser
   // is pure; git access happens upstream). Use the provided set as
@@ -199,14 +221,24 @@ function matchProjects(
         for (const d of graph.transitiveDependents(name)) changed.add(d)
     }
     if (filter.matcher === '') return [...changed]
-    return matchSelector(filter, projects).filter((name) => changed.has(name))
+    return matchSelector(filter, projects, tags).filter((name) => changed.has(name))
   }
-  return matchSelector(filter, projects)
+  return matchSelector(filter, projects, tags)
 }
 
-/** The projects a name or path selector names, git ranges aside. */
-function matchSelector(filter: ParsedFilter, projects: ProjectMeta[]): string[] {
+/** The projects a name, path or tag selector names, git ranges aside. */
+function matchSelector(
+  filter: ParsedFilter,
+  projects: ProjectMeta[],
+  tags: ProjectTags | undefined,
+): string[] {
   const out: string[] = []
+  if (filter.tag === true) {
+    const re = compileNameGlob(filter.matcher)
+    for (const p of projects)
+      if (tags?.get(p.name)?.some((t) => re.test(t)) === true) out.push(p.name)
+    return out
+  }
   if (filter.isPath) {
     // A path naming a project's own directory is that project, as Turbo and
     // pnpm read it: `.` is the root project, never every project under the
@@ -268,10 +300,15 @@ function compileNameGlob(pattern: string): RegExp {
   return new RegExp(`^${escaped}$`)
 }
 
+/** Each project's config `tags`, by project name. */
+type ProjectTags = ReadonlyMap<string, readonly string[]>
+
 export interface ApplyFiltersOptions {
   filters: ParsedFilter[]
   projects: ProjectMeta[]
   graph: PackageGraph
+  /** Read by `tag:` selectors; a project absent here carries no tag. */
+  tags?: ProjectTags
   /**
    * Pre-resolved affected-project sets for each `[<since>]` filter.
    * The caller (CLI / programmatic embedder) runs the git work and
@@ -304,7 +341,7 @@ export function applyFilters(opts: ApplyFiltersOptions): Set<string> {
   // taken in argv order, so `onNoMatch` names the filters as typed.
   const excludes: Set<string>[] = []
   for (const f of opts.filters) {
-    const matched = matchProjects(f, opts.projects, opts.affectedByFilter, opts.graph)
+    const matched = matchProjects(f, opts.projects, opts.affectedByFilter, opts.graph, opts.tags)
     if (matched.length === 0) opts.onNoMatch?.(f)
     const expanded = new Set<string>()
     for (const name of matched) {

package/src/workspace/migration.ts

@@ -203,6 +203,8 @@ export interface GeneratedProject {
   /** absolute project dir */
   dir: string
   importLines: string[]
+  /** The project's `tags` (an Nx project's); none written when empty. */
+  tags?: readonly string[]
   tasks: GeneratedTask[]
 }
 
@@ -599,7 +601,9 @@ function renderConfigFile(
   ]
   if (format === 'ts') lines.push("import type { ProjectConfig } from '@vzn/vx/config'")
   if (p.importLines.length > 0) lines.push(...p.importLines)
-  lines.push('', 'export default {', '  tasks: {')
+  lines.push('', 'export default {')
+  if (p.tags !== undefined && p.tags.length > 0) lines.push(`  tags: ${renderValue(p.tags, '  ')},`)
+  lines.push('  tasks: {')
   for (const t of p.tasks) {
     // A reason can quote a manifest's own text (an Nx `env` key), and a
     // line break there ended the comment: the rest was code in the file