Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,15 +40,15 @@ Test fixtures and snapshots:

```bash
# Run a task defined in vite-task.json
vite run <task> # run task in current package
vite run <package>#<task> # run task in specific package
vite run <task> -r # run task in all packages (recursive)
vite run <task> -t # run task in current package + transitive deps
vite run <task> --extra --args # pass extra args to the task command
vp run <task> # run task in current package
vp run <package>#<task> # run task in specific package
vp run <task> -r # run task in all packages (recursive)
vp run <task> -t # run task in current package + transitive deps
vp run <task> --extra --args # pass extra args to the task command

# Built-in commands (run tools from node_modules/.bin)
vite test [args...] # run vitest
vite lint [args...] # run oxlint
vp test [args...] # run vitest
vp lint [args...] # run oxlint

# Flags
-r, --recursive # run across all packages
Expand All @@ -59,7 +59,7 @@ vite lint [args...] # run oxlint
## Key Architecture

- **vite_task** - Main task runner with caching and session management
- **vite_task_bin** - CLI binary (`vite` command) and task synthesizer
- **vite_task_bin** - CLI binary (`vp` command) and task synthesizer
- **vite_task_graph** - Task dependency graph construction and config loading
- **vite_task_plan** - Execution planning (resolves env vars, working dirs, commands)
- **vite_workspace** - Workspace detection and package dependency graph
Expand Down
14 changes: 7 additions & 7 deletions crates/vite_task/docs/boolean-flags.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ The positive and negative forms of a flag are mutually exclusive. You cannot use

```bash
# This will result in an error
vite run --recursive --no-recursive build
vp run --recursive --no-recursive build
```

### Precedence
Expand All @@ -44,7 +44,7 @@ When only the negative form is used, it takes precedence and explicitly sets the

```bash
# Explicitly disable topological ordering
vite run build -r --no-topological
vp run build -r --no-topological
```

### Default Values
Expand All @@ -54,23 +54,23 @@ The negative flags are particularly useful for overriding default behaviors:
- `--recursive` with `--no-topological`: By default, recursive runs enable topological ordering. Use `--no-topological` to disable it:
```bash
# Recursive run WITHOUT topological ordering
vite run build -r --no-topological
vp run build -r --no-topological
```

## Examples

```bash
# Run with debugging disabled (useful if debug is enabled by default in config)
vite --no-debug build
vp --no-debug build

# Recursive build without topological ordering
vite run build --recursive --no-topological
vp run build --recursive --no-topological

# Explicitly disable parallel execution
vite run build --no-parallel
vp run build --no-parallel

# Run tests sequentially, not in parallel
vite run test --no-parallel
vp run test --no-parallel
```

## Implementation Details
Expand Down
48 changes: 24 additions & 24 deletions crates/vite_task/docs/task-cache.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,18 +29,18 @@ For tasks defined as below:

the task cache system is able to hit the same cache for `test` task and for the first subcommand in `build` task:

1. user runs `vite run build` -> no cache hit. run `echo $foo` and create cache
2. user runs `vite run test`
1. user runs `vp run build` -> no cache hit. run `echo $foo` and create cache
2. user runs `vp run test`
1. `echo $foo` -> **hit cache created in step 1 and replay**
2. `echo $bar` -> no cache hit. run `echo test` and create cache
3. user changes env `$foo`
4. user runs `vite run test`
4. user runs `vp run test`
1. `echo $foo`
1. the cache system should be able to **locate the cache that was created in step 1 and hit in step 2.1**
2. compare the command fingerprint and report cache miss because `$foo` is changed.
3. re-run and replace the cache with a new one.
2. `echo $bar` -> hit cache created in step 2.2 and replay
5. user runs `vite run build`: **hit the cache created in step 4.1.3 and replay**.
5. user runs `vp run build`: **hit the cache created in step 4.1.3 and replay**.

## Architecture

Expand Down Expand Up @@ -498,10 +498,10 @@ The cache location can be configured via environment variable:

```bash
# Custom cache location
VITE_CACHE_PATH=/tmp/vite-cache vite run build
VITE_CACHE_PATH=/tmp/vite-cache vp run build

# Default: node_modules/.vite/task-cache in workspace root
vite run build
vp run build
```

### Task-Level Cache Control
Expand Down Expand Up @@ -614,7 +614,7 @@ CommandFingerprint {
### Example: Synthetic Task Cache Key

```rust
// Synthetic task (e.g., "vite lint" in a task script)
// Synthetic task (e.g., "vp lint" in a task script)
TaskRunKey {
task_id: TaskId {
task_group_id: TaskGroupId {
Expand Down Expand Up @@ -645,10 +645,10 @@ CommandFingerprint {

```bash
# Enable debug logging
VITE_LOG=debug vite run build
VITE_LOG=debug vp run build

# Show cache operations
VITE_LOG=trace vite run build
VITE_LOG=trace vp run build
```

### Debug Output Examples
Expand Down Expand Up @@ -718,8 +718,8 @@ Tasks with identical commands automatically share cache entries:

Behavior:

1. `vite run script1` creates command cache for `cat foo.txt`
2. `vite run script2` hits the same command cache (shared)
1. `vp run script1` creates command cache for `cat foo.txt`
2. `vp run script2` hits the same command cache (shared)
3. If `foo.txt` changes, both tasks will see cache miss on next run
4. Cache update from either task benefits the other

Expand All @@ -729,8 +729,8 @@ Tasks with different arguments get separate cache entries:

```bash
# These create separate caches
vite run echo -- a # TaskRunKey with args: ["a"]
vite run echo -- b # TaskRunKey with args: ["b"]
vp run echo -- a # TaskRunKey with args: ["a"]
vp run echo -- b # TaskRunKey with args: ["b"]
```

### 4. Compound Commands for Granular Caching
Expand Down Expand Up @@ -787,23 +787,23 @@ No need to manually specify inputs - fspy captures actual dependencies.

```bash
# Initial run creates command cache
> vite run script1
> vp run script1
Cache not found
bar

# Different task, same command - hits shared cache
> vite run script2
> vp run script2
Cache hit, replaying
bar

# File change invalidates shared cache
> echo baz > foo.txt
> vite run script2
> vp run script2
Cache miss: foo.txt content changed
baz

# Original task benefits from updated cache
> vite run script1
> vp run script1
Cache hit, replaying
baz
```
Expand All @@ -812,20 +812,20 @@ baz

```bash
# Different args create separate caches
> vite run echo -- a
> vp run echo -- a
Cache not found
a

> vite run echo -- b
> vp run echo -- b
Cache not found
b

# Each argument combination has its own cache
> vite run echo -- a
> vp run echo -- a
Cache hit, replaying
a

> vite run echo -- b
> vp run echo -- b
Cache hit, replaying
b
```
Expand All @@ -834,16 +834,16 @@ b

```bash
# Different directories create separate caches for tasks
> cd folder1 && vite run lint
> cd folder1 && vp run lint
Cache not found
Found 0 warnings and 0 errors.

> cd folder2 && vite run lint
> cd folder2 && vp run lint
Cache not found # Different cwd = different cache
Found 0 warnings and 0 errors.

# Each directory maintains its own cache
> cd folder1 && vite run lint
> cd folder1 && vp run lint
Cache hit, replaying
Found 0 warnings and 0 errors.
```
Expand Down
2 changes: 1 addition & 1 deletion crates/vite_task/docs/terminologies.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,4 +31,4 @@ The two task groups generates 3 tasks:

These are **task names**. They are for displaying and filtering.

The user could execute `vite run build` under the `app` package, or execute `vite run app#build` from anywhere. The parameter `build` and `app#build` after `vite run` are **task requests**. They are used to match against task names to determine what tasks to run.
The user could execute `vp run build` under the `app` package, or execute `vp run app#build` from anywhere. The parameter `build` and `app#build` after `vp run` are **task requests**. They are used to match against task names to determine what tasks to run.
56 changes: 28 additions & 28 deletions crates/vite_task/docs/vite-run.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# `vite-plus run`
# `vp run`

Vite-plus run has two modes:

1. Implicit mode is running `vite-plus` without `run` command, it will run the task in the current package, it supposed to replace the `pnpm/yarn run` command.
2. Explicit mode is running `vite-plus run` with run command, like `vite-plus run vite-plus#build`.
1. Implicit mode is running `vp` without `run` command, it will run the task in the current package, it supposed to replace the `pnpm/yarn run` command.
2. Explicit mode is running `vp run` with run command, like `vp run vite-plus#build`.

## Implicit mode

Expand All @@ -15,7 +15,7 @@ Vite-plus run has two modes:
>
> This documentation describes the current behavior and should be updated when the Implicit Mode RFC is done.

With implicit mode, `vite` will run the task in the current package. It can't accept more than on task. The first argument will be treated as the task name; the args following the command will be treated as the task args and bypass to the task.
With implicit mode, `vp` will run the task in the current package. It can't accept more than on task. The first argument will be treated as the task name; the args following the command will be treated as the task args and bypass to the task.

Given the following `package.json` file:

Expand All @@ -31,54 +31,54 @@ Given the following `package.json` file:
This command equivalent to `vite build`:

```bash
vite-plus build
vp build
```

This command equivalent to `vite build --mode production`:

```bash
vite-plus build --mode production
vp build --mode production
```

This command equivalent to `oxlint packages/cli/binding/index.js`:

```bash
vite-plus lint packages/cli/binding/index.js
vp lint packages/cli/binding/index.js
```

If the command contains `#`, the command will be treated as a task in the workspace subpackage.

This command equivalent to `vite-plus run cli#build`:
This command equivalent to `vp run cli#build`:

```bash
vite-plus cli#build
vp cli#build
```

## Explicit mode

With explicit mode, `vite-plus run` will run the task in the workspace subpackage. It can accept more than one task. The arguments will be treated as the task names; the args following the `--` will be treated as the task args and bypass to the task.
With explicit mode, `vp run` will run the task in the workspace subpackage. It can accept more than one task. The arguments will be treated as the task names; the args following the `--` will be treated as the task args and bypass to the task.

### Default behavior

The `vite-plus run` command will run the scoped tasks in dependency order.
The `vp run` command will run the scoped tasks in dependency order.

Task names without `#` will be resolved in the current package (the package containing the nearest package.json file from the current working directory). For example:

- `vite-plus run build` - runs the build task in the current package
- `vite-plus run test lint` - Throw `OnlyOneTaskRequest` error
- `vite-plus run @other/package#build` - runs the build task in @other/package
- `vp run build` - runs the build task in the current package
- `vp run test lint` - Throw `OnlyOneTaskRequest` error
- `vp run @other/package#build` - runs the build task in @other/package

Behaviors when the package root and/or the workspace root is not found:

| package root | workspace root | behaviour |
| ------------ | -------------- | --------------------------------------------------------------------------------------------------------------------------- |
| found | not found | No possible: workspace root always fallbacks to package root. |
| not found | found | `vite-plus run build` should throw an `CurrentPackageNotFound` error. `vite-plus run @other/package#build` is still allowed |
| not found | not found | Throw an error on any `vite run`. The workspace root must always exist as it's where we store the cache. |
| package root | workspace root | behaviour |
| ------------ | -------------- | ------------------------------------------------------------------------------------------------------------- |
| found | not found | No possible: workspace root always fallbacks to package root. |
| not found | found | `vp run build` should throw an `CurrentPackageNotFound` error. `vp run @other/package#build` is still allowed |
| not found | not found | Throw an error on any `vp run`. The workspace root must always exist as it's where we store the cache. |

### `--recursive,-r`

With the `--recursive,-r` flag, the `vite-plus run` command will run the tasks in all monorepo packages.
With the `--recursive,-r` flag, the `vp run` command will run the tasks in all monorepo packages.

The task name should't contain `#` with the `--recursive,-r` flag. If any task name contains `#`, it would cause an `RecursiveRunWithScope` error.

Expand All @@ -98,16 +98,16 @@ Examples:

```bash
# Recursive build with topological ordering (default)
vite-plus run build -r
vp run build -r

# Recursive build WITHOUT topological ordering
vite-plus run build -r --no-topological
vp run build -r --no-topological

# Single package with topological ordering enabled
vite-plus run app#build -t
vp run app#build -t

# Multiple packages without topological ordering (default)
vite-plus run app#build web#build
vp run app#build web#build
```

Note: `--topological` and `--no-topological` are mutually exclusive and cannot be used together. See [boolean-flags.md](./boolean-flags.md) for more information about boolean flag patterns.
Expand Down Expand Up @@ -172,7 +172,7 @@ Task Dependencies (explicit):
utils#build → utils#test
```

The execution flow for `vite-plus run build -r --topological`:
The execution flow for `vp run build -r --topological`:

```
┌─────────────────────────────────────────────────────────────┐
Expand Down Expand Up @@ -342,12 +342,12 @@ The final step creates an execution plan:

Task requests are in form of `task_name` or `pkg#task_name`. They occur in two places:

- one or multiple parameters following after `vite run`.
- one or multiple parameters following after `vp run`.
- items in `dependsOn`.

How task requests work:

- `build` in `vite run build` matches task `build` in the current package determined by cwd.
- `build` in `vp run build` matches task `build` in the current package determined by cwd.
- `build` in `dependsOn: ["build"]` matches task `build` in the package where the config file is.
- `app#build` matches task `build` in package `app`.
- `app#build` raises an error if there are multiple packages named `app`.
Expand All @@ -357,4 +357,4 @@ How task requests work:
- `#build` raises an error if there are multiple nameless packages.
- `build` does not match task `build` in the nameless package.

While task requests with multiple `#` are invalid, packages with `#` in their names are valid. For example, a package named `pkg#special` can have a task named `build`. It can be referenced by executing `vite run build` under the folder of package `pkg#special`.
While task requests with multiple `#` are invalid, packages with `#` in their names are valid. For example, a package named `pkg#special` can have a task named `build`. It can be referenced by executing `vp run build` under the folder of package `pkg#special`.
Loading