Treqs Vscode

T-Reqs is a text-based requirements management solution based on the git version control system. With it's success and rising in recent years, we identified a need for the tool's VS Code extension that includes graphical interface enhancements to provide a more user-friendly experience. The goal of this project is to build a VS Code extension with a GUI for T-Reqs.

Table of Contents

• Treqs Vscode
• Description
• Requirements Documentation
• Visuals
• Installation
• Usage
• Support
• Roadmap
• Contributing
• Authors and Acknowledgment
• License
• Publish
  • Automatically
  • Manually

Description

T-Reqs has proven to be a suitable tool for managing requirements in agile and large scale projects in recent years. Howvwer, its lack of a user-friendly interface has created obstacles for broaders adoption and users who are not familiar with the command line interface.

With this project, we bring T-Reqs functionalities in a VS Code extension as well as we offer a user-friendly GUI while we keep the strendths of the original tool.

Overview of the Developed Extension

All major features of T-Reqs are supported and accessible in multiple ways, including a GUI interface and context menus. The extension features a sidebar with buttons and form fields. All the actions accessible there are also accessible by running a VS Code command, which can be assigned to hotkeys. The extension also supports several of these features from a language server, providing autocompletion, error diagnostics, previews, and suggestions while editing documents. These features further reduce the reliance on users manually managing IDs. Most of the features directly use treqs-ng as a back-end, which is automatically installed and configured on the user device, if all dependency requirements are met. The extension is available for download on the VS Code marketplace and the source code on GitLab.

Delivered Functionality

Error Checking

Figure: Error checking using in-editor diagnostics and single-file scanning

Helping the user ensure that the T-Reqs data are well formed was a priority, as many traceability features would not work otherwise and because the feature was highlighted as one often used by the interview participants. To support this, we have implemented error checking in three different ways, each providing their own benefits. One mode of interaction is to manually call the function, from either the sidebar, the runTreqsCheck command, or the file tree context menu. The directories to be scanned can be specified and a user-friendly output view of any errors will be displayed.

The second way is implemented as an automatic, file-level check that triggers when the user opens or saves the file. Any errors within that file will be notified to the user using a status bar element, providing immediate feedback.

The language server provides the final layer of error checking, in the form of diagnostics. The detected errors will be immediately highlighted within the editor as the user is typing, providing instant and clear feedback. Details of the errors can be displayed along with ways to resolve them.

Creating Elements

Figure: Creating elements using the editor suggestions

Being a simpler feature, only two ways of creating T-Reqs elements are provided. The first one uses functionality from the original T-Reqs CLI in the backend, to provide creation with ID generation and templating supported. It can be accessed by running the runTreqsCreate command, using the in-editor context menu, or from the sidebar, which supports the creation of multiple elements at once. The elements will be created at the position of the pointer or around the selected text.

The second way is using the language server-provided auto-completion snippets. These conveniently guide the user through the element creation, without interrupting their typing. It provides documentation and completion for the element and its attributes. The language server also provides syntax highlighting for the elements, regardless of which file type they are in. Regardless of which method is used, the extension will comment out the T-Reqs tags to not interfere with source code and allow the user to select the element type from the ones available in the ttim.yaml configuration file in the project root directory.

Creating Links

Figure: Creating links with editor suggestions

Three methods exist for creating links. When accessing the feature through the context menu or the runTreqsCreateLink command, the link will be created and copied to the user's clipboard. If the user selected an ID of an element, that will be the target of it and the link types will be filtered based on the allowed inlinks for that element. This makes it efficient to create multiple links to the same element. Pressing the button in the sidebar instead will create the link at the cursor position.

The language server also provides autocompletion for links and uses the surrounding context of the link placement to filter the selectable link types according to the T-Reqs configuration file ttim.yml. To select a target element, the user can simply start typing the label, select it, and the ID will be filled in. This minimizes the chance for errors and the definition of invalid relationships between elements, while also speeding up the element creation process. This supports use-case~\ref{uc:abstract-ids} as it minimizes the required direct user access with IDs.

Listing Elements

Figure: Listing elements using the sidebar

To list the T-Reqs elements, one can run the runTreqsList command, use the file-tree context-menu, or access all options by running it from the sidebar. Running it will show all T-Reqs elements within the workspace in a clear and accessible format, allowing users to filter them based on type and attribute. Requirements include hyperlinks to allow navigating to their definition, and they can also be edited in place. This allows managing requirements conveniently within a single, intuitive interface, even if they are defined in multiple files throughout the workspace.

PlantUML Overview

Figure: Displaying PlantUML sideview from the file tree context menu

Displaying a PlantUML overview of the elements and links provides a similar function to the normal listing of elements, but provides a more comprehensible overview of relationships and connections. It can be run using the runTreqsListPlantUML command, the file-tree context-menu, or the sidebar. Using the sidebar, it supports the same filtering options as when listing elements normally. These methods will display a static diagram of the selected files. There is also an option to display the view for the current file, using the button in the editor title menu. The default mode when opening the view with this mode is for the window to always display the contents of the active editor file, even as a new one is selected. The view contains a checkbox to freeze the view on a specific file, useful for opening multiple PlantUML diagrams at once.

Process Feature

T-Reqs process is a feature from the base version of T-Reqs that makes PNG images from embedded PlantUML diagrams. Our interviews suggest that it is the least used feature, so it is kept simple in the extension. It can be executed from the sidebar or by running the runTreqsProcess command. Once started, it can be stopped from the sidebar or by running the stopTreqsProcess.

Other Features

• Hovering on the link target ID will display a popup of the target element. Executing Go to Definition on the ID will also navigate to the target element.
• For new or less experienced users to T-Reqs we provide built-in documentation for elements and links.
• UUIDs for elements can be generated from the sidebar, the runTreqsGenerateId command, or from an in-editor suggestion.
• The openTreqsTerminal command will open a terminal window allowing access to the extension's T-Reqs installation to use the CLI.

Architecture Diagram

Figure: Architectural diagram of the extension

Requirements documentation

The requirements for the project are documented in the GitLab wiki.

Visuals

Usage

DEMO video for current available frature

Some screenshots of the extension in action:

Installation

Requirements:

• Python (>= 3.8.0)
• VS Code (>= 1.0.0)

You can use npm to install the dependencies.

npm install

dependencies that have to be installed manually, also add a Requirements subsection.

Support

Contact the authors team for support.

Roadmap

Cycle 1: 15/03/2025 - 25/04/2025

• Generate UIDs automatically
• Visualize requirement structures
• Users can interact with T-Reqs through an extension interface
• View referenced elements inline via inlay hints
• Navigate requirements via "Go to Definition"
• Quick create and edit as well as tags via autocompletion
• A dedicated sidebar for custom webview panel
• Command palette that has all T-Reqs commands
• Visualize T-Reqs elements using a dynamic table view with editable fields
• A metadata (ttim.yaml) for requirement modeling
• Using Tree-sitter for fast and robust parsing
• Create T-Reqs elements
• Create T-Reqs links
• List T-Reqs elements
• Automatically test & publish extension in pipeline
• Create Tree-sitter grammar for the T-Reqs markup language
• Create Tree-sitter parser
• Show diagnostic messages for errors in T-Reqs elements and links
• Parse ttim.yaml file into T-Reqs model for error checking and suggestions
• Show documentation while typing tag
• Show entire information while hovering on target ID

Cycle 2: 28/04/2025 - 06/06/2025

[TODO] - Update

• Reinstall python packages on extension update (#70)
• Add duplicate element ID check to diagnostics (#69)
• Make diagnostics project-wide (#68)
• Create other method for creating links (#66)
• Modify tree-sitter-treqs grammar (#53)
• Fix linking target ID by using parser (#47)
• Syntax highlight LSP (#44)
• Automatically save treqs list changes (#43)
• Add open treqs terminal command (#42)
• Add file tree commands (#41)
• Allow custom path for .treqs-ignore (#38)
• Allow creation of multiple treqs elements at once (#37)
• Initialize treqs model when a new workspace/project is opened (#34)
• Setup treqs project command (#24)
• Optimise extension package (#??)
• Add main use-cases (#61)

Contributing

[TODO] To be discussed.

Authors and acknowledgment

Created by:

• Yingchao Ji

• Henrik Lagrosen

• János Litkei

• Piotr Ostrowski

• Linh Pham

• Shiyao Xin

Supervisor: Eric Knauss

License

Licensed with the MIT License.

Publish

Automatically

Create a semantic tag in the format vX.Y.Z in the GitLab repository. This will trigger the GitLab pipeline to publish the extension to the marketplace automatically. The version code needs to be higher than the last version in the marketplace.

Manually

npm i

# In the node_modules directories in client and server, there is now a symlink to treqs-ts which will prevent vsce package from working. You have to remove them and replace them with the real treqs-ts package.

npx vsce login treqs-vscode
npx vsce package --follow-symlinks --no-git-tag-version -o extension.vsix

# Publish as pre-release
npx vsce publish --pre-release --follow-symlinks --no-git-tag-version  -i extension.vsix

More info can be found in the VS Code guide