@reqlan/language 1.4.0

package/src/reqlan-reference-code-lens.ts

@@ -0,0 +1,323 @@
+/**
+ * Classification labels and summary stats for reference CodeLens buttons.
+ * Click opens a reference card; navigation stays on document links / go-to-definition.
+ */
+import { AstUtils, GrammarUtils, URI, type AstNode } from 'langium';
+import { Command, type CodeLens, type Range } from 'vscode-languageserver';
+import { statSync } from 'node:fs';
+import {
+    isBracketReference,
+    isFileReference,
+    isFileSymbolReference,
+    isIdea,
+    isIdeaSet,
+    isLocalReference,
+    isOneLinerIdea,
+    isQualifiedReference,
+    isWikiLink,
+    type IdeaDeclaration,
+    type IdeaSet
+} from './generated/ast.js';
+import {
+    collectInboundReferencers,
+    type ReferencedDeclaration
+} from './reqlan-inbound-reference-inlay-label.js';
+import {
+    listFolderFileNames,
+    resolveFileReferenceLink,
+    type ResolvedFileLink
+} from './reqlan-file-link-resolver.js';
+import {
+    isNamespaceImportOnlyReference,
+    resolveNamespaceImportReferenceLink
+} from './reqlan-namespace-import-links.js';
+import { pathResolveContextFromServices } from './reqlan-path-resolve.js';
+import { referenceIdea } from './reqlan-references.js';
+import { summarizeIdeaDeclaration, truncateSummary } from './reqlan-idea-summary.js';
+import {
+    REQLAN_OPEN_REFERENCE_CODE_LENS_COMMAND,
+    type ReferenceCodeLensPayload
+} from './reqlan-code-lens-settings.js';
+import type { ReqlanServices } from './reqlan-module.js';
+
+export type ReferenceCodeLensClassification =
+    | { kind: 'idea'; declaration: ReferencedDeclaration }
+    | { kind: 'reqlan-file'; link: ResolvedFileLink }
+    | { kind: 'file'; link: ResolvedFileLink; extension: string }
+    | { kind: 'folder'; link: ResolvedFileLink };
+
+export function classifyReferenceForCodeLens(
+    services: ReqlanServices,
+    node: AstNode
+): ReferenceCodeLensClassification | undefined {
+    if (!isBracketReference(node) && !isWikiLink(node)) {
+        return undefined;
+    }
+    const target = node.target;
+    if (isLocalReference(target) || isQualifiedReference(target)) {
+        if (isNamespaceImportOnlyReference(target)) {
+            const link = resolveNamespaceImportReferenceLink(
+                target,
+                services.shared.workspace.LangiumDocuments,
+                services.shared.workspace.FileSystemProvider,
+                pathResolveContextFromServices(services)
+            );
+            return classifyResolvedFileLink(link);
+        }
+        const ideaRef = referenceIdea(target);
+        if (ideaRef?.ref) {
+            return { kind: 'idea', declaration: ideaRef.ref };
+        }
+        if (isQualifiedReference(target) && target.ideaset?.ref) {
+            return { kind: 'idea', declaration: target.ideaset.ref };
+        }
+        return undefined;
+    }
+    if (isFileReference(target) || isFileSymbolReference(target)) {
+        const link = resolveFileReferenceLink(
+            target,
+            services.shared.workspace.LangiumDocuments,
+            services.shared.workspace.FileSystemProvider,
+            pathResolveContextFromServices(services)
+        );
+        if (isFileSymbolReference(target) && target.symbols.length > 0) {
+            const idea = resolveFileSymbolIdea(services, link, target.symbols[0]!);
+            if (idea) {
+                return { kind: 'idea', declaration: idea };
+            }
+        }
+        return classifyResolvedFileLink(link);
+    }
+    return undefined;
+}
+
+function classifyResolvedFileLink(link: ResolvedFileLink | undefined): ReferenceCodeLensClassification | undefined {
+    if (!link || link.resolution === 'missing') {
+        return undefined;
+    }
+    if (link.resolution === 'folder') {
+        return { kind: 'folder', link };
+    }
+    const extension = fileExtension(link.targetUri);
+    if (!extension || extension === 'rq') {
+        return { kind: 'reqlan-file', link };
+    }
+    return { kind: 'file', link, extension };
+}
+
+function resolveFileSymbolIdea(
+    services: ReqlanServices,
+    link: ResolvedFileLink | undefined,
+    symbolName: string
+): IdeaDeclaration | IdeaSet | undefined {
+    if (!link || link.resolution !== 'file') {
+        return undefined;
+    }
+    const targetDocument = services.shared.workspace.LangiumDocuments.getDocument(URI.parse(link.targetUri));
+    if (!targetDocument) {
+        return undefined;
+    }
+    for (const candidate of AstUtils.streamAst(targetDocument.parseResult.value)) {
+        if ((isIdea(candidate) || isOneLinerIdea(candidate) || isIdeaSet(candidate)) && candidate.name === symbolName) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+
+export function referenceCodeLensTitle(classification: ReferenceCodeLensClassification): string {
+    switch (classification.kind) {
+        case 'idea':
+            return 'open idea';
+        case 'reqlan-file':
+            return 'open reqlan file';
+        case 'file':
+            return `open ${classification.extension} file`;
+        case 'folder':
+            return 'open folder';
+    }
+}
+
+export function buildReferenceCodeLens(
+    services: ReqlanServices,
+    node: AstNode,
+    classification: ReferenceCodeLensClassification
+): CodeLens | undefined {
+    const range = codeLensRange(node);
+    if (!range) {
+        return undefined;
+    }
+    const payload = payloadForClassification(services, classification);
+    if (!payload) {
+        return undefined;
+    }
+    const title = payload.classification;
+    const tooltip = payload.stats.length > 0
+        ? `${payload.displayName} · ${payload.stats.join(' · ')}`
+        : payload.displayName;
+    const command = Command.create(title, REQLAN_OPEN_REFERENCE_CODE_LENS_COMMAND, payload);
+    command.tooltip = tooltip;
+    return { range, command };
+}
+
+export function buildReferenceCodeLensStats(
+    services: ReqlanServices,
+    classification: ReferenceCodeLensClassification
+): string[] {
+    const parts: string[] = [];
+    if (classification.kind === 'idea') {
+        const referencers = collectInboundReferencers(services, classification.declaration).length;
+        const references = countOutboundReferences(classification.declaration);
+        parts.push(`${referencers} referencer${referencers === 1 ? '' : 's'}`);
+        parts.push(`${references} reference${references === 1 ? '' : 's'}`);
+        const edited = fileLastEditedLabel(AstUtils.getDocument(classification.declaration).uri.toString());
+        if (edited) {
+            parts.push(`last edited ${edited}`);
+        }
+        return parts;
+    }
+    if (classification.kind === 'folder') {
+        const files = classification.link.folderFiles
+            ?? listFolderFileNames(
+                services.shared.workspace.FileSystemProvider,
+                URI.parse(classification.link.targetUri)
+            );
+        parts.push(`${files.length} file${files.length === 1 ? '' : 's'}`);
+        return parts;
+    }
+    const edited = fileLastEditedLabel(classification.link.targetUri);
+    if (edited) {
+        parts.push(`last edited ${edited}`);
+    }
+    if (classification.kind === 'reqlan-file') {
+        const targetDocument = services.shared.workspace.LangiumDocuments.getDocument(
+            URI.parse(classification.link.targetUri)
+        );
+        if (targetDocument) {
+            let ideaCount = 0;
+            for (const candidate of AstUtils.streamAst(targetDocument.parseResult.value)) {
+                if (isIdea(candidate) || isOneLinerIdea(candidate) || isIdeaSet(candidate)) {
+                    ideaCount++;
+                }
+            }
+            parts.push(`${ideaCount} idea${ideaCount === 1 ? '' : 's'}`);
+        }
+    }
+    return parts;
+}
+
+/** @deprecated Prefer {@link buildReferenceCodeLensStats} — kept for existing tests. */
+export function buildReferenceCodeLensTooltip(
+    services: ReqlanServices,
+    classification: ReferenceCodeLensClassification
+): string | undefined {
+    const parts = buildReferenceCodeLensStats(services, classification);
+    return parts.length > 0 ? parts.join(' · ') : undefined;
+}
+
+export function countOutboundReferences(declaration: ReferencedDeclaration): number {
+    let count = 0;
+    for (const node of AstUtils.streamAst(declaration)) {
+        if (isBracketReference(node) || isWikiLink(node)) {
+            count++;
+        }
+    }
+    return count;
+}
+
+export function fileExtension(targetUri: string): string | undefined {
+    const path = URI.parse(targetUri).path;
+    const slash = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'));
+    const base = slash >= 0 ? path.slice(slash + 1) : path;
+    const dot = base.lastIndexOf('.');
+    if (dot <= 0 || dot === base.length - 1) {
+        return undefined;
+    }
+    return base.slice(dot + 1).toLowerCase();
+}
+
+export function fileLastEditedLabel(targetUri: string): string | undefined {
+    try {
+        const uri = URI.parse(targetUri);
+        if (uri.scheme !== 'file') {
+            return undefined;
+        }
+        const mtime = statSync(uri.fsPath).mtime;
+        return mtime.toISOString().slice(0, 10);
+    } catch {
+        return undefined;
+    }
+}
+
+function displayNameForUri(targetUri: string): string {
+    const path = URI.parse(targetUri).path;
+    const slash = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'));
+    return slash >= 0 ? path.slice(slash + 1) : path;
+}
+
+function payloadForClassification(
+    services: ReqlanServices,
+    classification: ReferenceCodeLensClassification
+): ReferenceCodeLensPayload | undefined {
+    const classificationLabel = referenceCodeLensTitle(classification);
+    const stats = buildReferenceCodeLensStats(services, classification);
+
+    if (classification.kind === 'idea') {
+        const declaration = classification.declaration;
+        const nameNode = GrammarUtils.findNodeForProperty(declaration.$cstNode, 'name');
+        const document = AstUtils.getDocument(declaration);
+        const summary = isIdea(declaration) || isOneLinerIdea(declaration)
+            ? truncateSummary(summarizeIdeaDeclaration(declaration), 240)
+            : undefined;
+        return {
+            kind: 'idea',
+            classification: classificationLabel,
+            displayName: declaration.name,
+            targetUri: document.uri.toString(),
+            line: nameNode?.range.start.line ?? 0,
+            character: nameNode?.range.start.character ?? 0,
+            summary: summary || undefined,
+            stats
+        };
+    }
+
+    const link = classification.link;
+    const displayName = displayNameForUri(link.targetUri);
+    if (classification.kind === 'folder') {
+        const folderFiles = link.folderFiles
+            ?? listFolderFileNames(
+                services.shared.workspace.FileSystemProvider,
+                URI.parse(link.targetUri)
+            );
+        return {
+            kind: 'folder',
+            classification: classificationLabel,
+            displayName,
+            targetUri: link.targetUri,
+            folderFiles,
+            summary: folderFiles.slice(0, 8).join(', ') + (folderFiles.length > 8 ? '…' : ''),
+            stats
+        };
+    }
+    return {
+        kind: classification.kind === 'reqlan-file' ? 'reqlan-file' : 'file',
+        classification: classificationLabel,
+        displayName,
+        targetUri: link.targetUri,
+        line: link.targetRange?.start.line ?? 0,
+        character: link.targetRange?.start.character ?? 0,
+        extension: classification.kind === 'file' ? classification.extension : undefined,
+        stats
+    };
+}
+
+function codeLensRange(node: AstNode): Range | undefined {
+    const cst = node.$cstNode;
+    if (!cst) {
+        return undefined;
+    }
+    return {
+        start: { line: cst.range.start.line, character: 0 },
+        end: cst.range.end
+    };
+}

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

@@ -0,0 +1,202 @@
+/**
+ * Locate places where a selection or word can become a [reference],
+ * and extract surrounding idea text for the search modal preview.
+ * rq:["../../../reqlan rq/extension/features-commands.rq".search_code_actions]
+ */
+import type { LangiumDocument } from 'langium';
+import type { Position, Range } from 'vscode-languageserver';
+import {
+    findContainingIdea,
+    isInMainDescriptionProse
+} from './reqlan-completion-context.js';
+import {
+    findIdeaReferenceAtPosition,
+    type IdeaReferenceSite
+} from './reqlan-idea-reference-site.js';
+import { isIdea, isOneLinerIdea, type IdeaDeclaration } from './generated/ast.js';
+
+export type ReferenceSearchMode = 'replace' | 'wrap';
+
+export interface ReferenceSearchContext {
+    ideaName: string;
+    /** Text before the target within the idea source. */
+    before: string;
+    /** Selected / reference text that will become (or already is) the reference. */
+    target: string;
+    /** Text after the target within the idea source. */
+    after: string;
+}
+
+export interface ReferenceSearchSite {
+    refText: string;
+    range: Range;
+    mode: ReferenceSearchMode;
+    kind: 'bracket' | 'wikilink' | 'prose';
+    context?: ReferenceSearchContext;
+}
+
+/**
+ * Prefer an existing [reference]/[[wikilink]] under the cursor; otherwise a
+ * selection or word in idea-body prose that can be wrapped as `[name]`.
+ */
+export function findReferenceSearchSite(
+    document: LangiumDocument,
+    range: Range
+): ReferenceSearchSite | undefined {
+    const existing = findIdeaReferenceAtPosition(document, range.start);
+    if (existing) {
+        return siteFromExistingReference(document, existing);
+    }
+    return findWrapSite(document, range);
+}
+
+function siteFromExistingReference(
+    document: LangiumDocument,
+    existing: IdeaReferenceSite
+): ReferenceSearchSite {
+    return {
+        refText: existing.refText,
+        range: existing.range,
+        mode: 'replace',
+        kind: existing.kind,
+        context: buildContextForRange(document, existing.range)
+    };
+}
+
+function findWrapSite(document: LangiumDocument, range: Range): ReferenceSearchSite | undefined {
+    const rawRange = isEmptyRange(range)
+        ? expandToWordAtPosition(document, range.start)
+        : normalizeForwardRange(range);
+    const wrapRange = rawRange ? trimRangeWhitespace(document, rawRange) : undefined;
+    if (!wrapRange || isEmptyRange(wrapRange)) {
+        return undefined;
+    }
+
+    // Both ends must sit in idea-body prose (not imports, attribute keys, refs, etc.)
+    const endProbe = document.textDocument.positionAt(
+        Math.max(
+            document.textDocument.offsetAt(wrapRange.start),
+            document.textDocument.offsetAt(wrapRange.end) - 1
+        )
+    );
+    if (!isAppropriateWrapLocation(document, wrapRange.start)
+        || !isAppropriateWrapLocation(document, endProbe)) {
+        return undefined;
+    }
+
+    // Keep wrap inside a single idea
+    const idea = findContainingIdea(document, wrapRange.start);
+    if (!idea || findContainingIdea(document, wrapRange.end) !== idea) {
+        return undefined;
+    }
+
+    const refText = document.textDocument.getText(wrapRange).trim();
+    if (!refText || /\n/.test(refText)) {
+        return undefined;
+    }
+    // Avoid wrapping text that is already bracket-wrapped
+    if (/^\[.*\]$/.test(refText) || /^\[\[.*\]\]$/.test(refText)) {
+        return undefined;
+    }
+
+    return {
+        refText,
+        range: wrapRange,
+        mode: 'wrap',
+        kind: 'prose',
+        context: buildContextForRange(document, wrapRange, idea)
+    };
+}
+
+export function isAppropriateWrapLocation(document: LangiumDocument, position: Position): boolean {
+    return isInMainDescriptionProse(document, position);
+}
+
+export function buildContextForRange(
+    document: LangiumDocument,
+    range: Range,
+    idea?: IdeaDeclaration
+): ReferenceSearchContext | undefined {
+    const containing = idea ?? findContainingIdea(document, range.start);
+    if (!containing?.$cstNode) {
+        return undefined;
+    }
+    const ideaRange = containing.$cstNode.range;
+    const ideaText = document.textDocument.getText(ideaRange);
+    const ideaStart = document.textDocument.offsetAt(ideaRange.start);
+    const targetStart = document.textDocument.offsetAt(range.start) - ideaStart;
+    const targetEnd = document.textDocument.offsetAt(range.end) - ideaStart;
+    if (targetStart < 0 || targetEnd > ideaText.length || targetStart > targetEnd) {
+        return undefined;
+    }
+    return {
+        ideaName: containing.name,
+        before: ideaText.slice(0, targetStart),
+        target: ideaText.slice(targetStart, targetEnd),
+        after: ideaText.slice(targetEnd)
+    };
+}
+
+export function expandToWordAtPosition(
+    document: LangiumDocument,
+    position: Position
+): Range | undefined {
+    const line = document.textDocument.getText({
+        start: { line: position.line, character: 0 },
+        end: { line: position.line + 1, character: 0 }
+    });
+    // Strip trailing newline for indexing
+    const lineText = line.replace(/\r?\n$/, '');
+    if (position.character > lineText.length) {
+        return undefined;
+    }
+    const isWord = (ch: string | undefined) => !!ch && /[A-Za-z0-9_]/.test(ch);
+    let start = position.character;
+    let end = position.character;
+    while (start > 0 && isWord(lineText[start - 1])) {
+        start -= 1;
+    }
+    while (end < lineText.length && isWord(lineText[end])) {
+        end += 1;
+    }
+    if (start === end) {
+        return undefined;
+    }
+    return {
+        start: { line: position.line, character: start },
+        end: { line: position.line, character: end }
+    };
+}
+
+function trimRangeWhitespace(document: LangiumDocument, range: Range): Range | undefined {
+    const text = document.textDocument.getText(range);
+    const lead = /^\s*/.exec(text)?.[0].length ?? 0;
+    const trail = /\s*$/.exec(text)?.[0].length ?? 0;
+    if (lead + trail >= text.length) {
+        return undefined;
+    }
+    const startOffset = document.textDocument.offsetAt(range.start) + lead;
+    const endOffset = document.textDocument.offsetAt(range.end) - trail;
+    return {
+        start: document.textDocument.positionAt(startOffset),
+        end: document.textDocument.positionAt(endOffset)
+    };
+}
+
+function isEmptyRange(range: Range): boolean {
+    return range.start.line === range.end.line && range.start.character === range.end.character;
+}
+
+function normalizeForwardRange(range: Range): Range {
+    if (
+        range.start.line > range.end.line
+        || (range.start.line === range.end.line && range.start.character > range.end.character)
+    ) {
+        return { start: range.end, end: range.start };
+    }
+    return range;
+}
+
+export function isBlockOrOneLinerIdea(node: unknown): node is IdeaDeclaration {
+    return isIdea(node) || isOneLinerIdea(node);
+}

package/src/reqlan-references.ts

@@ -0,0 +1,76 @@
+/**
+ * Shared helpers for the reference target union types.
+ */
+import type { Reference } from 'langium';
+import {
+    isFileReference,
+    isFileSymbolReference,
+    isLocalReference,
+    isQualifiedReference,
+    type IdeaDeclaration,
+    type Import,
+    type QualifiedReference,
+    type ReferenceTarget
+} from './generated/ast.js';
+import { unquoteReqlanString } from './reqlan-quoted-strings.js';
+
+export function referenceImport(target: ReferenceTarget): Reference<Import> | undefined {
+    if (isQualifiedReference(target)) {
+        return target.path?.ref || target.qualifier?.ref ? (target.path ?? target.qualifier) : undefined;
+    }
+    return undefined;
+}
+
+export function referenceIdea(target: ReferenceTarget): Reference<IdeaDeclaration> | undefined {
+    if (isQualifiedReference(target) || isLocalReference(target)) {
+        return target.idea;
+    }
+    return undefined;
+}
+
+export function referenceFilePath(target: ReferenceTarget): string | undefined {
+    if (isFileReference(target) || isFileSymbolReference(target)) {
+        return target.file;
+    }
+    if (isQualifiedReference(target)) {
+        return qualifiedReferenceImportPath(target);
+    }
+    return undefined;
+}
+
+export function qualifiedReferenceImportPath(reference: QualifiedReference): string | undefined {
+    if (reference.qualifier?.ref) {
+        return reference.qualifier.ref.path;
+    }
+    if (reference.path?.ref) {
+        return reference.path.ref.path;
+    }
+    if (reference.path?.$refText) {
+        return unquoteReqlanString(reference.path.$refText);
+    }
+    return undefined;
+}
+
+export function isAnonymousQualifiedReference(reference: QualifiedReference): boolean {
+    return reference.path !== undefined && reference.path.ref === undefined && reference.qualifier === undefined;
+}
+
+export { unquoteReqlanString } from './reqlan-quoted-strings.js';
+
+export interface ParsedMarkdownLink {
+    label: string;
+    target: string;
+}
+
+const MARKDOWN_LINK_PATTERN = /^\[([^\]]+)\]\(([^)]+)\)$/;
+
+export function parseMarkdownLink(raw: string): ParsedMarkdownLink | undefined {
+    const match = MARKDOWN_LINK_PATTERN.exec(raw);
+    if (!match) {
+        return undefined;
+    }
+    return {
+        label: match[1]!,
+        target: match[2]!
+    };
+}