@barqjs/cli 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 +128 -2
- package/dist/index.d.ts +104 -0
- package/dist/index.js +486 -0
- package/package.json +66 -4
- package/src/check.ts +518 -0
- package/src/index.ts +212 -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,129 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @barqjs/cli
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The `barq` command. It runs a project through the compiler's diagnostics with
|
|
4
|
+
no build and no dev server, prints what it finds as text or JSON, and applies
|
|
5
|
+
the fixes the findings carry.
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install --save-dev @barqjs/cli
|
|
9
|
+
npx barq check
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## `barq check [paths...]`
|
|
13
|
+
|
|
14
|
+
Checks every `.tsx` and `.jsx` file under the paths, and every script that
|
|
15
|
+
imports a `@barqjs/` package. With no path it checks the project root.
|
|
16
|
+
`node_modules`, `dist`, `build`, `coverage` and directories starting with a dot
|
|
17
|
+
are skipped.
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
src/view.tsx:7:32 warning BARQ001 `count` is an accessor, and here the function itself is used as the value. In a string it prints its own source text and in arithmetic it gives `NaN`. Call it: `count()`.
|
|
21
|
+
docs: https://github.com/salamaashoush/barq/blob/main/packages/compiler/docs/BARQ001.md
|
|
22
|
+
fix: `barq check --fix` repairs this
|
|
23
|
+
|
|
24
|
+
0 errors, 1 warning, 0 notes in 1 file, 1 more fixable with `--fix`
|
|
25
|
+
repair guide: node_modules/@barqjs/compiler/skills/compiler-diagnostics/SKILL.md
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Options:
|
|
29
|
+
|
|
30
|
+
- `--json`: one JSON document on stdout.
|
|
31
|
+
- `--fix`: apply the fixes, then report what is left.
|
|
32
|
+
- `--root <dir>`: the project root. Paths in the output are relative to it.
|
|
33
|
+
- `--routes <dir>`: the directory of file routes. Defaults to `src/routes`.
|
|
34
|
+
- `--level <CODE=level>`: set a code to `suppress`, `note`, `warning` or
|
|
35
|
+
`error`. Repeatable.
|
|
36
|
+
- `--max-warnings <n>`: exit 1 when there are more warnings than `n`.
|
|
37
|
+
|
|
38
|
+
Exit status: `0` when nothing is at error level, `1` when something is or the
|
|
39
|
+
warnings pass `--max-warnings`, `2` for a command line it does not understand.
|
|
40
|
+
|
|
41
|
+
### File routes
|
|
42
|
+
|
|
43
|
+
When the routes directory exists, the check reads it the way the build does and
|
|
44
|
+
writes nothing. Every `<Link to>` is then checked against the routes it gives
|
|
45
|
+
(`BARQ013`), and a route file whose `createFileRoute` id disagrees with its
|
|
46
|
+
filename is an error, as it is in a build.
|
|
47
|
+
|
|
48
|
+
### Settings in `package.json`
|
|
49
|
+
|
|
50
|
+
```json
|
|
51
|
+
{
|
|
52
|
+
"barq": {
|
|
53
|
+
"check": {
|
|
54
|
+
"paths": ["src"],
|
|
55
|
+
"routes": "src/routes",
|
|
56
|
+
"extraRoutes": ["/demo/dashboard", "/demo/dashboard/users/$id"],
|
|
57
|
+
"levels": { "BARQ004": "error", "BARQ011": "suppress" }
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
`extraRoutes` names patterns a link may use beside the file routes, such as
|
|
64
|
+
those of a second router the application builds by hand. A flag on the command
|
|
65
|
+
line replaces the setting of the same name, and a `--level` is added after the
|
|
66
|
+
ones here.
|
|
67
|
+
|
|
68
|
+
### The JSON form
|
|
69
|
+
|
|
70
|
+
```json
|
|
71
|
+
{
|
|
72
|
+
"version": 1,
|
|
73
|
+
"root": "/work/app",
|
|
74
|
+
"files": 12,
|
|
75
|
+
"summary": { "errors": 0, "warnings": 1, "notes": 0, "fixable": 1, "fixed": 0 },
|
|
76
|
+
"findings": [
|
|
77
|
+
{
|
|
78
|
+
"code": "BARQ001",
|
|
79
|
+
"severity": "warning",
|
|
80
|
+
"message": "`count` is an accessor, and here the function itself is used as the value. ...",
|
|
81
|
+
"file": "src/view.tsx",
|
|
82
|
+
"line": 7,
|
|
83
|
+
"column": 32,
|
|
84
|
+
"endLine": 7,
|
|
85
|
+
"endColumn": 37,
|
|
86
|
+
"docs": "https://github.com/salamaashoush/barq/blob/main/packages/compiler/docs/BARQ001.md",
|
|
87
|
+
"skill": "node_modules/@barqjs/compiler/skills/compiler-diagnostics/SKILL.md#barq001",
|
|
88
|
+
"fix": [{ "pos": 221, "end": 221, "text": "()" }]
|
|
89
|
+
}
|
|
90
|
+
]
|
|
91
|
+
}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
`line` and `column` are 1-based. `skill` is the section of the installed repair
|
|
95
|
+
guide for the code. `fix` is present when the repair is one spelling: each edit
|
|
96
|
+
replaces the UTF-16 range `pos` to `end` of the file with `text`, and the two
|
|
97
|
+
are equal for an insertion.
|
|
98
|
+
|
|
99
|
+
### What `--fix` repairs
|
|
100
|
+
|
|
101
|
+
- `BARQ001`, `BARQ002`, `BARQ003`: an accessor used without being called gains
|
|
102
|
+
its call.
|
|
103
|
+
- `BARQ022`: `<Theme.Provider>` becomes `<Theme>`, in both tags.
|
|
104
|
+
- `BARQ023`: `classList` becomes `class`.
|
|
105
|
+
- `BARQ024`: `on:click` becomes `onClick`, and `attr:title` and `bool:disabled`
|
|
106
|
+
lose their prefix. An event name that is not one lowercase word, and the
|
|
107
|
+
`style:`, `class:` and `use:` namespaces, have no single spelling and are
|
|
108
|
+
left to you.
|
|
109
|
+
|
|
110
|
+
A fix can uncover another finding, so the file is compiled again after each
|
|
111
|
+
round, up to five rounds.
|
|
112
|
+
|
|
113
|
+
## `barq codes`
|
|
114
|
+
|
|
115
|
+
Lists every code the installed compiler can raise, with its default level and
|
|
116
|
+
one line on what it means. `--json` prints the list with each code's page and
|
|
117
|
+
guide section.
|
|
118
|
+
|
|
119
|
+
## From a program
|
|
120
|
+
|
|
121
|
+
```ts
|
|
122
|
+
import { check } from "@barqjs/cli";
|
|
123
|
+
|
|
124
|
+
const result = check({ root: process.cwd(), paths: ["src"] });
|
|
125
|
+
if (result.summary.errors > 0) process.exitCode = 1;
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
`check`, `codes`, `applyFixes`, `formatText` and `projectOptions` are exported, with the types of
|
|
129
|
+
what they take and return.
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
type Severity = "error" | "warning" | "note";
|
|
2
|
+
interface Edit {
|
|
3
|
+
/** UTF-16 offsets into the file as it was read. Equal for an insertion. */
|
|
4
|
+
pos: number;
|
|
5
|
+
end: number;
|
|
6
|
+
text: string;
|
|
7
|
+
}
|
|
8
|
+
interface Finding {
|
|
9
|
+
/** `BARQ001`, or absent for a syntax error, which is the parser's. */
|
|
10
|
+
code?: string;
|
|
11
|
+
severity: Severity;
|
|
12
|
+
message: string;
|
|
13
|
+
/** Relative to the root, with `/` separators. */
|
|
14
|
+
file: string;
|
|
15
|
+
line: number;
|
|
16
|
+
column: number;
|
|
17
|
+
endLine: number;
|
|
18
|
+
endColumn: number;
|
|
19
|
+
/** The page for the code. */
|
|
20
|
+
docs?: string;
|
|
21
|
+
/** The section of the installed repair guide for the code. */
|
|
22
|
+
skill?: string;
|
|
23
|
+
/** Present when `--fix` would repair it. */
|
|
24
|
+
fix?: Edit[];
|
|
25
|
+
}
|
|
26
|
+
interface CheckResult {
|
|
27
|
+
version: 1;
|
|
28
|
+
root: string;
|
|
29
|
+
files: number;
|
|
30
|
+
summary: {
|
|
31
|
+
errors: number;
|
|
32
|
+
warnings: number;
|
|
33
|
+
notes: number;
|
|
34
|
+
fixable: number;
|
|
35
|
+
fixed: number;
|
|
36
|
+
};
|
|
37
|
+
findings: Finding[];
|
|
38
|
+
}
|
|
39
|
+
interface CheckOptions {
|
|
40
|
+
/** The project root: paths in the result are relative to it. */
|
|
41
|
+
root: string;
|
|
42
|
+
/** Files and directories to check, relative to the root. Defaults to the root. */
|
|
43
|
+
paths?: readonly string[];
|
|
44
|
+
/** Apply the fixes the findings carry, and report what is left. */
|
|
45
|
+
fix?: boolean;
|
|
46
|
+
/** Per-code level, as `[code, "suppress" | "note" | "warning" | "error"]`. */
|
|
47
|
+
levels?: readonly (readonly [string, string])[];
|
|
48
|
+
/**
|
|
49
|
+
* The directory of file routes, relative to the root. When it exists, every
|
|
50
|
+
* `<Link to>` is checked against the routes in it and a route file whose id
|
|
51
|
+
* disagrees with its filename is reported.
|
|
52
|
+
* @default "src/routes"
|
|
53
|
+
*/
|
|
54
|
+
routes?: string;
|
|
55
|
+
/**
|
|
56
|
+
* Route patterns a link may name beside the file routes, such as those of a
|
|
57
|
+
* second router the application builds by hand.
|
|
58
|
+
*/
|
|
59
|
+
extraRoutes?: readonly string[];
|
|
60
|
+
}
|
|
61
|
+
/**
|
|
62
|
+
* What a project sets for every run, under `barq.check` in its `package.json`.
|
|
63
|
+
* A flag on the command line replaces the field of the same name.
|
|
64
|
+
*/
|
|
65
|
+
export declare function projectOptions(root: string): Partial<CheckOptions>;
|
|
66
|
+
/**
|
|
67
|
+
* `source` with every fix applied that does not touch another's span, and how
|
|
68
|
+
* many findings that repaired. Last edit first, so an offset stays valid.
|
|
69
|
+
*/
|
|
70
|
+
export declare function applyFixes(source: string, findings: readonly Finding[]): [string, number];
|
|
71
|
+
export declare function check(options: CheckOptions): CheckResult;
|
|
72
|
+
interface CodeEntry {
|
|
73
|
+
code: string;
|
|
74
|
+
level: string;
|
|
75
|
+
summary: string;
|
|
76
|
+
docs: string;
|
|
77
|
+
skill: string;
|
|
78
|
+
}
|
|
79
|
+
/** Every code the installed compiler can raise, with its default level. */
|
|
80
|
+
export declare function codes(): CodeEntry[];
|
|
81
|
+
interface Paint {
|
|
82
|
+
error(text: string): string;
|
|
83
|
+
warning(text: string): string;
|
|
84
|
+
note(text: string): string;
|
|
85
|
+
dim(text: string): string;
|
|
86
|
+
bold(text: string): string;
|
|
87
|
+
}
|
|
88
|
+
/** The result for a person: one finding per block, then the count. */
|
|
89
|
+
export declare function formatText(result: CheckResult, paint: Paint): string;
|
|
90
|
+
interface Parsed {
|
|
91
|
+
command: string | undefined;
|
|
92
|
+
paths: string[];
|
|
93
|
+
json: boolean;
|
|
94
|
+
fix: boolean;
|
|
95
|
+
root: string;
|
|
96
|
+
routes: string | undefined;
|
|
97
|
+
levels: [string, string][];
|
|
98
|
+
maxWarnings: number | undefined;
|
|
99
|
+
help: boolean;
|
|
100
|
+
}
|
|
101
|
+
export declare function parse(argv: readonly string[]): Parsed;
|
|
102
|
+
/** Run one command line and answer with the exit status. */
|
|
103
|
+
export declare function main(argv: readonly string[], write: (text: string) => void): number;
|
|
104
|
+
export type { CheckOptions, CheckResult, CodeEntry, Edit, Finding, Paint, Severity };
|