Apex Stubs Generator

Apex Stubs Generator

What stubs are and where they live

.cls stub files represent the Apex standard library (namespaces, classes, methods, enums). They live in two places:

• This repo: packages/apex-parser-ast/src/resources/StandardApexLibrary/
• jorje: apex-jorje/apex-jorje-lsp/src/main/resources/StandardApexLibrary/

Both copies must be kept in sync. The authoritative source is this repo's generator pipeline.

API generation pipeline

The generator lives in packages/apex-parser-ast/scripts/ and is the sole supported stub-generation process. It fetches Apex type definitions from the Salesforce Symbol Table API, then converts the resulting JSON into .cls files.

Running the generator

Prerequisites:

• Authenticate the Salesforce CLI to an org that exposes the Symbol Table API.
• The API is available on a 264 org farm or later.

cd packages/apex-parser-ast

# Fetch all available type definitions from the default org (gus), then generate stubs.
npm run update:stubs

# Rebuild the protobuf cache after generation.
npm run compile

To use another authenticated org, API version, or one namespace:

npm run fetch:api-stubs -- --org myorg
npm run fetch:api-stubs -- --api-version v68.0
npm run fetch:api-stubs -- --namespace System
npm run generate:api-stubs

The pipeline:

1. fetch-api-stubs.mjs discovers API namespaces and writes JSON to build/api-stubs/.
2. generate-api-stubs.mjs validates the captured input, replaces generated output for configured namespaces, and preserves hand-crafted builtins.
3. generate-stdlib-cache.mjs, run by npm run compile, parses the .cls files and writes the protobuf cache.

Key source files

Namespace name rules

Namespace names come from the API capture. TARGET_NAMESPACES in api-stub-config.mjs defines which namespaces are emitted to StandardApexLibrary/; remaining fetched namespaces remain available to the type registry without producing bundled .cls files.

These names become the output folder names under StandardApexLibrary/.

Visibility rule

Hand-crafted builtins are preserved during generation. The authoritative skip lists are BUILTIN_CLASSES and BUILTIN_NAMESPACED_CLASSES in generate-api-stubs.mjs.

macOS case-insensitive filesystem — critical pitfall

macOS has a case-insensitive filesystem. Git's index stores the real committed name, but ls and file reads on macOS silently fold case. This means:

• A committed file SoapType.cls and a file on disk named SOAPType.cls appear identical locally.
• On Linux CI (case-sensitive), they are different files — causing test failures that do not reproduce on macOS.

Rules for working with filenames

1. Always use git ls-tree -r HEAD to get the true committed names — never trust ls.
2. Renaming for case: always use a two-step git mv through a temp name:

   git mv OldName.cls OldName_tmp.cls
   git mv OldName_tmp.cls NewName.cls
   

3. Auditing mismatches — find all .cls files where committed name ≠ declared class name:

   git ls-tree -r HEAD --name-only "packages/apex-parser-ast/src/resources/StandardApexLibrary/" \
   | while read f; do
     base=$(basename "$f" .cls)
     declared=$(grep -m1 -oP '(?<=global (class|interface|enum) )\S+' "$f" 2>/dev/null)
     [ -n "$declared" ] && [ "$declared" != "$base" ] && echo "MISMATCH: $f -> $declared"
   done
   

4. Auditing directory name mismatches — compare committed dirs against TOC + overrides: use git ls-tree HEAD --name-only <path> then compare against NAMESPACE_NAME_OVERRIDES and the scraped TOC output.

Source of truth for casing

Snapshot test

packages/apex-parser-ast/test/generator/emptyStubDetection.snapshot.test.ts

Tracks which stubs have no members (empty bodies). Fails when:

• New stubs are added that happen to be empty
• A rename changes the class name captured in the snapshot

Update after intentional changes:

cd packages/apex-parser-ast
npx jest emptyStubDetection --updateSnapshot

macOS caveat: --updateSnapshot may report "1 passed" instead of "1 updated" when the local file read returns the wrong casing. Trust what CI sees — edit the snapshot directly if needed to match the correct committed name.

Syncing stubs to jorje

After regenerating stubs in this repo, the same files must be copied to: apex-jorje/apex-jorje-lsp/src/main/resources/StandardApexLibrary/

jorje's branch conventions and build process are separate — sync is a manual copy of the StandardApexLibrary/ tree, then build/test in jorje.