Skip to content

Commit 9279ddf

Browse files
CopilotHerringtonDarkholme
Copilot
and
HerringtonDarkholme
authored
Add GitHub Copilot custom instructions for ast-grep.github.io repository (#803)
* Initial plan * Add GitHub Copilot custom instructions for ast-grep.github.io Co-authored-by: HerringtonDarkholme <[email protected]> --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: HerringtonDarkholme <[email protected]>
1 parent 09182e6 commit 9279ddf

File tree

1 file changed

+153
-0
lines changed

1 file changed

+153
-0
lines changed

‎.github/copilot-instructions.md

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# GitHub Copilot Instructions
2+
3+
## Repository Overview
4+
5+
This repository contains the documentation website source code for **ast-grep**, a lightning-fast and user-friendly tool for code searching, linting, and rewriting at large scale. The website is built using VitePress and serves as the comprehensive documentation hub for the ast-grep project.
6+
7+
## Technology Stack
8+
9+
- **Frontend Framework**: VitePress (static site generator based on Vue.js)
10+
- **Programming Languages**:
11+
- TypeScript/JavaScript (website functionality)
12+
- Rust (WASM compilation for in-browser ast-grep functionality)
13+
- **Package Manager**: **pnpm** (NOT npm - this is important!)
14+
- **Build Tools**:
15+
- wasm-pack (for Rust to WASM compilation)
16+
- Vite (bundling and development server)
17+
- Vue TypeScript compiler (vue-tsc)
18+
- **Linting/Formatting**:
19+
- oxlint (JavaScript/TypeScript linting)
20+
- dprint (code formatting)
21+
22+
## Important: Package Manager Usage
23+
24+
**⚠️ This repository uses pnpm instead of npm!**
25+
26+
Always use `pnpm` commands:
27+
- `pnpm install` (not `npm install`)
28+
- `pnpm run dev` (not `npm run dev`)
29+
- `pnpm run build` (not `npm run build`)
30+
31+
The project has a `pnpm-lock.yaml` file and is configured to work specifically with pnpm.
32+
33+
## Development Setup
34+
35+
1. **Prerequisites**:
36+
- Install Rust toolchain
37+
- Install wasm-pack: `cargo install wasm-pack`
38+
- Install pnpm: `npm install -g pnpm`
39+
40+
2. **Initial Setup**:
41+
```bash
42+
# Build WASM package
43+
wasm-pack build --target web
44+
45+
# Install dependencies
46+
pnpm install
47+
48+
# Start development server
49+
pnpm dev
50+
```
51+
52+
3. **Development Workflow**:
53+
- For WASM changes: Rebuild with `wasm-pack build --target web`
54+
- For website changes: Use `pnpm dev` for hot reloading
55+
- Visit `localhost:5173` for development preview
56+
57+
## Project Structure
58+
59+
```
60+
├── src/ # Rust source code for WASM bindings
61+
├── website/ # VitePress website source
62+
│ ├── .vitepress/ # VitePress configuration
63+
│ ├── guide/ # User guide documentation
64+
│ ├── reference/ # API and CLI reference
65+
│ ├── catalog/ # Rule examples by language
66+
│ ├── playground.md # Interactive playground page
67+
│ └── index.md # Homepage
68+
├── pkg/ # Generated WASM package (git-ignored)
69+
├── Cargo.toml # Rust dependencies
70+
├── package.json # Node.js dependencies and scripts
71+
└── pnpm-lock.yaml # pnpm lockfile
72+
```
73+
74+
## Available Scripts
75+
76+
- `pnpm dev`: Start development server with hot reloading
77+
- `pnpm build`: Build production website
78+
- `pnpm serve`: Preview production build locally
79+
- `pnpm lint`: Run linting (oxlint + dprint)
80+
- `pnpm lint:fix`: Fix linting issues automatically
81+
82+
## Coding Guidelines
83+
84+
### For TypeScript/JavaScript:
85+
- Use TypeScript for type safety
86+
- Follow Vue 3 Composition API patterns
87+
- Prefer `async/await` over promises
88+
- Use `const` over `let` when possible
89+
- Follow existing code style (enforced by oxlint and dprint)
90+
91+
### For Rust:
92+
- Focus on WASM bindings and web-compatible APIs
93+
- Use `wasm-bindgen` for JavaScript interop
94+
- Keep WASM bundle size optimized
95+
- Handle errors gracefully for web environment
96+
97+
### For Documentation:
98+
- Use clear, concise language
99+
- Include code examples for concepts
100+
- Test examples in the playground when possible
101+
- Maintain consistent formatting across pages
102+
103+
## WASM Integration
104+
105+
The repository includes Rust code that compiles to WebAssembly to provide ast-grep functionality in the browser:
106+
107+
- Rust source in `src/`
108+
- Compiled to `pkg/` directory (git-ignored)
109+
- Imported as optional dependency: `"ast-grep-wasm": "file:./pkg/"`
110+
- Used in playground and interactive features
111+
112+
## Common Tasks
113+
114+
### Adding New Documentation:
115+
1. Create markdown files in appropriate `website/` subdirectory
116+
2. Update navigation in `website/.vitepress/config.ts`
117+
3. Test locally with `pnpm dev`
118+
119+
### Updating WASM Functionality:
120+
1. Modify Rust code in `src/`
121+
2. Rebuild with `wasm-pack build --target web`
122+
3. Test integration in browser features
123+
124+
### Adding Dependencies:
125+
- Use `pnpm add <package>` for runtime dependencies
126+
- Use `pnpm add -D <package>` for development dependencies
127+
- Update Rust dependencies in `Cargo.toml` if needed
128+
129+
## Build and Deployment
130+
131+
The website is automatically deployed via GitHub Actions:
132+
1. Builds WASM package with `wasm-pack`
133+
2. Installs dependencies with `pnpm`
134+
3. Builds website with `pnpm build`
135+
4. Deploys to GitHub Pages
136+
137+
## Best Practices
138+
139+
1. **Always use pnpm** instead of npm
140+
2. Test WASM changes thoroughly in browser
141+
3. Maintain documentation quality and accuracy
142+
4. Follow existing naming conventions
143+
5. Update navigation when adding new pages
144+
6. Ensure examples work in the playground
145+
7. Keep build times reasonable by optimizing WASM size
146+
8. Use TypeScript types for better developer experience
147+
148+
## Troubleshooting
149+
150+
- **WASM not loading**: Rebuild with `wasm-pack build --target web`
151+
- **Dependencies issues**: Delete `node_modules` and run `pnpm install`
152+
- **Build failures**: Check that wasm-pack and pnpm are properly installed
153+
- **Playground not working**: Ensure tree-sitter WASM files are in `website/public/`

0 commit comments

Comments
 (0)