@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/docs/README.md
ADDED
|
@@ -0,0 +1,137 @@
|
|
|
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
|
+
- [BARQ008](BARQ008.md), warning: A `barq-ignore-next-line` comment silences nothing on the next line.
|
|
12
|
+
- [BARQ009](BARQ009.md), warning: A `barq-ignore-next-line` comment is malformed and silences nothing.
|
|
13
|
+
- [BARQ010](BARQ010.md), warning: JSX is passed to a prop the component reads as a value, which throws.
|
|
14
|
+
- [BARQ011](BARQ011.md), note: `keyed={false}` keeps element state in place when the list reorders.
|
|
15
|
+
- [BARQ012](BARQ012.md), error: A module exports server functions together with other things.
|
|
16
|
+
- [BARQ013](BARQ013.md), warning: `<Link to>` names a path that no route matches.
|
|
17
|
+
- [BARQ014](BARQ014.md), error: A `css`, `keyframes` or `globalCss` block is not valid CSS.
|
|
18
|
+
- [BARQ015](BARQ015.md), note: A `css` block interpolates a runtime value, so the browser builds it.
|
|
19
|
+
- [BARQ016](BARQ016.md), note: `atoms` has several conditional arguments, so the browser evaluates it.
|
|
20
|
+
- [BARQ017](BARQ017.md), note: A `@barqjs/css` call cannot be compiled, so the browser evaluates it.
|
|
21
|
+
- [BARQ018](BARQ018.md), warning: A component decides what to return from a reactive value it reads once.
|
|
22
|
+
- [BARQ019](BARQ019.md), warning: State is written while a component body or a computation runs.
|
|
23
|
+
- [BARQ020](BARQ020.md), warning: A store is destructured in a component body, so each name is a snapshot.
|
|
24
|
+
- [BARQ021](BARQ021.md), warning: An async computation reads a source after its first `await`, which is not tracked.
|
|
25
|
+
- [BARQ022](BARQ022.md), error: A context is rendered through `.Provider`, which a context does not have.
|
|
26
|
+
- [BARQ023](BARQ023.md), error: `classList` is written on an element, where it is an ordinary attribute.
|
|
27
|
+
- [BARQ024](BARQ024.md), error: An attribute uses a Solid 1.x namespace such as `on:` or `attr:`.
|
|
28
|
+
- [BARQ025](BARQ025.md), error: `<Dynamic>` is rendered, where Solid 2.0 uses the `dynamic` factory.
|
|
29
|
+
- [BARQ026](BARQ026.md), error: Markup the browser's HTML parser builds differently from the JSX.
|
|
30
|
+
- [BARQ027](BARQ027.md), error: A `bind:` or a form `action` is written for a custom renderer.
|
|
31
|
+
- [BARQ028](BARQ028.md), error: A module compiled for a custom renderer is also asked for `ssr`, `hydratable` or `interp`.
|
|
32
|
+
- [BARQ029](BARQ029.md), warning: Two renderers claim the same intrinsic tag.
|
|
33
|
+
- [BARQ030](BARQ030.md), error: A prop is assigned, and props are read-only.
|
|
34
|
+
- [BARQ031](BARQ031.md), error: A props pattern binds a name that cannot be kept reactive.
|
|
35
|
+
- [BARQ032](BARQ032.md), warning: A shorthand that cannot be split is merged with one of its longhands.
|
|
36
|
+
- [BARQ033](BARQ033.md), note: Two conditions on one property are written in the order the stylesheet reverses.
|
|
37
|
+
- [BARQ034](BARQ034.md), error: A tag names a prop whose default is a string, which is not a component.
|
|
38
|
+
|
|
39
|
+
When each code is reported:
|
|
40
|
+
|
|
41
|
+
- BARQ001, BARQ002, BARQ003, BARQ011 and BARQ018 to BARQ021: when the
|
|
42
|
+
`diagnostics` option is on. It defaults to on in development builds, and
|
|
43
|
+
`barq({ compiler: { diagnostics: true } })` runs them in a production build.
|
|
44
|
+
- BARQ004 and BARQ010: in development builds only.
|
|
45
|
+
- BARQ012 to BARQ017 and BARQ022 to BARQ034: in every build, so they can fail CI.
|
|
46
|
+
BARQ013 also needs the route table, which file-based routing provides.
|
|
47
|
+
- BARQ008 and BARQ009: in every build, about your own suppression comments.
|
|
48
|
+
|
|
49
|
+
[BARQ005](BARQ005.md), [BARQ006](BARQ006.md) and BARQ007 were removed and are not
|
|
50
|
+
reported. BARQ005 and BARQ006 have a page because a suppression comment may still name
|
|
51
|
+
them. BARQ005 warned about a destructured prop used as a value, which is correct code now
|
|
52
|
+
that destructuring props is supported. BARQ007 announced a fallback from the server
|
|
53
|
+
renderer to the DOM renderer, and there is no such fallback any more. A comment that names
|
|
54
|
+
any of the three is reported as [BARQ009](BARQ009.md).
|
|
55
|
+
|
|
56
|
+
## Codes are stable
|
|
57
|
+
|
|
58
|
+
A code is never renamed and never reused, because a suppression comment in your source
|
|
59
|
+
refers to it by name. A new code arrives in a minor release at warning level or below,
|
|
60
|
+
except one that reports a spelling the runtime no longer understands, as BARQ022 to
|
|
61
|
+
BARQ025 do: that code would otherwise be a page that builds and then misbehaves.
|
|
62
|
+
With `defaultCategory: "error"`, a new code can therefore turn a minor upgrade into a
|
|
63
|
+
failing build.
|
|
64
|
+
|
|
65
|
+
## Silencing one line
|
|
66
|
+
|
|
67
|
+
In statement position, write a line comment directly above the reported line:
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
// barq-ignore-next-line BARQ001 (the debug panel shows the source text)
|
|
71
|
+
const label = `${count}`;
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Between JSX children, write a JSX comment. A `//` line there is text: it silences
|
|
75
|
+
nothing and it is rendered on the page.
|
|
76
|
+
|
|
77
|
+
```tsx
|
|
78
|
+
<div>
|
|
79
|
+
{/* barq-ignore-next-line BARQ001 (the debug panel shows the source text) */}
|
|
80
|
+
<pre>{`${count}`}</pre>
|
|
81
|
+
</div>
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
- The code is required. A comment without one would also hide a diagnostic added to that
|
|
85
|
+
line later.
|
|
86
|
+
- Several codes can be listed, separated by commas or spaces: `BARQ001, BARQ003`.
|
|
87
|
+
- A reason in parentheses is required and has to be at least 10 characters.
|
|
88
|
+
- The comment covers the next line that is not blank and not a comment, so two comments
|
|
89
|
+
stacked above one line both apply to it. It covers one line, not one statement: a
|
|
90
|
+
diagnostic on the third line of a long statement needs the comment directly above that
|
|
91
|
+
line.
|
|
92
|
+
- A comment that silences nothing is reported as [BARQ008](BARQ008.md), and a comment
|
|
93
|
+
that cannot be read as [BARQ009](BARQ009.md). Both stay warnings whatever the project
|
|
94
|
+
settings say, so a comment cannot fail a build.
|
|
95
|
+
- A comment never changes the code the compiler produces.
|
|
96
|
+
|
|
97
|
+
## Changing a level for the whole project
|
|
98
|
+
|
|
99
|
+
```ts
|
|
100
|
+
barq({
|
|
101
|
+
compiler: {
|
|
102
|
+
checks: { BARQ004: "suppress", BARQ001: "error" },
|
|
103
|
+
defaultCategory: "warning",
|
|
104
|
+
},
|
|
105
|
+
});
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
A level is `suppress`, `note`, `warning` or `error`. An entry in `checks` wins over
|
|
109
|
+
`strictCss`, which makes BARQ014 to BARQ017 errors; that wins over `defaultCategory`,
|
|
110
|
+
which applies to every code; and that wins over the code's own level. The compiler and
|
|
111
|
+
the Vite plugin read the same settings, so a code silenced here is silent everywhere.
|
|
112
|
+
|
|
113
|
+
The compiler prints each fix as text and never rewrites your source.
|
|
114
|
+
|
|
115
|
+
## What the rules cannot see
|
|
116
|
+
|
|
117
|
+
The checks report only what they can prove from one file, so silence is not a guarantee.
|
|
118
|
+
|
|
119
|
+
- **Other files.** An accessor imported from another module is not known to be one, so
|
|
120
|
+
BARQ001 to BARQ003 say nothing about it, and BARQ010 does not follow a prop into a
|
|
121
|
+
component declared in another file.
|
|
122
|
+
- **Files without JSX.** The accessor and props rules run on `.jsx` and `.tsx` files.
|
|
123
|
+
- **A reassigned name.** A `let` that is assigned again is not treated as an
|
|
124
|
+
accessor.
|
|
125
|
+
- **A function that is not a component.** BARQ030 and BARQ031 are about a component's
|
|
126
|
+
props, and a component is a function with a capitalised name that holds JSX or is
|
|
127
|
+
written as a tag, a default export that holds JSX, or a function written inline at a
|
|
128
|
+
route option such as `component`. A function with a lowercase name is not one, so its
|
|
129
|
+
parameter is not reported.
|
|
130
|
+
- **A prop's value.** Every prop can change as far as the component can tell, whether or
|
|
131
|
+
not the caller passes anything that changes, so BARQ018 counts a prop only where the
|
|
132
|
+
same file renders the component with a value that changes.
|
|
133
|
+
- **A helper function.** BARQ019 sees a write written in the component body or in the
|
|
134
|
+
computation itself, not one inside a function the body calls.
|
|
135
|
+
- **A row whose `keyed` is not written out.** With `<For keyed={KEYED}>` or
|
|
136
|
+
`<For {...options}>` the compiler does not know whether the row is an accessor, so
|
|
137
|
+
BARQ001 to BARQ003 say nothing about that row.
|