[johnsoncodehk]

Summary

TSSLint v4 runs only on TypeScript 7.1. Rules get the TypeScript 7 AST (typescript/ast), plus the Program and Checker from typescript/sync. There is no TypeScript 5/6 code path and no compatibility layer. Framework files (.vue, .astro, .mdx, …) are linted through TypeScript 7.1's Content Mapper (tsconfig contentMappers) instead of Volar language plugins, so the tsconfig is the single source of truth. The CLI cache now decides what to re-lint from a dependency graph, the way tsc --incremental does, instead of splitting rules into syntactic and type-aware.

Published so far as 4.0.0-alpha.1 (npm dist-tag alpha). This branch is 38 commits ahead of that tag, including the result API change and the new cache.

Quick start

npm install @tsslint/cli@alpha @tsslint/config@alpha --save-dev   # TypeScript 7.1 comes with them
npx tsslint --project tsconfig.json

// tsconfig.json (framework files)
{
  "contentMappers": [
    { "package": "@vue/content-mapper", "extensions": [".vue"] }
  ]
}

// tsslint.config.ts
import { defineConfig, defineRule } from '@tsslint/config';

export default defineConfig({
  rules: {
    'no-debugger': defineRule(({ typescript: ts, file, report }) => {
      file.forEachChild(function visit(node): void {
        if (node.kind === ts.SyntaxKind.DebuggerStatement) {
          report('Debugger statement is not allowed.', node.getStart(file), node.getEnd());
        }
        node.forEachChild(visit);
      });
    }),
  },
});

Breaking changes

See docs/migration-v4.md for the full guide.

• TypeScript 7.1 is a direct dependency. Every package depends on typescript 7.1.0-beta (exact), separate from the typescript your project compiles with; the typescript peer dependency is gone. Diagnostics come from the TypeScript 7 checker and can differ from TypeScript 5/6 in edge cases.
• Node.js 22.15.0+ is required (was 22.6.0+). The cache tracks the modules a config imports with Module.registerHooks, added in 22.15.
• Rule context changed. typescript is now the typescript/ast module; program is a typescript/sync Program; checker is passed directly; ts.forEachChild(node, cb) becomes node.forEachChild(cb); ts.sys and friends are gone (use node:fs / node:path).
• Results use TypeScript 7.1 types. A report is a typescript/sync Diagnostic (pos, end, text) plus ruleId. withFix / withRefactor return TextEdit[] ({ pos, end, newText }). Plugin resolveDiagnostics / resolveCodeFixes receive the lint target ({ program, checker, file }) instead of the file.
• @tsslint/typescript-plugin and the VS Code extension are removed. TypeScript 7 has no tsserver plugin API, so v4 has no editor integration.
• importTSLintRules and fromTSLRules are removed. Both depend on the classic typescript API.
• --vue-project, --vue-vine-project, --mdx-project, --astro-project and --ts-macro-project are removed, together with the Volar dependencies. Declare contentMappers in the tsconfig instead; there is no replacement flag.
• --list-rules and Reporter.withoutCache() are removed. There is no syntactic / type-aware split left to list. Rules must only depend on the program; reads through fs, environment variables and the like are not tracked, and --force re-lints every file.
• Existing caches are discarded. The cache format is v11 (v3 shipped v2), so the first v4 run re-lints everything.
• @typescript-eslint/eslint-plugin does not load with typescript@7: its dependencies read the classic typescript API at module load. importESLintRules still works for ESLint core rules and plugins that don't import typescript.
• @tsslint/core API (only for embedders): createLinter takes ctx: { typescript: typeof import('typescript/ast') }, linter.lint takes { program, checker, file } instead of a file name, applyTextEdits works on strings, and linter.getTouchedFiles(fileName) is new.

Remaining work

• Move the typescript dependency from 7.1.0-beta to the stable 7.1 release once it is published.

Done

Engine

• @tsslint/types, @tsslint/core, @tsslint/config and @tsslint/cli are ported to the TypeScript 7.1 API (typescript/ast, typescript/sync).
• The CLI runs one TypeScript 7 API process and one snapshot holding every project of the run; projects share parsed files. --fix updates the snapshot after each write before the next pass.
• @tsslint/compat-eslint's lazy ESTree is ported to the TypeScript 7 AST.
• typescript is a direct dependency of every package; ESLint is declared as a peer (>=9.39.0 <10.0.0) where needed.

Content Mapper support

• Projects are loaded with runExternalCode, so mappers declared in the tsconfig run as part of loading the project; there is no flag to pass.
• Rules run on the transformed TypeScript (file.text) and report in its coordinates. Diagnostics are mapped back to the original file through the mapper's span map; those that only cover generated code are dropped.
• --fix applies a fix only when every edit maps exactly onto original text, and applies an edit once when a mapper copies the same code more than once.
• Rule reports inside the mapper's diagnostic directives (e.g. @vue-ignore, @vue-expect-error) are suppressed, and compiler diagnostics of mapped files are not mapped twice.

Volar removal

• The five framework flags, the Volar proxy language service, packages/cli/lib/languagePlugins.ts, fixtures/meta-frameworks and the languages plumbing in the cache are removed.
• packages/typescript-plugin and packages/vscode are removed.

Cache

Stored at os.tmpdir()/tsslint-cache/<tsslint version>/<typescript version>/<hash of tsconfig and config path>.cache.json, so a new TSSLint or TypeScript version starts cold. Format v11; any parse, shape or version mismatch is treated as a cold start, and writes go through a temp file and rename.

• A file is re-linted when it changes (mtime or size), when a file it imports or references changes its declaration emit, or when a file a rule read beyond its declarations (a declaration's body, the file's source or diagnostics, a checker query by position) changes its text.
• Declaration hashes are kept per export and per top-level declaration, and an importer is re-linted only when a name it imports reaches a change. Changes keep propagating through files whose own signature changes (e.g. re-exports).
• Everything is re-linted when compiler options, a tsconfig, the content mappers (including the nearest lockfile above each, so upgrading a mapper's dependencies counts), tsslint.config.ts or a module it imports, the set of program files, or anything under node_modules changes; also when the declaration signature of a script or UMD module changes, or what a declare global / declare module '...' block declares.
• Content-mapped files are compared by declaration signature like other files, so editing a function body in A.vue does not re-lint B.vue that imports it.
• Per-name hashes are 96-bit (base64url prefix of SHA-256) to keep the cache file small.

Docs

• docs/migration-v4.md: breaking changes, rule context mapping, flag → contentMappers, caching, ESLint interop, @tsslint/core API, framework projects.
• README: TypeScript 7 positioning, setup without a typescript install, caching, framework support, requirements.

CI and release

• CI runs on Node 24 against the TypeScript 7 test suite.
• The release workflow publishes non-master branches under the alpha dist-tag (4.0.0-alpha.0, 4.0.0-alpha.1).

Tests

All CI steps pass at 2290a30 (PR CI green; also run locally on Node 24.15.0, typescript 7.1.0-beta):

• compat-eslint parity bench: 97 rules × 33 files, clean parity; predicate coverage 152/152 ESTree types; lazy ESTree, review-bug, predicate/materializer, compat-pipeline, selector-analysis and TS-AST scan tests.
• CLI: cache, cache-flow, invalidation (stubbed API), integration (subprocess, including a stub content mapper for .vue) and render tests.
• pnpm run lint --force on the repo itself: 53 passed.

Notes

• Rules can no longer read the typescript your project uses; anything they need from TypeScript comes from typescript/ast and the Program / Checker they are given.
• The cache only tracks what rules read through the program. A rule that reads files directly needs --force.
• tsslint.config.ts is loaded with --experimental-strip-types, unchanged from v3.

pnpm install && pnpm run build && pnpm run lint

References

• Content Mapper: Content mappers microsoft/typescript-go#4712 (merged)
• Migration guide: docs/migration-v4.md
• Caching: README.md#caching, packages/cli/lib/invalidation.ts

[johnsoncodehk]

/release alpha 4.0.0

[github-actions]

Alpha release failed, see https://github.com/johnsoncodehk/tsslint/actions/runs/39767990607

[johnsoncodehk]

/release alpha 4.0.0

[github-actions]

Alpha release failed, see https://github.com/johnsoncodehk/tsslint/actions/runs/39770287974

[johnsoncodehk]

/release alpha 4.0.0

[github-actions]

Alpha release failed, see https://github.com/johnsoncodehk/tsslint/actions/runs/39771220489

[johnsoncodehk]

/release alpha 4.0.0

[github-actions]

Published 4.0.0-alpha.0 (dist-tag alpha) from f7d6918:

• @tsslint/cli@4.0.0-alpha.0
• @tsslint/compat-eslint@4.0.0-alpha.0
• @tsslint/config@4.0.0-alpha.0
• @tsslint/core@4.0.0-alpha.0
• @tsslint/types@4.0.0-alpha.0