@reqlan/language 1.4.0

package/src/reqlan-file-link-resolver.ts

@@ -0,0 +1,485 @@
+/**
+ * Resolves file references and import paths to target URIs and editor ranges.
+ */
+import type { CstNode, FileSystemProvider, LangiumDocument, LangiumDocuments, URI } from 'langium';
+import { AstUtils, CstUtils, GrammarUtils } from 'langium';
+import type { Range } from 'vscode-languageserver';
+import { resolveFileUri } from './reqlan-comment-resolver.js';
+import type { EmbeddedFileReference } from './reqlan-embedded-file-references.js';
+import { findEmbeddedFileReferencesInText } from './reqlan-embedded-file-references.js';
+import { findImportedDocument, resolveExistingImportUri } from './reqlan-imports.js';
+import type { PathResolveContext } from './reqlan-path-resolve.js';
+import { qualifiedReferenceImportPath } from './reqlan-references.js';
+import {
+    findTestLineInText,
+    parseFileReferenceString,
+    type ParsedFileReference
+} from './reqlan-file-references.js';
+import {
+    isFileReference,
+    isFileSymbolReference,
+    isImport,
+    isLocalReference,
+    isMarkdownLink,
+    isQualifiedReference,
+    type FileReference,
+    type FileSymbolReference,
+    type Import,
+    type MarkdownLink,
+    type QualifiedReference
+} from './generated/ast.js';
+import { parseMarkdownLink } from './reqlan-references.js';
+import { reqlanStringDelimiter } from './reqlan-quoted-strings.js';
+import {
+    isNamespaceImportOnlyReference,
+    resolveNamespaceImportReferenceLink
+} from './reqlan-namespace-import-links.js';
+
+export type ReferenceResolution = 'file' | 'folder' | 'missing';
+
+export type FileLinkTargetIssue = 'empty' | 'parse-error';
+
+export interface ResolvedFileLink {
+    sourceRange: Range;
+    targetUri: string;
+    targetRange?: Range;
+    resolution?: ReferenceResolution;
+    folderFiles?: string[];
+    targetIssue?: FileLinkTargetIssue;
+}
+
+function withFileSystem(
+    fileSystem: FileSystemProvider,
+    context?: PathResolveContext
+): PathResolveContext {
+    return { ...context, fileSystem: context?.fileSystem ?? fileSystem };
+}
+
+export function classifyReferenceUri(
+    targetUri: URI,
+    documents: LangiumDocuments,
+    fileSystem: FileSystemProvider
+): ReferenceResolution {
+    if (findTargetDocument(targetUri, documents)) {
+        return 'file';
+    }
+    if (!fileSystem.existsSync(targetUri)) {
+        return 'missing';
+    }
+    return fileSystem.statSync(targetUri).isDirectory ? 'folder' : 'file';
+}
+
+export function listFolderFileNames(fileSystem: FileSystemProvider, folderUri: URI): string[] {
+    return fileSystem.readDirectorySync(folderUri)
+        .filter(entry => entry.isFile)
+        .map(entry => {
+            const segments = entry.uri.path.split('/');
+            return segments[segments.length - 1] ?? '';
+        })
+        .filter(name => name.length > 0)
+        .sort((left, right) => left.localeCompare(right));
+}
+
+export function resolveFileReferenceLink(
+    reference: FileReference | FileSymbolReference,
+    documents: LangiumDocuments,
+    fileSystem: FileSystemProvider,
+    context?: PathResolveContext
+): ResolvedFileLink | undefined {
+    const document = AstUtils.getDocument(reference);
+    const parsed = parseFileReferenceString(reference.file);
+    const pathNode = GrammarUtils.findNodeForProperty(reference.$cstNode, 'file');
+    if (!pathNode) {
+        return undefined;
+    }
+    return resolveParsedFileLink(document, documents, fileSystem, parsed, pathNode, context);
+}
+
+export function resolveImportPathLink(
+    importDecl: Import,
+    documents: LangiumDocuments,
+    context?: PathResolveContext
+): ResolvedFileLink | undefined {
+    const document = AstUtils.getDocument(importDecl);
+    const pathNode = GrammarUtils.findNodeForProperty(importDecl.$cstNode, 'path');
+    if (!pathNode) {
+        return undefined;
+    }
+    const imported = findImportedDocument(importDecl.path, document, documents, context);
+    const target = imported?.parseResult.value.$cstNode;
+    if (!imported || !target) {
+        return undefined;
+    }
+    return {
+        sourceRange: pathNode.range,
+        targetUri: imported.textDocument.uri,
+        targetRange: target.range
+    };
+}
+
+export function resolveQualifiedReferencePathLink(
+    reference: QualifiedReference,
+    documents: LangiumDocuments,
+    context?: PathResolveContext
+): ResolvedFileLink | undefined {
+    const pathNode = reference.path?.$refNode;
+    if (!pathNode) {
+        return undefined;
+    }
+    const document = AstUtils.getDocument(reference);
+    const path = qualifiedReferenceImportPath(reference);
+    if (!path) {
+        return undefined;
+    }
+    const imported = findImportedDocument(path, document, documents, context);
+    const target = imported?.parseResult.value.$cstNode;
+    if (!imported || !target) {
+        return undefined;
+    }
+    return {
+        sourceRange: pathNode.range,
+        targetUri: imported.textDocument.uri,
+        targetRange: target.range
+    };
+}
+
+export function resolveMarkdownLinkTargetLink(
+    link: MarkdownLink,
+    document: LangiumDocument,
+    documents: LangiumDocuments,
+    fileSystem: FileSystemProvider,
+    context?: PathResolveContext
+): ResolvedFileLink | undefined {
+    const parsedLink = parseMarkdownLink(link.raw);
+    if (!parsedLink) {
+        return undefined;
+    }
+    const pathNode = GrammarUtils.findNodeForProperty(link.$cstNode, 'raw');
+    if (!pathNode) {
+        return undefined;
+    }
+    const targetStart = link.raw.indexOf('](') + 2;
+    const targetLength = parsedLink.target.length;
+    const sourceRange = {
+        start: {
+            line: pathNode.range.start.line,
+            character: pathNode.range.start.character + targetStart
+        },
+        end: {
+            line: pathNode.range.start.line,
+            character: pathNode.range.start.character + targetStart + targetLength
+        }
+    };
+    const parsed = parseFileReferenceString(parsedLink.target);
+    const targetUri = resolveFileUri(parsed.filePath, document, withFileSystem(fileSystem, context));
+    return resolvePathStringLink(document, documents, fileSystem, parsed, targetUri, sourceRange);
+}
+
+export function resolveEmbeddedFileReferenceLink(
+    reference: EmbeddedFileReference,
+    document: LangiumDocument,
+    documents: LangiumDocuments,
+    fileSystem: FileSystemProvider,
+    context?: PathResolveContext
+): ResolvedFileLink | undefined {
+    const parsed = parseFileReferenceString(reference.file);
+    const targetUri = resolveFileUri(parsed.filePath, document, withFileSystem(fileSystem, context));
+    return resolvePathStringLink(
+        document,
+        documents,
+        fileSystem,
+        parsed,
+        targetUri,
+        reference.range
+    );
+}
+
+export function resolveParsedFileLink(
+    document: LangiumDocument,
+    documents: LangiumDocuments,
+    fileSystem: FileSystemProvider,
+    parsed: ParsedFileReference,
+    pathNode: CstNode,
+    context?: PathResolveContext
+): ResolvedFileLink | undefined {
+    const targetUri = resolveFileUri(parsed.filePath, document, withFileSystem(fileSystem, context));
+    const sourceRange = parsed.testName
+        ? stringContentRange(pathNode)
+        : filePathRangeInStringNode(pathNode, parsed);
+    return resolvePathStringLink(document, documents, fileSystem, parsed, targetUri, sourceRange);
+}
+
+function resolvePathStringLink(
+    _document: LangiumDocument,
+    documents: LangiumDocuments,
+    fileSystem: FileSystemProvider,
+    parsed: ParsedFileReference,
+    targetUri: URI,
+    sourceRange: Range
+): ResolvedFileLink | undefined {
+    const resolution = classifyReferenceUri(targetUri, documents, fileSystem);
+    if (resolution === 'missing') {
+        return undefined;
+    }
+    if (resolution === 'folder') {
+        return {
+            sourceRange,
+            targetUri: targetUri.toString(),
+            resolution,
+            folderFiles: listFolderFileNames(fileSystem, targetUri)
+        };
+    }
+    const text = readTargetText(targetUri, documents, fileSystem);
+    if (text === undefined) {
+        return undefined;
+    }
+    const targetIssue = detectFileLinkTargetIssue(text, findTargetDocument(targetUri, documents));
+    let targetRange: Range | undefined;
+    if (parsed.testName) {
+        const line = findTestLineInText(text, parsed.testName);
+        if (line !== undefined) {
+            targetRange = lineRangeFromText(text, line);
+        }
+    } else if (parsed.lineStart !== undefined) {
+        targetRange = lineRangeFromText(text, parsed.lineStart - 1);
+    } else {
+        targetRange = fileStartRange();
+    }
+    return {
+        sourceRange,
+        targetUri: targetUri.toString(),
+        targetRange,
+        resolution: 'file',
+        targetIssue
+    };
+}
+
+export function detectFileLinkTargetIssue(
+    text: string,
+    targetDocument: LangiumDocument | undefined
+): FileLinkTargetIssue | undefined {
+    if (text.length === 0) {
+        return 'empty';
+    }
+    if (targetDocument && targetDocument.parseResult.parserErrors.length > 0) {
+        return 'parse-error';
+    }
+    return undefined;
+}
+
+export function fileLinkTargetIssueMessage(issue: FileLinkTargetIssue): string {
+    switch (issue) {
+        case 'empty':
+            return 'Referenced file is empty.';
+        case 'parse-error':
+            return 'Referenced file has parse errors.';
+    }
+}
+
+function findTargetDocument(targetUri: URI, documents: LangiumDocuments): LangiumDocument | undefined {
+    const direct = documents.getDocument(targetUri);
+    if (direct) {
+        return direct;
+    }
+    const normalizedTarget = normalizeUriPath(targetUri);
+    for (const document of documents.all) {
+        if (normalizeUriPath(document.uri) === normalizedTarget) {
+            return document;
+        }
+    }
+    return undefined;
+}
+
+function normalizeUriPath(uri: URI): string {
+    return decodeURIComponent(uri.path).replace(/\\/g, '/');
+}
+
+function readTargetText(targetUri: URI, documents: LangiumDocuments, fileSystem: FileSystemProvider): string | undefined {
+    const targetDocument = findTargetDocument(targetUri, documents);
+    if (targetDocument) {
+        return targetDocument.textDocument.getText();
+    }
+    if (!fileSystem.existsSync(targetUri)) {
+        return undefined;
+    }
+    if (fileSystem.statSync(targetUri).isDirectory) {
+        return undefined;
+    }
+    return fileSystem.readFileSync(targetUri);
+}
+
+export function bindingNameSourceRange(bindingNode: CstNode, bindingName: string): Range {
+    const line = bindingNode.range.start.line;
+    const startCharacter = bindingNode.range.start.character;
+    return {
+        start: { line, character: startCharacter },
+        end: { line, character: startCharacter + bindingName.length }
+    };
+}
+
+export function resolveImportedFileLink(
+    document: LangiumDocument,
+    documents: LangiumDocuments,
+    fileSystem: FileSystemProvider,
+    filePath: string,
+    sourceRange: Range,
+    context?: PathResolveContext
+): ResolvedFileLink | undefined {
+    const targetUri = resolveExistingImportUri(filePath, document, documents, fileSystem, context);
+    return resolvePathStringLink(document, documents, fileSystem, { filePath }, targetUri, sourceRange);
+}
+
+export function filePathRangeInStringNode(pathNode: CstNode, parsed: ParsedFileReference): Range {
+    const text = pathNode.text;
+    const contentStart = pathNode.range.start.character + (reqlanStringDelimiter(text) ? 1 : 0);
+    return {
+        start: { line: pathNode.range.start.line, character: contentStart },
+        end: { line: pathNode.range.start.line, character: contentStart + parsed.filePath.length }
+    };
+}
+
+function stringContentRange(pathNode: CstNode): Range {
+    const text = pathNode.text;
+    const quoteOffset = reqlanStringDelimiter(text) ? 1 : 0;
+    const trailingQuote = quoteOffset;
+    return {
+        start: { line: pathNode.range.start.line, character: pathNode.range.start.character + quoteOffset },
+        end: { line: pathNode.range.end.line, character: pathNode.range.end.character - trailingQuote }
+    };
+}
+
+function lineRangeFromText(text: string, line: number): Range {
+    const lineText = text.split(/\r?\n/)[line] ?? '';
+    return {
+        start: { line, character: 0 },
+        end: { line, character: lineText.length }
+    };
+}
+
+function fileStartRange(): Range {
+    return {
+        start: { line: 0, character: 0 },
+        end: { line: 0, character: 0 }
+    };
+}
+
+export function collectFileLinks(
+    document: LangiumDocument,
+    documents: LangiumDocuments,
+    fileSystem: FileSystemProvider,
+    context?: PathResolveContext
+): ResolvedFileLink[] {
+    const pathContext = withFileSystem(fileSystem, context);
+    const links: ResolvedFileLink[] = [];
+    const linkedRanges: string[] = [];
+    for (const node of AstUtils.streamAst(document.parseResult.value)) {
+        if (isFileReference(node) || isFileSymbolReference(node)) {
+            const link = resolveFileReferenceLink(node, documents, fileSystem, pathContext);
+            if (link) {
+                links.push(link);
+                linkedRanges.push(rangeKey(link.sourceRange));
+            }
+        }
+        if ((isLocalReference(node) || isQualifiedReference(node)) && isNamespaceImportOnlyReference(node)) {
+            const link = resolveNamespaceImportReferenceLink(node, documents, fileSystem, pathContext);
+            if (link) {
+                links.push(link);
+                linkedRanges.push(rangeKey(link.sourceRange));
+            }
+        }
+        if (isImport(node)) {
+            const link = resolveImportPathLink(node, documents, pathContext);
+            if (link) {
+                links.push(link);
+                linkedRanges.push(rangeKey(link.sourceRange));
+            }
+        }
+        if (isQualifiedReference(node) && node.path && !node.path.ref) {
+            const link = resolveQualifiedReferencePathLink(node, documents, pathContext);
+            if (link) {
+                links.push(link);
+                linkedRanges.push(rangeKey(link.sourceRange));
+            }
+        }
+        if (isMarkdownLink(node)) {
+            const link = resolveMarkdownLinkTargetLink(node, document, documents, fileSystem, pathContext);
+            if (link) {
+                links.push(link);
+                linkedRanges.push(rangeKey(link.sourceRange));
+            }
+        }
+    }
+    for (const reference of findEmbeddedFileReferencesInText(document.textDocument.getText())) {
+        const key = rangeKey(reference.range);
+        if (linkedRanges.includes(key) || links.some(link => rangesOverlap(link.sourceRange, reference.range))) {
+            continue;
+        }
+        const link = resolveEmbeddedFileReferenceLink(reference, document, documents, fileSystem, pathContext);
+        if (link) {
+            links.push(link);
+            linkedRanges.push(key);
+        }
+    }
+    return links;
+}
+
+function rangeKey(range: Range): string {
+    return `${range.start.line}:${range.start.character}-${range.end.line}:${range.end.character}`;
+}
+
+function rangesOverlap(left: Range, right: Range): boolean {
+    if (left.start.line !== right.start.line || right.start.line !== right.end.line || left.start.line !== left.end.line) {
+        return left.start.line === right.start.line;
+    }
+    return left.start.character <= right.end.character && right.start.character <= left.end.character;
+}
+
+export function resolvedFileLinkTargetUri(link: ResolvedFileLink): string | undefined {
+    if (link.resolution === 'folder' || link.resolution === 'missing') {
+        return undefined;
+    }
+    if (link.targetRange) {
+        return `${link.targetUri}#L${link.targetRange.start.line + 1}`;
+    }
+    return link.targetUri;
+}
+
+export function resolvedFileLinkToGoToTarget(
+    link: ResolvedFileLink,
+    sourceNode: CstNode,
+    targetDocument: LangiumDocument
+): { source: CstNode; target: CstNode; targetDocument: LangiumDocument } | undefined {
+    const root = targetDocument.parseResult.value.$cstNode;
+    if (!root) {
+        return undefined;
+    }
+    const target = link.targetRange
+        ? ({
+            range: link.targetRange,
+            astNode: root.astNode
+        } as CstNode)
+        : root;
+    return {
+        source: CstUtils.getDatatypeNode(sourceNode) ?? sourceNode,
+        target,
+        targetDocument
+    };
+}
+
+export function resolvedFileLinkToGoToTargetFromFilesystem(
+    link: ResolvedFileLink,
+    sourceNode: CstNode
+): { source: CstNode; target: CstNode; targetDocument: LangiumDocument } | undefined {
+    if (!link.targetRange) {
+        return undefined;
+    }
+    const target = { range: link.targetRange } as CstNode;
+    const targetDocument = {
+        textDocument: { uri: link.targetUri }
+    } as LangiumDocument;
+    return {
+        source: CstUtils.getDatatypeNode(sourceNode) ?? sourceNode,
+        target,
+        targetDocument
+    };
+}

package/src/reqlan-file-references.ts

@@ -0,0 +1,84 @@
+/**
+ * Parses file path strings from bracket references, including L# line suffixes and :test name suffixes.
+ */
+
+export interface ParsedFileReference {
+    filePath: string;
+    lineStart?: number;
+    lineEnd?: number;
+    testName?: string;
+}
+
+const LINE_SUFFIX_PATTERN = /^(.*?)L#(\d+)(?:-(\d+))?$/;
+
+export function parseFileReferenceString(file: string): ParsedFileReference {
+    const lineMatch = LINE_SUFFIX_PATTERN.exec(file);
+    const lineParsed = lineMatch
+        ? {
+            filePath: lineMatch[1],
+            lineStart: Number.parseInt(lineMatch[2], 10),
+            lineEnd: lineMatch[3] ? Number.parseInt(lineMatch[3], 10) : Number.parseInt(lineMatch[2], 10)
+        }
+        : { filePath: file };
+    const testParsed = parseTestNameSuffix(lineParsed.filePath);
+    return {
+        filePath: testParsed.filePath,
+        lineStart: lineParsed.lineStart,
+        lineEnd: lineParsed.lineEnd,
+        testName: testParsed.testName
+    };
+}
+
+function parseTestNameSuffix(file: string): { filePath: string; testName?: string } {
+    let colonIndex = -1;
+    for (let index = file.length - 1; index >= 0; index--) {
+        if (file[index] !== ':') {
+            continue;
+        }
+        if (index > 0 && file[index - 1] === '/' && index > 1 && file[index - 2] === '/') {
+            continue;
+        }
+        colonIndex = index;
+        break;
+    }
+    if (colonIndex < 0) {
+        return { filePath: file };
+    }
+    const testName = file.slice(colonIndex + 1);
+    if (!testName) {
+        return { filePath: file };
+    }
+    return {
+        filePath: file.slice(0, colonIndex),
+        testName
+    };
+}
+
+const NON_RQ_FILE_EXTENSION = /\.[^./\\]+$/;
+
+/**
+ * True when a bracketed quoted path is an arbitrary file reference, not an inline .rq import path.
+ */
+export function isOpaqueFileReferencePath(path: string): boolean {
+    const parsed = parseFileReferenceString(path);
+    if (parsed.testName !== undefined || parsed.lineStart !== undefined) {
+        return true;
+    }
+    const filePath = parsed.filePath;
+    if (/\.rq$/i.test(filePath)) {
+        return false;
+    }
+    return NON_RQ_FILE_EXTENSION.test(filePath);
+}
+
+export function findTestLineInText(text: string, testName: string): number | undefined {
+    const escaped = testName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const pattern = new RegExp(`\\b(?:test|it)\\(\\s*['\`]${escaped}['\`]`);
+    const lines = text.split(/\r?\n/);
+    for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+        if (pattern.test(lines[lineIndex])) {
+            return lineIndex;
+        }
+    }
+    return undefined;
+}

package/src/reqlan-grammar-config.ts

@@ -0,0 +1,14 @@
+/**
+ * Grammar configuration for rename and comment handling in requirement documents.
+ */
+import type { GrammarConfig, LangiumCoreServices } from 'langium';
+import { createGrammarConfig } from 'langium';
+
+const ReqlanNameRegexp = /"[^"]*"|'[^']*'|\w[\w_]*/;
+
+export function createReqlanGrammarConfig(services: LangiumCoreServices): GrammarConfig {
+    return {
+        ...createGrammarConfig(services),
+        nameRegexp: ReqlanNameRegexp
+    };
+}

package/src/reqlan-idea-reference-site.ts

@@ -0,0 +1,74 @@
+/**
+ * Locate a bracket/wiki idea reference under the cursor for search code actions.
+ * rq:["../../../reqlan rq/extension/features-commands.rq".search_code_actions]
+ */
+import type { CstNode, LangiumDocument } from 'langium';
+import { CstUtils } from 'langium';
+import type { Position, Range } from 'vscode-languageserver';
+import {
+    isBracketReference,
+    isLocalReference,
+    isQualifiedReference,
+    isWikiLink,
+    type BracketReference,
+    type WikiLink
+} from './generated/ast.js';
+import { referenceIdea } from './reqlan-references.js';
+
+export interface IdeaReferenceSite {
+    /** Current idea name text inside the reference (may be empty or partial). */
+    refText: string;
+    /** Range of text to replace with the chosen idea name (inside brackets). */
+    range: Range;
+    kind: 'bracket' | 'wikilink';
+}
+
+export function findIdeaReferenceAtPosition(
+    document: LangiumDocument,
+    position: Position
+): IdeaReferenceSite | undefined {
+    const root = document.parseResult.value.$cstNode;
+    if (!root) {
+        return undefined;
+    }
+    const offset = document.textDocument.offsetAt(position);
+    let current: CstNode | undefined = CstUtils.findLeafNodeAtOffset(root, offset);
+    while (current) {
+        const node = current.astNode;
+        if (isBracketReference(node) || isWikiLink(node)) {
+            return siteFromReferenceContainer(node);
+        }
+        current = current.container;
+    }
+    return undefined;
+}
+
+function siteFromReferenceContainer(node: BracketReference | WikiLink): IdeaReferenceSite | undefined {
+    const kind = isWikiLink(node) ? 'wikilink' : 'bracket';
+    const target = node.target;
+    if (!target) {
+        return undefined;
+    }
+
+    if (isLocalReference(target) || isQualifiedReference(target)) {
+        const idea = referenceIdea(target);
+        const ideaNode = idea?.$refNode;
+        if (ideaNode) {
+            return {
+                refText: idea.$refText,
+                range: ideaNode.range,
+                kind
+            };
+        }
+    }
+
+    const targetNode = target.$cstNode;
+    if (!targetNode) {
+        return undefined;
+    }
+    return {
+        refText: targetNode.text,
+        range: targetNode.range,
+        kind
+    };
+}