chore: add stagedLint validations

Author: cab-mikee

bin/cli.ts

@@ -41,7 +41,7 @@ cli
       log.success('Successfully set all git hooks')
     }
     catch (err) {
-      log.error('Was not able to set git hooks. Error:', err)
+      log.error(err)
       process.exit(1)
     }
   })

docs/config.md

@@ -32,7 +32,7 @@ You can configure your git hooks using any of these file formats:
 import type { GitHooksConfig } from 'bun-git-hooks'
 
 const config: GitHooksConfig = {
-  // Git hook commands
+  // Note: staged-lint is only available in pre-commit hook
   'pre-commit': {
     'staged-lint': {
       '*.{js,ts}': 'bunx --bun eslint . --fix',
@@ -62,9 +62,7 @@ export default config
       }
     },
     "commit-msg": "bun commitlint --edit $1",
-    "pre-push": "bun run build",
-    "verbose": true,
-    "preserveUnused": false
+    "pre-push": "bun run build"
   }
 }
 ```
@@ -73,32 +71,26 @@ export default config
 
 ### Hook Commands
 
-Any valid git hook can be configured with either a command string or a staged-lint configuration:
+Any valid git hook can be configured with either a command string or a staged-lint configuration (pre-commit only):
 
 ```ts
 const config: GitHooksConfig = {
   // Simple command
   'pre-commit': 'bun run lint',
 
-  // Staged lint configuration
+  // Staged lint configuration (pre-commit only)
   'pre-commit': {
     'staged-lint': {
       '*.{js,ts}': 'bunx --bun eslint . --fix',
       '*.{css,scss}': 'stylelint --fix'
     }
-  },
-
-  // Global staged lint configuration
-  'staged-lint': {
-    '*.{js,ts}': 'bunx --bun eslint . --fix',
-    '*.{css,scss}': 'stylelint --fix'
   }
 }
 ```
 
 ### Staged Lint Configuration
 
-The `staged-lint` feature allows you to run specific commands on staged files matching certain patterns:
+The `staged-lint` feature is only available in the pre-commit hook. It allows you to run specific commands on staged files matching certain patterns:
 
 ```ts
 const config: GitHooksConfig = {
@@ -123,25 +115,6 @@ const config: GitHooksConfig = {
 }
 ```
 
-You can also use `staged-lint` as a top-level configuration to apply the same rules to all hooks:
-
-```ts
-const config: GitHooksConfig = {
-  // Global staged lint configuration
-  'staged-lint': {
-    '*.{js,ts}': 'bunx --bun eslint . --fix',
-    '*.{css,scss}': 'stylelint --fix'
-  },
-
-  // Hook-specific staged lint configuration (takes precedence)
-  'pre-commit': {
-    'staged-lint': {
-      '*.{js,ts}': 'bunx --bun eslint . --fix --max-warnings=0'
-    }
-  }
-}
-```
-
 ### Global Options
 
 | Option | Type | Default | Description |
@@ -219,4 +192,5 @@ If no configuration is found, an error will be thrown.
 4. **Preserve Critical Hooks**: Use `preserveUnused` for important custom hooks
 5. **Enable Verbose Mode**: When debugging hook issues
 6. **Use Exit Codes**: Hooks should exit with non-zero for failures
-7. **Use Staged Lint**: For efficient file-specific linting
+7. **Use Staged Lint**: For efficient file-specific linting (pre-commit only)
+8. **Follow Restrictions**: Remember that staged-lint is only available in pre-commit hook

docs/index.md

@@ -55,7 +55,12 @@ cat > git-hooks.config.ts << EOL
 import type { GitHooksConfig } from 'bun-git-hooks'
 
 const config: GitHooksConfig = {
-  'pre-commit': 'bun run lint && bun run test',
+  // Note: staged-lint is only available in pre-commit hook
+  'pre-commit': {
+    'staged-lint': {
+      '*.{js,ts}': 'bunx --bun eslint . --fix --max-warnings=0'
+    }
+  },
   'commit-msg': 'bun commitlint --edit $1',
   'pre-push': 'bun run build',
 }
@@ -74,6 +79,7 @@ EOL
 - 📦 **Zero Dependencies**: Minimal footprint in your project
 - ⚡ **Fast**: Built for Bun with performance in mind
 - 🔧 **Flexible**: Multiple configuration formats and options
+- 🚫 **Restricted Features**: Clear boundaries for features like staged-lint (pre-commit only)
 
 ## Configuration Options
 
@@ -95,8 +101,13 @@ EOL
 
 ```ts
 const config: GitHooksConfig = {
-  // Lint and test before commits
-  'pre-commit': 'bun run lint && bun run test',
+  // Lint and test before commits (using staged-lint)
+  'pre-commit': {
+    'staged-lint': {
+      '*.{js,ts}': 'bunx --bun eslint . --fix --max-warnings=0',
+      '*.{css,scss}': 'stylelint --fix'
+    }
+  },
 
   // Validate commit messages
   'commit-msg': 'bun commitlint --edit $1',
@@ -108,10 +119,7 @@ const config: GitHooksConfig = {
   'post-checkout': 'bun install',
 
   // Run security checks before push
-  'pre-push': 'bun run security:check',
-
-  // Format code before commit
-  'pre-commit': 'bun run format && bun run lint',
+  'pre-push': 'bun run security:check'
 }
 ```
 

docs/usage.md

@@ -17,7 +17,7 @@ Create a `git-hooks.config.{ts,js,mjs,cjs,json}` file in your project root:
 import type { GitHooksConfig } from 'bun-git-hooks'
 
 const config: GitHooksConfig = {
-  // Using staged-lint for efficient file-specific linting
+  // Note: staged-lint is only available in pre-commit hook
   'pre-commit': {
     'staged-lint': {
       '*.{js,ts}': 'bunx --bun eslint . --fix',
@@ -67,13 +67,13 @@ git-hooks remove  # alias
 # Enable verbose logging
 git-hooks --verbose
 
-# Run staged lint for a specific hook
+# Run staged lint for pre-commit hook
 git-hooks run-staged-lint pre-commit
 ```
 
 ## Staged Lint Usage
 
-The `staged-lint` feature allows you to run specific commands on staged files matching certain patterns. This is more efficient than running commands on all files.
+The `staged-lint` feature is only available in the pre-commit hook. It allows you to run specific commands on staged files matching certain patterns. This is more efficient than running commands on all files.
 
 ### Basic Staged Lint
 
@@ -109,27 +109,6 @@ const config: GitHooksConfig = {
 }
 ```
 
-### Global Staged Lint
-
-You can define staged lint rules globally that apply to all hooks:
-
-```ts
-const config: GitHooksConfig = {
-  // Global staged lint configuration
-  'staged-lint': {
-    '*.{js,ts}': 'bunx --bun eslint . --fix',
-    '*.{css,scss}': 'stylelint --fix'
-  },
-
-  // Hook-specific configuration (takes precedence)
-  'pre-commit': {
-    'staged-lint': {
-      '*.{js,ts}': 'bunx --bun eslint . --fix --max-warnings=0'
-    }
-  }
-}
-```
-
 ## Environment Variables
 
 ### SKIP_INSTALL_GIT_HOOKS
@@ -196,7 +175,7 @@ const config: GitHooksConfig = {
 
 The following git hooks are supported:
 
-- `pre-commit`: Run before committing
+- `pre-commit`: Run before committing (supports staged-lint)
 - `prepare-commit-msg`: Run before the commit message editor is opened
 - `commit-msg`: Run to verify commit message
 - `post-commit`: Run after committing
@@ -221,6 +200,9 @@ catch (err) {
   else if (err.message.includes('git root')) {
     console.error('Not a Git repository')
   }
+  else if (err.message.includes('staged-lint is only allowed in pre-commit hook')) {
+    console.error('Staged-lint can only be used in pre-commit hook')
+  }
 }
 ```
 
@@ -239,9 +221,6 @@ interface GitHooksConfig {
   'commit-msg'?: string
   'post-merge'?: string
   // ... other git hooks
-  'staged-lint'?: {
-    [pattern: string]: string | string[]
-  }
   'preserveUnused'?: Array<string> | boolean
   'verbose'?: boolean
 }

src/git-hooks.ts

@@ -188,9 +188,13 @@ function _getPackageJson(projectPath = process.cwd()): { packageJsonContent: any
  */
 export function setHooksFromConfig(projectRootPath: string = process.cwd(), options?: SetHooksFromConfigOptions): void {
   if (!config || Object.keys(config).length === 0)
-    throw new Error('[ERROR] Config was not found! Please add `.git-hooks.config.{ts,js,mjs,cjs,mts,cts,json}` or `git-hooks.config.{ts,js,mjs,cjs,mts,cts,json}` or the `git-hooks` entry in package.json.\r\nCheck README for details')
+    throw new Error('[ERROR] Config was not found! Please add `.git-hooks.config.{ts,js,mjs,cjs,json}` or `git-hooks.config.{ts,js,mjs,cjs,json}` or the `git-hooks` entry in package.json.\r\nCheck README for details')
+
+  // Always use the provided configFile if available, otherwise use the cached config
+  const configFile = options?.configFile || { ...config }
+
+  _validateStagedLintConfig(configFile)
 
-  const configFile = options?.configFile ? options.configFile : config
   // Only validate hook names that aren't options
   const hookKeys = Object.keys(configFile).filter(key => !VALID_OPTIONS.includes(key as typeof VALID_OPTIONS[number]))
   const isValidConfig = hookKeys.every(key => VALID_GIT_HOOKS.includes(key as typeof VALID_GIT_HOOKS[number]))
@@ -427,6 +431,17 @@ function _validateHooks(config: Record<string, any>): boolean {
   return true
 }
 
+function _validateStagedLintConfig(config: GitHooksConfig): void {
+  for (const hook of VALID_GIT_HOOKS) {
+    if (hook !== 'pre-commit' && config[hook] && typeof config[hook] === 'object') {
+      const hookConfig = config[hook] as { 'stagedLint'?: StagedLintConfig; 'staged-lint'?: StagedLintConfig }
+      if (hookConfig['stagedLint'] || hookConfig['staged-lint']) {
+        throw new Error(`staged-lint is only allowed in pre-commit hook. Found in ${hook} hook.`)
+      }
+    }
+  }
+}
+
 const gitHooks: {
   PREPEND_SCRIPT: typeof PREPEND_SCRIPT
   setHooksFromConfig: typeof setHooksFromConfig