Skip to content

Commit 7f00689

Browse files
committed
Extend agent instructions
1 parent e7b2b85 commit 7f00689

3 files changed

Lines changed: 103 additions & 2 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 53 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,68 @@
22

33
Keep instructions concise, only add non-obvious information. Proactively update .github/copilot-instructions.md to prevent future mistakes.
44

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+
510
## Architecture
611

712
- 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
814
- Tests run against full artifact only—no unit tests to allow easy refactoring of internal APIs
915
- Test cases in `test/*/samples/` are configured via `_config.js` files; focus tests with `solo: true`
1016
- See CONTRIBUTING.md "How to write tests" for test type selection (function/form/chunking-form/cli/etc.)
1117

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+
1239
## Development Workflow
1340

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`
1667

1768
## Testing
1869

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
applyTo: 'test/**'
3+
description: 'How to write and run tests for this project'
4+
---
5+
6+
# Test types
7+
8+
- directory based tests
9+
- should be preferred for tests if possible
10+
- reside in directories in test/<category>/samples
11+
- each test has a \_config.js file with a description field and potentially other configuration options
12+
- the preferred way to work on a single or few of those tests is to add "solo: true" to the test's \_config.js file first, and then run
13+
```
14+
npm run build:quick
15+
npm run test:quick
16+
```
17+
- each test category is run by a test/<category>/index.js file
18+
- the available options for each test category are defined in test/types.d.ts
19+
- see below for the different categories
20+
- traditional file based tests
21+
- are run directly by mocha using "describe" and "it" blocks
22+
- can be found in test/misc/, test/hooks and test/incremental
23+
24+
# Test categories
25+
26+
- function
27+
- will bundle a main.js file next to the \_config.js file and then run it
28+
- have node:assert injected as a global variable in the bundled test code (main.js), allowing you to use `assert` directly without importing
29+
- in \_config.js, you must explicitly require assert: `const assert = require('node:assert/strict');` to use it in the `exports` function or other config functions
30+
- when testing if bundled code still works (use inline assert in the code or the exports field in \_config.js to make assertions)
31+
- when testing build errors
32+
- when testing warnings
33+
- when testing plugin hooks
34+
- form
35+
- will bundle a main.js file next to the \_config.js file and store the output either as an \_actual directory with outputs for each format (es.js, cjs.js, amd.js, system.js, umd.js, iife.js) or an \_actual.js file for a single format. Those will be compared with an existing \_expected directory or \_expected.js file
36+
- the single \_actual.js file will be generated if an \_expected.js file is present. Having a single file is preferred, so when writing a form test, start with writing the \_expected.js file before running the test for the first time
37+
- chunking-form
38+
- similar to form, but they always generate all formats and produce a separate directory for each format. The entire directory is compared with an \_expected directory
39+
- when multiple files are expected in the output
40+
- cli
41+
- when running rollup as a command line tool

‎AGENTS.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Rollup - Agent Instructions
2+
3+
This file provides AI agents with references to detailed conventions and patterns for working with the Cart2Order codebase.
4+
5+
Always read this file first: @.github/copilot-instructions.md
6+
7+
## Testing
8+
9+
For how to write tests, read @.github/instructions/TESTS.instructions.md

0 commit comments

Comments
 (0)