@ls-stack/fast-lint 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,186 @@
-# Temporary Holding Version
+# @ls-stack/fast-lint
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Type-aware lint rules running natively on [tsrs](https://github.com/maschwenk/tsrs), the Rust port of the TypeScript 7
+checker, through [tsrslint](https://github.com/maschwenk/tsrslint)'s rule framework. No ESLint, no Node type checker:
+only these rules run, against one shared program per tsconfig. Type-aware rules live here, not in
+[`@ls-stack/extended-lint`](../extended-lint).
+
+## Rules
+
+| rule | origin |
+| --- | --- |
+| `improved-no-unnecessary-condition` | moved from `@ls-stack/extended-lint` |
+| `strict-casting` | moved from `@ls-stack/extended-lint` (see below) |
+| `no-unnecessary-void-on-promise` | moved from `@ls-stack/extended-lint` |
+| `no-leaked-conditional-rendering` | port of `@eslint-react/no-leaked-conditional-rendering` (v2.3.13); option `reactVersion` (default `"19.0.0"`, also used for `""` and `"detect"`: the installed version isn't read) |
+
+Options are the same as the former ESLint rules' (see `lib/index.d.ts`). Rule names may carry a plugin prefix, so
+existing `@ls-stack/strict-casting` configs and disable comments keep working.
+
+### `strict-casting`
+
+Enforces safe and necessary `String()`/`Number()` casts.
+
+Checks performed:
+
+- **Unnecessary casts** (auto-fixable): casting a value that is already of the target type
+- **Nullish casts**: `String(value)` produces the strings `"null"`/`"undefined"`, and `Number(value)` produces `0` for `null` and `NaN` for `undefined`. A suggestion is provided to add a `?? ''`/`?? 0` fallback
+- **Invalid `Number()` casts**: casting a `symbol` (throws at runtime) or an object without a numeric `valueOf` (always results in `NaN`)
+- **`any`/`unknown` casts**: casting untyped values is unsafe, type or narrow the value before casting
+
+Bad:
+
+```ts
+declare const str: string
+declare const nullable: string | null
+declare const obj: { a: string }
+
+String(str) // Error: unnecessary cast
+String(nullable) // Error: may produce "null"
+Number(obj) // Error: results in NaN
+```
+
+Good:
+
+```ts
+String(num)
+String(nullable ?? '')
+Number(date) // Date has a numeric valueOf
+```
+
+Options:
+
+```ts
+type Options = [
+  {
+    /** Extra functions checked for unnecessary casts */
+    additionalCastFunctions?: { name: string; expectedType: 'string' | 'number' }[]
+    /** Allow casting possibly nullish values (default: false) */
+    allowNullishCasting?: boolean
+    /** Allow symbol/object Number() casts (default: false) */
+    allowInvalidCasting?: boolean
+    /** Allow casting `any` values (default: false) */
+    allowAnyCasting?: boolean
+    /** Allow casting `unknown` values, e.g. `String(err)` in catch blocks (default: false) */
+    allowUnknownCasting?: boolean
+  },
+]
+```
+
+For `String(obj)` producing `"[object Object]"`, use `@typescript-eslint/no-base-to-string`, which covers that case well.
+
+## Usage
+
+```sh
+fast-lint                      # every file of ./tsconfig.json
+fast-lint src/feature          # only files under these paths
+fast-lint --fix                # apply autofixes (strict-casting's unnecessary casts)
+fast-lint --format json        # stylish (default), compact or json, in ESLint's formats
+fast-lint --max-warnings 0 --timing   # --max-warnings -1: no limit
+fast-lint -p packages/app      # a tsconfig, or a directory with a tsconfig.json
+fast-lint --color -- -odd-name.ts     # force colors; `--` ends the options
+fast-lint --report-unused-disable-directives   # warn about fast-lint-disable comments that suppress nothing
+```
+
+A solution-style tsconfig (empty `files` plus `references`) lints its referenced projects; a file in several
+projects is linted once.
+
+Paths are printed relative to the current directory. A file with a syntax error gets a single `Parsing error`
+instead of rule diagnostics. `--quiet` hides warnings and doesn't apply their fixes; like ESLint, it skips `warn` rules
+entirely unless `--max-warnings` is given, in which case warnings still count. `--format json` prints ESLint's JSON
+result shape, listing only files with problems or fixes, with the file's `source` when it has problems and wasn't
+fixed.
+
+Exit code: `0` clean, `1` errors (or more warnings than `--max-warnings`), `2` fatal error: a tsconfig with a missing
+`files` entry or `extends` target, no files to lint, a path argument that matches no project file, a directory
+argument whose files are all ignored, or a fixed file that couldn't be written (reported after the results). A file
+argument that is ignored, a declaration file or in `node_modules` is skipped with a warning, and so is fixing a file
+that isn't UTF-8 (its problems are still reported).
+
+## Config
+
+`fast-lint.config.ts` (or `.mts`/`.mjs`/`.js`, evaluated by the Node launcher) or `fast-lint.config.json`, in the
+current directory or passed with `--config`. Without a config every rule runs as `error` with default options.
+
+```ts
+import { defineConfig } from '@ls-stack/fast-lint'
+
+export default defineConfig({
+  projects: ['tsconfig.json'],
+  ignores: ['dist/**'],
+  rules: {
+    'improved-no-unnecessary-condition': ['error', { alternativeForInCondition: 'use objectHasKey' }],
+    'strict-casting': ['warn', { additionalCastFunctions: [{ name: 'castToString', expectedType: 'string' }] }],
+    'no-unnecessary-void-on-promise': 'error',
+  },
+  overrides: [
+    {
+      files: ['src/**'],
+      ignores: ['**/*.test.ts'],
+      rules: { 'strict-casting': 'error', 'no-leaked-conditional-rendering': 'error' },
+    },
+  ],
+  reportUnusedDisableDirectives: true,
+})
+```
+
+Overrides apply in order, like ESLint flat config blocks: a severity-only entry keeps the options set by an earlier
+block. Globs are relative to the config file's directory (`../` for files outside it). Global `ignores` follow ESLint's
+semantics: a pattern matching a directory (`src/gen`, `**/out`, `dist/`, `dist/**`) ignores everything in it, and
+`!pattern` un-ignores files ignored by earlier patterns, but not files inside an ignored directory: to keep a file of
+an ignored directory, ignore its contents with `dir/**/*` instead. An override's `ignores` also accept `!pattern`,
+applied in order. Of the extglobs, only `@(a|b)` is supported (write the others with `{a,b}` or several globs). Rule
+names may carry a plugin prefix (`@ls-stack/strict-casting`), but not both forms of one rule in one block.
+
+A script config's default export must be the config object, or a promise of it.
+
+## Disable comments
+
+`eslint-disable`, `eslint-enable`, `eslint-disable-line` and `eslint-disable-next-line` comments (and their
+`oxlint-` and `fast-lint-` forms) are honored, with or without a rule list and a `-- description`, so existing
+directives such as `// eslint-disable-next-line @ls-stack/improved-no-unnecessary-condition` keep working. They are
+parsed like ESLint does: the comment text must start with the directive, `disable` and `enable` need a block comment
+(`/* */`), and a multi-line `disable-next-line` block comment applies to the line after the comment ends. Inline
+config comments (`/* eslint rule: "off" */`) are ignored.
+
+`--report-unused-disable-directives` (or `reportUnusedDisableDirectives: true` in the config) warns about
+`fast-lint-disable*` directives that suppressed nothing, like ESLint's option of the same name: a directive without a
+rule list when no problem was suppressed, else each listed rule that ran on the file and reported nothing there. Only
+`fast-lint-` directives are checked, since `eslint-` and `oxlint-` ones may belong to rules of those linters. The
+warnings have no rule id and no fix. Under `--quiet` they are hidden, and they aren't computed unless
+`--max-warnings` is given (warn rules don't run then, so their directives would look unused).
+
+### Running alongside ESLint
+
+When these rules are moved out of ESLint (set to `off` there, or their plugin removed), ESLint sees their
+`eslint-disable` comments as unused (`reportUnusedDisableDirectives`, a warning by default in ESLint 9), and
+`eslint --fix` deletes them, or as errors for an unknown rule when the plugin isn't loaded. Then fast-lint reports the
+problems again. Either write these rules' directives as `fast-lint-disable*` (or `oxlint-disable*`), which ESLint
+ignores, or set `linterOptions: { reportUnusedDisableDirectives: 'off' }` in the ESLint config, which also stops
+reporting directives that are unused for the remaining ESLint rules.
+
+## Differences from ESLint
+
+- `--fix` applies one pass of non-overlapping fixes (ESLint repeats up to 10 passes).
+- `improved-no-unnecessary-condition` reports nothing in a project without `strictNullChecks` (or `strict`), where
+  every type may be nullish.
+- Types come from tsrs (TypeScript 7.1-dev semantics); printed types in messages can differ slightly from TS 5.x.
+- Prebuilt binaries ship for macOS (arm64, x64), Linux (x64, arm64; glibc >= 2.17, not musl/Alpine) and Windows
+  x64 (also used on Windows arm64, through emulation). Elsewhere, set `FAST_LINT_BINARY` to a `cargo build --release`
+  binary. The launcher prints the package version for `--version`; the binary itself prints the crate version.
+
+## Development
+
+```sh
+cargo test                     # rule tests (tests/*.rs)
+cargo clippy --all-targets
+node scripts/build.mjs         # release binaries for every platform into dist/<platform>-<arch>/
+node scripts/build.mjs --clean linux-x64 win32-x64   # some platforms, deleting their build dirs afterwards
+```
+
+Cross-compiling from macOS needs the Rust targets (`rustup target add x86_64-apple-darwin
+x86_64-unknown-linux-gnu aarch64-unknown-linux-gnu x86_64-pc-windows-msvc`), `zig` + `cargo-zigbuild` for Linux, and
+`cargo-xwin` + Homebrew `llvm` (for `llvm-lib`) for Windows. Each platform takes about 2 minutes (fat LTO).
+
+The first build fetches tsrslint's git dependency, including its `typescript-go` submodule (~2 GB, cached in
+`~/.cargo/git`). tsrslint is pinned by commit in `Cargo.toml`; `Cargo.lock` pins the tsrs commit it was tested with.

package/bin/fast-lint.mjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { constants } from 'node:os'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const scriptConfigNames = [
+  'fast-lint.config.ts',
+  'fast-lint.config.mts',
+  'fast-lint.config.mjs',
+  'fast-lint.config.js',
+]
+
+const scriptConfigExtensions = ['.ts', '.mts', '.cts', '.mjs', '.cjs', '.js']
+
+function binaryPath() {
+  if (process.env.FAST_LINT_BINARY) return process.env.FAST_LINT_BINARY
+
+  const platform = `${process.platform}-${process.arch}`
+  const exe = process.platform === 'win32' ? 'fast-lint.exe' : 'fast-lint'
+  const candidates =
+    platform === 'win32-arm64' ? [platform, 'win32-x64'] : [platform]
+
+  for (const candidate of candidates) {
+    const path = fileURLToPath(
+      new URL(`../dist/${candidate}/${exe}`, import.meta.url),
+    )
+    if (existsSync(path)) return path
+  }
+
+  throw new Error(
+    `no prebuilt binary for ${platform}. Build one with \`cargo build --release\` in packages/fast-lint and point FAST_LINT_BINARY at it`,
+  )
+}
+
+function findConfigFlag(args) {
+  let found
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === undefined) continue
+
+    if (arg === '-c' || arg === '--config') {
+      found = { index: i, length: 2, path: args[i + 1] }
+      i++
+    } else if (arg.startsWith('--config=')) {
+      found = { index: i, length: 1, path: arg.slice('--config='.length) }
+    }
+  }
+
+  return found
+}
+
+function isScriptConfig(path) {
+  return scriptConfigExtensions.some((ext) => path.endsWith(ext))
+}
+
+async function loadScriptConfig(path) {
+  const module = await import(pathToFileURL(path).href)
+
+  if (!('default' in module)) {
+    throw new Error(`${path} has no default export`)
+  }
+
+  const config = await module.default
+
+  if (typeof config !== 'object' || config === null || Array.isArray(config)) {
+    throw new Error(
+      `${path}: the default export must be a config object or a promise of one`,
+    )
+  }
+
+  return JSON.stringify(config)
+}
+
+function hasInlineConfig(args) {
+  return args.some(
+    (arg) => arg === '--config-json' || arg.startsWith('--config-json='),
+  )
+}
+
+function packageVersion() {
+  const packageJson = JSON.parse(
+    readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+  )
+  return packageJson.version
+}
+
+async function resolveArgs(args) {
+  if (hasInlineConfig(args)) return args
+
+  const flag = findConfigFlag(args)
+
+  if (flag) {
+    if (!flag.path || !isScriptConfig(flag.path)) return args
+
+    const path = resolve(flag.path)
+    const rest = [...args]
+    rest.splice(flag.index, flag.length)
+
+    return [
+      ...rest,
+      '--config-json',
+      await loadScriptConfig(path),
+      '--config-root',
+      dirname(path),
+    ]
+  }
+
+  const found = scriptConfigNames
+    .map((name) => resolve(name))
+    .find((path) => existsSync(path))
+
+  if (!found) return args
+
+  return [
+    ...args,
+    '--config-json',
+    await loadScriptConfig(found),
+    '--config-root',
+    dirname(found),
+  ]
+}
+
+const rawArgs = process.argv.slice(2)
+
+if (rawArgs.includes('-v') || rawArgs.includes('--version')) {
+  console.log(packageVersion())
+  process.exit(0)
+}
+
+const isHelp = rawArgs.includes('-h') || rawArgs.includes('--help')
+
+let exe
+let args
+
+try {
+  exe = binaryPath()
+  args = isHelp ? rawArgs : await resolveArgs(rawArgs)
+} catch (error) {
+  console.error(
+    `fast-lint: ${error instanceof Error ? error.message : String(error)}`,
+  )
+  process.exit(2)
+}
+
+const child = spawn(exe, args, { stdio: 'inherit' })
+
+const signals = ['SIGINT', 'SIGTERM', 'SIGHUP']
+
+for (const signal of signals) {
+  process.on(signal, () => child.kill(signal))
+}
+
+child.on('error', (error) => {
+  const hint =
+    process.platform === 'linux' &&
+    !process.env.FAST_LINT_BINARY &&
+    'code' in error &&
+    error.code === 'ENOENT'
+      ? ' (the prebuilt Linux binaries need glibc >= 2.17; on musl/Alpine point FAST_LINT_BINARY at a binary built there)'
+      : ''
+  console.error(`fast-lint: failed to run ${exe}: ${error.message}${hint}`)
+  process.exit(2)
+})
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.exitCode = 128 + (constants.signals[signal] ?? 0)
+
+    if (signals.includes(signal)) {
+      process.removeAllListeners(signal)
+      process.kill(process.pid, signal)
+      return
+    }
+
+    process.exit()
+  }
+
+  process.exit(code ?? 2)
+})

package/lib/index.d.ts

@@ -0,0 +1,51 @@
+export type Severity = 'off' | 'warn' | 'error' | 0 | 1 | 2
+
+type RuleEntry<Options> = Severity | [Severity] | [Severity, Options]
+
+export type ImprovedNoUnnecessaryConditionOptions = {
+  alternativeForInCondition?: string
+}
+
+export type StrictCastingOptions = {
+  additionalCastFunctions?: {
+    name: string
+    expectedType: 'string' | 'number'
+  }[]
+  allowNullishCasting?: boolean
+  allowInvalidCasting?: boolean
+  allowAnyCasting?: boolean
+  allowUnknownCasting?: boolean
+}
+
+export type NoLeakedConditionalRenderingOptions = {
+  reactVersion?: string
+}
+
+type RuleOptions = {
+  'improved-no-unnecessary-condition': ImprovedNoUnnecessaryConditionOptions
+  'strict-casting': StrictCastingOptions
+  'no-unnecessary-void-on-promise': Record<string, never>
+  'no-leaked-conditional-rendering': NoLeakedConditionalRenderingOptions
+}
+
+export type RulesConfig = {
+  [Name in keyof RuleOptions as Name | `${string}/${Name}`]?: RuleEntry<
+    RuleOptions[Name]
+  >
+}
+
+export type Override = {
+  files: string[]
+  ignores?: string[]
+  rules?: RulesConfig
+}
+
+export type FastLintConfig = {
+  projects?: string[]
+  ignores?: string[]
+  rules?: RulesConfig
+  overrides?: Override[]
+  reportUnusedDisableDirectives?: boolean
+}
+
+export function defineConfig(config: FastLintConfig): FastLintConfig

package/lib/index.mjs

@@ -0,0 +1,3 @@
+export function defineConfig(config) {
+  return config
+}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@ls-stack/fast-lint",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "license": "MIT",
+  "description": "Type-aware lint rules of @ls-stack/extended-lint running natively on tsrs, the Rust port of the TypeScript checker",
+  "type": "module",
+  "bin": {
+    "fast-lint": "./bin/fast-lint.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.mjs"
+    }
+  },
+  "files": [
+    "bin",
+    "lib",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "github:lucaslos/eslint-plugin-extended-lint"
+  },
+  "author": "Lucas Santos",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "scripts": {
+    "test": "cargo test",
+    "lint": "cargo fmt --check && cargo clippy --all-targets -- -D warnings",
+    "build": "pnpm test && pnpm lint && pnpm run build:no-test",
+    "build:no-test": "node scripts/build.mjs",
+    "pre-publish": "pnpm build"
+  }
 }