feat(codegen): add TestRig command

README.md

@@ -107,6 +107,46 @@ antlr4-rust-gen \
 Use multiple roots when a build should emit several independent recognizers in
 one deterministic source-set compilation.
 
+### Run a grammar with TestRig
+
+TestRig can run directly from a grammar-only project. The project does not need
+a `Cargo.toml`, generated Rust sources, or a runtime dependency; it only needs a
+Rust toolchain because TestRig invokes Cargo internally. Install the companion
+command from the codegen package:
+
+```bash
+cargo install antlr-rust-codegen --bin antlr4-rust-testrig
+```
+
+From the grammar project, pass a combined grammar, its parser start rule, and
+zero or more UTF-8 inputs. With no input files the command reads stdin:
+
+```bash
+antlr4-rust-testrig JSON.g4 json --tokens --tree examples/*.json
+echo '{"ok":true}' | antlr4-rust-testrig JSON json --tree
+```
+
+For a lexer grammar, use the special start rule `tokens`. Pair split grammars
+with `--lexer-grammar` and the same import directories used for generation:
+
+```bash
+antlr4-rust-testrig MyGrammarParser.g4 start \
+  --lexer-grammar MyGrammarLexer.g4 \
+  --lib grammar \
+  tests/valid/*.txt
+```
+
+`--trace`, `--diagnostics`, and `--sll` expose the corresponding parser modes.
+Each invocation generates the recognizer and a grammar-specific runner in a
+temporary Cargo package, selects the matching `antlr-rust-runtime` release, and
+removes the generated package afterward. Cargo build artifacts are reused, so
+the first invocation can take longer while dependencies and the runner compile.
+
+TestRig processes every named input and returns a non-zero status when
+generation, temporary runner compilation, input reading, lexing, or parsing
+fails. Recovered lexer and parser syntax errors therefore fail CI even when a
+parse tree was produced.
+
 ### Generated-source/runtime compatibility
 
 Every newly generated lexer and parser contains a compile-time generated-code

crates/antlr-rust-codegen/Cargo.toml

@@ -1,18 +1,18 @@
 [package]
-name = "antlr-rust-codegen"
-version.workspace = true
-edition.workspace = true
-rust-version.workspace = true
-description = "ANTLR v4 grammar compiler and Rust source generator"
-repository.workspace = true
-homepage.workspace = true
-documentation = "https://docs.rs/antlr-rust-codegen"
-license.workspace = true
+categories             = ["development-tools::build-utils", "parser-implementations", "parsing"]
+description            = "ANTLR v4 grammar compiler and Rust source generator"
+documentation          = "https://docs.rs/antlr-rust-codegen"
+edition.workspace      = true
+homepage.workspace     = true
+include                = ["/Cargo.toml", "/README.md", "/src/**"]
+keywords               = ["antlr", "antlr4", "codegen", "lexer", "parser"]
+license.workspace      = true
 license-file.workspace = true
-readme = "README.md"
-keywords = ["antlr", "antlr4", "codegen", "parser", "lexer"]
-categories = ["development-tools::build-utils", "parser-implementations", "parsing"]
-include = ["/Cargo.toml", "/README.md", "/src/**"]
+name                   = "antlr-rust-codegen"
+readme                 = "README.md"
+repository.workspace   = true
+rust-version.workspace = true
+version.workspace      = true
 
 [lib]
 name = "antlr_rust_codegen"
@@ -22,10 +22,14 @@ path = "src/lib.rs"
 name = "antlr4-rust-gen"
 path = "src/bin/antlr4-rust-gen.rs"
 
+[[bin]]
+name = "antlr4-rust-testrig"
+path = "src/bin/antlr4-rust-testrig.rs"
+
 [dependencies]
-antlr-rust-runtime.workspace = true
 antlr-rust-g4-parser.workspace = true
 antlr-rust-rs-parser.workspace = true
+antlr-rust-runtime.workspace = true
 clap = { version = "4.6.5", default-features = false, features = [
     "cargo",
     "derive",
@@ -43,8 +47,8 @@ petgraph = { version = "0.8.3", default-features = false, features = ["std"] }
 thiserror.workspace = true
 
 [dev-dependencies]
-hmac-sha256 = "1"
-insta.workspace = true
+hmac-sha256      = "1"
+insta.workspace  = true
 memchr.workspace = true
 
 [lints]

crates/antlr-rust-codegen/README.md

@@ -39,6 +39,31 @@ Or install the command:
 cargo install antlr-rust-codegen --bin antlr4-rust-gen
 ```
 
+The package also provides `antlr4-rust-testrig` for running a grammar directly
+against UTF-8 files or stdin. A grammar-only project needs no `Cargo.toml`,
+generated Rust sources, or runtime dependency; only a Rust toolchain is
+required because TestRig invokes Cargo internally:
+
+```bash
+cargo install antlr-rust-codegen --bin antlr4-rust-testrig
+antlr4-rust-testrig JSON.g4 json --tokens --tree example.json
+```
+
+Use `tokens` as the start rule for a lexer grammar. For split grammars, pass
+the parser grammar first and pair it with `--lexer-grammar`:
+
+```bash
+antlr4-rust-testrig MyParser.g4 start \
+    --lexer-grammar MyLexer.g4 --lib grammar inputs/*.txt
+```
+
+The command generates and compiles a temporary grammar-specific runner with the
+matching runtime because Rust cannot reflectively load recognizer types or call
+a rule by name. It removes the temporary package afterward while retaining
+Cargo build artifacts for subsequent invocations. It processes every input and
+exits non-zero if generation, compilation, input reading, lexing, or parsing
+reports an error, so the same command can be used as a test runner.
+
 The runtime, codegen, and internal parser packages are released in lockstep.
 
 ## Internal module ownership

crates/antlr-rust-codegen/src/bin/antlr4-rust-testrig.rs

@@ -0,0 +1,3 @@
+fn main() -> Result<std::process::ExitCode, Box<dyn std::error::Error>> {
+    antlr_rust_codegen::run_testrig_cli()
+}

crates/antlr-rust-codegen/src/builder.rs

@@ -239,6 +239,7 @@ impl Builder {
             prune_unreachable: self.prune_unreachable,
             optimize_precedence_ladders: self.optimize_precedence_ladders,
             report_precedence_ladders: self.report_precedence_ladders,
+            test_rig: None,
         })
     }
 }

crates/antlr-rust-codegen/src/cli.rs

@@ -154,6 +154,7 @@ impl CliArgs {
             prune_unreachable: self.prune_unreachable,
             optimize_precedence_ladders: self.optimize_precedence_ladders,
             report_precedence_ladders: self.report_precedence_ladders,
+            test_rig: None,
         })
     }
 }

crates/antlr-rust-codegen/src/config.rs

@@ -3,6 +3,11 @@ use std::path::PathBuf;
 
 use crate::semantics::{SemPatternFile, SemUnknownPolicy};
 
+#[derive(Debug)]
+pub(crate) struct TestRigConfig {
+    pub(crate) start_rule: String,
+}
+
 #[derive(Debug)]
 pub(crate) struct CompilerConfig {
     pub(crate) roots: Vec<PathBuf>,
@@ -31,4 +36,6 @@ pub(crate) struct CompilerConfig {
     pub(crate) optimize_precedence_ladders: bool,
     /// Analyze the same pass on a shadow model and emit only its manifest.
     pub(crate) report_precedence_ladders: bool,
+    /// Emit a temporary-crate entry point for `antlr4-rust-testrig`.
+    pub(crate) test_rig: Option<TestRigConfig>,
 }

crates/antlr-rust-codegen/src/driver.rs

@@ -9,6 +9,9 @@ use crate::semantics::{
     enforce_require_full_options, enforce_require_full_semantics, enforce_sem_unknown,
     grammar_option_warning_messages, render_decisions_manifest, render_semantics_manifest,
 };
+use crate::test_rig::{
+    MAIN_PATH as TEST_RIG_MAIN_PATH, TestRigLexer, TestRigParser, render_test_rig,
+};
 
 pub(crate) fn generate(
     args: &CompilerConfig,
@@ -71,6 +74,8 @@ pub(crate) fn generate(
     let mut rendered_modules = BTreeMap::<PathBuf, String>::new();
     let mut emitted_lexers = BTreeSet::new();
     let mut emitted_parsers = BTreeSet::new();
+    let mut test_rig_lexers = Vec::new();
+    let mut test_rig_parsers = Vec::new();
 
     for root in &compilation.roots {
         if let Some(grammar) = root.lexer
@@ -104,6 +109,9 @@ pub(crate) fn generate(
             );
             let module = render_lexer_model(&render_model)?;
             insert_rendered_module(&mut rendered_modules, &grammar_name, module)?;
+            if args.test_rig.is_some() {
+                test_rig_lexers.push(TestRigLexer::new(grammar_name.clone()));
+            }
             manifest_grammars.push(("lexer", grammar_name, entries));
         }
 
@@ -141,6 +149,12 @@ pub(crate) fn generate(
                 },
             )?;
             insert_rendered_module(&mut rendered_modules, &grammar_name, module)?;
+            if args.test_rig.is_some() {
+                test_rig_parsers.push(TestRigParser::new(
+                    grammar_name.clone(),
+                    data.rule_names.clone(),
+                ));
+            }
             decision_report_grammars.push(DecisionReportGrammar {
                 name: grammar_name.clone(),
                 rule_names: data.rule_names.clone(),
@@ -174,6 +188,12 @@ pub(crate) fn generate(
     } else {
         artifacts.remove_if_present("optimizations.json")?;
     }
+    if let Some(test_rig) = &args.test_rig {
+        artifacts.insert(
+            TEST_RIG_MAIN_PATH,
+            render_test_rig(&test_rig.start_rule, &test_rig_lexers, &test_rig_parsers)?,
+        )?;
+    }
     let outputs = artifacts.write_to(&args.out_dir)?;
     Ok(Generation::new(inputs, outputs, warnings, diagnostics))
 }

crates/antlr-rust-codegen/src/lib.rs

@@ -17,6 +17,8 @@ mod parser;
 mod rust_output;
 mod semantics;
 mod structural;
+mod test_rig;
+mod testrig_cli;
 
 pub use artifact::Generation;
 pub use builder::{ActionMode, Builder, UnknownSemanticPolicy};
@@ -47,3 +49,9 @@ pub(crate) use structural::{structural_embedded_model, structural_predicates};
 pub fn run_cli() -> Result<(), Box<dyn std::error::Error>> {
     cli::run_cli()
 }
+
+/// Runs the `antlr4-rust-testrig` command using the process arguments.
+#[doc(hidden)]
+pub fn run_testrig_cli() -> Result<std::process::ExitCode, Box<dyn std::error::Error>> {
+    testrig_cli::run_cli()
+}

crates/antlr-rust-codegen/src/snapshots/antlr_rust_codegen__test_rig__tests__lexer_runner_rendered.snap

@@ -0,0 +1,131 @@
+---
+source: crates/antlr-rust-codegen/src/test_rig.rs
+expression: rendered
+---
+#![allow(clippy::print_stderr, clippy::print_stdout)]
+
+#[path = "../demo_lexer.rs"]
+mod generated_lexer;
+
+use generated_lexer::DemoLexer;
+
+use std::ffi::OsString;
+use std::fs::File;
+use std::io;
+use std::path::PathBuf;
+use std::process::ExitCode;
+
+use antlr4_runtime::{CommonTokenStream, InputStream};
+
+#[allow(dead_code)] // Parser-only flags remain accepted for lexer-only TestRig invocations.
+#[derive(Clone, Copy, Debug, Default)]
+struct Options {
+    tokens: bool,
+    tree: bool,
+    trace: bool,
+    diagnostics: bool,
+    sll: bool,
+}
+
+fn main() -> ExitCode {
+    match run() {
+        Ok(true) => ExitCode::SUCCESS,
+        Ok(false) => ExitCode::FAILURE,
+        Err(error) => {
+            eprintln!("error: {error}");
+            ExitCode::FAILURE
+        }
+    }
+}
+
+fn run() -> Result<bool, Box<dyn std::error::Error>> {
+    let (options, input_files) = options_and_inputs()?;
+    if input_files.is_empty() {
+        let stdin = io::stdin();
+        let input = InputStream::from_reader(stdin.lock())?;
+        return process(input, options);
+    }
+
+    let show_names = input_files.len() > 1;
+    let mut success = true;
+    for input_file in input_files {
+        let path = PathBuf::from(input_file);
+        if show_names {
+            eprintln!("{}", path.display());
+        }
+        match process_file(&path, options) {
+            Ok(input_success) => success &= input_success,
+            Err(error) => {
+                eprintln!("error: {}: {error}", path.display());
+                success = false;
+            }
+        }
+    }
+    Ok(success)
+}
+
+fn process_file(
+    path: &std::path::Path,
+    options: Options,
+) -> Result<bool, Box<dyn std::error::Error>> {
+    let input = InputStream::from_reader_with_source_name(
+        File::open(path)?,
+        path.display().to_string(),
+    )?;
+    process(input, options)
+}
+
+fn options_and_inputs() -> io::Result<(Options, Vec<OsString>)> {
+    let mut options = Options::default();
+    let mut inputs = Vec::new();
+    let mut arguments = std::env::args_os().skip(1);
+    while let Some(argument) = arguments.next() {
+        match argument.to_str() {
+            Some("--tokens") => options.tokens = true,
+            Some("--tree") => options.tree = true,
+            Some("--trace") => options.trace = true,
+            Some("--diagnostics") => options.diagnostics = true,
+            Some("--sll") => options.sll = true,
+            Some("--") => {
+                inputs.extend(arguments);
+                break;
+            }
+            _ => {
+                return Err(io::Error::new(
+                    io::ErrorKind::InvalidInput,
+                    format!("unexpected runner argument {}", argument.to_string_lossy()),
+                ));
+            }
+        }
+    }
+    Ok((options, inputs))
+}
+
+fn report_lexer_errors<L: antlr4_runtime::TokenSource>(
+    tokens: &mut CommonTokenStream<L>,
+) -> usize {
+    tokens.fill();
+    let count = tokens.number_of_source_errors();
+    for error in tokens.drain_source_errors() {
+        if !tokens.token_source().report_error(&error) {
+            eprintln!("line {}:{} {}", error.line, error.column, error.message);
+        }
+    }
+    count
+}
+
+
+fn process(
+    input: InputStream,
+    options: Options,
+) -> Result<bool, Box<dyn std::error::Error>> {
+    let lexer = DemoLexer::new(input);
+    let mut tokens = CommonTokenStream::try_new(lexer)?;
+    let lexer_errors = report_lexer_errors(&mut tokens);
+    if options.tokens {
+        for token in tokens.tokens() {
+            println!("{token}");
+        }
+    }
+    Ok(lexer_errors == 0)
+}