@jwikman/bc-code-intelligence-mcp 1.5.7-dev.1

package/embedded-knowledge/domains/roger-reviewer/case-statement-error-handling-troubleshooting.md

@@ -0,0 +1,115 @@
+---
+title: "Case Statement Error Handling and Troubleshooting"
+domain: "roger-reviewer"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["case", "error-handling", "troubleshooting", "debugging"]
+samples: "samples/case-error-handling.md"
+---
+# Case Statement Error Handling and Troubleshooting
+
+## Overview
+
+Effective error handling in case statements prevents runtime failures and provides meaningful user feedback when unexpected values occur. Understanding common error patterns and troubleshooting approaches ensures robust BC applications with predictable behavior.
+
+**Error Handling Philosophy**: Always include ELSE clauses for comprehensive error coverage and provide specific error messages that help users understand and resolve issues.
+
+## Common Error Scenarios
+- **Unhandled Values**: Case expression produces values not covered by any branch
+- **Type Mismatches**: Runtime type conflicts between expression and case values  
+- **Null References**: Accessing null objects or uninitialized variables in case expressions
+- **Range Violations**: Numeric values outside expected ranges in range-based cases
+
+Implementing comprehensive error handling prevents production failures and enables graceful degradation.
+
+## Defensive Programming Patterns
+
+### Mandatory ELSE Clauses
+Always include ELSE clauses to handle unexpected values. Robust error handling includes comprehensive case coverage while risky implementations omit ELSE clauses, leading to silent failures for unexpected values.
+
+### Input Validation Before Case Evaluation
+Validate inputs before case processing to prevent invalid data from reaching case evaluation. Check for blank values, uninitialized state indicators, and other invalid conditions before entering case logic.
+
+### Null Reference Prevention
+Implement null checking before case evaluation using record retrieval patterns. Verify record existence and field validity before accessing case expression values to prevent runtime null reference errors.
+
+## Error Message Best Practices
+
+### Informative Error Messages
+Provide context and actionable information in error messages. Specify valid ranges, current values, and field names to help users understand and resolve issues. Avoid generic messages that provide no actionable guidance.
+
+### User-Friendly Error Context
+Include business context in error messages by referencing business concepts and supported operations. List valid options and explain operational constraints to guide user behavior.
+
+### Localized Error Messages
+Use label constants for localized error messages with proper comment annotations. This enables multi-language support and maintains consistent error messaging across the application.
+
+## Advanced Error Handling Patterns
+
+### Graceful Degradation
+Implement fallback behavior instead of hard failures by logging issues and continuing with default processing. This approach maintains system operation while capturing diagnostic information.
+
+### Error Recovery Strategies
+Attempt recovery before failing by implementing data repair mechanisms. Check for recoverable conditions and provide alternative processing paths when primary validation fails.
+
+### State-Based Error Handling
+Handle errors based on current system state by validating state-specific conditions. Reset to safe states when invalid conditions are detected and provide context-appropriate error messages.
+
+## Debugging and Troubleshooting Techniques
+
+### Diagnostic Logging
+Add diagnostic logging for troubleshooting by recording case expression values and processing decisions. Log entry points, branch selections, and error conditions to support production debugging.
+
+### Execution Tracing
+Trace case statement execution using configurable debug settings. Record case evaluation start points and branch execution to understand control flow during debugging scenarios.
+
+### Boundary Value Testing
+Test boundary conditions explicitly by handling edge cases like zero values and range limits. Log boundary violations for analysis and provide clear error messages for invalid ranges.
+
+## Production Error Monitoring
+
+### Error Telemetry Collection
+Collect error telemetry for production monitoring by recording success metrics, partial success conditions, and failure scenarios. Track unknown result conditions separately for analysis.
+
+### Health Check Integration
+Integrate case statement health into system health checks by validating logic integrity. Monitor system modes and log critical errors when unknown states are detected.
+
+## Common Troubleshooting Scenarios
+
+### Value Type Mismatches
+Handle type comparison errors by ensuring consistent data types between case expressions and value literals. Text fields require text literals, not integer values.
+
+### Enum Synchronization Issues
+Handle enum extensions and version mismatches by providing default processing for unknown enum values. Log warnings for new values and implement graceful fallback behavior.
+
+### Performance-Related Error Patterns
+Avoid performance-related failures by implementing timeout mechanisms for complex operations. Set processing limits and provide appropriate error messages when limits are exceeded.
+
+## CodeCop Compliance Considerations
+
+### Official AL Guidelines Conflict
+
+**Important Note**: Error handling patterns in this topic conflict with Microsoft's CodeCop rules AA0005, AA0074, and AA0137.
+
+This represents the tension between robust error handling and strict code compliance:
+
+#### AA0074: Error Message TextConst Requirements
+- **CodeCop Compliance**: All error messages must use TextConst variables with approved suffixes
+- **Robust Error Handling**: Direct string literals allow for dynamic, contextual error messages
+
+#### AA0005: Error Handling Block Structure
+- **CodeCop Compliance**: Minimal BEGIN..END usage in case branches
+- **Error Handling Approach**: Consistent block structure for complex error scenarios
+
+#### AA0137: Error Handling Variables
+- **CodeCop Compliance**: Avoid declaring variables that may not be used in all error paths
+- **Defensive Programming**: Pre-declare error handling variables for consistent behavior
+
+### Team Decision Framework
+
+Consider these factors when choosing your approach:
+- **Localization Requirements**: TextConst variables are essential for multi-language applications
+- **Error Message Complexity**: Dynamic messages may require direct string construction
+- **Debugging Support**: Consistent error handling structure aids in troubleshooting
+- **Compliance vs. Robustness**: Balance between CodeCop compliance and comprehensive error handling
+

package/embedded-knowledge/domains/roger-reviewer/compound-statement-readability.md

@@ -0,0 +1,124 @@
+---
+title: "AL Compound Statement Readability Patterns"
+domain: "roger-reviewer"
+difficulty: "beginner"
+bc_versions: "14+"
+tags: ["readability", "compound-statements", "code-style", "maintainability"]
+prerequisites: ["al-syntax-basics"]
+samples: "samples/compound-statement-readability.md"
+---
+# AL Compound Statement Readability Patterns
+
+## Overview
+
+AL compound statements with begin-end blocks significantly enhance code readability and maintainability, even when syntactically optional. This pattern transforms single statements into structured blocks that communicate intent clearly and provide natural extension points for future development.
+
+The readability benefit becomes pronounced in conditional logic, loop constructs, and error handling scenarios where the logical grouping of statements improves code comprehension. Modern AL development emphasizes explicit structure over implicit behavior to reduce cognitive load during code review and maintenance activities.
+
+Professional AL codebases consistently apply compound statement patterns to establish clear visual boundaries around logical operations. This approach reduces the mental parsing required to understand code flow and makes the developer's intent explicit rather than implicit.
+
+## Core Readability Principles
+
+### Visual Structure Enhancement
+
+Compound statements create clear visual boundaries that separate logical blocks from surrounding code. The begin-end pairing acts as visual punctuation that helps developers quickly identify the scope and extent of conditional or iterative operations.
+
+When scanning AL code, developers can immediately recognize compound blocks without parsing individual statements to determine scope boundaries. This visual clarity becomes particularly valuable in complex procedures with multiple nested conditions or loops.
+
+The consistent application of compound statements creates a predictable visual rhythm in AL code that experienced developers can navigate efficiently. Code reviews benefit from this consistency as reviewers can focus on logic rather than parsing scope boundaries.
+
+### Intent Communication
+
+Compound statements explicitly communicate that a logical operation may expand in the future. Even single-statement blocks signal to other developers that the code author considered the possibility of additional statements within that logical context.
+
+This explicit intent prevents future developers from inadvertently introducing bugs when adding statements to what appeared to be simple single-statement conditions. The compound block structure anticipates natural code evolution and provides safe extension points.
+
+The presence of compound statements also indicates careful consideration of code structure rather than rushed implementation. This signals code quality and maintenance attention to future developers working with the codebase.
+
+### Consistency Benefits
+
+Applying compound statements consistently across an AL codebase eliminates decision fatigue around when to use block structure. Developers don't need to evaluate each situation individually - the pattern applies universally to conditional and iterative constructs.
+
+Consistent compound statement usage creates a unified coding style that multiple developers can follow without extensive style guide consultation. The pattern becomes automatic and reduces variability in code structure across team members.
+
+This consistency particularly benefits large AL projects where multiple developers contribute to the same procedures and tables over time. The uniform structure makes code ownership transitions smoother and reduces onboarding time for new team members.
+
+## Implementation Strategies
+
+### Conditional Logic Enhancement
+
+Transform all conditional statements into compound blocks regardless of current statement count. This approach ensures that adding new statements to conditional branches doesn't require restructuring existing code or risk introducing scope-related bugs.
+
+Apply this pattern to if-then-else constructs, case statements, and exception handling blocks. Each logical branch receives begin-end delimiters even when containing single statements, creating consistent structure across all conditional logic.
+
+The compound block approach becomes particularly valuable in business logic implementations where requirements frequently evolve and additional validation or processing steps need insertion into existing conditional paths.
+
+### Loop Structure Clarification
+
+Use compound statements for all loop constructs including for, while, and repeat-until statements. The begin-end blocks clearly delineate loop body boundaries and prevent common errors when adding statements to loop iterations.
+
+This pattern proves especially important in AL report processing and data migration scenarios where loop bodies frequently require enhancement as business requirements evolve. The compound structure provides safe insertion points without scope ambiguity.
+
+Loop compound statements also improve debugging experiences by providing clear breakpoint locations and logical step boundaries during code execution analysis.
+
+### Error Handling Organization
+
+Apply compound statements to all exception handling blocks and error processing logic. The structured approach creates clear separation between normal processing flow and error recovery operations.
+
+Even single-statement error handlers benefit from compound block structure as error handling logic frequently requires expansion to include logging, user notification, or recovery operations as applications mature.
+
+The compound pattern in error handling also establishes consistent structure for team members implementing exception handling across different areas of the AL application.
+
+## Best Practices
+
+### Automatic Application
+
+Treat compound statements as the default choice for all conditional and iterative constructs rather than evaluating each situation individually. This automatic application eliminates inconsistency and reduces cognitive overhead during code writing.
+
+Configure development environments and code formatting tools to automatically insert begin-end blocks when creating conditional or loop constructs. This automation ensures pattern consistency without requiring conscious decision-making.
+
+The automatic approach also supports code generation scenarios where templates and snippets consistently produce well-structured AL code that follows compound statement patterns.
+
+### Team Adoption Strategies
+
+Establish compound statements as a team coding standard documented in development guidelines. Include rationale and examples to help team members understand the benefits beyond syntactic correctness.
+
+Use code review processes to reinforce compound statement adoption and provide gentle correction when developers use single-statement alternatives. Focus on the maintainability benefits rather than strict rule enforcement.
+
+Consider implementing automated formatting or linting tools that can detect and suggest compound statement opportunities during the development process.
+
+## CodeCop Compliance Considerations
+
+### Official AL Guidelines Conflict
+
+**Important Note**: The patterns described in this topic conflict with Microsoft's official AL CodeCop rule AA0005, which states "Only use BEGIN..END to enclose compound statements." CodeCop will flag single-statement begin-end blocks as violations.
+
+This represents an active debate in the AL community between two valid approaches:
+- **CodeCop Compliance**: Minimal syntax, using begin-end only when multiple statements are present
+- **Maintainability Focus**: Consistent structure, using begin-end universally for future-proofing
+
+Teams must decide their approach based on project requirements, tool integration, and development philosophy. Some teams disable AA0005 to prioritize maintainability, while others follow CodeCop strictly for compliance with Microsoft's official guidelines.
+
+### Team Decision Framework
+
+Consider these factors when choosing your approach:
+- **Tool Integration**: Whether CodeCop compliance is required for your deployment pipeline
+- **Team Size**: Larger teams may benefit more from consistent structure patterns
+- **Code Longevity**: Long-lived codebases may prioritize future-proofing over minimal syntax
+- **Organizational Standards**: Whether company coding standards require CodeCop compliance
+
+## Common Misconceptions
+
+### Performance Impact Concerns
+
+Some developers worry that compound statements introduce performance overhead through additional syntax processing. In reality, AL compilation optimizes begin-end blocks and produces identical runtime performance regardless of compound statement usage.
+
+The compiler treats single statements and compound blocks identically during optimization phases, so readability improvements come without runtime costs. This makes compound statements purely beneficial from both maintenance and performance perspectives.
+
+### Verbosity Objections
+
+Developers occasionally resist compound statements as unnecessary verbosity that clutters code with syntactic overhead. However, the readability and maintainability benefits far outweigh the minimal additional syntax required.
+
+The perceived verbosity diminishes quickly as developers adapt to the consistent visual structure. Most teams find that compound statements actually improve reading speed once the pattern becomes familiar.
+
+Modern development practices prioritize code clarity over character count minimization, making compound statements align with contemporary software development philosophy.

package/embedded-knowledge/domains/roger-reviewer/lonely-repeat-statement-pattern.md

@@ -0,0 +1,110 @@
+---
+title: "Lonely Repeat Statement Pattern"
+domain: "roger-reviewer"
+difficulty: "beginner"
+bc_versions: "14+"
+tags: ["code-formatting", "repeat-statement", "readability", "code-standards"]
+prerequisites: ["al-syntax-basics", "control-structures"]
+samples: "samples/lonely-repeat-examples.md"
+---
+
+# Lonely Repeat Statement Pattern
+
+## Overview
+
+The "lonely repeat" anti-pattern occurs when a `repeat` keyword appears isolated on its own line without the associated `until` condition being visually connected. This formatting choice reduces code readability and violates AL formatting conventions.
+
+**Core Issue**: Isolated `repeat` statements create visual disconnection from their terminating conditions, making control flow harder to follow.
+
+## Pattern Definition
+
+### Lonely Repeat Structure
+```
+// Anti-pattern: Lonely repeat
+repeat
+    // statements
+until condition;
+```
+
+**Problem**: The `repeat` keyword lacks visual connection to its scope and terminating condition.
+
+### Preferred Formatting
+```
+// Preferred: Connected repeat block
+repeat
+    // statements
+until condition;
+```
+
+**Solution**: Maintain visual connection between `repeat`, statement block, and `until` condition through consistent indentation and spacing.
+
+## Formatting Standards
+
+### Standard AL Formatting Rules
+- **Consistent indentation**: `repeat` aligns with containing scope
+- **Statement block indentation**: Contents indented one level from `repeat`
+- **Until alignment**: `until` aligns with `repeat` keyword
+- **Condition formatting**: Condition on same line as `until` when concise
+
+### Visual Readability Principles
+- **Scope boundaries**: Clear visual indication of repeat block extent
+- **Flow connection**: Visual link between control keyword and condition
+- **Consistent spacing**: Uniform spacing patterns across all repeat statements
+
+## Common Violations
+
+```
+// Violation: Extra blank lines and misaligned until
+repeat
+
+    ProcessRecord();
+    until EOF;
+
+// Violation: Complex condition on same line
+repeat
+    ProcessRecord();
+until (Counter > MaxRecords) and (not ErrorOccurred) and ValidateData();
+```
+
+**Problems**: Unnecessary blank lines break visual flow, misaligned `until` breaks connection with `repeat` scope, and complex conditions reduce readability.
+
+## Best Practice Patterns
+
+### Simple Repeat Blocks
+```
+// Best practice: Clean, aligned structure
+repeat
+    ProcessNextRecord();
+    Counter += 1;
+until (Counter > MaxRecords) or EOF;
+```
+
+### Complex Condition Formatting
+```
+// Best practice: Multi-line complex conditions
+repeat
+    ProcessRecord();
+    ValidateData();
+until (Counter > MaxRecords) and
+     (not ErrorOccurred) and
+     ValidateCompleted;
+```
+
+### Nested Repeat Handling
+```
+// Best practice: Clear nesting structure
+repeat
+    repeat
+        ProcessSubRecord();
+    until SubRecordComplete;
+    FinalizeRecord();
+until AllRecordsProcessed;
+```
+
+## Implementation
+
+Use AL formatting tools for automated detection and establish team formatting standards with code review enforcement.
+
+*Complete formatting examples: samples/lonely-repeat-examples.md*
+*AL formatting standards: roger-reviewer-index.json#formatting-rules*
+*Automated formatting setup: sam-coder-index.json#formatting-configuration*