apex-language

Apex Language Support

Hard Rule: Semantic Facts Come Only from Semantic Infrastructure

Never scan raw Apex source text with regular expressions or other text heuristics to infer or recover semantic facts. This prohibition includes synthesizing symbols, declarations, types, references, scopes, member ownership, completion candidates, definition targets, and dependency or missing-artifact names.

Use grammar-derived parser contexts, tree walkers, symbol tables, resolved references/xref data, or a prior stable semantic snapshot. Raw document text may be supplied to the lexer/parser and used for document transport or position/range mechanics, but it must not be independently interpreted as a semantic fallback. If semantic state is unavailable, incomplete, or stale, preserve that uncertainty: wait, retry, or return an incomplete result. Never invent semantic state from source text.

ANTLR Grammar Reference

The Apex parser uses ANTLR grammar files that are not bundled in the module. Reference them from GitHub:

Grammar Files Location:

Repository: https://github.com/apex-dev-tools/apex-parser/tree/main/antlr
Parser Grammar: BaseApexParser.g4 - Defines parser rules (compilationUnit, classDeclaration, methodDeclaration, etc.)
Lexer Grammar: BaseApexLexer.g4 - Defines tokenization rules

Key Grammar Rules:

compilationUnit - Entry point for Apex class files
triggerUnit - Entry point for trigger files
anonymousUnit - Entry point for anonymous Apex blocks
classDeclaration, interfaceDeclaration, enumDeclaration - Type declarations
methodDeclaration, constructorDeclaration - Method/constructor declarations
Expression rules (left-recursive notation)

When implementing listeners or validators, reference the grammar to understand:

Available parser rule contexts (e.g., ClassDeclarationContext, MethodDeclarationContext)
Rule structure and child nodes
Token types and keywords

Core Apex Language Rules

No Import Statements

Apex has no import statements—never generate or expect them. The compiler resolves types by:

Searching the current namespace
Then the global namespace
Then other installed namespaces

Fully qualified names (<namespace>.<TypeName>) are used only when a name conflict exists; otherwise, use the unqualified name.

Important: A namespace and a type in that namespace can share the same name (e.g., Acme.Acme) and this is valid. Namespace is determined by org/package metadata, not declared in code.

Modifiers and Keywords

Final and Virtual:

Classes and methods are final by default (cannot be extended/overridden)
Cannot use final keyword on classes or methods (syntax error)
Use virtual keyword to make classes/methods extensible/overridable
final keyword can only be used for variables (prevents reassignment)

Example:

// Correct: Normal class (final by default)
public class MyClass { }

// Incorrect: Cannot use 'final' keyword on classes
public final class MyClass { }  // Syntax error!

// Correct: Virtual class (can be extended)
public virtual class MyClass { }

// Correct: Final variable
public final Integer count = 5;

File Types and Entry Points

.cls files: Use compilationUnit parser rule
.trigger files: Use triggerUnit parser rule
.apex files: Use anonymousUnit parser rule (wrapped in block)

Test Artifacts

The Apex language grammar only allows a single top-level type within the same file. When creating test artifacts:

Do not place more than one top-level type in a test artifact unless the test is expressly designed to test that validation condition
Test artifacts should follow the same single-type-per-file rule as production code
Only create multi-type test files when specifically testing the parser/validator's handling of multiple top-level types

Parser Listener Pattern

BaseApexParserListener

All custom listeners extend BaseApexParserListener<T>:

import { BaseApexParserListener } from './BaseApexParserListener';
import { ClassDeclarationContext } from '@apexdevtools/apex-parser';

export class MyListener extends BaseApexParserListener<MyResultType> {
  enterClassDeclaration(ctx: ClassDeclarationContext): void {
    // Handle class declaration entry
  }

  exitClassDeclaration(ctx: ClassDeclarationContext): void {
    // Handle class declaration exit
  }

  // Override getResult() to return your result
  getResult(): MyResultType {
    return this.result;
  }
}

Listener Methods

Listener methods correspond to parser rules:

enter* methods: Called when entering a rule context
exit* methods: Called when exiting a rule context
Method names match grammar rule names (camelCase)

Common Context Types:

ClassDeclarationContext - Class declarations
MethodDeclarationContext - Method declarations
ConstructorDeclarationContext - Constructor declarations
VariableDeclaratorContext - Variable declarations
ExpressionContext - Expressions
StatementContext - Statements

Using Listeners with CompilerService

import { CompilerService } from '@salesforce/apex-lsp-parser-ast';
import { MyListener } from './MyListener';

const compiler = new CompilerService();
const listener = new MyListener();
const result = compiler.compile(fileContent, fileName, listener);

// Access result
const myResult = result.result;
const errors = result.errors;
const warnings = result.warnings;

Leveraging Parser Rules

Understanding Rule Contexts

Each parser rule generates a context class with:

Child nodes accessible via properties
Token access via start/stop tokens
Location information for error reporting

Example:

enterMethodDeclaration(ctx: MethodDeclarationContext): void {
  // Access method name
  const methodName = ctx.id()?.text;
  
  // Access return type
  const returnType = ctx.typeRef()?.text;
  
  // Access modifiers
  const modifiers = ctx.modifier();
  
  // Access location for errors
  const location = {
    start: ctx.start.line,
    end: ctx.stop?.line,
  };
}

Finding Available Rules

To discover available parser rules:

Check the grammar file: BaseApexParser.g4
Look for rule names (e.g., methodDeclaration, classDeclaration)
Generated context types follow pattern: {RuleName}Context
Import from @apexdevtools/apex-parser

Common Patterns

Scope Tracking:

export class ScopeTrackingListener extends BaseApexParserListener<SymbolTable> {
  private scopeStack: ApexSymbol[] = [];

  enterClassDeclaration(ctx: ClassDeclarationContext): void {
    const classSymbol = this.createClassSymbol(ctx);
    const blockSymbol = this.createBlockSymbol('class', ctx);
    this.scopeStack.push(blockSymbol);
  }

  exitClassDeclaration(): void {
    this.scopeStack.pop();
  }

  getCurrentScope(): ApexSymbol {
    return this.scopeStack[this.scopeStack.length - 1];
  }
}

Error Reporting:

enterMethodDeclaration(ctx: MethodDeclarationContext): void {
  if (this.errorListener) {
    this.errorListener.addError({
      message: 'Custom error message',
      line: ctx.start.line,
      column: ctx.start.charPositionInLine,
    });
  }
}

Validation Patterns

TIER 1 (Immediate) Validators

Fast, same-file validations that run on every keystroke (<500ms):

Parameter limits (max 32)
Enum limits (max 100)
Duplicate detection
Naming validation
Forward reference validation

TIER 2 (Thorough) Validators

Comprehensive validations that may require cross-file analysis:

Method signature equivalence
Interface/class hierarchy validation
Cross-file type resolution

Error Codes and Messages

When working with semantics and validation, error codes and messages must be aligned with the Salesforce org compiler.

Error Messages Reference:

Source File: packages/apex-parser-ast/src/resources/messages/messages_en_US.properties
- Contains all error codes and messages (English) used by the Salesforce compiler
- Format: error.code.key=Error message text with {0} placeholders
Generated TypeScript Files (auto-generated, do not edit manually):
- packages/apex-parser-ast/src/generated/ErrorCodes.ts - Error code constants
- packages/apex-parser-ast/src/generated/messages_en_US.ts - Error message mappings

Workflow for Adding New Error Codes:

Check for existing error code: First, search messages_en_US.properties to see if an appropriate error code already exists
If a new error code is needed: Ask the user for permission before proceeding
- Present the proposed error code key and message
- Explain why a new code is needed vs. using an existing one
- Wait for explicit user approval before making changes
Edit the properties file: After receiving permission, add your new error code to messages_en_US.properties
```
my.new.error.code=Error message text with {0} placeholder
```
Regenerate TypeScript files: Run npm run precompile in packages/apex-parser-ast
- This generates ErrorCodes.ts and messages_en_US.ts from the properties file
- The generated files are used by validators for type-safe error code references

Use in validators: Import and use the generated constants

import { ErrorCodes } from '../generated/ErrorCodes';
// Use ErrorCodes.MY_NEW_ERROR_CODE in your validator

Critical: When implementing validators that require error reporting, if you determine that a new error code needs to be created, you must ask the user for permission before proceeding. Do not create new error codes without explicit user approval.

When to Consult This File:

Before introducing a new error code: Check if an appropriate error code already exists
When choosing an error code: Search the file to find the correct code for your validation
When writing error messages: Use existing messages or follow the same format/style
When implementing validators: Ensure error codes match Salesforce compiler behavior

Example Error Codes:

invalid.void.parameter - Parameters cannot be of type void
unreachable.statement - Unreachable statement
invalid.constructor.return - Constructors must not return a value
invalid.super.call - Call to 'super()' must be the first statement in a constructor method

Important: Always consult messages_en_US.properties when:

Adding new validation logic that needs error reporting
Choosing which error code to use for a validation failure
Ensuring consistency with Salesforce compiler error messages
Adding a new error code: Update .properties file, then run npm run precompile to regenerate TS files

Validator Implementation

Validators can use listeners to traverse parse trees:

import { BaseApexParserListener } from '../../../parser/listeners/BaseApexParserListener';

class MyValidatorListener extends BaseApexParserListener<void> {
  enterMethodDeclaration(ctx: MethodDeclarationContext): void {
    // Validate method
    if (ctx.parameterList()?.parameter().length > 32) {
      this.addError('Too many parameters');
    }
  }
}

Additional Resources

Grammar Files: https://github.com/apex-dev-tools/apex-parser/tree/main/antlr
Parser Package: @apexdevtools/apex-parser (v4.4.1+)
Project README: packages/apex-parser-ast/README.md - Comprehensive architecture documentation
Existing Listeners: packages/apex-parser-ast/src/parser/listeners/ - Reference implementations