# PSScriptAnalyzer Pre-commit Hook
A pre-commit hook for running [PSScriptAnalyzer](https://github.com/PowerShell/PSScriptAnalyzer) on PowerShell files to ensure code quality and consistency.
## Features
- **Cross-platform support**: Works on Windows, macOS, and Linux
- **Automatic installation**: Installs PSScriptAnalyzer if not present
- **Two modes**: Linting and formatting
- **Configurable severity**: Choose severity levels for issues (All, Information, Warning, Error)
- **PowerShell detection**: Automatically finds PowerShell Core (pwsh) or Windows PowerShell
- **Color-coded output**: Different colors for Error (red), Warning (orange), Information (cyan)
- **GitHub Actions integration**: Automatic annotations for GitHub Actions workflows
- **Improved output format**: Severity-first display for easy scanning
## Supported File Types
- `.ps1` - PowerShell scripts
- `.psm1` - PowerShell modules
- `.psd1` - PowerShell data files
## Prerequisites
- Python 3.9 or later
- PowerShell Core (pwsh) or Windows PowerShell
- pre-commit
### Installing PowerShell
If you don't have PowerShell installed:
- **Windows**: PowerShell is usually pre-installed. For PowerShell Core, visit [PowerShell releases](https://github.com/PowerShell/PowerShell/releases)
- **macOS**: `brew install powershell`
- **Linux**: Follow the [PowerShell installation guide](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-linux)
## Usage
Add this to your `.pre-commit-config.yaml`:
```yaml
repos:
- repo: https://github.com/thetestlabs/psscriptanalyzer-pre-commit
rev: v1.0.0 # Use the ref you want to point at
hooks:
- id: psscriptanalyzer
- id: psscriptanalyzer-format
```
### Available Hooks
#### `psscriptanalyzer`
Runs PSScriptAnalyzer to check for issues in your PowerShell files.
**Configuration options:**
```yaml
- id: psscriptanalyzer
args: ["--severity", "Warning"] # Default: Warning
# Available options: All, Information, Warning, Error
```
**Severity levels:**
- `All`: Shows Error, Warning, and Information issues (most comprehensive)
- `Information`: Shows only Information level issues
- `Warning`: Shows only Warning level issues (default)
- `Error`: Shows only Error level issues (most critical)
#### `psscriptanalyzer-format`
Formats your PowerShell files using PSScriptAnalyzer's formatter.
```yaml
- id: psscriptanalyzer-format
```
### Command Line Options
- `--format`: Format files instead of just analyzing them
- `--severity`: Set severity level:
- `All`: Show all issues (Error, Warning, Information)
- `Information`: Show only Information level issues
- `Warning`: Show only Warning level issues (default)
- `Error`: Show only Error level issues
### Output Format
The hook displays issues with color-coded severity levels:
**Local Terminal:**
- **Error**: Red text - `Error: filename: Line X:1: RuleName`
- **Warning**: Orange text - `Warning: filename: Line X:1: RuleName`
- **Information**: Cyan text - `Information: filename: Line X:1: RuleName`
**GitHub Actions:**
- **Error**: `::error` annotation - `Error: filename: Line X:1: RuleName`
- **Warning**: `::warning` annotation - `Warning: filename: Line X:1: RuleName`
- **Information**: `::notice` annotation - `Notice: filename: Line X:1: RuleName`
The severity-first format makes it easy to quickly scan and prioritize issues.
## Example Configuration
```yaml
repos:
- repo: https://github.com/thetestlabs/psscriptanalyzer-pre-commit
rev: v1.0.0
hooks:
# Check for issues (show all severity levels)
- id: psscriptanalyzer
args: ["--severity", "All"]
# Format files
- id: psscriptanalyzer-format
# Example: Only show critical errors
- id: psscriptanalyzer
name: psscriptanalyzer-errors-only
args: ["--severity", "Error"]
```
## How It Works
1. The hook detects PowerShell files in your commit
2. Finds PowerShell executable (pwsh or powershell)
3. Checks if PSScriptAnalyzer is installed, installs it if needed
4. Runs the appropriate PSScriptAnalyzer command
5. Reports issues or applies formatting
## Development
### Development Prerequisites
- Python 3.9+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip
- PowerShell Core (pwsh) or Windows PowerShell
To set up the development environment:
```bash
# Clone the repository
git clone https://github.com/thetestlabs/psscriptanalyzer-pre-commit.git
cd psscriptanalyzer-pre-commit
# Install uv (if not already installed)
# On macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
# On Windows:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# Install dependencies using uv
uv sync --dev
# Install pre-commit hooks
uv run pre-commit install
```
To test the hook locally:
```bash
# Run on files directly
uv run psscriptanalyzer-hook --help
uv run psscriptanalyzer-hook script.ps1
uv run psscriptanalyzer-hook --format script.ps1
uv run psscriptanalyzer-hook --severity Error script.ps1
# Alternative: using Python module execution
uv run python -m psscriptanalyzer_hook script.ps1
# Run code quality checks
uv run ruff check .
uv run ruff format .
uv run mypy psscriptanalyzer_hook.py
# Run tests
uv run pytest
# Run all pre-commit hooks
uv run pre-commit run --all-files
```
To build the package:
```bash
# Build wheel and source distribution
uv build
# Check package integrity
uv run twine check dist/*
```
### Alternative: Traditional Python Setup
If you prefer not to use uv:
```bash
# Install dependencies
pip install -e ".[dev]"
# Run commands without uv prefix
python -m psscriptanalyzer_hook --help
pre-commit run --all-files
pytest
ruff check .
mypy psscriptanalyzer_hook.py
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Related Projects
- [PSScriptAnalyzer](https://github.com/PowerShell/PSScriptAnalyzer) - The PowerShell static code checker
- [pre-commit](https://pre-commit.com/) - A framework for managing multi-language pre-commit hooks
Raw data
{
"_id": null,
"home_page": null,
"name": "psscriptanalyzer-pre-commit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Chris McQuaid <chris@thetestlabs.io>",
"keywords": "code-quality, formatting, linting, powershell, pre-commit, psscriptanalyzer, static-analysis",
"author": null,
"author_email": "Chris McQuaid <chris@thetestlabs.io>",
"download_url": "https://files.pythonhosted.org/packages/8a/c9/5be63cde216debce164af8c7c03e0637c3b5d43f818ef27719848201cd94/psscriptanalyzer_pre_commit-1.0.0.tar.gz",
"platform": null,
"description": "# PSScriptAnalyzer Pre-commit Hook\n\nA pre-commit hook for running [PSScriptAnalyzer](https://github.com/PowerShell/PSScriptAnalyzer) on PowerShell files to ensure code quality and consistency.\n\n## Features\n\n- **Cross-platform support**: Works on Windows, macOS, and Linux\n- **Automatic installation**: Installs PSScriptAnalyzer if not present\n- **Two modes**: Linting and formatting\n- **Configurable severity**: Choose severity levels for issues (All, Information, Warning, Error)\n- **PowerShell detection**: Automatically finds PowerShell Core (pwsh) or Windows PowerShell\n- **Color-coded output**: Different colors for Error (red), Warning (orange), Information (cyan)\n- **GitHub Actions integration**: Automatic annotations for GitHub Actions workflows\n- **Improved output format**: Severity-first display for easy scanning\n\n## Supported File Types\n\n- `.ps1` - PowerShell scripts\n- `.psm1` - PowerShell modules\n- `.psd1` - PowerShell data files\n\n## Prerequisites\n\n- Python 3.9 or later\n- PowerShell Core (pwsh) or Windows PowerShell\n- pre-commit\n\n### Installing PowerShell\n\nIf you don't have PowerShell installed:\n\n- **Windows**: PowerShell is usually pre-installed. For PowerShell Core, visit [PowerShell releases](https://github.com/PowerShell/PowerShell/releases)\n- **macOS**: `brew install powershell`\n- **Linux**: Follow the [PowerShell installation guide](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-linux)\n\n## Usage\n\nAdd this to your `.pre-commit-config.yaml`:\n\n```yaml\nrepos:\n - repo: https://github.com/thetestlabs/psscriptanalyzer-pre-commit\n rev: v1.0.0 # Use the ref you want to point at\n hooks:\n - id: psscriptanalyzer\n - id: psscriptanalyzer-format\n```\n\n### Available Hooks\n\n#### `psscriptanalyzer`\n\nRuns PSScriptAnalyzer to check for issues in your PowerShell files.\n\n**Configuration options:**\n\n```yaml\n- id: psscriptanalyzer\n args: [\"--severity\", \"Warning\"] # Default: Warning\n # Available options: All, Information, Warning, Error\n```\n\n**Severity levels:**\n\n- `All`: Shows Error, Warning, and Information issues (most comprehensive)\n- `Information`: Shows only Information level issues\n- `Warning`: Shows only Warning level issues (default)\n- `Error`: Shows only Error level issues (most critical)\n\n#### `psscriptanalyzer-format`\n\nFormats your PowerShell files using PSScriptAnalyzer's formatter.\n\n```yaml\n- id: psscriptanalyzer-format\n```\n\n### Command Line Options\n\n- `--format`: Format files instead of just analyzing them\n- `--severity`: Set severity level:\n - `All`: Show all issues (Error, Warning, Information)\n - `Information`: Show only Information level issues\n - `Warning`: Show only Warning level issues (default)\n - `Error`: Show only Error level issues\n\n### Output Format\n\nThe hook displays issues with color-coded severity levels:\n\n**Local Terminal:**\n\n- **Error**: Red text - `Error: filename: Line X:1: RuleName`\n- **Warning**: Orange text - `Warning: filename: Line X:1: RuleName`\n- **Information**: Cyan text - `Information: filename: Line X:1: RuleName`\n\n**GitHub Actions:**\n\n- **Error**: `::error` annotation - `Error: filename: Line X:1: RuleName`\n- **Warning**: `::warning` annotation - `Warning: filename: Line X:1: RuleName`\n- **Information**: `::notice` annotation - `Notice: filename: Line X:1: RuleName`\n\nThe severity-first format makes it easy to quickly scan and prioritize issues.\n\n## Example Configuration\n\n```yaml\nrepos:\n - repo: https://github.com/thetestlabs/psscriptanalyzer-pre-commit\n rev: v1.0.0\n hooks:\n # Check for issues (show all severity levels)\n - id: psscriptanalyzer\n args: [\"--severity\", \"All\"]\n\n # Format files\n - id: psscriptanalyzer-format\n\n # Example: Only show critical errors\n - id: psscriptanalyzer\n name: psscriptanalyzer-errors-only\n args: [\"--severity\", \"Error\"]\n```\n\n## How It Works\n\n1. The hook detects PowerShell files in your commit\n2. Finds PowerShell executable (pwsh or powershell)\n3. Checks if PSScriptAnalyzer is installed, installs it if needed\n4. Runs the appropriate PSScriptAnalyzer command\n5. Reports issues or applies formatting\n\n## Development\n\n### Development Prerequisites\n\n- Python 3.9+\n- [uv](https://docs.astral.sh/uv/) (recommended) or pip\n- PowerShell Core (pwsh) or Windows PowerShell\n\nTo set up the development environment:\n\n```bash\n# Clone the repository\ngit clone https://github.com/thetestlabs/psscriptanalyzer-pre-commit.git\ncd psscriptanalyzer-pre-commit\n\n# Install uv (if not already installed)\n# On macOS/Linux:\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n# On Windows:\npowershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n\n# Install dependencies using uv\nuv sync --dev\n\n# Install pre-commit hooks\nuv run pre-commit install\n```\n\nTo test the hook locally:\n\n```bash\n# Run on files directly\nuv run psscriptanalyzer-hook --help\nuv run psscriptanalyzer-hook script.ps1\nuv run psscriptanalyzer-hook --format script.ps1\nuv run psscriptanalyzer-hook --severity Error script.ps1\n\n# Alternative: using Python module execution\nuv run python -m psscriptanalyzer_hook script.ps1\n\n# Run code quality checks\nuv run ruff check .\nuv run ruff format .\nuv run mypy psscriptanalyzer_hook.py\n\n# Run tests\nuv run pytest\n\n# Run all pre-commit hooks\nuv run pre-commit run --all-files\n```\n\nTo build the package:\n\n```bash\n# Build wheel and source distribution\nuv build\n\n# Check package integrity\nuv run twine check dist/*\n```\n\n### Alternative: Traditional Python Setup\n\nIf you prefer not to use uv:\n\n```bash\n# Install dependencies\npip install -e \".[dev]\"\n\n# Run commands without uv prefix\npython -m psscriptanalyzer_hook --help\npre-commit run --all-files\npytest\nruff check .\nmypy psscriptanalyzer_hook.py\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Related Projects\n\n- [PSScriptAnalyzer](https://github.com/PowerShell/PSScriptAnalyzer) - The PowerShell static code checker\n- [pre-commit](https://pre-commit.com/) - A framework for managing multi-language pre-commit hooks\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Pre-commit hook for PSScriptAnalyzer - PowerShell static analysis and formatting",
"version": "1.0.0",
"project_urls": {
"Changelog": "https://github.com/thetestlabs/psscriptanalyzer-pre-commit/blob/main/CHANGELOG.md",
"Documentation": "https://psscriptanalyzer-pre-commit.readthedocs.io/",
"Homepage": "https://github.com/thetestlabs/psscriptanalyzer-pre-commit",
"Issues": "https://github.com/thetestlabs/psscriptanalyzer-pre-commit/issues",
"Repository": "https://github.com/thetestlabs/psscriptanalyzer-pre-commit"
},
"split_keywords": [
"code-quality",
" formatting",
" linting",
" powershell",
" pre-commit",
" psscriptanalyzer",
" static-analysis"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0ec1c08ff73826976ddd1910ecefe897ca23b81af8916a273fd2622d7e510bc0",
"md5": "0b593276eed1faefdcfc36f2f605a802",
"sha256": "4804c2375e6db60cd5a88c8824ce4a7000d73d09ed8d52333d1ba638cdc90c6c"
},
"downloads": -1,
"filename": "psscriptanalyzer_pre_commit-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0b593276eed1faefdcfc36f2f605a802",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 8750,
"upload_time": "2025-08-08T14:41:42",
"upload_time_iso_8601": "2025-08-08T14:41:42.777618Z",
"url": "https://files.pythonhosted.org/packages/0e/c1/c08ff73826976ddd1910ecefe897ca23b81af8916a273fd2622d7e510bc0/psscriptanalyzer_pre_commit-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8ac95be63cde216debce164af8c7c03e0637c3b5d43f818ef27719848201cd94",
"md5": "8eef50e4098c9181394bc576847b2715",
"sha256": "9e687978cd9aa0e66191afd2586f2d72ae87f18131cd25c6ecfe859269a96db9"
},
"downloads": -1,
"filename": "psscriptanalyzer_pre_commit-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "8eef50e4098c9181394bc576847b2715",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 99934,
"upload_time": "2025-08-08T14:41:44",
"upload_time_iso_8601": "2025-08-08T14:41:44.054537Z",
"url": "https://files.pythonhosted.org/packages/8a/c9/5be63cde216debce164af8c7c03e0637c3b5d43f818ef27719848201cd94/psscriptanalyzer_pre_commit-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-08 14:41:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "thetestlabs",
"github_project": "psscriptanalyzer-pre-commit",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "psscriptanalyzer-pre-commit"
}
JSON
