BREAKING: Move to antlr4 runtime for Typescript

.github/workflows/Build.yml

@@ -17,15 +17,18 @@ jobs:
       - name: Set up Node
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
 
-      - name: Set up JDK 8
+      - name: Set up JDK
         uses: actions/setup-java@v4
         with:
           distribution: "temurin"
-          java-version: 8
+          java-version: 11
           cache: "maven"
 
+      - name: Init
+        run: npm run init
+
       - name: Build & Test
         run: npm run build
 
@@ -35,11 +38,10 @@ jobs:
           submodules: recursive
           repository: apex-dev-tools/apex-samples
           path: apex-samples
-          ref: v1.2.0
+          ref: v1.3.0
 
       - name: Set samples env
         run: echo "SAMPLES=$GITHUB_WORKSPACE/apex-samples" >> "$GITHUB_ENV"
 
       - name: System Test
-        run: npm run test-samples
-        working-directory: npm
+        run: npm run systest

.github/workflows/PublishMaven.yml

@@ -14,12 +14,12 @@ jobs:
       - name: Set up Node
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
 
       - name: Set up Maven Central Repository
         uses: actions/setup-java@v4
         with:
-          java-version: "8"
+          java-version: 11
           distribution: "temurin"
           cache: "maven"
           server-id: ossrh
@@ -30,7 +30,7 @@ jobs:
 
       - name: Publish package
         run: |
-          npm run init-jvm
+          npm run init:jvm
           cd jvm
           mvn --batch-mode deploy
         env:

.github/workflows/PublishNPM.yml

@@ -14,12 +14,13 @@ jobs:
       - name: Set up Node
         uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 22
           registry-url: "https://registry.npmjs.org"
 
       - name: Publish package
         run: |
-          npm run build-npm
+          npm run init:npm
+          npm run build:npm
           cd npm
           npm publish --access public
         env:

.gitignore

@@ -1,2 +1,3 @@
 .metals/
 .vscode/
+node_modules/

.husky/.gitignore

@@ -0,0 +1 @@
+_

.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

.npmrc

@@ -0,0 +1,2 @@
+# Override user private registry back to default
+registry=https://registry.npmjs.org

CHANGELOG.md

@@ -1,5 +1,29 @@
 # apex-parser - Changelog
 
+## 5.0.0
+
+- (BREAKING) Migrated from `antlr4ts` to official `antlr4` runtime package.
+  - Some lesser used methods are missing in the type definitions, refer to the [antlr4 Javascript code](https://github.com/antlr/antlr4/tree/dev/runtime/JavaScript/src/antlr4) if you need to cast types.
+  - `extends` is now required to use antlr `Listener`/`Visitor` types.
+    - Exception being to avoid the property initialisation syntax in the antlr generated types:
+
+      ```apex
+      class MyListener extends ParseTreeListener implements ApexParserListener {
+        // with 'extends ApexParserListener' you must write this
+        enterMethodDeclaration = () => {}
+
+        // this requires 'extends ParseTreeListener implements ApexParserListener'
+        enterMethodDeclaration() {}
+      }
+      ```
+
+- (BREAKING) Updated output to `ES2020` and increased min node version to 16.
+- (BREAKING) Updated to ANTLR `4.13.2` across both distributions. Same tool now generates both.
+- (BREAKING) Re-exported antlr types removed, add `antlr4` package dep instead matching apex-parser version.
+- Typescript `CaseInsensitiveInputStream` type now extends `CharStream` and can be constructed from `string`.
+  - Constructor passing in `Charstream` retained to match Java version.
+- Removed `node-dir` dependency - replaced with node fs api.
+
 ## 4.4.0 - 2024-12-14
 
 - Support `TimeLiteral` for `Time` fields, e.g. `WHERE TimeField__c = 01:00:00.000Z` for SOQL queries

README.md

@@ -1,44 +1,29 @@
 # apex-parser
 
-Parser for Salesforce Apex (including Triggers & inline SOQL/SOQL). This is based on an [ANTLR4](https://www.antlr.org/) grammar, see antlr/ApexParser.g4.
+Parser for Salesforce Apex (including Triggers & inline SOQL/SOQL). This is based on an [ANTLR4](https://www.antlr.org/) grammar, see [`antlr/BaseApexParser.g4`](./antlr/BaseApexParser.g4).
 
 There are two builds of the parser available, a NPM module for use with Node and a Maven package for use on JVMs.
 
 These builds just contain the Parser & Lexer and provides no further support for analysing the generated parse trees beyond what is provided by ANTLR4.
 
-As Apex & SOQL/SOQL are case-insenstive languages you need to use the provided CaseInsensitiveInputStream for the parser to function correctly. When parsing Apex, inline SOQL/SOSL is automtaically parsed, but you can also parse SOQL/SOQL directly. You can find some minimal examples in the test classes.
+As Apex & SOQL/SOQL are case-insenstive languages you need to use the provided `CaseInsensitiveInputStream` for the parser to function correctly. When parsing Apex, inline SOQL/SOSL is automatically parsed, but you can also parse SOQL/SOQL directly. You can find some minimal examples in the test classes.
 
 ## Example
 
 To parse a class file (NPM version):
 
 ```typescript
-import { CharStreams } from "antlr4ts";
+import { CommonTokenStream } from "antlr4";
+import { ApexLexer, ApexParser, CaseInsensitiveInputStream } from "@apexdevtools/apex-parser";
 
-const stream = CharStreams.fromString("public class Hello {}");
-let lexer = new ApexLexer(new CaseInsensitiveInputStream(stream));
-let tokens  = new CommonTokenStream(lexer);
+const lexer = new ApexLexer(new CaseInsensitiveInputStream("public class Hello {}"));
+const tokens = new CommonTokenStream(lexer);
 
-let parser = new ApexParser(tokens);
-let context = parser.compilationUnit();
+const parser = new ApexParser(tokens);
+const context = parser.compilationUnit();
 ```
 
-The 'context' is a CompilationUnitContext object which is the root of the parsed representation of the class. You can access the parse tree via functions on it.
-
-## Unicode handling
-
-Prior to 2.12.0 the use of ANTLRInputStream for reading data in CaseInsensitiveStream would result character positions being given for UTF-16. The switch to CharStream input in 2.12.0 for JVM and 2.14.0 for node results in character positions reflecting Unicode code points.
-
-## antlr4ts versions
-
-The npm module uses antlr4ts 0.5.0-alpha.4, this was updated from 0.5.0-alpha.3 in the 2.9.1 version. You should make
-sure that if you are using a matching versions of this dependency if you use it directly. To avoid issues you can
-import 'CommonTokenStream' & 'ParseTreeWalker' from 'apex-parser' instead of from antlr4ts.
-
-```typescript
-import { CommonTokenStream} from "apex-parser";
-import { ParseTreeWalker } from "apex-parser";
-```
+The `context` is a `CompilationUnitContext` object which is the root of the parsed representation of the class. You can access the parse tree via functions on it.
 
 ## SOSL FIND quoting
 
@@ -48,51 +33,83 @@ SOSL FIND uses ' as a quoting character when embedded in Apex, in the API braces
 Find {something} RETURNING Account
 ```
 
-To parse the API format there is an alternative parser rule, soslLiteralAlt, that you can use instead of soslLiteral. See SOSLParserTest for some examples of how these differ.
+To parse the API format there is an alternative parser rule, `soslLiteralAlt`, that you can use instead of `soslLiteral`. See `SOSLParserTest` for some examples of how these differ.
 
-## Packages
+## Installation
 
-Maven
+### Maven
 
 ```xml
 <dependency>
     <groupId>io.github.apex-dev-tools</groupId>
     <artifactId>apex-parser</artifactId>
-    <version>4.4.0</version>
+    <version><!-- version --></version>
 </dependency>
 ```
 
-NPM
+### NPM
 
-```json
-{
-  "@apexdevtools/apex-parser": "^4.4.0"
-}
+```sh
+# install antlr4 to reference runtime types
+# must match version used by parser
+npm i antlr4 @apexdevtools/apex-parser
 ```
 
-## Building
+## Development
+
+### Prerequisites
+
+- JDK 11+ (for ANTLR tool)
+- Maven
+- NodeJS LTS
 
-To build both distributions:
+### Building
+
+The outer package contains scripts to build both distributions:
 
 ```shell
+# Run once - installs deps
+npm run init
+
+# Build & test distributions
 npm run build
 ```
 
-## Testing
+### Testing
+
+#### Unit Tests
 
-Unit tests are executed during the respective package builds. The system tests require both packages to be built, as the js test also spawns the jar version. They use a collection of sample projects located in the [apex-samples](https://github.com/apex-dev-tools/apex-samples) repository. Follow the README instructions in apex-samples to checkout the submodules. To run the tests:
+Options for testing:
+
+```shell
+# From root, build & test each
+npm run build:npm
+npm run build:jvm
+
+# From ./npm
+npm run build
+npm test
+
+# From ./jvm
+mvn test
+```
+
+#### System Tests
+
+The system tests use a collection of sample projects located in the [`apex-samples`](https://github.com/apex-dev-tools/apex-samples) repository. Follow the README instructions in `apex-samples` to checkout the submodules at the version tag used by the [build workflow](.github/workflows/Build.yml). Both packages must be built beforehand, as the js system test spawns the jar as well.
+
+To run the tests:
 
 ```shell
 # Set SAMPLES env var to samples repo location
 export SAMPLES=<abs path to apex-samples>
 
-# Exec test script
-npm run test-samples
+# From root dir
+npm run build
+npm run systest
 ```
 
-System test failures relating to the snapshots may highlight regressions. Though if an error is expected or the samples have changed, instead use `npm run test-snapshot` to update the snapshots, then commit the changes.
-
-The tag version of apex-samples used by builds is set in the [build file](.github/workflows/Build.yml).
+System test failures relating to the snapshots may highlight regressions. Though if an error is expected or the samples have changed, instead use `npm run systest:update` to update the snapshots, then commit the changes.
 
 ## Source & Licenses
 

antlr/ApexLexer.g4 → antlr/BaseApexLexer.g4

@@ -40,10 +40,6 @@
  */
 lexer grammar ApexLexer;
 
-@lexer::members {
-    public void clearCache() {_interp.clearDFA();}
-}
-
 channels {
     WHITESPACE_CHANNEL,
     COMMENT_CHANNEL

antlr/ApexParser.g4 → antlr/BaseApexParser.g4

@@ -39,11 +39,6 @@
  *  $ grun Apexcode compilationUnit *.cls
  */
 parser grammar ApexParser;
-options {tokenVocab=ApexLexer;}
-
-@parser::members {
-    public void clearCache() {_interp.clearDFA();}
-}
 
 // entry point for Apex trigger files
 triggerUnit

jvm/.lintstagedrc.json

@@ -0,0 +1,3 @@
+{
+  "*.java": "prettier --write"
+}

jvm/.prettierrc

@@ -0,0 +1,3 @@
+{
+  "plugins": ["prettier-plugin-java"]
+}

jvm/antlr/ApexLexer.g4

@@ -0,0 +1,7 @@
+lexer grammar ApexLexer;
+
+@lexer::members {
+public void clearCache() {_interp.clearDFA();}
+}
+
+import BaseApexLexer;

jvm/antlr/ApexParser.g4

@@ -0,0 +1,8 @@
+parser grammar ApexParser;
+options {tokenVocab=ApexLexer;}
+
+@parser::members {
+public void clearCache() {_interp.clearDFA();}
+}
+
+import BaseApexParser;