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

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.
@@ -0,0 +1,68 @@
1
+ # BARQ026: Markup the browser's HTML parser builds differently from the JSX
2
+
3
+ **Level:** error · [all codes](README.md)
4
+
5
+ ## Message
6
+
7
+ > `<div>` cannot be inside a `<p>`: the browser's HTML parser closes the paragraph at
8
+ > `<div>`, so the `<div>` lands after the `<p>` and the `</p>` that follows opens an empty
9
+ > one. A server-rendered page then hydrates against a tree that is not the one this JSX
10
+ > builds, which is a hydration mismatch and a full re-render in the browser. Move the `<div>`
11
+ > out of the `<p>`, or change the outer element (a `<div>` in place of a `<p>`, a `<span>` in
12
+ > place of an inner link).
13
+
14
+ The first sentence names what the parser does at that element. The other shapes it reports:
15
+
16
+ - a table part outside its parent, or anything but its parts inside a table: `<tr>`
17
+ directly in a `<table>` (the parser adds a `<tbody>`), `<td>` in a `<div>` (the parser
18
+ drops the tag), `<div>` in a `<tr>` (the parser moves it before the table).
19
+ - an element `<select>`, `<optgroup>` or `<option>` does not take.
20
+ - a second `<a>`, `<button>`, `<form>`, `<li>`, `<nobr>`, `<dd>` or `<dt>` inside an open one,
21
+ which the parser closes first.
22
+ - `<html>`, `<head>`, `<body>` and the obsolete `<frame>`, `<frameset>`, `<plaintext>`, which
23
+ are never an element of their own inside a page.
24
+
25
+ ## Failing example
26
+
27
+ ```tsx
28
+ export const Notice = (props) => (
29
+ <p>
30
+ Your order shipped.
31
+ <div class="details">{props.tracking}</div>
32
+ </p>
33
+ );
34
+ ```
35
+
36
+ ## Fixed example
37
+
38
+ ```tsx
39
+ export const Notice = (props) => (
40
+ <div>
41
+ <p>Your order shipped.</p>
42
+ <div class="details">{props.tracking}</div>
43
+ </div>
44
+ );
45
+ ```
46
+
47
+ ## Why this rule exists
48
+
49
+ A server render writes the markup as a string, and the browser parses that string with the
50
+ HTML parser, which repairs what HTML does not allow instead of keeping it. The page the
51
+ browser builds from `<p><div>…</div></p>` is `<p></p><div>…</div><p></p>`. Hydration then
52
+ walks a tree that is not the one the component builds, reports a mismatch, throws the
53
+ server's markup away and renders the page again. A client-only render does not show it,
54
+ because it builds elements one by one and never asks the parser.
55
+
56
+ The check follows JSX within one component: an element's children, and JSX that a
57
+ conditional, a `&&` or a list callback places where it stands. A component's children start
58
+ again, because the component decides where they go.
59
+
60
+ ## Silencing one line
61
+
62
+ ```tsx
63
+ // barq-ignore-next-line BARQ026 (rendered on the client only, never hydrated)
64
+ export const Legacy = () => <p><div>kept for an old stylesheet</div></p>;
65
+ ```
66
+
67
+ The reason in parentheses is required and has to be at least 10 characters. To change the
68
+ level for the whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
@@ -0,0 +1,53 @@
1
+ # BARQ027: A `bind:` or a form `action` is written for a custom renderer
2
+
3
+ **Level:** error · [all codes](README.md)
4
+
5
+ ## Message
6
+
7
+ > `bind:` is a two-way binding to a document form control, and this element is built by a
8
+ > custom renderer, which has none. Pass the value as a prop and write it back from the
9
+ > host's own event: `value={text()}` with `onChange={(next) => setText(next)}`.
10
+
11
+ For `action` on a `<form>`, the message says that the action is a document form's submit
12
+ handler or URL and suggests calling it from the host's own event, such as
13
+ `onSubmit={() => save()}`.
14
+
15
+ ## Failing example
16
+
17
+ ```tsx
18
+ // compiled with target: "universal"
19
+ export const Field = (props) => <input bind:value={props.text} />;
20
+ ```
21
+
22
+ ## Fixed example
23
+
24
+ ```tsx
25
+ // compiled with target: "universal"
26
+ export const Field = (props) => (
27
+ <input value={props.text()} onChange={(next: string) => props.setText(next)} />
28
+ );
29
+ ```
30
+
31
+ ## Why this rule exists
32
+
33
+ An element a custom renderer builds (in a module compiled with `target: "universal"`, a
34
+ file a `renderers` entry gives to one, or the children of a `boundaries` component whose
35
+ target is `universal`) has every attribute and event written as one `setProp` call on the
36
+ host's node, and the host decides what a name means. `bind:` needs two facts only a document form
37
+ control has: the property a user edits (`value`, `checked`, `valueAsNumber`) and the event
38
+ that reports the edit (`input`, `change`). A form `action` is the document's submit,
39
+ which a scene graph or a terminal does not have. Neither has a meaning the compiler could
40
+ write for an arbitrary host, so the module would build an element that silently never
41
+ updates, and the build fails instead. A literal `action="/save"` is an ordinary property
42
+ and is not reported.
43
+
44
+ ## Silencing one line
45
+
46
+ ```tsx
47
+ // barq-ignore-next-line BARQ027 (the host reads this name itself in a later version)
48
+ export const Field = (props) => <input bind:value={props.text} />;
49
+ ```
50
+
51
+ The reason in parentheses is required and has to be at least 10 characters. Silencing the
52
+ code does not make the binding work: nothing is emitted for it. To change the level for the
53
+ whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
@@ -0,0 +1,56 @@
1
+ # BARQ028: A module compiled for a custom renderer is also asked for `ssr`, `hydratable` or `interp`
2
+
3
+ **Level:** error · [all codes](README.md)
4
+
5
+ ## Message
6
+
7
+ > `ssr: true` was asked for together with `target: "universal"`, and the string backend
8
+ > renders the document's markup, which a custom host does not have. It was turned off for
9
+ > this module. Remove it from this module's options, or give the files of the custom
10
+ > renderer their own entry in `renderers`, which leaves `ssr` to the rest of the build.
11
+
12
+ The same message names `hydratable` (hydration claims the document's server markup) or
13
+ `interp` (the reference backend walks the document).
14
+
15
+ ## Failing example
16
+
17
+ ```tsx
18
+ // compiled with { target: "universal", ssr: true }
19
+ export const Scene = (props) => <box>{props.label()}</box>;
20
+ ```
21
+
22
+ ## Fixed example
23
+
24
+ ```tsx
25
+ // compiled with { target: "universal" }
26
+ export const Scene = (props) => <box>{props.label()}</box>;
27
+ ```
28
+
29
+ ## Why this rule exists
30
+
31
+ `ssr`, `hydratable` and `interp` each choose how a module reaches the document: as a string
32
+ of markup, as a client that claims that markup, or through the reference backend's walk. A
33
+ module compiled for a custom renderer reaches its own host instead, so asking for both is a
34
+ configuration that cannot mean anything. The compiler turns the document option off and
35
+ fails the build, so the mistake is seen rather than compiled into a bundle that ignores
36
+ half of what it was told.
37
+
38
+ An app that renders the document on the server and a custom host in the browser keeps
39
+ `ssr` and `hydratable` for its document files and gives the others a `renderers` entry,
40
+ which is not reported: the build's document options describe its document files, and the
41
+ files an entry gives to a custom renderer are not among them.
42
+
43
+ ```ts
44
+ barq({
45
+ ssr: true,
46
+ compiler: {
47
+ renderers: [{ include: ["src/scene/**"], target: "universal", moduleSource: "/src/renderer.ts" }],
48
+ },
49
+ });
50
+ ```
51
+
52
+ ## Turning it off
53
+
54
+ This code is about the options a module is compiled with rather than a line of it, so there
55
+ is no line to silence. To change the level for the whole project, see
56
+ [the index](README.md#changing-a-level-for-the-whole-project).
@@ -0,0 +1,57 @@
1
+ # BARQ029: Two renderers claim the same intrinsic tag
2
+
3
+ **Level:** warning · [all codes](README.md)
4
+
5
+ ## Message
6
+
7
+ > `<mesh>` is claimed by two renderers, `@acme/scene/renderer` and `@acme/other/renderer`, so
8
+ > it compiles for the document. Claim it in your own `intrinsics` configuration, which wins over
9
+ > what a package declares.
10
+
11
+ For a tag that no entry names and the document does not have, the message says that two
12
+ renderers claim every such tag (both declare `claimUnknown: true`).
13
+
14
+ ## Failing example
15
+
16
+ ```tsx
17
+ // two installed packages both list "mesh" under barq.intrinsics
18
+ export const Box = () => <mesh />;
19
+ ```
20
+
21
+ ## Fixed example
22
+
23
+ ```tsx
24
+ // the application's own intrinsics entry gives "mesh" to one of them
25
+ export const Box = () => <mesh />;
26
+ ```
27
+
28
+ ## Why this rule exists
29
+
30
+ A tree of intrinsic elements written outside every boundary builds through the renderer that
31
+ claims its root tag, so `function Box() { return <mesh /> }` is a scene object wherever it is
32
+ declared. When two renderers claim the tag, nothing in the source says which one the author
33
+ meant, and picking either would build the tree on a host the author may not render it into.
34
+ The tree compiles for the document instead, as it would with no renderer installed, and the
35
+ warning names both claimants.
36
+
37
+ An `intrinsics` entry in the application's own configuration takes the tag from every package
38
+ that declares it:
39
+
40
+ ```ts
41
+ barq({
42
+ compiler: {
43
+ intrinsics: [{ tags: ["mesh"], target: "universal", moduleSource: "@acme/scene/renderer" }],
44
+ },
45
+ });
46
+ ```
47
+
48
+ ## Silencing one line
49
+
50
+ ```tsx
51
+ // barq-ignore-next-line BARQ029 (this tree is only rendered in the document)
52
+ export const Box = () => <mesh />;
53
+ ```
54
+
55
+ The reason in parentheses is required and has to be at least 10 characters. Silencing the code
56
+ does not choose a renderer: the tree still compiles for the document. To change the level for
57
+ the whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
package/docs/README.md ADDED
@@ -0,0 +1,129 @@
1
+ # barq compiler diagnostics
2
+
3
+ Every diagnostic the compiler reports has a stable code, a level and a page here. Each
4
+ page shows the message, an example that raises it, the fixed example, why the rule
5
+ exists and how to silence it.
6
+
7
+ - [BARQ001](BARQ001.md), warning: An accessor is used as a value without being called.
8
+ - [BARQ002](BARQ002.md), warning: An accessor is used as a condition, which is always true.
9
+ - [BARQ003](BARQ003.md), warning: A property is read from an accessor instead of from its value.
10
+ - [BARQ004](BARQ004.md), note: A `<For>` row reads a field once, which goes stale if `each` holds store objects.
11
+ - [BARQ005](BARQ005.md), warning: A destructured prop is used as a value, or called where it may not be a function.
12
+ - [BARQ008](BARQ008.md), warning: A `barq-ignore-next-line` comment silences nothing on the next line.
13
+ - [BARQ009](BARQ009.md), warning: A `barq-ignore-next-line` comment is malformed and silences nothing.
14
+ - [BARQ010](BARQ010.md), warning: JSX is passed to a prop the component reads as a value, which throws.
15
+ - [BARQ011](BARQ011.md), note: `keyed={false}` keeps element state in place when the list reorders.
16
+ - [BARQ012](BARQ012.md), error: A module exports server functions together with other things.
17
+ - [BARQ013](BARQ013.md), warning: `<Link to>` names a path that no route matches.
18
+ - [BARQ014](BARQ014.md), error: A `css`, `keyframes` or `globalCss` block is not valid CSS.
19
+ - [BARQ015](BARQ015.md), note: A `css` block interpolates a runtime value, so the browser builds it.
20
+ - [BARQ016](BARQ016.md), note: `atoms` has several conditional arguments, so the browser evaluates it.
21
+ - [BARQ017](BARQ017.md), note: A `@barqjs/css` call cannot be compiled, so the browser evaluates it.
22
+ - [BARQ018](BARQ018.md), warning: A component decides what to return from a reactive value it reads once.
23
+ - [BARQ019](BARQ019.md), warning: State is written while a component body or a computation runs.
24
+ - [BARQ020](BARQ020.md), warning: A store is destructured in a component body, so each name is a snapshot.
25
+ - [BARQ021](BARQ021.md), warning: An async computation reads a source after its first `await`, which is not tracked.
26
+ - [BARQ022](BARQ022.md), error: A context is rendered through `.Provider`, which a context does not have.
27
+ - [BARQ023](BARQ023.md), error: `classList` is written on an element, where it is an ordinary attribute.
28
+ - [BARQ024](BARQ024.md), error: An attribute uses a Solid 1.x namespace such as `on:` or `attr:`.
29
+ - [BARQ025](BARQ025.md), error: `<Dynamic>` is rendered, where Solid 2.0 uses the `dynamic` factory.
30
+ - [BARQ026](BARQ026.md), error: Markup the browser's HTML parser builds differently from the JSX.
31
+ - [BARQ027](BARQ027.md), error: A `bind:` or a form `action` is written for a custom renderer.
32
+ - [BARQ028](BARQ028.md), error: A module compiled for a custom renderer is also asked for `ssr`, `hydratable` or `interp`.
33
+ - [BARQ029](BARQ029.md), warning: Two renderers claim the same intrinsic tag.
34
+
35
+ When each code is reported:
36
+
37
+ - BARQ001, BARQ002, BARQ003, BARQ005, BARQ011 and BARQ018 to BARQ021: when the
38
+ `diagnostics` option is on. It defaults to on in development builds, and
39
+ `barq({ compiler: { diagnostics: true } })` runs them in a production build.
40
+ - BARQ004 and BARQ010: in development builds only.
41
+ - BARQ012 to BARQ017 and BARQ022 to BARQ029: in every build, so they can fail CI.
42
+ BARQ013 also needs the route table, which file-based routing provides.
43
+ - BARQ008 and BARQ009: in every build, about your own suppression comments.
44
+
45
+ [BARQ006](BARQ006.md) and BARQ007 were removed and are not reported. BARQ006 has a page
46
+ because a suppression comment may still name it. BARQ007 announced a fallback from the
47
+ server renderer to the DOM renderer, and there is no such fallback any more. A comment
48
+ that names either code is reported as [BARQ009](BARQ009.md).
49
+
50
+ ## Codes are stable
51
+
52
+ A code is never renamed and never reused, because a suppression comment in your source
53
+ refers to it by name. A new code arrives in a minor release at warning level or below,
54
+ except one that reports a spelling the runtime no longer understands, as BARQ022 to
55
+ BARQ025 do: that code would otherwise be a page that builds and then misbehaves.
56
+ With `defaultCategory: "error"`, a new code can therefore turn a minor upgrade into a
57
+ failing build.
58
+
59
+ ## Silencing one line
60
+
61
+ In statement position, write a line comment directly above the reported line:
62
+
63
+ ```ts
64
+ // barq-ignore-next-line BARQ001 (the debug panel shows the source text)
65
+ const label = `${count}`;
66
+ ```
67
+
68
+ Between JSX children, write a JSX comment. A `//` line there is text: it silences
69
+ nothing and it is rendered on the page.
70
+
71
+ ```tsx
72
+ <div>
73
+ {/* barq-ignore-next-line BARQ001 (the debug panel shows the source text) */}
74
+ <pre>{`${count}`}</pre>
75
+ </div>
76
+ ```
77
+
78
+ - The code is required. A comment without one would also hide a diagnostic added to that
79
+ line later.
80
+ - Several codes can be listed, separated by commas or spaces: `BARQ001, BARQ003`.
81
+ - A reason in parentheses is required and has to be at least 10 characters.
82
+ - The comment covers the next line that is not blank and not a comment, so two comments
83
+ stacked above one line both apply to it. It covers one line, not one statement: a
84
+ diagnostic on the third line of a long statement needs the comment directly above that
85
+ line.
86
+ - A comment that silences nothing is reported as [BARQ008](BARQ008.md), and a comment
87
+ that cannot be read as [BARQ009](BARQ009.md). Both stay warnings whatever the project
88
+ settings say, so a comment cannot fail a build.
89
+ - A comment never changes the code the compiler produces.
90
+
91
+ ## Changing a level for the whole project
92
+
93
+ ```ts
94
+ barq({
95
+ compiler: {
96
+ checks: { BARQ004: "suppress", BARQ001: "error" },
97
+ defaultCategory: "warning",
98
+ },
99
+ });
100
+ ```
101
+
102
+ A level is `suppress`, `note`, `warning` or `error`. An entry in `checks` wins over
103
+ `strictCss`, which makes BARQ014 to BARQ017 errors; that wins over `defaultCategory`,
104
+ which applies to every code; and that wins over the code's own level. The compiler and
105
+ the Vite plugin read the same settings, so a code silenced here is silent everywhere.
106
+
107
+ The compiler prints each fix as text and never rewrites your source.
108
+
109
+ ## What the rules cannot see
110
+
111
+ The checks report only what they can prove from one file, so silence is not a guarantee.
112
+
113
+ - **Other files.** An accessor imported from another module is not known to be one, so
114
+ BARQ001 to BARQ003 say nothing about it, and BARQ010 does not follow a prop into a
115
+ component declared in another file.
116
+ - **Files without JSX.** The accessor and props rules run on `.jsx` and `.tsx` files.
117
+ - **A reassigned name.** A `let` that is assigned again is not treated as an
118
+ accessor.
119
+ - **A component only ever passed as a value.** BARQ005 needs to know that a function is
120
+ a component, which it learns from a JSX tag, an export, or a route option such as
121
+ `component`. A function that is only passed to another function is not reported.
122
+ - **A prop's value.** Every prop is a function you call, whether or not the caller passes
123
+ anything that changes, so BARQ018 counts a prop only where the same file renders the
124
+ component with a value that changes.
125
+ - **A helper function.** BARQ019 sees a write written in the component body or in the
126
+ computation itself, not one inside a function the body calls.
127
+ - **A row whose `keyed` is not written out.** With `<For keyed={KEYED}>` or
128
+ `<For {...options}>` the compiler does not know whether the row is an accessor, so
129
+ BARQ001 to BARQ003 say nothing about that row.