Merge pull request finos#1592 from LeighFinegold/feature/document-block-architecture-widget

Block Architecture Widget

Author: rocketstack-matt

calm-widgets/README.md

@@ -124,9 +124,182 @@ classDef highlight fill:#f2bbae;
 ```
 
 
-5. **Test thoroughly** with `npm test`
 
+### Block Architecture Widget
+
+Renders a system architecture as a Mermaid flowchart with optional containers (systems), interfaces, highlights, and flow-focused slices.
+
+```handlebars
+{{!-- Basic: render entire architecture --}}
+{{block-architecture this}}
+
+{{!-- Hide containers (just the services) --}}
+{{block-architecture this include-containers="none"}}
+
+{{!-- Show node interfaces as small attachment boxes --}}
+{{block-architecture this render-interfaces=true}}
+
+{{!-- Focus specific nodes (comma-separated) and highlight them --}}
+{{block-architecture this focus-nodes="trading-system,position-system" highlight-nodes="trade-svc,position-svc"}}
+
+{{!-- Focus one or more flows by unique-id or name (case-insensitive) --}}
+{{block-architecture this focus-flows="order-flow"}}
+
+{{!-- Flow focus + hide containers --}}
+{{block-architecture this focus-flows="order-flow" include-containers="none"}}
+
+{{!-- Multiple flows --}}
+{{block-architecture this focus-flows="order-flow,onboarding-flow"}}
+```
+
+**What it shows**
+- **Containers (systems)** as Mermaid subgraphs, with contained **nodes (services, dbs, etc.)** inside.
+- Optional **interfaces** as dotted attachments to their parent node.
+- **Edges** for `connects`/`interacts` relationships, using the relationship **`description`** as the label when present.
+- **Highlights** for any nodes listed in `highlight-nodes`.
+- Optional **clickable links** per node/interface (via `link-prefix` or `link-map`).
+
+**Options**
+
+| Option                | Type | Default | Description |
+|-----------------------|---|---:|---|
+| `focus-nodes`         | string (CSV) | — | Restrict the view to these node IDs (and, if containers are shown, their parent/child context per other options). |
+| `focus-relationships` | string (CSV) | — | Restrict view to the specified relationship unique-ids. Only those relationships and the nodes they connect are included (plus containers per settings). |
+| `focus-flows`         | string (CSV) | — | Restrict edges to transitions that belong to the given **flow unique-ids or names** (case-insensitive). Only nodes touching those edges are included (plus containers per settings). |
+| `focus-controls`      | string (CSV) | — | Restrict view to nodes and relationships linked to the specified control IDs. Only nodes touching those controls are included (plus containers per settings). |
+| `focus-interfaces`    | string (CSV) | — | Restrict view to nodes and relationships linked to the specified interface IDs. Only nodes touching those interfaces are included (plus containers per settings). || `highlight-nodes`     | string (CSV) | — | Nodes to visually highlight. |
+| `render-interfaces`   | boolean | `false` | If `true`, render each node’s `interfaces` as small interface boxes connected by dotted lines. |
+| `include-containers`  | `'none' \| 'parents' \| 'all'` | `'all'` | Which containers (systems) to draw. |
+| `include-children`    | `'none' \| 'direct' \| 'all'` | `'all'` | When focusing container nodes, include their direct/all descendants. |
+| `edges`               | `'connected' \| 'seeded' \| 'all' \| 'none'` | `'connected'` | For non-flow views, expand visible set with directly connected neighbors. When flows are focused, only flow edges are shown. |
+| `node-types`          | string (CSV) | — | Only include nodes whose `node-type` is in this list. |
+| `direction`           | `'both' \| 'in' \| 'out'` | `'both'` | Reserved (currently not used by the renderer). |
+| `edge-labels`         | `'description' \| 'none'` | `'description'` | Use the relationship `description` for edge labels; or hide labels entirely. |
+| `link-prefix`         | string | — | Prefix for clickable `click` links in Mermaid (e.g., `/docs/` makes `/docs/<node-id>`). |
+| `link-map`            | stringified JSON map | — | Explicit per-id links, e.g. `{"trade-svc": "/svc/trade"}`. Map entries override `link-prefix`. |
+
+> **Sorting:** Containers and nodes are always sorted **alphabetically by label** for stable layouts.
+
+**Context requirements**
+- The context must be a **CALM core canonical model**, e.g. `{ nodes, relationships, flows? }`.
+- To use `focus-flows`, `context.flows` must include the target flows. Each flow’s `transitions[*].relationship-unique-id` must point to a relationship in `context.relationships`.
+
+**Example Visual**
+
+For more examples, see the test fixtures:
+- [Basic structures](./test-fixtures/block-architecture-widget/basic-structures/)
+- [Enterprise trading system](./test-fixtures/block-architecture-widget/enterprise-bank-trading/)
+- [Interface variations](./test-fixtures/block-architecture-widget/interface-variations/)
+- [Focus flows](./test-fixtures/block-architecture-widget/focus-flows/)
+- [Domain interaction](./test-fixtures/block-architecture-widget/domain-interaction/)
+
+#### Example block architecture diagram with interfaces
+
+```mermaid
+%%{init: {"flowchart": {"htmlLabels": false}}}%%
+flowchart TB
+classDef boundary fill:#f8fafc,stroke:#64748b,stroke-dasharray: 5 4,stroke-width:2px,color:#000;
+classDef node fill:#ffffff,stroke:#1f2937,stroke-width:1px,color:#000;
+classDef iface fill:#f1f5f9,stroke:#64748b,stroke-width:1px,font-size:10px,color:#000;
+classDef highlight fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#000;
+
+        subgraph enterprise-bank["Enterprise Bank"]
+        direction TB
+                subgraph messaging-system["Messaging System"]
+                direction TB
+                    message-bus["Message Bus"]:::node
+                        message-bus__iface__trade-events-topic["◻ Trade Events Topic"]:::iface
+                end
+                class messaging-system boundary
+                subgraph trading-system["Trading System"]
+                direction TB
+                    trade-svc["Trade Service"]:::node
+                        trade-svc__iface__api["◻ API: /trades"]:::iface
+                        trade-svc__iface__jdbc["◻ JDBC: trading-db"]:::iface
+                        trade-svc__iface__events["◻ Topic: trade.events"]:::iface
+                    trading-db["Trading DB"]:::node
+                        trading-db__iface__sql["◻ SQL Interface"]:::iface
+                    trading-ui["Trading UI"]:::node
+                        trading-ui__iface__web-ui["◻ Web Interface"]:::iface
+                end
+                class trading-system boundary
+        end
+        class enterprise-bank boundary
+
+
+    trading-ui__iface__web-ui -->|Place Trade| trade-svc__iface__api
+    trade-svc__iface__jdbc -->|Persist| trading-db__iface__sql
+    trade-svc__iface__events -->|Publish Events| message-bus__iface__trade-events-topic
+
+    trading-ui -.- trading-ui__iface__web-ui
+    trade-svc -.- trade-svc__iface__api
+    trade-svc -.- trade-svc__iface__jdbc
+    trade-svc -.- trade-svc__iface__events
+    trading-db -.- trading-db__iface__sql
+    message-bus -.- message-bus__iface__trade-events-topic
+
+    class trade-svc highlight
+    class trading-ui highlight
+    class trading-db highlight
+    class message-bus highlight
+                        click message-bus "#message-bus" "Jump to Message Bus"
+                            click message-bus__iface__trade-events-topic "#message-bus__iface__trade-events-topic" "Jump to ◻ Trade Events Topic"
+                                        click trade-svc "#trade-service" "Jump to Trade Service"
+                            click trade-svc__iface__api "#trade-service-api" "Jump to ◻ API: /trades"
+                            click trade-svc__iface__jdbc "#trade-service-storage" "Jump to ◻ JDBC: trading-db"
+                            click trade-svc__iface__events "#trade-service-events" "Jump to ◻ Topic: trade.events"
+                        click trading-db "#trading-db" "Jump to Trading DB"
+                            click trading-db__iface__sql "#trading-db__iface__sql" "Jump to ◻ SQL Interface"
+                                click trading-ui "#trading-ui" "Jump to Trading UI"
+                            click trading-ui__iface__web-ui "#trading-ui__iface__web-ui" "Jump to ◻ Web Interface"
+
+```
+
+---
+
+#### Example block architecture diagram without interfaces
 
+```mermaid
+%%{init: {"flowchart": {"htmlLabels": false}}}%%
+flowchart TB
+classDef boundary fill:#f8fafc,stroke:#64748b,stroke-dasharray: 5 4,stroke-width:2px,color:#000;
+classDef node fill:#ffffff,stroke:#1f2937,stroke-width:1px,color:#000;
+classDef iface fill:#f1f5f9,stroke:#64748b,stroke-width:1px,font-size:10px,color:#000;
+classDef highlight fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#000;
+
+        subgraph enterprise-bank["Enterprise Bank"]
+        direction TB
+                subgraph messaging-system["Messaging System"]
+                direction TB
+                    message-bus["Message Bus"]:::node
+                end
+                class messaging-system boundary
+                subgraph trading-system["Trading System"]
+                direction TB
+                    trade-svc["Trade Service"]:::node
+                    trading-db["Trading DB"]:::node
+                    trading-ui["Trading UI"]:::node
+                end
+                class trading-system boundary
+        end
+        class enterprise-bank boundary
+
+
+    trading-ui -->|Place Trade| trade-svc
+    trade-svc -->|Persist| trading-db
+    trade-svc -->|Publish Events| message-bus
+
+
+    class trade-svc highlight
+    class trading-ui highlight
+    class trading-db highlight
+    class message-bus highlight
+                        click message-bus "#message-bus" "Jump to Message Bus"
+                        click trade-svc "#trade-service" "Jump to Trade Service"
+                        click trading-db "#trading-db" "Jump to Trading DB"
+                        click trading-ui "#trading-ui" "Jump to Trading UI"
+
+```
 
 ## 🛠️ Creating Custom Widgets
 
@@ -157,20 +330,20 @@ export interface MyWidgetViewModel {
 
 export const MyWidget: CalmWidget<
   MyWidgetContext,
-  MyWidgetOptions, 
+  MyWidgetOptions,
   MyWidgetViewModel
 > = {
   id: 'my-widget',
   templatePartial: 'my-widget-template.html',
-  
+
   // Optional: additional template partials
   partials: ['item-template.html'],
-  
+
   // Transform input data to view model
   transformToViewModel: (context, options) => {
     const showCount = options?.hash?.showCount ?? false;
     const prefix = options?.hash?.prefix ?? '•';
-    
+
     return {
       title: context.title,
       items: context.items,
@@ -198,6 +371,8 @@ export const MyWidget: CalmWidget<
 };
 ```
 
+
+
 ### 2. Template Files
 
 Create Handlebars templates for your widget:

calm-widgets/src/test-utils/fixture-loader.ts

@@ -31,7 +31,24 @@ export class FixtureLoader {
             throw new Error(`Expected file not found: ${expectedPath}`);
         }
 
-        const context = JSON.parse(fs.readFileSync(contextPath, 'utf-8'));
+        const rawContext = fs.readFileSync(contextPath, 'utf-8');
+        let context: unknown;
+        try {
+            context = JSON.parse(rawContext);
+        } catch {
+            // Try to be forgiving: strip common markdown code fences and JS-style comments
+            const stripped = rawContext
+                .replace(/^\uFEFF/, '') // BOM
+                .replace(/```(?:json)?\n?|```/g, '') // remove ```json fences
+                .replace(/\/\/.*$/gm, '') // remove // line comments
+                .replace(/\/\*[\s\S]*?\*\//g, '') // remove /* */ block comments
+                .trim();
+            try {
+                context = JSON.parse(stripped);
+            } catch (err2) {
+                throw new Error(`Failed to parse JSON context file ${contextPath}: ${err2 instanceof Error ? err2.message : String(err2)}`);
+            }
+        }
         const template = fs.readFileSync(templatePath, 'utf-8');
         const expected = fs.readFileSync(expectedPath, 'utf-8').trim();
 

calm-widgets/src/widget-engine.spec.ts

@@ -122,15 +122,16 @@ describe('WidgetEngine', () => {
     });
 
     describe('registerDefaultWidgets', () => {
-        it('registers the default widgets (list, table, json-viewer)', () => {
+        it('registers the default widgets (list, table, json-viewer, flow-sequence, related-nodes, block-architecture)', () => {
             engine.registerDefaultWidgets();
 
-            expect(registerMock).toHaveBeenCalledTimes(5);
+            expect(registerMock).toHaveBeenCalledTimes(6);
             expect(localHandlebars.registerHelper).toHaveBeenCalledWith('list', expect.any(Function));
             expect(localHandlebars.registerHelper).toHaveBeenCalledWith('table', expect.any(Function));
             expect(localHandlebars.registerHelper).toHaveBeenCalledWith('json-viewer', expect.any(Function));
             expect(localHandlebars.registerHelper).toHaveBeenCalledWith('flow-sequence', expect.any(Function));
             expect(localHandlebars.registerHelper).toHaveBeenCalledWith('related-nodes', expect.any(Function));
+            expect(localHandlebars.registerHelper).toHaveBeenCalledWith('block-architecture', expect.any(Function));
         });
     });
 });

calm-widgets/src/widget-engine.ts

@@ -9,6 +9,7 @@ import { ListWidget } from './widgets/list';
 import { JsonViewerWidget } from './widgets/json-viewer';
 import { FlowSequenceWidget } from './widgets/flow-sequence';
 import { RelatedNodesWidget } from './widgets/related-nodes';
+import { BlockArchitectureWidget } from './widgets/block-architecture';
 
 export class WidgetEngine {
     constructor(
@@ -70,6 +71,10 @@ export class WidgetEngine {
                 widget: RelatedNodesWidget as CalmWidget<unknown, object, unknown>,
                 folder: __dirname + '/widgets/related-nodes',
             },
+            {
+                widget: BlockArchitectureWidget as CalmWidget<unknown, object, unknown>,
+                folder: __dirname + '/widgets/block-architecture',
+            },
         ];
         this.setupWidgets(widgets);
     }

calm-widgets/src/widget-helpers.ts

@@ -65,6 +65,20 @@ export function registerGlobalTemplateHelpers(): Record<string, (...args: unknow
             return actualArgs.some(Boolean);
         },
 
+        length: (value: unknown): number => {
+            if (Array.isArray(value) || typeof value === 'string') return value.length;
+            if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                return Object.keys(value).length;
+            }
+            return 0;
+        },
+
+        gt: (a: unknown, b: unknown): boolean => {
+            const an = typeof a === 'number' ? a : Number(a);
+            const bn = typeof b === 'number' ? b : Number(b);
+            return an > bn;
+        },
+
         eachInMap: (map: unknown, options: unknown): string => {
             let result = '';
             if (

calm-widgets/src/widgets.e2e.spec.ts

@@ -205,4 +205,93 @@ describe('Widgets E2E - Handlebars Integration', () => {
             expect(result.trim()).toBe(expected);
         });
     });
+
+    describe('Block Architecture Widget', () => {
+        it('renders basic architecture structures (empty, single system, multiple systems)', () => {
+            const { context, template, expected } = fixtures.loadFixture('block-architecture-widget', 'basic-structures');
+            const compiled = handlebars.compile(template);
+            const result = compiled(context);
+            expect(result.trim()).toBe(expected);
+        });
+
+        // Interface rendering variations - consolidated from interfaces-off, interfaces-on-both, interfaces-on-one-side
+        it('handles all interface rendering variations in one comprehensive test', () => {
+            const { context, template, expected } = fixtures.loadFixture('block-architecture-widget', 'interface-variations');
+            const compiled = handlebars.compile(template);
+            const result = compiled(context);
+            expect(result.trim()).toBe(expected);
+        });
+
+        // Complex real-world scenarios - keep these as they demonstrate practical use cases
+        it('renders enterprise bank trading system with mixed communication patterns', () => {
+            const { context, template, expected } = fixtures.loadFixture('block-architecture-widget', 'enterprise-bank-trading');
+            const compiled = handlebars.compile(template);
+            const result = compiled(context);
+            expect(result.trim()).toBe(expected);
+        });
+
+        it('renders enterprise bank with clickable navigation pattern and progressive detail levels', () => {
+            const { context, template, expected } = fixtures.loadFixture('block-architecture-widget', 'enterprise-bank-navigation');
+            const compiled = handlebars.compile(template);
+            const result = compiled(context);
+            expect(result.trim()).toBe(expected);
+        });
+
+        it('renders a nested architecture with nested relationships', () => {
+            const { context, template, expected } = fixtures.loadFixture('block-architecture-widget', 'nested-architecture');
+            const compiled = handlebars.compile(template);
+            const result = compiled(context);
+            expect(result.trim()).toBe(expected);
+        });
+
+        it('renders large topology with many nodes and connections efficiently', () => {
+            const { context, template, expected } = fixtures.loadFixture('block-architecture-widget', 'large-topology');
+            const compiled = handlebars.compile(template);
+            const result = compiled(context);
+            expect(result.trim()).toBe(expected);
+        });
+
+        it('applies domain interaction diagram', () => {
+            const { context, template, expected } = fixtures.loadFixture('block-architecture-widget', 'domain-interaction');
+            const compiled = handlebars.compile(template);
+            const result = compiled(context);
+            expect(result.trim()).toBe(expected);
+        });
+
+        // New focus flows test - demonstrates flow-based filtering
+        it('filters architecture based on specific flows', () => {
+            const { context, template, expected } = fixtures.loadFixture('block-architecture-widget', 'focus-flows');
+            const compiled = handlebars.compile(template);
+            const result = compiled(context);
+            expect(result.trim()).toBe(expected);
+        });
+
+        it('filters architecture based on interface matching by unique-id and properties', () => {
+            const { context, template, expected } = fixtures.loadFixture('block-architecture-widget', 'focus-interfaces');
+            const compiled = handlebars.compile(template);
+            const result = compiled(context);
+            expect(result.trim()).toBe(expected);
+        });
+
+        it('filters architecture based on control matching by ID and properties', () => {
+            const { context, template, expected } = fixtures.loadFixture('block-architecture-widget', 'focus-controls');
+            const compiled = handlebars.compile(template);
+            const result = compiled(context);
+            expect(result.trim()).toBe(expected);
+        });
+
+        it('filters architecture based on node focusing with comprehensive scenarios', () => {
+            const { context, template, expected } = fixtures.loadFixture('block-architecture-widget', 'focus-nodes');
+            const compiled = handlebars.compile(template);
+            const result = compiled(context);
+            expect(result.trim()).toBe(expected);
+        });
+
+        it('filters architecture based on relationship focusing by unique-id', () => {
+            const { context, template, expected } = fixtures.loadFixture('block-architecture-widget', 'focus-relationships');
+            const compiled = handlebars.compile(template);
+            const result = compiled(context);
+            expect(result.trim()).toBe(expected);
+        });
+    });
 });