feat: filter packages with --filter

[branchseer]

Summary

Add pnpm-compatible --filter flag to vp run for selecting which packages to run tasks in.

Supports:

• Package name: exact (--filter @test/app) and glob (--filter @test/*)
• Directory: exact (--filter ./packages/app), glob (--filter ./packages/*), relative (., ..)
• Braced paths: {./path} for traversal on paths, name{./dir} for name + directory intersection
• Dependency traversal: foo... (dependencies), ...foo (dependents), ^ to exclude self, ...foo... (both)
• Exclusion: !foo to exclude packages from the result
• Multiple filters: --filter a --filter b (union); --filter "a b" (whitespace split, pnpm compat)
• -w / --workspace-root: select workspace root; additive with --filter, redundant with -r, supports -t for root + transitive deps
• Nested expansion: vp run --filter .... build inside package scripts is expanded in the plan

Architecture: PackageQueryArgs → PackageQuery → FilterResolution

Package selection lives in vite_workspace, not in the task runner. Any command that needs to pick packages can reuse it.

Step 1 — Parse CLI flags into a query.

PackageQueryArgs is a clap struct with -r, -t, -w, and --filter. Embed it via #[clap(flatten)], then call into_package_query():

// in any command definition (e.g. `vp exec`, `vp run`)
#[derive(clap::Args)]
struct MyCommand {
    #[clap(flatten)]
    packages: PackageQueryArgs,
}

// at runtime — package_name comes from `pkg#task` syntax (e.g. "app" in `vp run app#build`).
// commands that don't use `pkg#task` (like `vp exec`) pass None.
let query: PackageQuery = args.packages.into_package_query(package_name, &cwd)?;

into_package_query validates flag combinations (e.g. --filter + -r is an error), splits whitespace, parses each --filter token, and returns an opaque PackageQuery.

Step 2 — Resolve the query against the package graph.

let resolution: FilterResolution = indexed_package_graph.resolve_query(&query);
// resolution.package_subgraph  — the selected packages + edges between them
// resolution.unmatched_selectors — filter strings that matched nothing (for warnings)

PackageQuery is opaque — callers don't inspect its internals. They just pass it to resolve_query and get back the selected subgraph.

Future commands like vp exec only need steps 1 and 2 — they get the selected packages without depending on the task graph at all.

Step 3 (task runner only) — Map packages to tasks.

The task-graph layer maps the package subgraph to task nodes, reconnecting across packages that lack the requested task. Only vp run needs this step.

unmatched_selectors tracks original filter strings

Each --filter token is stored as a source: Option<Str> inside the parsed filter. Synthetic filters (implicit cwd, -w) get source: None since the user didn't type them. When a filter matches nothing, resolve_query collects the original string into unmatched_selectors: Vec<Str> so the caller can show a warning like:

warn: --filter "typo-pkg" matched no packages

This works correctly even with whitespace splitting (--filter "a b" → two filters, each with its own source string).

Test plan

• 48 unit tests in package_filter for parse_filter, into_package_query, resolve_directory_pattern, and source tracking — covering all selector types, traversal modes, flag combinations, path normalization, and error cases
• 40 plan snapshot tests across filter-workspace (35) and transitive-skip-intermediate (5) fixtures
• Existing plan and e2e snapshot tests still pass

🤖 Generated with Claude Code

[branchseer]

• feat: filter packages with --filter #176 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.