@cratis/screenplay-language 4.1.0 → 4.2.1

package/file-references.ts

@@ -0,0 +1,87 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { fenceMap, firstWord, indentOf } from './document-context';
+
+// The keyword the directive opens with — the single word the language points at a file with.
+export const fileReferenceKeyword = 'file';
+
+// A `file <path>` directive, with the path exactly as written and the span it occupies on its line.
+// The span is measured against the raw line, and its columns are one-based like every other position
+// this package reports, so an editor places a range on it the same way it does a validation issue.
+export interface FileReference {
+    path: string;
+    line: number;
+    startColumn: number;
+    endColumn: number;
+}
+
+// `file String` is a property named `file`; `file Invoices/Register.cs` is the directive. The two are
+// told apart by shape, the way the compiler tells them apart: a type reference is a bare identifier,
+// so anything carrying a separator or an extension is a path and nothing else. The property wins the
+// tie, because a document that used the name before the directive existed keeps meaning what it meant.
+const typeReferencePattern = /^[A-Za-z_]\w*(?:\[\])?\??$/;
+
+// A path naming a place on one machine rather than a place in the repository. The compiler warns about
+// these; nothing here rejects one, so a resolver can still probe it and come up empty on other machines.
+const absolutePathPattern = /^(?:[/\\]|[A-Za-z]:[/\\]|~[/\\])/;
+
+export function isAbsoluteFileReferencePath(path: string): boolean {
+    return absolutePathPattern.test(path);
+}
+
+// Drops a trailing `//` comment without cutting into a string or a template, mirroring how the
+// compiler strips one before it reads the line.
+function withoutComment(text: string): string {
+    let inString = false;
+    let inTemplate = false;
+
+    for (let index = 0; index < text.length; index++) {
+        const current = text[index];
+        if (current === '\\' && inString && index + 1 < text.length) {
+            index++;
+        } else if (current === '"' && !inTemplate) {
+            inString = !inString;
+        } else if (current === '`' && !inString) {
+            inTemplate = !inTemplate;
+        } else if (!inString && !inTemplate && current === '/' && text[index + 1] === '/') {
+            return text.slice(0, index);
+        }
+    }
+
+    return text;
+}
+
+// The `file` directive on a single line, or undefined when the line is not one. Callers that scan a
+// whole document go through fileReferences instead, so code fences are accounted for.
+export function fileReferenceOn(line: string, lineIndex: number): FileReference | undefined {
+    const indent = indentOf(line);
+    const content = withoutComment(line.slice(indent)).trimEnd();
+    if (firstWord(content) !== fileReferenceKeyword) return undefined;
+
+    const afterKeyword = content.slice(fileReferenceKeyword.length);
+    const path = afterKeyword.trim();
+
+    // A bare `file` leaves the word available as a name to whatever the enclosing block reads a bare
+    // word as, and a bare identifier after it is a property type rather than a path.
+    if (path.length === 0 || typeReferencePattern.test(path)) return undefined;
+
+    const separatorLength = afterKeyword.length - afterKeyword.trimStart().length;
+    const startColumn = indent + fileReferenceKeyword.length + separatorLength + 1;
+    return { path, line: lineIndex, startColumn, endColumn: startColumn + path.length };
+}
+
+// Every `file` directive in a document, in document order. Lines inside a code fence are skipped, so
+// a `file` line in an inline C# or TypeScript block is never mistaken for one of ours.
+export function fileReferences(lines: string[]): FileReference[] {
+    const fences = fenceMap(lines);
+    const references: FileReference[] = [];
+
+    for (let index = 0; index < lines.length; index++) {
+        if (fences[index]) continue;
+        const reference = fileReferenceOn(lines[index], index);
+        if (reference) references.push(reference);
+    }
+
+    return references;
+}

package/for_fileReferences/when_recognizing_an_absolute_path/with_paths_of_every_shape.ts

@@ -0,0 +1,26 @@
+// 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 } from 'vitest';
+import { isAbsoluteFileReferencePath } from '../../file-references';
+
+// A reference is relative to the repository root, so it means the same thing on every machine. An
+// absolute one names a place on one machine and is wrong without looking anything up.
+describe('when recognizing an absolute path', () => {
+    it('should recognize a posix path', () => {
+        isAbsoluteFileReferencePath('/Users/someone/Invoices/Register.cs').should.be.true;
+    });
+
+    it('should recognize a windows path', () => {
+        isAbsoluteFileReferencePath('C:/repos/Invoices/Register.cs').should.be.true;
+        isAbsoluteFileReferencePath('C:\\repos\\Invoices\\Register.cs').should.be.true;
+    });
+
+    it('should recognize a home-relative path', () => {
+        isAbsoluteFileReferencePath('~/repos/Invoices/Register.cs').should.be.true;
+    });
+
+    it('should not recognize a repository-relative path', () => {
+        isAbsoluteFileReferencePath('Invoices/Register.cs').should.be.false;
+    });
+});

package/for_fileReferences/when_scanning_a_document/inside_a_code_fence.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, beforeEach, it } from 'vitest';
+import { FileReference, fileReferences } from '../../file-references';
+
+// An inline C# block may well contain the word `file` at the start of a line — it is a C# modifier —
+// and none of it is Screenplay.
+describe('when scanning a document with a file line inside a code fence', () => {
+    let result: FileReference[];
+
+    beforeEach(() => {
+        result = fileReferences([
+            'handler',
+            '    ```',
+            '    file static class Helpers/NotAPath.cs',
+            '    ```',
+            '    file Handlers/Real.cs',
+        ]);
+    });
+
+    it('should find only the reference outside the fence', () => {
+        result.should.have.lengthOf(1);
+        result[0].path.should.equal('Handlers/Real.cs');
+    });
+});

package/for_fileReferences/when_scanning_a_document/with_a_bare_file_keyword.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, beforeEach, it } from 'vitest';
+import { FileReference, fileReferences } from '../../file-references';
+
+// A bare `file` carries no path, so it leaves the word available as a name to whatever the enclosing
+// block reads a bare word as.
+describe('when scanning a document with a bare file keyword', () => {
+    let result: FileReference[];
+
+    beforeEach(() => {
+        result = fileReferences(['reaction', '    file', '    file   ', 'filename Something.cs']);
+    });
+
+    it('should find no reference', () => {
+        result.should.be.empty;
+    });
+});

package/for_fileReferences/when_scanning_a_document/with_a_file_directive.ts

@@ -0,0 +1,30 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, beforeEach, it } from 'vitest';
+import { FileReference, fileReferences } from '../../file-references';
+
+describe('when scanning a document with a file directive', () => {
+    let result: FileReference[];
+
+    beforeEach(() => {
+        result = fileReferences(['command RegisterInvoice', '    handler', '        file Handlers/RegisterInvoice.cs']);
+    });
+
+    it('should find the reference', () => {
+        result.should.have.lengthOf(1);
+    });
+
+    it('should carry the declared path verbatim', () => {
+        result[0].path.should.equal('Handlers/RegisterInvoice.cs');
+    });
+
+    it('should report the line it sits on', () => {
+        result[0].line.should.equal(2);
+    });
+
+    it('should span the path and not the keyword', () => {
+        result[0].startColumn.should.equal(14);
+        result[0].endColumn.should.equal(14 + 'Handlers/RegisterInvoice.cs'.length);
+    });
+});

package/for_fileReferences/when_scanning_a_document/with_a_property_named_file.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, beforeEach, it } from 'vitest';
+import { FileReference, fileReferences } from '../../file-references';
+
+// `file String` declares a property called `file`; only a path is the directive. The two are told
+// apart by shape, and the property has to keep winning the tie.
+describe('when scanning a document with a property named file', () => {
+    let result: FileReference[];
+
+    beforeEach(() => {
+        result = fileReferences([
+            'type Attachment',
+            '    file String',
+            '    name String',
+            '    thumbnails String[]',
+            '    caption String?',
+        ]);
+    });
+
+    it('should find no reference', () => {
+        result.should.be.empty;
+    });
+});

package/for_fileReferences/when_scanning_a_document/with_a_trailing_comment.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, beforeEach, it } from 'vitest';
+import { FileReference, fileReferences } from '../../file-references';
+
+describe('when scanning a document with a trailing comment after a file directive', () => {
+    let result: FileReference[];
+
+    beforeEach(() => {
+        result = fileReferences(['    file Screens/InvoiceLineReport.tsx  // generated by Arc']);
+    });
+
+    it('should find the reference', () => {
+        result.should.have.lengthOf(1);
+    });
+
+    it('should leave the comment out of the path', () => {
+        result[0].path.should.equal('Screens/InvoiceLineReport.tsx');
+    });
+
+    it('should span only the path', () => {
+        result[0].endColumn.should.equal(result[0].startColumn + 'Screens/InvoiceLineReport.tsx'.length);
+    });
+});

package/for_fileReferences/when_scanning_a_document/with_directives_on_several_constructs.ts

@@ -0,0 +1,41 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, beforeEach, it } from 'vitest';
+import { FileReference, fileReferences } from '../../file-references';
+
+// The shape a captured application actually has — the directive appears under validation rules,
+// constraints, handlers, screens, performers and reactions alike, at whatever depth they sit.
+describe('when scanning a document with directives on several constructs', () => {
+    let result: FileReference[];
+
+    beforeEach(() => {
+        result = fileReferences([
+            'rule BeUnusedInvoiceNumber',
+            '            file Validations/BeUnusedInvoiceNumber.cs',
+            'constraint InvoiceStatusTransition',
+            '        file Constraints/InvoiceStatusTransitionConstraint.cs',
+            'screen InvoiceLineReport',
+            '        file Screens/InvoiceLineReport.tsx',
+            'performer',
+            '          file Queries/InvoiceSummaryPerformer.cs',
+        ]);
+    });
+
+    it('should find every reference', () => {
+        result.should.have.lengthOf(4);
+    });
+
+    it('should find them in document order', () => {
+        result.map((reference) => reference.path).should.deep.equal([
+            'Validations/BeUnusedInvoiceNumber.cs',
+            'Constraints/InvoiceStatusTransitionConstraint.cs',
+            'Screens/InvoiceLineReport.tsx',
+            'Queries/InvoiceSummaryPerformer.cs',
+        ]);
+    });
+
+    it('should report the line each one sits on', () => {
+        result.map((reference) => reference.line).should.deep.equal([1, 3, 5, 7]);
+    });
+});

package/for_scanDocument/when_scanning_a_query/with_a_dotted_return_type.ts

@@ -0,0 +1,34 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, beforeEach, it } from 'vitest';
+import { DocumentSymbols, scanDocument } from '../../symbols';
+
+// The compiler takes a dotted return type - QueryParser's ([\w.]+(?:\[\])?\??) - so the editor has to
+// as well. When it did not, the query never made it into the symbol table and every check and
+// completion reading from it went silently missing.
+describe('when scanning a query with a dotted return type', () => {
+    let symbols: DocumentSymbols;
+
+    beforeEach(() => {
+        symbols = scanDocument([
+            'module Invoicing',
+            '  feature Invoices',
+            '    slice StateView Overdue',
+            '      query Overdue => Invoicing.OverdueReadModel[]',
+            '        by invoiceId InvoiceId',
+        ]);
+    });
+
+    it('should register the query', () => {
+        symbols.queries.should.have.lengthOf(1);
+    });
+
+    it('should carry the return type as written', () => {
+        symbols.queries[0].returnType.should.equal('Invoicing.OverdueReadModel[]');
+    });
+
+    it('should collect the parameters it declares', () => {
+        symbols.queries[0].parameters.should.have.lengthOf(1);
+    });
+});

package/for_validateLines/when_validating_a_document/with_a_problem_of_every_coded_kind.ts

@@ -0,0 +1,52 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, beforeEach, it } from 'vitest';
+import { diagnosticCodes } from '../../diagnostic-codes';
+import { ValidationIssue, validateLines } from '../../validation';
+
+// One document holding every condition the editor and the compiler both check, so a condition added
+// later without a code fails here rather than reaching a user as a codeless squiggle.
+const document = [
+    'concept InvoiceId : Guid',
+    'concept InvoiceId : String',
+    'concept Amount : Wat',
+    '',
+    'module Invoicing',
+    '  feature Invoices',
+    '    slice Wat Register',
+    '      event InvoiceRegistered',
+    '        invoiceId InvoiceId',
+    '\t        amount Amount',
+    '      command RegisterInvoice',
+    '        invoiceId InvoiceId identifier',
+    '        amount Amount identifier',
+    '        reference Unknown',
+    '        authorize CanRegister',
+    '        produces InvoiceArchived',
+    '          registeredBy = $context.wat',
+    '          causedBy = $context.causedBy.wat',
+    '          department = $context.identity.wat',
+    '      query Overdue => OverdueReadModel[]',
+    '        performer',
+    '          csharp',
+    '            ```',
+    '            return readModels;',
+];
+
+describe('when validating a document with a problem of every coded kind', () => {
+    let issues: ValidationIssue[];
+
+    beforeEach(() => {
+        issues = validateLines(document);
+    });
+
+    it('should give every issue it reports a code', () => {
+        issues.filter((issue) => !issue.code).should.be.empty;
+    });
+
+    it('should report each condition with the code the compiler reports it with', () => {
+        const reported = new Set(issues.map((issue) => issue.code));
+        [...Object.values(diagnosticCodes)].forEach((code) => reported.has(code).should.be.true);
+    });
+});

package/for_validateLines/when_validating_a_document/with_an_unknown_policy.ts

@@ -0,0 +1,33 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, beforeEach, it } from 'vitest';
+import { diagnosticCodes } from '../../diagnostic-codes';
+import { ValidationIssue, validateLines } from '../../validation';
+
+describe('when validating a document with an unknown policy', () => {
+    let issues: ValidationIssue[];
+
+    beforeEach(() => {
+        issues = validateLines([
+            'module Invoicing',
+            '  feature Invoices',
+            '    slice StateView Overdue',
+            '      query Overdue => OverdueReadModel[]',
+            '        authorize CanRead',
+            '          or CanAlsoRead',
+        ]);
+    });
+
+    it('should report the policy named on the authorize line', () => {
+        issues[0].should.include({ line: 4, code: diagnosticCodes.unknownPolicy });
+    });
+
+    it('should report the policy continued on the line below it', () => {
+        issues[1].should.include({ line: 5, code: diagnosticCodes.unknownPolicy });
+    });
+
+    it('should report nothing else', () => {
+        issues.should.have.lengthOf(2);
+    });
+});

package/index.ts

@@ -79,6 +79,13 @@ 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 {
+    fileReferenceKeyword,
+    fileReferenceOn,
+    fileReferences,
+    isAbsoluteFileReferencePath,
+} from './file-references';
+export type { FileReference } from './file-references';
 export { builtInTriggerNames, knownEventNames, knownTriggerNames, knownTypeNames, scanDocument } from './symbols';
 export type {
     CommandSymbol,
@@ -100,3 +107,5 @@ export type { CompletionPlan } from './completion-planner';
 export { hoverContent } from './hover-content';
 export { validateLines } from './validation';
 export type { ValidationIssue, ValidationSeverity } from './validation';
+export { diagnosticCodes } from './diagnostic-codes';
+export type { DiagnosticCode } from './diagnostic-codes';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/screenplay-language",
-    "version": "4.1.0",
+    "version": "4.2.1",
     "description": "Monaco language service for the Cratis Screenplay DSL — syntax highlighting, IntelliSense, hover and diagnostics for .play files",
     "license": "MIT",
     "repository": {
@@ -33,16 +33,20 @@
         "**/*.ts"
     ],
     "scripts": {
-        "build": "tsc -p tsconfig.json",
+        "build": "tsc -p tsconfig.build.json",
         "compile": "tsc --noEmit -p tsconfig.json",
         "lint": "yarn g:lint",
-        "lint:ci": "yarn g:lint:ci"
+        "lint:ci": "yarn g:lint:ci",
+        "test": "vitest run"
     },
     "peerDependencies": {
         "monaco-editor": ">=0.44.0"
     },
     "devDependencies": {
+        "@types/chai": "^5.2.3",
+        "chai": "^6.2.2",
         "monaco-editor": "^0.55.1",
-        "typescript": "6.0.3"
+        "typescript": "6.0.3",
+        "vitest": "^4.1.11"
     }
 }

package/symbols.ts

@@ -194,7 +194,11 @@ export function scanDocument(lines: string[]): DocumentSymbols {
             continue;
         }
 
-        const queryMatch = trimmed.match(/^query\s+(\w+)\s*=>\s*(?:observable\s+)?([\w[\]?]+)\s*$/);
+        // The return type shape is the compiler's, dots and all - QueryParser's
+        // ^query\s+([A-Za-z_]\w*)\s*=>\s*(observable\s+)?([\w.]+(?:\[\])?\??)$. A narrower one here
+        // silently drops the query from the symbol table, and with it every check and completion that
+        // reads from it.
+        const queryMatch = trimmed.match(/^query\s+(\w+)\s*=>\s*(?:observable\s+)?([\w.]+(?:\[\])?\??)\s*$/);
         if (queryMatch) {
             // The return type names a read model, which no construct declares — only the
             // 'by' and 'filter' parameters resolve against the document's own types.