Blinter 🚀

Blinter is a linter for Windows batch files (.bat and .cmd). It provides comprehensive static analysis to identify syntax errors, security vulnerabilities, performance issues and style problems. Blinter helps you write safer, more reliable and maintainable batch scripts. Even in 2025, batch files deserve professional tooling! 💻

✅ Configurable Options - Configurable rules, logging, robust error handling
✅ Unicode Support - Support for international characters and filenames
✅ Performance Optimized - Handles large files (10MB+) efficiently

Features ✨

🔍 Rule Categories

114 Built-in Rules across 5 severity levels
Error Level (E001-E999): Critical syntax errors that prevent execution
Warning Level (W001-W999): Potential runtime issues and bad practices
Style Level (S001-S999): Code formatting and readability improvements
Security Level (SEC001+): Security vulnerabilities and dangerous operations
Performance Level (P001-P999): Optimization opportunities and efficiency improvements

📖 For complete rule descriptions with examples and implementation details, see Batch-File-Linter-Requirements.md

📋 Output Format

Rule Codes: Each issue has a unique identifier (e.g., E002, W005, SEC003)
Clear Explanations: Detailed descriptions of why each issue matters
Actionable Recommendations: Specific guidance on how to fix problems
Line-by-Line Analysis: Precise location of every issue
Context Information: Additional details about detected problems

🚀 Advanced Analysis

Static Code Analysis: Detects unreachable code and logic errors
Advanced Variable Expansion: Validates percent-tilde syntax (%~n1), string operations, and SET /A arithmetic
Command-Specific Validation: FOR loop variations, IF statement best practices, deprecated command detection
Variable Tracking: Identifies undefined variables and unsafe usage patterns
Security Scanning: Path traversal attacks, command injection risks, unsafe temp file creation
Performance Optimization: DIR flag optimization, unnecessary output detection, string operation efficiency
Cross-Platform Compatibility: Warns about Windows version issues and deprecated commands
Large File Handling: Efficiently processes files up to 10MB+ with performance warnings
Robust Encoding Detection: Handles UTF-8, UTF-16, Latin-1 and 6 more encoding formats

Installation 🛠️

🚀 Quick Start (Recommended)

Option 1: Install via pip

pip install Blinter

Option 2: Download standalone executable

Download the latest Blinter-v1.0.x-windows.zip from GitHub Releases

🔧 Manual Installation

Clone the repository:

git clone https://github.com/tboy1337/Blinter.git
cd Blinter

(Optional) Create a virtual environment:

python -m venv venv
venv\Scripts\Activate.ps1

(Optional but recommended) Install dependencies:

pip install -r requirements.txt

Prerequisites

Python 3.9+ (required for pip installation and development)
Windows OS (required for standalone executable)

Usage 📟

Basic Usage

If installed via pip:

# Analyze a single batch file
python -m blinter script.bat

# Analyze all batch files in a directory (recursive)
python -m blinter /path/to/batch/files

# Analyze batch files in directory only (non-recursive)
python -m blinter /path/to/batch/files --no-recursive

# Analyze with summary
python -m blinter script.bat --summary

# Create configuration file
python -m blinter --create-config

# Ignore configuration file
python -m blinter script.bat --no-config

# Get help
python -m blinter --help

If using standalone executable:

# Analyze a single batch file
Blinter-v1.0.x-windows.exe script.bat

# Analyze all batch files in a directory (recursive)
Blinter-v1.0.x-windows.exe /path/to/batch/files

# Analyze batch files in directory only (non-recursive)
Blinter-v1.0.x-windows.exe /path/to/batch/files --no-recursive

# Analyze with summary
Blinter-v1.0.x-windows.exe script.bat --summary

# Get help
Blinter-v1.0.x-windows.exe --help

If using manual installation:

# Analyze a single batch file
python blinter.py script.bat

# Analyze all batch files in a directory (recursive)
python blinter.py /path/to/batch/files

# Analyze batch files in directory only (non-recursive)
python blinter.py /path/to/batch/files --no-recursive

# Analyze with summary
python blinter.py script.bat --summary

# Create configuration file
python blinter.py --create-config

# Ignore configuration file
python blinter.py script.bat --no-config

# Get help
python blinter.py --help

Command Line Options

<path>: Path to a batch file (.bat or .cmd) OR directory containing batch files
--summary: Display summary statistics of issues found
--severity: Show detailed severity level breakdown (always included)
--no-recursive: When processing directories, only analyze files in the specified directory (not subdirectories)
--no-config: Don't use configuration file (blinter.ini) even if it exists
--create-config: Create a default blinter.ini configuration file and exit
--help: Show help menu and rule categories

Note: Command line options override configuration file settings. Blinter automatically looks for blinter.ini in the current directory.

Configuration 📝

Blinter supports configuration files to customize its behavior. Create a blinter.ini file in your project directory to set default options.

Creating a Configuration File

Generate a default configuration file with all available options:

python blinter.py --create-config

This creates a blinter.ini file with default settings.

Configuration Options

Section	Setting	Description	Default
`[general]`	`recursive`	Search subdirectories when analyzing folders	`true`
`[general]`	`show_summary`	Display summary statistics after analysis	`false`
`[general]`	`max_line_length`	Maximum line length for S011 rule	`120`
`[general]`	`min_severity`	Minimum severity level to report	None (all)
`[rules]`	`enabled_rules`	Comma-separated list of rules to enable exclusively	None (all enabled)
`[rules]`	`disabled_rules`	Comma-separated list of rules to disable	None

Command Line Override

Command line options always override configuration file settings:

# Use config file settings
python -m blinter myscript.bat

# Override config to show summary
python -m blinter myscript.bat --summary

# Ignore config file completely
python -m blinter myscript.bat --no-config

🐍 Programmatic API Usage

Blinter provides a powerful Python API for integration into your applications:

import blinter

# Basic usage
issues = blinter.lint_batch_file("script.bat")
for issue in issues:
    print(f"Line {issue.line_number}: {issue.rule.name} ({issue.rule.code})")

# With custom configuration
from blinter import BlinterConfig, RuleSeverity
config = BlinterConfig(
    max_line_length=80,
    disabled_rules={"S007", "S011"},
    min_severity=RuleSeverity.WARNING
)
issues = blinter.lint_batch_file("script.bat", config=config)

# Process results
for issue in issues:
    print(f"Line {issue.line_number}: {issue.rule.name}")
    print(f"  {issue.rule.explanation}")
    print(f"  Fix: {issue.rule.recommendation}")


# Thread-safe design allows safe concurrent usage
# You can implement your own concurrent processing if needed
from concurrent.futures import ThreadPoolExecutor

files = ["script1.bat", "script2.cmd", "script3.bat"]
with ThreadPoolExecutor(max_workers=4) as executor:
    results = list(executor.map(blinter.lint_batch_file, files))

🔧 Configuration Options

Parameter	Type	Default	Description
`file_path`	`str`	Required	Path to batch file to analyze
`max_line_length`	`int`	`120`	Maximum line length for S011 rule
`enable_style_rules`	`bool`	`True`	Enable/disable style-related rules
`enable_performance_rules`	`bool`	`True`	Enable/disable performance rules

Note: Security rules are always enabled for safety.

Supported File Types

.bat files (traditional batch files)
.cmd files (recommended for modern Windows)
Unicode filenames and international characters supported
Large files (10MB+) handled efficiently with performance monitoring

📁 Directory Processing

Blinter can analyze entire directories of batch files with powerful options:

Recursive Analysis: Automatically finds and processes all .bat and .cmd files in directories and subdirectories
Non-Recursive Mode: Use --no-recursive to analyze only files in the specified directory
Batch Processing: Handles multiple files efficiently with consolidated reporting
Error Resilience: Continues processing other files even if some files have encoding or permission issues
Progress Tracking: Shows detailed results for each file plus combined summary statistics

Examples:

# Pip installation:
python -m blinter ./my-batch-scripts                 # Analyze all files recursively
python -m blinter . --no-recursive                   # Current directory only
python -m blinter ./scripts --summary               # With summary statistics

# Standalone executable:
Blinter.exe ./my-batch-scripts            # Analyze all files recursively
Blinter.exe . --no-recursive             # Current directory only
Blinter.exe ./scripts --summary          # With summary statistics

# Manual installation:
python blinter.py ./my-batch-scripts      # Analyze all files recursively
python blinter.py . --no-recursive       # Current directory only  
python blinter.py ./scripts --summary     # With summary statistics

🔥 Integration Example

CI/CD Integration

# Example GitHub Actions workflow
- name: Lint Batch Files
  run: |
    python -c "
    import blinter
    import sys
    issues = blinter.lint_batch_file('deploy.bat')
    errors = [i for i in issues if i.rule.severity.value == 'Error']
    if errors:
        print(f'Found {len(errors)} critical errors!')
        sys.exit(1)
    print(f'✅ Batch file passed with {len(issues)} total issues')
    "

Contributing 🤝

Contributions are welcome!

Ways to Contribute

🐛 Report bugs or issues
💡 Suggest new rules or features
📖 Improve documentation
🧪 Add test cases
🔧 Submit bug fixes or enhancements

License 📄

This project is licensed under the CRL License - see LICENSE.md for details.

Metadata

Release files for blinter 1.0.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for blinter 1.0.6
File	Size	Uploaded	Provenance
blinter-1.0.6.tar.gz	106.8 kB	Sep 28, 2025	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for blinter 1.0.6
File	Interpreter	ABI	Platform	Reset
blinter-1.0.6-py3-none-any.whl 44.5 kB Sep 28, 2025 Without provenance	Python 3	none	any	Details

Total release size: 151.3 kB

Release files / blinter-1.0.6.tar.gz

Download URL	blinter-1.0.6.tar.gz
Size	106.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`6db09adc48efd75bd64adcb11d7adbbce35c34efa50ed77c6261cc9f8b434f67`
BLAKE2b-256 checksum How to use checksums	`157c2323e0de108a998d4f209eb50cca3ce3f3318e07d3cc0d883ae946c8b00b`
Upload date	Sep 28, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.7`

Release files / blinter-1.0.6-py3-none-any.whl

Download URL	blinter-1.0.6-py3-none-any.whl
Size	44.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`6c779ef98f24ef71f9feab0f297baa347d535e8f6aac375cea9081806d8f91b8`
BLAKE2b-256 checksum How to use checksums	`0117189c8f62f15fbb95371f5e4696ceba2a9baf41350a675319c0d306795cb2`
Upload date	Sep 28, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.7`

Security for blinter 1.0.6

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.