@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/index.d.ts
ADDED
|
@@ -0,0 +1,604 @@
|
|
|
1
|
+
/* auto-generated by NAPI-RS */
|
|
2
|
+
/* eslint-disable */
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* One entry of `boundaries`: a component whose JSX children render through
|
|
6
|
+
* another renderer than the JSX around it, the way a canvas component hosts a
|
|
7
|
+
* scene graph inside a document.
|
|
8
|
+
*/
|
|
9
|
+
export interface BoundaryEntry {
|
|
10
|
+
/** The module the component is imported from. */
|
|
11
|
+
source: string
|
|
12
|
+
/** The name it is exported under. */
|
|
13
|
+
name: string
|
|
14
|
+
/** `"dom"` or `"universal"`: what its children compile for. */
|
|
15
|
+
target: string
|
|
16
|
+
/** The module its children import the renderer's helpers from. */
|
|
17
|
+
moduleSource: string
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
export declare function diagnosticCodes(): Array<JsCode>
|
|
21
|
+
|
|
22
|
+
export declare function gatherAtoms(sheets: Array<string>): GatheredAtoms
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* Every atom of a build's stylesheets in one sheet, each written once and in
|
|
26
|
+
* one tier order, and the sheets without them.
|
|
27
|
+
*
|
|
28
|
+
* The bundler's stylesheets are per chunk and the tier order is per sheet, so
|
|
29
|
+
* an atom two chunks share is written twice and the later copy can win a pair
|
|
30
|
+
* the order was meant to settle. `sheets[i]` of the result is `sheets[i]` of
|
|
31
|
+
* the input with its atoms removed; `atoms` goes where every page loads it.
|
|
32
|
+
*/
|
|
33
|
+
export interface GatheredAtoms {
|
|
34
|
+
atoms: string
|
|
35
|
+
sheets: Array<string>
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* One entry of `intrinsics`: lowercase tags a renderer claims, so a JSX tree
|
|
40
|
+
* rooted at one of them builds through that renderer wherever it is written.
|
|
41
|
+
*/
|
|
42
|
+
export interface IntrinsicEntry {
|
|
43
|
+
tags: Array<string>
|
|
44
|
+
/**
|
|
45
|
+
* Also claim a lowercase tag without a hyphen that no renderer names and
|
|
46
|
+
* the document does not have.
|
|
47
|
+
* @default false
|
|
48
|
+
*/
|
|
49
|
+
claimUnknown?: boolean
|
|
50
|
+
/** `"dom"` or `"universal"`. */
|
|
51
|
+
target: string
|
|
52
|
+
/** The module the claimed elements import the renderer's helpers from. */
|
|
53
|
+
moduleSource: string
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* Every diagnostic this build can raise, with its default level and its docs
|
|
58
|
+
* page. One resolution of the code table, shared by the Vite plugin and any
|
|
59
|
+
* CLI, so a listing cannot drift from what the compiler actually emits.
|
|
60
|
+
*/
|
|
61
|
+
export interface JsCode {
|
|
62
|
+
code: string
|
|
63
|
+
level: string
|
|
64
|
+
summary: string
|
|
65
|
+
docs: string
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* One diagnostic, as structured data. The span survives the boundary: `pos` is
|
|
70
|
+
* what Rollup's `this.warn(warning, position)` takes, and that argument is the
|
|
71
|
+
* only thing that produces `pos`/`loc`/`frame`. Flattening this to a string is
|
|
72
|
+
* what left the pipeline with no code frame anywhere, in any mode.
|
|
73
|
+
*/
|
|
74
|
+
export interface JsDiagnostic {
|
|
75
|
+
/** `BARQ001`; absent for a parser diagnostic, which is oxc's code space. */
|
|
76
|
+
code?: string
|
|
77
|
+
/** `note` | `warning` | `error` */
|
|
78
|
+
severity: string
|
|
79
|
+
message: string
|
|
80
|
+
file: string
|
|
81
|
+
/** 1-based */
|
|
82
|
+
line: number
|
|
83
|
+
/** 1-based, UTF-16 code units — what a source map counts */
|
|
84
|
+
column: number
|
|
85
|
+
endLine: number
|
|
86
|
+
endColumn: number
|
|
87
|
+
/**
|
|
88
|
+
* UTF-16 offset into the ORIGINAL source, which is the string index
|
|
89
|
+
* Rollup's `position` takes
|
|
90
|
+
*/
|
|
91
|
+
pos: number
|
|
92
|
+
end: number
|
|
93
|
+
/** path of the docs page for this code, relative to the package root */
|
|
94
|
+
docs?: string
|
|
95
|
+
/**
|
|
96
|
+
* The edits that repair it, when the repair is one spelling: apply every
|
|
97
|
+
* one, last first, and the finding is gone.
|
|
98
|
+
*/
|
|
99
|
+
fix?: Array<JsEdit>
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/**
|
|
103
|
+
* One replacement in the original source. `pos` and `end` are UTF-16 offsets,
|
|
104
|
+
* and equal for an insertion.
|
|
105
|
+
*/
|
|
106
|
+
export interface JsEdit {
|
|
107
|
+
pos: number
|
|
108
|
+
end: number
|
|
109
|
+
text: string
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/** A dev-mode label: which JSX, in which component, produced a hoisted template. */
|
|
113
|
+
export interface JsTemplateLabel {
|
|
114
|
+
template: string
|
|
115
|
+
component?: string
|
|
116
|
+
line: number
|
|
117
|
+
column: number
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* The cascade layer order `sheets` between them declare, as one list.
|
|
122
|
+
*
|
|
123
|
+
* Read from the modules the compiler emitted rather than from the built
|
|
124
|
+
* assets, because a minifier has rewritten the statement by then: Lightning
|
|
125
|
+
* CSS drops the names that have a block in the same file, which is sound
|
|
126
|
+
* within one sheet and loses the order across several.
|
|
127
|
+
*/
|
|
128
|
+
export declare function layerOrder(sheets: Array<string>): Array<string>
|
|
129
|
+
|
|
130
|
+
/**
|
|
131
|
+
* The CLIENT half of a module that declares middleware: `.server(…)` deleted,
|
|
132
|
+
* and any top-level declaration only it reached deleted with it.
|
|
133
|
+
*
|
|
134
|
+
* Returns the source unchanged when there is nothing to strip, so a caller can
|
|
135
|
+
* hand every module through without asking first.
|
|
136
|
+
*
|
|
137
|
+
* `middleware_split.rs` says why this has to exist: a middleware's client half
|
|
138
|
+
* runs in the browser, so the client stub imports the module that declares it —
|
|
139
|
+
* and a module holding a session check reaches whatever that check needs. The
|
|
140
|
+
* same import through a route's `middleware` once left a fully server-rendered
|
|
141
|
+
* page on which nothing was interactive.
|
|
142
|
+
*/
|
|
143
|
+
export declare function middlewareSplit(source: string, filename: string, startSource?: string | undefined | null): string
|
|
144
|
+
|
|
145
|
+
/**
|
|
146
|
+
* The `Backend` trait's whole instruction set, by `Op` variant name, generated
|
|
147
|
+
* from the same macro list the trait and its dispatch are generated from
|
|
148
|
+
* (`codegen::backend::OPS`).
|
|
149
|
+
*
|
|
150
|
+
* It crosses the boundary so the reference backend's JS half can be checked
|
|
151
|
+
* against it in BOTH directions. Rust exhaustiveness makes a new `Op` a compile
|
|
152
|
+
* error in every `impl Backend`; nothing in the language can make it a compile
|
|
153
|
+
* error in `interp.ts`, so the name sets are asserted equal instead — the same
|
|
154
|
+
* bidirectional pinning discipline the rule IDs use.
|
|
155
|
+
*/
|
|
156
|
+
export declare function opcodes(): Array<string>
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* A bundled stylesheet with its atoms ordered by tier.
|
|
160
|
+
*
|
|
161
|
+
* The compiler emits one stylesheet per MODULE and a bundler concatenates them
|
|
162
|
+
* in import order, so an atom's tier — the one thing that settles a base rule
|
|
163
|
+
* against the same property under an at-rule, since `@media` adds no
|
|
164
|
+
* specificity — held inside one `atoms` call and nowhere else. `collectCss`
|
|
165
|
+
* has always sorted globally, so dev was right and the production bundle was
|
|
166
|
+
* not; this is the same sort over the concatenated asset.
|
|
167
|
+
*
|
|
168
|
+
* Not a cascade layer, and it must never become one. A layer overrides
|
|
169
|
+
* specificity outright where a tier is a tie-breaker on top of it: measured in
|
|
170
|
+
* a browser, one sub-layer per tier moved 289 computed values on `@barqjs/ui`'s
|
|
171
|
+
* gallery and reordering moves 8, every one of them a rule under an at-rule
|
|
172
|
+
* that a later base rule was beating.
|
|
173
|
+
*
|
|
174
|
+
* `layers` is the document's cascade layer order, and it is declared in front
|
|
175
|
+
* of every asset that names a layer at all. A layer's position is fixed by its
|
|
176
|
+
* FIRST appearance across every stylesheet the page loads, so a code-split
|
|
177
|
+
* build cannot leave the statement in whichever chunk its module landed in:
|
|
178
|
+
* the chunk carrying `@layer barq.ui{ … }` may well be linked first, and then
|
|
179
|
+
* the components sit in front of the reset and Tailwind's preflight beats
|
|
180
|
+
* them. Repeating the statement is idempotent by specification.
|
|
181
|
+
*
|
|
182
|
+
* Idempotent, and safe over a stylesheet holding none of ours: a rule that is
|
|
183
|
+
* not an atom keeps its index.
|
|
184
|
+
*/
|
|
185
|
+
export declare function orderCss(css: string, layers?: Array<string> | undefined | null): string
|
|
186
|
+
|
|
187
|
+
/**
|
|
188
|
+
* One entry of `renderers`: the files it matches compile for its target,
|
|
189
|
+
* importing from its module.
|
|
190
|
+
*/
|
|
191
|
+
export interface RendererEntry {
|
|
192
|
+
/**
|
|
193
|
+
* Globs matched against the file name: `*` within one path segment, `**`
|
|
194
|
+
* across segments. A pattern that does not start with `/` matches at any
|
|
195
|
+
* directory, so `src/scene/**` matches `/home/salama/app/src/scene/a.tsx`.
|
|
196
|
+
*/
|
|
197
|
+
include: Array<string>
|
|
198
|
+
/**
|
|
199
|
+
* `"dom"` or `"universal"`.
|
|
200
|
+
* @default `"universal"`
|
|
201
|
+
*/
|
|
202
|
+
target?: string
|
|
203
|
+
/**
|
|
204
|
+
* The module these files import the renderer's helpers from.
|
|
205
|
+
* @default the top-level `moduleSource`
|
|
206
|
+
*/
|
|
207
|
+
moduleSource?: string
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
/**
|
|
211
|
+
* One route's id and the source file it came from.
|
|
212
|
+
*
|
|
213
|
+
* The route table itself carries `src` per node, but a build wants the mapping
|
|
214
|
+
* WITHOUT parsing the module it just generated — a second reader of our own
|
|
215
|
+
* emit is a second thing to keep in step. `<link rel="modulepreload">` and the
|
|
216
|
+
* route-action manifest both start from this.
|
|
217
|
+
*/
|
|
218
|
+
export interface RouteEntry {
|
|
219
|
+
/** The route id, as `RouteMap` keys it. */
|
|
220
|
+
id: string
|
|
221
|
+
/** Project-relative source path, without the leading slash the module uses. */
|
|
222
|
+
file: string
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
/**
|
|
226
|
+
* A route file whose id literal is out of date.
|
|
227
|
+
*
|
|
228
|
+
* The literal is generator-owned: it is derived from the filename, so a rename
|
|
229
|
+
* makes it wrong and hand-maintaining it is the chore `createFileRoute` exists
|
|
230
|
+
* to remove.
|
|
231
|
+
*/
|
|
232
|
+
export interface RouteIdMismatch {
|
|
233
|
+
/** Project-relative source path. */
|
|
234
|
+
file: string
|
|
235
|
+
/** What the file says. */
|
|
236
|
+
declared: string
|
|
237
|
+
/** What its name derives. */
|
|
238
|
+
expected: string
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
/**
|
|
242
|
+
* Split a route module into the half the tree imports and the half it loads.
|
|
243
|
+
*
|
|
244
|
+
* The static route table is what makes a file route able to declare the whole
|
|
245
|
+
* option set — the router reads `validateSearch`, `beforeLoad` and the cache
|
|
246
|
+
* options synchronously — and the price is an eager component. This is where
|
|
247
|
+
* that price is paid back, and it is where TanStack pays it too
|
|
248
|
+
* (`router-plugin/src/core/constants.ts:4-16`).
|
|
249
|
+
*
|
|
250
|
+
* `specifier` is what the reference half will `import()`. The caller owns that
|
|
251
|
+
* spelling because the BUNDLER decides what a module id looks like, not the
|
|
252
|
+
* compiler.
|
|
253
|
+
*
|
|
254
|
+
* `for_client` also DELETES the `server` option, which holds a route's HTTP
|
|
255
|
+
* handlers. Without it a handler's body — and whatever it imports to reach a
|
|
256
|
+
* database — sits in the browser bundle. Theirs deletes the same node.
|
|
257
|
+
*/
|
|
258
|
+
export declare function routeSplit(source: string, filename: string, specifier: string, forClient?: boolean | undefined | null, splitComponents?: boolean | undefined | null, coreSource?: string | undefined | null): RouteSplitResult
|
|
259
|
+
|
|
260
|
+
/** Both halves of a code-split route module. */
|
|
261
|
+
export interface RouteSplitResult {
|
|
262
|
+
/**
|
|
263
|
+
* The module the generated tree imports, with each split value replaced by
|
|
264
|
+
* a `lazy()` over the other half.
|
|
265
|
+
*/
|
|
266
|
+
reference: string
|
|
267
|
+
/** The module `<file>?barq-split` serves. */
|
|
268
|
+
split: string
|
|
269
|
+
/**
|
|
270
|
+
* Why the route was NOT split. Both halves are the original source in that
|
|
271
|
+
* case, so a refusal costs bytes and never correctness.
|
|
272
|
+
*/
|
|
273
|
+
refused?: string
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
/**
|
|
277
|
+
* Scan a directory of route files and emit the table and its types.
|
|
278
|
+
*
|
|
279
|
+
* The whole of file-based routing, in one call. The plugin asks and
|
|
280
|
+
* invalidates; it does not read the directory, derive a route from a filename,
|
|
281
|
+
* or build a string — so a route table cannot mean two things.
|
|
282
|
+
*
|
|
283
|
+
* `out_file` is where the caller will write `source`, project-relative — the
|
|
284
|
+
* import specifiers it emits are relative to that file's own directory.
|
|
285
|
+
*
|
|
286
|
+
* `write_ids` is the one thing here that TOUCHES the project: a route's id
|
|
287
|
+
* literal is generator-owned, so a rename makes it wrong, and dev rewrites it
|
|
288
|
+
* in place the way their plugin does (`transform.ts:133-140`). A BUILD does
|
|
289
|
+
* not — it reports the disagreement instead, so CI cannot pass on a file the
|
|
290
|
+
* build silently edited.
|
|
291
|
+
*/
|
|
292
|
+
export declare function routeTree(root: string, dir: string, outFile?: string | undefined | null, writeIds?: boolean | undefined | null): RouteTreeResult
|
|
293
|
+
|
|
294
|
+
/** The generated route table, its types, and what produced them. */
|
|
295
|
+
export interface RouteTreeResult {
|
|
296
|
+
/**
|
|
297
|
+
* The contents of `routeTree.gen.ts` — the table AND its types.
|
|
298
|
+
*
|
|
299
|
+
* One file rather than a virtual module plus a `.d.ts`, which is
|
|
300
|
+
* TanStack's arrangement, whose generated tree defaults to
|
|
301
|
+
* `./src/routeTree.gen.ts`. The caller writes it where `out_file` said.
|
|
302
|
+
*/
|
|
303
|
+
source: string
|
|
304
|
+
/**
|
|
305
|
+
* Every route file found, project-relative. The caller registers these
|
|
306
|
+
* with its watcher — file EVENTS are the one part of this that cannot move
|
|
307
|
+
* into the compiler, because the bundler owns them.
|
|
308
|
+
*/
|
|
309
|
+
files: Array<string>
|
|
310
|
+
/** Every leaf pattern, which is what `routes` wants for `BARQ013`. */
|
|
311
|
+
patterns: Array<string>
|
|
312
|
+
/** Route id to source file, layouts included, for the build-time checks. */
|
|
313
|
+
entries: Array<RouteEntry>
|
|
314
|
+
/**
|
|
315
|
+
* Declarations a route made that are present but not literals. The caller
|
|
316
|
+
* reports these; the table cannot carry them and will not guess.
|
|
317
|
+
*/
|
|
318
|
+
warnings: Array<string>
|
|
319
|
+
/**
|
|
320
|
+
* Route files whose `createFileRoute` id literal disagrees with the id
|
|
321
|
+
* their FILENAME derives, and that were not rewritten. Empty when
|
|
322
|
+
* `writeIds` asked for the rewrite and it succeeded.
|
|
323
|
+
*/
|
|
324
|
+
mismatches: Array<RouteIdMismatch>
|
|
325
|
+
/** Route files whose id literal was rewritten on disk this call. */
|
|
326
|
+
rewritten: Array<string>
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
export declare function transform(code: string, options?: TransformOptions | undefined | null): TransformResult
|
|
330
|
+
|
|
331
|
+
/**
|
|
332
|
+
* `autoComputed` and the three component NAME LISTS the deleted Babel plugin
|
|
333
|
+
* took are not here and will not be. Nothing in this compiler could read them —
|
|
334
|
+
* every component and every reactive read resolves by `SymbolId` in P0,
|
|
335
|
+
* and `autoComputed` rewrote statements OUTSIDE JSX, which this pipeline never
|
|
336
|
+
* touches: lowering takes no `Program` and codegen only splices at the sites
|
|
337
|
+
* harvest recorded.
|
|
338
|
+
*/
|
|
339
|
+
export interface TransformOptions {
|
|
340
|
+
filename?: string
|
|
341
|
+
sourcemap?: boolean
|
|
342
|
+
/**
|
|
343
|
+
* Module source for the renderer's helpers. Under `target: "universal"`
|
|
344
|
+
* it is the module that exports what `createRenderer` returned.
|
|
345
|
+
* @default `@barqjs/web`
|
|
346
|
+
*/
|
|
347
|
+
moduleSource?: string
|
|
348
|
+
/**
|
|
349
|
+
* `"dom"` or `"universal"`. `"universal"` compiles for a renderer made
|
|
350
|
+
* with `@barqjs/universal`'s `createRenderer`, imported from
|
|
351
|
+
* `moduleSource`. `ssr`, `hydratable` and `interp` are document
|
|
352
|
+
* concepts, and asking for one of them with it is an error.
|
|
353
|
+
* @default `"dom"`
|
|
354
|
+
*/
|
|
355
|
+
target?: string
|
|
356
|
+
/**
|
|
357
|
+
* Per-file renderer selection: a file matching an entry's `include`
|
|
358
|
+
* compiles for that entry's target and module, whatever `target`,
|
|
359
|
+
* `moduleSource`, `ssr` and `hydratable` say for the rest of the build.
|
|
360
|
+
* The first entry that matches wins.
|
|
361
|
+
*/
|
|
362
|
+
renderers?: Array<RendererEntry>
|
|
363
|
+
/**
|
|
364
|
+
* Components whose children compile for another renderer. A JSX element
|
|
365
|
+
* whose tag is the import `name` from `source` compiles for the module's
|
|
366
|
+
* own target, and its children for the entry's `target` and
|
|
367
|
+
* `moduleSource`. Boundaries nest.
|
|
368
|
+
*/
|
|
369
|
+
boundaries?: Array<BoundaryEntry>
|
|
370
|
+
/**
|
|
371
|
+
* Intrinsic tags a renderer claims. A tree of intrinsic elements outside
|
|
372
|
+
* every boundary whose root tag one entry claims, and the document does
|
|
373
|
+
* not have, compiles for that entry's `target` and `moduleSource`.
|
|
374
|
+
*/
|
|
375
|
+
intrinsics?: Array<IntrinsicEntry>
|
|
376
|
+
/**
|
|
377
|
+
* Module source for the helpers every target shares and for the
|
|
378
|
+
* components and primitives an author imports.
|
|
379
|
+
* @default `@barqjs/core`
|
|
380
|
+
*/
|
|
381
|
+
coreSource?: string
|
|
382
|
+
/**
|
|
383
|
+
* Module source for the string backend's helpers.
|
|
384
|
+
* @default `@barqjs/server`
|
|
385
|
+
*/
|
|
386
|
+
serverSource?: string
|
|
387
|
+
/**
|
|
388
|
+
* Module source for `createServerFn`.
|
|
389
|
+
* @default `@barqjs/start`
|
|
390
|
+
*/
|
|
391
|
+
startSource?: string
|
|
392
|
+
/**
|
|
393
|
+
* Where the emitted CLIENT stub imports `clientRpc` from. Not the same
|
|
394
|
+
* module as {@link start_source} — see `DEFAULT_CLIENT_SOURCE`.
|
|
395
|
+
* @default `@barqjs/start/client`
|
|
396
|
+
*/
|
|
397
|
+
clientSource?: string
|
|
398
|
+
/**
|
|
399
|
+
* Module source for `Link` and `NavLink`.
|
|
400
|
+
* @default `@barqjs/router`
|
|
401
|
+
*/
|
|
402
|
+
routerSource?: string
|
|
403
|
+
/**
|
|
404
|
+
* Module source for `css`, `keyframes` and `globalCss`.
|
|
405
|
+
* @default `@barqjs/css`
|
|
406
|
+
*/
|
|
407
|
+
cssSource?: string
|
|
408
|
+
/**
|
|
409
|
+
* Every route pattern in the project, for `BARQ013` to check `<Link to>`
|
|
410
|
+
* against. The compiler sees ONE module; the route set is a whole-project
|
|
411
|
+
* fact, so it arrives as an option rather than being discovered.
|
|
412
|
+
*
|
|
413
|
+
* Absent (rather than empty) turns the check off, so a project without a
|
|
414
|
+
* route table does not get a warning on every link it writes.
|
|
415
|
+
*/
|
|
416
|
+
routes?: Array<string>
|
|
417
|
+
/**
|
|
418
|
+
* `"client"` or `"server"`. Picks which half of the program this module is
|
|
419
|
+
* being compiled for, which is a different question from `ssr`'s backend.
|
|
420
|
+
* @default `"server"`
|
|
421
|
+
*/
|
|
422
|
+
env?: string
|
|
423
|
+
/**
|
|
424
|
+
* Project root. Server-function ids are derived relative to it, so an id
|
|
425
|
+
* carries no absolute path — RedwoodSDK ships `/src/path.ts#name` verbatim
|
|
426
|
+
* in its client bundle, which hands an attacker the source tree layout.
|
|
427
|
+
*/
|
|
428
|
+
root?: string
|
|
429
|
+
/**
|
|
430
|
+
* Emit the module's server-function exports alongside the code. A side
|
|
431
|
+
* artefact on the same terms as `ownership` and `addresses`: nothing it
|
|
432
|
+
* produces reaches lowering, the passes or codegen, so `code` is
|
|
433
|
+
* byte-identical either way.
|
|
434
|
+
*/
|
|
435
|
+
serverFns?: boolean
|
|
436
|
+
dev?: boolean
|
|
437
|
+
/**
|
|
438
|
+
* Carry names and positions from the source into the output, for the
|
|
439
|
+
* runtime's development findings: a signal, memo, effect or store is named
|
|
440
|
+
* after the binding it is declared as, a binding effect after the element
|
|
441
|
+
* and attribute it writes, and each of them and every component call
|
|
442
|
+
* carries `file:line:col`, the file relative to `root`. Positions need a
|
|
443
|
+
* `filename`.
|
|
444
|
+
* @default the value of `dev`
|
|
445
|
+
*/
|
|
446
|
+
sourceNames?: boolean
|
|
447
|
+
templates?: boolean
|
|
448
|
+
ssr?: boolean
|
|
449
|
+
/**
|
|
450
|
+
* Emit for the reference backend instead of the DOM
|
|
451
|
+
* backend: the analysed IR is serialised beside the module and
|
|
452
|
+
* `@barqjs/web/interp` walks it. DEV and test only. Wins over `ssr`,
|
|
453
|
+
* because the two are different backends over the same IR and asking for
|
|
454
|
+
* both is a caller bug rather than a blend.
|
|
455
|
+
*/
|
|
456
|
+
interp?: boolean
|
|
457
|
+
/**
|
|
458
|
+
* Run the source-level diagnostic rules (D1). Defaults to `dev`: they
|
|
459
|
+
* are advice about reactivity, they are delivered through the dev channels,
|
|
460
|
+
* and a production build should not pay for analysis nobody reads. Set it
|
|
461
|
+
* explicitly to run them in CI.
|
|
462
|
+
*/
|
|
463
|
+
diagnostics?: boolean
|
|
464
|
+
/**
|
|
465
|
+
* Per-code severity, `[[code, category]]`. `category` is one of `suppress`,
|
|
466
|
+
* `note`, `warning`, `error`. napi has no map type, so this is pairs.
|
|
467
|
+
*/
|
|
468
|
+
checks?: Array<Array<string>>
|
|
469
|
+
/**
|
|
470
|
+
* Report what this module EXPORTS that another could fold against, and do
|
|
471
|
+
* it even when the module writes no CSS of its own.
|
|
472
|
+
*
|
|
473
|
+
* Off by default, because a normal transform has no use for it: an
|
|
474
|
+
* integration turns it on only for a file some other file imports from.
|
|
475
|
+
* @default false
|
|
476
|
+
*/
|
|
477
|
+
cssExports?: boolean
|
|
478
|
+
/**
|
|
479
|
+
* What this module's imports resolve to, which an integration looked up
|
|
480
|
+
* and this compiler did not.
|
|
481
|
+
*
|
|
482
|
+
* `[specifier, exported name, kind, member, value]`, where `kind` is
|
|
483
|
+
* `text`, `group` or `layer` and `member` is the group key or empty. napi
|
|
484
|
+
* has no map type, so this is tuples.
|
|
485
|
+
*
|
|
486
|
+
* The pass stays a pure function of its inputs: it reads no file, it only
|
|
487
|
+
* reports which one it would have to (`cssImportsWanted`) and folds what
|
|
488
|
+
* it is handed. That is what keeps dev and a build identical — a name
|
|
489
|
+
* resolves to the same value in both, where StyleX's aggregate over every
|
|
490
|
+
* module does not.
|
|
491
|
+
*/
|
|
492
|
+
cssImports?: Array<Array<string>>
|
|
493
|
+
/**
|
|
494
|
+
* Every CSS diagnostic is an error, so a call `@barqjs/css`'s runtime
|
|
495
|
+
* would have to evaluate fails the build instead.
|
|
496
|
+
*
|
|
497
|
+
* The point is what it makes provable rather than what it forbids: with
|
|
498
|
+
* no call falling back, nothing reaches the runtime's object walk, and a
|
|
499
|
+
* build can drop it. An explicit `checks` entry still wins over this.
|
|
500
|
+
* @default false
|
|
501
|
+
*/
|
|
502
|
+
strictCss?: boolean
|
|
503
|
+
/** The category every code takes when `checks` does not name it. */
|
|
504
|
+
defaultCategory?: string
|
|
505
|
+
/**
|
|
506
|
+
* Emit the static ownership tree alongside the
|
|
507
|
+
* code. It is a side artefact: no field it produces reaches lowering, the
|
|
508
|
+
* passes or codegen, so `code` is byte-identical either way. Off by
|
|
509
|
+
* default — a production compile does not pay for the extra AST walk.
|
|
510
|
+
*/
|
|
511
|
+
ownership?: boolean
|
|
512
|
+
/**
|
|
513
|
+
* Emit the compile-time address table alongside the code. A side artefact
|
|
514
|
+
* on the same terms as `ownership`: nothing it produces reaches lowering,
|
|
515
|
+
* the passes or codegen, so `code` is byte-identical either way. Its point
|
|
516
|
+
* is that the DOM and the string backend can be compiled from one source
|
|
517
|
+
* and their address sets diffed.
|
|
518
|
+
*/
|
|
519
|
+
addresses?: boolean
|
|
520
|
+
/**
|
|
521
|
+
* Emit for CLAIM-BASED HYDRATION.
|
|
522
|
+
*
|
|
523
|
+
* Unlike `ownership` and `addresses` this one DOES change the emitted
|
|
524
|
+
* module, on both backends, and that is the point: the
|
|
525
|
+
* string backend writes `<!--[-->` … `<!--]-->` at every hole and
|
|
526
|
+
* `<!--[k-->` at every range, and the DOM backend walks through `child`
|
|
527
|
+
* and `sib` — a hydration-only logical index that steps over those ranges
|
|
528
|
+
* — instead of `.firstChild`/`.nextSibling`.
|
|
529
|
+
*
|
|
530
|
+
* Off by default, so a page that is never hydrated pays neither the wire
|
|
531
|
+
* bytes nor the indirection. H3's falsification procedure is exactly the
|
|
532
|
+
* diff between the two settings.
|
|
533
|
+
*/
|
|
534
|
+
hydratable?: boolean
|
|
535
|
+
/**
|
|
536
|
+
* The optimisation level. `0` turns every optimisation off and is the
|
|
537
|
+
* oracle's reference; anything else is the optimising
|
|
538
|
+
* path, which is the default. It changes no semantics — `-O0` output is
|
|
539
|
+
* slower and larger and never different.
|
|
540
|
+
*/
|
|
541
|
+
optimize?: number
|
|
542
|
+
/**
|
|
543
|
+
* Per-pass override on top of `optimize`, `[[name, "on"|"off"]]`. napi has
|
|
544
|
+
* no map type, so this is pairs. The names are `fold`, `dedup`, `anchor`,
|
|
545
|
+
* `fuse`, `walk`, `eta`, `hoist`, `splice`, `flow` — one flag per
|
|
546
|
+
* optimisation, because the -O0/-Ox differential's payoff is that every
|
|
547
|
+
* optimisation is individually bisectable.
|
|
548
|
+
*/
|
|
549
|
+
passes?: Array<Array<string>>
|
|
550
|
+
}
|
|
551
|
+
|
|
552
|
+
export interface TransformResult {
|
|
553
|
+
code: string
|
|
554
|
+
map?: string
|
|
555
|
+
/**
|
|
556
|
+
* Every diagnostic, formatted as `file:line:col: CODE level: message`.
|
|
557
|
+
* Kept alongside `diagnostics` because a string is what a plain `this.warn`
|
|
558
|
+
* and a console sink both want; `diagnostics` is what a code frame needs.
|
|
559
|
+
*/
|
|
560
|
+
warnings: Array<string>
|
|
561
|
+
diagnostics: Array<JsDiagnostic>
|
|
562
|
+
/** Populated under `dev` only. */
|
|
563
|
+
labels: Array<JsTemplateLabel>
|
|
564
|
+
/**
|
|
565
|
+
* The static ownership tree as JSON, under `ownership: true` only.
|
|
566
|
+
* The oracle's expected value, derived from the source rather than from a
|
|
567
|
+
* second execution.
|
|
568
|
+
*/
|
|
569
|
+
ownership?: string
|
|
570
|
+
/**
|
|
571
|
+
* This module's export surface and which exports are server functions, as
|
|
572
|
+
* JSON, under `serverFns: true` only. The build reads it to know what to
|
|
573
|
+
* mount, and a reviewer reads it to see what is public.
|
|
574
|
+
*/
|
|
575
|
+
serverFns?: string
|
|
576
|
+
/**
|
|
577
|
+
* The compile-time address table as JSON, under `addresses: true` only.
|
|
578
|
+
* `(module, unit, position)` for every
|
|
579
|
+
* position in the module, computed identically by every backend.
|
|
580
|
+
*/
|
|
581
|
+
addresses?: string
|
|
582
|
+
/**
|
|
583
|
+
* This module's stylesheet, when it wrote any `css`. The build serves it
|
|
584
|
+
* from a virtual module the transformed code imports, so the bundler owns
|
|
585
|
+
* dev invalidation, the production asset and SSR collection — and one file
|
|
586
|
+
* edited invalidates one file's CSS.
|
|
587
|
+
*/
|
|
588
|
+
css?: string
|
|
589
|
+
/**
|
|
590
|
+
* `[specifier, exported name]` for every imported binding a fold needed
|
|
591
|
+
* and did not have.
|
|
592
|
+
*
|
|
593
|
+
* Empty when the module folded on its own, which is the point: an
|
|
594
|
+
* integration resolves these and calls `transform` again with
|
|
595
|
+
* `cssImports`, so it pays for resolution only where it buys a fold.
|
|
596
|
+
*/
|
|
597
|
+
cssWanted: Array<Array<string>>
|
|
598
|
+
/**
|
|
599
|
+
* `[exported name, kind, member, value]` for what this module exports that
|
|
600
|
+
* another can fold against, under `cssExports: true` or whenever the
|
|
601
|
+
* module writes CSS. `kind` is `text`, `number`, `group` or `layer`.
|
|
602
|
+
*/
|
|
603
|
+
cssExports: Array<Array<string>>
|
|
604
|
+
}
|
package/index.js
ADDED
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
const { existsSync, readFileSync } = require("node:fs");
|
|
4
|
+
const { join } = require("node:path");
|
|
5
|
+
|
|
6
|
+
const { name, version } = require("./package.json");
|
|
7
|
+
|
|
8
|
+
const PREBUILT = [
|
|
9
|
+
"darwin-arm64",
|
|
10
|
+
"darwin-x64",
|
|
11
|
+
"linux-arm64-gnu",
|
|
12
|
+
"linux-x64-gnu",
|
|
13
|
+
"linux-x64-musl",
|
|
14
|
+
"win32-arm64-msvc",
|
|
15
|
+
"win32-x64-msvc",
|
|
16
|
+
];
|
|
17
|
+
|
|
18
|
+
function isMusl() {
|
|
19
|
+
try {
|
|
20
|
+
return readFileSync("/usr/bin/ldd", "utf8").includes("musl");
|
|
21
|
+
} catch {
|
|
22
|
+
const report = typeof process.report?.getReport === "function" ? process.report.getReport() : null;
|
|
23
|
+
return report !== null && !report.header?.glibcVersionRuntime;
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
function platformKey() {
|
|
28
|
+
const { platform, arch } = process;
|
|
29
|
+
if (platform === "linux") return `linux-${arch}-${isMusl() ? "musl" : "gnu"}`;
|
|
30
|
+
if (platform === "win32") return `win32-${arch}-msvc`;
|
|
31
|
+
return `${platform}-${arch}`;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
function load() {
|
|
35
|
+
const key = platformKey();
|
|
36
|
+
|
|
37
|
+
// A binary beside this file can only be a local `napi build`: `files` does
|
|
38
|
+
// not ship one. It wins over the installed platform package, and a broken one
|
|
39
|
+
// is an error rather than a fallback, so the workspace never silently tests
|
|
40
|
+
// the last published compiler.
|
|
41
|
+
const local = join(__dirname, `barq-compiler.${key}.node`);
|
|
42
|
+
if (existsSync(local)) return require(local);
|
|
43
|
+
|
|
44
|
+
const pkg = `${name}-${key}`;
|
|
45
|
+
if (!PREBUILT.includes(key)) {
|
|
46
|
+
throw new Error(
|
|
47
|
+
`${name} has no prebuilt native binding for ${key}. Prebuilt bindings exist for ` +
|
|
48
|
+
`${PREBUILT.join(", ")}. On another platform, build one from source with a Rust ` +
|
|
49
|
+
"toolchain: `napi build --platform --release --no-js` in this package's directory.",
|
|
50
|
+
);
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
let resolved;
|
|
54
|
+
try {
|
|
55
|
+
resolved = require.resolve(pkg);
|
|
56
|
+
} catch (error) {
|
|
57
|
+
if (error?.code !== "MODULE_NOT_FOUND") throw error;
|
|
58
|
+
throw new Error(
|
|
59
|
+
`${name} could not find its native binding for ${key}: the optional dependency ${pkg} ` +
|
|
60
|
+
"is not installed. Package managers skip it when optional dependencies are disabled " +
|
|
61
|
+
"(--no-optional, --omit=optional) or when the lockfile was written on another platform. " +
|
|
62
|
+
"Reinstall with optional dependencies enabled.",
|
|
63
|
+
{ cause: error },
|
|
64
|
+
);
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
const installed = require(`${pkg}/package.json`).version;
|
|
68
|
+
if (installed !== version) {
|
|
69
|
+
throw new Error(
|
|
70
|
+
`${name}@${version} found ${pkg}@${installed}; the two are released together and must ` +
|
|
71
|
+
"match. Reinstall so the lockfile resolves both to the same version.",
|
|
72
|
+
);
|
|
73
|
+
}
|
|
74
|
+
return require(resolved);
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
const binding = load();
|
|
78
|
+
|
|
79
|
+
// One static assignment per export: node's CommonJS-to-ESM bridge finds named
|
|
80
|
+
// exports by scanning for this shape, so `import { transform }` needs it.
|
|
81
|
+
|
|
82
|
+
module.exports.diagnosticCodes = binding.diagnosticCodes;
|
|
83
|
+
module.exports.gatherAtoms = binding.gatherAtoms;
|
|
84
|
+
module.exports.layerOrder = binding.layerOrder;
|
|
85
|
+
module.exports.middlewareSplit = binding.middlewareSplit;
|
|
86
|
+
module.exports.opcodes = binding.opcodes;
|
|
87
|
+
module.exports.orderCss = binding.orderCss;
|
|
88
|
+
module.exports.routeSplit = binding.routeSplit;
|
|
89
|
+
module.exports.routeTree = binding.routeTree;
|
|
90
|
+
module.exports.transform = binding.transform;
|