@cratis/screenplay-language 0.1.0

package/dist/validation.js

@@ -0,0 +1,101 @@
+// 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 { fenceMap, indentOf } from './document-context';
+import { knownEventNames, scanDocument } from './symbols';
+function issue(severity, line, startColumn, length, message) {
+    return { severity, message, line, startColumn, endColumn: startColumn + length };
+}
+function tokenIssue(severity, line, text, token, message) {
+    const column = text.indexOf(token) + 1;
+    return issue(severity, line, column, token.length, message);
+}
+// 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) {
+    const fences = fenceMap(lines);
+    const symbols = scanDocument(lines);
+    const events = new Set(knownEventNames(symbols));
+    const policies = new Set(symbols.policies.map((policy) => policy.name));
+    const issues = [];
+    const checkEvent = (line, text, name) => {
+        if (!events.has(name)) {
+            issues.push(tokenIssue('warning', line, text, name, `Unknown event type '${name}' — declare it in a slice or import it.`));
+        }
+    };
+    let authorizeIndent = -1;
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index];
+        const trimmed = line.trim();
+        if (fences[index] || trimmed.length === 0)
+            continue;
+        const leading = line.match(/^[ ]*(\t+)/);
+        if (leading) {
+            issues.push(issue('warning', index, leading[0].length - leading[1].length + 1, leading[1].length, 'Screenplay is indentation-based — use spaces, not tabs.'));
+        }
+        // Policy references continue on indented lines below an authorize clause.
+        if (authorizeIndent >= 0) {
+            if (indentOf(line) > authorizeIndent &&
+                /^(?:or\s+)?[A-Z]\w*(?:\s+or\s+[A-Z]\w*)*$/.test(trimmed)) {
+                for (const name of trimmed.split(/\s+/).filter((token) => token !== 'or')) {
+                    if (!policies.has(name)) {
+                        issues.push(tokenIssue('warning', index, line, name, `Unknown policy '${name}' — declare it with 'policy ${name}'.`));
+                    }
+                }
+                continue;
+            }
+            authorizeIndent = -1;
+        }
+        const slice = trimmed.match(/^slice\s+(\w+)/);
+        if (slice && !sliceTypes.includes(slice[1])) {
+            issues.push(tokenIssue('error', index, line, slice[1], `Unknown slice type '${slice[1]}' — expected ${sliceTypes.join(', ')}.`));
+        }
+        const concept = trimmed.match(/^concept\s+\w+\s*:\s*(\w+)/);
+        if (concept && concept[1] !== 'Enum' && !primitiveTypes.includes(concept[1])) {
+            issues.push(tokenIssue('error', index, line, concept[1], `Unknown primitive type '${concept[1]}' — expected ${primitiveTypes.join(', ')} or Enum.`));
+        }
+        const authorize = trimmed.match(/^authorize\s+(.*)$/);
+        if (authorize) {
+            authorizeIndent = indentOf(line);
+            for (const name of authorize[1].split(/\s+/).filter((token) => token !== 'or' && token.length > 0)) {
+                if (!policies.has(name)) {
+                    issues.push(tokenIssue('warning', index, line, name, `Unknown policy '${name}' — declare it with 'policy ${name}'.`));
+                }
+            }
+        }
+        const reactsOn = trimmed.match(/^on\s+([A-Z]\w*)\s*$/);
+        if (reactsOn)
+            checkEvent(index, line, reactsOn[1]);
+        const produces = trimmed.match(/^produces\s+([A-Z]\w*)\s*$/);
+        if (produces)
+            checkEvent(index, line, produces[1]);
+        if (/^produces\s+when\b/.test(trimmed)) {
+            for (let next = index + 1; next < lines.length; next++) {
+                const candidate = lines[next];
+                if (fences[next] || candidate.trim().length === 0)
+                    continue;
+                if (indentOf(candidate) > indentOf(line)) {
+                    const name = candidate.trim().match(/^([A-Z]\w*)\s*$/);
+                    if (name)
+                        checkEvent(next, candidate, name[1]);
+                }
+                break;
+            }
+        }
+        const uniqueEvent = trimmed.match(/^unique\s+event\s+([A-Z]\w*)/);
+        if (uniqueEvent)
+            checkEvent(index, line, uniqueEvent[1]);
+        const uniqueProperty = trimmed.match(/^unique\s+[a-z_]\w*\s+on\s+([A-Z]\w*)/);
+        if (uniqueProperty)
+            checkEvent(index, line, uniqueProperty[1]);
+    }
+    const fenceLines = lines
+        .map((line, index) => ({ line, index }))
+        .filter(({ line }) => /^\s*```\s*$/.test(line));
+    if (fenceLines.length % 2 === 1) {
+        const last = fenceLines[fenceLines.length - 1];
+        issues.push(issue('error', last.index, 1, last.line.length + 1, 'Unclosed inline code block — expected a closing ``` line.'));
+    }
+    return issues;
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../validation.ts"],"names":[],"mappings":"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"}

package/document-context.ts

@@ -0,0 +1,51 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export function indentOf(line: string): number {
+    return line.length - line.trimStart().length;
+}
+
+export function firstWord(line: string): string {
+    return line.trim().split(/\s+/)[0] ?? '';
+}
+
+// Marks every line that is a code fence or lives inside one, so structural
+// scanning never mistakes inline C#/TypeScript/HTML for Screenplay.
+export function fenceMap(lines: string[]): boolean[] {
+    const map: boolean[] = new Array(lines.length).fill(false);
+    let open = false;
+    for (let index = 0; index < lines.length; index++) {
+        if (/^\s*```\s*$/.test(lines[index])) {
+            map[index] = true;
+            open = !open;
+            continue;
+        }
+        map[index] = open;
+    }
+    return map;
+}
+
+// Walks upward from a position and returns the chain of enclosing block openers,
+// innermost first — e.g. ['command', 'slice', 'feature', 'module']. A block opener
+// is any less-indented line above; its first word names the construct (for layout
+// slots this is the slot name, which callers treat as an unknown construct).
+export function enclosingChain(
+    lines: string[],
+    fences: boolean[],
+    lineIndex: number,
+    indent: number,
+): string[] {
+    const chain: string[] = [];
+    let currentIndent = indent;
+    for (let index = lineIndex - 1; index >= 0 && currentIndent > 0; index--) {
+        if (fences[index]) continue;
+        const line = lines[index];
+        if (line.trim().length === 0) continue;
+        const lineIndent = indentOf(line);
+        if (lineIndent < currentIndent) {
+            chain.push(firstWord(line));
+            currentIndent = lineIndent;
+        }
+    }
+    return chain;
+}

package/hover-content.ts

@@ -0,0 +1,76 @@
+// Copyright (c) Cratis. All rights reserved.
+// 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 { getSubLanguage } from './sub-language-registry';
+import { attributeDocs, contextVariableDocs, keywordDocs } from './keyword-docs';
+
+// Produces the hover markdown for a word at a position, without any editor
+// dependency — the Monaco service and the VSCode extension share this content.
+// Columns are 1-based, matching both editors' word-at-position APIs.
+export function hoverContent(
+    lines: string[],
+    lineIndex: number,
+    word: string,
+    startColumn: number,
+    endColumn: number,
+): string | null {
+    const fences = fenceMap(lines);
+    if (fences[lineIndex]) return null;
+
+    const line = lines[lineIndex] ?? '';
+    const before = line.charAt(startColumn - 2);
+
+    if (before === '@') {
+        const doc = attributeDocs[word];
+        if (doc) return doc;
+    }
+    if (before === '$' || before === '.') {
+        const variable = line.substring(0, endColumn - 1).match(/\$[\w.]*$/)?.[0];
+        if (variable) {
+            const doc =
+                contextVariableDocs[variable] ??
+                (variable.startsWith('$env') ? contextVariableDocs['$env'] : undefined);
+            if (doc) return doc;
+        }
+    }
+
+    const symbols = scanDocument(lines);
+
+    const concept = symbols.concepts.find((candidate) => candidate.name === word);
+    if (concept) {
+        const attributes = concept.attributes.length ? ` ${concept.attributes.join(' ')}` : '';
+        const values = concept.enumValues.length
+            ? `\n\nValues: ${concept.enumValues.join(', ')}`
+            : '';
+        return `\`\`\`screenplay\nconcept ${concept.name} : ${concept.primitive}${attributes}\n\`\`\`${values}`;
+    }
+
+    const policy = symbols.policies.find((candidate) => candidate.name === word);
+    if (policy) {
+        const body = policy.requires.length ? policy.requires.join('\n') : '(custom C#)';
+        return `\`\`\`screenplay\npolicy ${policy.name}\n${body}\n\`\`\``;
+    }
+
+    const event = symbols.events.find((candidate) => candidate.name === word);
+    if (event) {
+        const properties = event.properties
+            .map((property) => `${property.name} ${property.type}`)
+            .join('\n');
+        return `\`\`\`screenplay\nevent ${event.name}\n${properties}\n\`\`\``;
+    }
+
+    // Sub-language keywords take precedence inside their construct.
+    const chain = enclosingChain(lines, fences, lineIndex, indentOf(line));
+    for (const construct of [line.trim().split(/\s+/)[0], ...chain]) {
+        const subLanguage = getSubLanguage(construct ?? '');
+        const doc = subLanguage?.hovers?.[word];
+        if (doc) return doc;
+    }
+
+    const keywordDoc = keywordDocs[word];
+    if (keywordDoc) return `**${word}** — ${keywordDoc}`;
+
+    return null;
+}

package/hover.ts

@@ -0,0 +1,23 @@
+// 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 { hoverContent } from './hover-content';
+
+export function createHoverProvider(): languages.HoverProvider {
+    return {
+        provideHover(model, position) {
+            const word = model.getWordAtPosition(position);
+            if (!word) return null;
+
+            const content = hoverContent(
+                model.getLinesContent(),
+                position.lineNumber - 1,
+                word.word,
+                word.startColumn,
+                word.endColumn,
+            );
+            return content ? { contents: [{ value: content }] } : null;
+        },
+    };
+}

package/index.ts

@@ -0,0 +1,98 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import {
+    Monaco,
+    languageConfiguration,
+    languageExtensionPoint,
+    languageId,
+} from './language';
+import { createTokensProvider } from './tokens';
+import { createCompletionProvider } from './completions';
+import { createHoverProvider } from './hover';
+import { attachDiagnostics } from './diagnostics';
+import {
+    getSubLanguage,
+    getSubLanguages,
+    onSubLanguagesChanged,
+    registerSubLanguage,
+} from './sub-language-registry';
+import { pdl } from './sub-languages/pdl';
+import { cdl } from './sub-languages/cdl';
+import { screenplayDark, screenplayDarkThemeName } from './themes/screenplay-dark';
+import { screenplayLight, screenplayLightThemeName } from './themes/screenplay-light';
+
+const registeredInstances = new Set<Monaco>();
+
+function applyTokensProvider(monaco: Monaco): void {
+    monaco.languages.setMonarchTokensProvider(languageId, createTokensProvider(getSubLanguages()));
+}
+
+// Sub-languages registered after register() recompose the tokenizer on the fly.
+onSubLanguagesChanged(() => registeredInstances.forEach(applyTokensProvider));
+
+// Registers the built-in PDL and CDL sub-languages. Hosts that do not go through
+// register() — such as the VSCode extension — call this before using the registry.
+export function ensureBuiltInSubLanguages(): void {
+    if (!getSubLanguage('projection')) registerSubLanguage('projection', pdl);
+    if (!getSubLanguage('capture')) registerSubLanguage('capture', cdl);
+}
+
+export function register(monaco: Monaco): void {
+    if (registeredInstances.has(monaco)) return;
+
+    ensureBuiltInSubLanguages();
+
+    registeredInstances.add(monaco);
+
+    monaco.languages.register(languageExtensionPoint);
+    monaco.languages.setLanguageConfiguration(languageId, languageConfiguration);
+    applyTokensProvider(monaco);
+    monaco.languages.registerCompletionItemProvider(languageId, createCompletionProvider(monaco));
+    monaco.languages.registerHoverProvider(languageId, createHoverProvider());
+    monaco.editor.defineTheme(screenplayDarkThemeName, screenplayDark);
+    monaco.editor.defineTheme(screenplayLightThemeName, screenplayLight);
+    attachDiagnostics(monaco);
+}
+
+export {
+    clauseKeywords,
+    codeBlockTags,
+    conceptAttributes,
+    constructKeywords,
+    languageId,
+    primitiveTypes,
+    sliceTypes,
+} from './language';
+export type { Monaco } from './language';
+export { getSubLanguage, getSubLanguages, registerSubLanguage } from './sub-language-registry';
+export type {
+    MonarchTokenRules,
+    SubLanguage,
+    SubLanguageCompletion,
+    SubLanguageDefinition,
+} from './sub-language-registry';
+export { pdl } from './sub-languages/pdl';
+export { cdl } from './sub-languages/cdl';
+export { screenplayDarkThemeName } from './themes/screenplay-dark';
+export { screenplayLightThemeName } from './themes/screenplay-light';
+export { enclosingChain, fenceMap, firstWord, indentOf } from './document-context';
+export { knownEventNames, scanDocument } from './symbols';
+export type {
+    ConceptSymbol,
+    DocumentSymbols,
+    EventSymbol,
+    ImportSymbol,
+    NamedSymbol,
+    PolicySymbol,
+    PropertySymbol,
+    QuerySymbol,
+} from './symbols';
+export { attributeDocs, contextVariableDocs, keywordDocs } from './keyword-docs';
+export { contextVariableItems, producesItems } from './completion-items';
+export type { CompletionEntry } from './completion-items';
+export { completionEntriesFor, planCompletions } from './completion-planner';
+export type { CompletionPlan } from './completion-planner';
+export { hoverContent } from './hover-content';
+export { validateLines } from './validation';
+export type { ValidationIssue, ValidationSeverity } from './validation';

package/keyword-docs.ts

@@ -0,0 +1,102 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+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.',
+    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.',
+    provider: 'A named identity provider within `authentication`, with free-form `name value` settings.',
+    description: 'A human-readable description of a module, feature, slice, persona, or command — the first body line, as a quoted single line or a fenced ``` block for multiple lines.',
+    module: 'The top-level namespace — maps to a bounded context.',
+    layout: 'A reusable screen template with named slots.',
+    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.',
+    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.',
+    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.',
+    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.',
+    validate: 'Declarative validation rules, or `validate csharp` for imperative rules — on commands and concepts.',
+    produces: 'Declares the events a command emits — single, multiple, or conditional.',
+    handler: 'A fully imperative command implementation — a `file <Path>` reference or an inline `csharp` block, instead of `produces`.',
+    when: 'Guards a produced event or a capture append with a condition.',
+    require: 'A policy condition: `authenticated`, `role "..."`, or `claim "..." matches ...`.',
+    authenticated: 'Requires an authenticated caller.',
+    role: 'Requires the caller to have the given role.',
+    claim: 'Requires a claim on the caller to match a subject or value.',
+    subject: 'The subject (identity) of the caller.',
+    data: 'Binds a read model to a screen through a query.',
+    action: 'Makes a command available as an action on a screen.',
+    navigate: 'Navigates to a screen, optionally passing a parameter with `by`.',
+    section: 'A named structural section of a screen.',
+    table: 'A table widget over a read model or child collection.',
+    summary: 'A summary widget showing labeled fields.',
+    column: 'A table column bound to a property.',
+    field: 'A summary field bound to a property.',
+    title: 'The display title of a screen or section.',
+    label: 'The display label of an action, column, or field.',
+    unique: 'A uniqueness constraint — `unique <property> on <EventType>` or `unique event <EventType>`.',
+    concurrency: 'The concurrency scope enforced when the command appends events — dimensions: `eventSource`, `sourceType`, `streamType`, `streamId`, `events`.',
+    eventSource: 'Concurrency dimension — scope the check to the event source id of the command.',
+    sourceType: 'Concurrency dimension — scope the check to an event source type.',
+    streamType: 'Concurrency dimension — scope the check to an event stream type.',
+    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.',
+    readmodel: 'Read model state in a specification — `given readmodel` establishes it, `then readmodel` asserts it.',
+    file: 'Delegates the implementation to an external file; the Screenplay contract stays visible.',
+    by: 'Introduces the identifying parameter.',
+    via: 'Connects screen data to the query that supplies it.',
+    filter: 'An optional query filter parameter.',
+    on: 'The event a reactor or constraint applies to, or a widget interaction such as `on row-click`.',
+    message: 'The validation message reported when the rule fails.',
+    matches: 'Matches a value against a regular expression or a named pattern such as `email`.',
+    all: 'Applies a comparison to every element of a collection.',
+    max: 'Maximum length or value.',
+    min: 'Minimum length or value.',
+    length: 'Constrains the exact length of a value.',
+    today: 'The current date.',
+    empty: 'Used with `not empty` — the value must be present.',
+    not: 'Negates a validation condition, as in `not empty`.',
+    and: 'Both conditions must hold.',
+    or: 'Either condition may hold.',
+    csharp: 'An inline C# block between triple backticks.',
+    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.',
+    StateChange: 'Slice type — a command → events flow; something that changes the system.',
+    StateView: 'Slice type — a query + projection + screen; something that reads the system.',
+    Automation: 'Slice type — a reactor or reducer; something that reacts to events.',
+    Translate: 'Slice type — a capture; converts external data into events.',
+    Uuid: 'Primitive type — a universally unique identifier.',
+    String: 'Primitive type — a string of characters.',
+    Int: 'Primitive type — an integer number.',
+    Decimal: 'Primitive type — a decimal number.',
+    Bool: 'Primitive type — true or false.',
+    Date: 'Primitive type — a date without time.',
+    DateTime: 'Primitive type — a date and time.',
+    Enum: 'An enumeration concept with a fixed set of values.',
+};
+
+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.',
+};
+
+export const contextVariableDocs: Record<string, string> = {
+    '$context.occurred': 'The timestamp of the event.',
+    '$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.',
+    '$strings': 'A localized string resolved from the `.strings` file of the active locale, e.g. `$strings.invoices.title`.',
+    '$eventContext.occurred': 'The timestamp of the event being projected.',
+};

package/language.ts

@@ -0,0 +1,130 @@
+// 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';
+
+export type Monaco = typeof import('monaco-editor');
+
+export const languageId = 'screenplay';
+
+export const languageExtensionPoint: languages.ILanguageExtensionPoint = {
+    id: languageId,
+    extensions: ['.play'],
+    aliases: ['Screenplay', 'screenplay', 'play'],
+    mimetypes: ['text/x-screenplay'],
+};
+
+export const constructKeywords = [
+    'domain',
+    'import',
+    'concept',
+    'policy',
+    'persona',
+    'authentication',
+    'module',
+    'layout',
+    'feature',
+    'slice',
+    'event',
+    'command',
+    'query',
+    'reactor',
+    'screen',
+    'constraint',
+    'specification',
+    'seed',
+];
+
+export const clauseKeywords = [
+    'description',
+    'template',
+    'require',
+    'authenticated',
+    'role',
+    'claim',
+    'subject',
+    'authorize',
+    'validate',
+    'produces',
+    'handler',
+    'when',
+    'given',
+    'then',
+    'error',
+    'message',
+    'not',
+    'empty',
+    'matches',
+    'all',
+    'max',
+    'min',
+    'length',
+    'today',
+    'true',
+    'false',
+    'and',
+    'or',
+    'by',
+    'filter',
+    'data',
+    'via',
+    'action',
+    'navigate',
+    'to',
+    'label',
+    'section',
+    'table',
+    'summary',
+    'title',
+    'column',
+    'field',
+    'on',
+    'unique',
+    'file',
+    'concurrency',
+    'eventSource',
+    'sourceType',
+    'streamType',
+    'streamId',
+    'tag',
+    'for',
+    'readmodel',
+    'provider',
+];
+
+export const codeBlockTags = ['csharp', 'typescript', 'react', 'html'];
+
+export const sliceTypes = ['StateChange', 'StateView', 'Automation', 'Translate'];
+
+export const primitiveTypes = ['Uuid', 'String', 'Int', 'Decimal', 'Bool', 'Date', 'DateTime'];
+
+export const conceptAttributes = ['@pii', '@sensitive'];
+
+export const languageConfiguration: languages.LanguageConfiguration = {
+    comments: {
+        lineComment: '//',
+    },
+    brackets: [
+        ['(', ')'],
+        ['[', ']'],
+    ],
+    autoClosingPairs: [
+        { open: '(', close: ')' },
+        { open: '[', close: ']' },
+        { open: '"', close: '"' },
+    ],
+    surroundingPairs: [
+        { open: '(', close: ')' },
+        { open: '[', close: ']' },
+        { open: '"', close: '"' },
+    ],
+    folding: {
+        offSide: true,
+    },
+    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.*$/,
+        // Dedents are always explicit in an offside language — never auto-dedent.
+        decreaseIndentPattern: /(?!)/,
+    },
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+    "name": "@cratis/screenplay-language",
+    "version": "0.1.0",
+    "description": "Monaco language service for the Cratis Screenplay DSL — syntax highlighting, IntelliSense, hover and diagnostics for .play files",
+    "license": "MIT",
+    "type": "module",
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "publishConfig": {
+        "access": "public"
+    },
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./capture": {
+            "types": "./dist/sub-languages/capture/index.d.ts",
+            "import": "./dist/sub-languages/capture/index.js"
+        },
+        "./projection": {
+            "types": "./dist/sub-languages/projection/index.d.ts",
+            "import": "./dist/sub-languages/projection/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "**/*.ts"
+    ],
+    "scripts": {
+        "build": "tsc -p tsconfig.json",
+        "compile": "tsc --noEmit -p tsconfig.json",
+        "lint": "yarn g:lint",
+        "lint:ci": "yarn g:lint:ci"
+    },
+    "peerDependencies": {
+        "monaco-editor": ">=0.44.0"
+    },
+    "devDependencies": {
+        "monaco-editor": "^0.55.1",
+        "typescript": "6.0.3"
+    }
+}