@barqjs/compiler 0.0.0-stage → 0.2.0-next.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Salama Ashoush
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,242 @@
1
- # Temporary Holding Version
1
+ # @barqjs/compiler
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The barq JSX compiler, written in Rust on [oxc](https://oxc.rs) and loaded into
4
+ Node or Bun through napi-rs. It turns JSX into templates that are cloned once
5
+ and runtime calls from `@barqjs/web` that update only the holes that read a
6
+ signal, with the reactive calls from `@barqjs/core`. With `ssr: true` the same
7
+ analysis emits a string renderer that imports `@barqjs/server` instead, and
8
+ with `target: "universal"` it builds every element through a custom renderer
9
+ made with `@barqjs/universal`.
10
+
11
+ It also generates the file route table, splits route and middleware modules into
12
+ their client and server halves, compiles `@barqjs/css` blocks to a stylesheet,
13
+ and reports mistakes before the code runs: 28 [diagnostics](./docs/README.md),
14
+ each with a stable `BARQ` code, a page that shows the fix, and a required reason
15
+ to silence it.
16
+
17
+ ## Install
18
+
19
+ Applications do not call this package. `@barqjs/vite` depends on it and runs it
20
+ on every `.jsx` and `.tsx` file:
21
+
22
+ ```bash
23
+ bun add -d @barqjs/vite
24
+ ```
25
+
26
+ ```ts
27
+ import barq from "@barqjs/vite";
28
+ import { defineConfig } from "vite";
29
+
30
+ export default defineConfig({
31
+ plugins: [barq()],
32
+ });
33
+ ```
34
+
35
+ There is one pipeline. If the native binary cannot be loaded, the plugin throws
36
+ rather than compiling the file some other way.
37
+
38
+ The binary is built per platform. The targets are listed under `napi.targets` in
39
+ `package.json`: Linux x64 and arm64 (glibc), macOS x64 and arm64, and Windows
40
+ x64 and arm64.
41
+
42
+ ## Coming from Solid
43
+
44
+ The output has the shape Solid 2.0's `@solidjs/compiler` produces: a static
45
+ template per element tree, cloned, then one binding per dynamic hole, with
46
+ delegated events.
47
+
48
+ Where it differs:
49
+
50
+ - A component writes a prop as its value, `props.name` or a destructured
51
+ `{ name }`, and both stay live. The props record holds a Cell per prop, a
52
+ function, and the compiler writes the call that reads it. Solid passes a
53
+ getter on the props object, so destructuring there reads once.
54
+ `cells(props)` gives the record itself, where a Cell is wanted unread.
55
+ - What is reactive is decided from the binding a name resolves to (oxc's
56
+ `SymbolId`), never from how it is spelled. `createSignal` imported under
57
+ another name is still a signal.
58
+ - The checks run in the compiler, one file at a time, and print a code with a
59
+ docs page. See [docs/README.md](./docs/README.md).
60
+
61
+ ## Writing code the compiler understands
62
+
63
+ Call an accessor where you want its value. The compiler wraps each JSX
64
+ expression in its own tracked scope, so `{count() * 2}` updates when `count`
65
+ changes. Code outside JSX is left as written, so a derived value there is a
66
+ function or a memo:
67
+
68
+ ```tsx
69
+ import { createMemo, createSignal } from "@barqjs/core";
70
+
71
+ const [count, setCount] = createSignal(0);
72
+ const doubled = createMemo(() => count() * 2);
73
+
74
+ export const Counter = () => (
75
+ <button type="button" onClick={() => setCount(count() + 1)}>
76
+ {count()} doubled is {doubled()}
77
+ </button>
78
+ );
79
+ ```
80
+
81
+ Passing the accessor itself, `{count}`, is also live. Using it as a value,
82
+ `count * 2` or `` `${count}` ``, is a bug that
83
+ [BARQ001](./docs/BARQ001.md) reports.
84
+
85
+ Props are written as values. `props.title` and a destructured
86
+ `{ title, tone = "warm", ...rest }` both follow the prop, because the compiler
87
+ writes each read. An object spread onto a component, `<Chip {...options} />`,
88
+ is an object of values too.
89
+
90
+ ## API
91
+
92
+ ```ts
93
+ import { transform } from "@barqjs/compiler";
94
+
95
+ const { code, map, warnings, diagnostics } = transform(source, {
96
+ filename: "App.tsx",
97
+ sourcemap: true,
98
+ dev: false,
99
+ ssr: false,
100
+ });
101
+ ```
102
+
103
+ `transform(code, options)` compiles one module. The options a caller sets:
104
+
105
+ - `filename`: used in diagnostics and source maps. The accessor and props checks
106
+ run only when it ends in `.jsx` or `.tsx`.
107
+ - `sourcemap`: return `map`. Without it `map` is absent, not `null`.
108
+ - `ssr`: emit the string backend for the server. In Vite this is per module, so
109
+ the plugin reads it from the transform hook rather than from its own options.
110
+ - `hydratable`: emit the markers a server-rendered page hydrates against. Off by
111
+ default, so a page that is never hydrated does not pay for them.
112
+ - `dev`: the development build. Turns on the dev-only diagnostics, template
113
+ labels and source locations.
114
+ - `sourceNames`: carry names and positions into the output for the runtime's
115
+ findings. A signal, memo and store is named after the binding it is declared
116
+ as (`createSignal(0, { name: "count", loc: "src/App.tsx:3:29" })`), a binding
117
+ effect runs under the element and attribute it writes (`li.class`,
118
+ `li.children`, `<Show>`), and every component call carries where it is
119
+ written. Positions are relative to `root` and need a `filename`. Defaults to
120
+ `dev`.
121
+ - `diagnostics`: run the source-level checks. Defaults to `dev`; set it in CI to
122
+ run them on a production build.
123
+ - `checks`, `defaultCategory`, `strictCss`: change the level of a code. See
124
+ [docs/README.md](./docs/README.md#changing-a-level-for-the-whole-project).
125
+ - `routes`: the route patterns [BARQ013](./docs/BARQ013.md) checks `<Link to>`
126
+ against. Absent turns the check off.
127
+ - `moduleSource`: where the emitted code imports the renderer from. Defaults
128
+ to `@barqjs/web`.
129
+ - `coreSource`: where the emitted code imports the reactive calls (`props`,
130
+ `cell`, `block`, `bindEffect`, `createComponent`) and the components an
131
+ author imports from. Defaults to `@barqjs/core`.
132
+ - `target`: `"dom"` (the default) or `"universal"`. A universal module creates
133
+ each node with `createElement` or `createTextNode`, places it with
134
+ `insertNode`, and writes every attribute, property and event with one
135
+ `setProp` call under the name the author wrote, all imported from
136
+ `moduleSource`, which is then a module that exports what
137
+ `@barqjs/universal`'s `createRenderer` returned. `bind:` and a form `action`
138
+ are errors there ([BARQ027](./docs/BARQ027.md)), as are `ssr`, `hydratable`
139
+ and `interp` ([BARQ028](./docs/BARQ028.md)).
140
+ - `renderers`: per-file renderer selection, a list of
141
+ `{ include, target, moduleSource }`. A file whose name matches one of an
142
+ entry's `include` globs compiles for that entry's `target` (`"universal"` by
143
+ default) and `moduleSource`, and the first entry that matches wins. A file
144
+ an entry gives to the universal target is compiled without `ssr` and
145
+ `hydratable`, which keep describing the build's document files.
146
+ - `boundaries`: components whose children compile for another renderer than
147
+ the JSX around them, a list of `{ source, name, target, moduleSource }`. An
148
+ element whose tag resolves to the import `name` from `source` (a named
149
+ import, a renamed one, or a member of a namespace import, and never a local
150
+ binding of the same name) compiles for the module's renderer, and its JSX
151
+ children and `children` prop compile for the entry's `target` and
152
+ `moduleSource`. Boundaries nest. The children stay lazy, so the component
153
+ creates them where it reads `props.children`, inside its own renderer's
154
+ root. A module that writes no boundary compiles exactly as it would without
155
+ the option. Under `ssr` the boundary renders and a universal boundary's
156
+ children are left out of the server module; `@barqjs/vite` also reads
157
+ `"barq": { "boundaries": [...] }` from a dependency's `package.json`.
158
+ [DESIGN.md](./DESIGN.md#8-renderer-boundaries-and-claimed-intrinsics) has the emission.
159
+ - `intrinsics`: tags a renderer claims, a list of
160
+ `{ tags, claimUnknown, target, moduleSource }`. Outside every boundary, a
161
+ tree of intrinsic elements whose root tag one entry claims, and the
162
+ document does not have, compiles for that entry's renderer wherever it is
163
+ written, so `function Box() { return <mesh /> }` is a scene object in a page
164
+ file. A tag the document also has (`line`, `audio`, `path`, `source`) is the
165
+ renderer's only when the tree under it holds a tag that renderer alone
166
+ claims, and never under an `<svg>`. With `claimUnknown`, an entry also takes
167
+ any lowercase tag without a hyphen that no entry names and the document does
168
+ not have. A tag with a hyphen is always the document's. JSX written inside a
169
+ claimed tree follows it, and so does a component such as `<Show>` whose JSX
170
+ all went to one renderer. Two entries claiming one tag is
171
+ [BARQ029](./docs/BARQ029.md), and the tree stays the document's.
172
+ - `templates`: `false` emits `element()` calls instead of cloned templates.
173
+ - `optimize`: `0` turns every optimisation off. The output is larger and slower
174
+ and never behaves differently.
175
+
176
+ The rest (`env`, `root`, `serverFns`, the other `*Source` names, `cssExports`,
177
+ `cssImports`, `ownership`, `addresses`, `interp`, `passes`) are set by
178
+ `@barqjs/vite` and documented in `index.d.ts`. An option the compiler does not
179
+ know throws, and the message names the closest one, so `sourceMap` is reported
180
+ as a misspelling of `sourcemap`.
181
+
182
+ The result:
183
+
184
+ - `code`: the compiled module.
185
+ - `map`: the source map, when asked for.
186
+ - `diagnostics`: structured records with `code`, `severity`, `message`, the
187
+ span (`line`, `column`, `endLine`, `endColumn`, `pos`, `end`) and `docs`, a
188
+ link to the page for the code. A finding whose repair is one spelling also
189
+ has `fix`: a list of `{ pos, end, text }` edits over the source, UTF-16
190
+ offsets, which `barq check --fix` from `@barqjs/cli` applies.
191
+ - `warnings`: the same set as `file:line:col: CODE level: message` strings.
192
+ - `labels`, `css` and the side outputs the options above ask for.
193
+
194
+ A syntax error throws instead of returning.
195
+
196
+ The package also exports the pieces `@barqjs/vite` builds on:
197
+
198
+ - `diagnosticCodes()`: every code, with its level, summary and docs URL.
199
+ - `routeTree(root, dir, outFile?, writeIds?)`: scans a routes directory and
200
+ returns the source of `routeTree.gen.ts`, the route patterns and any warnings.
201
+ - `routeSplit(source, filename, specifier, forClient?, splitComponents?)`: splits
202
+ a route module so its components load lazily, and deletes its `server`
203
+ handlers from the client half.
204
+ - `middlewareSplit(source, filename, startSource?)`: the client half of a module
205
+ that declares middleware, with `.server(...)` removed.
206
+ - `orderCss(css, layers?)` and `layerOrder(sheets)`: order the atoms and cascade
207
+ layers of a bundled stylesheet.
208
+
209
+ ### Deeply nested input
210
+
211
+ oxc's parser and code generator recurse without a depth limit. `transform()`
212
+ estimates the nesting depth with a byte scan and compiles a file that could
213
+ overflow the caller's stack on a thread sized for it. A file nested past the
214
+ limit fails with an error that names the depth, instead of crashing the process.
215
+ Ordinary files never leave the calling thread. The per-level stack costs the
216
+ sizing uses are measured and recorded in `src/compile.rs`.
217
+
218
+ ### Bundling
219
+
220
+ The generated `index.js` holds one guarded `require()` per platform napi-rs
221
+ knows. `@barqjs/vite` loads it with `createRequire`, so an application bundle
222
+ never includes it. A tool that bundles code importing this package directly
223
+ should mark it external.
224
+
225
+ ## Building from source
226
+
227
+ A Rust toolchain is required. `@napi-rs/cli` needs Node on `PATH`
228
+ (`^20.17.0 || ^22.13.0 || >= 23.5.0`) even when it is run through Bun.
229
+
230
+ ```sh
231
+ bun run build # napi build --platform --release
232
+ bun run build:debug # napi build --platform, much faster, same file names
233
+ bun test # the differential harness, needs the binding built first
234
+ bun run test # cargo fmt --check, clippy, cargo test, then bun test
235
+ ```
236
+
237
+ `index.js`, `index.d.ts` and `barq-compiler.<triple>.node` are build output and
238
+ are not committed. Until one of the build commands has run, the test harness
239
+ fails with a message saying so, and `@barqjs/vite` throws naming the command.
240
+
241
+ The fixture corpus the harness runs is described in
242
+ [fixtures/README.md](./fixtures/README.md).
@@ -0,0 +1,55 @@
1
+ # BARQ001: An accessor is used as a value without being called
2
+
3
+ **Level:** warning · [all codes](README.md)
4
+
5
+ ## Message
6
+
7
+ > `count` is an accessor, and here the function itself is used as the value. In a string
8
+ > it prints its own source text and in arithmetic it gives `NaN`. Call it: `count()`.
9
+
10
+ ## Failing example
11
+
12
+ ```tsx
13
+ import { createSignal } from "@barqjs/core";
14
+
15
+ const [count] = createSignal(0);
16
+
17
+ export const Total = () => <p>{`total: ${count}`}</p>;
18
+ ```
19
+
20
+ ## Fixed example
21
+
22
+ ```tsx
23
+ import { createSignal } from "@barqjs/core";
24
+
25
+ const [count] = createSignal(0);
26
+
27
+ export const Total = () => <p>{`total: ${count()}`}</p>;
28
+ ```
29
+
30
+ ## Why this rule exists
31
+
32
+ An accessor is a function, and JavaScript turns a function into a string or a number
33
+ without complaint: `` `${count}` `` puts the accessor's source text on the page and
34
+ `count * 2` is `NaN`. Neither throws, and TypeScript accepts the string forms. A prop is
35
+ not an accessor: a component writes `props.count` as the value and the compiler writes the
36
+ read, so a prop inside a string or a calculation is correct and is not reported.
37
+
38
+ Passing the accessor itself to JSX is correct and is not reported: `<p>{count}</p>` and
39
+ `<div id={count}>` both stay up to date.
40
+
41
+ ## Silencing one line
42
+
43
+ ```tsx
44
+ import { createSignal } from "@barqjs/core";
45
+
46
+ const [count] = createSignal(0);
47
+
48
+ // barq-ignore-next-line BARQ001 (the debug panel shows the source text)
49
+ export const source = `${count}`;
50
+ ```
51
+
52
+ The reason in parentheses is required and has to be at least 10 characters. Between JSX
53
+ children, write the comment as `{/* barq-ignore-next-line BARQ001 (reason) */}` on the line
54
+ above: a `//` line there is text and would be rendered on the page. To change the level
55
+ for the whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
@@ -0,0 +1,53 @@
1
+ # BARQ002: An accessor is used as a condition, which is always true
2
+
3
+ **Level:** warning · [all codes](README.md)
4
+
5
+ ## Message
6
+
7
+ > `loading` is an accessor, and a function is always truthy, so this condition is always
8
+ > true and its other branch never runs. Call it: `loading()`.
9
+
10
+ ## Failing example
11
+
12
+ ```tsx
13
+ import { createSignal } from "@barqjs/core";
14
+
15
+ const [loading] = createSignal(true);
16
+
17
+ export const Status = () => <p>{loading ? "Loading" : "Ready"}</p>;
18
+ ```
19
+
20
+ ## Fixed example
21
+
22
+ ```tsx
23
+ import { createSignal } from "@barqjs/core";
24
+
25
+ const [loading] = createSignal(true);
26
+
27
+ export const Status = () => <p>{loading() ? "Loading" : "Ready"}</p>;
28
+ ```
29
+
30
+ ## Why this rule exists
31
+
32
+ A function is always truthy. `if (loading)`, `loading ? a : b`, `loading && x`, `!loading`
33
+ and a loop that tests an accessor therefore never change with the signal: one branch is
34
+ dead from the start, and a `while (loading)` never ends.
35
+
36
+ A prop is not reported here: a component writes `props.label` as the value and the
37
+ compiler writes the read, so `props.label ? a : b` tests what the caller passed.
38
+
39
+ ## Silencing one line
40
+
41
+ ```tsx
42
+ import { createSignal } from "@barqjs/core";
43
+
44
+ const [loading] = createSignal(true);
45
+
46
+ // barq-ignore-next-line BARQ002 (checking that the accessor exists)
47
+ export const present = loading ? "yes" : "no";
48
+ ```
49
+
50
+ The reason in parentheses is required and has to be at least 10 characters. Between JSX
51
+ children, write the comment as `{/* barq-ignore-next-line BARQ002 (reason) */}` on the line
52
+ above: a `//` line there is text and would be rendered on the page. To change the level
53
+ for the whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
@@ -0,0 +1,58 @@
1
+ # BARQ003: A property is read from an accessor instead of from its value
2
+
3
+ **Level:** warning · [all codes](README.md)
4
+
5
+ ## Message
6
+
7
+ > `user` is an accessor, so `.email` is read from the function and not from the value it
8
+ > returns, and the result is `undefined`. Call it first: `user().email`.
9
+
10
+ ## Failing example
11
+
12
+ ```tsx
13
+ import { createSignal } from "@barqjs/core";
14
+
15
+ const [user] = createSignal({ email: "salama@example.com" });
16
+
17
+ export const Email = () => <p>{user.email}</p>;
18
+ ```
19
+
20
+ ## Fixed example
21
+
22
+ ```tsx
23
+ import { createSignal } from "@barqjs/core";
24
+
25
+ const [user] = createSignal({ email: "salama@example.com" });
26
+
27
+ export const Email = () => <p>{user().email}</p>;
28
+ ```
29
+
30
+ ## Why this rule exists
31
+
32
+ The value is behind the call, so `user.email` asks the function for a property it does
33
+ not have and the page shows nothing. Habits from other libraries land here too: an
34
+ accessor has no `.value`, `.set` or `.peek`, and writing goes through the setter that
35
+ `createSignal` returns beside it. A prop is different: a component writes it as the value
36
+ and the compiler writes the read, so `props.user.email` is correct and is not reported.
37
+
38
+ `items.length` is reported too, with its own message. Every function has a `length`, so it
39
+ never comes back `undefined`: it is the accessor's parameter count, `0`, and a list that
40
+ shows `0` items has nothing else wrong with it. Write `items().length`. `user.name` is not
41
+ reported, because a function's own `name` is sometimes read on purpose; write
42
+ `user().name` for the value's.
43
+
44
+ ## Silencing one line
45
+
46
+ ```tsx
47
+ import { createSignal } from "@barqjs/core";
48
+
49
+ const [user] = createSignal({ email: "salama@example.com" });
50
+
51
+ // barq-ignore-next-line BARQ003 (reading a label attached to the function)
52
+ export const label = user.label;
53
+ ```
54
+
55
+ The reason in parentheses is required and has to be at least 10 characters. Between JSX
56
+ children, write the comment as `{/* barq-ignore-next-line BARQ003 (reason) */}` on the line
57
+ above: a `//` line there is text and would be rendered on the page. To change the level
58
+ for the whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
@@ -0,0 +1,116 @@
1
+ # BARQ004: A `<For>` row reads a field once, which goes stale if `each` holds store objects
2
+
3
+ **Level:** note · [all codes](README.md)
4
+
5
+ ## Message
6
+
7
+ > `<For>` reads a field of this row once, when the row is built, and the compiler cannot
8
+ > tell where the items in `each` come from. If they are store objects, changing that field
9
+ > in place leaves the row showing the old value. Read the field where it is shown, as
10
+ > `{row.name}` in the row callback's JSX, or key the list and read the row by calling it:
11
+ > `keyed={(row) => row.id}` with `row().name`.
12
+
13
+ ## Failing example
14
+
15
+ ```tsx
16
+ import { For, createStore } from "@barqjs/core";
17
+
18
+ const [state] = createStore({ rows: [{ id: 1, name: "salama" }] });
19
+
20
+ export const List = () => (
21
+ <ul>
22
+ <For each={state.rows}>{({ name }) => <li>{name}</li>}</For>
23
+ </ul>
24
+ );
25
+ ```
26
+
27
+ ```tsx
28
+ import { For, createStore } from "@barqjs/core";
29
+
30
+ const [state] = createStore({ rows: [{ id: 1, name: "salama" }] });
31
+
32
+ export const List = () => (
33
+ <ul>
34
+ <For each={state.rows}>
35
+ {(row) => {
36
+ const label = row.name.toUpperCase();
37
+ return <li>{label}</li>;
38
+ }}
39
+ </For>
40
+ </ul>
41
+ );
42
+ ```
43
+
44
+ ## Fixed example
45
+
46
+ ```tsx
47
+ import { For, createStore } from "@barqjs/core";
48
+
49
+ const [state] = createStore({ rows: [{ id: 1, name: "salama" }] });
50
+
51
+ export const List = () => (
52
+ <ul>
53
+ <For each={state.rows}>{(row) => <li>{row.name}</li>}</For>
54
+ </ul>
55
+ );
56
+ ```
57
+
58
+ ```tsx
59
+ import { For, createStore } from "@barqjs/core";
60
+
61
+ const [state] = createStore({ rows: [{ id: 1, name: "salama" }] });
62
+
63
+ export const List = () => (
64
+ <ul>
65
+ <For each={state.rows} keyed={(row) => row.id}>
66
+ {(row) => <li>{row().name}</li>}
67
+ </For>
68
+ </ul>
69
+ );
70
+ ```
71
+
72
+ ## Why this rule exists
73
+
74
+ Without `keyed`, a row is identified by the item itself and receives it as a plain value.
75
+ A store changes fields in place: the item stays the same object, so the row is kept rather
76
+ than built again. What the row shows is then up to where each field is read.
77
+
78
+ A field read in a hole of the row callback, a child like `{row.name}`, an attribute like
79
+ `title={row.name}`, or a component prop, is compiled as a read that runs again when the
80
+ field changes, so that row follows the store and nothing is reported. That holds for a
81
+ callback written inline and for one passed by name, `{renderRow}`, alike. A field read
82
+ anywhere the row reads it only while it is built is reported:
83
+
84
+ - a destructured parameter, `({ name }) => …`, or `const { name } = row`;
85
+ - a read outside the JSX, `const name = row.name`, or a row handed to a function there;
86
+ - a read that picks the JSX, `row.done ? <s/> : <li/>`, or the tag, `<row.Icon />`;
87
+ - a callback the module does not show, such as an import, whose reads cannot be seen.
88
+
89
+ Handlers, `ref`, `bind:` and a form's `action` are handed over once whatever their
90
+ source, a signal's included, so a row field read there is not reported.
91
+
92
+ The note needs both halves: a callback that reads a field once, and rows the compiler
93
+ cannot prove are plain values. Rows written as an array literal are plain, and a `<For>`
94
+ over them is not reported. With `keyed={(row) => row.id}` or `keyed={false}` the row
95
+ receives an accessor, `row().name` is read again when the field changes, and nothing is
96
+ reported.
97
+
98
+ ## Silencing one line
99
+
100
+ ```tsx
101
+ import { For, createStore } from "@barqjs/core";
102
+
103
+ const [state] = createStore({ rows: [{ id: 1, name: "salama" }] });
104
+
105
+ export const List = () => (
106
+ <ul>
107
+ {/* barq-ignore-next-line BARQ004 (rows are replaced, never changed in place) */}
108
+ <For each={state.rows}>{({ name }) => <li>{name}</li>}</For>
109
+ </ul>
110
+ );
111
+ ```
112
+
113
+ The reason in parentheses is required and has to be at least 10 characters. Between JSX
114
+ children, write the comment as `{/* barq-ignore-next-line BARQ004 (reason) */}` on the line
115
+ above: a `//` line there is text and would be rendered on the page. To change the level
116
+ for the whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
@@ -0,0 +1,25 @@
1
+ # BARQ005: removed
2
+
3
+ The compiler does not report this code. [All codes](README.md)
4
+
5
+ BARQ005 warned that a name destructured from a component's props was the prop's Cell, a
6
+ function, and was being used as a value. Destructuring props is supported now: the compiler
7
+ makes each use of a destructured name the read it stands for, so the name is the value its
8
+ type says it is, it follows the prop, and a default applies whenever the prop is
9
+ `undefined`. There is nothing to warn about:
10
+
11
+ ```tsx
12
+ export function Chip({ text, tone = "warm" }: { text: string; tone?: string }) {
13
+ return <span data-tone={tone}>{`#${text}`}</span>;
14
+ }
15
+ ```
16
+
17
+ Two errors cover what destructuring cannot do. [BARQ030](BARQ030.md) reports an assignment
18
+ to a prop, a destructured name included. [BARQ031](BARQ031.md) reports a pattern that
19
+ cannot be kept reactive: a computed key, a default inside a nested pattern, or a rest
20
+ element inside one.
21
+
22
+ ## If a comment still names it
23
+
24
+ `BARQ005` is not a code the compiler knows, so a comment that names it is reported as
25
+ [BARQ009](BARQ009.md) and silences nothing. Delete the comment.
@@ -0,0 +1,23 @@
1
+ # BARQ006: removed
2
+
3
+ The compiler does not report this code. [All codes](README.md)
4
+
5
+ BARQ006 warned that `<Dynamic>` read every prop once and handed the component it rendered
6
+ values that never updated. barq no longer exports `<Dynamic>` (see [BARQ025](BARQ025.md)).
7
+ The component the `dynamic` factory returns passes each prop through as the same Cell it
8
+ received, so what it renders reads current values and there is nothing to warn about:
9
+
10
+ ```tsx
11
+ import { createSignal } from "@barqjs/core";
12
+ import { dynamic } from "@barqjs/web";
13
+
14
+ const [total] = createSignal(0);
15
+ const Output = dynamic(() => "output");
16
+
17
+ export const Total = () => <Output value={total()} />;
18
+ ```
19
+
20
+ ## If a comment still names it
21
+
22
+ `BARQ006` is not a code the compiler knows, so a comment that names it is reported as
23
+ [BARQ009](BARQ009.md) and silences nothing. Delete the comment.
@@ -0,0 +1,43 @@
1
+ # BARQ008: A `barq-ignore-next-line` comment silences nothing on the next line
2
+
3
+ **Level:** warning · [all codes](README.md)
4
+
5
+ ## Message
6
+
7
+ > This `barq-ignore-next-line` names BARQ001, and nothing on the line below reports it,
8
+ > so the comment does nothing. Delete it, or move it to the line directly above the
9
+ > diagnostic; inside JSX, write it as `{/* barq-ignore-next-line ... */}`.
10
+
11
+ ## Failing example
12
+
13
+ ```tsx
14
+ // barq-ignore-next-line BARQ001 (the debug panel shows the source text)
15
+ export const Label = () => <p>ok</p>;
16
+ ```
17
+
18
+ ## Fixed example
19
+
20
+ ```tsx
21
+ export const Label = () => <p>ok</p>;
22
+ ```
23
+
24
+ ## Why this rule exists
25
+
26
+ A suppression that silences nothing is a leftover: the code it covered was fixed or moved.
27
+ Left in place, it would hide the next diagnostic with that code on that line without
28
+ anyone deciding that it should.
29
+
30
+ Two things produce this by accident. A comment covers the next line only, not the whole
31
+ statement, so it has to sit directly above the line the diagnostic points at. And between
32
+ JSX children a `//` line is text, so the comment has to be written as
33
+ `{/* barq-ignore-next-line BARQ001 (reason) */}`.
34
+
35
+ ## Turning it off
36
+
37
+ This code has no per-line form, because a suppression of a suppression would need its own
38
+ check. It stays a warning even with `defaultCategory: "error"`, so a stale comment cannot
39
+ fail a build. To stop reporting it for the whole project:
40
+
41
+ ```ts
42
+ barq({ compiler: { checks: { BARQ008: "suppress" } } });
43
+ ```