@cratis/screenplay-language 4.49.0 → 4.51.0

package/for_inlineEvents/when_authoring_inline_events.ts

@@ -0,0 +1,149 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, it, expect } from 'vitest';
+import { planCompletions } from '../completion-planner';
+import { hoverContent } from '../hover-content';
+import { destinationHints } from '../production-destinations';
+import { scanDocument } from '../symbols';
+import { validateLines } from '../validation';
+
+const source = [
+    'command Rename', '  projectId Uuid identifier', '  name String', '  produces event Renamed',
+    '    description "A new name"', '    documentation', '      ```markdown', '      event NotADeclaration', '      ```',
+    '    @tag String = name', '    name String = name',
+];
+
+describe('when authoring inline events', () => {
+    it('should index the event and its typed properties, not its prose', () => {
+        const symbols = scanDocument(source);
+        expect(symbols.events.map(event => event.name)).toEqual(['Renamed']);
+        expect(symbols.events[0].properties.map(property => property.name)).toEqual(['tag', 'name']);
+        expect(symbols.commands[0].properties.map(property => property.name)).toEqual(['projectId', 'name']);
+    });
+    it('should validate its metadata without false positives', () => expect(validateLines(source)).toEqual([]));
+    it.each([
+        ['    documentation "details"'],
+        ['    documentation'],
+        ['    documentation', '      ```text', '      Details', '      ```'],
+        ['    documentation', '    ```markdown', '    Details', '    ```'],
+        ['    documentation', '      ```markdown', '      ', '      ```'],
+        ['    documentation', '      ```markdown', '      Details'],
+    ])('should reject malformed documentation without searching later declarations for its fence', (...body) => {
+        const lines = ['command Rename', '  produces event Renamed', ...body];
+        expect(validateLines(lines).filter(issue => issue.code === 'PLAY0477').map(issue => issue.line)).toEqual([2]);
+    });
+    it('should distinguish adjacent complete documentation blocks from malformed directives', () => {
+        const lines = ['event First', '  documentation "details"', 'event Second', '  documentation',
+            '    ```markdown', '    Details', '    ```', 'event Third', '  documentation',
+            '    ```markdown', '    ', '    ```', 'event Fourth', '  documentation', '',
+            '    ```markdown', '    More details', '    ```'];
+        expect(validateLines(lines).filter(issue => issue.code === 'PLAY0477').map(issue => issue.line)).toEqual([1, 8]);
+    });
+    it('should offer event metadata and typed mappings inside the body', () => {
+        const plan = planCompletions([...source, '    '], source.length, '    ');
+        expect(plan.kind).toBe('entries');
+        if (plan.kind === 'entries') expect(plan.entries.map(entry => entry.label)).toEqual(expect.arrayContaining(['description', 'documentation', 'id', 'tag', 'for', 'property mapping']));
+    });
+    it('should show the implicit command identifier', () => expect(destinationHints(source).map(hint => hint.label)).toEqual(['for projectId']));
+    it('should suppress hints for uncertain mixed destinations', () => expect(destinationHints([...source, '  produces Another', '    for otherId'])).toEqual([]));
+    it('should suppress hints for incomplete and repeated explicit destinations', () => {
+        expect(destinationHints([...source, '    for'])).toEqual([]);
+        expect(destinationHints([...source, '    for projectId', '    for projectId'])).toEqual([]);
+    });
+    it('should not hint a header that has no event name', () => expect(destinationHints(['command Rename', '  produces'])).toEqual([]));
+    it('should explain the new declaration form', () => expect(hoverContent(source, 3, 'produces', 3, 11)).toContain('produces event'));
+    it('should preserve information severity for redundant pins', () => expect(validateLines([...source, '    id "Renamed"']).find(issue => issue.code === 'PLAY0471')?.severity).toBe('information'));
+    it.each(['namespace', 'sequence', 'correlation', 'causation', 'causedBy', 'occurred'])('should reject %s as system metadata', keyword => {
+        expect(validateLines([...source, `    ${keyword} = name`]).map(issue => issue.code)).toContain('PLAY0476');
+    });
+    it('should warn about identifier duplication', () => expect(validateLines([...source, '    projectId Uuid = projectId']).find(issue => issue.code === 'PLAY0469')?.severity).toBe('warning'));
+    it('should reject an inline event in a reaction', () => expect(validateLines(['reaction React', '  every 1 day', '    produces event Done']).map(issue => issue.code)).toContain('PLAY0474'));
+    it('should require explicit destinations for mixed inline and plain omissions', () => {
+        const lines = [...source, '  produces Legacy // retained allocation'];
+        expect(validateLines(lines).filter(issue => issue.code === 'PLAY0470').map(issue => issue.message)).toContain("Production 'Legacy' must state for explicitly when destinations differ.");
+        expect(destinationHints(lines)).toEqual([]);
+    });
+    it('should suppress legacy allocation hints when a sibling can promote a destination', () => {
+        expect(destinationHints(['command Rename', '  projectId Uuid identifier', '  produces First', '    for projectId', '  produces Legacy'])).toEqual([]);
+    });
+    it.each([
+        ['  produces First', '    name = name', '      for projectId', '  produces Legacy'],
+        ['  produces First', '      name = name', '    for projectId', '  produces Legacy'],
+        ['    produces First', '      name = name', '        for projectId', '  produces Legacy'],
+        ['  produces when name != ""', '    First', '      name = name', '        for projectId', '  produces Legacy'],
+    ])('should not hint allocation when a differently indented destination is promoted', (...productions) => {
+        const lines = ['command Rename', '  projectId Uuid identifier', '  name String', ...productions];
+        expect(scanDocument(lines).commands[0].produces?.[0].target).toBe('projectId');
+        expect(destinationHints(lines)).toEqual([]);
+    });
+    it('should see deeper destinations after fenced event documentation', () => {
+        const lines = ['command Rename', '  projectId Uuid identifier', '  produces event Renamed',
+            '    documentation', '      ```markdown', '      Details', '      ```', '      for otherId', '  produces Legacy'];
+        expect(scanDocument(lines).commands[0].produces?.[0].target).toBe('otherId');
+        expect(destinationHints(lines)).toEqual([]);
+    });
+    it('should suppress hints when a sibling production cannot be classified', () => {
+        expect(destinationHints(['command Rename', '  projectId Uuid identifier', '  produces First', '  produces event'])).toEqual([]);
+        expect(destinationHints(['command Rename', '  projectId Uuid identifier', '  produces event'])).toEqual([]);
+        expect(destinationHints(['command Rename', '  produces First', '  produces when'])).toEqual([]);
+    });
+    it('should place a destination hint before a trailing comment', () => {
+        const lines = ['command Rename', '  projectId Uuid identifier', '  produces event Renamed // note'];
+        expect(destinationHints(lines)).toEqual([{ line: 2, column: '  produces event Renamed'.length + 1, label: 'for projectId' }]);
+    });
+    it('should report duplicate typed properties at the repeated mapping', () => {
+        const lines = [...source, '      name Uuid = otherId // duplicate'];
+        expect(validateLines(lines).filter(issue => issue.code === 'PLAY0168').map(issue => ({ line: issue.line, severity: issue.severity })))
+            .toEqual([{ line: source.length, severity: 'error' }]);
+    });
+    it('should treat escaped and unescaped inline property names as the same name', () => {
+        expect(validateLines([...source, '    @name String = name']).filter(issue => issue.code === 'PLAY0168').map(issue => issue.line)).toEqual([source.length]);
+    });
+    it('should detect collisions with commented imports in the document', () => {
+        expect(validateLines(['import Other.Renamed // note', ...source]).filter(issue => issue.code === 'PLAY0473').map(issue => issue.line)).toEqual([4]);
+    });
+    it('should detect collisions with commented imports from other files', () => {
+        const application = scanDocument(['import Other.Renamed // note']);
+        expect(validateLines(source, { application }).filter(issue => issue.code === 'PLAY0473').map(issue => issue.line)).toEqual([3]);
+    });
+    it('should not scan imports inside event documentation', () => {
+        const lines = source.map(line => line === '      event NotADeclaration' ? '      import Other.Renamed // prose' : line);
+        expect(scanDocument(lines).imports).toEqual([]);
+        expect(validateLines(lines)).toEqual([]);
+    });
+    it('should hint allocation when all plain productions omit destinations', () => {
+        expect(destinationHints(['command Rename', '  produces First', '  produces Legacy']).map(hint => hint.label)).toEqual(['for <new event source>', 'for <new event source>']);
+    });
+    it('should analyze commented headers, destinations, mappings and metadata like the compiler', () => {
+        const lines = source.map(line => line === '    documentation' ? `${line} // details` : line);
+        lines.push('    projectId Uuid = projectId // note', '  produces Other // sibling', '    for projectId // same identifier');
+        expect(validateLines(lines).filter(issue => ['PLAY0470', 'PLAY0477'].includes(issue.code ?? ''))).toEqual([]);
+        expect(validateLines(lines).find(issue => issue.code === 'PLAY0469')?.severity).toBe('warning');
+        expect(destinationHints(lines).map(hint => hint.label)).toEqual(['for projectId']);
+    });
+    it('should suppress hints when a commented sibling targets another source', () => {
+        const lines = [...source, '  produces Other // sibling', '    for otherId // other source'];
+        expect(validateLines(lines).some(issue => issue.code === 'PLAY0470')).toBe(true);
+        expect(destinationHints(lines)).toEqual([]);
+    });
+    it('should preserve comment markers inside strings and templates and ignore fences', () => {
+        const lines = [...source, '    url String = "https://example.org" // url', '    template String = `https://{name}` // template'];
+        expect(scanDocument(lines).commands[0].produces?.[0].mappings.map(mapping => mapping.source)).toContain('"https://example.org"');
+        expect(scanDocument(lines).commands[0].produces?.[0].mappings.map(mapping => mapping.source)).toContain('`https://{name}`');
+        expect(destinationHints(lines).map(hint => hint.label)).toEqual(['for projectId']);
+        const fenced = ['command Rename', '  documentation', '    ```markdown', '  produces event Fake', '    for otherId', '    ```'];
+        expect(destinationHints(fenced)).toEqual([]);
+        expect(validateLines(fenced).filter(issue => issue.code?.startsWith('PLAY047'))).toEqual([]);
+    });
+    it('should show metadata hover only on event directives', () => {
+        expect(hoverContent(['event Done', '  id "Old"'], 1, 'id', 3, 5)).toContain('rename');
+        expect(hoverContent(['event Done', '  documentation'], 1, 'documentation', 3, 16)).not.toBeNull();
+        for (const line of ['  id String', '  key id', '  name String = id', '  id String = name']) {
+            const start = line.indexOf('id') + 1;
+            expect(hoverContent(['event Done', line], 1, 'id', start, start + 2)).toBeNull();
+        }
+        expect(hoverContent(['command Done', '  documentation'], 1, 'documentation', 3, 16)).toBeNull();
+    });
+    it('should retain standalone property-shaped id and documentation names', () => expect(scanDocument(['event Done', '  id String', '  documentation String']).events[0].properties.map(property => property.name)).toEqual(['id', 'documentation']));
+});

package/for_inlineEvents/when_completing_many_events.ts

@@ -0,0 +1,49 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, expect, it, vi } from 'vitest';
+import type { editor, languages, Position } from 'monaco-editor';
+import { createCompletionProvider } from '../completions';
+import { Monaco } from '../language';
+
+const monaco = {
+    Range: class {},
+    languages: { CompletionItemKind: { Event: 1 }, CompletionItemInsertTextRule: { InsertAsSnippet: 1 } },
+} as unknown as Monaco;
+
+function complete(count: number, inline: boolean): { work: number; suggestions: languages.CompletionItem[] } {
+    const lines = [...Array.from({ length: count }, (_, index) => inline ? `command Record${index}\n  produces event Recorded${index}` : `event Recorded${index}`).join('\n').split('\n'),
+        'constraint Unique', '  on '];
+    const model = {
+        getLinesContent: () => lines,
+        getWordUntilPosition: () => ({ word: '', startColumn: 6, endColumn: 6 }),
+    } as unknown as editor.ITextModel;
+    const searches = vi.spyOn(Array.prototype, 'some');
+    const filters = vi.spyOn(Array.prototype, 'filter');
+    const membership = vi.spyOn(Set.prototype, 'has');
+    try {
+        const result = createCompletionProvider(monaco).provideCompletionItems(model, { lineNumber: lines.length, column: 6 } as Position, {} as languages.CompletionContext, {} as never) as languages.CompletionList;
+        return {
+            suggestions: result.suggestions,
+            work: [...searches.mock.contexts, ...filters.mock.contexts].reduce<number>((sum, receiver) => sum + (receiver as unknown[]).length, 0) + membership.mock.calls.length,
+        };
+    } finally {
+        searches.mockRestore();
+        filters.mockRestore();
+        membership.mockRestore();
+    }
+}
+
+describe('when completing many event names in Monaco', () => {
+    it.each([false, true])('should keep completion work linear for inline declarations: %s', inline => {
+        const small = complete(500, inline);
+        const medium = complete(1000, inline);
+        const large = complete(2000, inline);
+        expect(small.work).toBeGreaterThan(0);
+        expect(medium.work).toBeLessThan(small.work * 2.2);
+        expect(large.work).toBeLessThan(medium.work * 2.2);
+        expect(large.suggestions).toHaveLength(2000);
+        expect(large.suggestions.map(item => item.label)).toEqual(Array.from({ length: 2000 }, (_, index) => `Recorded${index}`));
+        expect(large.suggestions.every(item => item.detail === (inline ? 'inline event' : 'event'))).toBe(true);
+    });
+});

package/for_inlineEvents/when_indexing_command_production_ownership.ts

@@ -0,0 +1,79 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, expect, it } from 'vitest';
+import { destinationHints } from '../production-destinations';
+import { scanDocument } from '../symbols';
+import { validateLines } from '../validation';
+
+describe('when indexing command production ownership', () => {
+    it('should keep the documented multiline authorization out of command properties', () => {
+        const lines = ['policy IsAccountant', '  require role "Accountant"', 'policy IsCustomerSelf', '  require authenticated',
+            'command Rename', '  projectId Uuid identifier',
+            '  authorize IsAccountant', '            or IsCustomerSelf', '  produces event Renamed'];
+        const command = scanDocument(lines).commands[0];
+        expect(command.properties.map(property => property.name)).toEqual(['projectId']);
+        expect(command.produces?.map(production => production.name)).toEqual(['Renamed']);
+        expect(validateLines(lines)).toEqual([]);
+        expect(destinationHints(lines).map(hint => hint.label)).toEqual(['for projectId']);
+    });
+
+    it.each(['or IsCustomerSelf', 'and IsCustomerSelf', 'IsCustomerSelf', '(IsCustomerSelf)', 'or IsCüstomerSelf', 'produces Ghost'])('should consume %s as an authorization continuation', continuation => {
+        const lines = ['command Rename', '  authorize IsAccountant', `    ${continuation}`, '  produces Legacy'];
+        const command = scanDocument(lines).commands[0];
+        expect(command.properties).toEqual([]);
+        expect(command.productionHeaders).toEqual([3]);
+        expect(destinationHints(lines).map(hint => hint.line)).toEqual([3]);
+    });
+
+    it('should end authorization ownership at the first nonmatching line, not merely a dedent', () => {
+        const lines = ['command Rename', '  projectId Uuid identifier', '  authorize IsAccountant',
+            '    or IsCustomerSelf // continuation', '    names String[]', '    produces event Renamed'];
+        const command = scanDocument(lines).commands[0];
+        expect(command.properties.map(property => property.name)).toEqual(['projectId', 'names']);
+        expect(command.productionHeaders).toEqual([5]);
+        expect(destinationHints(lines).map(hint => hint.label)).toEqual(['for projectId']);
+    });
+
+    it.each([
+        [['  description "Rename the project"']],
+        [['  description', '    ```text', '    produces Ghost', '    ```']],
+    ])('should leave deeper syntax after a description in its command', description => {
+        const lines = ['command Rename', '  projectId Uuid identifier', ...description, '    produces event Renamed'];
+        const command = scanDocument(lines).commands[0];
+        expect(command.properties.map(property => property.name)).toEqual(['projectId']);
+        expect(command.produces?.map(production => production.name)).toEqual(['Renamed']);
+        expect(destinationHints(lines).map(hint => hint.label)).toEqual(['for projectId']);
+    });
+
+    it.each(['validate', 'handler', 'concurrency', 'name'])('should keep a deeper production after the %s property in its command', name => {
+        const lines = ['command Rename', '  projectId Uuid identifier', `  ${name} String`,
+            '    produces event Renamed', '      value String = "renamed"'];
+        expect(scanDocument(lines).commands[0].produces?.map(production => production.name)).toEqual(['Renamed']);
+        expect(validateLines(lines)).toEqual([]);
+        expect(destinationHints(lines).map(hint => hint.label)).toEqual(['for projectId']);
+    });
+
+    it.each(['validate', 'handler', 'concurrency'])('should not hint allocation after a deeper destination beneath the %s property', name => {
+        const lines = ['command Rename', '  projectId Uuid identifier', `  ${name} String // a property, not a block`,
+            '    produces First', '      for projectId', '  produces Legacy'];
+        expect(scanDocument(lines).commands[0].produces?.map(production => [production.name, production.target]))
+            .toEqual([['First', 'projectId'], ['Legacy', undefined]]);
+        expect(destinationHints(lines)).toEqual([]);
+        expect(validateLines(lines).filter(issue => issue.code === 'PLAY0478').map(issue => issue.line)).toEqual([5]);
+    });
+
+    it.each(['validate', 'handler', 'concurrency'])('should suppress hints for an unclassifiable production beneath the %s property', name => {
+        expect(destinationHints(['command Rename', '  projectId Uuid identifier', `  ${name} String`,
+            '    produces event', '  produces Legacy'])).toEqual([]);
+    });
+
+    it.each(['validate', 'validate csharp', 'handler', 'concurrency'])('should keep the %s block opaque to command ownership', directive => {
+        const lines = ['command Rename', `  ${directive}`, '    ghost Uuid identifier', '    produces First', '      for ghost', '  produces Legacy'];
+        const command = scanDocument(lines).commands[0];
+        expect(command.properties).toEqual([]);
+        expect(command.produces?.map(production => production.name)).toEqual(['Legacy']);
+        expect(destinationHints(lines).map(hint => hint.line)).toEqual([5]);
+        expect(validateLines(lines).filter(issue => issue.code === 'PLAY0478')).toEqual([]);
+    });
+});

package/for_scanDocument/when_scanning_many_commands.ts

@@ -0,0 +1,47 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, it, vi } from 'vitest';
+import * as context from '../document-context';
+import { scanDocument } from '../symbols';
+import { validateLines } from '../validation';
+
+function commands(count: number): string[] {
+    return ['module Projects', '  feature Registration', ...Array.from({ length: count }, (_, index) => [
+        `    slice StateChange Register${index}`,
+        `      command Register${index} // command`,
+        '        description Uuid identifier // keyword-named property',
+        '        details String',
+        '        produces Registered',
+        '          nested Uuid identifier',
+        '  // a comment is not an ancestor',
+        '        handler',
+        '          ```csharp',
+        '          ghost Uuid identifier',
+        '          ```',
+        '        name String',
+    ]).flat()];
+}
+
+describe('when scanning many commands', () => {
+    it('should visit structural indentation a linear number of times', () => {
+        const visits = vi.spyOn(context, 'indentOf');
+        try {
+            const small = commands(150);
+            validateLines(small);
+            const smallCount = visits.mock.calls.length;
+            visits.mockClear();
+            const large = commands(300);
+            validateLines(large);
+            const largeCount = visits.mock.calls.length;
+            const symbols = scanDocument(large);
+            smallCount.should.be.greaterThan(0);
+            largeCount.should.be.lessThan(large.length * 10);
+            largeCount.should.be.lessThan(smallCount * 2.1);
+            symbols.commands.length.should.equal(300);
+            symbols.commands.every(command => command.properties.map(property => property.name).join(',') === 'description,details,name').should.equal(true);
+        } finally {
+            visits.mockRestore();
+        }
+    });
+});

package/for_tokens/when_highlighting_event_metadata.ts

@@ -0,0 +1,63 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, expect, it } from 'vitest';
+import type { Token } from 'monaco-editor';
+import { clauseKeywords } from '../language';
+import { createTokensProvider } from '../tokens';
+
+const provider = createTokensProvider([]);
+const rules = provider.tokenizer.eventBody as unknown as [RegExp, unknown][];
+
+describe('when highlighting event metadata', () => {
+    it.each(['id', 'documentation'])('should leave %s available as an ordinary name', word => {
+        expect(clauseKeywords).not.toContain(word);
+    });
+    it('should recognize only directive-shaped metadata inside the event state', () => {
+        expect(rules[1][0].test('    id "Old"')).toBe(true);
+        expect(rules[1][0].test('    id String')).toBe(false);
+        expect(rules[1][0].test('    name String = id')).toBe(false);
+        expect(rules[2][0].test('    documentation // details')).toBe(true);
+        expect(rules[2][0].test('    documentation String')).toBe(false);
+    });
+    it('should tokenize event directives without claiming property names or later blocks', async () => {
+        const compilerPath = 'monaco-editor/esm/vs/editor/standalone/common/monarch/monarchCompile.js';
+        const lexerPath = 'monaco-editor/esm/vs/editor/standalone/common/monarch/monarchLexer.js';
+        const { compile } = await import(compilerPath);
+        const { MonarchTokenizer } = await import(lexerPath);
+        const tokenizer = new MonarchTokenizer({}, {}, 'screenplay', compile('screenplay', provider), {
+            getValue: () => 20000,
+            onDidChangeConfiguration: () => ({ dispose() {} }),
+        });
+        let state = tokenizer.getInitialState();
+        const tokenize = (line: string): Token[] => {
+            const result = tokenizer.tokenize(line, true, state);
+            state = result.endState;
+            return result.tokens;
+        };
+        try {
+            for (const header of ['  event Done', '  produces event Done']) {
+                tokenize(header);
+                expect(tokenize('    id "Old"').find(token => token.offset === 4)?.type).toBe('keyword.play');
+                expect(tokenize('    id String').find(token => token.offset === 4)?.type).toBe('identifier.play');
+                expect(tokenize('    documentation String').find(token => token.offset === 4)?.type).toBe('identifier.play');
+                const documentation = tokenize('    documentation // details');
+                expect(documentation.find(token => token.offset === 4)?.type).toBe('keyword.play');
+                expect(documentation.find(token => token.offset === 18)?.type).toBe('comment.play');
+                expect(tokenize('      ```markdown').find(token => token.type === 'string.quote.play')).toBeDefined();
+                expect(tokenize('      event Prose')[0].type).toBe('string.play');
+                tokenize('      ```');
+                tokenize('  command Other');
+                expect(tokenize('    id "NotMetadata"').find(token => token.offset === 4)?.type).toBe('identifier.play');
+            }
+        } finally {
+            tokenizer.dispose();
+        }
+    });
+    it('should leave the event state when a line is not nested under its header', () => {
+        const exit = new RegExp(rules[0][0].source.replace('$S2', '  '));
+        expect(exit.test('  command Other')).toBe(true);
+        expect(exit.test('    id "Old"')).toBe(false);
+        expect(exit.test('')).toBe(false);
+    });
+});

package/for_validateLines/when_validating_a_document/with_a_problem_of_every_coded_kind.ts

@@ -28,6 +28,9 @@ const document = [
     '          registeredBy = $context.wat',
     '          causedBy = $context.causedBy.wat',
     '          department = $context.identity.wat',
+    '      command ArchiveInvoice',
+    '        invoiceId InvoiceId identifier',
+    '        produces InvoiceArchived',
     '      projection Statistics => StatisticsReadModel',
     '        from InvoiceRegistered',
     '          cause = $eventContext.causationId',
@@ -35,6 +38,20 @@ const document = [
     '          firstCause = $eventContext.causation.occurred',
     '          nothing = $eventContext.',
     '          count byUser.$causedBy.subject',
+    '      command Rename',
+    '        invoiceId InvoiceId identifier',
+    '        otherId InvoiceId',
+    '        produces event Renamed generation 2',
+    '          invoiceId InvoiceId = invoiceId',
+    '          id "Renamed"',
+    '          id "Older"',
+    '          documentation "not fenced"',
+    '        produces Other',
+    '          for otherId',
+    '      event Renamed',
+    '      reaction React',
+    '        every 1 day',
+    '          produces event Unsupported',
     '      query Overdue => OverdueReadModel[]',
     '        performer',
     '          csharp',

package/for_validateLines/when_validating_production_destinations/with_an_available_identifier.ts

@@ -0,0 +1,120 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, describe, it } from 'vitest';
+import { diagnosticCodes } from '../../diagnostic-codes';
+import { ValidationIssue, validateLines } from '../../validation';
+
+const source = [
+    'module Projects',
+    '  feature Registration',
+    '    slice StateChange Register',
+    '      command Register',
+    '        projectId Uuid identifier',
+    '        produces ProjectRegistered // omitted destination',
+    '          name = name',
+    '        produces ProjectUpdated',
+    '          for projectId // explicit destination',
+    '        produces when true == true',
+    '          ProjectConditional',
+    '      event ProjectRegistered',
+    '      event ProjectUpdated',
+    '      event ProjectConditional',
+];
+
+const destinations = (lines: string[]) => validateLines(lines).filter(issue => issue.code === diagnosticCodes.omittedProductionDestination);
+
+describe('when validating production destinations with an available identifier', () => {
+    let issues: ValidationIssue[];
+
+    beforeEach(() => {
+        issues = destinations(source);
+    });
+
+    it('should advise only on the plain omitted destination', () => {
+        issues.map(issue => issue.line).should.deep.equal([5]);
+    });
+
+    it('should keep the advice informational', () => {
+        issues[0].severity.should.equal('information');
+        issues[0].message.should.contain('for projectId');
+    });
+
+    it('should not advise without an identifier', () => {
+        destinations(source.map(line => line.replace(' identifier', ''))).should.have.lengthOf(0);
+    });
+
+    it.each(['Uuid?', 'Uuid[]', 'Uuid[]?'])('should not advise for a %s identifier', (type) => {
+        destinations(source.map(line => line.replace('projectId Uuid identifier', `projectId ${type} identifier`))).should.have.lengthOf(0);
+    });
+
+    it.each([
+        ['command Register // explanation', 'projectId Uuid identifier'],
+        ['command Register', 'projectId Uuid identifier // explanation'],
+        ['command Register // explanation', 'projectId Uuid identifier // explanation'],
+    ])('should discover identifiers despite trailing comments: %s; %s', (command, property) => {
+        destinations(source.map(line => line.replace('command Register', command).replace('projectId Uuid identifier', property)))
+            .map(issue => issue.line).should.deep.equal([5]);
+    });
+
+    it.each(['// outside', '      // beside the command', '        // beside the production'])(
+        'should skip comment-only ancestry lines: %s', (comment) => {
+            destinations([...source.slice(0, 5), comment, ...source.slice(5)])
+                .map(issue => issue.line).should.deep.equal([6]);
+        });
+
+    it.each(['description', 'handler', 'concurrency', 'validate', 'template', 'profile', 'when', 'identifier', 'sourceType', 'streamType'])(
+        'should follow command property rules for %s', (name) => {
+            const issues = destinations(source.map(line => line.replaceAll('projectId', name)));
+            issues.map(issue => issue.line).should.deep.equal([5]);
+            issues[0].message.should.contain(`for ${name}`);
+        });
+
+    it('should not treat a nested concurrency dimension as a command identifier', () => {
+        destinations([
+            ...source.slice(0, 4),
+            '        concurrency',
+            '          sourceType Uuid identifier',
+            '        produces ProjectRegistered',
+            '      event ProjectRegistered',
+        ]).should.have.lengthOf(0);
+    });
+
+    it('should not discover an identifier inside a fence', () => {
+        destinations([
+            ...source.slice(0, 4),
+            '        produces ProjectRegistered',
+            '        validate',
+            '          ```csharp',
+            '          ghostId Uuid identifier',
+            '          ```',
+            '      event ProjectRegistered',
+        ]).should.have.lengthOf(0);
+    });
+
+    it('should not count fenced identifiers beside a real identifier', () => {
+        destinations([
+            ...source.slice(0, 5),
+            '        produces ProjectRegistered',
+            '        validate',
+            '          ```csharp',
+            '          ghostId Uuid identifier',
+            '          ```',
+            '      event ProjectRegistered',
+        ]).map(issue => issue.line).should.deep.equal([5]);
+    });
+
+    it('should not advise on reaction productions', () => {
+        destinations(source.map(line => line.replace('command Register', 'reaction Register'))).should.have.lengthOf(0);
+    });
+
+    it('should ignore fenced code that looks like a production', () => {
+        destinations([
+            ...source.slice(0, 5),
+            '        handler',
+            '          ```csharp',
+            '        produces NotScreenplay',
+            '          ```',
+        ]).should.have.lengthOf(0);
+    });
+});

package/hover-content.ts

@@ -2,7 +2,8 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { enclosingChain, fenceMap, indentOf } from './document-context';
-import { scanDocument } from './symbols';
+import { directBody, scanDocument } from './symbols';
+import { eventAnalysisSource } from './event-analysis-source';
 import { getSubLanguage } from './sub-language-registry';
 import { attributeDocs, contextVariableDocs, keywordDocs, specificationKeywordDocs } from './keyword-docs';
 
@@ -102,6 +103,13 @@ export function hoverContent(
         return `**${word}** — ${specificationKeywordDocs[word]}`;
     }
 
+    if (word === 'id' || word === 'documentation') {
+        const source = eventAnalysisSource(lines);
+        const inEvent = symbols.events.some(event => directBody(source, fences, event.line, indentOf(source[event.line])).includes(lineIndex));
+        const directive = word === 'id' ? /^\s*id\s+"/.test(source[lineIndex]) : /^\s*documentation\s*$/.test(source[lineIndex]);
+        if (!inEvent || !directive || startColumn !== indentOf(line) + 1) return null;
+    }
+
     const keywordDoc = keywordDocs[word];
     if (keywordDoc) return `**${word}** — ${keywordDoc}`;
 

package/index.ts

@@ -10,6 +10,7 @@ import {
 import { createTokensProvider } from './tokens';
 import { CompletionOptions, createCompletionProvider } from './completions';
 import { createHoverProvider } from './hover';
+import { createInlayHintsProvider } from './inlay-hints';
 import { attachDiagnostics } from './diagnostics';
 import {
     getSubLanguage,
@@ -53,6 +54,7 @@ export function register(monaco: Monaco, options: LanguageServiceOptions = {}):
     applyTokensProvider(monaco);
     monaco.languages.registerCompletionItemProvider(languageId, createCompletionProvider(monaco, options));
     monaco.languages.registerHoverProvider(languageId, createHoverProvider());
+    monaco.languages.registerInlayHintsProvider(languageId, createInlayHintsProvider());
     monaco.editor.defineTheme(screenplayDarkThemeName, screenplayDark);
     monaco.editor.defineTheme(screenplayLightThemeName, screenplayLight);
     attachDiagnostics(monaco);
@@ -115,6 +117,9 @@ export { completionEntriesFor, planCompletions } from './completion-planner';
 export type { CompletionPlan } from './completion-planner';
 export { hoverContent } from './hover-content';
 export { validateLines } from './validation';
+export { destinationHints, productionDestinations } from './production-destinations';
+export type { DestinationHint } from './DestinationHint';
+export type { ProductionSymbol } from './ProductionSymbol';
 export type { ValidationContext, ValidationIssue, ValidationSeverity } from './validation';
 export { diagnosticCodes } from './diagnostic-codes';
 export type { DiagnosticCode } from './diagnostic-codes';

package/inlay-hints.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { languages } from 'monaco-editor';
+import { destinationHints } from './production-destinations';
+
+export function createInlayHintsProvider(): languages.InlayHintsProvider {
+    return {
+        provideInlayHints(model, range) {
+            const hints = destinationHints(model.getLinesContent()).filter(hint => hint.line + 1 >= range.startLineNumber && hint.line + 1 <= range.endLineNumber);
+            return {
+                hints: hints.map(hint => ({ position: { lineNumber: hint.line + 1, column: hint.column }, label: hint.label, paddingLeft: true })),
+                dispose() {},
+            };
+        },
+    };
+}