@reqlan/language 1.6.2 → 1.7.0

package/src/generated/module.ts

@@ -11,14 +11,14 @@ export const ReqlanLanguageMetaData = {
     languageId: 'reqlan',
     fileExtensions: ['.rq'],
     caseInsensitive: false,
-    mode: 'development'
+    mode: 'production'
 } as const satisfies LanguageMetaData;
 
 export const ReqlanCommentLanguageMetaData = {
     languageId: 'reqlan-comment',
     fileExtensions: [],
     caseInsensitive: false,
-    mode: 'development'
+    mode: 'production'
 } as const satisfies LanguageMetaData;
 
 export const ReqlanGeneratedSharedModule: Module<LangiumSharedCoreServices, LangiumGeneratedSharedCoreServices> = {

package/src/index.ts

@@ -1,4 +1,7 @@
 export * from './reqlan-module.js';
+export * from './reqlan-parse-budget.js';
+export { ReqlanAsyncParser, resolveParseWorkerPath } from './reqlan-async-parser.js';
+export { ReqlanLangiumDocumentFactory } from './reqlan-document-factory.js';
 export * from './reqlan-validator.js';
 export * from './reqlan-comment-resolver.js';
 export * from './reqlan-ignore-error.js';

package/src/reqlan-async-parser.ts

@@ -0,0 +1,178 @@
+/**
+ * Per-file parse budget via Langium's worker-thread async parser.
+ * Happy path is in-process sync parse; workers enforce a killable wall-clock budget
+ * for large files, sticky timeout escalation, or explicit force.
+ * rq:["../../../reqlan rq/language/parser_lexer.rq".parse_budget_timeout]
+ */
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+    type AstNode,
+    type LangiumCoreServices,
+    type LangiumParser
+} from 'langium';
+import { WorkerThreadAsyncParser } from 'langium/node';
+import {
+    CancellationToken,
+    CancellationTokenSource
+} from 'vscode-languageserver';
+import {
+    createIncompleteParseResult,
+    DEFAULT_PARSE_BUDGET_MS,
+    DEFAULT_WORKER_PARSE_THRESHOLD_CHARS,
+    type ParseWorkerMode,
+    type ReqlanParseResult,
+    shouldEscalateToParseWorker
+} from './reqlan-parse-budget.js';
+
+export interface ReqlanAsyncParserOptions {
+    timeoutMs?: number;
+    /** Override worker script path (tests). */
+    workerPath?: string;
+    /**
+     * `auto` (default): sync below size threshold; worker when escalated.
+     * `true` / `false`: always / never use workers.
+     */
+    useWorker?: ParseWorkerMode;
+    /** Characters at or above which `auto` mode uses a worker. */
+    workerThresholdChars?: number;
+    /** Worker pool size (Langium default is 8; keep small for startup). */
+    threadCount?: number;
+}
+
+export interface ReqlanParseCallOptions {
+    /** Force the killable worker path for this call (sticky URI escalate, tests). */
+    forceWorker?: boolean;
+}
+
+/**
+ * Directory of this module (or of the CJS bundle that inlined it).
+ * Avoid static `import.meta.url`: esbuild format cjs + target es2017 empties it
+ * (see reqlan rq/extension/startup-performance.rq invalid_url_activation_failure).
+ */
+declare const __dirname: string | undefined;
+
+function moduleDirectory(): string {
+    if (typeof __dirname === 'string') {
+        return __dirname;
+    }
+    // Native ESM only — hide from esbuild's empty-import-meta rewrite.
+    const metaUrl = (0, eval)('import.meta.url') as string;
+    return dirname(fileURLToPath(metaUrl));
+}
+
+export function resolveParseWorkerPath(explicit?: string): string {
+    if (explicit) {
+        return explicit;
+    }
+    const dir = moduleDirectory();
+    const jsPath = join(dir, 'reqlan-parse-worker.js');
+    if (existsSync(jsPath)) {
+        return jsPath;
+    }
+    const cjsPath = join(dir, 'reqlan-parse-worker.cjs');
+    if (existsSync(cjsPath)) {
+        return cjsPath;
+    }
+    return jsPath;
+}
+
+export class ReqlanAsyncParser extends WorkerThreadAsyncParser {
+    private readonly timeoutMs: number;
+    private readonly useWorker: ParseWorkerMode;
+    private readonly workerThresholdChars: number;
+    private readonly syncParser: LangiumParser;
+
+    constructor(services: LangiumCoreServices, options: ReqlanAsyncParserOptions = {}) {
+        super(services, () => resolveParseWorkerPath(options.workerPath));
+        this.syncParser = services.parser.LangiumParser;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_PARSE_BUDGET_MS;
+        this.useWorker = options.useWorker ?? 'auto';
+        this.workerThresholdChars = options.workerThresholdChars ?? DEFAULT_WORKER_PARSE_THRESHOLD_CHARS;
+        this.threadCount = options.threadCount ?? 2;
+        // Fail fast after cancel so the budget is close to timeoutMs wall-clock.
+        this.terminationDelay = 50;
+    }
+
+    override async parse<T extends AstNode>(
+        text: string,
+        cancelToken: CancellationToken,
+        callOptions: ReqlanParseCallOptions = {}
+    ): Promise<ReqlanParseResult<T>> {
+        if (cancelToken.isCancellationRequested) {
+            return createIncompleteParseResult<T>(this.syncParser, {
+                reason: 'failure',
+                cause: 'cancelled'
+            });
+        }
+
+        const escalate = shouldEscalateToParseWorker(text, {
+            useWorker: this.useWorker,
+            forceWorker: callOptions.forceWorker,
+            thresholdChars: this.workerThresholdChars
+        });
+        if (!escalate) {
+            return this.parseOnThread<T>(text);
+        }
+
+        return this.parseInWorker<T>(text, cancelToken);
+    }
+
+    /** Sync entry used by document factory / tests. */
+    parseSync<T extends AstNode>(text: string): ReqlanParseResult<T> {
+        return this.parseOnThread<T>(text);
+    }
+
+    private async parseInWorker<T extends AstNode>(
+        text: string,
+        cancelToken: CancellationToken
+    ): Promise<ReqlanParseResult<T>> {
+        const timeoutSource = new CancellationTokenSource();
+        const timer = setTimeout(() => timeoutSource.cancel(), this.timeoutMs);
+        const callerCancel = cancelToken.onCancellationRequested(() => {
+            timeoutSource.cancel();
+        });
+
+        try {
+            return await super.parse<T>(text, timeoutSource.token) as ReqlanParseResult<T>;
+        } catch (error) {
+            if (timeoutSource.token.isCancellationRequested) {
+                if (cancelToken.isCancellationRequested) {
+                    return createIncompleteParseResult<T>(this.syncParser, {
+                        reason: 'failure',
+                        cause: 'cancelled'
+                    });
+                }
+                return createIncompleteParseResult<T>(this.syncParser, {
+                    reason: 'timeout',
+                    timeoutMs: this.timeoutMs
+                });
+            }
+            return createIncompleteParseResult<T>(this.syncParser, {
+                reason: 'failure',
+                cause: error instanceof Error ? error.message : String(error)
+            });
+        } finally {
+            clearTimeout(timer);
+            callerCancel.dispose();
+            timeoutSource.dispose();
+        }
+    }
+
+    private parseOnThread<T extends AstNode>(text: string): ReqlanParseResult<T> {
+        try {
+            return this.syncParser.parse(text) as ReqlanParseResult<T>;
+        } catch (error) {
+            return createIncompleteParseResult<T>(this.syncParser, {
+                reason: 'failure',
+                cause: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+
+    /** Exposed for tests that need the underlying sync parser. */
+    get langiumParser(): LangiumParser {
+        return this.syncParser;
+    }
+}

package/src/reqlan-completion-provider.ts

@@ -124,7 +124,7 @@ export class ReqlanCompletionProvider extends DefaultCompletionProvider {
                 return [];
             }
             return model.elements
-                .filter(element => {
+                .filter((element): element is typeof element & { name: string } => {
                     if (refInfo.property === 'ideaset') {
                         return isIdeaSet(element);
                     }

package/src/reqlan-document-factory.ts

@@ -0,0 +1,75 @@
+/**
+ * Document factory that never lets a sync lex/parse throw escape into workspace init.
+ * Async path uses [ReqlanAsyncParser]: sync fast path by default, killable worker when escalated.
+ * rq:["../../../reqlan rq/language/parser_lexer.rq".parse_budget_timeout]
+ */
+import {
+    DefaultLangiumDocumentFactory,
+    type AstNode,
+    type LangiumDocument,
+    type LangiumSharedCoreServices,
+    type ParseResult,
+    type ParserOptions,
+    URI
+} from 'langium';
+import type { CancellationToken } from 'vscode-languageserver';
+import { CancellationToken as CancelToken } from 'vscode-languageserver';
+import { ReqlanAsyncParser } from './reqlan-async-parser.js';
+import {
+    createIncompleteParseResult,
+    type ReqlanParseResult
+} from './reqlan-parse-budget.js';
+
+export class ReqlanLangiumDocumentFactory extends DefaultLangiumDocumentFactory {
+    /** URIs that previously hit the parse budget — keep using a killable worker. */
+    private readonly workerEscalateUris = new Set<string>();
+
+    constructor(services: LangiumSharedCoreServices) {
+        super(services);
+    }
+
+    protected override parse<T extends AstNode>(
+        uri: URI,
+        text: string,
+        options?: ParserOptions
+    ): ParseResult<T> {
+        const services = this.serviceRegistry.getServices(uri);
+        try {
+            return services.parser.LangiumParser.parse(text, options);
+        } catch (error) {
+            return createIncompleteParseResult<T>(services.parser.LangiumParser, {
+                reason: 'failure',
+                cause: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+
+    protected override async parseAsync<T extends AstNode>(
+        uri: URI,
+        text: string,
+        cancellationToken: CancellationToken = CancelToken.None
+    ): Promise<ParseResult<T>> {
+        const services = this.serviceRegistry.getServices(uri);
+        const asyncParser = services.parser.AsyncParser;
+        const uriKey = uri.toString();
+        const forceWorker = this.workerEscalateUris.has(uriKey);
+
+        const result = asyncParser instanceof ReqlanAsyncParser
+            ? await asyncParser.parse<T>(text, cancellationToken, { forceWorker })
+            : await asyncParser.parse<T>(text, cancellationToken);
+
+        const reqlanResult = result as ReqlanParseResult<T>;
+        if (reqlanResult.reqlanIncomplete?.reason === 'timeout') {
+            this.workerEscalateUris.add(uriKey);
+        } else if (!reqlanResult.reqlanIncomplete) {
+            this.workerEscalateUris.delete(uriKey);
+        }
+
+        return result;
+    }
+
+    /** Test helper: expose incomplete marker after async parse. */
+    static isIncompleteDocument(document: LangiumDocument): boolean {
+        return Boolean((document.parseResult as ReqlanParseResult).reqlanIncomplete);
+    }
+}

package/src/reqlan-linker.ts

@@ -5,7 +5,7 @@
  */
 import type { AstNode, FileSystemProvider, LangiumDocument, LangiumDocuments, ReferenceInfo } from 'langium';
 import { AstUtils, DefaultLinker, type DefaultReference } from 'langium';
-import { isLocalReference, isModel, isQualifiedReference } from './generated/ast.js';
+import { isIdea, isIdeaSet, isLocalReference, isModel, isOneLinerIdea, isQualifiedReference } from './generated/ast.js';
 import { isOpaqueFileReferencePath } from './reqlan-file-references.js';
 import { findNamespaceImportByAlias } from './reqlan-import-bindings.js';
 import { isResolvableImportPath } from './reqlan-imports.js';
@@ -69,7 +69,9 @@ export class ReqlanLinker extends DefaultLinker {
             return false;
         }
         const name = refInfo.reference.$refText;
-        if (model.elements.some(element => element.name === name)) {
+        if (model.elements.some(element =>
+            (isIdea(element) || isOneLinerIdea(element) || isIdeaSet(element)) && element.name === name
+        )) {
             return false;
         }
         return findNamespaceImportByAlias(model.imports, name) !== undefined;

package/src/reqlan-module.ts

@@ -1,4 +1,4 @@
-import { type Module, inject } from 'langium';
+import { type Module, inject, type PartialLangiumSharedCoreServices } from 'langium';
 import { createDefaultModule, createDefaultSharedModule, type DefaultSharedModuleContext, type LangiumServices, type LangiumSharedServices, type PartialLangiumServices } from 'langium/lsp';
 import { ReqlanGeneratedModule, ReqlanGeneratedSharedModule } from './generated/module.js';
 import { ReqlanDefinitionProvider } from './reqlan-definition-provider.js';
@@ -18,6 +18,9 @@ import { ReqlanSemanticTokenProvider } from './reqlan-semantic-token-provider.js
 import { ReqlanTokenBuilder } from './reqlan-token-builder.js';
 import { registerRqIgnoreErrorFiltering } from './reqlan-ignore-error.js';
 import { ReqlanValidator, registerValidationChecks } from './reqlan-validator.js';
+import { ReqlanWorkspaceManager } from './reqlan-workspace-manager.js';
+import { ReqlanAsyncParser } from './reqlan-async-parser.js';
+import { ReqlanLangiumDocumentFactory } from './reqlan-document-factory.js';
 
 /**
  * Declaration of custom services - add your own service classes here.
@@ -39,6 +42,13 @@ export type ReqlanServices = LangiumServices & ReqlanAddedServices
  * declared custom services. The Langium defaults can be partially specified to override only
  * selected services, while the custom services must be fully specified.
  */
+export const ReqlanSharedModule: Module<LangiumSharedServices, PartialLangiumSharedCoreServices> = {
+    workspace: {
+        WorkspaceManager: services => new ReqlanWorkspaceManager(services),
+        LangiumDocumentFactory: services => new ReqlanLangiumDocumentFactory(services)
+    }
+};
+
 export const ReqlanModule: Module<ReqlanServices, PartialLangiumServices & ReqlanAddedServices> = {
     validation: {
         ReqlanValidator: services => new ReqlanValidator(services)
@@ -51,7 +61,8 @@ export const ReqlanModule: Module<ReqlanServices, PartialLangiumServices & Reqla
     },
     parser: {
         GrammarConfig: createReqlanGrammarConfig,
-        TokenBuilder: () => new ReqlanTokenBuilder()
+        TokenBuilder: () => new ReqlanTokenBuilder(),
+        AsyncParser: (services: ReqlanServices) => new ReqlanAsyncParser(services)
     },
     lsp: {
         DefinitionProvider: services => new ReqlanDefinitionProvider(services),
@@ -87,7 +98,8 @@ export function createReqlanServices(context: DefaultSharedModuleContext): {
 } {
     const shared = inject(
         createDefaultSharedModule(context),
-        ReqlanGeneratedSharedModule
+        ReqlanGeneratedSharedModule,
+        ReqlanSharedModule
     );
     const Reqlan = inject(
         createDefaultModule({ shared }),

package/src/reqlan-parse-budget.ts

@@ -0,0 +1,155 @@
+/**
+ * Per-file parse/lex budget: if a document cannot finish within the budget,
+ * return an empty model plus warning + error diagnostics instead of hanging the host.
+ * rq:["../../../reqlan rq/language/parser_lexer.rq".parse_budget_timeout]
+ */
+import type { AstNode, LangiumParser, ParseResult } from 'langium';
+
+/** Default wall-clock budget for lex+parse of one file (worker-enforced). */
+export const DEFAULT_PARSE_BUDGET_MS = 8_000;
+
+/**
+ * Prefer in-process sync parse below this size. Worker threads (killable budget)
+ * are reserved for larger inputs, hang-sentinel tests, sticky timeout escalation,
+ * or an explicit force.
+ */
+export const DEFAULT_WORKER_PARSE_THRESHOLD_CHARS = 64_000;
+
+/** Test-only sentinel: a worker that sees this marker hangs until terminated. */
+export const PARSE_HANG_SENTINEL = '__REQLAN_PARSE_HANG__';
+
+export const PARSE_TIMEOUT_WARNING =
+    'Parse budget exceeded for this file; semantic features may be incomplete until the file is simplified or the budget is raised.';
+
+export function parseTimeoutErrorMessage(timeoutMs: number): string {
+    return `Failed to lex/parse this file within ${timeoutMs}ms; left unloaded so the rest of the workspace can continue.`;
+}
+
+export function parseFailureErrorMessage(cause: string): string {
+    return `Lex/parse aborted for this file (${cause}); left unloaded so the rest of the workspace can continue.`;
+}
+
+export type ParseWorkerMode = boolean | 'auto';
+
+export interface ParseWorkerEscalationOptions {
+    /** `auto` (default): sync below threshold; worker for large / sentinel / force. */
+    useWorker?: ParseWorkerMode;
+    forceWorker?: boolean;
+    thresholdChars?: number;
+}
+
+/** Whether this parse should run in a killable worker thread. */
+export function shouldEscalateToParseWorker(
+    text: string,
+    options: ParseWorkerEscalationOptions = {}
+): boolean {
+    const mode = options.useWorker ?? 'auto';
+    if (mode === false) {
+        return false;
+    }
+    if (mode === true || options.forceWorker) {
+        return true;
+    }
+    if (text.includes(PARSE_HANG_SENTINEL)) {
+        return true;
+    }
+    const threshold = options.thresholdChars ?? DEFAULT_WORKER_PARSE_THRESHOLD_CHARS;
+    return text.length >= threshold;
+}
+
+/** Lexer error plus optional severity used for budget-timeout warnings. */
+export type ReqlanLexerError = ParseResult['lexerErrors'][number] & {
+    severity?: 'warning' | 'error' | 'info' | 'hint';
+};
+
+export interface ReqlanParseResult<T extends AstNode = AstNode> extends Omit<ParseResult<T>, 'lexerErrors'> {
+    lexerErrors: ReqlanLexerError[];
+    /** Set when lex/parse did not complete successfully within budget (timeout or crash). */
+    reqlanIncomplete?: {
+        reason: 'timeout' | 'failure';
+        timeoutMs?: number;
+        cause?: string;
+    };
+}
+
+export function isReqlanIncompleteParseResult(
+    result: ParseResult
+): result is ReqlanParseResult {
+    return Boolean((result as ReqlanParseResult).reqlanIncomplete);
+}
+
+interface PlaceholderToken {
+    image: string;
+    startOffset: number;
+    endOffset: number;
+    startLine: number;
+    endLine: number;
+    startColumn: number;
+    endColumn: number;
+    tokenTypeIdx: number;
+    tokenType: { name: string };
+}
+
+function placeholderToken(): PlaceholderToken {
+    return {
+        image: '',
+        startOffset: Number.NaN,
+        endOffset: Number.NaN,
+        startLine: Number.NaN,
+        endLine: Number.NaN,
+        startColumn: Number.NaN,
+        endColumn: Number.NaN,
+        tokenTypeIdx: -1,
+        tokenType: { name: 'EOF' }
+    };
+}
+
+function timeoutParserError(message: string) {
+    return {
+        name: 'ReqlanParseTimeout',
+        message,
+        token: placeholderToken(),
+        resyncedTokens: [],
+        context: {
+            ruleStack: [],
+            ruleOccurrenceStack: []
+        }
+    };
+}
+
+function timeoutLexerWarning(message: string): ReqlanLexerError {
+    return {
+        offset: 0,
+        line: 1,
+        column: 1,
+        length: 1,
+        message,
+        severity: 'warning'
+    };
+}
+
+/**
+ * Empty model with a lexer warning and a parser error so the editor shows both severities.
+ */
+export function createIncompleteParseResult<T extends AstNode>(
+    parser: LangiumParser,
+    options: {
+        reason: 'timeout' | 'failure';
+        timeoutMs?: number;
+        cause?: string;
+    }
+): ReqlanParseResult<T> {
+    const empty = parser.parse('') as ReqlanParseResult<T>;
+    const errorMessage = options.reason === 'timeout'
+        ? parseTimeoutErrorMessage(options.timeoutMs ?? DEFAULT_PARSE_BUDGET_MS)
+        : parseFailureErrorMessage(options.cause ?? 'unexpected error');
+    // Casts: Chevrotain exception shapes are structural; Langium only needs message + token positions.
+    empty.parserErrors = [timeoutParserError(errorMessage) as ReqlanParseResult<T>['parserErrors'][number]];
+    empty.lexerErrors = [timeoutLexerWarning(PARSE_TIMEOUT_WARNING)];
+    empty.reqlanIncomplete = {
+        reason: options.reason,
+        timeoutMs: options.timeoutMs,
+        cause: options.cause
+    };
+    return empty;
+}

package/src/reqlan-parse-worker.ts

@@ -0,0 +1,35 @@
+/**
+ * Langium worker-thread parse entry: sync lex/parse, dehydrate, postMessage.
+ * The parent enforces the wall-clock budget via worker.terminate().
+ * rq:["../../../reqlan rq/language/parser_lexer.rq".parse_budget_timeout]
+ */
+import { parentPort } from 'node:worker_threads';
+import { EmptyFileSystem } from 'langium';
+import { createReqlanServices } from './reqlan-module.js';
+import { PARSE_HANG_SENTINEL } from './reqlan-parse-budget.js';
+
+if (!parentPort) {
+    throw new Error('reqlan-parse-worker must run as a worker thread');
+}
+
+const { Reqlan } = createReqlanServices(EmptyFileSystem);
+const parser = Reqlan.parser.LangiumParser;
+const hydrator = Reqlan.serializer.Hydrator;
+
+parentPort.on('message', (text: unknown) => {
+    const input = typeof text === 'string' ? text : '';
+    if (input.includes(PARSE_HANG_SENTINEL)) {
+        // Intentional hang for tests — parent terminates on budget expiry.
+        for (;;) {
+            /* spin */
+        }
+    }
+    try {
+        const result = parser.parse(input);
+        parentPort!.postMessage(hydrator.dehydrate(result));
+    } catch (error) {
+        // Surface as worker 'error' so ParserWorker rejects instead of hydrating garbage.
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`reqlan parse worker failed: ${message}`);
+    }
+});