# Build the official TypeScript grammar for Rust
The official grammars-v4 TypeScript lexer and parser use grammar-specific
stateful actions and predicates, including the argument-taking `p("of")` and
`n("get"|"set")` helpers. This repository routes those calls through generated
typed Rust hooks and keeps the target-specific state in copyable base modules.
## Prerequisites
- Rust 1.95 or newer
- Java 17 or newer
- ANTLR 4.13.2
- `antlr/grammars-v4` at the pinned parity commit
```bash
ANTLR4_JAR=/tmp/antlr-cleanroom/tools/antlr-4.13.2-complete.jar
ANTLR_JAR_SHA256=eae2dfa119a64327444672aff63e9ec35a20180dc5b8090b7a6ab85125df4d76
mkdir -p /tmp/antlr-cleanroom/tools
curl -fLo "$ANTLR4_JAR" \
https://www.antlr.org/download/antlr-4.13.2-complete.jar
echo "${ANTLR_JAR_SHA256} ${ANTLR4_JAR}" | shasum -a 256 -c -
git clone --filter=blob:none --no-checkout \
https://github.com/antlr/grammars-v4.git \
/tmp/antlr-cleanroom/grammars-v4
git -C /tmp/antlr-cleanroom/grammars-v4 sparse-checkout init --cone
git -C /tmp/antlr-cleanroom/grammars-v4 sparse-checkout set javascript/typescript
git -C /tmp/antlr-cleanroom/grammars-v4 checkout \
284602b3f23ca54dc30778204ab7ae9e969145e9
```
## Generate ANTLR metadata
Run the ANTLR tool on the unmodified split grammar. The generated Java files
can be ignored; the Rust generator consumes the `.interp` metadata and the
original `.g4` sources.
```bash
GRAMMAR=/tmp/antlr-cleanroom/grammars-v4/javascript/typescript
BUILD=/tmp/antlr-cleanroom/typescript-rust
JAR=/tmp/antlr-cleanroom/tools/antlr-4.13.2-complete.jar
mkdir -p "$BUILD/interp" "$BUILD/lexer" "$BUILD/parser"
(
cd "$GRAMMAR"
java -jar "$JAR" -o "$BUILD/interp" -Xexact-output-dir \
TypeScriptLexer.g4 TypeScriptParser.g4
)
```
## Generate strict Rust modules
From this repository's root:
```bash
cargo run --locked --release --bin antlr4-rust-gen -- \
--lexer "$BUILD/interp/TypeScriptLexer.interp" \
--grammar "$GRAMMAR/TypeScriptLexer.g4" \
--sem-patterns patterns/javascript.toml \
--sem-unknown error \
--require-full-semantics \
--out-dir "$BUILD/lexer"
cargo run --locked --release --bin antlr4-rust-gen -- \
--parser "$BUILD/interp/TypeScriptParser.interp" \
--grammar "$GRAMMAR/TypeScriptParser.g4" \
--sem-patterns patterns/javascript.toml \
--sem-unknown error \
--require-full-semantics \
--out-dir "$BUILD/parser"
```
Every authored action and predicate is either translated or routed to a typed
hook. Do not pass `--allow-unsupported-lexer-actions`: the TypeScript base needs
all template, brace, strict-mode, regex, and token-lookaround helpers to retain
the official grammar's behavior.
Copy these files into an application crate:
- `$BUILD/lexer/type_script_lexer.rs`
- `$BUILD/parser/type_script_parser.rs`
- `tests/typescript-parity/dumper/src/typescript_lexer_base.rs`
- `tests/typescript-parity/dumper/src/typescript_parser_base.rs`
The base files are examples rather than runtime modules. Adjust their module
paths if the generated files do not live under `generated` in the application.
## Construct the typed lexer and parser
```rust
use antlr4_runtime::{CommonTokenStream, InputStream, Parser};
use generated::type_script_lexer::TypeScriptLexer;
use generated::type_script_parser::TypeScriptParser;
use typescript_lexer_base::TypeScriptLexerBase;
use typescript_parser_base::TypeScriptParserBase;
let source = "interface Box<T> { value: T }";
let lexer = TypeScriptLexer::with_typed_hooks(
InputStream::new(source),
TypeScriptLexerBase::with_strict_default(false),
);
let tokens = CommonTokenStream::new(lexer);
let mut parser = TypeScriptParser::with_typed_hooks(tokens, TypeScriptParserBase);
let tree = parser.program().expect("TypeScript parses");
assert_eq!(parser.number_of_syntax_errors(), 0);
assert!(!tree.text().is_empty());
```
`program()` is the compilation-unit entry rule. The lexer base tracks the last
default-channel token, strict scopes, brace depth, and nested template depth.
The parser base implements visible lookahead/lookbehind for `n(...)` and
`p(...)`, automatic-semicolon-insertion checks, and the TypeScript
open-brace/function/interface guard.
For lower-level diagnostics, fill a `CommonTokenStream` and call
`drain_source_errors()` before parsing, or inspect
`Parser::number_of_syntax_errors()` after the entry rule.
The generator intentionally omits `--require-generated-parser`. Rules outside
the direct recursive-descent compiler use the faithful runtime ATN interpreter,
which receives the same typed hooks.
## Run the repository proof
```bash
tests/typescript-parity/run.sh \
--antlr-jar "$JAR" \
--grammars-v4 /tmp/antlr-cleanroom/grammars-v4
```
The harness regenerates the Rust recognizers and the official Java target, then
compares tokens and parse trees for every fixture under
`tests/typescript-parity/snippets/`.