@cratis/screenplay-language 4.49.0 → 4.51.0

package/inline-event-validation.ts

@@ -0,0 +1,115 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DiagnosticCode, diagnosticCodes } from './diagnostic-codes';
+import { fenceMap, indentOf } from './document-context';
+import { productionDestinations } from './production-destinations';
+import { eventAnalysisSource } from './event-analysis-source';
+import { directBody, DocumentSymbols } from './symbols';
+import type { ValidationIssue, ValidationSeverity } from './validation';
+
+const reserved = new Set(['namespace', 'sequence', 'correlation', 'causation', 'causedBy', 'occurred']);
+const quotedId = /^id\s+"((?:[^"\\]|\\.)*)"$/;
+
+export function validateInlineEvents(lines: string[], symbols: DocumentSymbols, application: DocumentSymbols): ValidationIssue[] {
+    lines = eventAnalysisSource(lines);
+    const issues: ValidationIssue[] = [];
+    const fences = fenceMap(lines);
+    const documentationBlocks = nonemptyMarkdownBlocks(lines, fences);
+    const commandProductions = new Set(symbols.commands.flatMap(command => command.productionHeaders ?? []));
+    const eventCounts = new Map<string, number>();
+    const importedNames = new Set<string>();
+    for (const document of [symbols, application]) {
+        for (const event of document.events) eventCounts.set(event.name, (eventCounts.get(event.name) ?? 0) + 1);
+        for (const imported of document.imports) importedNames.add(imported.shortName);
+    }
+    const report = (line: number, code: DiagnosticCode, message: string, severity: ValidationSeverity = 'error') => {
+        issues.push({ line, startColumn: indentOf(lines[line]) + 1, endColumn: lines[line].length + 1, code, message, severity });
+    };
+    for (const event of symbols.events) {
+        const body = directBody(lines, fences, event.line, indentOf(lines[event.line]));
+        if (event.inline) {
+            const properties = new Set<string>();
+            for (const property of event.properties) {
+                if (properties.has(property.name)) report(property.line, diagnosticCodes.duplicateDeclaration, `Event '${event.name}' already declares property '${property.name}'.`);
+                properties.add(property.name);
+            }
+            if (!commandProductions.has(event.line)) report(event.line, diagnosticCodes.inlineEventOutsideCommand, 'Inline events can only be declared inside commands.');
+            if (event.generation !== undefined) report(event.line, diagnosticCodes.inlineEventGeneration, 'Inline events are generation 1; extract the event before declaring generations.');
+            if ((eventCounts.get(event.name) ?? 0) > 1 || importedNames.has(event.name)) {
+                report(event.line, diagnosticCodes.inlineEventCollision, `Inline event '${event.name}' collides with another declaration or import.`);
+            }
+        }
+        let hasId = false;
+        let hasDocumentation = false;
+        for (const index of body) {
+            const text = lines[index].trim();
+            const keyword = text.split(/\s+/)[0];
+            if (event.inline && keyword === 'generation') report(index, diagnosticCodes.inlineEventGeneration, 'Inline events are generation 1; extract the event before declaring generations.');
+            if (event.inline && keyword === 'origin') report(index, diagnosticCodes.reservedProductionMetadata, 'An inline event is local to its command and cannot declare origin.');
+            // Property-shaped metadata names stay properties, whether standalone or typed mappings.
+            if (/^(?:id|description|documentation)\s+[\w.]+(?:\[\])?\??(?:\s*=.*)?$/.test(text)) continue;
+            if (keyword === 'id') {
+                const match = text.match(quotedId);
+                if (hasId || match === null || match[1].trim().length === 0) report(index, diagnosticCodes.invalidEventId, 'Expected one nonempty id "<old-name>".');
+                else if (match[1] === event.name) report(index, diagnosticCodes.redundantEventId, 'This id repeats the event name; remove it.', 'information');
+                hasId = true;
+            }
+            if (keyword === 'documentation') {
+                let next = index + 1;
+                while (next < lines.length && lines[next].trim().length === 0) next++;
+                if (hasDocumentation || text !== 'documentation' || lines[next]?.trim() !== '```markdown' || indentOf(lines[next]) <= indentOf(lines[index]) ||
+                    !documentationBlocks.has(next)) {
+                    report(index, diagnosticCodes.invalidEventDocumentation, 'Expected one nonempty fenced markdown documentation block.');
+                }
+                hasDocumentation = true;
+            }
+        }
+    }
+    // Also cover reaction productions without a backward ancestry walk per metadata line.
+    const productionIndents: number[] = [];
+    for (let index = 0; index < lines.length; index++) {
+        if (fences[index] || lines[index].trim().length === 0) continue;
+        const indent = indentOf(lines[index]);
+        while (productionIndents.length > 0 && productionIndents[productionIndents.length - 1] >= indent) productionIndents.pop();
+        const keyword = lines[index].trim().split(/\s+/)[0];
+        if (reserved.has(keyword) && productionIndents.length > 0) {
+            report(index, diagnosticCodes.reservedProductionMetadata, `'${keyword}' is system-assigned production metadata.`);
+        }
+        if (keyword === 'produces') productionIndents.push(indent);
+    }
+    for (const command of symbols.commands) {
+        const { identifier, mixed } = productionDestinations(command);
+        for (const production of command.produces ?? []) {
+            if (mixed && production.target === undefined) report(production.line, diagnosticCodes.explicitProducesTargetsRequired, `Production '${production.name}' must state for explicitly when destinations differ.`);
+            const destination = production.target ?? (production.inline ? identifier : undefined);
+            if (identifier === undefined || destination !== identifier) continue;
+            for (const mapping of production.mappings.filter(mapping => mapping.source === identifier)) {
+                report(mapping.line, diagnosticCodes.eventSourceIdInPayload, `The payload copies '${identifier}', which already identifies the event source.`, production.inline ? 'warning' : 'information');
+            }
+        }
+    }
+    return issues;
+}
+
+// Record complete, nonempty Markdown fences once. Validation must not scan a suffix
+// for every documentation directive, especially while its opener is still being typed.
+function nonemptyMarkdownBlocks(lines: string[], fences: boolean[]): Set<number> {
+    const blocks = new Set<number>();
+    let opening: number | undefined;
+    let content = false;
+    for (let index = 0; index < lines.length; index++) {
+        if (!fences[index]) continue;
+        const text = lines[index].trim();
+        if (opening === undefined) {
+            opening = index;
+            content = false;
+        } else if (text === '```') {
+            if (content && lines[opening].trim() === '```markdown') blocks.add(opening);
+            opening = undefined;
+        } else if (text.length > 0) {
+            content = true;
+        }
+    }
+    return blocks;
+}

package/keyword-docs.ts

@@ -20,7 +20,9 @@ export const keywordDocs: Record<string, string> = {
     template: 'Declares the named slots of a layout.',
     feature: 'A vertical slice grouping. Features nest arbitrarily deep.',
     slice: 'The atomic unit of behavior, aligned with Event Modeling. Has a type and a name.',
-    event: 'An event type — an immutable, past-tense fact. Properties use concepts or primitives.',
+    event: 'An immutable, past-tense fact. Declare it in a slice or inline with `produces event <Name>` in a command. Inline properties are typed mappings; inline tags belong to the event type.',
+    documentation: 'Authoring-only event documentation in a fenced ```markdown block. It does not change executable model bytes.',
+    id: 'Preserves the previous persisted event name after a rename. Leave absent on new events; repeating the current name is redundant.',
     command: 'An imperative intent. Declares authorization, validation, and what events it produces — declaratively, or via a full handler.',
     query: 'A read-side entry point mapping to a return type, with an optional description, parameters and performer.',
     observable: 'Qualifies a query return type as a live read — `query <Name> => observable <ReadModel>` keeps pushing as the read model changes, instead of answering once.',
@@ -38,7 +40,7 @@ export const keywordDocs: Record<string, string> = {
     constraint: 'A server-side rule enforced in the Chronicle kernel before events are committed.',
     authorize: 'References the policies that must all pass for the construct to execute.',
     validate: 'Declarative validation rules, or `validate` followed by ```csharp for imperative rules — on commands and concepts.',
-    produces: 'Declares the events a command emits — single, multiple, or conditional.',
+    produces: 'References a declared event with `produces <Name>`, or declares one inline with `produces event <Name>`. An inline omitted `for` uses the command identifier only when all destinations are the same source; legacy plain omission allocates an identity.',
     reads: 'Declares a view consulted by a command or reaction trigger: `reads <View> [as <alias>] [by <value>]`. A reaction `by` names a value taken by its trigger; clock triggers cannot use `by`. Repeated views require unique aliases. Runtime binding is not yet supported for command or reaction reads.',
     as: 'Names an instance of a view in a command or reaction trigger reads declaration, for example `reads Account as source by sourceId`.',
     handler: 'A fully imperative command implementation — a `file <Path>` reference or an inline `csharp` block, instead of `produces`.',
@@ -67,7 +69,7 @@ export const keywordDocs: Record<string, string> = {
     streamId: 'Concurrency dimension — scope the check to an event stream id.',
     tag: 'Attaches a tag to appended events — a static identifier or string, or a `$context.` expression resolved at append time.',
     seed: 'Declares events to seed into the event store per event source id — multiple blocks accumulate.',
-    for: 'Introduces a seed group — the events to seed for one event source id.',
+    for: 'Names the event source of a production or seed group. Inside `produces event`, omission uses the command identifier unless another production targets a different source.',
     readmodel: 'Read model state in a specification — `given readmodel` establishes it, `then readmodel` asserts it, `then no readmodel <View> for <key>` asserts keyed absence.',
     no: 'A keyed absence assertion: `then no readmodel <View> for <key>`.',
     arguments: 'The values supplied to a query asserted by `then query`.',

package/package.json

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

package/production-destinations.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { DestinationHint } from './DestinationHint';
+import { eventAnalysisSource } from './event-analysis-source';
+import { CommandSymbol, scanDocument } from './symbols';
+
+export function productionDestinations(command: CommandSymbol): { identifier?: string; mixed: boolean } {
+    const identifiers = command.properties.filter(property => property.isIdentifier && !property.type.includes('?') && !property.type.includes('[]'));
+    const identifier = identifiers.length === 1 ? identifiers[0].name : undefined;
+    const productions = command.produces ?? [];
+    const mixed = productions.some(production => production.target !== undefined && production.target !== identifier) ||
+        (productions.some(production => production.inline && production.target === undefined) &&
+         productions.some(production => !production.inline && production.target === undefined));
+    return { identifier, mixed };
+}
+
+// Shared by both editor adapters. Never suggest that a legacy allocated source is the command identifier.
+export function destinationHints(lines: string[]): DestinationHint[] {
+    const source = eventAnalysisSource(lines);
+    return scanDocument(source).commands.flatMap(command => {
+        const { identifier, mixed } = productionDestinations(command);
+        if (mixed || command.productionHeaders?.length !== command.produces?.length) return [];
+        const hasPromotedDestination = command.produces?.some(sibling => sibling.target !== undefined || sibling.inline);
+        return (command.produces ?? []).flatMap(production => {
+            if (production.target !== undefined || (production.inline && (identifier === undefined || /\bgeneration\b/.test(source[production.line])))) return [];
+            // A sibling destination can promote the command default in the legacy binder.
+            if (!production.inline && hasPromotedDestination) return [];
+            return [{ line: production.line, column: source[production.line].length + 1, label: production.inline ? `for ${identifier}` : 'for <new event source>' }];
+        });
+    });
+}

package/symbols.ts

@@ -2,7 +2,9 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { fenceMap, indentOf } from './document-context';
+import { eventAnalysisSource } from './event-analysis-source';
 import { clauseKeywords } from './language';
+import { ProductionSymbol } from './ProductionSymbol';
 
 export interface PropertySymbol {
     name: string;
@@ -35,6 +37,7 @@ export interface PolicySymbol {
 export interface EventSymbol {
     name: string;
     generation?: number;
+    inline?: boolean;
     properties: PropertySymbol[];
     line: number;
 }
@@ -42,6 +45,8 @@ export interface EventSymbol {
 export interface CommandSymbol extends NamedSymbol {
     properties: PropertySymbol[];
     reads?: ReadSymbol[];
+    produces?: ProductionSymbol[];
+    productionHeaders?: number[];
 }
 
 export interface ReadSymbol {
@@ -83,19 +88,21 @@ const conceptPattern = /^concept\s+(\w+)\s*:\s*(\w+)((?:\s+@\w+)*)\s*$/;
 const propertyPattern = /^\s*(@?[a-z_]\w*)\s+([\w.]+(?:\[\])?\??)(\s+identifier)?\s*$/;
 const attributeReasonPattern = /^([a-z_]\w*)\s+reason\s+"((?:[^"\\]|\\.)*)"\s*$/;
 const readPattern = /^\s*reads\s+([A-Z]\w*)(?:\s+as\s+([a-z_]\w*))?(?:\s+by\s+([a-z_]\w*))?\s*$/;
+const commandReserved = ['authorize', 'produces', 'reads'];
+// AuthorizeParser's continuation pattern, including the compiler's Unicode word characters.
+const authorizationContinuation = /^(?:(?:or|and)\s+)?[A-Za-z_(][\p{L}\p{Mn}\p{Nd}\p{Pc}\s()]*$/u;
+const eventReserved = clauseKeywords.filter(keyword => !['id', 'description', 'documentation'].includes(keyword));
 const queryParameterPattern =
     /^\s*(?:by|filter)\s+([a-z_]\w*)\s+([\w.]+(?:\[\])?\??)(?:\s+from\s+.+)?\s*$/;
 
-// A body line can only be a genuine PropertyLine when its name is not itself a reserved clause
-// keyword - 'authorize CanManageInvoice', 'produces InvoiceRegistered', 'tag audit', 'validate'
-// and every 'concurrency' dimension ('sourceType Invoice', 'streamType Invoicing', ...) all have the
-// same two-token shape a property line does. The grammar's own keyword escape ('@authorize ...') is
-// the one way a real property may share a name with one of these, so only that form survives here.
-function propertiesIn(lines: string[], body: number[]): PropertySymbol[] {
+// Property-shaped clauses depend on their owner. Commands reserve only authorize,
+// produces and reads; bare directives such as description and handler can be properties.
+// The @ escape always denotes a property, and 'as' keeps its established property meaning.
+function propertiesIn(lines: string[], body: number[], reserved: readonly string[]): PropertySymbol[] {
     return body
         .map((index) => ({ index, match: lines[index].match(propertyPattern) }))
         .filter((entry): entry is { index: number; match: RegExpMatchArray } => entry.match !== null)
-        .filter(({ match }) => match[1].startsWith('@') || match[1] === 'as' || !clauseKeywords.includes(match[1]))
+        .filter(({ match }) => match[1].startsWith('@') || match[1] === 'as' || !reserved.includes(match[1]))
         .map(({ index, match }) => ({
             name: match[1].replace(/^@/, ''),
             type: match[2],
@@ -108,7 +115,6 @@ function collectBody(lines: string[], fences: boolean[], start: number, indent:
     const body: number[] = [];
     for (let index = start + 1; index < lines.length; index++) {
         if (fences[index]) {
-            body.push(index);
             continue;
         }
         const line = lines[index];
@@ -119,6 +125,29 @@ function collectBody(lines: string[], fences: boolean[], start: number, indent:
     return body;
 }
 
+// Event/production parsers accept every greater indent, not just the smallest child indent.
+// Command block directives own their nested lines; properties do not. Fenced prose is never syntax.
+export function directBody(lines: string[], fences: boolean[], start: number, indent: number): number[] {
+    const body = collectBody(lines, fences, start, indent).filter(index => !fences[index] && !/^\s*(?:\/\/|#)/.test(lines[index]));
+    if (!/^\s*command\b/.test(lines[start])) return body;
+    let blockIndent: number | undefined;
+    let authorization = false;
+    return body.filter(index => {
+        const childIndent = indentOf(lines[index]);
+        const text = lines[index].trim();
+        // AuthorizeParser owns only consecutive deeper lines with requirement shape.
+        // Unlike opaque blocks, a nonmatching line returns control to CommandParser.
+        if (blockIndent !== undefined && childIndent > blockIndent &&
+            (!authorization || authorizationContinuation.test(text))) return false;
+        const property = text !== 'validate csharp' && propertiesIn(lines, [index], commandReserved).length > 0;
+        // Description consumes only a quoted value or a fence (already excluded above).
+        const leaf = property || /^description(?:\s|$)/.test(text);
+        blockIndent = leaf ? undefined : childIndent;
+        authorization = /^authorize(?:\s|$)/.test(text);
+        return true;
+    });
+}
+
 export function scanDocument(lines: string[]): DocumentSymbols {
     const symbols: DocumentSymbols = {
         imports: [],
@@ -131,7 +160,14 @@ export function scanDocument(lines: string[]): DocumentSymbols {
         screens: [],
         triggers: [],
     };
+    // One normalization pass for every declaration, including comments on fence openers.
+    lines = eventAnalysisSource(lines);
     const fences = fenceMap(lines);
+    const eventLines = lines;
+    const eventFences = fences;
+    // Typed inline mappings share property syntax once their source expression is removed.
+    // Do this once, never once per inline event.
+    const eventPropertyLines = lines.map(line => line.replace(/\s*=(?!=|>).*/, ''));
 
     for (let index = 0; index < lines.length; index++) {
         if (fences[index]) continue;
@@ -139,7 +175,7 @@ export function scanDocument(lines: string[]): DocumentSymbols {
         const trimmed = line.trim();
         const indent = indentOf(line);
 
-        const importMatch = trimmed.match(/^import\s+([\w.]+)\s*$/);
+        const importMatch = eventLines[index].trim().match(/^import\s+([\w.]+)\s*$/);
         if (importMatch && indent === 0) {
             const qualifiedName = importMatch[1];
             const shortName = qualifiedName.split('.').pop() ?? qualifiedName;
@@ -176,7 +212,7 @@ export function scanDocument(lines: string[]): DocumentSymbols {
         if (typeMatch) {
             symbols.types.push({
                 name: typeMatch[1],
-                properties: propertiesIn(lines, collectBody(lines, fences, index, indent)),
+                properties: propertiesIn(lines, collectBody(lines, fences, index, indent), clauseKeywords),
                 line: index,
             });
             continue;
@@ -191,23 +227,47 @@ export function scanDocument(lines: string[]): DocumentSymbols {
             continue;
         }
 
-        const eventMatch = trimmed.match(/^event\s+(\w+)(?:\s+generation\s+(\d+))?\s*$/);
+        const eventMatch = eventLines[index].trim().match(/^(?:produces\s+)?event\s+(\w+)(?:\s+generation\s+(\d+))?\s*$/);
         if (eventMatch) {
             symbols.events.push({
                 name: eventMatch[1],
                 ...(eventMatch[2] ? { generation: Number(eventMatch[2]) } : {}),
-                properties: propertiesIn(lines, collectBody(lines, fences, index, indent)),
+                inline: trimmed.startsWith('produces '),
+                properties: propertiesIn(trimmed.startsWith('produces ') ? eventPropertyLines : eventLines,
+                    directBody(eventLines, eventFences, index, indent), eventReserved),
                 line: index,
             });
             continue;
         }
 
-        const commandMatch = trimmed.match(/^command\s+(\w+)\s*$/);
+        const commandMatch = eventLines[index].trim().match(/^command\s+(\w+)\s*$/);
         if (commandMatch) {
-            const body = collectBody(lines, fences, index, indent);
+            // A command property is a leaf, not an indentation owner. Share the parser-shaped
+            // body with properties, productions, advice and destination hints.
+            const body = directBody(lines, fences, index, indent);
+            const productionHeaders = body.filter(line => /^\s*produces\b/.test(lines[line]));
             symbols.commands.push({
                 name: commandMatch[1],
-                properties: propertiesIn(lines, body),
+                properties: propertiesIn(lines, body.filter(line => lines[line].trim() !== 'validate csharp'), commandReserved),
+                productionHeaders,
+                produces: productionHeaders.flatMap(line => {
+                    const header = eventLines[line].trim();
+                    const inline = /^produces\s+event\b/.test(header);
+                    const conditional = /^produces\s+when\b/.test(header);
+                    const eventLine = conditional ? directBody(eventLines, eventFences, line, indentOf(eventLines[line]))[0] : line;
+                    if (eventLine === undefined) return [];
+                    const name = conditional ? eventLines[eventLine].trim() : header.match(inline ? /^produces\s+event\s+([A-Za-z_]\w*)(?:\s+generation\s+\d+)?\s*$/ : /^produces\s+([A-Z]\w*)\s*$/)?.[1];
+                    if (name === undefined || !/^[A-Za-z_]\w*$/.test(name)) return [];
+                    const children = directBody(eventLines, eventFences, eventLine, indentOf(eventLines[eventLine]));
+                    const targets = children.map(index => eventLines[index].trim().match(/^for(?:\s+(.*))?$/)).filter(match => match !== null);
+                    // Empty or repeated targets are uncertain, not implicit destinations.
+                    const target = targets.length === 0 ? undefined : targets.length === 1 ? targets[0][1] ?? '' : '';
+                    const mappings = children.flatMap(index => {
+                        const match = eventLines[index].trim().match(inline ? /^(@?[a-z_]\w*)\s+[\w.[\]?]+\s*=(?!=|>)\s*(.+)$/ : /^(@?[\w.]+)\s*=(?!=|>)\s*(.+)$/);
+                        return match === null ? [] : [{ name: match[1].replace(/^@/, ''), source: match[2], line: index }];
+                    });
+                    return [{ name, inline, conditional, line, target, mappings }];
+                }),
                 reads: body.filter((line) => !fences[line])
                     .map((line) => ({ line, match: lines[line].match(readPattern) }))
                     .filter((entry): entry is { line: number; match: RegExpMatchArray } => entry.match !== null)

package/tokens.ts

@@ -59,9 +59,11 @@ export function createTokensProvider(subLanguages: SubLanguage[]): languages.IMo
             [/^(\s*)(then)(\s+)(result|no\s+result)\b/, ['white', 'keyword', 'white', 'keyword']],
             // A quoted import names .play files rather than a qualified name - the path reads as a link.
             [/^(\s*)(import)(\s+)("[^"\\]*")/, ['white', 'keyword', 'white', 'string.link']],
-            // Only an event header reserves 'generation'; properties and context paths do not.
-            [/^(\s*)(event)(\s+)([A-Za-z_]\w*)(\s+)(generation)(?=\s+\d+\s*$)/,
-                ['white', 'keyword', 'white', 'type.identifier', 'white', 'keyword']],
+            // Retain the header indent so event metadata stops at the enclosing block boundary.
+            [/^(\s*)((?:produces\s+)?event)(\s+)([A-Za-z_]\w*)(\s+)(generation)(\s+)(\d+)(?=\s*(?:\/\/.*)?$)/,
+                ['white', 'keyword', 'white', 'type.identifier', 'white', 'keyword', 'white', { token: 'number', next: '@eventBody.$1' }]],
+            [/^(\s*)((?:produces\s+)?event)(\s+)([A-Za-z_]\w*)(?=\s*(?:\/\/.*)?$)/,
+                ['white', 'keyword', 'white', { token: 'type.identifier', next: '@eventBody.$1' }]],
             // A tagged opening fence carries the embedded language; legacy tag lines still highlight.
             ...codeBlockTags.map(
                 (tag): MonarchTokenRules[number] => [
@@ -111,6 +113,13 @@ export function createTokensProvider(subLanguages: SubLanguage[]): languages.IMo
             { include: '@common' },
         ],
 
+        eventBody: [
+            [/^(?!$S2[ \t]+|\s*$)/, { token: '@rematch', next: '@pop' }],
+            [/^(\s*)(id)(?=\s+")/, ['white', 'keyword']],
+            [/^(\s*)(documentation)(?=\s*(?:\/\/.*)?$)/, ['white', { token: 'keyword', next: '@descriptionBlockPending' }]],
+            { include: '@root' },
+        ],
+
         common: commonTokenRules,
 
         // After a code tag, the only thing allowed before the opening fence is whitespace.
@@ -131,7 +140,8 @@ export function createTokensProvider(subLanguages: SubLanguage[]): languages.IMo
 
         // After a bare description, the only thing allowed before the opening fence is whitespace.
         descriptionBlockPending: [
-            [/^\s*```(?:text)?\s*$/, { token: 'string.quote', switchTo: '@descriptionBlock' }],
+            [/\/\/.*$/, 'comment'],
+            [/^\s*```(?:text|markdown)?\s*$/, { token: 'string.quote', switchTo: '@descriptionBlock' }],
             [/^\s*[^\s`].*$/, { token: '@rematch', next: '@pop' }],
             [/\s+/, 'white'],
         ],

package/validation.ts

@@ -1,9 +1,11 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import { validateInlineEvents } from './inline-event-validation';
 import { causedByProperties, contextRoots, identityProperties, primitiveTypes, sliceTypes } from './language';
 import { DiagnosticCode, diagnosticCodes } from './diagnostic-codes';
 import { enclosingChain, fenceMap, indentOf } from './document-context';
+import { eventAnalysisSource } from './event-analysis-source';
 import { resolveEventContextPath } from './event-context';
 import {
     DocumentSymbols,
@@ -15,7 +17,7 @@ import {
 } from './symbols';
 import { fileImportOn, isFileImportLine } from './file-imports';
 
-export type ValidationSeverity = 'error' | 'warning';
+export type ValidationSeverity = 'error' | 'warning' | 'information';
 
 export interface ValidationIssue {
     line: number;
@@ -139,6 +141,7 @@ export function validateLines(lines: string[], context: ValidationContext = {}):
     const events = new Set([...knownEventNames(symbols), ...knownEventNames(application)]);
     const policies = new Set([...symbols.policies, ...application.policies].map((policy) => policy.name));
     const issues: ValidationIssue[] = validateDeclarations(lines, symbols, application);
+    issues.push(...validateProductionDestinations(lines, symbols));
 
     const checkEvent = (line: number, text: string, name: string) => {
         if (!events.has(name)) {
@@ -325,6 +328,7 @@ export function validateLines(lines: string[], context: ValidationContext = {}):
     }
 
     issues.push(...validateEventContextPaths(lines, fences));
+    issues.push(...validateInlineEvents(lines, symbols, application));
 
     const fenceLines = lines
         .map((line, index) => ({ line, index }))
@@ -346,6 +350,24 @@ export function validateLines(lines: string[], context: ValidationContext = {}):
     return issues;
 }
 
+// This is advice, not a semantic default: accepting the typed workspace repair changes routing.
+function validateProductionDestinations(lines: string[], symbols: DocumentSymbols): ValidationIssue[] {
+    const issues: ValidationIssue[] = [];
+    lines = eventAnalysisSource(lines);
+    for (const command of symbols.commands) {
+        const identifiers = command.properties.filter(property => property.isIdentifier && !property.type.endsWith('?') && !property.type.endsWith('[]'));
+        if (identifiers.length !== 1) continue;
+        for (const production of command.produces ?? []) {
+            if (production.inline || production.conditional || production.target !== undefined) continue;
+            const line = production.line;
+            issues.push(issue('information', line, indentOf(lines[line]) + 1, lines[line].trim().length,
+                `Plain 'produces ${production.name}' omits its destination — use 'for ${identifiers[0].name}' to explicitly select the command's identifier.`,
+                diagnosticCodes.omittedProductionDestination));
+        }
+    }
+    return issues;
+}
+
 // Inside a module or feature an import names files, and a quoted import anywhere has the compiler's shape.
 function validateImport(lines: string[], fences: boolean[], index: number): ValidationIssue | undefined {
     const line = lines[index];