Debian Codegraph @

.windsurfrules

raw
1 <!-- Canonical source: AGENTS.md — keep this file in sync -->
2 # AGENTS.md — node-re2
3
4 > `node-re2` provides Node.js bindings for [RE2](https://github.com/google/re2): a fast, safe alternative to backtracking regular expression engines. The npm package name is `re2`. It is a C++ native addon built with `node-gyp` and `nan`.
5
6 For project structure, module dependencies, and the architecture overview see [ARCHITECTURE.md](./ARCHITECTURE.md).
7 For detailed usage docs see the [README](./README.md) and the [wiki](https://github.com/uhop/node-re2/wiki).
8
9 ## Setup
10
11 This project uses git submodules for vendored dependencies (RE2 and Abseil):
12
13 ```bash
14 git clone --recursive https://github.com/uhop/node-re2.git
15 cd node-re2
16 npm install
17 ```
18
19 If the native addon fails to download a prebuilt artifact, it builds locally via `node-gyp`.
20
21 **Supported Node.js versions:** `^22.22.2 || ^24.15.0 || >=26.0.0` (the `engines` field). Narrowed in 1.25.0 to mirror `node-gyp` 13 — Node 25.x and the older 22.0–22.22.1 / 24.0–24.14 patch ranges are no longer supported.
22
23 ## Commands
24
25 - **Install:** `npm install` (downloads prebuilt artifact or builds from source)
26 - **Build (release):** `npm run rebuild` (or `node-gyp -j max rebuild`)
27 - **Build (debug):** `npm run rebuild:dev` (or `node-gyp -j max rebuild --debug`)
28 - **Test:** `npm test` (runs `tape6 --flags FO`, worker threads)
29 - **Test (sequential):** `npm run test:seq`
30 - **Test (multi-process):** `npm run test:proc`
31 - **Test (single file):** `node tests/test-<name>.mjs`
32 - **TypeScript check:** `npm run ts-check`
33 - **Lint:** `npm run lint` (Prettier check)
34 - **Lint fix:** `npm run lint:fix` (Prettier write)
35 - **Verify build:** `npm run verify-build`
36
37 ## Project structure
38
39 ```
40 node-re2/
41 ├── package.json # Package config; "tape6" section configures test discovery
42 ├── binding.gyp # node-gyp build configuration for the C++ addon
43 ├── re2.js # Main entry point: loads native addon, sets up Symbol aliases
44 ├── re2.d.ts # TypeScript declarations for the public API
45 ├── tsconfig.json # TypeScript config (noEmit, strict, types: ["node"])
46 ├── lib/ # C++ source code (native addon)
47 │ ├── addon.cc # Node.js addon initialization, method registration
48 │ ├── wrapped_re2.h # WrappedRE2 class definition (core C++ wrapper)
49 │ ├── wrapped_re2_set.h # WrappedRE2Set class definition (RE2.Set wrapper)
50 │ ├── isolate_data.h # Per-isolate data struct for thread-safe addon state
51 │ ├── new.cc # Constructor: parse pattern/flags, create RE2 instance
52 │ ├── exec.cc # RE2.prototype.exec() implementation
53 │ ├── test.cc # RE2.prototype.test() implementation
54 │ ├── match.cc # RE2.prototype.match() implementation
55 │ ├── replace.cc # RE2.prototype.replace() implementation
56 │ ├── search.cc # RE2.prototype.search() implementation
57 │ ├── split.cc # RE2.prototype.split() implementation
58 │ ├── to_string.cc # RE2.prototype.toString() implementation
59 │ ├── accessors.cc # Property accessors (source, flags, lastIndex, etc.)
60 │ ├── pattern.cc # Pattern translation (RegExp → RE2 syntax, Unicode classes)
61 │ ├── set.cc # RE2.Set implementation (multi-pattern matching)
62 │ ├── util.cc # Shared utilities (UTF-8/UTF-16 conversion, buffer helpers)
63 │ ├── util.h # Utility declarations
64 │ └── pattern.h # Pattern translation declarations
65 ├── scripts/
66 │ └── verify-build.js # Quick smoke test for the built addon
67 ├── tests/ # Test files (test-*.mjs using tape-six)
68 ├── ts-tests/ # TypeScript type-checking tests
69 │ └── test-types.ts # Verifies type declarations compile correctly
70 ├── bench/ # Benchmarks
71 ├── vendor/ # Vendored C++ dependencies (git submodules)
72 │ ├── re2/ # Google RE2 library source
73 │ └── abseil-cpp/ # Abseil C++ library (RE2 dependency)
74 └── .github/ # CI workflows, Dependabot config, actions
75 ```
76
77 ## Code style
78
79 - **CommonJS** throughout (`"type": "commonjs"` in package.json).
80 - **No transpilation** — JavaScript code runs directly.
81 - **C++ code** uses tabs for indentation, 4-wide. JavaScript uses 2-space indentation.
82 - **Prettier** for JS/TS formatting (see `.prettierrc`): 80 char width, single quotes, no bracket spacing, no trailing commas, arrow parens "avoid".
83 - **nan** (Native Abstractions for Node.js) for the C++ addon API.
84 - Semicolons are enforced by Prettier (default `semi: true`).
85 - Imports use `require()` syntax in source, `import` in tests (`.mjs`).
86
87 ## Critical rules
88
89 - **Do not modify vendored code.** Never edit files under `vendor/`. They are git submodules.
90 - **Do not modify or delete test expectations** without understanding why they changed.
91 - **Do not add comments or remove comments** unless explicitly asked.
92 - **Keep `re2.js` and `re2.d.ts` in sync.** All public API exposed from `re2.js` must be typed in `re2.d.ts`.
93 - **The addon must build on all supported platforms:** Linux (x64, arm64, Alpine), macOS (x64, arm64), Windows (x64, arm64).
94 - **RE2 is always Unicode-mode.** The `u` flag is always added implicitly.
95 - **Buffer support is a first-class feature.** All methods that accept strings must also accept Buffers, returning Buffers when given Buffer input.
96
97 ## Architecture
98
99 - `re2.js` is the main entry point. It loads the native C++ addon from `build/Release/re2.node` and sets up `Symbol.match`, `Symbol.search`, `Symbol.replace`, `Symbol.split`, and `Symbol.matchAll` on the prototype.
100 - The C++ addon (`lib/*.cc`) wraps Google's RE2 library via nan. Each RegExp method has its own `.cc` file.
101 - `lib/new.cc` handles construction: parsing patterns, translating RegExp syntax to RE2 syntax (via `lib/pattern.cc`), and creating the underlying `re2::RE2` instance.
102 - `lib/pattern.cc` translates JavaScript RegExp features to RE2 equivalents. General_Category and Script are mapped to RE2-native names (`\p{Letter}` → `\p{L}`, `\p{Script=Latin}` → `\p{Latin}`); binary properties (Emoji, Alphabetic, ASCII, ID_Start, …) and Script_Extensions are expanded inline to codepoint-range character classes using tables in `lib/unicode_properties.h`. The full accepted set matches [MDN's Unicode character class escape reference](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Unicode_character_class_escape) (excluding `v`-flag Properties of Strings). Tables are auto-generated from `@unicode/unicode-17.0.0` via `node scripts/gen-unicode-properties.mjs`.
103 - `lib/set.cc` implements `RE2.Set` for multi-pattern matching using `re2::RE2::Set`.
104 - `lib/util.cc` provides UTF-8 ↔ UTF-16 conversion helpers and buffer utilities.
105 - Prebuilt native artifacts are hosted on GitHub Releases and downloaded at install time via `install-artifact-from-github`.
106
107 ## Writing tests
108
109 ```js
110 import test from 'tape-six';
111 import {RE2} from '../re2.js';
112
113 test('example', t => {
114 const re = new RE2('a(b*)', 'i');
115 const result = re.exec('aBbC');
116 t.ok(result);
117 t.equal(result[0], 'aBb');
118 t.equal(result[1], 'Bb');
119 });
120 ```
121
122 - Test files use `tape-six`: `.mjs` for runtime tests, `.ts` for TypeScript typing tests.
123 - Test file naming convention: `test-*.mjs` in `tests/`, `test-*.ts` in `ts-tests/`.
124 - Tests are configured in `package.json` under the `"tape6"` section.
125 - Test files should be directly executable: `node tests/test-foo.mjs`.
126
127 ## Key conventions
128
129 - The library is a drop-in replacement for `RegExp` — the `RE2` object emulates the standard `RegExp` API.
130 - `RE2.Set` provides multi-pattern matching: `new RE2.Set(patterns, flags, options)`.
131 - Static helpers: `RE2.getUtf8Length(str)`, `RE2.getUtf16Length(buf)`.
132 - `RE2.unicodeWarningLevel` controls behavior when non-Unicode regexps are created.
133 - The `install` script tries to download a prebuilt `.node` artifact before falling back to `node-gyp rebuild`.
134 - All C++ source is in `lib/`, all vendored third-party C++ is in `vendor/`.