Skip to content

Commit b74aa39

Browse files
lukastaegertlukastaegert
committed
Migrate instructions to AGENTS.md
1 parent aa5a377 commit b74aa39

3 files changed

Lines changed: 111 additions & 127 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 0 additions & 83 deletions
This file was deleted.

‎.github/instructions/TESTS.instructions.md‎

Lines changed: 0 additions & 41 deletions
This file was deleted.

‎AGENTS.md‎

Lines changed: 111 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,117 @@
11
# Rollup - Agent Instructions
22

3-
This file provides AI agents with references to detailed conventions and patterns for working with the Cart2Order codebase.
3+
Keep instructions concise, only add non-obvious information. Proactively update AGENTS.md to prevent future mistakes.
44

5-
Always read this file first: @.github/copilot-instructions.md
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+
10+
## Architecture
11+
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
14+
- Tests run against full artifact only—no unit tests to allow easy refactoring of internal APIs
15+
- Test cases in `test/*/samples/` are configured via `_config.js` files; focus tests with `solo: true`
16+
- See CONTRIBUTING.md "How to write tests" for test type selection (function/form/chunking-form/cli/etc.)
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+
39+
## Browser Path Shim
40+
41+
- `browser/src/path.ts` replaces `node:path` in the browser build (wired via `rollup.config.ts` aliases)
42+
- `src/utils/relativeId.ts` imports `relative` **directly** from `../../browser/src/path` (not via `src/utils/path.ts`) so it works in both builds
43+
- `src/utils/path.ts` re-exports from `node:path`; for browser builds rollup.config.ts substitutes `browser/src/path.ts` transparently for all other imports
44+
45+
## Development Workflow
46+
47+
### Build Outputs
48+
49+
- **Node build**: Artifacts placed in `dist/` (JavaScript + `.node` native modules)
50+
- **Browser build**: Artifacts placed in `browser/dist/`; browser tests use `browser/dist/rollup.browser.js`
51+
- All tests import from these dist folders - tests run against the full built artifact only
52+
53+
### Quick Rebuild Commands
54+
55+
- `npm run build:quick` - Rebuild both JavaScript and Rust for Node build, copy to dist/
56+
- `npm run update:js` - Rebuild only JavaScript for both Node (`dist/`) and browser (`browser/dist/`), then copy native to dist/; run this after any change to `src/` or `browser/src/`
57+
- `npm run update:napi` - Rebuild only Rust NAPI, copy to dist/
58+
- `npm run build:copy-native` - Copy Rust `.node` files to dist/ (called internally by update commands)
59+
60+
### Full Build Commands
61+
62+
- `npm run build` - Full build: WASM + AST converters + NAPI (release) + JavaScript + copy native
63+
- `npm run build:napi` - Build Rust NAPI bindings (use `-- --release` for optimized)
64+
- `npm run build:wasm` - Build browser WASM
65+
- `npm run build:js` - Build JavaScript (Node and browser)
66+
67+
### Common Workflows
68+
69+
- **Rust changes only**: `npm run update:napi` then `npm run test:only`
70+
- **JavaScript changes only**: `npm run update:js` then `npm run test:only`
71+
- **AST schema changes**: `npm run build:ast-converters` to regenerate TypeScript and Rust files
72+
- **Testing changes**: `npm run build:quick` then `npm run test:only`
673

774
## Testing
875

9-
For how to write tests, read @.github/instructions/TESTS.instructions.md
76+
- Always test edge cases, especially in core logic or build/test infrastructure
77+
- Test names and descriptions use clear, descriptive language of the expected behavior, e.g. "description: 'does X when Y happens"
78+
79+
### Test Types
80+
81+
- Directory based tests
82+
- Should be preferred for tests if possible
83+
- Reside in directories in `test/<category>/samples`
84+
- Each test has a `_config.js` file with a description field and potentially other configuration options
85+
- 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:
86+
```
87+
npm run build:quick
88+
npm run test:quick
89+
```
90+
- Each test category is run by a `test/<category>/index.js` file
91+
- The available options for each test category are defined in `test/types.d.ts`
92+
- Traditional file based tests
93+
- Are run directly by mocha using `describe` and `it` blocks
94+
- Can be found in `test/misc/`, `test/hooks` and `test/incremental`
95+
96+
### Test Categories
97+
98+
- **function**
99+
- Will bundle a `main.js` file next to the `_config.js` file and then run it
100+
- Has `node:assert` injected as a global variable in the bundled test code (`main.js`), allowing you to use `assert` directly without importing
101+
- 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
102+
- Use when testing if bundled code still works (use inline assert in the code or the exports field in `_config.js` to make assertions)
103+
- Use when testing build errors, warnings, or plugin hooks
104+
- **form**
105+
- Will bundle a `main.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, compared with an existing `_expected` directory or `_expected.js` file
106+
- 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
107+
- **chunking-form**
108+
- Similar to form, but always generates all formats and produces a separate directory for each format; the entire directory is compared with an `_expected` directory
109+
- Use when multiple files are expected in the output
110+
- **cli**
111+
- Use when running rollup as a command line tool
112+
113+
## Code Review Focus
114+
115+
- **Ignore style/linting issues** in test sample files (`test/*/samples/`) except for `_config.js` files
116+
- Test samples intentionally violate best practices to test edge cases—do not flag style violations in these files
117+
- Focus reviews on production code quality

0 commit comments

Comments
 (0)