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

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*

package/embedded-knowledge/domains/sam-coder/al-object-navigation-shortcuts.md

@@ -0,0 +1,128 @@
+---
+title: "AL Object Navigation Shortcuts"
+domain: "sam-coder"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["navigation", "al-objects", "workspace", "symbol-search", "dependencies"]
+prerequisites: ["vs-code-al-shortcuts", "al-project-structure"]
+---
+
+# AL Object Navigation Shortcuts
+
+## Overview
+
+Efficient navigation between AL objects is crucial for understanding code relationships, debugging complex scenarios, and maintaining large AL projects. Master these navigation patterns to move fluidly through Business Central codebases.
+
+**Core Concept**: AL object navigation combines symbol search, dependency tracking, and workspace awareness for rapid code exploration.
+
+## Symbol-Based Navigation
+
+### Go-To Definition Patterns
+**F12** on any AL symbol provides immediate navigation:
+- **Object references**: Jump from usage to object definition
+- **Procedure calls**: Navigate to procedure implementation
+- **Variable declarations**: Find where variables are declared
+- **Field references**: Jump to table field definitions
+
+### Peek Definition Workflow
+**Alt+F12** opens inline preview without losing current context:
+- **Quick reference checking**: Verify procedure signatures without navigation
+- **Multi-object comparison**: Compare related objects side-by-side
+- **Context preservation**: Maintain current editing position while exploring
+
+### Reference Discovery
+**Shift+F12** reveals all usages of current symbol:
+- **Impact analysis**: Understand where objects/procedures are used
+- **Refactoring planning**: Identify all affected code before changes
+- **Documentation research**: Find usage examples across codebase
+
+## Workspace-Level Navigation
+
+### Global Symbol Search
+**Ctrl+T** enables rapid workspace-wide object discovery:
+- **Object name search**: Find tables, pages, codeunits by partial name
+- **Procedure location**: Locate specific procedures across all objects
+- **Fuzzy matching**: Use partial strings to find objects quickly
+
+### AL-Specific Object Navigation
+**Ctrl+Shift+P → "AL: Go!"** provides enhanced AL object search:
+- **Object type filtering**: Search within specific object types (tables, pages)
+- **Object ID navigation**: Jump directly to objects by ID number
+- **Extension awareness**: Navigate across multiple AL extensions
+
+### File-Level Symbol Navigation
+**Ctrl+Shift+O** shows current file's symbol outline:
+- **Procedure listing**: Quick access to all procedures in current object
+- **Variable declarations**: Jump to variable declaration sections
+- **Structured navigation**: Navigate by AL object structure (triggers, procedures)
+
+## Dependency Tracking
+
+### Cross-Object Relationships
+Understanding AL object dependencies through navigation:
+- **Table-Page relationships**: Navigate from table fields to related pages
+- **Codeunit dependencies**: Track procedure calls across codeunits
+- **Report-Dataset connections**: Follow data flow from datasets to layout
+
+### Extension Boundary Navigation
+Navigate between AL extensions and base application:
+- **Base application references**: Jump to standard BC objects from extensions
+- **Extension dependencies**: Navigate between dependent AL extensions
+- **Symbol resolution**: Understand which extension provides specific symbols
+
+## Advanced Navigation Techniques
+
+### Multi-Cursor Object Exploration
+Use **Ctrl+D** for simultaneous multi-object navigation:
+- **Pattern identification**: Select similar symbols across multiple objects
+- **Bulk navigation**: Navigate to multiple related definitions simultaneously
+- **Comparison workflows**: Compare similar patterns across objects
+
+### Breadcrumb Navigation
+Leverage VS Code breadcrumbs for AL object context:
+- **Object hierarchy**: Visual representation of current location in AL object
+- **Quick parent navigation**: Click breadcrumbs to navigate to parent scopes
+- **Context awareness**: Understand current position within complex AL objects
+
+### Search Integration with Navigation
+Combine **Ctrl+Shift+F** with navigation shortcuts:
+- **Usage pattern search**: Find specific AL patterns across workspace
+- **Cross-reference validation**: Verify object relationships through search
+- **Documentation discovery**: Find comments and documentation related to objects
+
+## Navigation Efficiency Patterns
+
+### Context-Preserving Exploration
+- **Tab management**: Use multiple tabs for related AL objects
+- **Split editor**: Compare related objects side-by-side
+- **Breadcrumb trails**: Maintain awareness of navigation history
+
+### Rapid Discovery Workflows
+- **Symbol-first navigation**: Start with symbol search, then explore context
+- **Reference-driven exploration**: Use "Find All References" to understand object usage
+- **Definition-to-usage flow**: Navigate from definitions to all usage contexts
+
+### Team Navigation Standards
+- **Consistent naming patterns**: Enable predictable object discovery
+- **Documentation links**: Include navigation hints in object comments
+- **Dependency documentation**: Maintain clear dependency maps for complex solutions
+
+## Common Navigation Scenarios
+
+### Debugging Complex Flows
+Navigate efficiently through call stacks and data flows:
+1. **Start at error location** using diagnostic navigation
+2. **Trace back through call stack** using Go-to-Definition
+3. **Identify data sources** through table/field navigation
+4. **Verify related objects** using Find-All-References
+
+### Code Review Navigation
+Systematic exploration of code changes:
+1. **Start with modified objects** in source control view
+2. **Navigate to related objects** using dependency tracking
+3. **Verify impact scope** using reference discovery
+4. **Check integration points** through cross-object navigation
+
+*Navigation practice exercises: samples/al-navigation-practice.md*
+*Workspace search patterns: sam-coder-index.json#workspace-navigation*
+*AL object relationships: code-design-index.json#object-dependencies*

package/embedded-knowledge/domains/sam-coder/al-readability-optimization.md

@@ -0,0 +1,75 @@
+---
+title: "AL Readability Optimization"
+domain: "sam-coder"
+difficulty: "advanced"
+bc_versions: "14+"
+tags: ["readability", "optimization", "code-quality"]
+type: "improvement-pattern"
+category: "code-quality"
+pattern_type: "good"
+severity: "medium"
+impact_level: "medium"
+improvement_suggestion: "Optimize AL code readability through strategic formatting and organization techniques"
+implementation_steps: ["analyze-readability-factors", "apply-optimization-techniques", "validate-improvement"]
+validation_criteria: ["improved-code-readability", "reduced-cognitive-load"]
+technical_areas: ["al-code"]
+---
+
+# AL Readability Optimization
+
+## Overview
+
+Readability optimization in AL code involves strategic application of formatting, naming, and organizational techniques to minimize cognitive load and maximize code comprehension. Optimized readability directly impacts development productivity and code maintainability.
+
+**Key Principle**: Structure AL code to minimize cognitive effort required for understanding logic, flow, and purpose.
+
+## Strategic Framework
+
+### Cognitive Load Reduction
+- **Visual Hierarchy**: Clear formatting that reveals code structure immediately
+- **Logical Organization**: Code arrangement that follows natural reading patterns
+- **Context Clarity**: Sufficient information for understanding without external references
+- **Complexity Management**: Techniques for handling complex logic readably
+
+### Comprehension Enhancement
+Optimize code layout and organization to support quick understanding of business logic, control flow, and data operations within Business Central context.
+
+## Architecture Focus
+
+### Readability Factors
+- **Visual Structure**: Indentation, spacing, and alignment for clarity
+- **Naming Clarity**: Descriptive identifiers that convey purpose
+- **Logical Flow**: Code organization that matches business process flow
+- **Documentation Integration**: Comments and structure that enhance understanding
+
+### Optimization Techniques
+Apply systematic approaches to improve code readability including strategic formatting, logical organization, and clarity enhancement patterns.
+
+## Best Practices
+
+### Structure Optimization
+- **Logical code grouping** that reflects business operations
+- **Clear visual hierarchy** through consistent formatting
+- **Strategic white space** to separate conceptual sections
+- **Meaningful naming** that conveys purpose and context
+- **Progressive complexity** from simple to complex operations
+
+### Flow Enhancement
+Organize code to follow natural reading patterns, group related operations logically, and use formatting to guide reader attention to important elements.
+
+### Clarity Techniques
+Use consistent patterns for similar operations, eliminate unnecessary complexity, and structure code to support quick mental model building.
+
+## Anti-Patterns
+
+### Avoid These Approaches
+- **Dense code blocks** without logical separation
+- **Unclear naming** requiring mental translation
+- **Random organization** without logical flow
+- **Inconsistent patterns** requiring constant style adaptation
+- **Unnecessary complexity** that obscures business logic
+
+Poor readability optimization increases development time, introduces errors, and makes code maintenance more difficult and expensive.
+
+*Related patterns: al-formatting-consistency-patterns.md, al-statement-per-line-rule.md*
+*Cross-references: See samples in other formatting topics for readability examples*

package/embedded-knowledge/domains/sam-coder/al-record-find-early-exit.md

@@ -0,0 +1,95 @@
+---
+title: "AL Record Find Early Exit"
+domain: "sam-coder"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["record-access", "performance", "early-exit", "database"]
+type: "improvement-pattern"
+category: "performance"
+pattern_type: "good"
+severity: "high"
+impact_level: "high"
+improvement_suggestion: "Implement early exit patterns for record Find operations to prevent unnecessary processing"
+implementation_steps: ["identify-record-operations", "apply-early-exit-patterns", "validate-performance"]
+validation_criteria: ["improved-performance", "reduced-database-load"]
+technical_areas: ["al-code", "database"]
+samples: "samples/al-record-find-early-exit.md"
+---
+
+# AL Record Find Early Exit
+
+## Overview
+
+Implementing early exit patterns for AL record Find operations prevents unnecessary database queries and subsequent processing when records don't exist. This fundamental performance optimization reduces database load and improves response times.
+
+**Key Principle**: Always check Find() results before proceeding with record-dependent operations to avoid processing non-existent data.
+
+## Strategic Framework
+
+### Standard Find Pattern
+```
+if Customer.Find() then begin
+    // Process found record
+end else begin
+    // Handle not found case
+end;
+```
+
+### Early Exit Implementation
+Replace nested if-else with guard clause pattern:
+```
+if not Customer.Find() then
+    exit;
+
+// Process found record directly
+```
+
+### Performance Impact
+Early exits eliminate unnecessary code execution when records don't exist, reducing CPU usage and improving user experience in data-sparse scenarios.
+
+## Architecture Focus
+
+### Database Efficiency
+**Query Optimization**: Early exits prevent cascading database operations when initial record retrieval fails
+**Connection Management**: Reduced database round trips improve connection pool utilization
+**Memory Management**: Avoiding record processing when data doesn't exist conserves memory allocation
+**Transaction Scope**: Early exits keep transaction scope minimal for non-existent record scenarios
+
+### Error Prevention
+Early exit patterns prevent null reference errors and invalid data processing that can occur when assuming record existence without verification.
+
+### Code Flow Clarity
+Guard clause implementation creates clear separation between record existence validation and business logic processing.
+
+## Best Practices
+
+### Implementation Patterns
+- **Guard Clauses First**: Check record existence at procedure start before main logic
+- **Consistent Error Handling**: Standardize response for non-existent records across application
+- **Logging Considerations**: Log appropriate messages for record not found scenarios
+- **Return Value Strategy**: Design clear return patterns for procedures with early exits
+
+### Performance Optimization
+- **Filter Before Find**: Apply appropriate filters before Find() to reduce search scope
+- **Index Utilization**: Ensure Find operations use optimal indexes for best performance
+- **Batch Processing**: Consider FindSet() for multiple record processing scenarios
+- **Existence Checks**: Use IsEmpty() for existence verification without full record loading
+
+### Error Handling Integration
+- **Graceful Degradation**: Handle missing records without disrupting user workflow
+- **Clear Messaging**: Provide meaningful feedback when records cannot be found
+- **Recovery Options**: Offer alternative actions when primary records are unavailable
+- **Audit Trails**: Log record access attempts for troubleshooting and analysis
+
+## Anti-Patterns
+
+### Avoid These Approaches
+- **Assumed Existence**: Processing records without Find() verification
+- **Nested Processing**: Deep conditional nesting instead of early validation
+- **Ignored Return Values**: Not checking Find() boolean result before proceeding
+- **Cascading Failures**: Allowing record-not-found errors to propagate through system
+
+Failing to implement early exits in high-frequency operations creates cumulative performance degradation and unnecessary database load.
+
+*Related patterns: al-record-filtering.md, al-database-optimization.md*
+*Implementation examples: see samples/al-record-find-early-exit.md*