tsgolint

Rules in tsgolint are implemented using a visitor pattern. Instead of traversing the entire tree manually, each rule registers listeners for specific TypeScript AST (Abstract Syntax Tree) node types. When the linter encounters a registered node type, it executes the corresponding check function. Rules can also access the TypeScript checker to perform type-aware analysis.

func (r *Rule) Run(ctx RuleContext) RuleListeners {
    return RuleListeners{
        ast.FunctionDeclaration: r.checkFunction,
        ast.CallExpression: r.checkCall,
    }
}

tsgolint achieves high performance through several key architectural strategies:

• Direct AST Access: It uses typescript-go to access the TypeScript AST directly. This eliminates the overhead of converting TypeScript AST to other formats like ESTree.
• Parallel Processing: A worker pool utilizes all available CPU cores. Files and rules are distributed across these workers to execute in parallel.
• Shared State: TypeScript programs are shared across workers to minimize redundant work.
• Streaming Diagnostics: Diagnostics are collected and processed in real-time via a streaming model to improve memory efficiency and responsiveness.

Because tsgolint is built directly on TypeScript, its version numbers track the supported TypeScript version. The version format is v[TypeScript Version].[tsgolint Patch].

For example, v7.0.2001 means:

• 7.0.2 is the supported TypeScript version.
• 001 is the tsgolint patch version.

When the supported TypeScript version changes, the major/minor/patch components of the version number change, and the tsgolint patch suffix resets.

Oxlint uses a two-layer architecture to balance speed and depth of analysis:

1. Oxlint Layer: Handles syntax and structural analysis. This layer is nearly instant.
2. tsgolint Layer: Handles type-aware semantic rules. This layer requires TypeScript semantic analysis via typescript-go and is triggered when using the --type-aware flag.

Oxlint manages file discovery, configuration, and output formatting, while tsgolint executes the specific semantic rules and emits diagnostics.

tsgolint operates as a high-performance backend designed to integrate with the Oxlint CLI frontend. This separation of concerns allows Oxlint to manage user-facing tasks while tsgolint focuses on deep, type-aware analysis.

• Oxlint CLI (Frontend): Responsible for file discovery, reading configuration, output formatting, and rule orchestration.
• tsgolint (Backend): Responsible for executing type-aware rules, managing TypeScript integration, and generating diagnostics.

This architecture enables tsgolint to provide specialized TypeScript analysis without bloating the main Oxlint CLI logic.

To run benchmarks on your local machine, you must have the built tsgolint binary, Node.js with Corepack, and hyperfine installed. Follow these steps:

1. Clone the target repositories:

   ./clone-projects.sh

2. Install dependencies and configure ESLint:

   ./setup.sh

3. Execute the benchmark script:

   ./bench.sh

To use tsgolint for type-aware linting, you must install the oxlint-tsgolint package as a development dependency. tsgolint acts as the type-aware backend for Oxlint, enabling rules that require TypeScript semantic analysis.

pnpm add -D oxlint-tsgolint@latest

To set up and execute the cross-platform end-to-end tests for TSGoLint, navigate to the e2e directory, install dependencies using pnpm, and then run the test command.

Prerequisites

• pnpm installed on your system.
• Node.js environment.

Installation

cd e2e
pnpm install

Execution

pnpm test

To run benchmarks using a containerized environment, ensure you have already built the tsgolint binary (refer to the main README.md for build instructions) and have Docker or Podman installed. Use the following commands to build the container image:

docker build --file ./Containerfile --progress plain ..

# or

podman build --file ./Containerfile --progress plain ..