@cratis/screenplay-language 4.51.0 → 4.53.0

package/sub-languages/projection/HoverProvider.ts

@@ -1,377 +0,0 @@
-// Copyright (c) Cratis. All rights reserved.
-// Licensed under the MIT license. See LICENSE file in the project root for full license information.
-
-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[] = [];
-    private eventSchemas: Record<string, JsonSchema> = {};
-    private draftReadModel: DraftReadModelInfo | null = null;
-
-    setReadModels(readModels: ReadModelInfo[]): void {
-        this.readModels = readModels || [];
-    }
-
-    // Keep for backwards compatibility
-    setReadModelSchemas(schemas: JsonSchema[]): void {
-        this.readModels = schemas.map(schema => ({
-            identifier: this.getSchemaName(schema) || '',
-            displayName: this.getSchemaName(schema) || '',
-            schema
-        }));
-    }
-
-    setEventSchemas(schemas: Record<string, JsonSchema> | JsonSchema[]): void {
-        if (!schemas) {
-            this.eventSchemas = {};
-            return;
-        }
-
-        if (Array.isArray(schemas)) {
-            const map: Record<string, JsonSchema> = {};
-            schemas.forEach((s, i) => {
-                if (!s) return;
-                const name = this.getSchemaName(s) || `Event${i + 1}`;
-                map[name] = s;
-            });
-            this.eventSchemas = map;
-            return;
-        }
-
-        this.eventSchemas = schemas;
-    }
-
-    setDraftReadModel(draft: DraftReadModelInfo | null): void {
-        this.draftReadModel = draft;
-    }
-
-    provideHover(model: editor.ITextModel, position: Position): languages.ProviderResult<languages.Hover> {
-        const word = model.getWordAtPosition(position);
-        if (!word) return null;
-
-        const wordText = word.word;
-
-        // Check if we're on the projection name (before '=>')
-        const lineContent = model.getLineContent(position.lineNumber);
-        const projectionNameMatch = this.getProjectionNameAtPosition(lineContent, position.column);
-        if (projectionNameMatch) {
-            return {
-                contents: [{ value: 'The name of the projection' }],
-                range: {
-                    startLineNumber: position.lineNumber,
-                    startColumn: word.startColumn,
-                    endLineNumber: position.lineNumber,
-                    endColumn: word.endColumn,
-                },
-            };
-        }
-
-        // 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) {
-            return {
-                contents: [{ value: keywordInfo }],
-                range: {
-                    startLineNumber: position.lineNumber,
-                    startColumn: word.startColumn,
-                    endLineNumber: position.lineNumber,
-                    endColumn: word.endColumn,
-                },
-            };
-        }
-
-        // Check if it's a built-in expression
-        const expressionInfo = this.getExpressionInfo(wordText);
-        if (expressionInfo) {
-            return {
-                contents: [{ value: expressionInfo }],
-                range: {
-                    startLineNumber: position.lineNumber,
-                    startColumn: word.startColumn,
-                    endLineNumber: position.lineNumber,
-                    endColumn: word.endColumn,
-                },
-            };
-        }
-
-        // Check if it's an event type
-        if (this.eventSchemas[wordText]) {
-            const schema = this.eventSchemas[wordText];
-            const description = this.getSchemaDescription(schema);
-            const properties = this.getSchemaProperties(schema);
-
-            let content = `**Event Type:** \`${wordText}\`\n\n`;
-            if (description) {
-                content += `${description}\n\n`;
-            }
-            if (properties.length > 0) {
-                content += `**Properties:**\n\n${properties.map(p => `- \`${p.name}\`: ${p.type}`).join('\n')}`;
-            }
-
-            return {
-                contents: [{ value: content }],
-                range: {
-                    startLineNumber: position.lineNumber,
-                    startColumn: word.startColumn,
-                    endLineNumber: position.lineNumber,
-                    endColumn: word.endColumn,
-                },
-            };
-        }
-
-        // Check if it's a draft read model
-        if (this.isDraftReadModel(wordText)) {
-            const description = this.getSchemaDescription(this.draftReadModel!.schema);
-            const properties = this.getSchemaProperties(this.draftReadModel!.schema);
-            const identifier = this.draftReadModel!.identifier;
-            const displayName = this.draftReadModel!.displayName;
-
-            let content = `**Read Model (Draft):** \`${displayName}\`\n\n**Identifier:** \`${identifier}\`\n\n`;
-            if (description) {
-                content += `${description}\n\n`;
-            }
-            if (properties.length > 0) {
-                content += `**Properties:**\n\n${properties.map(p => `- \`${p.name}\`: ${p.type}`).join('\n')}`;
-            }
-
-            return {
-                contents: [{ value: content }],
-                range: {
-                    startLineNumber: position.lineNumber,
-                    startColumn: word.startColumn,
-                    endLineNumber: position.lineNumber,
-                    endColumn: word.endColumn,
-                },
-            };
-        }
-
-        // Check if it's a read model
-        const readModel = this.resolveReadModelInfo(wordText);
-        if (readModel) {
-            const description = this.getSchemaDescription(readModel.schema);
-            const properties = this.getSchemaProperties(readModel.schema);
-
-            let content = `**Read Model:** \`${readModel.displayName}\`\n\n**Identifier:** \`${readModel.identifier}\`\n\n`;
-            if (description) {
-                content += `${description}\n\n`;
-            }
-            if (properties.length > 0) {
-                content += `**Properties:**\n\n${properties.map(p => `- \`${p.name}\`: ${p.type}`).join('\n')}`;
-            }
-
-            return {
-                contents: [{ value: content }],
-                range: {
-                    startLineNumber: position.lineNumber,
-                    startColumn: word.startColumn,
-                    endLineNumber: position.lineNumber,
-                    endColumn: word.endColumn,
-                },
-            };
-        }
-
-        // Check if it's a property in the current context
-        const propertyInfo = this.getPropertyInfo(model, position, wordText);
-        if (propertyInfo) {
-            return {
-                contents: [{ value: propertyInfo }],
-                range: {
-                    startLineNumber: position.lineNumber,
-                    startColumn: word.startColumn,
-                    endLineNumber: position.lineNumber,
-                    endColumn: word.endColumn,
-                },
-            };
-        }
-
-        return null;
-    }
-
-    private getKeywordInfo(word: string): string | null {
-        const keywords: Record<string, string> = {
-            'projection': '**projection** - Defines a projection that transforms events into a read model',
-            'from': '**from** *<EventType>*\n\nHandles specific event types and maps their properties to the read model.',
-            'all': '**all**\n\nSubscribes to **all event types in the system**, regardless of explicit `from` blocks. Mappings inside `all` run for every event that arrives system-wide.',
-            'every': '**every**\n\nHandles all events the projection **explicitly subscribes to** through `from` blocks, with automatic property mapping.',
-            'key': '**key** *<expression>*\n\nDefines the projection key or composite key type.',
-            'parent': '**parent** *<expression>*\n\nDefines a parent relationship for hierarchical projections.',
-            'join': '**join** *<collection>* **on** *<property>*\n\nJoins with a child collection based on a property.',
-            'children': '**children** *<collection>* **id** *<expression>*\n\nDefines operations on child collections.',
-            'remove': '**remove with** *<EventType>* or **remove via join on** *<EventType>*\n\nRemoves items from the read model based on events.',
-            'clear': '**clear** *<property>*\n\nRemoves the value a property holds. **clear with** *<EventType>* nulls a whole nested object instead.',
-            'automap': '**automap** or **no automap**\n\nControls automatic property mapping from events to the read model.',
-            'increment': '**increment** *<property>*\n\nIncrements a numeric property by 1.',
-            'decrement': '**decrement** *<property>*\n\nDecrements a numeric property by 1.',
-            'count': '**count** *<property>*\n\nCounts occurrences and stores in a property.',
-            'add': '**add** *<property>* **by** *<expression>*\n\nAdds a value to a property.',
-            'subtract': '**subtract** *<property>* **by** *<expression>*\n\nSubtracts a value from a property.',
-            'exclude': '**exclude children**\n\nExcludes child collections from automatic mapping.',
-            'events': '**events** *<EventType>*, ...\n\nSpecifies which event types to include in a join.',
-            'via': 'Used with **remove via join on** to remove items via a join relationship.',
-            'with': 'Used with **remove with** to specify which event type triggers removal.',
-            'on': 'Used with **join** to specify the join property.',
-            'by': 'Used with **add** or **subtract** to specify the value.',
-            'id': 'Used with **children** to specify the child identifier expression.',
-            'no': 'Used with **no automap** to disable automatic property mapping.',
-            'variant': '**variant** *<Name>*\n\nDeclares one of several mutually exclusive named read models sharing the projection\'s identity. Entering one variant removes the entity from every other variant of the same projection.',
-            'enters': '**enters on** *<EventType>*\n\nDeclares the event that activates this variant - the only event allowed to create it. Every other event the variant subscribes to is update-only.',
-        };
-
-        return keywords[word] || null;
-    }
-
-    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\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();
-        const match = firstLine.match(/^projection\s+[\w.]+\s*=>\s*([\w.]+)/);
-        if (!match) return null;
-
-        const readModelName = match[1];
-        const draftMatch = this.isDraftReadModel(readModelName) ? this.draftReadModel : null;
-        const resolvedReadModel = draftMatch ? null : this.resolveReadModelInfo(readModelName);
-        const activeSchema = draftMatch?.schema || resolvedReadModel?.schema;
-
-        if (activeSchema?.properties && activeSchema.properties[propertyName]) {
-            const prop = activeSchema.properties[propertyName];
-            const type = this.getPropertyTypeDescription(prop);
-            const description = prop.description;
-
-            let content = `**Property:** \`${propertyName}\`\n\n**Type:** \`${type}\``;
-            if (description) {
-                content += `\n\n${description}`;
-            }
-            return content;
-        }
-
-        // Check if it's an event property
-        const eventType = this.getCurrentEventType(model, position.lineNumber);
-        if (eventType && this.eventSchemas[eventType]) {
-            const eventSchema = this.eventSchemas[eventType];
-            if (eventSchema.properties && eventSchema.properties[propertyName]) {
-                const prop = eventSchema.properties[propertyName];
-                const type = this.getPropertyTypeDescription(prop);
-                const description = prop.description;
-
-                let content = `**Event Property:** \`${propertyName}\`\n\n**Type:** \`${type}\``;
-                if (description) {
-                    content += `\n\n${description}`;
-                }
-                return content;
-            }
-        }
-
-        return null;
-    }
-
-    private resolveReadModelInfo(readModelToken: string): ReadModelInfo | null {
-        return this.readModels.find(rm => rm.identifier === readModelToken || rm.displayName === readModelToken) || null;
-    }
-
-    private isDraftReadModel(readModelToken: string): boolean {
-        return !!this.draftReadModel && (this.draftReadModel.identifier === readModelToken || this.draftReadModel.displayName === readModelToken);
-    }
-
-    private getCurrentEventType(model: editor.ITextModel, lineNumber: number): string | null {
-        for (let i = lineNumber; i >= 1; i--) {
-            const line = model.getLineContent(i).trim();
-            const fromMatch = line.match(/^from\s+([\w-]+)/);
-            if (fromMatch) {
-                return fromMatch[1];
-            }
-        }
-        return null;
-    }
-
-    private getProjectionNameAtPosition(lineContent: string, column: number): boolean {
-        // Check if we're on line 1 (projection declaration line)
-        const projectionMatch = lineContent.match(/^\s*projection\s+(\S+)\s*=>/);
-        if (!projectionMatch) return false;
-
-        const projectionKeywordEnd = lineContent.indexOf('projection') + 'projection'.length;
-        const arrowStart = lineContent.indexOf('=>');
-
-        // Check if cursor is between 'projection' keyword and '=>'
-        // and is on the projection name itself
-        return column > projectionKeywordEnd && column <= arrowStart;
-    }
-
-    private getSchemaName(schema: JsonSchema): string | undefined {
-        if (schema.name) return schema.name;
-        if (schema.title) return schema.title;
-        if (typeof schema.$id === 'string') {
-            const parts = schema.$id.split('/');
-            return parts[parts.length - 1] || schema.$id;
-        }
-        return undefined;
-    }
-
-    private getSchemaDescription(schema: JsonSchema): string | undefined {
-        return schema.description || undefined;
-    }
-
-    private getSchemaProperties(schema: JsonSchema): Array<{ name: string; type: string }> {
-        if (!schema.properties) return [];
-
-        return Object.entries(schema.properties).map(([name, prop]) => ({
-            name,
-            type: this.getPropertyTypeDescription(prop),
-        }));
-    }
-
-    private getPropertyTypeDescription(propSchema: JsonSchemaProperty): string {
-        if (propSchema.type === 'array' && propSchema.items) {
-            const itemType = propSchema.items.type || propSchema.items.$ref?.split('/').pop() || 'unknown';
-            return `${itemType}[]`;
-        }
-        return propSchema.type || propSchema.$ref?.split('/').pop() || 'unknown';
-    }
-}