|
1 | 1 | # Rollup - Agent Instructions |
2 | 2 |
|
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. |
4 | 4 |
|
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` |
6 | 73 |
|
7 | 74 | ## Testing |
8 | 75 |
|
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