vscode extension: rename the id property and all its references in scope

[shutterfreak]

I'm trying to figure out how I should implement a vscode source action to rename the selected 'id' property, which is either the unique ID of an Element (Graph, Node, Link) or is the refText in the 'src' or 'dst' property of Link.

Here's a Langium playground link with a simplified grammar and DSL example.

I wrote a custom scope provider that puts the 'id' property in the global scope.

Basically I would like the source action to rename all 'id' properties (and references) in scope, when either selecting the 'id' property or when selecting the 'refText' in a reference (which uses 'id' from the global scope).

I set up src/extension/main.ts to register the extension in vscode. Should I define my custom renameProvider in src/vscode-extension/src/ and register it in extension.ts, or should I use language-server?

[msujew]

Hey @shutterfreak,

implement a vscode source action

Do you perhaps mean a code action? You can implement one that internally calls the References services to provide the text edits. That's how the DefaultRenameProvider is implemented:

langium/packages/langium/src/lsp/rename-provider.ts

Lines 51 to 53 in fa8371b

	export class DefaultRenameProvider implements RenameProvider {
	protected readonly references: References;

[msujew]

You can take a look at our Langium grammar code action provider implementation to see how this can be accomplished. Generally, code actions are always generated from a previously generated diagnostic (we use the data property of the diagnostic to identify which code action to provide).

I mentioned in my initial comment that you can use the RenameProvider in your implementation to provide the edits. However, feature itself needs to be provided by a CodeActionProvider. I left that out.

[cdietrich]

depending on the usecase you might also look into code lenses.

[shutterfreak]

I mentioned in my initial comment that you can use the RenameProvider in your implementation to provide the edits. However, feature itself needs to be provided by a CodeActionProvider. I left that out.

Do you know an example implementation of this approach?

[msujew]

I'm not aware of one, no. However, using the RenameProvider should be pretty straightforward, as you can reuse the range/position provided by the diagnostic to feed into the RenameProvider.

[shutterfreak]

I'm not aware of one, no. However, using the RenameProvider should be pretty straightforward, as you can reuse the range/position provided by the diagnostic to feed into the RenameProvider.

If you know how to do it, it's actually pretty straightforward. Here's an example implementation for my Graph language with some debug output. There might be easier ways, though, but I'm still learning. The hardest bit is understanding that the vscode extension shows the document, hence renders the CST. We need to find the matching AST node from the cursor context (position) and then get the offset of the CST node we need to edit (in my case, the CST node that keeps the id property). To edit the references, just use document.references...

Add "renameProvider": true to package.json in the contributes.languages[] section:

  "contributes": {
    "languages": [
      {
        "id": "graph",
        "aliases": [
          "Graph",
          "graph"
        ],
        "extensions": [
          ".graph"
        ],
        "configuration": "./language-configuration.json",
        "renameProvider": true
      }

In src/language/graph-module.ts import our rename provider and inject it in GraphModule.lsp.RenameProvider:

. . .
import { GraphRenameProvider } from "../language-server/graph-rename-provider.js";

. . .

/**
 * Union of Langium default services and your custom services - use this as constructor parameter
 * of custom service classes.
 */
export type GraphServices = LangiumServices & GraphAddedServices;

/**
 * Dependency injection module that overrides Langium default services and contributes the
 * 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 GraphModule: Module<
  GraphServices,
  PartialLangiumServices & GraphAddedServices
> = {
  validation: {
    GraphValidator: () => new GraphValidator(),
  },
  references: {
    ScopeComputation: (services) => new GraphScopeComputation(services),
  },
  lsp: {
    // Inject our code action provider:
    CodeActionProvider: () => new GraphCodeActionProvider(),
    // Inject our rename provider:
    RenameProvider: (services) => new GraphRenameProvider(services),
  },
};

And define the rename provider in src/lsp/graph-rename-provider.ts:

import { type AstNode, AstUtils, CstNode, GrammarUtils, type LangiumDocument } from 'langium';
import { DefaultRenameProvider, LangiumServices } from 'langium/lsp';
import { inspect } from 'node:util';
import {
  CancellationToken,
  Position,
  Range,
  RenameParams,
  TextDocumentPositionParams,
  TextEdit,
  WorkspaceEdit,
} from 'vscode-languageserver';

import { isElement } from '../language/generated/ast.js';

export class GraphRenameProvider extends DefaultRenameProvider {
  constructor(services: LangiumServices) {
    super(services);
  }

  /**
   * Determines if a rename operation is valid and returns the range of the identifier to rename.
   */
  override async prepareRename(
    document: LangiumDocument,
    params: TextDocumentPositionParams,
    // eslint-disable-next-line @typescript-eslint/no-unused-vars
    cancelToken?: CancellationToken,
  ): Promise<Range | undefined> {
    console.log('GraphRenameProvider.prepareRename() called, params.position : ', params.position);
    const node = this.findDeclarationNode(document, params.position);
    console.log(
      `GraphRenameProvider.prepareRename() found node of type '${node?.$type}' defined as:\n${node?.$cstNode?.text}\n\n\n`,
      // + inspect(node),
    );
    // If a valid node is found, return its name range; otherwise, return undefined

    if (!node) {
      return Promise.resolve(undefined);
    }

    const cstIdNode = GrammarUtils.findNodeForProperty(node.$cstNode, 'id');
    console.log(
      `GraphRenameProvider.prepareRename() found CST node with property "id": (${inspect(cstIdNode?.range)}) : [${cstIdNode?.text}]\n` +
        inspect(cstIdNode),
    );

    return Promise.resolve(
      // node ? this.nameProvider.getNameNode(node)?.range : undefined,
      // namedNode?.range
      cstIdNode?.range,
    );
  }

  /**
   * Performs the rename operation by updating all occurrences of the symbol in the document.
   */
  override async rename(
    document: LangiumDocument,
    params: RenameParams,
    // eslint-disable-next-line @typescript-eslint/no-unused-vars
    cancelToken?: CancellationToken,
  ): Promise<WorkspaceEdit | undefined> {
    const node = this.findDeclarationNode(document, params.position);
    console.log('GraphRenameProvider.rename() called, params : ', inspect(params));
    console.log(
      `GraphRenameProvider.rename() found node of type '${node?.$type}' defined as:\n${node?.$cstNode?.text}\n\n\n`,
    );

    if (!node || !isElement(node)) {
      return undefined;
    }
    // Generate the required text edits for renaming the element
    return Promise.resolve(this.createRenameEdit(document, node, params.newName));
  }

  /**
   * Finds the declaration node corresponding to the rename request.
   */

  protected findDeclarationNode(
    document: LangiumDocument,
    position: Position,
  ): AstNode | undefined {
    const rootNode = document.parseResult.value;

    // Ensure CST node exists
    if (!rootNode.$cstNode) {
      console.log('GraphRenameProvider.findDeclarationNode() - No root CST node.');
      return undefined;
    }

    // Find the AST node at the given cursor position
    const declarationNode = this.findAstNodeAtPosition(rootNode.$cstNode, position);
    console.log(
      `GraphRenameProvider.findDeclarationNode() - will return node of type '${declarationNode?.$type}' defined as:\n${declarationNode?.$cstNode?.text}\n\n\n`,
    );

    return declarationNode;
  }

  protected findAstNodeAtPosition(rootCstNode: CstNode, position: Position): AstNode | undefined {
    let i = 0;
    const matches: AstNode[] = [];

    // Process the AST nodes to get the matching AST entry
    for (const astNode of AstUtils.streamAllContents(rootCstNode.astNode)) {
      i++;
      if (astNode.$cstNode == undefined) {
        continue;
      }
      const { start, end } = astNode.$cstNode.range;

      // Check if cursor in astNode's Cst node range:
      if (position.line < start.line) {
        // cstNode before cursor (line level) -- SKIP
        continue;
      } else if (position.line > end.line) {
        // cstNode after cursor (line level) -- SKIP
        continue;
      } else {
        // cursor line in cstNode range
        if (position.line === start.line && position.character < start.character) {
          // cstNode after cursor (char level) -- SKIP
          continue;
        } else if (position.line === end.line && position.character > end.character) {
          // cstNode before cursor (char level) -- SKIP
          continue;
        }
      }

      // Potential candidate found
      console.log(`POTENTIAL MATCH: cursor position within cstNode range`);

      console.log(
        `\nAST ${String('    ' + i).slice(-4)} | ${astNode.$type} (${
          astNode.$containerProperty ?? '<unknown container property>'
        }) - cstNode <${astNode.$cstNode.grammarSource?.$type ?? 'undefined'}: ${
          astNode.$cstNode.grammarSource?.$containerProperty ?? '<container property not set>'
        }> @ (line ${start.line}, char ${start.character}) to (line ${end.line}, char ${end.character}) -- length = ${astNode.$cstNode.length}`,
      );
      console.log(
        astNode.$cstNode.text
          .split(/\r?\n|\r|\n/g)
          .map(
            (line, index) =>
              `  astNode.$cstNode.text: ${String('    ' + (index + start.line + 1)).slice(-4)} | ${line}`,
          )
          .join('\n'),
      );

      // We found a possible match of type Element (Graph, Node, Link) or Style
      matches.push(astNode);

      if (!isElement(astNode)) {
        // rename not applicable
        console.log(' -- not in scope for renaming (skipped)');
        continue;
      }
    }

    // Now get the AST node with the "smallest match":
    const m = matches.sort((a, b) => (a.$cstNode?.length ?? 0) - (b.$cstNode?.length ?? 0));

    console.log(
      (m[0].$cstNode?.text ?? '<Error: CST Node is undefined>')
        .split(/\r?\n|\r|\n/g)
        .map(
          (line, index) =>
            `  MATCH astNode.$cstNode.text: ${String('    ' + (index + (m[0].$cstNode?.range.start.line ?? 0) + 1)).slice(-4)} | ${line}`,
        )
        .join('\n'),
    );

    return m[0];
  }

  /**
   * Creates the necessary text edits to rename an element, updating all references.
   */
  protected createRenameEdit(
    document: LangiumDocument,
    node: AstNode,
    newName: string,
  ): WorkspaceEdit | undefined {
    console.log(
      `\n\nGraphRenameProvider.createRenameEdit() - node type: '${node.$type}' - property 'id' will be renamed to "${newName}"`,
    );

    if (!isElement(node) || node.id == null) {
      return undefined;
    }

    console.log(
      `GraphRenameProvider.createRenameEdit() - node type: '${node.$type}' - property 'id' will be renamed from "${node.id ?? ''}" to "${newName}"`,
    );

    // Collect all existing IDs in the document to avoid naming conflicts
    const existingIds = new Set<string>();
    for (const childNode of AstUtils.streamAllContents(document.parseResult.value)) {
      if (isElement(childNode) && childNode.id != null) {
        existingIds.add(childNode.id);
      }
    }

    console.log(
      `GraphRenameProvider.createRenameEdit() - existing 'id' values: [${[...existingIds].join(', ')}] -- should not contain "${newName}"`,
    );

    // Validate the new name to prevent conflicts with existing identifiers or keywords
    if (existingIds.has(newName) || this.isKeyword(newName)) {
      console.warn(
        `GraphRenameProvider.createRenameEdit() - Error: "${newName}" already exists as 'id' or is a reserved keyword`,
      );
      return undefined;
    }

    const edits: TextEdit[] = [];

    // Rename the actual declaration
    const cstIdNode = GrammarUtils.findNodeForProperty(node.$cstNode, 'id');
    if (cstIdNode) {
      edits.push(TextEdit.replace(cstIdNode.range, newName));
    } else {
      console.warn("No CST node for 'id' property found.");
    }

    // Find all references
    const refs = document.references;

    console.log(`GraphRenameProvider.createRenameEdit() - Found ${refs.length} references:`);

    for (const ref of refs) {
      console.log(
        `- Reference at ${inspect(ref.$refNode?.range)}: ${ref.$refText} ${
          ref.$refNode
            ? `Node type '${ref.$refNode.astNode.$type}', text: ${ref.$refNode.text}`
            : 'Unresolved reference'
        }`,
      );
    }

    // Rename all references
    for (const ref of document.references) {
      if (ref.$refText !== node.id) {
        continue; // Skip references that don't match the original ID
      }

      console.log(
        `GraphRenameProvider.createRenameEdit() - Renaming reference '${ref.$refText}' at ${inspect(ref.$refNode?.range)}`,
      );

      if (ref.$refNode) {
        edits.push(TextEdit.replace(ref.$refNode.range, newName));
      }
    }

    if (edits.length === 0) {
      console.warn('No edits generated for rename.');
      return undefined;
    }

    const changes = { changes: { [document.uri.toString()]: edits } };

    console.log(`GraphRenameProvider.createRenameEdit() - will return:\n${inspect(changes)}\n`);

    return changes;
  }

  /**
   * Checks if a given name is a reserved keyword in the language to prevent invalid renaming.
   */
  protected isKeyword(name: string): boolean {
    const keywords = new Set(['element', 'graph', 'link', 'node', 'style', 'to', 'with']);
    return keywords.has(name);
  }
}

[shutterfreak]

I hoped to find example implementations as inspiration but I lack the understanding of the vscode-LSP-langium integration to get it to work.

[msujew]

Like I said, we have an example implementation here. Aside from binding the service, it's a fully running implementation that shows how to contribute code actions to an editor.

but I lack the understanding of the vscode-LSP-langium integration to get it to work.

It's not like we do anything special in there. We just pass the arguments we get from the language client into the CodeActionProvider service.

[shutterfreak]

Thanks for your support.

Unfortunately I can't figure out from the examples provided how to get it implemented in my simple scaffolded langium project. I'll have to dig deeper into the mechanics of LSP and the different way they're implemented in a langium project.

[cdietrich]

simply creating a code action provider and register it does not work
(very old example, imports may differ: https://github.com/cdietrich/langium-mydsl/blob/5fba91fe563da587014ff0be69105da49746b3dd/src/language-server/mydsl-module.ts#L32 https://github.com/cdietrich/langium-mydsl/blob/5fba91fe563da587014ff0be69105da49746b3dd/src/language-server/mydsl-code-actions.ts) or as pointed out for the grmmar dsl:

langium/packages/langium/src/grammar/langium-grammar-module.ts

Line 48 in fa8371b

CodeActionProvider: (services) => new LangiumGrammarCodeActionProvider(services),

https://github.com/eclipse-langium/langium/blob/fa8371b7382f4fb84d69264b08a6425ea453a849/packages/langium/src/grammar/lsp/grammar-code-actions.ts

[shutterfreak]

Okay.

I have the core langium stuff in src/language/, and the dependency injection module defined in src/language/graph-module.ts:

export const GraphModule: Module<
  GraphServices,
  PartialLangiumServices & GraphAddedServices
> = {
  validation: {
    GraphValidator: () => new GraphValidator(),
  },
  references: {
    ScopeComputation: (services) => new GraphScopeComputation(services),
  },
};

Does your example imply that I need to create another dependency injection module for the language server, say in src/language-server/graph-module.ts, for the services and validations relating to the vscode extension?

Or can I just add the lsp related entry to my existing dependency injection module (in src/language/graph-module.ts) as in:

import {
  AstNode,
  AstNodeDescription,
  AstUtils,
  DefaultScopeComputation,
  LangiumDocument,
  type Module,
  MultiMap,
  PrecomputedScopes,
  inject,
} from "langium";
import {
  createDefaultModule,
  createDefaultSharedModule,
  type DefaultSharedModuleContext,
  type LangiumServices,
  type LangiumSharedServices,
  type PartialLangiumServices,
} from "langium/lsp";
import {
  GraphGeneratedModule,
  GraphGeneratedSharedModule,
} from "./generated/module.js";
import { GraphValidator, registerValidationChecks } from "./graph-validator.js";
import {
  isElement,
  isGraph,
  isModel,
  isStyle,
  Model,
} from "./generated/ast.js";
import chalk from "chalk";
import { GraphCodeActionProvider } from "../language-server/graph-code-actions.js";

/**
 * Declaration of custom services - add your own service classes here.
 */
export interface GraphAddedServices {
  validation: {
    GraphValidator: GraphValidator;
  };
  references: {
    ScopeComputation: GraphScopeComputation;
  };
}

/**
 * Union of Langium default services and your custom services - use this as constructor parameter
 * of custom service classes.
 */
export type GraphServices = LangiumServices & GraphAddedServices;

/**
 * Dependency injection module that overrides Langium default services and contributes the
 * 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 GraphModule: Module<
  GraphServices,
  PartialLangiumServices & GraphAddedServices
> = {
  validation: {
    // NOTE: we use createGraphServices() to register the full set of services into ValidationRegistry
    GraphValidator: () => new GraphValidator(),
  },
  references: {
    ScopeComputation: (services) => new GraphScopeComputation(services),
  },
  lsp: { // NEW - LSP for the code actions:
    CodeActionProvider: () => new GraphCodeActionProvider()
  }
};


/**
 * Create the full set of services required by Langium.
 *
 * First inject the shared services by merging two modules:
 *  - Langium default shared services
 *  - Services generated by langium-cli
 *
 * Then inject the language-specific services by merging three modules:
 *  - Langium default language-specific services
 *  - Services generated by langium-cli
 *  - Services specified in this file
 *
 * @param context Optional module context with the LSP connection
 * @returns An object wrapping the shared services and the language-specific services
 */
export function createGraphServices(context: DefaultSharedModuleContext): {
  shared: LangiumSharedServices;
  Graph: GraphServices;
} {
  const shared = inject(
    createDefaultSharedModule(context),
    GraphGeneratedSharedModule,
  );
  const Graph = inject(
    createDefaultModule({ shared }),
    GraphGeneratedModule,
    GraphModule,
  );
  shared.ServiceRegistry.register(Graph);
  registerValidationChecks(Graph);
  if (!context.connection) {
    // We don't run inside a language server
    // Therefore, initialize the configuration provider instantly
    shared.workspace.ConfigurationProvider.initialized({}).catch((exception) =>
      console.error(exception),
    );
  }
  return { shared, Graph };
}

So I don't define GraphValidationRegistry() as I believe it is already covered in src/language/graph-validator.ts:

/**
 * Register custom validation checks.
 */
export function registerValidationChecks(services: GraphServices) {
  const registry = services.validation.ValidationRegistry;
  const validator = services.validation.GraphValidator;
  const checks: ValidationChecks<GraphAstType> = {
    Model: [validator.checkUniqueElementNames, validator.checkStyles],
    Link: [validator.checkLinkStyles],
    Style: [validator.checkStyleNames, validator.checkStyleSubstyles],
    StyleDefinition: [validator.checkStyleDefinitionTopics],
    HexColorDefinition: [validator.checkHexColorDefinitions],
    RgbColorDefinition: [validator.checkRgbColorDefinitions],
    TextColorDefinition: [validator.checkTextColorDefinitions],
    LineStyleDefinition: [validator.checkLineWidthDefinitions],
    OpacityStyleDefinition: [validator.checkOpacityStyleDefinition],
    ShapeStyleDefinition: [validator.checkShapeStyleDefinitions],
  };
  registry.register(checks, validator);
}

Should I then place the code actions for my DSL in src/language-server/graph-code-actions.ts?

[cdietrich]

you can create and name the file however you like. JavaScript/Typescript has no file naming conventions.
and the validation you simply register in the xxxx-validator.ts that is already there
you also use the module that is already there

[shutterfreak]

I got it to work thanks to your input!

I added the diagnostic codes to my validators, for instance:

  checkUniqueElementNames = (
    model: Model,
    accept: ValidationAcceptor,
  ): void => {
    // Create a set of identifiers while traversing the AST
    const identifiers = new Set<string>();

    function traverseElement(element: Element): void {
      const preamble = `traverseElement(${element.$type} element (${element.id ?? "<no name>"}))`;
      console.log(chalk.white(`${preamble} - START`));
      if (
        (isNode(element) || isGraph(element)) &&
        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
        (element.id === undefined || element.id.length == 0)
      ) {
        accept(
          "error",
          `${element.$type} must have a nonempty id [${element.$cstNode?.text}]`,
          { node: element, property: "id", code: "empty_id" },
        );
      }
      if (element.id !== undefined) {
        // The element has a name (note: links have an optional name)
        if (identifiers.has(element.id)) {
          // report an error if the identifier is not unique
          accept("error", `Duplicate name '${element.id}'`, {
            node: element,
            property: "id",
            code: "duplicate_id",
          });
        } else {
          identifiers.add(element.id);
        }
      }

      if (element.$type === "Graph") {
        // Recurse
        for (const e of element.elements) {
          traverseElement(e);
        }
      }
    }

    // Traverse the elements in the model:
    for (const element of model.elements) {
      traverseElement(element);
    }
  };

the code property is then used as a way to select the proper code action, as in:

import { CodeActionKind, Diagnostic } from "vscode-languageserver";
import { CodeActionParams } from "vscode-languageserver-protocol";
import { Command, CodeAction } from "vscode-languageserver-types";
import { AstUtils, LangiumDocument, MaybePromise } from "langium";
import { CodeActionProvider } from "langium/lsp";
import { isElement, isStyle } from "../language/generated/ast.js";

export class GraphCodeActionProvider implements CodeActionProvider {
  getCodeActions(
    document: LangiumDocument,
    params: CodeActionParams,
  ): MaybePromise<(Command | CodeAction)[]> {
    const result: CodeAction[] = [];
    if ("context" in params) {
      for (const diagnostic of params.context.diagnostics) {
        const codeAction = this.createCodeAction(diagnostic, document);
        if (codeAction) {
          result.push(codeAction);
        }
      }
    }
    return result;
  }

  private createCodeAction(
    diagnostic: Diagnostic,

    document: LangiumDocument,
  ): CodeAction | undefined {
    switch (
      diagnostic.code // code as defined in 'graph-validator.ts' for each validation check
    ) {
      case "duplicate_id":
        return this.generateNewId(diagnostic, document);
      /*
      case "name_lowercase":
        return this.makeUpperCase(diagnostic, document);
      */
      default:
        return undefined;
    }
  }

  // Define the code actions:

  private generateNewId(
    diagnostic: Diagnostic,
    document: LangiumDocument,
  ): CodeAction {
    const rootNode = document.parseResult.value;
    const existingIds = new Set<string>();

    // Collect all existing IDs in the AST
    for (const childNode of AstUtils.streamAllContents(rootNode)) {
      if (
        (isElement(childNode) || isStyle(childNode)) &&
        childNode.id !== undefined
      ) {
        existingIds.add(childNode.id);
      }
    }

    // Ensure that the element is valid and has a type
    const element = rootNode;
    if (!("$type" in element) || typeof element.$type !== "string") {
      return undefined!;
    }

    // Generate a new ID based on the first letter of the type
    // TODO - replace with the current node instead of the root node (which always is of type 'Model'):
    const baseId = element.$type.charAt(0).toLowerCase();
    let counter = 1;
    let newId = baseId + counter;

    while (existingIds.has(newId)) {
      counter++;
      newId = baseId + counter;
    }

    return {
      title: "Generate new id",
      kind: CodeActionKind.QuickFix,
      diagnostics: [diagnostic],
      isPreferred: true,
      edit: {
        changes: {
          [document.textDocument.uri]: [
            {
              range: diagnostic.range,
              newText: newId,
            },
          ],
        },
      },
    };
  }
}