lint-staged 15.2.11 → 15.4.0

package/README.md

@@ -13,7 +13,7 @@ npm install --save-dev lint-staged # requires further setup
 ```
 $ git commit
 
-✔ Preparing lint-staged...
+✔ Backed up original state in git stash (5bda95f)
 ❯ Running tasks for staged files...
   ❯ packages/frontend/.lintstagedrc.json — 1 file
     ↓ *.js — no files [SKIPPED]
@@ -70,6 +70,9 @@ Now change a few files, `git add` or `git add --patch` some of them to your comm
 
 See [examples](#examples) and [configuration](#configuration) for more information.
 
+> [!CAUTION]  
+> _Lint-staged_ runs `git` operations affecting the files in your repository. By default _lint-staged_ creates a `git stash` as a backup of the original state before running any configured tasks to help prevent data loss.
+
 ## Changelog
 
 See [Releases](https://github.com/okonet/lint-staged/releases).
@@ -117,9 +120,10 @@ Options:
   -c, --config [path]                path to configuration file, or - to read from stdin
   --cwd [path]                       run all tasks in specific directory, instead of the current
   -d, --debug                        print additional debug information (default: false)
-  --diff [string]                    override the default "--staged" flag of "git diff" to get list of files. Implies
-                                     "--no-stash".
-  --diff-filter [string]             override the default "--diff-filter=ACMR" flag of "git diff" to get list of files
+  --diff [string]                    override the default "--staged" flag of "git diff" to get list of files.
+                                     Implies "--no-stash".
+  --diff-filter [string]             override the default "--diff-filter=ACMR" flag of "git diff" to get list of
+                                     files
   --max-arg-length [number]          maximum length of the command-line argument string (default: 0)
   --no-stash                         disable the backup stash, and do not revert in case of errors. Implies
                                      "--no-hide-partially-staged".
@@ -127,9 +131,15 @@ Options:
   -q, --quiet                        disable lint-staged’s own console output (default: false)
   -r, --relative                     pass relative filepaths to tasks (default: false)
   -x, --shell [path]                 skip parsing of tasks for better shell support (default: false)
-  -v, --verbose                      show task output even when tasks succeed; by default only failed output is shown
-                                     (default: false)
+  -v, --verbose                      show task output even when tasks succeed; by default only failed output is
+                                     shown (default: false)
   -h, --help                         display help for command
+
+Any lost modifications can be restored from a git stash:
+
+  > git stash list
+  stash@{0}: automatic lint-staged backup
+  > git stash apply --index stash@{0}
 ```
 
 - **`--allow-empty`**: By default, when linter tasks undo all staged changes, lint-staged will exit with an error and abort the commit. Use this flag to allow creating empty git commits.
@@ -198,6 +208,28 @@ So, considering you did `git add file1.ext file2.ext`, lint-staged will run the
 
 `your-cmd file1.ext file2.ext`
 
+### TypeScript
+
+_Lint-staged_ provides TypeScript types for the configuration and main Node.js API. You can use the JSDoc syntax in your JS configuration files:
+
+```js
+/**
+ * @filename: lint-staged.config.js
+ * @type {import('lint-staged').Configuration}
+ */
+export default {
+  '*': 'prettier --write',
+}
+```
+
+It's also possible to use the `.ts` file extension for the configuration if your Node.js version supports it. The `--experimental-strip-types` flag was introduced in [Node.js v22.6.0](https://github.com/nodejs/node/releases/tag/v22.6.0) and unflagged in [v23.6.0](https://github.com/nodejs/node/releases/tag/v23.6.0), enabling Node.js to execute TypeScript files without additional configuration.
+
+```shell
+export NODE_OPTIONS="--experimental-strip-types"
+
+npx lint-staged --config lint-staged.config.ts
+```
+
 ### Task concurrency
 
 By default _lint-staged_ will run configured tasks concurrently. This means that for every glob, all the commands will be started at the same time. With the following config, both `eslint` and `prettier` will run at the same time:

package/bin/lint-staged.js

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
 
-import fs from 'node:fs/promises'
+import { userInfo } from 'node:os'
 
 import { supportsColor } from 'chalk'
 import { Option, program } from 'commander'
 import debug from 'debug'
 
 import lintStaged from '../lib/index.js'
-import { CONFIG_STDIN_ERROR } from '../lib/messages.js'
+import { CONFIG_STDIN_ERROR, RESTORE_STASH_EXAMPLE } from '../lib/messages.js'
 import { readStdin } from '../lib/readStdin.js'
+import { getVersion } from '../lib/version.js'
 
 // Force colors for packages that depend on https://www.npmjs.com/package/supports-color
 if (supportsColor) {
@@ -20,45 +21,42 @@ const debugLog = debug('lint-staged:bin')
 // Do not terminate main Listr process on SIGINT
 process.on('SIGINT', () => {})
 
-const packageJson = JSON.parse(await fs.readFile(new URL('../package.json', import.meta.url)))
-const version = packageJson.version
+program.version(await getVersion())
 
-const cli = program.version(version)
+program.option('--allow-empty', 'allow empty commits when tasks revert all staged changes', false)
 
-cli.option('--allow-empty', 'allow empty commits when tasks revert all staged changes', false)
-
-cli.option(
+program.option(
   '-p, --concurrent <number|boolean>',
   'the number of tasks to run concurrently, or false for serial',
   true
 )
 
-cli.option('-c, --config [path]', 'path to configuration file, or - to read from stdin')
+program.option('-c, --config [path]', 'path to configuration file, or - to read from stdin')
 
-cli.option('--cwd [path]', 'run all tasks in specific directory, instead of the current')
+program.option('--cwd [path]', 'run all tasks in specific directory, instead of the current')
 
-cli.option('-d, --debug', 'print additional debug information', false)
+program.option('-d, --debug', 'print additional debug information', false)
 
-cli.addOption(
+program.addOption(
   new Option(
     '--diff [string]',
     'override the default "--staged" flag of "git diff" to get list of files. Implies "--no-stash".'
   ).implies({ stash: false })
 )
 
-cli.option(
+program.option(
   '--diff-filter [string]',
   'override the default "--diff-filter=ACMR" flag of "git diff" to get list of files'
 )
 
-cli.option('--max-arg-length [number]', 'maximum length of the command-line argument string', 0)
+program.option('--max-arg-length [number]', 'maximum length of the command-line argument string', 0)
 
 /**
  * We don't want to show the `--stash` flag because it's on by default, and only show the
  * negatable flag `--no-stash` in stead. There seems to be a bug in Commander.js where
  * configuring only the latter won't actually set the default value.
  */
-cli
+program
   .addOption(
     new Option('--stash', 'enable the backup stash, and revert in case of errors')
       .default(true)
@@ -78,7 +76,7 @@ cli
  * negatable flag `--no-hide-partially-staged` in stead. There seems to be a bug in Commander.js where
  * configuring only the latter won't actually set the default value.
  */
-cli
+program
   .addOption(
     new Option('--hide-partially-staged', 'hide unstaged changes from partially staged files')
       .default(true)
@@ -91,26 +89,26 @@ cli
     ).default(false)
   )
 
-cli.option('-q, --quiet', 'disable lint-staged’s own console output', false)
+program.option('-q, --quiet', 'disable lint-staged’s own console output', false)
 
-cli.option('-r, --relative', 'pass relative filepaths to tasks', false)
+program.option('-r, --relative', 'pass relative filepaths to tasks', false)
 
-cli.option('-x, --shell [path]', 'skip parsing of tasks for better shell support', false)
+program.option('-x, --shell [path]', 'skip parsing of tasks for better shell support', false)
 
-cli.option(
+program.option(
   '-v, --verbose',
   'show task output even when tasks succeed; by default only failed output is shown',
   false
 )
 
-const cliOptions = cli.parse(process.argv).opts()
+program.addHelpText('afterAll', '\n' + RESTORE_STASH_EXAMPLE)
+
+const cliOptions = program.parse(process.argv).opts()
 
 if (cliOptions.debug) {
   debug.enable('lint-staged*')
 }
 
-debugLog('Running `lint-staged@%s` on Node.js %s (%s)', version, process.version, process.platform)
-
 const options = {
   allowEmpty: !!cliOptions.allowEmpty,
   concurrent: JSON.parse(cliOptions.concurrent),
@@ -128,6 +126,13 @@ const options = {
   verbose: !!cliOptions.verbose,
 }
 
+try {
+  const { shell } = userInfo()
+  debugLog('Using shell: %s', shell)
+} catch {
+  debugLog('Could not determine current shell')
+}
+
 debugLog('Options parsed from command-line: %o', options)
 
 if (options.configPath === '-') {

package/lib/configFiles.js

@@ -16,9 +16,15 @@ export const CONFIG_FILE_NAMES = [
   '.lintstagedrc.yaml',
   '.lintstagedrc.yml',
   '.lintstagedrc.mjs',
+  '.lintstagedrc.mts',
   '.lintstagedrc.js',
+  '.lintstagedrc.ts',
   '.lintstagedrc.cjs',
+  '.lintstagedrc.cts',
   'lint-staged.config.mjs',
+  '.lint-staged.config.mts',
   'lint-staged.config.js',
+  '.lint-staged.config.ts',
   'lint-staged.config.cjs',
+  '.lint-staged.config.cts',
 ]

package/lib/gitWorkflow.js

@@ -98,7 +98,11 @@ export class GitWorkflow {
    */
   async getBackupStash(ctx) {
     const stashes = await this.execGit(['stash', 'list'])
-    const index = stashes.split('\n').findIndex((line) => line.includes(STASH))
+
+    const index = stashes
+      .split('\n')
+      .findIndex((line) => line.includes(STASH) && line.includes(ctx.backupHash))
+
     if (index === -1) {
       ctx.errors.add(GetBackupStashError)
       throw new Error('lint-staged automatic backup is missing!')
@@ -190,9 +194,9 @@ export class GitWorkflow {
   /**
    * Create a diff of partially staged files and backup stash if enabled.
    */
-  async prepare(ctx) {
+  async prepare(ctx, task) {
     try {
-      debugLog('Backing up original state...')
+      debugLog(task.title)
 
       // Get a list of files with bot staged and unstaged changes.
       // Unstaged changes to these files should be hidden before the tasks run.
@@ -223,10 +227,19 @@ export class GitWorkflow {
       // Save stash of all staged files.
       // The `stash create` command creates a dangling commit without removing any files,
       // and `stash store` saves it as an actual stash.
-      const hash = await this.execGit(['stash', 'create'])
-      await this.execGit(['stash', 'store', '--quiet', '--message', STASH, hash])
+      const stashHash = await this.execGit(['stash', 'create'])
+      ctx.backupHash = await this.execGit(['rev-parse', '--short', stashHash])
+      await this.execGit([
+        'stash',
+        'store',
+        '--quiet',
+        '--message',
+        `${STASH} (${ctx.backupHash})`,
+        ctx.backupHash,
+      ])
 
-      debugLog('Done backing up original state!')
+      task.title = `Backed up original state in git stash (${ctx.backupHash})`
+      debugLog(task.title)
     } catch (error) {
       handleError(error, ctx)
     }

package/lib/index.js

@@ -1,4 +1,4 @@
-import debug from 'debug'
+import debugLib from 'debug'
 
 import { execGit } from './execGit.js'
 import {
@@ -9,6 +9,7 @@ import {
 } from './messages.js'
 import { printTaskOutput } from './printTaskOutput.js'
 import { runAll } from './runAll.js'
+import { cleanupSkipped } from './state.js'
 import {
   ApplyEmptyCommitError,
   ConfigNotFoundError,
@@ -16,8 +17,9 @@ import {
   GitError,
 } from './symbols.js'
 import { validateOptions } from './validateOptions.js'
+import { getVersion } from './version.js'
 
-const debugLog = debug('lint-staged')
+const debugLog = debugLib('lint-staged')
 
 /**
  * Get the maximum length of a command-line argument string based on current platform
@@ -83,6 +85,18 @@ const lintStaged = async (
   } = {},
   logger = console
 ) => {
+  // Seemingly enable debug twice (also done in bin), so that it also works when using the Node.js API
+  if (debug) {
+    debugLib.enable('lint-staged*')
+
+    debugLog(
+      'Running `lint-staged@%s` on Node.js %s (%s)',
+      await getVersion(),
+      process.version,
+      process.platform
+    )
+  }
+
   const gitVersion = await execGit(['version', '--build-options'], { cwd })
   debugLog('%s', gitVersion)
 
@@ -123,11 +137,14 @@ const lintStaged = async (
         logger.error(NO_CONFIGURATION)
       } else if (ctx.errors.has(ApplyEmptyCommitError)) {
         logger.warn(PREVENTED_EMPTY_COMMIT)
-      } else if (ctx.errors.has(GitError) && !ctx.errors.has(GetBackupStashError)) {
+      } else if (
+        (ctx.errors.has(GitError) || cleanupSkipped(ctx)) &&
+        !ctx.errors.has(GetBackupStashError)
+      ) {
         logger.error(GIT_ERROR)
         if (ctx.shouldBackup) {
           // No sense to show this if the backup stash itself is missing.
-          logger.error(RESTORE_STASH_EXAMPLE)
+          logger.error(RESTORE_STASH_EXAMPLE + '\n')
         }
       }
 

package/lib/loadConfig.js

@@ -57,19 +57,21 @@ const NO_EXT = 'noExt'
  * assumption is in `cosmiconfig` as well.
  */
 const loaders = {
+  [NO_EXT]: yamlParse,
+  '.cjs': dynamicImport,
+  '.cts': dynamicImport,
   '.js': dynamicImport,
   '.json': jsonParse,
   '.mjs': dynamicImport,
-  '.cjs': dynamicImport,
+  '.mts': dynamicImport,
+  '.ts': dynamicImport,
   '.yaml': yamlParse,
   '.yml': yamlParse,
-  [NO_EXT]: yamlParse,
 }
 
 const readFile = async (filepath) => {
   const absolutePath = path.resolve(filepath)
-  const file = await fs.readFile(absolutePath)
-  return await file.toString()
+  return fs.readFile(absolutePath, 'utf-8')
 }
 
 const loadConfigByExt = async (filepath) => {

package/lib/messages.js

@@ -77,12 +77,11 @@ export const PREVENTED_EMPTY_COMMIT = `
   Use the --allow-empty option to continue, or check your task configuration`)}
 `
 
-export const RESTORE_STASH_EXAMPLE = `  Any lost modifications can be restored from a git stash:
+export const RESTORE_STASH_EXAMPLE = `Any lost modifications can be restored from a git stash:
 
-    > git stash list
-    stash@{0}: automatic lint-staged backup
-    > git stash apply --index stash@{0}
-`
+  > git stash list
+  stash@{0}: automatic lint-staged backup
+  > git stash apply --index stash@{0}`
 
 export const CONFIG_STDIN_ERROR = chalk.redBright(`${error} Failed to read config from stdin.`)
 

package/lib/runAll.js

@@ -291,8 +291,8 @@ export const runAll = async (
   const runner = new Listr(
     [
       {
-        title: 'Preparing lint-staged...',
-        task: (ctx) => git.prepare(ctx),
+        title: ctx.shouldBackup ? 'Backing up original state...' : 'Preparing lint-staged...',
+        task: (ctx, task) => git.prepare(ctx, task),
       },
       {
         title: 'Hiding unstaged changes to partially staged files...',

package/lib/state.js

@@ -12,6 +12,7 @@ import {
 export const getInitialState = ({ quiet = false } = {}) => ({
   hasPartiallyStagedFiles: null,
   shouldBackup: null,
+  backupHash: null,
   shouldHidePartiallyStaged: true,
   errors: new Set([]),
   events: new EventEmitter(),
@@ -40,6 +41,7 @@ export const restoreUnstagedChangesSkipped = (ctx) => {
   if (ctx.errors.has(GitError)) {
     return GIT_ERROR
   }
+
   // Should be skipped when tasks fail
   if (ctx.errors.has(TaskError)) {
     return TASK_ERROR
@@ -67,13 +69,10 @@ export const cleanupEnabled = (ctx) => ctx.shouldBackup
 
 export const cleanupSkipped = (ctx) => {
   // Should be skipped in case of unknown git errors
-  if (
-    ctx.errors.has(GitError) &&
-    !ctx.errors.has(ApplyEmptyCommitError) &&
-    !ctx.errors.has(RestoreUnstagedChangesError)
-  ) {
+  if (restoreOriginalStateSkipped(ctx)) {
     return GIT_ERROR
   }
+
   // Should be skipped when reverting to original state fails
   if (ctx.errors.has(RestoreOriginalStateError)) {
     return GIT_ERROR

package/lib/types.d.ts

@@ -0,0 +1,101 @@
+type SyncFunctionTask = (stagedFileNames: string[]) => string | string[]
+
+type AsyncFunctionTask = (stagedFileNames: string[]) => Promise<string | string[]>
+
+type FunctionTask = SyncFunctionTask | AsyncFunctionTask
+
+export type Configuration =
+  | Record<string, string | FunctionTask | (string | FunctionTask)[]>
+  | FunctionTask
+
+export type Options = {
+  /**
+   * Allow empty commits when tasks revert all staged changes
+   * @default false
+   */
+  allowEmpty?: boolean
+  /**
+   * The number of tasks to run concurrently, or `false` to run tasks serially
+   * @default true
+   */
+  concurrent?: boolean | number
+  /**
+   * Manual task configuration; disables automatic config file discovery when used
+   */
+  config?: Configuration
+  /**
+   * Path to single configuration file; disables automatic config file discovery when used
+   */
+  configPath?: string
+  /**
+   * Working directory to run all tasks in, defaults to current working directory
+   */
+  cwd?: string
+  /**
+   * Whether or not to enable debug output
+   * @default false
+   */
+  debug?: boolean
+  /**
+   * Override the default `--staged` flag of `git diff` to get list of files.
+   * @warn changing this also implies `stash: false`.
+   * @example HEAD...origin/main
+   */
+  diff?: string
+  /**
+   * Override the default `--diff-filter=ACMR` flag of `git diff` to get list of files
+   * @default "ACMR"
+   */
+  diffFilter?: string
+  /**
+   * Maximum argument string length, by default automatically detected
+   */
+  maxArgLength?: number
+  /**
+   * Disable lint-staged’s own console output
+   * @default false
+   */
+  quiet?: boolean
+  /**
+   * Pass filepaths relative to `CWD` to tasks, instead of absolute
+   * @default false
+   */
+  relative?: boolean
+  /**
+   * Skip parsing of tasks for better shell support
+   * @default false
+   */
+  shell?: boolean
+  /**
+   * Enable the backup stash, and revert in case of errors.
+   * @warn Disabling this also implies `hidePartiallyStaged: false`.
+   * @default true
+   */
+  stash?: boolean
+  /**
+   * Whether to hide unstaged changes from partially staged files before running tasks
+   * @default true
+   */
+  hidePartiallyStaged?: boolean
+  /**
+   * Show task output even when tasks succeed; by default only failed output is shown
+   * @default false
+   */
+  verbose?: boolean
+}
+
+type LogFunction = (...params: any) => void
+
+type Logger = {
+  log: LogFunction
+  warn: LogFunction
+  error: LogFunction
+}
+
+/**
+ * @returns {boolean} `true` when linting was successful, `false` when some tasks failed with errors
+ * @throws {Error} when failed to some other errors
+ */
+type lintStaged = (options: Options, logger?: Logger) => Promise<boolean>
+
+export default lintStaged

package/lib/version.js

@@ -0,0 +1,6 @@
+import fs from 'node:fs/promises'
+
+export const getVersion = async () => {
+  const packageJson = JSON.parse(await fs.readFile(new URL('../package.json', import.meta.url)))
+  return packageJson.version
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lint-staged",
-  "version": "15.2.11",
+  "version": "15.4.0",
   "description": "Lint files staged by git",
   "license": "MIT",
   "repository": "https://github.com/lint-staged/lint-staged",
@@ -23,6 +23,7 @@
     "./bin": "./bin/lint-staged.js",
     "./package.json": "./package.json"
   },
+  "types": "lib/types.d.ts",
   "files": [
     "bin",
     "lib"
@@ -31,12 +32,13 @@
     "lint": "eslint .",
     "test": "cross-env NODE_OPTIONS=--experimental-vm-modules npx jest --coverage",
     "test:watch": "npm run test -- --watch",
+    "typecheck": "tsc --noEmit --strict test/unit/types.ts",
     "version": "npx changeset version",
     "postversion": "npm i --package-lock-only && git commit -am \"chore(changeset): release\"",
     "tag": "npx changeset tag"
   },
   "dependencies": {
-    "chalk": "~5.3.0",
+    "chalk": "~5.4.1",
     "commander": "~12.1.0",
     "debug": "~4.4.0",
     "execa": "~8.0.1",
@@ -49,16 +51,16 @@
   },
   "devDependencies": {
     "@changesets/changelog-github": "0.5.0",
-    "@changesets/cli": "2.27.10",
-    "@commitlint/cli": "19.6.0",
+    "@changesets/cli": "2.27.11",
+    "@commitlint/cli": "19.6.1",
     "@commitlint/config-conventional": "19.6.0",
-    "@eslint/js": "9.16.0",
+    "@eslint/js": "9.17.0",
     "consolemock": "1.1.0",
     "cross-env": "7.0.3",
-    "eslint": "9.16.0",
+    "eslint": "9.17.0",
     "eslint-config-prettier": "9.1.0",
-    "eslint-plugin-jest": "28.9.0",
-    "eslint-plugin-n": "17.15.0",
+    "eslint-plugin-jest": "28.10.0",
+    "eslint-plugin-n": "17.15.1",
     "eslint-plugin-prettier": "5.2.1",
     "eslint-plugin-simple-import-sort": "12.1.1",
     "husky": "9.1.7",
@@ -66,7 +68,8 @@
     "jest-snapshot-serializer-ansi": "2.1.0",
     "mock-stdin": "1.0.0",
     "prettier": "3.4.2",
-    "semver": "7.6.3"
+    "semver": "7.6.3",
+    "typescript": "5.7.3"
   },
   "keywords": [
     "lint",