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

package/embedded-knowledge/domains/sam-coder/samples/type-safe-operations.md

@@ -0,0 +1,427 @@
+# Type-Safe Operations Sample
+
+## Overview
+This sample demonstrates type-safe operation patterns in AL including generic procedures, interface-based type safety, and compile-time type validation techniques.
+
+## Generic Type-Safe Procedures
+
+```al
+codeunit 50400 "Type Safe Operations"
+{
+    procedure SafeGetRecord<T>(RecordNo: Code[20]; var TargetRecord: Record T): Boolean
+    begin
+        TargetRecord.SetRange("No.", RecordNo);
+        exit(TargetRecord.FindFirst());
+    end;
+
+    procedure SafeUpdateField<T>(var TargetRecord: Record T; FieldNo: Integer; NewValue: Variant): Boolean
+    var
+        RecordRef: RecordRef;
+        FieldRef: FieldRef;
+    begin
+        RecordRef.GetTable(TargetRecord);
+
+        if not RecordRef.FieldExist(FieldNo) then
+            exit(false);
+
+        FieldRef := RecordRef.Field(FieldNo);
+
+        if not ValidateFieldType(FieldRef, NewValue) then
+            exit(false);
+
+        FieldRef.Value := NewValue;
+        RecordRef.SetTable(TargetRecord);
+
+        exit(TargetRecord.Modify(true));
+    end;
+
+    local procedure ValidateFieldType(FieldRef: FieldRef; NewValue: Variant): Boolean
+    begin
+        case FieldRef.Type of
+            FieldType::Code:
+                exit(NewValue.IsCode);
+            FieldType::Text:
+                exit(NewValue.IsText);
+            FieldType::Integer:
+                exit(NewValue.IsInteger);
+            FieldType::Decimal:
+                exit(NewValue.IsDecimal);
+            FieldType::Boolean:
+                exit(NewValue.IsBoolean);
+            FieldType::Date:
+                exit(NewValue.IsDate);
+            FieldType::DateTime:
+                exit(NewValue.IsDateTime);
+            else
+                exit(false);
+        end;
+    end;
+}
+```
+
+## Interface-Based Type Safety
+
+```al
+interface "Type Safe Validator"
+{
+    procedure Validate(Value: Variant): Boolean;
+    procedure GetValidationMessage(): Text;
+}
+
+codeunit 50401 "Customer Validator" implements "Type Safe Validator"
+{
+    procedure Validate(Value: Variant): Boolean
+    var
+        Customer: Record Customer;
+    begin
+        if not Value.IsRecord then
+            exit(false);
+
+        Customer := Value;
+        exit(ValidateCustomer(Customer));
+    end;
+
+    procedure GetValidationMessage(): Text
+    begin
+        exit('Customer validation failed');
+    end;
+
+    local procedure ValidateCustomer(Customer: Record Customer): Boolean
+    begin
+        if Customer."No." = '' then
+            exit(false);
+
+        if Customer.Name = '' then
+            exit(false);
+
+        if Customer.Blocked <> Customer.Blocked::" " then
+            exit(false);
+
+        exit(true);
+    end;
+}
+
+codeunit 50402 "Item Validator" implements "Type Safe Validator"
+{
+    procedure Validate(Value: Variant): Boolean
+    var
+        Item: Record Item;
+    begin
+        if not Value.IsRecord then
+            exit(false);
+
+        Item := Value;
+        exit(ValidateItem(Item));
+    end;
+
+    procedure GetValidationMessage(): Text
+    begin
+        exit('Item validation failed');
+    end;
+
+    local procedure ValidateItem(Item: Record Item): Boolean
+    begin
+        if Item."No." = '' then
+            exit(false);
+
+        if Item.Description = '' then
+            exit(false);
+
+        if Item.Type = Item.Type::" " then
+            exit(false);
+
+        exit(true);
+    end;
+}
+```
+
+## Type-Safe Data Processing
+
+```al
+codeunit 50403 "Type Safe Data Processor"
+{
+    procedure ProcessTypedData<T>(var DataRecord: Record T; Processor: Interface "Data Processor"): Boolean
+    var
+        RecordVariant: Variant;
+    begin
+        RecordVariant := DataRecord;
+
+        if not Processor.CanProcess(RecordVariant) then
+            exit(false);
+
+        if not Processor.Process(RecordVariant) then
+            exit(false);
+
+        DataRecord := RecordVariant;
+        exit(true);
+    end;
+
+    procedure BatchProcessRecords<T>(var RecordSet: Record T; Processor: Interface "Data Processor"): Integer
+    var
+        ProcessedCount: Integer;
+        CurrentRecord: Record T;
+    begin
+        RecordSet.FindSet();
+        repeat
+            CurrentRecord := RecordSet;
+            if ProcessTypedData(CurrentRecord, Processor) then
+                ProcessedCount += 1;
+        until RecordSet.Next() = 0;
+
+        exit(ProcessedCount);
+    end;
+}
+
+interface "Data Processor"
+{
+    procedure CanProcess(Data: Variant): Boolean;
+    procedure Process(var Data: Variant): Boolean;
+    procedure GetProcessorName(): Text;
+}
+```
+
+## Type-Safe Configuration Pattern
+
+```al
+codeunit 50404 "Type Safe Config Manager"
+{
+    procedure GetConfigValue<T>(ConfigKey: Code[50]): T
+    var
+        ConfigRecord: Record "Type Safe Configuration";
+        ResultValue: T;
+        ConfigVariant: Variant;
+    begin
+        if not ConfigRecord.Get(ConfigKey) then
+            Error('Configuration key %1 not found', ConfigKey);
+
+        ConfigVariant := ConfigRecord.Value;
+
+        if not TryConvertToType<T>(ConfigVariant, ResultValue) then
+            Error('Cannot convert configuration value to requested type for key %1', ConfigKey);
+
+        exit(ResultValue);
+    end;
+
+    procedure SetConfigValue<T>(ConfigKey: Code[50]; Value: T): Boolean
+    var
+        ConfigRecord: Record "Type Safe Configuration";
+        ValueVariant: Variant;
+    begin
+        ValueVariant := Value;
+
+        if ConfigRecord.Get(ConfigKey) then
+            ConfigRecord.Modify()
+        else begin
+            ConfigRecord.Init();
+            ConfigRecord."Config Key" := ConfigKey;
+            ConfigRecord.Insert();
+        end;
+
+        ConfigRecord.Value := ValueVariant;
+        ConfigRecord."Data Type" := GetVariantType(ValueVariant);
+
+        exit(ConfigRecord.Modify(true));
+    end;
+
+    [TryFunction]
+    local procedure TryConvertToType<T>(SourceVariant: Variant; var TargetValue: T)
+    var
+        TempVariant: Variant;
+    begin
+        TempVariant := SourceVariant;
+        TargetValue := TempVariant;
+    end;
+
+    local procedure GetVariantType(Value: Variant): Enum "Configuration Data Type"
+    begin
+        case true of
+            Value.IsBoolean:
+                exit("Configuration Data Type"::Boolean);
+            Value.IsInteger:
+                exit("Configuration Data Type"::Integer);
+            Value.IsDecimal:
+                exit("Configuration Data Type"::Decimal);
+            Value.IsText:
+                exit("Configuration Data Type"::Text);
+            Value.IsCode:
+                exit("Configuration Data Type"::Code);
+            Value.IsDate:
+                exit("Configuration Data Type"::Date);
+            Value.IsDateTime:
+                exit("Configuration Data Type"::DateTime);
+            else
+                exit("Configuration Data Type"::Variant);
+        end;
+    end;
+}
+```
+
+## Type-Safe Event Handling
+
+```al
+codeunit 50405 "Type Safe Event Manager"
+{
+    procedure RegisterEventHandler<T>(EventName: Code[50]; Handler: Interface "Typed Event Handler")
+    var
+        EventRegistration: Record "Event Handler Registration";
+    begin
+        EventRegistration.Init();
+        EventRegistration."Event Name" := EventName;
+        EventRegistration."Handler Type" := GetTypeName<T>();
+        EventRegistration."Handler Interface" := Handler;
+        EventRegistration.Active := true;
+        EventRegistration.Insert(true);
+    end;
+
+    procedure RaiseTypedEvent<T>(EventName: Code[50]; EventData: T): Boolean
+    var
+        EventRegistration: Record "Event Handler Registration";
+        Handler: Interface "Typed Event Handler";
+        EventVariant: Variant;
+        HandlerExecuted: Boolean;
+    begin
+        EventVariant := EventData;
+
+        EventRegistration.SetRange("Event Name", EventName);
+        EventRegistration.SetRange("Handler Type", GetTypeName<T>());
+        EventRegistration.SetRange(Active, true);
+
+        if EventRegistration.FindSet() then
+            repeat
+                Handler := EventRegistration."Handler Interface";
+                if Handler.HandleEvent(EventVariant) then
+                    HandlerExecuted := true;
+            until EventRegistration.Next() = 0;
+
+        exit(HandlerExecuted);
+    end;
+
+    local procedure GetTypeName<T>(): Text
+    var
+        TypeHelper: Codeunit "Type Helper";
+        DummyValue: T;
+        DummyVariant: Variant;
+    begin
+        DummyVariant := DummyValue;
+        exit(TypeHelper.GetObjectName(DummyVariant));
+    end;
+}
+
+interface "Typed Event Handler"
+{
+    procedure HandleEvent(EventData: Variant): Boolean;
+    procedure GetHandlerName(): Text;
+}
+```
+
+## Type-Safe Collection Operations
+
+```al
+codeunit 50406 "Type Safe Collections"
+{
+    procedure CreateTypedList<T>(): List of [T]
+    var
+        TypedList: List of [T];
+    begin
+        exit(TypedList);
+    end;
+
+    procedure AddToTypedList<T>(var TypedList: List of [T]; Item: T): Boolean
+    begin
+        TypedList.Add(Item);
+        exit(true);
+    end;
+
+    procedure FilterTypedList<T>(var TypedList: List of [T]; FilterFunc: Interface "List Filter"): List of [T]
+    var
+        FilteredList: List of [T];
+        Item: T;
+        ItemVariant: Variant;
+    begin
+        foreach Item in TypedList do begin
+            ItemVariant := Item;
+            if FilterFunc.ShouldInclude(ItemVariant) then
+                FilteredList.Add(Item);
+        end;
+
+        exit(FilteredList);
+    end;
+
+    procedure TransformTypedList<TSource, TTarget>(SourceList: List of [TSource]; TransformFunc: Interface "List Transform"): List of [TTarget]
+    var
+        TargetList: List of [TTarget];
+        SourceItem: TSource;
+        SourceVariant: Variant;
+        TargetVariant: Variant;
+        TargetItem: TTarget;
+    begin
+        foreach SourceItem in SourceList do begin
+            SourceVariant := SourceItem;
+            if TransformFunc.Transform(SourceVariant, TargetVariant) then begin
+                TargetItem := TargetVariant;
+                TargetList.Add(TargetItem);
+            end;
+        end;
+
+        exit(TargetList);
+    end;
+}
+
+interface "List Filter"
+{
+    procedure ShouldInclude(Item: Variant): Boolean;
+}
+
+interface "List Transform"
+{
+    procedure Transform(Source: Variant; var Target: Variant): Boolean;
+}
+```
+
+## Type-Safe Error Handling
+
+```al
+codeunit 50407 "Type Safe Error Handler"
+{
+    procedure TryOperation<TInput, TOutput>(Input: TInput; Operation: Interface "Typed Operation"; var Output: TOutput): Boolean
+    var
+        InputVariant: Variant;
+        OutputVariant: Variant;
+        OperationResult: Boolean;
+    begin
+        InputVariant := Input;
+
+        if not Operation.Validate(InputVariant) then
+            exit(false);
+
+        OperationResult := Operation.Execute(InputVariant, OutputVariant);
+
+        if OperationResult then
+            Output := OutputVariant;
+
+        exit(OperationResult);
+    end;
+
+    procedure ExecuteWithFallback<T>(PrimaryOperation: Interface "Typed Operation"; FallbackOperation: Interface "Typed Operation"; Input: T): T
+    var
+        Output: T;
+    begin
+        if TryOperation(Input, PrimaryOperation, Output) then
+            exit(Output);
+
+        if TryOperation(Input, FallbackOperation, Output) then
+            exit(Output);
+
+        Error('All operations failed for input type %1', GetTypeName<T>());
+    end;
+}
+
+interface "Typed Operation"
+{
+    procedure Validate(Input: Variant): Boolean;
+    procedure Execute(Input: Variant; var Output: Variant): Boolean;
+    procedure GetOperationName(): Text;
+}
+```
+
+This sample demonstrates comprehensive type-safe operation patterns including generic procedures, interface-based validation, typed collections, configuration management, event handling, and error handling with compile-time type safety.

package/embedded-knowledge/domains/sam-coder/single-to-compound-conversion.md

@@ -0,0 +1,122 @@
+---
+title: "Converting AL Single Statements to Compound Blocks"
+domain: "sam-coder"
+difficulty: "beginner"
+bc_versions: "14+"
+tags: ["refactoring", "compound-statements", "code-conversion", "development-workflow"]
+prerequisites: ["al-syntax-basics", "compound-statement-readability"]
+samples: "samples/single-to-compound-conversion.md"
+---
+# Converting AL Single Statements to Compound Blocks
+
+## Overview
+
+Converting single AL statements to compound blocks represents a fundamental refactoring pattern that enhances code maintainability and prepares codebases for future expansion. This transformation process involves systematically identifying single-statement constructs and wrapping them in begin-end blocks to create consistent structure.
+
+The conversion process addresses technical debt in existing AL codebases where single statements were used for simplicity but now create maintenance challenges. Modern AL development practices favor compound statements for their explicit structure and future-proofing benefits.
+
+This refactoring pattern becomes particularly valuable during code review processes, team transitions, or when preparing legacy AL code for enhancement. The systematic conversion creates a foundation for reliable code evolution without introducing scope-related bugs.
+
+## Conversion Methodology
+
+### Systematic Identification
+
+Begin conversion efforts by cataloging all single-statement constructs across the AL codebase. Focus on conditional statements, loop constructs, and exception handlers where single statements appear without compound block structure.
+
+Use development environment search capabilities to locate patterns like if-then without corresponding begin-end blocks, while loops with single statements, and case branches containing only single operations.
+
+Document the scope of conversion work to prioritize high-impact areas and coordinate conversion efforts across development team members. This systematic approach prevents duplicate work and ensures comprehensive coverage.
+
+### Priority-Based Conversion
+
+Start conversion efforts with frequently modified code sections where the compound statement benefits provide immediate value. Focus on procedures and triggers that undergo regular enhancement or maintenance activities.
+
+Prioritize conversion in business logic implementations where requirements changes commonly add new statements to existing conditional or loop constructs. These areas benefit most from the future-proofing aspects of compound statements.
+
+Consider the development team's current work to align conversion efforts with active development areas. This coordination maximizes the immediate benefits while minimizing disruption to ongoing feature development.
+
+### Safe Transformation Process
+
+Implement conversion changes through controlled refactoring sessions rather than bulk automated transformations. This approach allows verification of each change and prevents introduction of unintended side effects.
+
+Test each conversion increment to ensure behavioral equivalence between single-statement and compound block implementations. Use existing unit tests or create focused test scenarios to validate conversion accuracy.
+
+Apply version control branching strategies to isolate conversion work from feature development, allowing safe experimentation and easy rollback if issues arise during the transformation process.
+
+## Development Environment Integration
+
+### Editor Enhancement
+
+Configure AL development environments to automatically suggest compound statement conversions during code editing. Many modern editors provide refactoring tools that can identify single-statement opportunities and offer conversion suggestions.
+
+Set up code formatting rules that automatically insert begin-end blocks when creating new conditional or loop constructs. This proactive approach prevents the accumulation of single-statement constructs in new development.
+
+Use editor extensions or plugins that highlight single-statement constructs during code review, making conversion opportunities visible without manual scanning.
+
+### Automated Detection
+
+Implement code analysis tools that identify single-statement patterns and generate conversion recommendations. These tools can scan entire AL projects and provide comprehensive reports on conversion opportunities.
+
+Create custom linting rules that flag single-statement constructs as style violations, encouraging developers to use compound blocks consistently. Configure these rules with appropriate severity levels to balance enforcement with development workflow efficiency.
+
+Integrate conversion detection into continuous integration processes to catch single-statement introductions before they enter the main codebase. This prevents the accumulation of inconsistent patterns.
+
+### Template Integration
+
+Update code templates and snippets to generate compound statements by default rather than single-statement alternatives. This proactive measure ensures new code follows compound statement patterns automatically.
+
+Modify code generation tools and wizards to produce begin-end blocks consistently across all conditional and iterative constructs. This systematic approach eliminates the need for subsequent conversion work.
+
+Share updated templates across development team members to ensure consistent adoption of compound statement patterns in all new development efforts.
+
+## Team Collaboration Strategies
+
+### Conversion Planning
+
+Coordinate conversion efforts across development team members to prevent conflicts and ensure comprehensive coverage. Establish clear ownership of different code areas to avoid duplicate conversion work.
+
+Schedule conversion activities during development lulls or maintenance windows to minimize impact on feature development timelines. Plan conversion work in manageable increments that fit within available development capacity.
+
+Communicate conversion priorities and progress to keep team members informed about changing code patterns and ensure alignment with ongoing development activities.
+
+### Knowledge Transfer
+
+Provide training and documentation to help team members understand compound statement benefits and conversion techniques. Focus on practical examples that demonstrate the maintainability advantages.
+
+Establish mentoring relationships between experienced developers and those new to compound statement patterns. This peer support accelerates adoption and ensures consistent application across the team.
+
+Create conversion guidelines that document approved techniques and common pitfalls to avoid. Share these guidelines through team knowledge bases or development wikis.
+
+### Quality Assurance
+
+Implement peer review processes for conversion work to ensure accuracy and maintain code quality standards. Use code review sessions as teaching opportunities to reinforce compound statement benefits.
+
+Establish testing protocols that verify conversion accuracy and prevent regression introduction during transformation activities. Create focused test scenarios that validate behavioral equivalence.
+
+Monitor conversion quality metrics to identify areas where additional training or process refinement might improve outcomes. Track conversion accuracy and team adoption rates to measure progress.
+
+## Common Conversion Scenarios
+
+### Legacy Code Enhancement
+
+Address legacy AL codebases that predominantly use single-statement patterns by implementing gradual conversion strategies. Focus on high-value areas where maintainability improvements provide immediate benefits.
+
+Plan conversion work around scheduled maintenance activities or enhancement projects to maximize efficiency and minimize dedicated refactoring overhead.
+
+Document legacy code patterns and conversion rationale to help future developers understand the evolution of coding standards within the organization.
+
+### Code Review Integration
+
+Incorporate conversion opportunities into regular code review processes, using review sessions to identify and address single-statement patterns as they arise.
+
+Establish review guidelines that encourage compound statement adoption without creating adversarial review environments. Focus on educational benefits rather than strict enforcement.
+
+Use review comments to explain compound statement benefits and provide conversion examples that demonstrate improved maintainability.
+
+### New Developer Onboarding
+
+Include compound statement conversion skills in new developer training programs to establish proper coding patterns from the beginning of team tenure.
+
+Provide hands-on conversion exercises that give new developers experience with both identification and transformation techniques. Use real codebase examples to make training relevant.
+
+Assign conversion tasks as learning opportunities for new team members, providing mentorship and feedback throughout the process.

package/embedded-knowledge/domains/sam-coder/template-method-pattern-al.md

@@ -0,0 +1,96 @@
+---
+title: "Template Method Pattern in AL"
+domain: "sam-coder"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["template-method", "behavioral-patterns", "algorithm-structure", "inheritance"]
+prerequisites: ["object-orientation-al", "inheritance-patterns", "virtual-methods"]
+samples: "samples/template-method-pattern.md"
+related_topics: ["business-process-template-patterns", "type-safe-operations-al"]
+---
+
+# Template Method Pattern in AL
+
+## Overview
+
+The Template Method Pattern defines the skeleton of an algorithm in a base class, allowing subclasses to override specific steps without changing the algorithm's structure. In AL development, this pattern enables consistent process execution while providing flexibility for customization.
+
+**Key Benefit**: Provides a stable algorithm framework that ensures consistent execution while enabling customization of specific steps through inheritance.
+
+## Core Pattern Architecture
+
+### Algorithm Skeleton Definition
+Define the overall algorithm structure in a base codeunit or interface, establishing the sequence of operations and control flow.
+
+### Extension Points
+Identify specific steps in the algorithm that can be customized by subclasses while maintaining the overall algorithm integrity.
+
+### Invariant Operations
+Implement operations that remain constant across all algorithm implementations, providing stability and consistency.
+
+## Implementation Strategies
+
+### Virtual Method Framework
+Use virtual methods in AL to create extension points that subclasses can override while maintaining the template algorithm structure.
+
+### Interface-Based Templates
+Design template patterns using interfaces to define algorithm contracts that implementing classes must fulfill.
+
+### Event-Driven Templates
+Integrate template methods with AL event systems to provide extension points without requiring inheritance.
+
+## AL-Specific Patterns
+
+### Codeunit Template Hierarchy
+Create codeunit hierarchies where base codeunits define template algorithms and derived codeunits customize specific operations.
+
+### Page Template Patterns
+Implement page template patterns that provide consistent user interaction flows while allowing customization of specific behaviors.
+
+### Report Template Framework
+Design report templates that define consistent report generation algorithms while enabling customization of data processing and formatting.
+
+## Advanced Template Techniques
+
+### Multi-Phase Templates
+Design template algorithms that support multiple phases of execution, enabling complex customization scenarios.
+
+### Conditional Template Execution
+Implement template methods that can conditionally execute different algorithm branches based on runtime conditions or configuration.
+
+### Nested Template Patterns
+Create nested template structures where template methods can invoke other template methods, enabling complex algorithm composition.
+
+## Advanced Implementation
+
+### Process Integration
+Design templates for business processes, data operations, and workflow automation with consistent error handling.
+
+### Performance & Validation
+Optimize template efficiency, implement lazy evaluation, and provide consistent validation approaches.
+
+## Implementation Guidelines
+
+### Testing & Documentation
+Validate template structure, test customizations, and provide comprehensive documentation with clear customization guidelines.
+
+### Framework Integration
+Integrate with existing Business Central frameworks and patterns for consistent implementation.
+
+### Extension Integration
+Design templates that work effectively with AL extension mechanisms and AppSource publishing requirements.
+
+### Cross-Module Templates
+Create template patterns that can work across different modules while maintaining consistent behavior.
+
+## Best Practices
+
+Keep algorithms focused, minimize extension points, document contracts, and implement comprehensive error handling.
+
+## Common Pitfalls
+
+Avoid template complexity and inflexible designs that reduce effectiveness and customization opportunities.
+
+*Complete template method examples: samples/template-method-pattern.md*
+*Business process templates: business-process-template-patterns.md*
+*Type-safe implementations: type-safe-operations-al.md*