|
2 | 2 |
|
3 | 3 | Keep instructions concise, only add non-obvious information. Proactively update .github/copilot-instructions.md to prevent future mistakes. |
4 | 4 |
|
| 5 | +## General |
| 6 | + |
| 7 | +- Variables and functions should have clear, descriptive names that reflect their purpose and behavior and not e.g. their data types. |
| 8 | +- Code should be organized so that things that will most likely change together are located near each other, instead of e.g. grouping solely by technical categories. |
| 9 | + |
5 | 10 | ## Architecture |
6 | 11 |
|
7 | 12 | - TypeScript + Rust hybrid: Rust code in `rust/` (bindings_napi, bindings_wasm, parse_ast crates) called via `native.js` and `native.wasm.js` |
| 13 | +- Generated files: Files with "Do not edit this file directly" comments (e.g., `src/ast/bufferParsers.ts`, `src/ast/childNodeKeys.ts`, `src/ast/nodeIds.ts`) are generated from `scripts/ast-types.ts` via `scripts/generate-ast-converters.ts` and files that are imported in that file |
8 | 14 | - Tests run against full artifact only—no unit tests to allow easy refactoring of internal APIs |
9 | 15 | - Test cases in `test/*/samples/` are configured via `_config.js` files; focus tests with `solo: true` |
10 | 16 | - See CONTRIBUTING.md "How to write tests" for test type selection (function/form/chunking-form/cli/etc.) |
11 | 17 |
|
| 18 | +## JS-Rust Interface |
| 19 | + |
| 20 | +When adding/modifying functions that cross the JS-Rust boundary: |
| 21 | + |
| 22 | +1. **Rust implementations**: Update `rust/bindings_napi/src/lib.rs` (Node native) and `rust/bindings_wasm/src/lib.rs` (WASM) |
| 23 | +2. **JS handover points** (must have matching signatures): |
| 24 | + - `native.js` - Node native build (NAPI) |
| 25 | + - `native.wasm.js` - Node WASM build |
| 26 | + - `browser/src/wasm.ts` - Browser WASM build |
| 27 | +3. **Build process**: `rollup.config.ts` replaces `native.js` with `browser/src/wasm.ts` for browser builds; CI replaces it with `native.wasm.js` for Node WASM builds |
| 28 | +4. **TypeScript definitions**: `native.d.ts` is auto-generated by napi-rs for NAPI bindings; WASM types are generated in `wasm/bindings_wasm.d.ts` |
| 29 | +5. **Testing builds** (will also generate definitions): |
| 30 | + - Node native: `npm run build:napi` |
| 31 | + - Browser WASM: `npm run build:wasm` |
| 32 | + - Node WASM: `npm run build:wasm:node` |
| 33 | + |
| 34 | +## Rust Code Organization |
| 35 | + |
| 36 | +- Focus on performance, avoid unnecessary copying of data or AST loops, build the final buffer once |
| 37 | +- When adding headers, reserve space for them once upfront to avoid the need to change all existing buffer references |
| 38 | + |
12 | 39 | ## Development Workflow |
13 | 40 |
|
14 | | -- Quick iteration: `npm run update:js` (TS changes) or `npm run update:napi` (Rust changes), then `npm run test:only` |
15 | | -- Rust only: `npm run build:napi` |
| 41 | +### Build Outputs |
| 42 | + |
| 43 | +- **Node build**: Artifacts placed in `dist/` (JavaScript + `.node` native modules) |
| 44 | +- **Browser build**: Artifacts placed in `browser/dist/` |
| 45 | +- All tests import from these dist folders - tests run against the full built artifact only |
| 46 | + |
| 47 | +### Quick Rebuild Commands |
| 48 | + |
| 49 | +- `npm run build:quick` - Rebuild both JavaScript and Rust for Node build, copy to dist/ |
| 50 | +- `npm run update:js` - Rebuild only JavaScript for Node, copy native to dist/ |
| 51 | +- `npm run update:napi` - Rebuild only Rust NAPI, copy to dist/ |
| 52 | +- `npm run build:copy-native` - Copy Rust `.node` files to dist/ (called internally by update commands) |
| 53 | + |
| 54 | +### Full Build Commands |
| 55 | + |
| 56 | +- `npm run build` - Full build: WASM + AST converters + NAPI (release) + JavaScript + copy native |
| 57 | +- `npm run build:napi` - Build Rust NAPI bindings (use `-- --release` for optimized) |
| 58 | +- `npm run build:wasm` - Build browser WASM |
| 59 | +- `npm run build:js` - Build JavaScript (Node and browser) |
| 60 | + |
| 61 | +### Common Workflows |
| 62 | + |
| 63 | +- **Rust changes only**: `npm run update:napi` then `npm run test:only` |
| 64 | +- **JavaScript changes only**: `npm run update:js` then `npm run test:only` |
| 65 | +- **AST schema changes**: `npm run build:ast-converters` to regenerate TypeScript and Rust files |
| 66 | +- **Testing changes**: `npm run build:quick` then `npm run test:only` |
16 | 67 |
|
17 | 68 | ## Testing |
18 | 69 |
|
|
0 commit comments