@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 +21 -0
- package/README.md +241 -2
- package/docs/BARQ001.md +55 -0
- package/docs/BARQ002.md +53 -0
- package/docs/BARQ003.md +58 -0
- package/docs/BARQ004.md +116 -0
- package/docs/BARQ005.md +25 -0
- package/docs/BARQ006.md +23 -0
- package/docs/BARQ008.md +43 -0
- package/docs/BARQ009.md +48 -0
- package/docs/BARQ010.md +76 -0
- package/docs/BARQ011.md +88 -0
- package/docs/BARQ012.md +81 -0
- package/docs/BARQ013.md +63 -0
- package/docs/BARQ014.md +61 -0
- package/docs/BARQ015.md +64 -0
- package/docs/BARQ016.md +52 -0
- package/docs/BARQ017.md +63 -0
- package/docs/BARQ018.md +116 -0
- package/docs/BARQ019.md +109 -0
- package/docs/BARQ020.md +78 -0
- package/docs/BARQ021.md +79 -0
- package/docs/BARQ022.md +57 -0
- package/docs/BARQ023.md +55 -0
- package/docs/BARQ024.md +58 -0
- package/docs/BARQ025.md +74 -0
- package/docs/BARQ026.md +68 -0
- package/docs/BARQ027.md +53 -0
- package/docs/BARQ028.md +56 -0
- package/docs/BARQ029.md +57 -0
- package/docs/BARQ030.md +65 -0
- package/docs/BARQ031.md +61 -0
- package/docs/BARQ032.md +68 -0
- package/docs/BARQ033.md +81 -0
- package/docs/BARQ034.md +55 -0
- package/docs/README.md +137 -0
- package/index.d.ts +604 -0
- package/index.js +90 -0
- package/package.json +87 -4
- package/skills/compiler-diagnostics/SKILL.md +890 -0
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
|
-
#
|
|
1
|
+
# @barqjs/compiler
|
|
2
2
|
|
|
3
|
-
|
|
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).
|
package/docs/BARQ001.md
ADDED
|
@@ -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).
|
package/docs/BARQ002.md
ADDED
|
@@ -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).
|
package/docs/BARQ003.md
ADDED
|
@@ -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).
|
package/docs/BARQ004.md
ADDED
|
@@ -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).
|
package/docs/BARQ005.md
ADDED
|
@@ -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.
|
package/docs/BARQ006.md
ADDED
|
@@ -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.
|
package/docs/BARQ008.md
ADDED
|
@@ -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
|
+
```
|