@cratis/screenplay-language 1.6.4 → 1.7.0

package/keyword-docs.ts

@@ -4,7 +4,10 @@
 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.',
-    concept: 'A formalized value type wrapping a primitive. Attributes such as `@pii` travel with every usage.',
+    concept: 'A formalized value type wrapping a primitive. Attributes such as `@pii` travel with every usage, optionally with a `<attribute> reason "..."` line saying why.',
+    type: 'A composite value type — a named shape built from several properties, referenced by events, commands and other types the same way a concept is.',
+    reason: 'Records why a concept attribute applies — the purpose, the lawful basis, whose subject the value lives under. Written as `pii reason "..."` in the concept body.',
+    identifier: 'Marks the command property a runtime resolves the event source id from. At most one per command; without it a new Uuid is generated.',
     policy: 'A named authorization rule referenced by commands and queries. Multiple policies AND together.',
     persona: 'A named role interacting with the application, with an optional description and its associated policies.',
     authentication: 'Declares the identity providers of the application — at most one block per file.',
@@ -17,10 +20,12 @@ export const keywordDocs: Record<string, string> = {
     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.',
     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.',
+    query: 'A read-side entry point mapping to a return type, with an optional description, parameters and performer.',
+    performer: 'The code that performs a query — a `file <Path>` reference or an inline `csharp`/`sql` block. The query\'s counterpart to a command handler.',
+    from: 'Fills a query parameter from the query context instead of the caller, as in `filter tenantId TenantId from $context.tenant`.',
     projection: 'Declares how events project into a read model, using the embedded Projection Declaration Language (PDL).',
     capture: 'Converts external data into events, using the embedded Change Data Capture Language (CDL).',
-    reactor: 'Reacts to events and produces side effects. Lives inside Automation slices.',
+    reactor: 'Reacts to events and produces side effects. Lives inside Automation slices. A trigger with no body states intent on its own — `file`/code is optional realization metadata.',
     screen: 'A UI declaration. Supports intent, structure, and layout-with-code levels, or a full file reference.',
     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.',
@@ -70,6 +75,7 @@ export const keywordDocs: Record<string, string> = {
     and: 'Both conditions must hold.',
     or: 'Either condition may hold.',
     csharp: 'An inline C# block between triple backticks.',
+    sql: 'An inline SQL block between triple backticks — a query performer written against a relational store.',
     typescript: 'An inline TypeScript block between triple backticks.',
     react: 'An inline React/TSX block; receives the surrounding data contract as `Props`.',
     html: 'An inline static HTML block.',
@@ -88,12 +94,21 @@ export const keywordDocs: Record<string, string> = {
 };
 
 export const attributeDocs: Record<string, string> = {
-    pii: '`@pii` — the value is personally identifiable information; Chronicle manages and erases it automatically wherever the concept is used.',
-    sensitive: '`@sensitive` — the value is sensitive; Chronicle applies its sensitivity rules automatically wherever the concept is used.',
+    pii: '`@pii` — the value is personally identifiable information; Chronicle manages and erases it automatically wherever the concept is used. Add `pii reason "..."` in the concept body to record why.',
+    sensitive: '`@sensitive` — the value is sensitive; Chronicle applies its sensitivity rules automatically wherever the concept is used. Add `sensitive reason "..."` in the concept body to record why.',
 };
 
 export const contextVariableDocs: Record<string, string> = {
-    '$context.occurred': 'The timestamp of the event.',
+    '$context.occurred': 'When the command or query was received.',
+    '$context.tenant': 'The tenant the command or query is executing for.',
+    '$context.command': 'The command being handled, shaped by its `command` declaration.',
+    '$context.arguments': 'The arguments of the query being performed.',
+    '$context.causedBy': 'The identity that caused the command or query — `subject`, `name`, `userName`.',
+    '$context.causedBy.subject': 'The subject of the identity that caused the command or query.',
+    '$context.causedBy.name': 'The display name of the identity that caused the command or query.',
+    '$context.causedBy.userName': 'The user name of the identity that caused the command or query.',
+    '$context.causation': 'What caused the command or query — `type`, `occurred`, `properties`.',
+    '$context.causation.type': 'What caused the command or query — a command, a reactor, a schedule.',
     '$context.identity.id': 'The subject of the caller from the auth token.',
     '$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.',

package/language.ts

@@ -18,6 +18,7 @@ export const constructKeywords = [
     'domain',
     'import',
     'concept',
+    'type',
     'policy',
     'persona',
     'authentication',
@@ -47,6 +48,10 @@ export const clauseKeywords = [
     'validate',
     'produces',
     'handler',
+    'performer',
+    'identifier',
+    'reason',
+    'from',
     'when',
     'given',
     'then',
@@ -92,7 +97,20 @@ export const clauseKeywords = [
     'provider',
 ];
 
-export const codeBlockTags = ['csharp', 'typescript', 'react', 'html'];
+export const codeBlockTags = ['csharp', 'typescript', 'react', 'html', 'sql'];
+
+// The roots a `$context.` path can start with — the members of CommandContext and QueryContext.
+export const contextRoots = [
+    'command',
+    'arguments',
+    'tenant',
+    'causedBy',
+    'causation',
+    'occurred',
+    'identity',
+];
+
+export const causedByProperties = ['subject', 'name', 'userName'];
 
 export const sliceTypes = ['StateChange', 'StateView', 'Automation', 'Translate'];
 
@@ -123,7 +141,7 @@ export const languageConfiguration: languages.LanguageConfiguration = {
     },
     indentationRules: {
         increaseIndentPattern:
-            /^\s*(module|feature|slice|policy|persona|authentication|provider|event|command|screen|projection|capture|reactor|constraint|layout|template|validate|produces|handler|section|concurrency|seed|for)\b.*$/,
+            /^\s*(module|feature|slice|policy|persona|authentication|provider|event|command|query|type|screen|projection|capture|reactor|constraint|layout|template|validate|produces|handler|performer|section|concurrency|seed|for)\b.*$/,
         // Dedents are always explicit in an offside language — never auto-dedent.
         decreaseIndentPattern: /(?!)/,
     },

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/screenplay-language",
-    "version": "1.6.4",
+    "version": "1.7.0",
     "description": "Monaco language service for the Cratis Screenplay DSL — syntax highlighting, IntelliSense, hover and diagnostics for .play files",
     "license": "MIT",
     "repository": {

package/symbols.ts

@@ -6,16 +6,25 @@ import { fenceMap, indentOf } from './document-context';
 export interface PropertySymbol {
     name: string;
     type: string;
+    isIdentifier: boolean;
+    line: number;
 }
 
 export interface ConceptSymbol {
     name: string;
     primitive: string;
     attributes: string[];
+    attributeReasons: Record<string, string>;
     enumValues: string[];
     line: number;
 }
 
+export interface TypeSymbol {
+    name: string;
+    properties: PropertySymbol[];
+    line: number;
+}
+
 export interface PolicySymbol {
     name: string;
     requires: string[];
@@ -28,6 +37,10 @@ export interface EventSymbol {
     line: number;
 }
 
+export interface CommandSymbol extends NamedSymbol {
+    properties: PropertySymbol[];
+}
+
 export interface NamedSymbol {
     name: string;
     line: number;
@@ -35,6 +48,7 @@ export interface NamedSymbol {
 
 export interface QuerySymbol extends NamedSymbol {
     returnType: string;
+    parameters: PropertySymbol[];
 }
 
 export interface ImportSymbol {
@@ -46,15 +60,31 @@ export interface ImportSymbol {
 export interface DocumentSymbols {
     imports: ImportSymbol[];
     concepts: ConceptSymbol[];
+    types: TypeSymbol[];
     policies: PolicySymbol[];
     events: EventSymbol[];
-    commands: NamedSymbol[];
+    commands: CommandSymbol[];
     queries: QuerySymbol[];
     screens: NamedSymbol[];
 }
 
 const conceptPattern = /^concept\s+(\w+)\s*:\s*(\w+)((?:\s+@\w+)*)\s*$/;
-const propertyPattern = /^\s*([a-z_]\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 queryParameterPattern =
+    /^\s*(?:by|filter)\s+([a-z_]\w*)\s+([\w.]+(?:\[\])?\??)(?:\s+from\s+.+)?\s*$/;
+
+function propertiesIn(lines: string[], body: number[]): PropertySymbol[] {
+    return body
+        .map((index) => ({ index, match: lines[index].match(propertyPattern) }))
+        .filter((entry): entry is { index: number; match: RegExpMatchArray } => entry.match !== null)
+        .map(({ index, match }) => ({
+            name: match[1].replace(/^@/, ''),
+            type: match[2],
+            isIdentifier: match[3] !== undefined,
+            line: index,
+        }));
+}
 
 function collectBody(lines: string[], fences: boolean[], start: number, indent: number): number[] {
     const body: number[] = [];
@@ -75,6 +105,7 @@ export function scanDocument(lines: string[]): DocumentSymbols {
     const symbols: DocumentSymbols = {
         imports: [],
         concepts: [],
+        types: [],
         policies: [],
         events: [],
         commands: [],
@@ -99,20 +130,39 @@ export function scanDocument(lines: string[]): DocumentSymbols {
 
         const conceptMatch = trimmed.match(conceptPattern);
         if (conceptMatch) {
+            const body = collectBody(lines, fences, index, indent).map((i) => lines[i].trim());
+            const attributeReasons: Record<string, string> = {};
+            for (const line of body) {
+                const reason = line.match(attributeReasonPattern);
+                if (reason && attributeReasons[reason[1]] === undefined) {
+                    attributeReasons[reason[1]] = reason[2];
+                }
+            }
             const enumValues =
                 conceptMatch[2] === 'Enum'
-                    ? collectBody(lines, fences, index, indent).map((i) => lines[i].trim())
+                    ? body.filter((line) => !attributeReasonPattern.test(line))
                     : [];
             symbols.concepts.push({
                 name: conceptMatch[1],
                 primitive: conceptMatch[2],
                 attributes: conceptMatch[3].trim().split(/\s+/).filter(Boolean),
+                attributeReasons,
                 enumValues,
                 line: index,
             });
             continue;
         }
 
+        const typeMatch = trimmed.match(/^type\s+(\w+)\s*$/);
+        if (typeMatch) {
+            symbols.types.push({
+                name: typeMatch[1],
+                properties: propertiesIn(lines, collectBody(lines, fences, index, indent)),
+                line: index,
+            });
+            continue;
+        }
+
         const policyMatch = trimmed.match(/^policy\s+(\w+)\s*$/);
         if (policyMatch) {
             const requires = collectBody(lines, fences, index, indent)
@@ -124,23 +174,46 @@ export function scanDocument(lines: string[]): DocumentSymbols {
 
         const eventMatch = trimmed.match(/^event\s+(\w+)\s*$/);
         if (eventMatch) {
-            const properties = collectBody(lines, fences, index, indent)
-                .map((i) => lines[i].match(propertyPattern))
-                .filter((match): match is RegExpMatchArray => match !== null)
-                .map((match) => ({ name: match[1], type: match[2] }));
-            symbols.events.push({ name: eventMatch[1], properties, line: index });
+            symbols.events.push({
+                name: eventMatch[1],
+                properties: propertiesIn(lines, collectBody(lines, fences, index, indent)),
+                line: index,
+            });
             continue;
         }
 
         const commandMatch = trimmed.match(/^command\s+(\w+)\s*$/);
         if (commandMatch) {
-            symbols.commands.push({ name: commandMatch[1], line: index });
+            symbols.commands.push({
+                name: commandMatch[1],
+                properties: propertiesIn(lines, collectBody(lines, fences, index, indent)),
+                line: index,
+            });
             continue;
         }
 
         const queryMatch = trimmed.match(/^query\s+(\w+)\s*=>\s*([\w[\]]+)\s*$/);
         if (queryMatch) {
-            symbols.queries.push({ name: queryMatch[1], returnType: queryMatch[2], line: index });
+            // The return type names a read model, which no construct declares — only the
+            // 'by' and 'filter' parameters resolve against the document's own types.
+            const parameters = collectBody(lines, fences, index, indent)
+                .map((i) => ({ index: i, match: lines[i].match(queryParameterPattern) }))
+                .filter(
+                    (entry): entry is { index: number; match: RegExpMatchArray } =>
+                        entry.match !== null,
+                )
+                .map(({ index: line, match }) => ({
+                    name: match[1],
+                    type: match[2],
+                    isIdentifier: false,
+                    line,
+                }));
+            symbols.queries.push({
+                name: queryMatch[1],
+                returnType: queryMatch[2],
+                parameters,
+                line: index,
+            });
             continue;
         }
 
@@ -159,3 +232,14 @@ export function knownEventNames(symbols: DocumentSymbols): string[] {
         ...symbols.imports.map((imported) => imported.shortName),
     ];
 }
+
+// Everything a property type reference can resolve to — the primitives, the declared
+// concepts and types, and the short names of the imports.
+export function knownTypeNames(symbols: DocumentSymbols, primitives: readonly string[]): string[] {
+    return [
+        ...primitives,
+        ...symbols.concepts.map((concept) => concept.name),
+        ...symbols.types.map((type) => type.name),
+        ...symbols.imports.map((imported) => imported.shortName),
+    ];
+}

package/tokens.ts

@@ -17,6 +17,7 @@ const embeddedLanguages: Record<string, string> = {
     typescript: 'typescript',
     react: 'typescript',
     html: 'html',
+    sql: 'sql',
 };
 
 function subLanguageState(keyword: string): string {

package/validation.ts

@@ -1,9 +1,15 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { primitiveTypes, sliceTypes } from './language';
+import { causedByProperties, contextRoots, primitiveTypes, sliceTypes } from './language';
 import { fenceMap, indentOf } from './document-context';
-import { knownEventNames, scanDocument } from './symbols';
+import {
+    DocumentSymbols,
+    PropertySymbol,
+    knownEventNames,
+    knownTypeNames,
+    scanDocument,
+} from './symbols';
 
 export type ValidationSeverity = 'error' | 'warning';
 
@@ -36,6 +42,69 @@ function tokenIssue(
     return issue(severity, line, column, token.length, message);
 }
 
+// Reports every property whose type reference names nothing the document declares, and
+// every command that marks more than one property as its identifier.
+function validateDeclarations(lines: string[], symbols: DocumentSymbols): ValidationIssue[] {
+    const issues: ValidationIssue[] = [];
+    const types = new Set(knownTypeNames(symbols, primitiveTypes));
+
+    const checkProperties = (properties: PropertySymbol[], owner: string) => {
+        for (const property of properties.filter(
+            (candidate) => !types.has(candidate.type.replace(/[[\]?]/g, '')),
+        )) {
+            const bare = property.type.replace(/[[\]?]/g, '');
+            issues.push(
+                tokenIssue(
+                    'warning',
+                    property.line,
+                    lines[property.line],
+                    property.type,
+                    `Unknown type '${bare}' on '${property.name}' of ${owner} — declare it with 'concept ${bare} : <Primitive>' or 'type ${bare}'.`,
+                ),
+            );
+        }
+    };
+
+    for (const type of symbols.types) checkProperties(type.properties, `type '${type.name}'`);
+    for (const event of symbols.events) checkProperties(event.properties, `event '${event.name}'`);
+    for (const query of symbols.queries) checkProperties(query.parameters, `query '${query.name}'`);
+    for (const command of symbols.commands) {
+        checkProperties(command.properties, `command '${command.name}'`);
+        const identifiers = command.properties.filter((property) => property.isIdentifier);
+        for (const extra of identifiers.slice(1)) {
+            issues.push(
+                tokenIssue(
+                    'error',
+                    extra.line,
+                    lines[extra.line],
+                    'identifier',
+                    `Command '${command.name}' already marks '${identifiers[0].name}' as identifier — only one property can be the identifier.`,
+                ),
+            );
+        }
+    }
+
+    const declared = new Map<string, number>();
+    for (const declaration of [...symbols.concepts, ...symbols.types]) {
+        const first = declared.get(declaration.name);
+        if (first === undefined) {
+            declared.set(declaration.name, declaration.line);
+            continue;
+        }
+        issues.push(
+            tokenIssue(
+                'error',
+                declaration.line,
+                lines[declaration.line],
+                declaration.name,
+                `Duplicate declaration of '${declaration.name}' — concept and type names must be unique.`,
+            ),
+        );
+    }
+
+    return issues;
+}
+
 // Validates a Screenplay document without any editor dependency — both the Monaco
 // service and the VSCode extension adapt these issues to their marker/diagnostic APIs.
 export function validateLines(lines: string[]): ValidationIssue[] {
@@ -43,7 +112,7 @@ export function validateLines(lines: string[]): ValidationIssue[] {
     const symbols = scanDocument(lines);
     const events = new Set(knownEventNames(symbols));
     const policies = new Set(symbols.policies.map((policy) => policy.name));
-    const issues: ValidationIssue[] = [];
+    const issues: ValidationIssue[] = validateDeclarations(lines, symbols);
 
     const checkEvent = (line: number, text: string, name: string) => {
         if (!events.has(name)) {
@@ -131,6 +200,24 @@ export function validateLines(lines: string[]): ValidationIssue[] {
 
         const uniqueProperty = trimmed.match(/^unique\s+[a-z_]\w*\s+on\s+([A-Z]\w*)/);
         if (uniqueProperty) checkEvent(index, line, uniqueProperty[1]);
+
+        // Every $context. path must name something CommandContext or QueryContext carries.
+        for (const path of line.match(/\$context\.[\w.]+/g) ?? []) {
+            const segments = path.substring('$context.'.length).split('.');
+            if (!contextRoots.includes(segments[0])) {
+                issues.push(
+                    tokenIssue('warning', index, line, path, `Unknown $context path '${segments.join('.')}' — expected one of ${contextRoots.join(', ')}.`),
+                );
+            } else if (
+                segments[0] === 'causedBy' &&
+                segments.length > 1 &&
+                !causedByProperties.includes(segments[1])
+            ) {
+                issues.push(
+                    tokenIssue('warning', index, line, path, `Unknown $context.causedBy property '${segments[1]}' — expected ${causedByProperties.join(', ')}.`),
+                );
+            }
+        }
     }
 
     const fenceLines = lines