IF Commons GitHub

rule

The typed way to define a lint rule in the ESLint plugin format that bun lint --plugin loads (commons lint 0001-lint FR-002): the few ESTree nodes the rules of ./rules/ read (as typescript-estree gives them to a plugin, written here, without @types/eslint), a rule's context, its visitor, defineRule, which decodes a rule's options once with the kernel's decoders and reports options that do not decode instead of running, and what the rules share: a list of files, each with its reason, by glob (allowList), the file being linted relative to the working folder (fileOf), and the names a node gives (nameOf, stringOf).

A rule takes one options object, the second element of its setting: "ifc/no-vendor-api" = ["error", { allow = [...] }] in bunfig.toml's [lint.rules], or --rule '{"ifc/no-vendor-api": ["error", {...}]}'. Rules never get types: a JavaScript rule of bun lint has no parserServices.program.

import { boolean } from "@intellectual-frontiers/core";
import { defineRule } from "./rule.ts";
export const noDebugger = defineRule({ description: "no debugger statement", options: { strict: boolean } }, (context, options) => ({
  DebuggerStatement: (node) => context.report({ node, message: options.strict === true ? "remove it" : "remove it, please" }),
}));

Spec: 0001-lint FR-002

Source: commons/lint/src/rule.ts

1 of 37 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

Nodetypeno test imports it
type Node = { readonly type: string; readonly range?: readonly [number, number]; readonly parent?: Node };

Any node: its type, its offsets in the source (range), and its parent where the linter links them.

Identifiertypeno test imports it
type Identifier = Node & { readonly type: "Identifier"; readonly name: string };

A name: Bun, kind.

Literaltypeno test imports it
type Literal = Node & { readonly type: "Literal"; readonly value: unknown };

A literal: a string, a number, a boolean, null or a regular expression.

MemberExpressiontypeno test imports it
type MemberExpression = Node & {
  readonly type: "MemberExpression";
  readonly object: Node;
  readonly property: Node;
  readonly computed: boolean;
};

a.b or a[b].

CallExpressiontypeno test imports it
type CallExpression = Node & { readonly type: "CallExpression"; readonly callee: Node; readonly arguments: readonly Node[] };

f(x).

ImportDeclarationtypeno test imports it
type ImportDeclaration = Node & {
  readonly type: "ImportDeclaration";
  readonly source: Literal;
  readonly specifiers: readonly Node[];
};

import ... from "x".

ExportAllDeclarationtypeno test imports it
type ExportAllDeclaration = Node & { readonly type: "ExportAllDeclaration"; readonly source: Literal };

export * from "x".

ExportNamedDeclarationtypeno test imports it
type ExportNamedDeclaration = Node & { readonly type: "ExportNamedDeclaration"; readonly source: Literal | null };

export { a } from "x", or export { a } (no source).

ImportExpressiontypeno test imports it
type ImportExpression = Node & { readonly type: "ImportExpression"; readonly source: Node };

import("x").

TSImportTypetypeno test imports it
type TSImportType = Node & { readonly type: "TSImportType"; readonly source?: Node; readonly argument?: Node };

typeof import("x") in a type.

TSExternalModuleReferencetypeno test imports it
type TSExternalModuleReference = Node & { readonly type: "TSExternalModuleReference"; readonly expression: Node };

import x = require("x")'s reference.

TSQualifiedNametypeno test imports it
type TSQualifiedName = Node & { readonly type: "TSQualifiedName"; readonly left: Node; readonly right: Node };

A.B in a type.

SwitchCasetypeno test imports it
type SwitchCase = Node & { readonly type: "SwitchCase"; readonly test: Node | null; readonly consequent: readonly Node[] };

One case (or default, whose test is null) of a switch.

SwitchStatementtypeno test imports it
type SwitchStatement = Node & {
  readonly type: "SwitchStatement";
  readonly discriminant: Node;
  readonly cases: readonly SwitchCase[];
};

switch (d) { ... }.

Programtypeno test imports it
type Program = Node & { readonly type: "Program"; readonly body: readonly Node[] };

The whole file.

DebuggerStatementtypeno test imports it
type DebuggerStatement = Node & { readonly type: "DebuggerStatement" };

debugger;.

Nodestypeno test imports it
type Nodes = { readonly Program: Program; readonly Identifier: Identifier; readonly MemberExpression: MemberExpres… (624 characters)
type Nodes = {
  readonly Program: Program;
  readonly Identifier: Identifier;
  readonly MemberExpression: MemberExpression;
  readonly CallExpression: CallExpression;
  readonly ImportDeclaration: ImportDeclaration;
  readonly ExportAllDeclaration: ExportAllDeclaration;
  readonly ExportNamedDeclaration: ExportNamedDeclaration;
  readonly ImportExpression: ImportExpression;
  readonly TSImportType: TSImportType;
  readonly TSExternalModuleReference: TSExternalModuleReference;
  readonly TSQualifiedName: TSQualifiedName;
  readonly SwitchStatement: SwitchStatement;
  readonly DebuggerStatement: DebuggerStatement;
};

The nodes a visitor may name, by type.

Visitortypeno test imports it
type Visitor = { readonly [K in keyof Nodes]?: (node: Nodes[K]) => void };

What a rule does on each node of a type, as the linter walks the file.

Commenttypeno test imports it
type Comment = { readonly type: "Line" | "Block" | "Shebang"; readonly value: string; readonly range: readonly [number, number] };

A comment: Line (//), Block (between /* and its end; its value starts with * for a JSDoc block) or the file's Shebang.

Positiontypeno test imports it
type Position = { readonly line: number; readonly column: number };

A place in the source: the line from 1 and the column from 0.

Reporttypeno test imports it
type Report = { readonly node: Node; readonly message: string } | { readonly loc: Position; readonly message: string };

A problem a rule reports: at a node, or at a place.

RuleContexttypeno test imports it
type RuleContext = { /** The rule's id with its plugin's prefix: `ifc/no-vendor-api`. */ readonly id: string; /** … (499 characters)
type RuleContext = {
  /** The rule's id with its plugin's prefix: `ifc/no-vendor-api`. */
  readonly id: string;
  /** The file's absolute path. */
  readonly filename: string;
  /** The linter's working folder. */
  readonly cwd: string;
  /** The rule's options: what follows the severity in its setting. */
  readonly options: readonly unknown[];
  readonly sourceCode: { readonly text: string; readonly getAllComments: () => readonly Comment[] };
  readonly report: (report: Report) => void;
};

What a rule is given for each file, as ESLint gives it.

Ruletype
type Rule = {
  readonly meta: {
    readonly type: "problem" | "suggestion";
    readonly docs: { readonly description: string };
    /** `false`: the options are decoded by the rule itself (`defineRule`), not by a JSON schema. */
    readonly schema: false;
  };
  readonly create: (context: RuleContext) => Visitor;
};

A rule in ESLint's format.

Imported by 9 tests of the run (1 passed, 0 failed): the library's results

Plugintypeno test imports it
type Plugin = {
  readonly meta: { readonly name: string; readonly version?: string };
  readonly rules: Readonly<Record<string, Rule>>;
};

A plugin in ESLint's format: its name, which is the prefix of its rules' ids, and its rules.

OptionsOftypeno test imports it
type OptionsOf<O extends Fields> = { readonly [K in keyof O]?: Decoded<O[K]> };

A rule's options as decoded: each of the decoders' fields, absent where it was not given.

defineRulefunctionno test imports it
function defineRule<const O extends Fields>(spec: { readonly description: string; readonly type?: "problem" | "suggestion" | undefined; readonly options: O; }, create: (context: RuleContext, options: OptionsOf<O>) => Visitor): Rule

A rule in ESLint's format from its description and the decoders of its optional options, and what it does with the options decoded (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 the top of each file, and the rule does nothing else.

Allowedtypeno test imports it
type Allowed = { readonly files: string; readonly reason: string; readonly pattern: RegExp };

A file, or files by glob, allowed what a rule refuses elsewhere, with the reason.

allowedconstno test imports it
const allowed: Decoder<Allowed>

One allowed entry: { files, reason }, the glob read as kernel/glob.ts reads one, the reason not empty.

allowListconstno test imports it
const allowList: Decoder<readonly Allowed[]>

A list of files, each with its reason, as a rule's option allow (0001-lint FR-002).

fileOffunctionno test imports it
function fileOf(context: RuleContext): string

The file being linted, relative to the linter's working folder, with /.

allowedForfunctionno test imports it
function allowedFor(list: readonly Allowed[] | undefined, file: string): Allowed | undefined

The entry of the list that allows the file, if any.

isIdentifierfunctionno test imports it
function isIdentifier(node: Node | null | undefined, name?: string | undefined): node is Identifier

Whether the node is the identifier, or any identifier where no name is given.

stringOffunctionno test imports it
function stringOf(node: Node | null | undefined): string | undefined

The string a node holds: a string literal, a template with no expression, or a type's string literal (TSLiteralType).

isNodefunctionno test imports it
function isNode(value: unknown): value is Node

Whether a value is a node.

nameOffunctionno test imports it
function nameOf(node: MemberExpression): readonly [string, string] | undefined

The name a member expression's object and property give, globalThis. taken off the object: Bun.file is ["Bun", "file"], globalThis.console.log is ["console", "log"], a["b"] is ["a", "b"]; undefined where either is not a name.

propertyOffunctionno test imports it
function propertyOf(node: MemberExpression): string | undefined

The property a member expression names: b of a.b and of a["b"].

isMemberfunctionno test imports it
function isMember(node: Node | null | undefined): node is MemberExpression

Whether a node is a member expression.

Titles, headings, exports, tables, columns and requirements. Esc closes.