@cparra/apex-reflection 4.0.0-beta.4 → 4.0.0-beta.6

package/README.md

@@ -11,13 +11,12 @@ npm i @cparra/apex-reflection
 ## Usage
 
 This library exposes a single function that handles parsing the body of an Apex top level type (class, interface, or
-enum)
-and returns the result.
+enum) and returns the result.
 
 ```typescript
-import {reflect} from '@cparra/apex-reflection';
+import { reflect } from "@cparra/apex-reflection";
 
-const classBody = 'public with sharing class ExampleClass {}';
+const classBody = "public with sharing class ExampleClass {}";
 const response = reflect(classBody);
 ```
 
@@ -34,23 +33,33 @@ const response = reflect(rawFile.toString());
 ```
 
 The `reflect` function returns a `ReflectionResult` which contains either the results of the parsed `Type`
-(which will either be a `ClassMirror`, an `InterfaceMirror` or an `EnumMirror`) or a `ParsingError` if the passed in
+(which will either be a `ClassMirror`, an `InterfaceMirror`, or an `EnumMirror`) or a `ParsingError` if the passed in
 body was not parsed successfully, with a message indicating where the error occurred.
 
 ## Contributing
 
 Even though this library is exposed as a Node.js library, the project's source code is written in Dart. The source can
-be found in the `lib/src` directory.
+be found in the `lib/src` directory of the repository.
+
+This package ships the Dart code compiled to a WebAssembly module (`dist/node.wasm`) together with its JS loader
+(`dist/node.mjs`), loaded lazily by the thin TypeScript wrapper in `index.mts`. Node.js 22 or newer is required (the
+module uses WasmGC). To rebuild the module after changing the Dart source, run from the repository root:
+
+```shell
+dart compile wasm lib/src/node/node.dart -o js/node.wasm
+```
+
+`npm run build` compiles the TypeScript wrapper and copies the wasm module and its loader into `dist/`.
 
 ### Tests
 
-Both the Dart source code and the JS output must be tested.
+Both the Dart source code and the packaged WebAssembly module must be tested.
 
-The Dart tests live in the `test` directory. The Dart source code must have unit tests testing each individual Dart file
-as well as end-to-end tests that verify the overall parsing functionality.
+The Dart tests live in the repository's `test` directory. The Dart source code must have unit tests testing each
+individual Dart file as well as end-to-end tests that verify the overall parsing functionality.
 
-The JS tests live in `js/apex-reflection-node/__tests__`. These are end-to-end tests that ensure that the transpiled JS
-code is working as intended.
+The JS tests live in `__tests__`. These are end-to-end tests that run against the built package (`dist/`), so they
+also guard against publishing a stale WebAssembly artifact. Run them with `npm test`.
 
 ### JSON serialization
 
@@ -62,27 +71,16 @@ helps automatically create the round-trip code for serialization and de-serializ
 
 When changing any of the model classes with serialization support, to re-build the serialization code run
 
-```
-pub run build_runner build
-```
-
-### Parsing
-
-The parsing algorithm relies on using ANTLR4 and its Dart target. Currently `dart2js` is not able to transpile the
-source from the `antrl4` library hosted in pub.dev, so we rely on a local copy that fixes the transpilation issues,
-which lives in `lib/antrl4-4.9.2`.
-
-To generate the Antlr4 Apex output run:
-
 ```shell
-antlr4 -Dlanguage=Dart lib/src/antlr/grammars/apex/ApexLexer.g4 lib/src/antlr/grammars/apex/ApexParser.g4 -o lib/src/antlr/lib/apex/
+dart run build_runner build
 ```
 
-To generate the Antlr4 Apexdoc output run:
+### Parsing
 
-```shell
-antlr4 -Dlanguage=Dart lib/src/antlr/grammars/apexdoc/ApexdocLexer.g4 lib/src/antlr/grammars/apexdoc/ApexdocParser.g4 -o lib/src/antlr/lib/apexdoc/
-```
+Parsing is implemented with handwritten [petitparser](https://pub.dev/packages/petitparser) grammars. 
+The Apex grammar parses only the declaration structure needed for reflection (bodies are skipped as
+balanced blocks), and the Apexdoc grammar is composed into it, so doc comments are parsed in the same single pass. See
+the repository README for details.
 
 ## Typescript
 

package/dist/index.d.mts

@@ -29,6 +29,11 @@ export interface DocComment {
     descriptionLines: string[];
     description: string;
     error?: string;
+    /**
+     * True when the comment contains an `{@hidden}` inline tag, meaning the
+     * documented element should be excluded from generated documentation.
+     */
+    hidden?: boolean;
 }
 export interface AnnotationElementValue {
     key: string;

package/dist/node.mjs

@@ -222,7 +222,6 @@ class CompiledApp {
       _217: (o, p) => o[p],
       _218: (o, p, v) => o[p] = v,
       _220: o => o instanceof Array,
-      _227: (a, s) => a.join(s),
       _231: a => a.length,
       _233: (a, i) => a[i],
       _239: o => o instanceof Uint8Array,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cparra/apex-reflection",
-  "version": "4.0.0-beta.4",
+  "version": "4.0.0-beta.6",
   "description": "Provides tools for reflecting Apex code, the language used in Salesforce development.",
   "main": "dist/index.mjs",
   "scripts": {