{"id":30260768,"url":"https://github.com/bytebase/antlr-v4-linter","last_synced_at":"2026-06-30T20:31:23.381Z","repository":{"id":308104587,"uuid":"1031628064","full_name":"bytebase/antlr-v4-linter","owner":"bytebase","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-05T06:53:01.000Z","size":208,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-06T09:58:59.768Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bytebase.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-04T05:12:59.000Z","updated_at":"2025-09-27T07:21:25.000Z","dependencies_parsed_at":"2025-08-04T08:29:33.432Z","dependency_job_id":"d05716b8-f311-46ce-bfd6-4ad953ff1f10","html_url":"https://github.com/bytebase/antlr-v4-linter","commit_stats":null,"previous_names":["bytebase/antlr-v4-linter"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/bytebase/antlr-v4-linter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytebase%2Fantlr-v4-linter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytebase%2Fantlr-v4-linter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytebase%2Fantlr-v4-linter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytebase%2Fantlr-v4-linter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bytebase","download_url":"https://codeload.github.com/bytebase/antlr-v4-linter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytebase%2Fantlr-v4-linter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34983170,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-15T19:57:58.786Z","updated_at":"2026-06-30T20:31:23.360Z","avatar_url":"https://github.com/bytebase.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ANTLR v4 Grammar Linter\n\n[![PyPI version](https://badge.fury.io/py/antlr-v4-linter.svg)](https://badge.fury.io/py/antlr-v4-linter)\n[![Python versions](https://img.shields.io/pypi/pyversions/antlr-v4-linter.svg)](https://pypi.org/project/antlr-v4-linter/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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## ✨ 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## 📦 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## 🚀 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## 📋 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## ⚙️ 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## 🐍 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## 🔧 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## 🤝 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## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- The ANTLR project and community for the excellent parser generator\n- All contributors who help improve this linter\n\n## 🔗 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## 📊 Project Status\n\n- ✅ All 24 rules implemented\n- ✅ Published to PyPI\n- ✅ Comprehensive test coverage\n- ✅ GitHub Actions CI/CD\n- 🚧 IDE extensions (coming soon)\n- 🚧 Auto-fix capabilities (coming soon)\n\n## 🚀 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 → 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)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytebase%2Fantlr-v4-linter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbytebase%2Fantlr-v4-linter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytebase%2Fantlr-v4-linter/lists"}