@cratis/screenplay-language 4.17.0 → 4.18.0

package/for_validateLines/when_validating_event_context_paths/in_a_projection.ts

@@ -0,0 +1,97 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, beforeEach, it } from 'vitest';
+import { diagnosticCodes } from '../../diagnostic-codes';
+import { eventContextPaths } from '../../event-context';
+import { ValidationIssue, validateLines } from '../../validation';
+
+function validate(...mappings: string[]): ValidationIssue[] {
+    return validateLines([
+        'projection Statistics => StatisticsReadModel',
+        '  from Happened',
+        ...mappings.map((mapping) => `    ${mapping}`),
+    ]);
+}
+
+describe('when validating every event context path the catalog lists', () => {
+    let issues: ValidationIssue[];
+
+    beforeEach(() => {
+        issues = validate(
+            ...eventContextPaths.map((path, index) => `value${index} = $eventContext.${path.path}`),
+            ...eventContextPaths.map((path) => `count countBy.$eventContext.${path.path}`),
+            'week = $eventContext.occurred.Week()',
+            'type = $eventContext.EventType.Id',
+        );
+    });
+
+    it('should report nothing', () => {
+        issues.should.be.empty;
+    });
+});
+
+describe('when validating an unknown event context member', () => {
+    let issues: ValidationIssue[];
+
+    beforeEach(() => {
+        issues = validate('cause = $eventContext.causationId');
+    });
+
+    it('should warn with the compiler code', () => {
+        issues.map((issue) => [issue.code, issue.severity]).should.deep.equal([[diagnosticCodes.unknownEventContextMember, 'warning']]);
+    });
+
+    it('should squiggle the whole path', () => {
+        const [issue] = issues;
+        [issue.startColumn, issue.endColumn].should.deep.equal([13, 13 + '$eventContext.causationId'.length]);
+    });
+});
+
+describe('when validating an unknown event context sub-path', () => {
+    let issues: ValidationIssue[];
+
+    beforeEach(() => {
+        issues = validate('week = $eventContext.occurred.week');
+    });
+
+    it('should warn with the compiler code', () => {
+        issues.map((issue) => [issue.code, issue.severity]).should.deep.equal([[diagnosticCodes.unknownEventContextPath, 'warning']]);
+    });
+});
+
+describe('when validating a path below an event context collection', () => {
+    let issues: ValidationIssue[];
+
+    beforeEach(() => {
+        issues = validate('count byTag.$eventContext.tags.value');
+    });
+
+    it('should report an error with the compiler code', () => {
+        issues.map((issue) => [issue.code, issue.severity]).should.deep.equal([[diagnosticCodes.eventContextPathBelowCollection, 'error']]);
+    });
+});
+
+describe('when validating a dynamic key naming no event context member', () => {
+    let issues: ValidationIssue[];
+
+    beforeEach(() => {
+        issues = validate('count byNothing.$eventContext');
+    });
+
+    it('should report an error with the compiler code', () => {
+        issues.map((issue) => [issue.code, issue.severity]).should.deep.equal([[diagnosticCodes.missingEventContextPath, 'error']]);
+    });
+});
+
+describe('when validating a dynamic key naming another source', () => {
+    let issues: ValidationIssue[];
+
+    beforeEach(() => {
+        issues = validate('count byUser.$causedBy.subject');
+    });
+
+    it('should warn with the compiler code', () => {
+        issues.map((issue) => [issue.code, issue.severity]).should.deep.equal([[diagnosticCodes.unresolvedDynamicKeySource, 'warning']]);
+    });
+});

package/index.ts

@@ -100,6 +100,8 @@ export type {
     TypeSymbol,
 } from './symbols';
 export { attributeDocs, contextVariableDocs, keywordDocs } from './keyword-docs';
+export { eventContextMemberAt, eventContextMembers, eventContextMembersAfter, eventContextPaths, namesEventContextMember } from './event-context';
+export type { EventContextMember, EventContextPath } from './event-context';
 export { contextVariableItems, producesItems } from './completion-items';
 export type { CompletionEntry } from './completion-items';
 export { completionEntriesFor, planCompletions } from './completion-planner';

package/keyword-docs.ts

@@ -1,6 +1,8 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import { eventContextPaths } from './event-context';
+
 export const keywordDocs: Record<string, string> = {
     domain: 'The domain the file belongs to — optional, at most one per file, before everything else.',
     import: 'Imports a type from another module; it becomes available by its short name.',
@@ -128,5 +130,6 @@ export const contextVariableDocs: Record<string, string> = {
     '$env': 'An environment variable, e.g. `$env.SERVICE_NAME`.',
     '$secrets': 'An encrypted secret resolved at runtime, e.g. `$secrets.azureAdClientId` — stays symbolic in the compiled tree.',
     '$strings': 'A localized string resolved from the `.strings` file of the active locale, e.g. `$strings.invoices.title`.',
-    '$eventContext.occurred': 'The timestamp of the event being projected.',
+    // Every $eventContext path the event-context catalog lists, for projections.
+    ...Object.fromEntries(eventContextPaths.map((path) => [`$eventContext.${path.path}`, path.description])),
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/screenplay-language",
-    "version": "4.17.0",
+    "version": "4.18.0",
     "description": "Monaco language service for the Cratis Screenplay DSL — syntax highlighting, IntelliSense, hover and diagnostics for .play files",
     "keywords": [
         "cratis",

package/sub-languages/projection/CompletionProvider.ts

@@ -3,6 +3,7 @@
 
 import type { editor, languages, IRange, Position } from 'monaco-editor';
 import type { JsonSchema, JsonSchemaProperty, ReadModelInfo } from './index';
+import { eventContextMembers, eventContextMembersAfter } from '../../event-context';
 
 interface CompletionContext {
     lineContent: string;
@@ -13,6 +14,10 @@ interface CompletionContext {
     lineNumber: number;
 }
 
+// The path typed so far after $eventContext. - on its own or as the dynamic key of a mapping target - and the
+// partial segment under the cursor.
+const EVENT_CONTEXT_PATH = /\$eventContext\.((?:\w+\.)*)(\w*)$/;
+
 export class CompletionProvider implements languages.CompletionItemProvider {
     private readModels: ReadModelInfo[] = [];
     private eventSchemas: Record<string, JsonSchema> = {};
@@ -177,7 +182,10 @@ export class CompletionProvider implements languages.CompletionItemProvider {
     }
 
     private isPropertyDotAccess(context: CompletionContext): boolean {
-        return /(\w+|\$\w+)\.(\w*)$/.test(context.textBeforeCursor);
+        // A member of an event property or a $-expression, or any depth of an event-context path - written as an
+        // expression or as the dynamic key of a mapping target (propertyName.$eventContext.<path>).
+        return /(\w+|\$\w+)\.(\w*)$/.test(context.textBeforeCursor) ||
+               EVENT_CONTEXT_PATH.test(context.textBeforeCursor);
     }
 
     private addProjectionLineCompletions(suggestions: languages.CompletionItem[], context: CompletionContext): void {
@@ -501,37 +509,14 @@ export class CompletionProvider implements languages.CompletionItemProvider {
             {
                 label: '$causedBy',
                 insertText: '$causedBy',
-                documentation: 'Information about who/what caused the event',
-                detail: 'Identity Expression',
-                children: [
-                    { name: 'subject', doc: 'The subject identifier' },
-                    { name: 'name', doc: 'The display name' },
-                    { name: 'userName', doc: 'The username' },
-                ]
+                documentation: 'The identity that caused the event. Chronicle cannot yet evaluate this short form (Cratis/Chronicle#4119) - prefer $eventContext.causedBy.<property>.',
+                detail: 'Identity Expression'
             },
             {
                 label: '$eventContext',
                 insertText: '$eventContext.',
-                documentation: 'Access event context properties',
-                detail: 'Event Context Expression',
-                children: [
-                    { name: 'sequenceNumber', doc: 'The event sequence number' },
-                    { name: 'occurred', doc: 'When the event occurred' },
-                    { name: 'eventSourceId', doc: 'The event source identifier' },
-                    { name: 'namespace', doc: 'The event namespace' },
-                ]
-            },
-            {
-                label: '$occurred',
-                insertText: '$occurred',
-                documentation: 'Timestamp when the event occurred',
-                detail: 'Occurred Expression'
-            },
-            {
-                label: '$namespace',
-                insertText: '$namespace',
-                documentation: 'The namespace of the event',
-                detail: 'Namespace Expression'
+                documentation: `Metadata about the event: ${eventContextMembers.map((member) => member.name).join(', ')}`,
+                detail: 'Event Context Expression'
             },
         ];
 
@@ -550,55 +535,24 @@ export class CompletionProvider implements languages.CompletionItemProvider {
     }
 
     private addPropertyMemberCompletions(suggestions: languages.CompletionItem[], context: CompletionContext): void {
+        // Any depth of an event-context path, as an expression or as a dynamic key (propertyName.$eventContext.<path>)
+        const eventContextMatch = context.textBeforeCursor.match(EVENT_CONTEXT_PATH);
+        if (eventContextMatch) {
+            const segments = eventContextMatch[1].split('.').filter((segment) => segment.length > 0);
+            this.addEventContextMemberCompletions(suggestions, context, segments, eventContextMatch[2]);
+            return;
+        }
+
         const match = context.textBeforeCursor.match(/(\w+|\$\w+)\.(\w*)$/);
         if (!match) return;
 
         const [, objectName, partialProp] = match;
 
-        // Handle $causedBy properties
-        if (objectName === '$causedBy') {
-            const causedByProps = [
-                { name: 'subject', doc: 'The subject identifier', type: 'string' },
-                { name: 'name', doc: 'The display name', type: 'string' },
-                { name: 'userName', doc: 'The username', type: 'string' },
-            ];
-
-            causedByProps.forEach((prop) => {
-                if (!partialProp || prop.name.startsWith(partialProp)) {
-                    suggestions.push({
-                        label: prop.name,
-                        kind: 9,
-                        insertText: prop.name,
-                        documentation: prop.doc,
-                        detail: prop.type,
-                        range: this.getRangeForWord(context),
-                    });
-                }
-            });
-            return;
-        }
-
-        // Handle $eventContext properties
-        if (objectName === '$eventContext') {
-            const contextProps = [
-                { name: 'sequenceNumber', doc: 'The event sequence number', type: 'EventSequenceNumber' },
-                { name: 'occurred', doc: 'When the event occurred', type: 'DateTimeOffset' },
-                { name: 'eventSourceId', doc: 'The event source identifier', type: 'string' },
-                { name: 'namespace', doc: 'The event namespace', type: 'string' },
-            ];
-
-            contextProps.forEach((prop) => {
-                if (!partialProp || prop.name.startsWith(partialProp)) {
-                    suggestions.push({
-                        label: prop.name,
-                        kind: 9,
-                        insertText: prop.name,
-                        documentation: prop.doc,
-                        detail: prop.type,
-                        range: this.getRangeForWord(context),
-                    });
-                }
-            });
+        // $causedBy is the short form of $eventContext.causedBy, at any depth
+        const causedByMatch = context.textBeforeCursor.match(/\$causedBy\.((?:\w+\.)*)(\w*)$/);
+        if (causedByMatch) {
+            const segments = causedByMatch[1].split('.').filter((segment) => segment.length > 0);
+            this.addEventContextMemberCompletions(suggestions, context, ['causedBy', ...segments], causedByMatch[2]);
             return;
         }
 
@@ -620,6 +574,27 @@ export class CompletionProvider implements languages.CompletionItemProvider {
         }
     }
 
+    private addEventContextMemberCompletions(
+        suggestions: languages.CompletionItem[],
+        context: CompletionContext,
+        segments: readonly string[],
+        partial: string
+    ): void {
+        const members = eventContextMembersAfter(segments) ?? [];
+        members
+            .filter((member) => !partial || member.name.startsWith(partial))
+            .forEach((member) => {
+                suggestions.push({
+                    label: member.name,
+                    kind: member.kind === 'function' ? 1 : 9,
+                    insertText: member.name,
+                    documentation: member.description,
+                    detail: member.type,
+                    range: this.getRangeForWord(context),
+                });
+            });
+    }
+
     private getCurrentEventType(model: editor.ITextModel, lineNumber: number): string | null {
         // Search backwards to find the event type declaration
         for (let i = lineNumber; i >= 1; i--) {

package/sub-languages/projection/HoverProvider.ts

@@ -3,6 +3,7 @@
 
 import type { editor, languages, Position } from 'monaco-editor';
 import type { JsonSchema, JsonSchemaProperty, ReadModelInfo, DraftReadModelInfo } from './index';
+import { describeEventContext, describeEventContextMember, eventContextMemberAt } from '../../event-context';
 
 export class HoverProvider implements languages.HoverProvider {
     private readModels: ReadModelInfo[] = [];
@@ -67,6 +68,20 @@ export class HoverProvider implements languages.HoverProvider {
             };
         }
 
+        // A segment of an $eventContext path - before keywords, since a member such as 'id' is also a keyword
+        const eventContextInfo = this.getEventContextInfo(lineContent, word.startColumn);
+        if (eventContextInfo) {
+            return {
+                contents: [{ value: eventContextInfo }],
+                range: {
+                    startLineNumber: position.lineNumber,
+                    startColumn: word.startColumn,
+                    endLineNumber: position.lineNumber,
+                    endColumn: word.endColumn,
+                },
+            };
+        }
+
         // Check if it's a keyword
         const keywordInfo = this.getKeywordInfo(wordText);
         if (keywordInfo) {
@@ -224,15 +239,36 @@ export class HoverProvider implements languages.HoverProvider {
     private getExpressionInfo(word: string): string | null {
         const expressions: Record<string, string> = {
             '$eventSourceId': '**$eventSourceId**\n\nThe identifier of the event source (aggregate/entity) that generated the event.',
-            '$causedBy': '**$causedBy**\n\nInformation about who/what caused the event.\n\n**Properties:**\n- `subject` - The subject identifier\n- `name` - The display name\n- `userName` - The username',
-            '$eventContext': '**$eventContext**\n\nAccess to event context properties.\n\n**Properties:**\n- `sequenceNumber` - The event sequence number\n- `occurred` - When the event occurred\n- `eventSourceId` - The event source identifier\n- `namespace` - The event namespace',
-            '$occurred': '**$occurred**\n\nThe timestamp when the event occurred.',
-            '$namespace': '**$namespace**\n\nThe namespace of the event.',
+            '$causedBy': '**$causedBy**\n\nThe identity that caused the event - `subject`, `name`, `userName` or `onBehalfOf`, itself an identity.\n\nChronicle cannot yet evaluate this short form (Cratis/Chronicle#4119); prefer **$eventContext.causedBy**.*property*.',
+            '$eventContext': describeEventContext(),
         };
 
         return expressions[word] || null;
     }
 
+    // Describes the $eventContext path segment starting at the given column, if the word there is one.
+    private getEventContextInfo(lineContent: string, startColumn: number): string | null {
+        for (const match of lineContent.matchAll(/\$eventContext((?:\.\w+(?:\(\))?)*)/g)) {
+            let column = (match.index ?? 0) + 1;
+            if (startColumn === column) return describeEventContext();
+
+            column += '$eventContext'.length;
+            const segments = match[1].split('.').slice(1);
+            for (let index = 0; index < segments.length; index++) {
+                column += 1;
+                if (startColumn === column) {
+                    const path = segments.slice(0, index + 1);
+                    const member = eventContextMemberAt(path);
+                    return member ? describeEventContextMember(path.join('.'), member) : null;
+                }
+
+                column += segments[index].length;
+            }
+        }
+
+        return null;
+    }
+
     private getPropertyInfo(model: editor.ITextModel, position: Position, propertyName: string): string | null {
         // Try to find the active read model
         const firstLine = model.getLineContent(1).trim();

package/sub-languages/projection/Validator.ts

@@ -3,6 +3,8 @@
 
 import type { editor } from 'monaco-editor';
 import type { JsonSchema, ReadModelInfo, DraftReadModelInfo } from './index';
+import { fenceMap } from '../../document-context';
+import { validateEventContextPaths } from '../../validation';
 
 export class Validator {
     private readModels: ReadModelInfo[] = [];
@@ -349,6 +351,19 @@ export class Validator {
             }
         }
 
+        // Share the host's event-context path checks and catalog resolution, including dynamic dictionary keys.
+        for (const issue of validateEventContextPaths(lines, fenceMap(lines))) {
+            markers.push({
+                severity: issue.severity === 'error' ? 8 : 4,
+                startLineNumber: issue.line + 1,
+                endLineNumber: issue.line + 1,
+                startColumn: issue.startColumn,
+                endColumn: issue.endColumn,
+                message: issue.message,
+                code: issue.code,
+            });
+        }
+
         return markers;
     }
 

package/sub-languages/projection/language.ts

@@ -45,8 +45,6 @@ const KEYWORDS = [
 const BUILTINS = [
     '$eventSourceId',
     '$causedBy',
-    '$occurred',
-    '$namespace',
     '$eventContext',
 ] as const;
 

package/validation.ts

@@ -4,6 +4,7 @@
 import { causedByProperties, contextRoots, identityProperties, primitiveTypes, sliceTypes } from './language';
 import { DiagnosticCode, diagnosticCodes } from './diagnostic-codes';
 import { fenceMap, indentOf } from './document-context';
+import { resolveEventContextPath } from './event-context';
 import {
     DocumentSymbols,
     PropertySymbol,
@@ -305,6 +306,8 @@ export function validateLines(lines: string[]): ValidationIssue[] {
         }
     }
 
+    issues.push(...validateEventContextPaths(lines, fences));
+
     const fenceLines = lines
         .map((line, index) => ({ line, index }))
         .filter(({ line }) => /^\s*```\s*$/.test(line));
@@ -324,3 +327,59 @@ export function validateLines(lines: string[]): ValidationIssue[] {
 
     return issues;
 }
+
+// A mapping target: the first word of a mapping line, after the keyword that opens it if there is one.
+const mappingTarget = /^(?:(?:increment|decrement|count|clear|add|subtract|set)\s+)?@?([$\w.]+)(?=\s|=|$)/;
+
+// Every $eventContext.<path> - in an expression or as the dynamic key of a mapping target - checked against the
+// event-context catalog the way the compiler checks it (Parsing/EventContextPathValidator.cs).
+export function validateEventContextPaths(lines: string[], fences: boolean[]): ValidationIssue[] {
+    const issues: ValidationIssue[] = [];
+    const names = (members: readonly { name: string }[]) => members.map((member) => member.name).join(', ');
+
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index];
+        if (fences[index]) continue;
+
+        for (const match of line.matchAll(/(\.)?\$eventContext((?:\.(?:\w+(?:\(\))?)?)*)/g)) {
+            const token = match[0].substring(match[1]?.length ?? 0);
+            const written = match[2];
+            if (written.length === 0) {
+                // A bare $eventContext names nothing only as a dynamic key; in an expression the compiler rejects it as invalid.
+                if (match[1]) {
+                    issues.push(issue('error', index, (match.index ?? 0) + 2, token.length, `'$eventContext' names no member - expected one of ${names(resolveEventContextPath('').expected)}.`, diagnosticCodes.missingEventContextPath));
+                }
+                continue;
+            }
+
+            const path = written.substring(1);
+            const resolution = resolveEventContextPath(path);
+            const column = (match.index ?? 0) + (match[1]?.length ?? 0) + 1;
+            switch (resolution.status) {
+                case 'missing':
+                    issues.push(issue('error', index, column, token.length, `'$eventContext.${path}' names no member - expected one of ${names(resolution.expected)}.`, diagnosticCodes.missingEventContextPath));
+                    break;
+                case 'unknownMember':
+                    issues.push(issue('warning', index, column, token.length, `Unknown event context member '${resolution.segment}' in '$eventContext.${path}' - expected one of ${names(resolution.expected)}.`, diagnosticCodes.unknownEventContextMember));
+                    break;
+                case 'unknownSubPath': {
+                    const has = resolution.expected.length === 0 ? 'no members to address' : `members ${names(resolution.expected)}`;
+                    issues.push(issue('warning', index, column, token.length, `Unknown event context path '$eventContext.${path}' - '${resolution.member?.name}' (${resolution.member?.type}) has ${has}.`, diagnosticCodes.unknownEventContextPath));
+                    break;
+                }
+                case 'belowCollection':
+                    issues.push(issue('error', index, column, token.length, `'$eventContext.${path}' cannot resolve - '${resolution.member?.name}' is a collection (${resolution.member?.type}) and cannot be addressed below.`, diagnosticCodes.eventContextPathBelowCollection));
+                    break;
+            }
+        }
+
+        // Only $eventContext resolves in a dynamic key; any other $ source is kept as the literal key text.
+        const target = line.trim().match(mappingTarget)?.[1];
+        const source = target?.match(/\.\$(\w+)/)?.[1];
+        if (target && source && source !== 'eventContext') {
+            issues.push(tokenIssue('warning', index, line, target, `Dynamic dictionary key '$${source}' in '${target}' is never resolved - only '$eventContext.<path>' is, so the literal text '$${source}' becomes the key.`, diagnosticCodes.unresolvedDynamicKeySource));
+        }
+    }
+
+    return issues;
+}