bc-code-intelligence-mcp 1.5.6 → 1.5.7

package/embedded-knowledge/domains/eva-errors/try-function-usage.md

@@ -0,0 +1,129 @@
+---
+title: "Try Function Usage Guidelines"
+domain: "eva-errors"
+difficulty: "intermediate"
+bc_versions: "14+"
+tags: ["try-function", "error-handling", "transactions", "external-systems", "best-practices"]
+samples: "samples/try-function-usage.md"
+related_topics:
+  - "codeunit-run-pattern.md"
+  - "testfield-error-handling.md"
+---
+# Try Function Usage Guidelines
+
+## Overview
+
+Try functions in Business Central provide a mechanism to catch runtime errors without terminating execution. While powerful, they have significant constraints around transaction handling that must be understood to use them correctly.
+
+**Core Principle**: Try functions are designed for error detection and graceful handling—not for suppressing errors during write operations.
+
+## When to Use Try Functions
+
+### External System Calls
+Try functions are ideal for wrapping calls to external systems where failures are expected and recoverable:
+- Web service calls that may timeout or fail
+- External API integrations
+- File system operations
+- HTTP client requests
+
+External systems are inherently unreliable, and wrapping these calls allows your code to detect failures and respond appropriately rather than crashing.
+
+### Validation Without Termination
+Use try functions when you need to validate data or test conditions without stopping execution:
+- Pre-flight checks before processing
+- Batch validation scenarios
+- User input validation with graceful feedback
+
+### Read-Only Operations
+Try functions work well for read operations that might fail:
+- Record lookups that may not find results
+- Configuration checks
+- Data existence verification
+
+## When NOT to Use Try Functions
+
+### Write Operations in the Call Stack
+**Critical Rule**: Never perform database write operations (INSERT, MODIFY, DELETE) inside a try function or any procedure called from within a try function.
+
+This is prohibited because:
+- The transaction behavior becomes unpredictable
+- Partial writes cannot be properly rolled back
+- Data integrity cannot be guaranteed
+- The AL runtime explicitly prevents this pattern
+
+### Suppressing Legitimate Errors
+Don't use try functions to hide errors that indicate real problems:
+- Business rule violations should be reported, not hidden
+- Data validation failures need user attention
+- Configuration errors require administrator action
+
+### Complex Transaction Scenarios
+Avoid try functions in the middle of multi-step transaction processes where you need consistent state management.
+
+## Transaction Behavior
+
+### Try Function Transaction Rules
+When a try function catches an error:
+- Any pending database changes within the try scope are rolled back
+- The calling code continues execution
+- GetLastErrorText() captures the error message
+
+### Write Operation Restrictions
+The Business Central runtime enforces that write transactions cannot occur within a try function's call stack. Attempting this will result in a runtime error indicating the operation is not allowed.
+
+## Implementation Patterns
+
+### External Service Wrapper
+Create try functions specifically for external calls, keeping all database operations outside:
+
+```
+// Correct pattern:
+1. Prepare data (outside try)
+2. Call try function for external operation
+3. Check result
+4. Write to database based on result (outside try)
+```
+
+### Error Detection and Logging
+Use try functions to detect errors, capture details, then handle the situation outside the try scope:
+
+```
+// Pattern:
+1. Call try function
+2. If failed: capture GetLastErrorText()
+3. Log error or notify user
+4. Take appropriate action
+```
+
+## Best Practices
+
+### Keep Try Functions Focused
+- Single responsibility: one external call or validation per try function
+- Minimal code inside the try function
+- No side effects beyond the intended operation
+
+### Handle Errors Appropriately
+- Always check the return value of try function calls
+- Use GetLastErrorText() to capture error details
+- Provide meaningful feedback or logging
+
+### Separate Concerns
+- Database operations: outside try functions
+- External calls: inside try functions
+- Error handling logic: after try function returns
+
+## Common Mistakes
+
+### Database Writes Inside Try
+Attempting to modify, insert, or delete records inside a try function or its call stack will fail at runtime.
+
+### Ignoring Return Values
+Calling a try function without checking its boolean return defeats the purpose of error handling.
+
+### Over-Reliance on Try Functions
+Using try functions as a general error suppression mechanism rather than for specific, expected failure scenarios creates fragile code.
+
+## Related Patterns
+
+For scenarios requiring transaction isolation with error handling, see the Codeunit.Run() pattern which provides proper transaction boundaries with error capture capabilities.
+

package/embedded-knowledge/domains/morgan-market/partner-readiness-analysis.md

@@ -0,0 +1,201 @@
+---
+title: "Partner Readiness Analysis for AppSource Apps"
+domain: "morgan-market"
+difficulty: "advanced"
+bc_versions: "18+"
+tags: ["appsource", "partner-readiness", "extensibility", "telemetry", "access-modifiers", "events", "isv"]
+samples: "samples/partner-readiness-checklist.md"
+related_topics:
+  - "../jordan-bridge/event-architecture.md"
+  - "../alex-architect/api-interface-design-patterns.md"
+  - "../dean-debug/telemetry-fundamentals.md"
+  - "../seth-security/access-modifier-strategy.md"
+---
+# Partner Readiness Analysis for AppSource Apps
+
+## Overview
+
+Publishing an app to AppSource involves more than passing technical validation. A truly partner-ready app considers the full lifecycle: how partners will extend it, how you'll support it in production, how customers will integrate with it, and how the codebase will evolve over time.
+
+**Core Principle**: AppSource validation is the minimum bar. Partner readiness is the path to marketplace success and sustainable business.
+
+## The Partner Lifecycle Mindset
+
+When you publish to AppSource, you're not just shipping code—you're entering a partnership ecosystem:
+
+- **Partners (PTEs)** will build on top of your app
+- **Customers** will integrate your app into their processes
+- **You** will need to diagnose issues remotely
+- **Microsoft** will evolve the platform under your app
+
+Each of these relationships requires intentional design decisions that go beyond "does it work?"
+
+## Partner Readiness Checklist
+
+### 1. Event Architecture for Extensibility
+
+**Why It Matters**: Partners and PTEs need to extend your app without modifying your code. Without proper events, they're stuck—or worse, they'll find workarounds that break on your next update.
+
+**Key Questions**:
+- [ ] Do critical business processes raise events before and after key operations?
+- [ ] Can partners inject validation logic before you commit data?
+- [ ] Can partners react to state changes without polling?
+- [ ] Are events granular enough to be useful but not so numerous as to be noisy?
+
+**What to Expose**:
+- Document posting and state transitions
+- Master data creation and modification
+- Integration touchpoints (before/after external calls)
+- Validation phases where partners might add business rules
+
+**Anti-Patterns**:
+- Raising events with insufficient context (missing key fields)
+- Events that fire but can't influence the outcome
+- Undocumented events that partners discover by accident
+
+**Specialist Referral**: → **Jordan Bridge** for event architecture patterns and publisher/subscriber design
+
+---
+
+### 2. Telemetry for Production Support
+
+**Why It Matters**: When something goes wrong at a customer site, you won't have debugger access. Telemetry is your eyes into production behavior—and your evidence when diagnosing "it doesn't work" reports.
+
+**Key Questions**:
+- [ ] Do you emit custom telemetry for key business operations?
+- [ ] Can you identify which customer, which document, which operation from telemetry alone?
+- [ ] Do you capture timing information for performance-sensitive operations?
+- [ ] Are errors logged with enough context to diagnose without reproduction?
+
+**What to Instrument**:
+- External service calls (start, end, success/failure, duration)
+- Long-running operations with intermediate checkpoints
+- Error conditions with business context (not just technical stack traces)
+- Configuration-dependent behavior branches
+
+**Anti-Patterns**:
+- Logging so verbose it becomes noise
+- Missing correlation IDs across related operations
+- Telemetry that exposes PII or sensitive business data
+
+**Specialist Referral**: → **Dean Debug** for telemetry implementation patterns and KQL query strategies
+
+---
+
+### 3. Access Modifier Strategy
+
+**Why It Matters**: Your `public` and `internal` decisions define your support surface. Everything marked `public` becomes a contract you must maintain. Everything marked `internal` gives you freedom to refactor.
+
+**Key Questions**:
+- [ ] Is every public procedure intentionally public, or just "default"?
+- [ ] Are internal implementation details protected from external callers?
+- [ ] Do codeunits have appropriate access modifiers (Public vs Internal)?
+- [ ] Are procedures that partners SHOULD call clearly marked and documented?
+
+**Strategic Decisions**:
+- **Public Codeunits/Procedures**: Partner-facing API surface—document, version, maintain
+- **Internal Codeunits/Procedures**: Implementation freedom—refactor without breaking partners
+- **Protected Tables**: Control who can write to your data
+- **Access = Public on Tables/Pages**: Required for extensibility, but increases your contract surface
+
+**Anti-Patterns**:
+- Making everything public "just in case"
+- No documentation of what the public API actually is
+- Changing internal behavior that partners somehow depended on
+
+**Specialist Referral**: → **Seth Security** for access modifier strategy and encapsulation patterns
+
+---
+
+### 4. Interface Architecture
+
+**Why It Matters**: Interfaces enable dependency inversion—partners can provide implementations you call without tight coupling. This is essential for apps that need pluggable behavior.
+
+**Key Questions**:
+- [ ] Do you use interfaces where partner-provided implementations make sense?
+- [ ] Are interfaces well-documented with clear implementation contracts?
+- [ ] Can partners register their implementations without modifying your code?
+- [ ] Is interface discovery and registration straightforward?
+
+**Good Interface Candidates**:
+- External system connectors (shipping, payment, tax services)
+- Calculation engines with customer-specific logic
+- Document generation with format variations
+- Notification handlers with channel flexibility
+
+**Anti-Patterns**:
+- Interfaces without documentation of expected behavior
+- No default implementation for optional interfaces
+- Registration mechanisms that require insider knowledge
+
+**Specialist Referral**: → **Alex Architect** for interface design patterns and facade architecture
+
+---
+
+### 5. Upgrade and Migration Considerations
+
+**Why It Matters**: Your app will evolve. Partners will have extensions depending on your schema and APIs. Breaking changes have real business impact.
+
+**Key Questions**:
+- [ ] Do you have a versioning strategy for your public API?
+- [ ] Are breaking changes communicated before releases?
+- [ ] Do upgrade codeunits handle data migration for schema changes?
+- [ ] Is there a deprecation process for obsolete functionality?
+
+**Best Practices**:
+- Use `ObsoleteState` and `ObsoleteReason` to communicate deprecation timeline
+- Provide upgrade codeunits for schema migrations
+- Document breaking changes in release notes
+- Give partners advance notice for significant changes
+
+**Specialist Referral**: → **Logan Legacy** for upgrade codeunit patterns and migration strategies
+
+---
+
+### 6. Documentation for Partner Success
+
+**Why It Matters**: Partners can't use what they can't discover. Documentation transforms your app from "code that works" to "platform partners can build on."
+
+**Key Questions**:
+- [ ] Are public APIs documented with usage examples?
+- [ ] Are events discoverable with clear documentation of when they fire?
+- [ ] Is there guidance for common extension scenarios?
+- [ ] Do partners know how to get help when they're stuck?
+
+**Documentation Assets**:
+- API reference (procedures, parameters, return values)
+- Event catalog (event, context, typical use cases)
+- Integration guide (common partner scenarios)
+- Troubleshooting guide (common issues and resolution)
+
+**Specialist Referral**: → **Taylor Docs** for documentation structure and partner communication
+
+---
+
+## Analysis Workflow
+
+When analyzing an app for partner readiness, work through each category systematically:
+
+1. **Inventory**: What events, public APIs, and telemetry currently exist?
+2. **Gap Analysis**: What's missing for each category based on the checklists?
+3. **Priority Assessment**: Which gaps have the highest partner impact?
+4. **Remediation Plan**: What changes are needed, and in what order?
+5. **Specialist Handoffs**: Which specialists should address specific gaps?
+
+## Continuous Improvement
+
+Partner readiness isn't a one-time checklist—it's an ongoing discipline:
+
+- **Gather Feedback**: Listen to partners using your app
+- **Monitor Telemetry**: What operations cause the most issues?
+- **Review Gaps**: After each release, what extension scenarios weren't supported?
+- **Iterate**: Improve event coverage and documentation with each version
+
+## Summary
+
+AppSource validation asks: "Does this app work?"
+
+Partner readiness asks: "Can partners succeed with this app?"
+
+The difference is the foundation of a sustainable AppSource business.
+

package/embedded-knowledge/domains/morgan-market/samples/partner-readiness-checklist.md

@@ -0,0 +1,288 @@
+# Partner Readiness Checklist Examples
+
+## Event Architecture Review
+
+### Good: Well-Designed Event Pattern
+```al
+codeunit 50100 "My Document Processor"
+{
+    // Partners can validate before processing
+    [IntegrationEvent(false, false)]
+    local procedure OnBeforeProcessDocument(var MyDocument: Record "My Document"; var IsHandled: Boolean)
+    begin
+    end;
+
+    // Partners can react after processing
+    [IntegrationEvent(false, false)]
+    local procedure OnAfterProcessDocument(var MyDocument: Record "My Document"; Success: Boolean)
+    begin
+    end;
+
+    // Partners can add line-level logic
+    [IntegrationEvent(false, false)]
+    local procedure OnBeforeProcessDocumentLine(
+        var MyDocument: Record "My Document"; 
+        var MyDocumentLine: Record "My Document Line";
+        var IsHandled: Boolean)
+    begin
+    end;
+
+    procedure ProcessDocument(var MyDocument: Record "My Document")
+    var
+        IsHandled: Boolean;
+    begin
+        OnBeforeProcessDocument(MyDocument, IsHandled);
+        if IsHandled then
+            exit;
+
+        ProcessLines(MyDocument);
+        FinalizeDocument(MyDocument);
+
+        OnAfterProcessDocument(MyDocument, true);
+    end;
+}
+```
+
+### Poor: Missing Event Context
+```al
+// ❌ Partners can't do anything useful with this
+[IntegrationEvent(false, false)]
+local procedure OnProcess()
+begin
+end;
+
+// ❌ No IsHandled - partners can't prevent default behavior
+[IntegrationEvent(false, false)]
+local procedure OnBeforePost(DocumentNo: Code[20])
+begin
+end;
+```
+
+---
+
+## Telemetry Implementation
+
+### Good: Comprehensive Operation Telemetry
+```al
+codeunit 50101 "External Service Connector"
+{
+    var
+        TelemetryCategory: Label 'MyApp-ExternalService', Locked = true;
+
+    procedure CallExternalService(DocumentNo: Code[20]): Boolean
+    var
+        StartTime: DateTime;
+        Duration: Duration;
+        CustomDimensions: Dictionary of [Text, Text];
+    begin
+        StartTime := CurrentDateTime();
+        
+        CustomDimensions.Add('DocumentNo', DocumentNo);
+        CustomDimensions.Add('Operation', 'CallExternalService');
+        CustomDimensions.Add('Endpoint', GetEndpointName());
+        
+        Session.LogMessage(
+            'MYAPP-0001', 
+            'External service call started', 
+            Verbosity::Normal, 
+            DataClassification::SystemMetadata, 
+            TelemetryScope::ExtensionPublisher, 
+            CustomDimensions);
+
+        if not TryCallService(DocumentNo) then begin
+            Duration := CurrentDateTime() - StartTime;
+            CustomDimensions.Add('Duration', Format(Duration));
+            CustomDimensions.Add('ErrorMessage', GetLastErrorText());
+            
+            Session.LogMessage(
+                'MYAPP-0002', 
+                'External service call failed', 
+                Verbosity::Error, 
+                DataClassification::SystemMetadata, 
+                TelemetryScope::ExtensionPublisher, 
+                CustomDimensions);
+            exit(false);
+        end;
+
+        Duration := CurrentDateTime() - StartTime;
+        CustomDimensions.Add('Duration', Format(Duration));
+        
+        Session.LogMessage(
+            'MYAPP-0003', 
+            'External service call completed', 
+            Verbosity::Normal, 
+            DataClassification::SystemMetadata, 
+            TelemetryScope::ExtensionPublisher, 
+            CustomDimensions);
+        
+        exit(true);
+    end;
+}
+```
+
+### Poor: Insufficient Telemetry
+```al
+// ❌ No telemetry at all for external call
+procedure CallExternalService(DocumentNo: Code[20]): Boolean
+begin
+    exit(TryCallService(DocumentNo));
+end;
+
+// ❌ Telemetry without context
+Session.LogMessage('MYAPP-0001', 'Service called', Verbosity::Normal, 
+    DataClassification::SystemMetadata, TelemetryScope::ExtensionPublisher);
+```
+
+---
+
+## Access Modifier Strategy
+
+### Good: Intentional Access Control
+```al
+// Public codeunit - this is the partner-facing API
+codeunit 50102 "My Document API"
+{
+    Access = Public;
+
+    // Public procedure - documented contract for partners
+    procedure CreateDocument(CustomerNo: Code[20]): Code[20]
+    var
+        DocProcessor: Codeunit "My Document Processor Internal";
+    begin
+        exit(DocProcessor.CreateDocumentInternal(CustomerNo));
+    end;
+
+    // Public procedure - partners can call this
+    procedure GetDocumentStatus(DocumentNo: Code[20]): Enum "My Document Status"
+    begin
+        exit(GetStatusInternal(DocumentNo));
+    end;
+}
+
+// Internal codeunit - implementation details hidden from partners
+codeunit 50103 "My Document Processor Internal"
+{
+    Access = Internal;
+
+    // Internal procedure - free to refactor
+    procedure CreateDocumentInternal(CustomerNo: Code[20]): Code[20]
+    begin
+        // Implementation that can change without breaking partners
+    end;
+}
+```
+
+### Poor: Unintentional Public Surface
+```al
+// ❌ Everything public by default - massive support surface
+codeunit 50104 "My Codeunit"
+{
+    // All these become partner contracts accidentally
+    procedure DoTheThing()
+    procedure HelperMethod1()
+    procedure HelperMethod2()
+    procedure InternalCalculation()
+    procedure DebugOutput()
+}
+```
+
+---
+
+## Interface Architecture
+
+### Good: Well-Documented Interface Pattern
+```al
+// Clear interface contract
+interface "IShipping Provider"
+{
+    /// <summary>
+    /// Calculates shipping rate for the given shipment parameters.
+    /// </summary>
+    /// <param name="Weight">Total weight in base unit of measure</param>
+    /// <param name="DestinationCountry">ISO country code</param>
+    /// <returns>Shipping cost in LCY</returns>
+    procedure CalculateRate(Weight: Decimal; DestinationCountry: Code[10]): Decimal;
+
+    /// <summary>
+    /// Creates a shipping label and returns the tracking number.
+    /// </summary>
+    /// <param name="ShipmentNo">The shipment document number</param>
+    /// <returns>Carrier tracking number</returns>
+    procedure CreateLabel(ShipmentNo: Code[20]): Text[50];
+}
+
+// Default implementation partners can reference
+codeunit 50110 "Default Shipping Provider" implements "IShipping Provider"
+{
+    procedure CalculateRate(Weight: Decimal; DestinationCountry: Code[10]): Decimal
+    begin
+        // Default flat-rate calculation
+        exit(Weight * 0.50);
+    end;
+
+    procedure CreateLabel(ShipmentNo: Code[20]): Text[50]
+    begin
+        // Default - no label creation
+        exit('');
+    end;
+}
+
+// Registration mechanism
+table 50100 "Shipping Provider Setup"
+{
+    fields
+    {
+        field(1; "Primary Key"; Code[10]) { }
+        field(2; "Provider"; Enum "Shipping Provider") { }
+    }
+}
+
+enum 50100 "Shipping Provider" implements "IShipping Provider"
+{
+    Extensible = true;
+    
+    value(0; Default)
+    {
+        Implementation = "IShipping Provider" = "Default Shipping Provider";
+    }
+}
+```
+
+---
+
+## Partner Readiness Summary Report Template
+
+```al
+// Generate a readiness report for your app
+codeunit 50199 "Partner Readiness Report"
+{
+    procedure GenerateReport()
+    var
+        Report: TextBuilder;
+    begin
+        Report.AppendLine('# Partner Readiness Report');
+        Report.AppendLine('Generated: ' + Format(CurrentDateTime()));
+        Report.AppendLine('');
+        
+        Report.AppendLine('## Event Coverage');
+        Report.AppendLine('- Integration Events: ' + Format(CountIntegrationEvents()));
+        Report.AppendLine('- Business Events: ' + Format(CountBusinessEvents()));
+        Report.AppendLine('');
+        
+        Report.AppendLine('## Access Modifier Summary');
+        Report.AppendLine('- Public Codeunits: ' + Format(CountPublicCodeunits()));
+        Report.AppendLine('- Internal Codeunits: ' + Format(CountInternalCodeunits()));
+        Report.AppendLine('');
+        
+        Report.AppendLine('## Telemetry Coverage');
+        Report.AppendLine('- LogMessage Calls: ' + Format(CountTelemetryCalls()));
+        Report.AppendLine('');
+        
+        Report.AppendLine('## Interface Definitions');
+        Report.AppendLine('- Interfaces: ' + Format(CountInterfaces()));
+        Report.AppendLine('- Implementations: ' + Format(CountImplementations()));
+        
+        Message(Report.ToText());
+    end;
+}
+```

package/embedded-knowledge/domains/quinn-tester/isolation-testing-patterns.md

@@ -0,0 +1,82 @@
+---
+title: "Isolation Testing Patterns with Test Doubles"
+domain: "quinn-tester"
+difficulty: "advanced"
+bc_versions: "18+"
+tags: ["testing", "isolation", "test-doubles", "mocks", "spies", "dependency-injection", "unit-testing"]
+samples: "samples/isolation-testing-patterns.md"
+related_topics:
+  - "../alex-architect/testability-design-patterns.md"
+  - "../roger-reviewer/testability-code-smells.md"
+source: "Adapted from Vjeko.com: Testing in isolation (Dec 2023)"
+---
+# Isolation Testing Patterns with Test Doubles
+
+## Overview
+
+Testing in isolation means testing your code independent from its dependencies. When code is designed with interfaces and dependency injection, you substitute real implementations with "test doubles"—fake implementations giving complete control during testing.
+
+**Core Principle**: Test YOUR code, not your dependencies. Use test doubles to isolate what you're testing from what you're depending on.
+
+## Types of Test Doubles
+
+### Dummy
+A placeholder passed but never used. Satisfies parameter requirements when the dependency isn't exercised in your test path.
+
+### Stub
+Returns predetermined values. Provides canned answers to calls made during test. Use when you need the dependency to return specific values.
+
+### Spy
+Records what happened during execution. Allows assertions about how dependencies were called—was it invoked? With what parameters?
+
+### Mock
+Pre-programmed with expectations. Controls dependency behavior AND verifies interaction patterns.
+
+### Throwing Double
+Simulates errors. Use for testing error handling paths when dependencies fail.
+
+## When to Use Each
+
+| Scenario | Double | Why |
+|----------|--------|-----|
+| Dependency not used in test path | Dummy | Just satisfies signature |
+| Need specific return value | Stub | Control the response |
+| Need to verify it was called | Spy | Record and inspect |
+| Need to control AND verify | Mock | Full control |
+| Dependency might throw errors | Throwing | Test error handling |
+
+## Testing Patterns
+
+**Happy Path**: Permission granted, conversion succeeds, logging occurs. Use stub for converter, spy for logger.
+
+**Permission Denial**: Permission denied, process fails before conversion. Use dummy converter (won't be called), spy to verify no logging.
+
+**Parameter Verification**: Verify dependencies receive correct parameters. Use spy that captures arguments for assertion.
+
+**Error Propagation**: Converter fails, error propagates correctly. Use throwing double, verify logger not invoked.
+
+## Structuring Test Doubles
+
+**Naming**: `[Type] [Interface Name]` - e.g., "Spy Logger", "Stub Converter"
+
+**Organization**: Keep test doubles in test app, organized by interface they implement.
+
+## Test Production Implementations Separately
+
+Test your actual implementations (database permission checker, database logger) directly with simple, focused tests. Then use test doubles when testing business logic that USES those implementations.
+
+## Benefits
+
+- **Speed**: No database = fast tests (hundreds in seconds)
+- **Reliability**: No external dependencies = no flaky tests
+- **Focus**: Test exactly what you mean to test
+- **Maintainability**: Dependency changes don't break business logic tests
+
+## When You Still Need Integration Tests
+
+Isolation tests verify your code works given certain dependency behaviors. Integration tests verify dependencies are wired correctly and end-to-end scenarios function.
+
+**Rule**: Many isolation tests, few integration tests. The pyramid, not the ice cream cone.
+
+See samples for complete test double implementations and test codeunit examples.
+