# ANTLR v4 Grammar Linter
[](https://badge.fury.io/py/antlr-v4-linter)
[](https://pypi.org/project/antlr-v4-linter/)
[](https://opensource.org/licenses/MIT)
A comprehensive static analysis linter for ANTLR v4 grammar files (.g4) that identifies common issues, enforces best practices, and improves grammar quality and maintainability.
## ✨ Features
- **24 Built-in Rules** across 8 categories for comprehensive grammar analysis
- **Configurable Rule Severity** - Set rules as error, warning, or info
- **Multiple Output Formats** - Text (with colors), JSON, XML, SARIF
- **Smart Detection** - Identifies naming issues, complexity problems, performance bottlenecks
- **Flexible Configuration** - JSON-based configuration with rule-specific thresholds
- **CLI and Programmatic APIs** - Use as command-line tool or Python library
## 📦 Installation
```bash
# Using pip
pip install antlr-v4-linter
# Using uv (faster)
uv pip install antlr-v4-linter
# Using pipx (isolated environment)
pipx install antlr-v4-linter
```
## 🚀 Quick Start
```bash
# Lint a single grammar file
antlr-lint lint MyGrammar.g4
# Lint multiple files or directories
antlr-lint lint src/
antlr-lint lint "*.g4"
# Use custom configuration
antlr-lint lint --config antlr-lint.json MyGrammar.g4
# Output in different formats
antlr-lint lint --format json MyGrammar.g4
antlr-lint lint --format xml MyGrammar.g4
# List all available rules
antlr-lint rules
# Create a configuration file
antlr-lint init
```
## 📋 Available Rules
The linter includes **24 rules** organized into 8 categories:
### Syntax and Structure (S001-S003)
- **S001**: Missing EOF token - Main parser rule should end with EOF
- **S002**: Incomplete input parsing - Lexer should have catch-all rule
- **S003**: Ambiguous string literals - Same literal in multiple lexer rules
### Naming and Convention (N001-N003)
- **N001**: Parser rule naming - Must start with lowercase letter
- **N002**: Lexer rule naming - Must start with uppercase letter
- **N003**: Inconsistent naming convention - Mixed camelCase/snake_case
### Labeling and Organization (L001-L003)
- **L001**: Missing alternative labels - Multi-alternative rules need labels
- **L002**: Inconsistent label naming - Labels should follow consistent style
- **L003**: Duplicate labels - Labels must be unique within rule
### Complexity and Maintainability (C001-C003)
- **C001**: Excessive complexity - Rules exceed configurable thresholds
- **C002**: Deeply nested rule - Too many nesting levels
- **C003**: Very long rule - Rule definition spans too many lines
### Token and Lexer (T001-T003)
- **T001**: Overlapping tokens - Token definitions may conflict
- **T002**: Unreachable token - Token shadowed by earlier rules
- **T003**: Unused token - Token defined but never used
### Error Handling (E001-E002)
- **E001**: Missing error recovery - No error handling strategies
- **E002**: Potential ambiguity - Grammar may have ambiguous paths
### Performance (P001-P002)
- **P001**: Excessive backtracking - Patterns causing performance issues
- **P002**: Inefficient lexer pattern - Suboptimal regular expressions
### Documentation (D001-D002)
- **D001**: Missing rule documentation - Complex rules lack comments
- **D002**: Missing grammar header - No file-level documentation
## ⚙️ Configuration
Create an `antlr-lint.json` file in your project root:
```json
{
"rules": {
"S001": { "enabled": true, "severity": "error" },
"N001": { "enabled": true, "severity": "error" },
"C001": {
"enabled": true,
"severity": "warning",
"thresholds": {
"maxAlternatives": 10,
"maxNestingDepth": 5,
"maxTokens": 50
}
}
},
"excludePatterns": ["*.generated.g4", "build/**/*.g4"],
"outputFormat": "text"
}
```
### Configuration Options
- **rules**: Configure individual rules with `enabled`, `severity`, and rule-specific `thresholds`
- **excludePatterns**: Glob patterns for files to skip
- **outputFormat**: Choose between `text`, `json`, `xml`, or `sarif`
Generate a default configuration:
```bash
antlr-lint init
```
## 🐍 Programmatic API
Use the linter in your Python code:
```python
from antlr_v4_linter import ANTLRLinter, LinterConfig
# Create linter with default config
linter = ANTLRLinter()
# Or with custom config
config = LinterConfig.from_file("antlr-lint.json")
linter = ANTLRLinter(config)
# Lint a single file
result = linter.lint_file("MyGrammar.g4")
print(f"Found {result.total_issues} issues")
# Lint multiple files
results = linter.lint_files(["Grammar1.g4", "Grammar2.g4"])
for result in results:
print(f"{result.file_path}: {result.error_count} errors, {result.warning_count} warnings")
```
## 🔧 Development
```bash
# Clone the repository
git clone https://github.com/bytebase/antlr-v4-linter.git
cd antlr-v4-linter
# Install in development mode
pip install -e ".[dev]"
# Run tests
pytest
# Format code
black src/ tests/
isort src/ tests/
# Type checking
mypy src/
# Build package
python -m build
```
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## 📝 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- The ANTLR project and community for the excellent parser generator
- All contributors who help improve this linter
## 🔗 Links
- **PyPI Package**: https://pypi.org/project/antlr-v4-linter/
- **GitHub Repository**: https://github.com/bytebase/antlr-v4-linter
- **Issue Tracker**: https://github.com/bytebase/antlr-v4-linter/issues
- **ANTLR Documentation**: https://www.antlr.org/
## 📊 Project Status
- ✅ All 24 rules implemented
- ✅ Published to PyPI
- ✅ Comprehensive test coverage
- ✅ GitHub Actions CI/CD
- 🚧 IDE extensions (coming soon)
- 🚧 Auto-fix capabilities (coming soon)
## 🚀 GitHub Actions Integration
The project includes automated CI/CD workflows:
### Automatic Release on Tag
When you push a version tag (e.g., `0.1.3`), the package is automatically:
1. Built and tested
2. Published to Test PyPI
3. Published to Production PyPI
4. GitHub Release created
```bash
# Create and push a version tag
git tag 0.1.3
git push origin 0.1.3
```
### Manual Release
Use the "Manual Release" workflow in GitHub Actions:
1. Go to Actions → Manual Release
2. Click "Run workflow"
3. Enter version number
4. Choose whether to test on Test PyPI first
### Continuous Integration
All pushes and pull requests run:
- Multi-platform tests (Linux, macOS)
- Python 3.8-3.12 compatibility tests
- Code quality checks (black, isort, flake8, mypy)
Raw data
{
"_id": null,
"home_page": null,
"name": "antlr-v4-linter",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8.1",
"maintainer_email": "Bytebase Team <support@bytebase.com>",
"keywords": "antlr, antlr4, linter, grammar, parser, lexer, static-analysis",
"author": null,
"author_email": "Bytebase <support@bytebase.com>",
"download_url": "https://files.pythonhosted.org/packages/28/89/b6a787e59bf7084f499f73ec2714cbf5f58965cc71bb8a70dfa1b9ceae60/antlr_v4_linter-0.1.4.tar.gz",
"platform": null,
"description": "# ANTLR v4 Grammar Linter\n\n[](https://badge.fury.io/py/antlr-v4-linter)\n[](https://pypi.org/project/antlr-v4-linter/)\n[](https://opensource.org/licenses/MIT)\n\nA comprehensive static analysis linter for ANTLR v4 grammar files (.g4) that identifies common issues, enforces best practices, and improves grammar quality and maintainability.\n\n## \u2728 Features\n\n- **24 Built-in Rules** across 8 categories for comprehensive grammar analysis\n- **Configurable Rule Severity** - Set rules as error, warning, or info\n- **Multiple Output Formats** - Text (with colors), JSON, XML, SARIF\n- **Smart Detection** - Identifies naming issues, complexity problems, performance bottlenecks\n- **Flexible Configuration** - JSON-based configuration with rule-specific thresholds\n- **CLI and Programmatic APIs** - Use as command-line tool or Python library\n\n## \ud83d\udce6 Installation\n\n```bash\n# Using pip\npip install antlr-v4-linter\n\n# Using uv (faster)\nuv pip install antlr-v4-linter\n\n# Using pipx (isolated environment)\npipx install antlr-v4-linter\n```\n\n## \ud83d\ude80 Quick Start\n\n```bash\n# Lint a single grammar file\nantlr-lint lint MyGrammar.g4\n\n# Lint multiple files or directories\nantlr-lint lint src/\nantlr-lint lint \"*.g4\"\n\n# Use custom configuration\nantlr-lint lint --config antlr-lint.json MyGrammar.g4\n\n# Output in different formats\nantlr-lint lint --format json MyGrammar.g4\nantlr-lint lint --format xml MyGrammar.g4\n\n# List all available rules\nantlr-lint rules\n\n# Create a configuration file\nantlr-lint init\n```\n\n## \ud83d\udccb Available Rules\n\nThe linter includes **24 rules** organized into 8 categories:\n\n### Syntax and Structure (S001-S003)\n- **S001**: Missing EOF token - Main parser rule should end with EOF\n- **S002**: Incomplete input parsing - Lexer should have catch-all rule\n- **S003**: Ambiguous string literals - Same literal in multiple lexer rules\n\n### Naming and Convention (N001-N003)\n- **N001**: Parser rule naming - Must start with lowercase letter\n- **N002**: Lexer rule naming - Must start with uppercase letter\n- **N003**: Inconsistent naming convention - Mixed camelCase/snake_case\n\n### Labeling and Organization (L001-L003)\n- **L001**: Missing alternative labels - Multi-alternative rules need labels\n- **L002**: Inconsistent label naming - Labels should follow consistent style\n- **L003**: Duplicate labels - Labels must be unique within rule\n\n### Complexity and Maintainability (C001-C003)\n- **C001**: Excessive complexity - Rules exceed configurable thresholds\n- **C002**: Deeply nested rule - Too many nesting levels\n- **C003**: Very long rule - Rule definition spans too many lines\n\n### Token and Lexer (T001-T003)\n- **T001**: Overlapping tokens - Token definitions may conflict\n- **T002**: Unreachable token - Token shadowed by earlier rules\n- **T003**: Unused token - Token defined but never used\n\n### Error Handling (E001-E002)\n- **E001**: Missing error recovery - No error handling strategies\n- **E002**: Potential ambiguity - Grammar may have ambiguous paths\n\n### Performance (P001-P002)\n- **P001**: Excessive backtracking - Patterns causing performance issues\n- **P002**: Inefficient lexer pattern - Suboptimal regular expressions\n\n### Documentation (D001-D002)\n- **D001**: Missing rule documentation - Complex rules lack comments\n- **D002**: Missing grammar header - No file-level documentation\n\n## \u2699\ufe0f Configuration\n\nCreate an `antlr-lint.json` file in your project root:\n\n```json\n{\n \"rules\": {\n \"S001\": { \"enabled\": true, \"severity\": \"error\" },\n \"N001\": { \"enabled\": true, \"severity\": \"error\" },\n \"C001\": { \n \"enabled\": true, \n \"severity\": \"warning\",\n \"thresholds\": {\n \"maxAlternatives\": 10,\n \"maxNestingDepth\": 5,\n \"maxTokens\": 50\n }\n }\n },\n \"excludePatterns\": [\"*.generated.g4\", \"build/**/*.g4\"],\n \"outputFormat\": \"text\"\n}\n```\n\n### Configuration Options\n\n- **rules**: Configure individual rules with `enabled`, `severity`, and rule-specific `thresholds`\n- **excludePatterns**: Glob patterns for files to skip\n- **outputFormat**: Choose between `text`, `json`, `xml`, or `sarif`\n\nGenerate a default configuration:\n```bash\nantlr-lint init\n```\n\n## \ud83d\udc0d Programmatic API\n\nUse the linter in your Python code:\n\n```python\nfrom antlr_v4_linter import ANTLRLinter, LinterConfig\n\n# Create linter with default config\nlinter = ANTLRLinter()\n\n# Or with custom config\nconfig = LinterConfig.from_file(\"antlr-lint.json\")\nlinter = ANTLRLinter(config)\n\n# Lint a single file\nresult = linter.lint_file(\"MyGrammar.g4\")\nprint(f\"Found {result.total_issues} issues\")\n\n# Lint multiple files\nresults = linter.lint_files([\"Grammar1.g4\", \"Grammar2.g4\"])\nfor result in results:\n print(f\"{result.file_path}: {result.error_count} errors, {result.warning_count} warnings\")\n```\n\n## \ud83d\udd27 Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/bytebase/antlr-v4-linter.git\ncd antlr-v4-linter\n\n# Install in development mode\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Format code\nblack src/ tests/\nisort src/ tests/\n\n# Type checking\nmypy src/\n\n# Build package\npython -m build\n```\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## \ud83d\udcdd License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- The ANTLR project and community for the excellent parser generator\n- All contributors who help improve this linter\n\n## \ud83d\udd17 Links\n\n- **PyPI Package**: https://pypi.org/project/antlr-v4-linter/\n- **GitHub Repository**: https://github.com/bytebase/antlr-v4-linter\n- **Issue Tracker**: https://github.com/bytebase/antlr-v4-linter/issues\n- **ANTLR Documentation**: https://www.antlr.org/\n\n## \ud83d\udcca Project Status\n\n- \u2705 All 24 rules implemented\n- \u2705 Published to PyPI\n- \u2705 Comprehensive test coverage\n- \u2705 GitHub Actions CI/CD\n- \ud83d\udea7 IDE extensions (coming soon)\n- \ud83d\udea7 Auto-fix capabilities (coming soon)\n\n## \ud83d\ude80 GitHub Actions Integration\n\nThe project includes automated CI/CD workflows:\n\n### Automatic Release on Tag\n\nWhen you push a version tag (e.g., `0.1.3`), the package is automatically:\n1. Built and tested\n2. Published to Test PyPI\n3. Published to Production PyPI\n4. GitHub Release created\n\n```bash\n# Create and push a version tag\ngit tag 0.1.3\ngit push origin 0.1.3\n```\n\n### Manual Release\n\nUse the \"Manual Release\" workflow in GitHub Actions:\n1. Go to Actions \u2192 Manual Release\n2. Click \"Run workflow\"\n3. Enter version number\n4. Choose whether to test on Test PyPI first\n\n### Continuous Integration\n\nAll pushes and pull requests run:\n- Multi-platform tests (Linux, macOS)\n- Python 3.8-3.12 compatibility tests\n- Code quality checks (black, isort, flake8, mypy)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A comprehensive static analysis linter for ANTLR v4 grammar files",
"version": "0.1.4",
"project_urls": {
"Changelog": "https://github.com/bytebase/antlr-v4-linter/releases",
"Documentation": "https://github.com/bytebase/antlr-v4-linter#readme",
"Homepage": "https://github.com/bytebase/antlr-v4-linter",
"Issues": "https://github.com/bytebase/antlr-v4-linter/issues",
"Repository": "https://github.com/bytebase/antlr-v4-linter"
},
"split_keywords": [
"antlr",
" antlr4",
" linter",
" grammar",
" parser",
" lexer",
" static-analysis"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4494e45812dbaa85d636a36bb969a3a76ba8c05aba1e783df35cef8260598265",
"md5": "94db5e1d785a96bcda599bd7c722eee8",
"sha256": "67ade8b8f77e30d0d78d177f900f5a262df73fe85cb614954b196ae34ebbd908"
},
"downloads": -1,
"filename": "antlr_v4_linter-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "94db5e1d785a96bcda599bd7c722eee8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.1",
"size": 67691,
"upload_time": "2025-08-05T06:53:32",
"upload_time_iso_8601": "2025-08-05T06:53:32.791570Z",
"url": "https://files.pythonhosted.org/packages/44/94/e45812dbaa85d636a36bb969a3a76ba8c05aba1e783df35cef8260598265/antlr_v4_linter-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2889b6a787e59bf7084f499f73ec2714cbf5f58965cc71bb8a70dfa1b9ceae60",
"md5": "d54362f9337ff16068150d7fba704c13",
"sha256": "e45d7b2f6409b53d32091877991fe44cbc9d759562f5f8bbc07c1cc4c1510d3c"
},
"downloads": -1,
"filename": "antlr_v4_linter-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "d54362f9337ff16068150d7fba704c13",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.1",
"size": 59845,
"upload_time": "2025-08-05T06:53:34",
"upload_time_iso_8601": "2025-08-05T06:53:34.212657Z",
"url": "https://files.pythonhosted.org/packages/28/89/b6a787e59bf7084f499f73ec2714cbf5f58965cc71bb8a70dfa1b9ceae60/antlr_v4_linter-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-05 06:53:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bytebase",
"github_project": "antlr-v4-linter",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "antlr-v4-linter"
}
JSON
