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: 1. Searching the current namespace 2. Then the global namespace 3. 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:** ```apex // 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>`: ```typescript 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 ```typescript 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:** ```typescript 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: 1. Check the grammar file: `BaseApexParser.g4` 2. Look for rule names (e.g., `methodDeclaration`, `classDeclaration`) 3. Generated context types follow pattern: `{RuleName}Context` 4. Import from `@apexdevtools/apex-parser` ### Common Patterns **Scope Tracking:** ```typescript 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:** ```typescript 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:** 1. **Check for existing error code**: First, search `messages_en_US.properties` to see if an appropriate error code already exists 2. **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 3. **Edit the properties file**: After receiving permission, add your new error code to `messages_en_US.properties` ```properties my.new.error.code=Error message text with {0} placeholder ``` 4. **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 5. **Use in validators**: Import and use the generated constants ```typescript 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: 1. Adding new validation logic that needs error reporting 2. Choosing which error code to use for a validation failure 3. Ensuring consistency with Salesforce compiler error messages 4. **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: ```typescript 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