If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/antlr/antlr4 shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 3mo ago
• 48+ active contributors
• Distributed ownership (top contributor 18% of recent commits)
• BSD-3-Clause licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live antlr/antlr4 repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/antlr/antlr4.

What it runs against: a local clone of antlr/antlr4 — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in antlr/antlr4 | Confirms the artifact applies here, not a fork | | 2 | License is still BSD-3-Clause | Catches relicense before you depend on it | | 3 | Default branch dev exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 110 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of antlr/antlr4. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/antlr/antlr4.git
#   cd antlr4
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of antlr/antlr4 and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "antlr/antlr4(\\.git)?\\b" \\
  && ok "origin remote is antlr/antlr4" \\
  || miss "origin remote is not antlr/antlr4 (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(BSD-3-Clause)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"BSD-3-Clause\"" package.json 2>/dev/null) \\
  && ok "license is BSD-3-Clause" \\
  || miss "license drift — was BSD-3-Clause at generation time"

# 3. Default branch
git rev-parse --verify dev >/dev/null 2>&1 \\
  && ok "default branch dev exists" \\
  || miss "default branch dev no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "antlr4-maven-plugin/src/main/java/org/antlr/mojo/antlr4/Antlr4Mojo.java" \\
  && ok "antlr4-maven-plugin/src/main/java/org/antlr/mojo/antlr4/Antlr4Mojo.java" \\
  || miss "missing critical file: antlr4-maven-plugin/src/main/java/org/antlr/mojo/antlr4/Antlr4Mojo.java"
test -f "antlr4-maven-plugin/pom.xml" \\
  && ok "antlr4-maven-plugin/pom.xml" \\
  || miss "missing critical file: antlr4-maven-plugin/pom.xml"
test -f "CONTRIBUTING.md" \\
  && ok "CONTRIBUTING.md" \\
  || miss "missing critical file: CONTRIBUTING.md"
test -f "doc/building-antlr.md" \\
  && ok "doc/building-antlr.md" \\
  || miss "missing critical file: doc/building-antlr.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 110 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~80d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/antlr/antlr4"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

ANTLR 4 is a parser generator that converts formal grammar definitions (written in ANTLR grammar notation) into executable parsers and parse tree visitors/listeners for 10 target languages (Java, C++, C#, Python, JavaScript, Go, Swift, Dart, TypeScript, PHP). It reads structured text or binary files, builds abstract syntax trees, and generates language recognition infrastructure—used to build compilers, interpreters, domain-specific languages, and syntax-aware tools. Monorepo structure: antlr4-maven-plugin/ contains the Maven plugin wrapper; runtime libraries and code generators live in parent dirs not shown (inferred from pom.xml parent reference to antlr4-master). Each target language (Java, C++, C#, Python, Swift, Go, Dart, JavaScript, TypeScript) has its own runtime subdirectory with generated code and templates. Grammar files are .g4 files; the tool outputs language-specific parser classes and listener/visitor interfaces.

Language designers and compiler engineers who need to build parsers or interpreters; IDE developers requiring syntax highlighting and code analysis; DevOps/MLOps engineers building domain-specific languages for configuration or orchestration; anyone needing to parse structured data formats (JSON, SQL, custom protocols) without hand-coding lexer/parser logic.

Highly mature: ANTLR 4 has been in production use since 2012+ (current version 4.13.3-SNAPSHOT on master, stable 4.x releases tagged). The repo shows active CI/CD (GitHub Actions on .github/workflows/hosted.yml), comprehensive test coverage across 10 language targets, and regular releases. Master branch is stable; dev branch is where active development occurs. This is a canonical, battle-tested tool used in production by thousands of projects.

Low risk for stable releases (master branch), moderate for dev branch. The versioning policy treats minor version bumps as potentially breaking (regenerate parsers each release), so 4.x → 4.y upgrades require parser regeneration. The codebase is massive (2.4M Java, 1M C++, etc.), making contributions complex; heavy reliance on correct grammar semantics means user errors in .g4 files can cause subtle parsing bugs. Single primary maintainer (Terence Parr) creates a knowledge concentration risk.

Version 4.13.3 in SNAPSHOT development; recent work visible in the Maven plugin includes grammar dependency tracking (GrammarDependencies.java), error logging (Antlr4ErrorLog.java), and mojo task execution (Antlr4Mojo.java). The hosted.yml workflow indicates ongoing CI runs across macOS, Windows, and Linux. Maintenance is active but incremental rather than feature-heavy.

Clone and build the Maven-based project: git clone https://github.com/antlr/antlr4.git && cd antlr4 && mvn clean install. This builds the antlr4-maven-plugin and core tool. For immediate parser generation, install ANTLR CLI: mvn install creates an antlr-X.X.X-complete.jar executable. Then: java -jar antlr-X.X.X-complete.jar -Dlanguage=Java your-grammar.g4 to generate a parser.

Daily commands: Dev/test workflow: mvn clean test in root runs all unit tests across runtime targets. To test the Maven plugin specifically: cd antlr4-maven-plugin && mvn clean test. To regenerate parsers from grammars: mvn clean generate-sources (if configured in pom.xml). There is no 'dev server'—ANTLR is a code generation tool, not a runtime service.

• README.md — Entry point for understanding ANTLR's purpose, capabilities, and build status; all contributors must align with this vision.
• antlr4-maven-plugin/src/main/java/org/antlr/mojo/antlr4/Antlr4Mojo.java — Core Maven plugin orchestrator that drives grammar compilation; essential for understanding the build integration layer.
• antlr4-maven-plugin/pom.xml — Defines the plugin's dependencies and build configuration; critical for any changes to the Maven integration.
• CONTRIBUTING.md — Establishes contribution guidelines and conventions that all PRs must follow.
• doc/building-antlr.md — Documents the build process and project structure; essential for local development and CI/CD understanding.
• Package.swift — Defines Swift package dependencies and build configuration; critical for Swift target support.
• .github/workflows/hosted.yml — CI/CD pipeline configuration for cross-platform testing on macOS, Windows, and Linux.

Add Support for a New Target Language

1. Create a new target language documentation file in doc/ following the pattern of doc/cpp-target.md or doc/csharp-target.md (doc/new-language-target.md)
2. Implement the runtime library for your target language in a new runtime directory (pattern: runtime/YourLanguage/) (runtime/YourLanguage/src/main/...)
3. Create a new code generator template in the ANTLR tool that produces runtime code for your target (tool/src/org/antlr/v4/codegen/YourLanguageTarget.java)
4. Add integration tests to validate grammar compilation and runtime behavior for your target (antlr4-maven-plugin/src/test/projects/yourLanguageTest/pom.xml)

Add a New Maven Plugin Test Project

1. Create a new test project directory under antlr4-maven-plugin/src/test/projects/ (antlr4-maven-plugin/src/test/projects/myTestProject/pom.xml)
2. Define test grammar files in the standard location (antlr4-maven-plugin/src/test/projects/myTestProject/src/main/antlr4/test/MyGrammar.g4)
3. Add a test case to Antlr4MojoTest.java that exercises your scenario (antlr4-maven-plugin/src/test/java/org/antlr/mojo/antlr4/Antlr4MojoTest.java)

Extend Grammar Dependency Resolution

1. Review the current dependency resolution logic in GrammarDependencies.java (antlr4-maven-plugin/src/main/java/org/antlr/mojo/antlr4/GrammarDependencies.java)
2. Add new logic to handle custom import paths or dependency scenarios (antlr4-maven-plugin/src/main/java/org/antlr/mojo/antlr4/GrammarDependencies.java)
3. Create a corresponding test project under antlr4-maven-plugin/src/test/projects/ (antlr4-maven-plugin/src/test/projects/customDependencyScenario/pom.xml)
4. Add test case to Antlr4MojoTest.java to validate the new dependency resolution (antlr4-maven-plugin/src/test/java/org/antlr/mojo/antlr4/Antlr4MojoTest.java)

• Maven Plugin (Mojo) — Integrates grammar compilation seamlessly into Maven's build lifecycle; enables standard Java project workflows.
• Multi-language Runtime Libraries (Java, C++, C#, Go, Dart, JavaScript) — Allows ANTLR grammars to generate parsers and runtimes for diverse target platforms without rewriting grammar.
• Listener/Visitor Pattern — Decouples grammar-driven parsing from application logic; enables flexible tree traversal without modifying generated code.
• GitHub Actions CI/CD — Provides cross-platform (macOS, Windows, Linux) testing to ensure runtime compatibility across target languages.

• Grammar-based code generation rather than hand-coded parsing

  • Why: Shifts development effort from writing parsers to defining grammars; reduces bugs and maintenance burden.
  • Consequence: Requires learning ANTLR grammar syntax and understanding generated code structure; initial learning curve.

• Separate runtime libraries per target language

  • Why: Allows idiomatic, language-native implementations optimized for each platform.
  • Consequence: Maintenance burden increases with each supported language; potential for feature parity issues across runtimes.

• Maven plugin as primary build integration

  • Why: Aligns with Java ecosystem conventions; simplifies dependency management and grammar compilation ordering.
  • Consequence: Heavy coupling to Maven tooling; users of Gradle, Ant, or direct CLI must find alternative integration paths.

• Runtime execution of ANTLR grammars (compiles to native code only, does not interpret dynamically)
• IDE-agnostic text editor support (grammar editing relies on IDE plugins or external tools)
• Real-time grammar validation during development (not a language server implementation)
• Graphical grammar designer (text-based grammar format only)

Maven plugin requires ANTLR tool as a dependency (pom.xml parent); if parent pom.xml is not in sync, builds may fail silently. Grammar import resolution happens via classpath scanning—misplaced .g4 files in src/main/antlr4 won't be discovered. The 'dependencyRemoved' test project structure (imports/ subdirectory) suggests grammars in nested paths must match plugin configuration <imports> parameter or they're ignored. No environment variables required, but Maven version ≥3.8.5 is specified (see pom.xml); older Maven may have transitive dependency resolution issues.

• LL(*) Adaptive Parsing — ANTLR 4's core parsing strategy uses LL(*) with dynamic lookahead, which allows it to handle left-recursive rules and ambiguous grammars automatically—understanding this avoids writing non-deterministic grammars that fail or backtrack inefficiently.
• Parse Tree and Tree Walk Patterns (Listener vs. Visitor) — ANTLR generates both Listener (callback-driven) and Visitor (traversal-driven) interfaces for parse trees; choosing between them affects code structure and control flow in semantic analysis or code generation phases.
• Grammar Imports and Lexical Modes — ANTLR grammars can import other grammars and define lexical modes for context-specific tokenization (e.g., switching to string-literal mode); this enables modular grammar design and handling of embedded languages, visible in the GrammarDependencies.java tracking logic.
• Semantic Predicates and Gating — ANTLR allows embedded code in grammars ({...}? guards) to influence parsing decisions at runtime; misuse causes subtle bugs or performance cliffs—understanding when to apply them vs. post-parse semantic checking is critical.
• Multiple Target Language Code Generation — ANTLR generates parsers in 10 languages from a single grammar; the challenge is maintaining API consistency across targets (Java, C++, Python, etc.) while respecting each language's idioms—this is why version bumps can break compatibility.
• Incremental Compilation via Dependency Tracking — The Maven plugin (GrammarDependencies.java) tracks which .g4 files import which others to avoid regenerating unchanged parsers; incorrect dependency resolution causes stale parsers or unnecessary rebuilds in multi-grammar projects.
• Lexer vs. Parser Separation and Token Channels — ANTLR separates lexing and parsing explicitly; lexer rules (uppercase) create tokens; parser rules (lowercase) consume them. Token channels allow hiding whitespace/comments without losing them—essential for building ASTs that preserve source fidelity.

• tree-sitter/tree-sitter — Alternative parser generator using PEG grammars and C codegen; simpler learning curve but less grammar expressiveness than ANTLR's LL(*)
• antlr/grammars-v4 — Official repository of 300+ pre-written ANTLR grammars for real languages (Java, Python, SQL, JSON, etc.); reference implementations for grammar design and common patterns
• bison/bison — GNU's YACC-compatible parser generator for C/C++; older, production-proven alternative but limited to two languages and requires separate lexer
• lark-parser/lark — Python parsing toolkit supporting both EBNF and Earley algorithms; lighter-weight alternative for Python-only projects, embedded parsing without separate generation step
• antlr/antlr-intellij-plugin-v4 — IntelliJ IDEA plugin providing syntax highlighting, error checking, and live preview for ANTLR .g4 grammars; essential IDE companion for grammar development

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for antlr4-maven-plugin grammar dependency resolution

The antlr4-maven-plugin contains GrammarDependencies.java and Antlr4Mojo.java which handle complex grammar import logic, but there are only minimal tests in antlr4-maven-plugin/src/test/java/org/antlr/mojo/antlr4/Antlr4MojoTest.java. The test projects (dependencyRemoved, importTokens, importsCustom, importsStandard) suggest edge cases around grammar imports that need robust coverage to prevent regressions when handling cyclic dependencies, missing imports, and token resolution.

• [ ] Expand Antlr4MojoTest.java with parameterized tests for each test project scenario
• [ ] Add specific test cases for cyclic grammar imports (if not already covered)
• [ ] Add test cases for missing import resolution and error handling in GrammarDependencies.java
• [ ] Add test cases for token import scenarios documented in importTokens and importsCustom projects
• [ ] Verify all test projects in antlr4-maven-plugin/src/test/projects/ have corresponding unit test coverage

Add GitHub Actions workflow for Maven plugin cross-version compatibility testing

The hosted.yml workflow exists in .github/workflows/ but appears to focus on main ANTLR builds. The antlr4-maven-plugin declares mavenVersion=3.8.5 as a property and depends on plexus-compiler-api 2.12.1, but there's no CI verification that the plugin works correctly with different Maven versions (3.8.x, 3.9.x) or against different ANTLR tool versions. This is critical since the maven plugin is a separate release artifact.

• [ ] Create .github/workflows/maven-plugin-matrix.yml to test against Maven versions 3.8.5, 3.9.0+
• [ ] Add matrix build testing the plugin against multiple ANTLR runtime versions
• [ ] Run the integration tests from antlr4-maven-plugin/src/test/projects/ in the workflow
• [ ] Document the Maven version support matrix in antlr4-maven-plugin/README.md or pom.xml

Add documentation for antlr4-maven-plugin configuration options with code examples

The antlr4-maven-plugin has documentation in src/site/apt/ (usage.apt.vm, faq.apt.vm, examples/), but Antlr4Mojo.java shows several configuration parameters (@Parameter annotations) that may not be fully documented in the site docs. Additionally, there's no clear troubleshooting guide for the complex dependency resolution logic that GrammarDependencies.java handles.

• [ ] Review all @Parameter annotations in antlr4-maven-plugin/src/main/java/org/antlr/mojo/antlr4/Antlr4Mojo.java
• [ ] Create or update antlr4-maven-plugin/src/site/apt/configuration.apt with complete parameter reference including types, defaults, and examples
• [ ] Add troubleshooting section documenting common grammar import issues and solutions (cross-reference GrammarDependencies logic)
• [ ] Add code examples for advanced scenarios (custom output directories, token imports, import paths) to examples/ directory

• Add integration test for cyclic grammar import detection: antlr4-maven-plugin currently tracks imports via GrammarDependencies.java, but the test suite (antlr4-maven-plugin/src/test/projects/) lacks a test case for A.g4 → B.g4 → A.g4 cycles. Create a new test project in src/test/projects/cyclicImport/ with circular imports and verify the Mojo logs a clear error.
• Document the <imports> parameter behavior in antlr4-maven-plugin/src/site/apt/usage.apt.vm: currently unclear whether nested .g4 files in src/main/antlr4/foo/bar/Grammar.g4 require special configuration. Add an example showing relative path imports and file discovery rules.
• Add support for custom error listener configuration in Antlr4Mojo.java: currently Antlr4ErrorLog.java captures errors, but users cannot plug in custom ErrorListener implementations. Add a <errorListenerClass> parameter allowing users to specify a fully-qualified class name, load it via reflection, and pass it to the ANTLR tool invocation.

The ANTLR4 Maven plugin codebase shows reasonable security practices but has several areas for improvement. Primary concerns include outdated dependencies (particularly plexus-build-api from 2010 and old versions of Maven and Plexus components) that may contain known vulnerabilities. The use of snapshot versions in the project configuration is also a concern for reproducible builds. No hardcoded secrets, injection vulnerabilities, or critical misconfigurations were detected in the provided files. Regular dependency updates and moving to stable released versions are recommended.

• Medium · Outdated Maven Plugin API Dependency — antlr4-maven-plugin/pom.xml (maven-plugin-api dependency). The pom.xml specifies maven-plugin-api version 3.8.5, which may contain known vulnerabilities. Maven 3.8.5 was released in 2021 and newer versions with security patches are available. Fix: Update maven-plugin-api to the latest stable version (currently 3.9.x). Review Maven security advisories and update dependencies regularly.
• Low · Outdated Plexus Compiler API — antlr4-maven-plugin/pom.xml (plexus-compiler-api dependency). The plexus-compiler-api dependency version 2.12.1 is relatively old. Newer versions may contain security improvements and bug fixes. Fix: Update plexus-compiler-api to the latest available version and review the changelog for security-related fixes.
• Low · Old Plexus Build API Version — antlr4-maven-plugin/pom.xml (plexus-build-api dependency). The plexus-build-api dependency version 0.0.7 is significantly outdated (released around 2010). While this is a build-time dependency, it may contain unpatched vulnerabilities. Fix: Evaluate if plexus-build-api 0.0.7 is still necessary. If possible, upgrade to a newer version or replace with an actively maintained alternative. If no newer version exists, consider removing the dependency if unused.
• Low · Snapshot Version in Production Build — antlr4-maven-plugin/pom.xml (version property). The parent POM version is set to '4.13.3-SNAPSHOT', indicating the project is using snapshot/development versions. This should not be used for production releases. Fix: Use stable, released versions for production builds. Only use SNAPSHOT versions in development environments. Implement proper version management and CI/CD practices.
• Low · Missing Dependency Version Pinning — antlr4-maven-plugin/pom.xml (dependencies section). The pom.xml contains incomplete dependency declarations (see truncated comments). Version pinning for all transitive dependencies should be explicitly managed to prevent unexpected version changes. Fix: Use a Bill of Materials (BOM) or explicit dependency management to pin all transitive dependency versions. Add a dependencyManagement section if not present.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.