Skip to content

Commit 2e30409

Browse files
branchseerclaude
branchseer
and
claude
authored
docs: overhaul README.md, CLAUDE.md and add CONTRIBUTING.md (#234)
## Summary - Overhaul `README.md` — concise project description, getting started with `vp run` examples, link to Vite+ docs - Overhaul `CLAUDE.md` — repository structure, architecture, code constraints, streamlined for AI-assisted development - Add `CONTRIBUTING.md` — prerequisites, `vt` vs `vp` comparison, dev workflow, testing, cross-platform requirements, code conventions --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 28f371a commit 2e30409

File tree

4 files changed

+194
-129
lines changed

4 files changed

+194
-129
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,6 @@ on:
88
workflow_dispatch:
99
pull_request:
1010
types: [opened, synchronize]
11-
paths-ignore:
12-
- '**/*.md'
1311
push:
1412
branches:
1513
- main
@@ -25,7 +23,25 @@ defaults:
2523
shell: bash
2624

2725
jobs:
26+
detect-changes:
27+
runs-on: ubuntu-latest
28+
permissions:
29+
contents: read
30+
pull-requests: read
31+
outputs:
32+
code-changed: ${{ steps.filter.outputs.code }}
33+
steps:
34+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
35+
- uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
36+
id: filter
37+
with:
38+
filters: |
39+
code:
40+
- '!**/*.md'
41+
2842
test:
43+
needs: detect-changes
44+
if: needs.detect-changes.outputs.code-changed == 'true'
2945
name: Test
3046
strategy:
3147
fail-fast: false
@@ -132,6 +148,7 @@ jobs:
132148

133149
done:
134150
runs-on: ubuntu-latest
151+
if: always()
135152
needs:
136153
- test
137154
- fmt

‎CLAUDE.md‎

Lines changed: 55 additions & 127 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,28 @@
1-
# CLAUDE.md
2-
3-
## Project Overview
4-
5-
A monorepo task runner (like nx/turbo) with intelligent caching and dependency resolution.
6-
7-
## Build Commands
1+
# Vite Task
2+
3+
A monorepo task runner (like Nx/Turbo) with intelligent caching and dependency resolution, distributed as the `vp run` command in [Vite+](https://github.com/voidzero-dev/vite-plus).
4+
5+
## Repository Structure
6+
7+
- `crates/vite_task` — Task execution engine with caching and session management
8+
- `crates/vite_task_bin` — Internal dev CLI binary (`vt`) and task synthesizer
9+
- `crates/vite_task_graph` — Task dependency graph construction and config loading
10+
- `crates/vite_task_plan` — Execution planning (resolves env vars, working dirs, commands)
11+
- `crates/vite_workspace` — Workspace detection and package dependency graph
12+
- `crates/fspy*` — File system access tracing (9 crates: supervisor, preload libs, platform backends)
13+
- `crates/pty_terminal*` — Cross-platform headless terminal emulator (3 crates)
14+
- `crates/vite_path` — Type-safe absolute/relative path system
15+
- `crates/vite_str` — Stack-allocated compact string type
16+
- `crates/vite_glob` — Glob pattern matching
17+
- `crates/vite_shell` — Shell command parsing
18+
- `crates/vite_select` — Interactive fuzzy selection UI
19+
- `crates/vite_tui` — Terminal UI components (WIP, unfinished)
20+
- `crates/vite_graph_ser` — Graph serialization utilities
21+
- `crates/subprocess_test` — Subprocess testing framework
22+
- `packages/tools` — Node.js test utilities (print, json-edit, check-tty, etc.)
23+
- `docs/` — Documentation (inputs configuration guide)
24+
25+
## Development Commands
826

927
```bash
1028
just init # Install build tools and dependencies
@@ -30,96 +48,37 @@ INSTA_UPDATE=always cargo test # Update snapshots
3048

3149
Integration tests (e2e, plan, fspy) require `pnpm install` in `packages/tools` first. You don't need `pnpm install` in test fixture directories.
3250

33-
Test fixtures and snapshots:
51+
### Test Fixtures
3452

35-
- **Plan**: `crates/vite_task_plan/tests/plan_snapshots/fixtures/` - quicker, sufficient for testing behaviour before actual execution:
36-
- task graph
37-
- resolved configurations
38-
- resolved program paths, cwd, and env vars
39-
- **E2E**: `crates/vite_task_bin/tests/e2e_snapshots/fixtures/` - needed for testing execution and beyond: caching, output styling
53+
- **Plan**: `crates/vite_task_plan/tests/plan_snapshots/fixtures/` — quicker, sufficient for testing task graph, resolved configs, program paths, cwd, and env vars
54+
- **E2E**: `crates/vite_task_bin/tests/e2e_snapshots/fixtures/` — needed for testing execution, caching, output styling
4055

4156
### Cross-Platform Testing
4257

43-
**CRITICAL**: This project must work on both Unix (macOS/Linux) and Windows. For any cross-platform features:
44-
45-
1. **No Platform Skipping**: Skipping tests on either platform is **UNACCEPTABLE**
46-
- Use `#[cfg(unix)]` and `#[cfg(windows)]` for platform-specific code within tests
47-
- Both platforms must execute the test and verify the feature works correctly
48-
- If a feature can't work on a platform, it shouldn't be added
58+
**CRITICAL**: This project must work on both Unix (macOS/Linux) and Windows. Skipping tests on either platform is **UNACCEPTABLE**.
4959

50-
2. **Windows Cross-Testing from macOS**:
51-
`cargo xtest` cross-compiles the test binary and runs it on a real remote Windows environment (not emulation). The filesystem is bridged so the test can access local fixture files.
52-
```bash
53-
cargo xtest --builder cargo-xwin --target aarch64-pc-windows-msvc -p <package> --test <test>
60+
- Use `#[cfg(unix)]` and `#[cfg(windows)]` for platform-specific code within tests
61+
- Both platforms must execute the test and verify the feature works correctly
62+
- Use cross-platform libraries for common operations (e.g., `terminal_size` for terminal dimensions)
5463

55-
# Examples:
56-
cargo xtest --builder cargo-xwin --target aarch64-pc-windows-msvc -p pty_terminal --test terminal
57-
cargo xtest --builder cargo-xwin --target aarch64-pc-windows-msvc -p pty_terminal --test terminal -- resize_terminal
58-
```
64+
## Architecture
5965

60-
3. **Cross-Platform Test Design Patterns**:
61-
- Use conditional compilation for platform-specific setup/assertions
62-
- Use cross-platform libraries for common operations (e.g., `terminal_size` for terminal dimensions)
63-
- Verify platform-specific behavior works as expected:
64-
- **Unix**: SIGWINCH signals, ioctl, /dev/null, etc.
65-
- **Windows**: ConPTY, GetConsoleScreenBufferInfo, NUL, etc.
66+
### Task Execution Pipeline
6667

67-
4. **Example**: The `pty_terminal::resize_terminal` test demonstrates proper cross-platform testing:
68-
- Unix: Installs SIGWINCH handler to verify signal delivery
69-
- Windows: Acknowledges synchronous ConPTY resize behavior
70-
- Both: Query terminal size using cross-platform `terminal_size` crate
71-
- Both: Verify resize actually works and returns correct dimensions
72-
73-
## CLI Usage
74-
75-
```bash
76-
# Run a task defined in vite-task.json
77-
vt run <task> # run task in current package
78-
vt run <package>#<task> # run task in specific package
79-
vt run <task> -r # run task in all packages (recursive)
80-
vt run <task> -t # run task in current package + transitive deps
81-
vt run <task> -- --extra --args # pass extra args to the task command
82-
vt run # interactive task selector (fuzzy search)
83-
84-
# Built-in commands (run tools from node_modules/.bin)
85-
vt test [args...] # run vitest
86-
vt lint [args...] # run oxlint
87-
88-
# Cache management
89-
vt cache clean # remove the cache database
90-
91-
# Package selection flags
92-
-r, --recursive # select all packages in the workspace
93-
-t, --transitive # select current package + transitive deps
94-
-w, --workspace-root # select the workspace root package
95-
-F, --filter <pattern> # pnpm-style filter (repeatable, see below)
96-
97-
# Run flags
98-
--ignore-depends-on # skip explicit dependsOn dependencies
99-
-v, --verbose # show full detailed summary after execution
100-
--cache # force caching on for all tasks and scripts
101-
--no-cache # force caching off for all tasks and scripts
102-
--last-details # show detailed summary of the last run
103-
104-
# Filter patterns (pnpm-style)
105-
-F <name> # select by package name
106-
-F '@scope/*' # select by glob pattern
107-
-F ./<dir> # select packages under a directory
108-
-F '<pattern>...' # select package and its dependencies
109-
-F '...<pattern>' # select package and its dependents
110-
-F '!<pattern>' # exclude packages matching pattern
68+
```
69+
CLI (vite_task_bin) → Task Graph (vite_task_graph) → Plan (vite_task_plan) → Execution (vite_task)
70+
↑ ↓
71+
vite_workspace fspy (file tracing)
11172
```
11273

113-
## Key Architecture
74+
### Task Dependencies
11475

115-
- **vite_task** - Main task runner with caching and session management
116-
- **vite_task_bin** - CLI binary (`vt` command) and task synthesizer
117-
- **vite_task_graph** - Task dependency graph construction and config loading
118-
- **vite_task_plan** - Execution planning (resolves env vars, working dirs, commands)
119-
- **vite_workspace** - Workspace detection and package dependency graph
120-
- **fspy** - File system access tracking for precise cache invalidation
76+
1. **Explicit**: Defined via `dependsOn` in `vite-task.json` (skip with `--ignore-depends-on`)
77+
2. **Topological**: Based on package.json dependencies
78+
- With `-r/--recursive`: runs task across all packages in dependency order
79+
- With `-t/--transitive`: runs task in current package and its dependencies
12180

122-
## Task Configuration
81+
### Task Configuration
12382

12483
Tasks are defined in `vite-task.json`:
12584

@@ -140,37 +99,11 @@ Tasks are defined in `vite-task.json`:
14099
}
141100
```
142101

143-
- `cache` (root): workspace-wide cache toggle. Default: `{ "scripts": false, "tasks": true }`
144-
- `command`: shell command to run (required)
145-
- `cwd`: working directory relative to the package root
146-
- `dependsOn`: explicit task dependencies (`taskName` or `package#task`)
147-
- `cache` (task): enable/disable caching for this task (default: `true`)
148-
- `env`: env var names to fingerprint and pass to the task
149-
- `untrackedEnv`: env var names to pass without fingerprinting
150-
- `input`: files for cache fingerprinting (globs, `{ "auto": true }`, negation patterns)
151-
152-
## Task Dependencies
153-
154-
1. **Explicit**: Defined via `dependsOn` in `vite-task.json` (skip with `--ignore-depends-on`)
155-
2. **Topological**: Based on package.json dependencies
156-
- With `-r/--recursive`: runs task across all packages in dependency order
157-
- With `-t/--transitive`: runs task in current package and its dependencies
158-
159-
## Cross-Platform Linting
160-
161-
After major changes (especially to `fspy*` or platform-specific crates), run cross-platform clippy before pushing:
162-
163-
```bash
164-
just lint # native (host platform)
165-
just lint-linux # Linux via cargo-zigbuild
166-
just lint-windows # Windows via cargo-xwin
167-
```
168-
169102
## Code Constraints
170103

171104
### Required Patterns
172105

173-
These patterns are enforced by `.clippy.toml`:
106+
Enforced by `.clippy.toml`:
174107

175108
| Instead of | Use |
176109
| ----------------------------------- | ---------------------------------------- |
@@ -181,28 +114,23 @@ These patterns are enforced by `.clippy.toml`:
181114
| `std::env::current_dir` | `vite_path::current_dir` |
182115
| `.to_lowercase()`/`.to_uppercase()` | `cow_utils` methods |
183116

117+
### Path Type System
118+
119+
- Use `AbsolutePath` for internal data flow; only convert to `RelativePath` when saving to cache
120+
- Use methods like `strip_prefix`/`join` from `vite_path` instead of converting to std paths
121+
- Only convert to std paths when interfacing with std library functions
122+
- Add necessary methods in `vite_path` instead of falling back to std path types
123+
184124
### Cross-Platform Requirements
185125

186-
**All code must work on both Unix and Windows without platform skipping:**
126+
All code must work on both Unix and Windows without platform skipping:
187127

188128
- Use `#[cfg(unix)]` / `#[cfg(windows)]` for platform-specific implementations
189-
- Always test on both platforms (use `cargo xtest` for Windows cross-compilation)
190129
- Platform differences should be handled gracefully, not skipped
191-
- Document platform-specific behavior in code comments
192-
193-
## Path Type System
194-
195-
- **Type Safety**: All paths use typed `vite_path` instead of `std::path`
196-
- **Absolute Paths**: `vite_path::AbsolutePath` / `AbsolutePathBuf`
197-
- **Relative Paths**: `vite_path::RelativePath` / `RelativePathBuf`
198-
199-
- **Usage Guidelines**:
200-
- Use `AbsolutePath` for internal data flow; only convert to `RelativePath` when saving to cache
201-
- Use methods like `strip_prefix`/`join` from `vite_path` instead of converting to std paths
202-
- Only convert to std paths when interfacing with std library functions
203-
- Add necessary methods in `vite_path` instead of falling back to std path types
130+
- After major changes to `fspy*` or platform-specific crates, run `just lint-linux` and `just lint-windows`
204131

205132
## Quick Reference
206133

207134
- **Task Format**: `package#task` (e.g., `app#build`, `@test/utils#lint`)
208135
- **Config File**: `vite-task.json` in each package
136+
- **Rust Edition**: 2024, MSRV 1.88.0

‎CONTRIBUTING.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Contributing to Vite Task
2+
3+
## Prerequisites
4+
5+
- [Rust](https://rustup.rs/) (see [rust-toolchain.toml](rust-toolchain.toml) for the required version)
6+
- [Node.js](https://nodejs.org/) (^20.19.0 || >=22.12.0)
7+
- [pnpm](https://pnpm.io/) (10.x)
8+
- [just](https://just.systems/) — task runner for build commands
9+
- [cargo-binstall](https://github.com/cargo-bins/cargo-binstall) — for installing Rust tools
10+
11+
## Initial Setup
12+
13+
```bash
14+
just init
15+
```
16+
17+
This installs all required Rust tools (`cargo-insta`, `typos-cli`, `cargo-shear`, `dprint`, `taplo-cli`) and bootstraps the Node.js tooling.
18+
19+
## Development Workflow
20+
21+
Officially, Vite Task is distributed as part of Vite+ and invoked via `vp run`. The `vt` binary (`vite_task_bin` crate) is an internal development CLI for working on this repo in pure Rust without building the full Vite+ stack. Use `cargo run --bin vt` to build and run locally during development. Don't reference `vt` in user-facing documentation — it's not a public interface.
22+
23+
| | `vp run` (Vite+) | `vt run` (this repo) |
24+
| ------------ | -------------------------------------------- | -------------------- |
25+
| Purpose | End-user CLI | Internal dev/testing |
26+
| Config | `vite.config.ts` (`run` block) | `vite-task.json` |
27+
| Distribution | Bundled in Vite+ | `cargo run --bin vt` |
28+
| Scope | Full toolchain (dev, build, test, lint, ...) | Task runner only |
29+
30+
```bash
31+
just ready # Full quality check: typos, fmt, check, test, lint, doc
32+
just fmt # Format code (cargo fmt + cargo shear + dprint)
33+
just check # Check compilation with all features
34+
just test # Run all tests
35+
just lint # Clippy linting
36+
just doc # Generate documentation
37+
```
38+
39+
### Running Specific Tests
40+
41+
```bash
42+
cargo test # All tests
43+
cargo test -p vite_task_bin --test e2e_snapshots # E2E snapshot tests
44+
cargo test -p vite_task_plan --test plan_snapshots # Plan snapshot tests
45+
cargo test --test e2e_snapshots -- stdin # Filter by test name
46+
INSTA_UPDATE=always cargo test # Update snapshots
47+
```
48+
49+
Integration tests (e2e, plan, fspy) require `pnpm install` in `packages/tools` first. You don't need `pnpm install` in test fixture directories.
50+
51+
### Test Fixtures
52+
53+
- **Plan snapshots** — `crates/vite_task_plan/tests/plan_snapshots/fixtures/` — quicker, sufficient for testing task graph, resolved configs, program paths, cwd, and env vars
54+
- **E2E snapshots** — `crates/vite_task_bin/tests/e2e_snapshots/fixtures/` — needed for testing actual execution, caching behavior, and output styling
55+
56+
See individual crate READMEs for crate-specific testing details.
57+
58+
## Cross-Platform Development
59+
60+
This project must work on macOS, Linux, and Windows. Skipping tests on any platform is not acceptable.
61+
62+
- Use `#[cfg(unix)]` / `#[cfg(windows)]` for platform-specific code
63+
- Use cross-platform libraries where possible (e.g., `terminal_size` instead of raw ioctl/ConPTY)
64+
65+
### Cross-Platform Linting
66+
67+
After changes to `fspy*` or platform-specific crates, run cross-platform clippy:
68+
69+
```bash
70+
just lint # Native (host platform)
71+
just lint-linux # Linux via cargo-zigbuild
72+
just lint-windows # Windows via cargo-xwin
73+
```
74+
75+
## Code Conventions
76+
77+
### Required Patterns
78+
79+
These are enforced by `.clippy.toml`:
80+
81+
| Instead of | Use |
82+
| ------------------------------------- | ------------------------------------------ |
83+
| `HashMap` / `HashSet` | `FxHashMap` / `FxHashSet` from rustc-hash |
84+
| `std::path::Path` / `PathBuf` | `vite_path::AbsolutePath` / `RelativePath` |
85+
| `std::format!` | `vite_str::format!` |
86+
| `String` (for small strings) | `vite_str::Str` |
87+
| `std::env::current_dir` | `vite_path::current_dir` |
88+
| `.to_lowercase()` / `.to_uppercase()` | `cow_utils` methods |
89+
90+
### Path Type System
91+
92+
All paths use `vite_path` for type safety:
93+
94+
- **`AbsolutePath` / `AbsolutePathBuf`** — for internal data flow
95+
- **`RelativePath` / `RelativePathBuf`** — for cache storage and display
96+
97+
Use `vite_path` methods (`strip_prefix`, `join`, etc.) instead of converting to `std::path`. Only convert to std paths when interfacing with std library functions. Add necessary methods to `vite_path` rather than falling back.
98+
99+
## macOS Performance Tip
100+
101+
Add your terminal app to the approved "Developer Tools" in System Settings > Privacy & Security. Your Rust builds will be ~30% faster.

‎README.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,20 @@
11
# Vite Task
2+
3+
Monorepo task runner with intelligent caching and dependency-aware scheduling, powering [`vp run`](https://github.com/voidzero-dev/vite-plus) in [Vite+](https://viteplus.dev).
4+
5+
## Getting Started
6+
7+
Install [Vite+](https://viteplus.dev), then run tasks from your workspace. See the [documentation](https://viteplus.dev/guide/run) for full usage.
8+
9+
```bash
10+
vp run build # run a task in the current package
11+
vp run build -r # run across all packages in dependency order
12+
vp run @my/app#build -t # run in a package and its transitive dependencies
13+
vp run --cache build # run with caching enabled
14+
```
15+
16+
## License
17+
18+
[MIT](LICENSE)
19+
20+
Copyright (c) 2026-present [VoidZero Inc.](https://voidzero.dev/)

0 commit comments

Comments
 (0)