@intellectual-frontiers/lint 0.0.0-stage → 0.1.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.
- package/LICENSE +21 -0
- package/README.md +8 -2
- package/dist/plugin.d.ts +31 -0
- package/dist/plugin.js +19 -0
- package/dist/rule.d.ts +207 -0
- package/dist/rule.js +125 -0
- package/dist/rules/import-boundary.d.ts +7 -0
- package/dist/rules/import-boundary.js +64 -0
- package/dist/rules/module-doc.d.ts +3 -0
- package/dist/rules/module-doc.js +39 -0
- package/dist/rules/no-registry-import.d.ts +5 -0
- package/dist/rules/no-registry-import.js +46 -0
- package/dist/rules/no-vendor-api.d.ts +5 -0
- package/dist/rules/no-vendor-api.js +46 -0
- package/dist/rules/switch-absurd.d.ts +5 -0
- package/dist/rules/switch-absurd.js +72 -0
- package/dist/rules/terminal-writers.d.ts +10 -0
- package/dist/rules/terminal-writers.js +53 -0
- package/dist/test-rule.d.ts +32 -0
- package/dist/test-rule.js +100 -0
- package/package.json +50 -4
- package/src/plugin.ts +49 -0
- package/src/rule.ts +281 -0
- package/src/rules/import-boundary.ts +64 -0
- package/src/rules/module-doc.ts +43 -0
- package/src/rules/no-registry-import.ts +48 -0
- package/src/rules/no-vendor-api.ts +50 -0
- package/src/rules/switch-absurd.ts +71 -0
- package/src/rules/terminal-writers.ts +57 -0
- package/src/test-rule.ts +130 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Intellectual Frontiers
|
|
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,9 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @intellectual-frontiers/lint
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The lint plugin of Intellectual Frontiers in the ESLint plugin format that bun lint --plugin loads, with the rules every harness wants (no vendor API, no registry import, import boundaries, a module block in every file, absurd in every switch, no write to the terminal outside a list) and the typed way to define a rule of its own and to test it against the real linter.
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
bun add @intellectual-frontiers/lint # or: npm install @intellectual-frontiers/lint
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
Sources and specifications: https://github.com/intellectual-frontiers/.github/tree/main/commons/lint
|
package/dist/plugin.d.ts
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* IFC TypeScript's lint plugin in the ESLint plugin format (commons lint 0001-lint FR-001), named `ifc`, which `bun lint`
|
|
3
|
+
* loads from this file as it is (TypeScript, no build): `bun lint --plugin=<path to lint/plugin.ts> --rule '{"ifc/no-vendor-api":
|
|
4
|
+
* ["error", {...}]}'` for one run, or in `bunfig.toml`:
|
|
5
|
+
*
|
|
6
|
+
* ```toml
|
|
7
|
+
* [lint]
|
|
8
|
+
* plugins = ["./lint/plugin.ts"] # relative to bunfig.toml
|
|
9
|
+
*
|
|
10
|
+
* [lint.rules]
|
|
11
|
+
* "ifc/no-vendor-api" = ["error", { allow = [{ files = "src/host/**", reason = "the one module that wraps the vendor's API" }] }]
|
|
12
|
+
* "ifc/terminal-writers" = ["error", { allow = [{ files = "src/console.ts", reason = "the renderer, the one writer for a person" }] }]
|
|
13
|
+
* ```
|
|
14
|
+
*
|
|
15
|
+
* The rules every harness wants, each taking its lists from its options so that a harness keeps its own lists and adds its own rules
|
|
16
|
+
* (as its own plugin, with `defineRule` of `./rule.ts`):
|
|
17
|
+
* - `no-vendor-api`: no member of a vendor's global (`Bun.*` and the like) outside the files listed with their reasons;
|
|
18
|
+
* - `no-registry-import`: no `npm:`, `jsr:` or URL specifier;
|
|
19
|
+
* - `import-boundary`: a relative import that leaves its package (the option `roots`) is refused;
|
|
20
|
+
* - `module-doc`: every file begins with a JSDoc block that says `@module`;
|
|
21
|
+
* - `switch-absurd`: a `switch` on a union's `kind` ends in `default` calling `absurd`;
|
|
22
|
+
* - `terminal-writers`: no write to the terminal outside the files listed with their reasons.
|
|
23
|
+
*
|
|
24
|
+
* Spec: 0001-lint FR-001
|
|
25
|
+
*
|
|
26
|
+
* @module
|
|
27
|
+
*/
|
|
28
|
+
import type { Plugin } from "./rule.js";
|
|
29
|
+
/** The plugin: `ifc`, the prefix of its rules' ids, and its rules. */
|
|
30
|
+
declare const plugin: Plugin;
|
|
31
|
+
export default plugin;
|
package/dist/plugin.js
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import { importBoundary } from "./rules/import-boundary.js";
|
|
2
|
+
import { moduleDoc } from "./rules/module-doc.js";
|
|
3
|
+
import { noRegistryImport } from "./rules/no-registry-import.js";
|
|
4
|
+
import { noVendorApi } from "./rules/no-vendor-api.js";
|
|
5
|
+
import { switchAbsurd } from "./rules/switch-absurd.js";
|
|
6
|
+
import { terminalWriters } from "./rules/terminal-writers.js";
|
|
7
|
+
/** The plugin: `ifc`, the prefix of its rules' ids, and its rules. */
|
|
8
|
+
const plugin = {
|
|
9
|
+
meta: { name: "ifc", version: "0.5.0" },
|
|
10
|
+
rules: {
|
|
11
|
+
"no-vendor-api": noVendorApi,
|
|
12
|
+
"no-registry-import": noRegistryImport,
|
|
13
|
+
"import-boundary": importBoundary,
|
|
14
|
+
"module-doc": moduleDoc,
|
|
15
|
+
"switch-absurd": switchAbsurd,
|
|
16
|
+
"terminal-writers": terminalWriters,
|
|
17
|
+
},
|
|
18
|
+
};
|
|
19
|
+
export default plugin;
|
package/dist/rule.d.ts
ADDED
|
@@ -0,0 +1,207 @@
|
|
|
1
|
+
import { type Decoded, type Decoder, type Fields } from "@intellectual-frontiers/core";
|
|
2
|
+
/** Any node: its type, its offsets in the source (`range`), and its parent where the linter links them. */
|
|
3
|
+
export type Node = {
|
|
4
|
+
readonly type: string;
|
|
5
|
+
readonly range?: readonly [number, number];
|
|
6
|
+
readonly parent?: Node;
|
|
7
|
+
};
|
|
8
|
+
/** A name: `Bun`, `kind`. */
|
|
9
|
+
export type Identifier = Node & {
|
|
10
|
+
readonly type: "Identifier";
|
|
11
|
+
readonly name: string;
|
|
12
|
+
};
|
|
13
|
+
/** A literal: a string, a number, a boolean, `null` or a regular expression. */
|
|
14
|
+
export type Literal = Node & {
|
|
15
|
+
readonly type: "Literal";
|
|
16
|
+
readonly value: unknown;
|
|
17
|
+
};
|
|
18
|
+
/** `a.b` or `a[b]`. */
|
|
19
|
+
export type MemberExpression = Node & {
|
|
20
|
+
readonly type: "MemberExpression";
|
|
21
|
+
readonly object: Node;
|
|
22
|
+
readonly property: Node;
|
|
23
|
+
readonly computed: boolean;
|
|
24
|
+
};
|
|
25
|
+
/** `f(x)`. */
|
|
26
|
+
export type CallExpression = Node & {
|
|
27
|
+
readonly type: "CallExpression";
|
|
28
|
+
readonly callee: Node;
|
|
29
|
+
readonly arguments: readonly Node[];
|
|
30
|
+
};
|
|
31
|
+
/** `import ... from "x"`. */
|
|
32
|
+
export type ImportDeclaration = Node & {
|
|
33
|
+
readonly type: "ImportDeclaration";
|
|
34
|
+
readonly source: Literal;
|
|
35
|
+
readonly specifiers: readonly Node[];
|
|
36
|
+
};
|
|
37
|
+
/** `export * from "x"`. */
|
|
38
|
+
export type ExportAllDeclaration = Node & {
|
|
39
|
+
readonly type: "ExportAllDeclaration";
|
|
40
|
+
readonly source: Literal;
|
|
41
|
+
};
|
|
42
|
+
/** `export { a } from "x"`, or `export { a }` (no source). */
|
|
43
|
+
export type ExportNamedDeclaration = Node & {
|
|
44
|
+
readonly type: "ExportNamedDeclaration";
|
|
45
|
+
readonly source: Literal | null;
|
|
46
|
+
};
|
|
47
|
+
/** `import("x")`. */
|
|
48
|
+
export type ImportExpression = Node & {
|
|
49
|
+
readonly type: "ImportExpression";
|
|
50
|
+
readonly source: Node;
|
|
51
|
+
};
|
|
52
|
+
/** `typeof import("x")` in a type. */
|
|
53
|
+
export type TSImportType = Node & {
|
|
54
|
+
readonly type: "TSImportType";
|
|
55
|
+
readonly source?: Node;
|
|
56
|
+
readonly argument?: Node;
|
|
57
|
+
};
|
|
58
|
+
/** `import x = require("x")`'s reference. */
|
|
59
|
+
export type TSExternalModuleReference = Node & {
|
|
60
|
+
readonly type: "TSExternalModuleReference";
|
|
61
|
+
readonly expression: Node;
|
|
62
|
+
};
|
|
63
|
+
/** `A.B` in a type. */
|
|
64
|
+
export type TSQualifiedName = Node & {
|
|
65
|
+
readonly type: "TSQualifiedName";
|
|
66
|
+
readonly left: Node;
|
|
67
|
+
readonly right: Node;
|
|
68
|
+
};
|
|
69
|
+
/** One `case` (or `default`, whose `test` is null) of a switch. */
|
|
70
|
+
export type SwitchCase = Node & {
|
|
71
|
+
readonly type: "SwitchCase";
|
|
72
|
+
readonly test: Node | null;
|
|
73
|
+
readonly consequent: readonly Node[];
|
|
74
|
+
};
|
|
75
|
+
/** `switch (d) { ... }`. */
|
|
76
|
+
export type SwitchStatement = Node & {
|
|
77
|
+
readonly type: "SwitchStatement";
|
|
78
|
+
readonly discriminant: Node;
|
|
79
|
+
readonly cases: readonly SwitchCase[];
|
|
80
|
+
};
|
|
81
|
+
/** The whole file. */
|
|
82
|
+
export type Program = Node & {
|
|
83
|
+
readonly type: "Program";
|
|
84
|
+
readonly body: readonly Node[];
|
|
85
|
+
};
|
|
86
|
+
/** `debugger;`. */
|
|
87
|
+
export type DebuggerStatement = Node & {
|
|
88
|
+
readonly type: "DebuggerStatement";
|
|
89
|
+
};
|
|
90
|
+
/** The nodes a visitor may name, by type. */
|
|
91
|
+
export type Nodes = {
|
|
92
|
+
readonly Program: Program;
|
|
93
|
+
readonly Identifier: Identifier;
|
|
94
|
+
readonly MemberExpression: MemberExpression;
|
|
95
|
+
readonly CallExpression: CallExpression;
|
|
96
|
+
readonly ImportDeclaration: ImportDeclaration;
|
|
97
|
+
readonly ExportAllDeclaration: ExportAllDeclaration;
|
|
98
|
+
readonly ExportNamedDeclaration: ExportNamedDeclaration;
|
|
99
|
+
readonly ImportExpression: ImportExpression;
|
|
100
|
+
readonly TSImportType: TSImportType;
|
|
101
|
+
readonly TSExternalModuleReference: TSExternalModuleReference;
|
|
102
|
+
readonly TSQualifiedName: TSQualifiedName;
|
|
103
|
+
readonly SwitchStatement: SwitchStatement;
|
|
104
|
+
readonly DebuggerStatement: DebuggerStatement;
|
|
105
|
+
};
|
|
106
|
+
/** What a rule does on each node of a type, as the linter walks the file. */
|
|
107
|
+
export type Visitor = {
|
|
108
|
+
readonly [K in keyof Nodes]?: (node: Nodes[K]) => void;
|
|
109
|
+
};
|
|
110
|
+
/** A comment: `Line` (`//`), `Block` (between `/*` and its end; its `value` starts with `*` for a JSDoc block) or the file's `Shebang`. */
|
|
111
|
+
export type Comment = {
|
|
112
|
+
readonly type: "Line" | "Block" | "Shebang";
|
|
113
|
+
readonly value: string;
|
|
114
|
+
readonly range: readonly [number, number];
|
|
115
|
+
};
|
|
116
|
+
/** A place in the source: the line from 1 and the column from 0. */
|
|
117
|
+
export type Position = {
|
|
118
|
+
readonly line: number;
|
|
119
|
+
readonly column: number;
|
|
120
|
+
};
|
|
121
|
+
/** A problem a rule reports: at a node, or at a place. */
|
|
122
|
+
export type Report = {
|
|
123
|
+
readonly node: Node;
|
|
124
|
+
readonly message: string;
|
|
125
|
+
} | {
|
|
126
|
+
readonly loc: Position;
|
|
127
|
+
readonly message: string;
|
|
128
|
+
};
|
|
129
|
+
/** What a rule is given for each file, as ESLint gives it. */
|
|
130
|
+
export type RuleContext = {
|
|
131
|
+
/** The rule's id with its plugin's prefix: `ifc/no-vendor-api`. */
|
|
132
|
+
readonly id: string;
|
|
133
|
+
/** The file's absolute path. */
|
|
134
|
+
readonly filename: string;
|
|
135
|
+
/** The linter's working folder. */
|
|
136
|
+
readonly cwd: string;
|
|
137
|
+
/** The rule's options: what follows the severity in its setting. */
|
|
138
|
+
readonly options: readonly unknown[];
|
|
139
|
+
readonly sourceCode: {
|
|
140
|
+
readonly text: string;
|
|
141
|
+
readonly getAllComments: () => readonly Comment[];
|
|
142
|
+
};
|
|
143
|
+
readonly report: (report: Report) => void;
|
|
144
|
+
};
|
|
145
|
+
/** A rule in ESLint's format. */
|
|
146
|
+
export type Rule = {
|
|
147
|
+
readonly meta: {
|
|
148
|
+
readonly type: "problem" | "suggestion";
|
|
149
|
+
readonly docs: {
|
|
150
|
+
readonly description: string;
|
|
151
|
+
};
|
|
152
|
+
/** `false`: the options are decoded by the rule itself (`defineRule`), not by a JSON schema. */
|
|
153
|
+
readonly schema: false;
|
|
154
|
+
};
|
|
155
|
+
readonly create: (context: RuleContext) => Visitor;
|
|
156
|
+
};
|
|
157
|
+
/** A plugin in ESLint's format: its name, which is the prefix of its rules' ids, and its rules. */
|
|
158
|
+
export type Plugin = {
|
|
159
|
+
readonly meta: {
|
|
160
|
+
readonly name: string;
|
|
161
|
+
readonly version?: string;
|
|
162
|
+
};
|
|
163
|
+
readonly rules: Readonly<Record<string, Rule>>;
|
|
164
|
+
};
|
|
165
|
+
/** A rule's options as decoded: each of the decoders' fields, absent where it was not given. */
|
|
166
|
+
export type OptionsOf<O extends Fields> = {
|
|
167
|
+
readonly [K in keyof O]?: Decoded<O[K]>;
|
|
168
|
+
};
|
|
169
|
+
/**
|
|
170
|
+
* A rule in ESLint's format from its description and the decoders of its optional options, and what it does with the options decoded
|
|
171
|
+
* (0001-lint FR-002). The options are the first after the severity, an object (absent is `{}`); options that do not decode are reported once, at
|
|
172
|
+
* the top of each file, and the rule does nothing else.
|
|
173
|
+
*/
|
|
174
|
+
export declare function defineRule<const O extends Fields>(spec: {
|
|
175
|
+
readonly description: string;
|
|
176
|
+
readonly type?: "problem" | "suggestion";
|
|
177
|
+
readonly options: O;
|
|
178
|
+
}, create: (context: RuleContext, options: OptionsOf<O>) => Visitor): Rule;
|
|
179
|
+
/** A file, or files by glob, allowed what a rule refuses elsewhere, with the reason. */
|
|
180
|
+
export type Allowed = {
|
|
181
|
+
readonly files: string;
|
|
182
|
+
readonly reason: string;
|
|
183
|
+
readonly pattern: RegExp;
|
|
184
|
+
};
|
|
185
|
+
/** One allowed entry: `{ files, reason }`, the glob read as `kernel/glob.ts` reads one, the reason not empty. */
|
|
186
|
+
export declare const allowed: Decoder<Allowed>;
|
|
187
|
+
/** A list of files, each with its reason, as a rule's option `allow` (0001-lint FR-002). */
|
|
188
|
+
export declare const allowList: Decoder<readonly Allowed[]>;
|
|
189
|
+
/** The file being linted, relative to the linter's working folder, with `/`. */
|
|
190
|
+
export declare function fileOf(context: RuleContext): string;
|
|
191
|
+
/** The entry of the list that allows the file, if any. */
|
|
192
|
+
export declare function allowedFor(list: readonly Allowed[] | undefined, file: string): Allowed | undefined;
|
|
193
|
+
/** Whether the node is the identifier, or any identifier where no name is given. */
|
|
194
|
+
export declare function isIdentifier(node: Node | null | undefined, name?: string): node is Identifier;
|
|
195
|
+
/** The string a node holds: a string literal, a template with no expression, or a type's string literal (`TSLiteralType`). */
|
|
196
|
+
export declare function stringOf(node: Node | null | undefined): string | undefined;
|
|
197
|
+
/** Whether a value is a node. */
|
|
198
|
+
export declare function isNode(value: unknown): value is Node;
|
|
199
|
+
/**
|
|
200
|
+
* The name a member expression's object and property give, `globalThis.` taken off the object: `Bun.file` is `["Bun",
|
|
201
|
+
* "file"]`, `globalThis.console.log` is `["console", "log"]`, `a["b"]` is `["a", "b"]`; undefined where either is not a name.
|
|
202
|
+
*/
|
|
203
|
+
export declare function nameOf(node: MemberExpression): readonly [string, string] | undefined;
|
|
204
|
+
/** The property a member expression names: `b` of `a.b` and of `a["b"]`. */
|
|
205
|
+
export declare function propertyOf(node: MemberExpression): string | undefined;
|
|
206
|
+
/** Whether a node is a member expression. */
|
|
207
|
+
export declare function isMember(node: Node | null | undefined): node is MemberExpression;
|
package/dist/rule.js
ADDED
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The typed way to define a lint rule in the ESLint plugin format that `bun lint --plugin` loads (commons lint 0001-lint
|
|
3
|
+
* FR-002): the few ESTree nodes the rules of `./rules/` read (as typescript-estree gives them to a plugin, written here, without
|
|
4
|
+
* `@types/eslint`), a rule's context, its visitor, `defineRule`, which decodes a rule's options once with the kernel's decoders and
|
|
5
|
+
* reports options that do not decode instead of running, and what the rules share: a list of files, each with its reason, by glob
|
|
6
|
+
* (`allowList`), the file being linted relative to the working folder (`fileOf`), and the names a node gives (`nameOf`, `stringOf`).
|
|
7
|
+
*
|
|
8
|
+
* A rule takes one options object, the second element of its setting: `"ifc/no-vendor-api" = ["error", { allow = [...] }]` in
|
|
9
|
+
* `bunfig.toml`'s `[lint.rules]`, or `--rule '{"ifc/no-vendor-api": ["error", {...}]}'`. Rules never get types: a JavaScript rule of
|
|
10
|
+
* `bun lint` has no `parserServices.program`.
|
|
11
|
+
*
|
|
12
|
+
* @example
|
|
13
|
+
* ```ts
|
|
14
|
+
* import { boolean } from "@intellectual-frontiers/core";
|
|
15
|
+
* import { defineRule } from "./rule.ts";
|
|
16
|
+
* export const noDebugger = defineRule({ description: "no debugger statement", options: { strict: boolean } }, (context, options) => ({
|
|
17
|
+
* DebuggerStatement: (node) => context.report({ node, message: options.strict === true ? "remove it" : "remove it, please" }),
|
|
18
|
+
* }));
|
|
19
|
+
* ```
|
|
20
|
+
*
|
|
21
|
+
* Spec: 0001-lint FR-002
|
|
22
|
+
*
|
|
23
|
+
* @module
|
|
24
|
+
*/
|
|
25
|
+
import { relative } from "node:path";
|
|
26
|
+
import { array, formatDecodeError, object, string, err, ok, } from "@intellectual-frontiers/core";
|
|
27
|
+
import { formatGlobError, globToRegExp } from "@intellectual-frontiers/formats/glob";
|
|
28
|
+
/**
|
|
29
|
+
* A rule in ESLint's format from its description and the decoders of its optional options, and what it does with the options decoded
|
|
30
|
+
* (0001-lint FR-002). The options are the first after the severity, an object (absent is `{}`); options that do not decode are reported once, at
|
|
31
|
+
* the top of each file, and the rule does nothing else.
|
|
32
|
+
*/
|
|
33
|
+
export function defineRule(spec, create) {
|
|
34
|
+
const decode = object({}, spec.options);
|
|
35
|
+
return {
|
|
36
|
+
meta: { type: spec.type ?? "problem", docs: { description: spec.description }, schema: false },
|
|
37
|
+
create: (context) => {
|
|
38
|
+
const given = context.options[0] ?? {};
|
|
39
|
+
const options = decode(given);
|
|
40
|
+
if (options.kind === "err") {
|
|
41
|
+
const message = `${context.id}: its options are not right: ${formatDecodeError(options.error)}`;
|
|
42
|
+
return { Program: () => context.report({ loc: { line: 1, column: 0 }, message }) };
|
|
43
|
+
}
|
|
44
|
+
return create(context, options.value);
|
|
45
|
+
},
|
|
46
|
+
};
|
|
47
|
+
}
|
|
48
|
+
const allowedEntry = object({ files: string, reason: string });
|
|
49
|
+
/** One allowed entry: `{ files, reason }`, the glob read as `kernel/glob.ts` reads one, the reason not empty. */
|
|
50
|
+
export const allowed = (input, path = "$") => {
|
|
51
|
+
const e = allowedEntry(input, path);
|
|
52
|
+
if (e.kind === "err")
|
|
53
|
+
return e;
|
|
54
|
+
const fail = (expected) => err({ kind: "decode", path, expected, found: JSON.stringify(input) });
|
|
55
|
+
if (e.value.reason.trim() === "")
|
|
56
|
+
return fail("an entry with its reason (`reason` is empty)");
|
|
57
|
+
const pattern = globToRegExp(e.value.files);
|
|
58
|
+
if (pattern.kind === "err")
|
|
59
|
+
return fail(`an entry whose files are a glob: ${formatGlobError(pattern.error)}`);
|
|
60
|
+
return ok({ files: e.value.files, reason: e.value.reason, pattern: pattern.value });
|
|
61
|
+
};
|
|
62
|
+
/** A list of files, each with its reason, as a rule's option `allow` (0001-lint FR-002). */
|
|
63
|
+
export const allowList = array(allowed);
|
|
64
|
+
/** The file being linted, relative to the linter's working folder, with `/`. */
|
|
65
|
+
export function fileOf(context) {
|
|
66
|
+
return relative(context.cwd, context.filename).replaceAll("\\", "/");
|
|
67
|
+
}
|
|
68
|
+
/** The entry of the list that allows the file, if any. */
|
|
69
|
+
export function allowedFor(list, file) {
|
|
70
|
+
return list?.find((a) => a.pattern.test(file));
|
|
71
|
+
}
|
|
72
|
+
/** Whether the node is the identifier, or any identifier where no name is given. */
|
|
73
|
+
export function isIdentifier(node, name) {
|
|
74
|
+
return (node !== null &&
|
|
75
|
+
node !== undefined &&
|
|
76
|
+
node.type === "Identifier" &&
|
|
77
|
+
"name" in node &&
|
|
78
|
+
typeof node.name === "string" &&
|
|
79
|
+
(name === undefined || node.name === name));
|
|
80
|
+
}
|
|
81
|
+
/** The string a node holds: a string literal, a template with no expression, or a type's string literal (`TSLiteralType`). */
|
|
82
|
+
export function stringOf(node) {
|
|
83
|
+
if (node === null || node === undefined)
|
|
84
|
+
return undefined;
|
|
85
|
+
if (node.type === "Literal" && "value" in node)
|
|
86
|
+
return typeof node.value === "string" ? node.value : undefined;
|
|
87
|
+
if (node.type === "TSLiteralType" && "literal" in node && isNode(node.literal))
|
|
88
|
+
return stringOf(node.literal);
|
|
89
|
+
if (node.type === "TemplateLiteral" && "quasis" in node && "expressions" in node && Array.isArray(node.expressions)) {
|
|
90
|
+
const quasis = node.quasis;
|
|
91
|
+
if (node.expressions.length !== 0 || !Array.isArray(quasis))
|
|
92
|
+
return undefined;
|
|
93
|
+
const first = quasis[0];
|
|
94
|
+
if (typeof first !== "object" || first === null || !("value" in first))
|
|
95
|
+
return undefined;
|
|
96
|
+
const value = first.value;
|
|
97
|
+
return typeof value === "object" && value !== null && "cooked" in value && typeof value.cooked === "string" ? value.cooked : undefined;
|
|
98
|
+
}
|
|
99
|
+
return undefined;
|
|
100
|
+
}
|
|
101
|
+
/** Whether a value is a node. */
|
|
102
|
+
export function isNode(value) {
|
|
103
|
+
return typeof value === "object" && value !== null && "type" in value && typeof value.type === "string";
|
|
104
|
+
}
|
|
105
|
+
/**
|
|
106
|
+
* The name a member expression's object and property give, `globalThis.` taken off the object: `Bun.file` is `["Bun",
|
|
107
|
+
* "file"]`, `globalThis.console.log` is `["console", "log"]`, `a["b"]` is `["a", "b"]`; undefined where either is not a name.
|
|
108
|
+
*/
|
|
109
|
+
export function nameOf(node) {
|
|
110
|
+
const object = isIdentifier(node.object)
|
|
111
|
+
? node.object.name
|
|
112
|
+
: isMember(node.object) && isIdentifier(node.object.object, "globalThis")
|
|
113
|
+
? propertyOf(node.object)
|
|
114
|
+
: undefined;
|
|
115
|
+
const property = propertyOf(node);
|
|
116
|
+
return object === undefined || property === undefined ? undefined : [object, property];
|
|
117
|
+
}
|
|
118
|
+
/** The property a member expression names: `b` of `a.b` and of `a["b"]`. */
|
|
119
|
+
export function propertyOf(node) {
|
|
120
|
+
return node.computed ? stringOf(node.property) : isIdentifier(node.property) ? node.property.name : undefined;
|
|
121
|
+
}
|
|
122
|
+
/** Whether a node is a member expression. */
|
|
123
|
+
export function isMember(node) {
|
|
124
|
+
return (node !== null && node !== undefined && node.type === "MemberExpression" && "object" in node && isNode(node.object) && "property" in node);
|
|
125
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import { type Rule } from "../rule.js";
|
|
2
|
+
/** The folder of `file` that is its package: the longest of `roots` whose segments match its leading folders; undefined where none does. */
|
|
3
|
+
export declare function packageOf(file: string, roots: readonly string[]): string | undefined;
|
|
4
|
+
/** Where a relative specifier lands from `file`, as a `/` path relative to the same folder as `file` (`../` where it leaves it). */
|
|
5
|
+
export declare function landing(file: string, specifier: string): string;
|
|
6
|
+
/** The rule. */
|
|
7
|
+
export declare const importBoundary: Rule;
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `import-boundary` (commons lint 0001-lint FR-005): a relative import that leaves its package is refused; another package is
|
|
3
|
+
* imported by its name. The packages are the option `roots`, folders relative to the linter's working folder, each a glob of whole
|
|
4
|
+
* segments (`kernel`, `packages/*`, `lib/ts/*`); a file's package is the longest root it is in, and a file in none is not checked.
|
|
5
|
+
*
|
|
6
|
+
* Options: `roots` (the package and member folders) and `allow` (`[{ files, reason }]`).
|
|
7
|
+
*
|
|
8
|
+
* Spec: 0001-lint FR-005
|
|
9
|
+
*
|
|
10
|
+
* @module
|
|
11
|
+
*/
|
|
12
|
+
import { posix } from "node:path";
|
|
13
|
+
import { array, string } from "@intellectual-frontiers/core";
|
|
14
|
+
import { globToRegExp } from "@intellectual-frontiers/formats/glob";
|
|
15
|
+
import { allowedFor, allowList, defineRule, fileOf, isIdentifier, stringOf } from "../rule.js";
|
|
16
|
+
/** The folder of `file` that is its package: the longest of `roots` whose segments match its leading folders; undefined where none does. */
|
|
17
|
+
export function packageOf(file, roots) {
|
|
18
|
+
const folders = file.split("/").slice(0, -1);
|
|
19
|
+
let best;
|
|
20
|
+
for (const root of roots) {
|
|
21
|
+
const n = root.split("/").filter((s) => s !== "" && s !== ".").length;
|
|
22
|
+
if (n === 0 || n > folders.length)
|
|
23
|
+
continue;
|
|
24
|
+
const head = folders.slice(0, n).join("/");
|
|
25
|
+
const re = globToRegExp(root);
|
|
26
|
+
if (re.kind === "ok" && re.value.test(head) && (best === undefined || head.length > best.length))
|
|
27
|
+
best = head;
|
|
28
|
+
}
|
|
29
|
+
return best;
|
|
30
|
+
}
|
|
31
|
+
/** Where a relative specifier lands from `file`, as a `/` path relative to the same folder as `file` (`../` where it leaves it). */
|
|
32
|
+
export function landing(file, specifier) {
|
|
33
|
+
return posix.normalize(posix.join(posix.dirname(file), specifier));
|
|
34
|
+
}
|
|
35
|
+
/** The rule. */
|
|
36
|
+
export const importBoundary = defineRule({
|
|
37
|
+
description: "a relative import stays in its package: import another package by its name",
|
|
38
|
+
options: { roots: array(string), allow: allowList },
|
|
39
|
+
}, (context, options) => {
|
|
40
|
+
const file = fileOf(context);
|
|
41
|
+
const own = packageOf(file, options.roots ?? []);
|
|
42
|
+
if (own === undefined || allowedFor(options.allow, file) !== undefined)
|
|
43
|
+
return {};
|
|
44
|
+
const check = (node, source) => {
|
|
45
|
+
const specifier = stringOf(source);
|
|
46
|
+
if (specifier === undefined || !(specifier.startsWith("./") || specifier.startsWith("../")))
|
|
47
|
+
return;
|
|
48
|
+
const target = landing(file, specifier);
|
|
49
|
+
if (target.startsWith(`${own}/`))
|
|
50
|
+
return;
|
|
51
|
+
context.report({ node, message: `"${specifier}" leaves the package ${own}/: import the other package by its name` });
|
|
52
|
+
};
|
|
53
|
+
return {
|
|
54
|
+
ImportDeclaration: (node) => check(node, node.source),
|
|
55
|
+
ExportAllDeclaration: (node) => check(node, node.source),
|
|
56
|
+
ExportNamedDeclaration: (node) => check(node, node.source),
|
|
57
|
+
ImportExpression: (node) => check(node, node.source),
|
|
58
|
+
TSImportType: (node) => check(node, node.source ?? node.argument),
|
|
59
|
+
CallExpression: (node) => {
|
|
60
|
+
if (isIdentifier(node.callee, "require"))
|
|
61
|
+
check(node, node.arguments[0]);
|
|
62
|
+
},
|
|
63
|
+
};
|
|
64
|
+
});
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `module-doc` (commons lint 0001-lint FR-006): a file begins with its module's documentation, a JSDoc block (`/** ... *\/`)
|
|
3
|
+
* that says `@module`, before any code and before any other comment (a shebang may come first).
|
|
4
|
+
*
|
|
5
|
+
* Options: `tag` (`@module` by default) and `allow` (`[{ files, reason }]`).
|
|
6
|
+
*
|
|
7
|
+
* Spec: 0001-lint FR-006
|
|
8
|
+
*
|
|
9
|
+
* @module
|
|
10
|
+
*/
|
|
11
|
+
import { string } from "@intellectual-frontiers/core";
|
|
12
|
+
import { allowedFor, allowList, defineRule, fileOf } from "../rule.js";
|
|
13
|
+
/** The rule. */
|
|
14
|
+
export const moduleDoc = defineRule({
|
|
15
|
+
description: "a file begins with a JSDoc block that says @module",
|
|
16
|
+
type: "suggestion",
|
|
17
|
+
options: { tag: string, allow: allowList },
|
|
18
|
+
}, (context, options) => {
|
|
19
|
+
if (allowedFor(options.allow, fileOf(context)) !== undefined)
|
|
20
|
+
return {};
|
|
21
|
+
const tag = options.tag ?? "@module";
|
|
22
|
+
return {
|
|
23
|
+
Program: (node) => {
|
|
24
|
+
const first = context.sourceCode.getAllComments().find((c) => c.type !== "Shebang");
|
|
25
|
+
const code = node.body[0]?.range?.[0] ?? Number.POSITIVE_INFINITY;
|
|
26
|
+
const documented = first !== undefined &&
|
|
27
|
+
first.type === "Block" &&
|
|
28
|
+
first.value.startsWith("*") &&
|
|
29
|
+
first.value.includes(tag) &&
|
|
30
|
+
first.range[1] <= code;
|
|
31
|
+
if (!documented) {
|
|
32
|
+
context.report({
|
|
33
|
+
loc: { line: 1, column: 0 },
|
|
34
|
+
message: `begin the file with its module's documentation: a /** ... */ block that says ${tag}, before any code or other comment`,
|
|
35
|
+
});
|
|
36
|
+
}
|
|
37
|
+
},
|
|
38
|
+
};
|
|
39
|
+
});
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `no-registry-import` (commons lint 0001-lint FR-004): no module specifier that names a registry or a URL (`npm:`, `jsr:`,
|
|
3
|
+
* `http:`, `https:` by default), in an import, an export, a dynamic `import()`, a type's `import()`, `import x = require()` or
|
|
4
|
+
* `require()`; a package is installed and imported by its bare name.
|
|
5
|
+
*
|
|
6
|
+
* Options: `prefixes` (the refused beginnings of a specifier) and `allow` (`[{ files, reason }]`).
|
|
7
|
+
*
|
|
8
|
+
* Spec: 0001-lint FR-004
|
|
9
|
+
*
|
|
10
|
+
* @module
|
|
11
|
+
*/
|
|
12
|
+
import { array, string } from "@intellectual-frontiers/core";
|
|
13
|
+
import { allowedFor, allowList, defineRule, fileOf, isIdentifier, stringOf } from "../rule.js";
|
|
14
|
+
/** The beginnings of a specifier the rule refuses where none are given. */
|
|
15
|
+
export const REGISTRY_PREFIXES = ["npm", "jsr", "http", "https"].map((scheme) => `${scheme}:`);
|
|
16
|
+
/** The rule. */
|
|
17
|
+
export const noRegistryImport = defineRule({
|
|
18
|
+
description: "no npm:, jsr: or URL module specifier: install the package and import it by its bare name",
|
|
19
|
+
options: { prefixes: array(string), allow: allowList },
|
|
20
|
+
}, (context, options) => {
|
|
21
|
+
if (allowedFor(options.allow, fileOf(context)) !== undefined)
|
|
22
|
+
return {};
|
|
23
|
+
const prefixes = options.prefixes ?? REGISTRY_PREFIXES;
|
|
24
|
+
const check = (node, source) => {
|
|
25
|
+
const specifier = stringOf(source);
|
|
26
|
+
const prefix = specifier === undefined ? undefined : prefixes.find((p) => specifier.toLowerCase().startsWith(p));
|
|
27
|
+
if (specifier === undefined || prefix === undefined)
|
|
28
|
+
return;
|
|
29
|
+
context.report({
|
|
30
|
+
node,
|
|
31
|
+
message: `"${specifier}" names a registry or a URL (${prefix}): install the package and import it by its bare name`,
|
|
32
|
+
});
|
|
33
|
+
};
|
|
34
|
+
return {
|
|
35
|
+
ImportDeclaration: (node) => check(node, node.source),
|
|
36
|
+
ExportAllDeclaration: (node) => check(node, node.source),
|
|
37
|
+
ExportNamedDeclaration: (node) => check(node, node.source),
|
|
38
|
+
ImportExpression: (node) => check(node, node.source),
|
|
39
|
+
TSImportType: (node) => check(node, node.source ?? node.argument),
|
|
40
|
+
TSExternalModuleReference: (node) => check(node, node.expression),
|
|
41
|
+
CallExpression: (node) => {
|
|
42
|
+
if (isIdentifier(node.callee, "require"))
|
|
43
|
+
check(node, node.arguments[0]);
|
|
44
|
+
},
|
|
45
|
+
};
|
|
46
|
+
});
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `no-vendor-api` (commons lint 0001-lint FR-003): no member of a vendor's global (`Deno.*`, `Bun.*` by default), in code or in
|
|
3
|
+
* a type, outside the files of the option `allow`, each with its reason; a harness keeps its own list.
|
|
4
|
+
*
|
|
5
|
+
* Options: `globals` (the vendor globals, `["Deno", "Bun"]` by default) and `allow` (`[{ files, reason }]`, globs relative to the
|
|
6
|
+
* linter's working folder).
|
|
7
|
+
*
|
|
8
|
+
* Spec: 0001-lint FR-003
|
|
9
|
+
*
|
|
10
|
+
* @module
|
|
11
|
+
*/
|
|
12
|
+
import { array, string } from "@intellectual-frontiers/core";
|
|
13
|
+
import { allowedFor, allowList, defineRule, fileOf, isIdentifier, isMember, nameOf, propertyOf } from "../rule.js";
|
|
14
|
+
/** The vendor globals the rule refuses where none are given. */
|
|
15
|
+
export const VENDOR_GLOBALS = ["Deno", "Bun"];
|
|
16
|
+
/** The rule. */
|
|
17
|
+
export const noVendorApi = defineRule({
|
|
18
|
+
description: "no member of a vendor's global (Deno, Bun) outside the files listed with their reasons",
|
|
19
|
+
options: { globals: array(string), allow: allowList },
|
|
20
|
+
}, (context, options) => {
|
|
21
|
+
if (allowedFor(options.allow, fileOf(context)) !== undefined)
|
|
22
|
+
return {};
|
|
23
|
+
const globals = options.globals ?? VENDOR_GLOBALS;
|
|
24
|
+
const refuse = (node, what, vendor) => context.report({
|
|
25
|
+
node,
|
|
26
|
+
message: `${what} is ${vendor}'s own API: use a node: builtin or the runtime, or list this file with its reason in allow`,
|
|
27
|
+
});
|
|
28
|
+
return {
|
|
29
|
+
MemberExpression: (node) => {
|
|
30
|
+
const name = nameOf(node);
|
|
31
|
+
if (name !== undefined && globals.includes(name[0])) {
|
|
32
|
+
refuse(node, `${name[0]}.${name[1]}`, name[0]);
|
|
33
|
+
return;
|
|
34
|
+
}
|
|
35
|
+
// `globalThis.Deno` itself, not as the object of a member (which the outer expression reports).
|
|
36
|
+
const vendor = isIdentifier(node.object, "globalThis") ? propertyOf(node) : undefined;
|
|
37
|
+
const outer = node.parent !== undefined && isMember(node.parent) && node.parent.object === node;
|
|
38
|
+
if (vendor !== undefined && globals.includes(vendor) && !outer)
|
|
39
|
+
refuse(node, `globalThis.${vendor}`, vendor);
|
|
40
|
+
},
|
|
41
|
+
TSQualifiedName: (node) => {
|
|
42
|
+
if (isIdentifier(node.left) && globals.includes(node.left.name) && isIdentifier(node.right))
|
|
43
|
+
refuse(node, `${node.left.name}.${node.right.name}`, node.left.name);
|
|
44
|
+
},
|
|
45
|
+
};
|
|
46
|
+
});
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import { type Node, type Rule } from "../rule.js";
|
|
2
|
+
/** Whether a statement of a `default` calls one of the functions: `f(x);`, `return f(x);`, `throw f(x);`, or in a block. */
|
|
3
|
+
export declare function callsOneOf(node: Node | null | undefined, functions: readonly string[]): boolean;
|
|
4
|
+
/** The rule. */
|
|
5
|
+
export declare const switchAbsurd: Rule;
|