bc-code-intelligence-mcp 1.1.1

package/embedded-knowledge/domains/roger-reviewer/samples/lonely-repeat-examples.md

@@ -0,0 +1,280 @@
+# Lonely Repeat Statement Pattern - AL Code Examples
+
+## Overview
+The "Lonely Repeat Statement Pattern" refers to repeat-until loops that are difficult to read due to poor formatting, unclear conditions, or lack of proper structure. This sample demonstrates how to identify and fix these patterns in AL code.
+
+## Problem Pattern: Lonely and Hard-to-Read Repeat Statements
+
+### Example 1: Basic Formatting Issues
+
+**Problematic Code:**
+```al
+procedure ProcessCustomerRecords()
+var
+    Customer: Record Customer;
+    Counter: Integer;
+begin
+    Customer.FindFirst();
+    repeat Customer.CalcFields("Sales (LCY)"); if Customer."Sales (LCY)" > 10000 then begin Counter += 1; Message('High value customer: %1', Customer.Name); end; until Customer.Next() = 0;
+end;
+```
+
+**Improved Code:**
+```al
+procedure ProcessCustomerRecords()
+var
+    Customer: Record Customer;
+    Counter: Integer;
+begin
+    if Customer.FindFirst() then
+        repeat
+            Customer.CalcFields("Sales (LCY)");
+            if Customer."Sales (LCY)" > 10000 then begin
+                Counter += 1;
+                Message('High value customer: %1', Customer.Name);
+            end;
+        until Customer.Next() = 0;
+end;
+```
+
+### Example 2: Complex Condition Handling
+
+**Problematic Code:**
+```al
+procedure ValidateItemInventory()
+var
+    Item: Record Item;
+    InventorySetup: Record "Inventory Setup";
+    IsValid: Boolean;
+begin
+    Item.SetRange(Blocked, false);
+    Item.FindFirst();
+    repeat IsValid := true; Item.CalcFields(Inventory); if (Item.Inventory < Item."Reorder Point") and (Item."Reorder Point" > 0) and (Item."Replenishment System" = Item."Replenishment System"::Purchase) then IsValid := false; if not IsValid then Error('Item %1 needs reordering', Item."No."); until Item.Next() = 0;
+end;
+```
+
+**Improved Code:**
+```al
+procedure ValidateItemInventory()
+var
+    Item: Record Item;
+    NeedsReordering: Boolean;
+begin
+    Item.SetRange(Blocked, false);
+    if Item.FindFirst() then
+        repeat
+            Item.CalcFields(Inventory);
+
+            NeedsReordering := (Item.Inventory < Item."Reorder Point") and
+                              (Item."Reorder Point" > 0) and
+                              (Item."Replenishment System" = Item."Replenishment System"::Purchase);
+
+            if NeedsReordering then
+                Error('Item %1 needs reordering', Item."No.");
+        until Item.Next() = 0;
+end;
+```
+
+## Advanced Pattern Improvements
+
+### Example 3: Nested Loop Clarity
+
+**Problematic Code:**
+```al
+procedure RecalculateCustomerStatistics()
+var
+    Customer: Record Customer;
+    SalesLine: Record "Sales Line";
+    TotalAmount: Decimal;
+begin
+    Customer.FindFirst();
+    repeat TotalAmount := 0; SalesLine.SetRange("Sell-to Customer No.", Customer."No."); if SalesLine.FindFirst() then repeat TotalAmount += SalesLine."Line Amount"; until SalesLine.Next() = 0; Customer."Sales (LCY)" := TotalAmount; Customer.Modify(); until Customer.Next() = 0;
+end;
+```
+
+**Improved Code:**
+```al
+procedure RecalculateCustomerStatistics()
+var
+    Customer: Record Customer;
+    SalesLine: Record "Sales Line";
+    TotalAmount: Decimal;
+begin
+    if Customer.FindFirst() then
+        repeat
+            TotalAmount := 0;
+            SalesLine.SetRange("Sell-to Customer No.", Customer."No.");
+
+            if SalesLine.FindFirst() then
+                repeat
+                    TotalAmount += SalesLine."Line Amount";
+                until SalesLine.Next() = 0;
+
+            Customer."Sales (LCY)" := TotalAmount;
+            Customer.Modify();
+        until Customer.Next() = 0;
+end;
+```
+
+### Example 4: Error Handling in Repeat Loops
+
+**Problematic Code:**
+```al
+procedure PostSalesDocuments()
+var
+    SalesHeader: Record "Sales Header";
+    SalesPost: Codeunit "Sales-Post";
+begin
+    SalesHeader.SetRange("Document Type", SalesHeader."Document Type"::Order);
+    SalesHeader.SetRange(Status, SalesHeader.Status::Released);
+    SalesHeader.FindFirst();
+    repeat if not SalesPost.Run(SalesHeader) then Message('Error posting document %1', SalesHeader."No."); until SalesHeader.Next() = 0;
+end;
+```
+
+**Improved Code:**
+```al
+procedure PostSalesDocuments()
+var
+    SalesHeader: Record "Sales Header";
+    SalesPost: Codeunit "Sales-Post";
+    DocumentsProcessed: Integer;
+    DocumentsFailed: Integer;
+begin
+    SalesHeader.SetRange("Document Type", SalesHeader."Document Type"::Order);
+    SalesHeader.SetRange(Status, SalesHeader.Status::Released);
+
+    if SalesHeader.FindFirst() then
+        repeat
+            Clear(SalesPost);
+            if SalesPost.Run(SalesHeader) then
+                DocumentsProcessed += 1
+            else begin
+                DocumentsFailed += 1;
+                Message('Error posting document %1: %2', SalesHeader."No.", GetLastErrorText());
+            end;
+        until SalesHeader.Next() = 0;
+
+    Message('Processing complete. Posted: %1, Failed: %2', DocumentsProcessed, DocumentsFailed);
+end;
+```
+
+## Performance and Safety Patterns
+
+### Example 5: Large Dataset Processing
+
+**Problematic Code:**
+```al
+procedure ArchiveOldEntries()
+var
+    GLEntry: Record "G/L Entry";
+    ArchiveEntry: Record "G/L Entry Archive";
+begin
+    GLEntry.SetFilter("Posting Date", '<%1', CalcDate('-2Y', Today()));
+    GLEntry.FindFirst();
+    repeat ArchiveEntry.TransferFields(GLEntry); ArchiveEntry.Insert(); GLEntry.Delete(); until GLEntry.Next() = 0;
+end;
+```
+
+**Improved Code:**
+```al
+procedure ArchiveOldEntries()
+var
+    GLEntry: Record "G/L Entry";
+    ArchiveEntry: Record "G/L Entry Archive";
+    ProcessedCount: Integer;
+    BatchSize: Integer;
+begin
+    BatchSize := 1000; // Process in batches for better performance
+    ProcessedCount := 0;
+
+    GLEntry.SetFilter("Posting Date", '<%1', CalcDate('-2Y', Today()));
+
+    if GLEntry.FindFirst() then
+        repeat
+            ArchiveEntry.TransferFields(GLEntry);
+            ArchiveEntry.Insert();
+            GLEntry.Delete();
+
+            ProcessedCount += 1;
+
+            // Commit periodically to avoid long transactions
+            if ProcessedCount mod BatchSize = 0 then begin
+                Commit();
+                Message('Processed %1 entries...', ProcessedCount);
+            end;
+        until GLEntry.Next() = 0;
+
+    Message('Archive complete. Total entries processed: %1', ProcessedCount);
+end;
+```
+
+### Example 6: Conditional Processing with Early Exit
+
+**Problematic Code:**
+```al
+procedure FindFirstAvailableItem(LocationCode: Code[10]): Code[20]
+var
+    Item: Record Item;
+    ItemLedgerEntry: Record "Item Ledger Entry";
+    AvailableQty: Decimal;
+begin
+    Item.FindFirst();
+    repeat Item.SetRange("Location Filter", LocationCode); Item.CalcFields(Inventory); if Item.Inventory > 0 then exit(Item."No."); until Item.Next() = 0;
+end;
+```
+
+**Improved Code:**
+```al
+procedure FindFirstAvailableItem(LocationCode: Code[10]): Code[20]
+var
+    Item: Record Item;
+begin
+    Item.SetRange(Blocked, false);
+    Item.SetRange(Type, Item.Type::Inventory);
+
+    if Item.FindFirst() then
+        repeat
+            Item.SetRange("Location Filter", LocationCode);
+            Item.CalcFields(Inventory);
+
+            if Item.Inventory > 0 then
+                exit(Item."No.");
+        until Item.Next() = 0;
+
+    // Return empty if no available item found
+    exit('');
+end;
+```
+
+## Best Practices Summary
+
+### Formatting Guidelines
+1. **Always use proper indentation** for repeat-until blocks
+2. **Place conditions on separate lines** for complex boolean expressions
+3. **Use meaningful variable names** instead of inline calculations
+4. **Add blank lines** to separate logical sections within loops
+
+### Performance Considerations
+1. **Process in batches** for large datasets to avoid transaction timeouts
+2. **Use proper filters** before starting repeat loops to minimize iterations
+3. **Calculate fields only when necessary** within the loop
+4. **Consider using FindSet()** with ReadOnly parameter for read-only operations
+
+### Error Handling
+1. **Always check FindFirst() result** before starting repeat loop
+2. **Handle errors gracefully** with appropriate user feedback
+3. **Use Clear()** on codeunit variables before calling Run()
+4. **Implement progress indicators** for long-running operations
+
+### Code Readability
+1. **Extract complex conditions** into well-named boolean variables
+2. **Use early exit patterns** when searching for specific records
+3. **Add comments** to explain business logic within loops
+4. **Avoid deeply nested structures** by using helper procedures
+
+## Related Patterns
+- **FindSet Pattern**: Use `FindSet()` with `ReadOnly` parameter for better performance when only reading data
+- **Batch Processing Pattern**: Process records in controlled batches with periodic commits
+- **Error Accumulation Pattern**: Collect errors during processing and report them together
+- **Progress Indication Pattern**: Provide user feedback during long-running repeat operations

package/embedded-knowledge/domains/sam-coder/al-formatting-consistency-patterns.md

@@ -0,0 +1,75 @@
+---
+title: "AL Formatting Consistency Patterns"
+domain: "sam-coder"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["formatting", "consistency", "code-standards"]
+type: "improvement-pattern"
+category: "code-quality"
+pattern_type: "good"
+severity: "medium"
+impact_level: "medium"
+improvement_suggestion: "Apply consistent formatting patterns across all AL code to improve maintainability"
+implementation_steps: ["establish-formatting-standards", "apply-consistent-patterns", "validate-uniformity"]
+validation_criteria: ["consistent-formatting-application", "improved-code-uniformity"]
+technical_areas: ["al-code"]
+---
+
+# AL Formatting Consistency Patterns
+
+## Overview
+
+Consistent formatting patterns across AL code improve maintainability, reduce cognitive load, and enhance team collaboration. Establishing and applying uniform formatting standards creates professional, readable code that supports effective development workflows.
+
+**Key Principle**: Apply consistent formatting patterns uniformly across all AL objects to create predictable, maintainable code structure.
+
+## Strategic Framework
+
+### Consistency Benefits
+- **Reduced Cognitive Load**: Predictable formatting reduces mental effort
+- **Improved Collaboration**: Team members can focus on logic rather than style
+- **Enhanced Maintainability**: Consistent patterns support easier code updates
+- **Professional Quality**: Uniform appearance reflects development maturity
+
+### Code Quality Impact
+Consistent formatting directly impacts code quality by making code easier to read, review, and maintain. It supports effective development practices and reduces errors.
+
+## Architecture Focus
+
+### Formatting Domains
+- **Indentation Standards**: Consistent spacing and alignment patterns
+- **Keyword Formatting**: Uniform keyword placement and casing
+- **Comment Styles**: Standardized documentation formatting
+- **Expression Layout**: Consistent operator and expression formatting
+
+### Pattern Application
+Establish comprehensive formatting standards that cover all aspects of AL code appearance and apply them consistently across entire codebase.
+
+## Best Practices
+
+### Standards Development
+- **Comprehensive guidelines** covering all AL language elements
+- **Team agreement** on formatting preferences and standards
+- **Tool integration** for automated formatting enforcement
+- **Regular validation** of consistency across codebase
+- **Documentation** of formatting decisions and rationale
+
+### Implementation Strategy
+Use automated formatting tools where possible, establish clear team guidelines for manual formatting decisions, and regularly review code for consistency compliance.
+
+### Maintenance Approach
+Integrate formatting standards into development workflow through code review processes, automated validation, and team training on consistency importance.
+
+## Anti-Patterns
+
+### Avoid These Approaches
+- **Mixed formatting styles** within single project
+- **Inconsistent indentation** across AL objects
+- **Random keyword casing** without standards
+- **Varied comment formatting** creating visual inconsistency
+- **No formatting guidelines** leading to style conflicts
+
+Inconsistent formatting creates unnecessary cognitive overhead and makes code harder to maintain and review effectively.
+
+*Related patterns: al-readability-optimization.md, al-blank-line-organization.md*
+*Cross-references: See samples in other formatting topics for consistency examples*

package/embedded-knowledge/domains/sam-coder/al-line-comment-formatting.md

@@ -0,0 +1,67 @@
+---
+title: "AL Line Comment Formatting and Placement Patterns"
+domain: "sam-coder"
+difficulty: "beginner"
+bc_versions: "14+"
+tags: ["comments", "code-quality", "readability", "maintainability"]
+prerequisites: ["al-basics"]
+---
+# AL Line Comment Formatting and Placement Patterns
+
+## Overview
+
+Line comments in AL code provide contextual explanation and improve code readability when properly formatted and strategically placed. Effective commenting enhances maintainability without cluttering the codebase.
+
+**Key Principle**: Comments should explain *why* code exists, not *what* it does. Focus on business logic, complex calculations, and non-obvious implementation decisions.
+
+## Strategic Framework
+
+### Comment Placement Strategy
+- **Above code blocks**: Explain purpose before implementation
+- **Inline with complex logic**: Clarify non-obvious calculations or conditions
+- **End-of-line for variables**: Document units, ranges, or special meanings
+- **Section headers**: Group related functionality within procedures
+
+### Content Guidelines
+- **Business context**: Explain why specific logic is needed
+- **Edge cases**: Document special conditions or exceptions
+- **Performance notes**: Explain optimization decisions
+- **Integration points**: Clarify external system interactions
+
+## Architecture Patterns
+
+### Procedure-Level Comments
+Place explanatory comments immediately above procedure declarations to describe purpose, key parameters, and expected outcomes. Use consistent formatting with proper spacing.
+
+### Variable Documentation
+Document complex variables with end-of-line comments explaining units, valid ranges, or business significance. This is especially important for calculated fields and configuration values.
+
+### Logic Block Comments
+Group related logic with section comments that explain the overall approach. This helps readers understand the flow without parsing individual statements.
+
+## Best Practices
+
+### Formatting Standards
+- **Consistent spacing**: Single space after // marker
+- **Proper alignment**: Align related inline comments vertically
+- **Clear language**: Use complete sentences for complex explanations
+- **Standard terminology**: Use consistent BC terminology throughout
+
+### Strategic Commenting
+- **Focus on complexity**: Comment complex business rules and calculations
+- **Avoid obvious statements**: Don't comment self-evident code
+- **Update with changes**: Maintain comment accuracy during code updates
+- **Group related items**: Use section comments to organize related functionality
+
+### Maintenance Approach
+Keep comments current with code changes. Outdated comments are worse than no comments as they mislead future developers and create maintenance debt.
+
+## Anti-Patterns
+
+### Avoid These Approaches
+- **Commenting obvious code**: Don't explain what simple assignments do
+- **Excessive commenting**: Every line doesn't need explanation
+- **Outdated information**: Comments that no longer match the code
+- **Poor grammar/spelling**: Unprofessional comments reduce credibility
+- **Code explanation**: Explaining *what* code does instead of *why*
+

package/embedded-knowledge/domains/sam-coder/al-lonely-repeat-pattern.md

@@ -0,0 +1,76 @@
+---
+title: "AL Lonely Repeat Pattern"
+domain: "sam-coder"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["repeat-loops", "control-flow", "code-patterns"]
+samples: "samples/al-lonely-repeat-pattern.md"
+type: "improvement-pattern"
+category: "language-fundamentals"
+pattern_type: "good"
+severity: "medium"
+impact_level: "medium"
+improvement_suggestion: "Avoid lonely repeat statements by ensuring proper until conditions and loop structure"
+implementation_steps: ["identify-repeat-patterns", "validate-until-conditions", "ensure-proper-structure"]
+validation_criteria: ["complete-repeat-until-pairs", "proper-loop-structure"]
+technical_areas: ["al-code"]
+---
+
+# AL Lonely Repeat Pattern
+
+## Overview
+
+The lonely repeat pattern in AL occurs when repeat statements lack proper until conditions or have incomplete loop structures. Understanding proper repeat-until loop construction prevents infinite loops and ensures reliable iteration patterns in Business Central code.
+
+**Key Principle**: Every repeat statement must have a corresponding until condition that provides a reliable loop exit strategy.
+
+## Strategic Framework
+
+### Loop Structure Integrity
+- **Complete Pairs**: Every repeat must have matching until condition
+- **Exit Conditions**: Reliable termination logic for all loops
+- **Logic Validation**: Ensure until conditions can actually be met
+- **Infinite Loop Prevention**: Proper loop variable modification patterns
+
+### Control Flow Reliability
+Repeat-until loops must have well-defined termination conditions that guarantee loop completion under normal execution scenarios.
+
+## Architecture Focus
+
+### Repeat-Until Patterns
+- **Condition Logic**: Until conditions that provide reliable loop exit
+- **Variable Modification**: Loop variables that progress toward termination
+- **Error Handling**: Safeguards against infinite loop scenarios
+- **Performance Considerations**: Efficient loop structures for data processing
+
+### Loop Design Principles
+Structure repeat-until loops with clear progression logic and reliable termination conditions. Avoid patterns that could lead to infinite execution or unpredictable behavior.
+
+## Best Practices
+
+### Proper Loop Construction
+- **Clear until conditions** that can be reliably evaluated
+- **Loop variable progression** ensuring movement toward termination
+- **Boundary condition handling** for edge cases
+- **Error prevention** through validation and safeguards
+- **Performance optimization** for large data set processing
+
+### Termination Logic
+Design until conditions that provide multiple exit paths when appropriate and include safeguards against infinite loop scenarios in data processing operations.
+
+### Code Reliability
+Structure repeat loops with clear termination logic and appropriate error handling to ensure reliable execution in all Business Central scenarios.
+
+## Anti-Patterns
+
+### Avoid These Approaches
+- **Repeat without until** creating incomplete loop structures
+- **Unreachable until conditions** that cannot be satisfied
+- **No loop variable progression** preventing termination
+- **Complex until logic** that obscures termination conditions
+- **Missing error handling** for loop failure scenarios
+
+Lonely repeat patterns create unreliable code that may cause infinite loops or unpredictable behavior in Business Central applications.
+
+*Implementation examples: see samples/al-lonely-repeat-pattern.md*
+*Related patterns: al-statement-per-line-rule.md, al-readability-optimization.md*

package/embedded-knowledge/domains/sam-coder/al-named-parameter-pattern.md

@@ -0,0 +1,98 @@
+---
+title: "AL Named Parameter Pattern"
+domain: "sam-coder"
+difficulty: "intermediate"
+bc_versions: "17+"
+tags: ["parameters", "code-clarity", "maintainability", "readability"]
+type: "improvement-pattern"
+category: "code-quality"
+pattern_type: "good"
+severity: "medium"
+impact_level: "medium"
+improvement_suggestion: "Use descriptive variable naming to create self-documenting parameter patterns"
+implementation_steps: ["identify-complex-calls", "create-descriptive-variables", "validate-clarity"]
+validation_criteria: ["improved-call-clarity", "reduced-parameter-errors"]
+technical_areas: ["al-code"]
+samples: "samples/al-named-parameter-pattern.md"
+---
+
+# AL Named Parameter Pattern
+
+## Overview
+
+Named parameter patterns in AL improve code readability, reduce parameter ordering errors, and enhance maintainability by making procedure calls self-documenting. This pattern particularly benefits procedures with multiple parameters of similar types.
+
+**Key Principle**: Use descriptive variable naming to make procedure calls immediately understandable without referring to procedure definitions.
+
+## Strategic Framework
+
+### Implementation Approach
+AL doesn't support native named parameters, but naming conventions and parameter objects achieve similar benefits through descriptive variable usage.
+
+### Parameter Object Pattern
+Create dedicated parameter records or temporary tables for complex parameter sets, providing natural naming and extensibility.
+
+### Descriptive Variable Naming
+Use clearly named local variables that self-document parameter purposes when calling procedures.
+
+### Parameter Documentation
+Structure parameter lists with consistent ordering and comprehensive documentation to support clear calling patterns.
+
+## Architecture Focus
+
+### Maintainability Enhancement
+**Parameter Evolution**: Parameter objects support adding new parameters without breaking existing calls
+**Type Safety**: Structured parameters reduce type mismatch errors
+**Documentation**: Self-documenting code through clear parameter naming
+**Refactoring Support**: Named patterns simplify procedure signature changes
+
+### Code Clarity Benefits
+**Call Site Readability**: Procedure calls clearly communicate their purpose and data flow
+**Parameter Validation**: Centralized parameter validation within parameter objects
+**Default Handling**: Parameter objects can encapsulate default value logic
+**Complex Operations**: Multi-step operations benefit from structured parameter passing
+
+### Performance Considerations
+Parameter objects may have slight overhead but improve development velocity and reduce debugging time through clearer interfaces.
+
+## Best Practices
+
+### Variable Naming Strategy
+Create descriptive local variables before procedure calls:
+```
+CustomerNo := 'C0001';
+PostingDate := WorkDate();
+DocumentType := DocumentType::Invoice;
+PostSalesDocument(CustomerNo, PostingDate, DocumentType);
+```
+
+### Parameter Object Design
+- **Logical Grouping**: Group related parameters into cohesive objects
+- **Validation Integration**: Include parameter validation within object methods
+- **Default Values**: Implement sensible defaults for optional parameters
+- **Clear Naming**: Use business domain terminology for parameter properties
+
+### Procedure Interface Design
+- **Consistent Ordering**: Establish standard parameter ordering patterns
+- **Optional Parameters**: Place optional parameters at end of parameter list
+- **Documentation**: Provide comprehensive parameter documentation
+- **Interface Stability**: Design parameter interfaces for long-term stability
+
+### Call Site Organization
+- **Descriptive Variables**: Use meaningful variable names that explain parameter purpose
+- **Logical Grouping**: Group related parameter assignments together
+- **Clear Separation**: Separate parameter preparation from procedure calls
+- **Error Context**: Include parameter validation before complex procedure calls
+
+## Anti-Patterns
+
+### Avoid These Approaches
+- **Magic Numbers**: Passing literal values without descriptive variable names
+- **Parameter Soup**: Long parameter lists without logical organization
+- **Type Confusion**: Multiple parameters of same type without clear differentiation
+- **Inconsistent Ordering**: Different parameter ordering patterns across similar procedures
+
+Procedures with unclear parameter patterns create debugging difficulties and increase the likelihood of parameter ordering errors during maintenance.
+
+*Related patterns: al-procedure-design.md, al-code-clarity.md*
+*Implementation examples: see samples/al-named-parameter-pattern.md*