Changelog

0.20.1b1

Released:

17.11.2025

pre-release:

🔧 Fixes

This pre-release fixes an issue with the deployment of the last pre-release, whereby for some platforms incorrect binaries were bundled with the VS Code extension.

0.20.0b1

Released:

12.10.2025

pre-release:

New and Improved

  • ✨ Enhanced Type Safety with Sphinx-Needs v6 Compatibility

    ubCode now includes comprehensive typing support to mirror sphinx-needs v6.

    This includes:

    • Added schema option to the need extra options configuration, allowing you to define and enforce value types for custom need fields

    • Full type validation for need extra options (string, bool, int, float, and list variants)

    • Improved handling of nullable extra options for more flexible need definitions

    • Type-aware filtering and querying of needs

    For example:

    [[needs.extra_options]]
name = "effort"
description = "Story points (Fibonacci sequence)"

[needs.extra_options.schema]
type = "integer"
enum = [1, 2, 3, 5, 8, 13, 21, 34]
description = "Must be a Fibonacci number"

    See Extra options configuration for more details.

  • ✨ Ontology Schema Validation

    New (experimental) CLI command ubc schema validate provides comprehensive validation of your project’s need schema and ontology:

    • Validates need type definitions against configured schemas (using the needs.schema_definitions_from_json configuration)

    • Checks consistency of extra options and their types across the project

    • Ensures compliance with ontology rules and constraints

    • Provides detailed error reporting for schema violations

    ubc schema validate

    See the Configuration and CLI documentation for more information.

  • ✨ Model Context Protocol (MCP) Server Integration

    The VS Code extension now includes a built-in MCP server that provides:

    • Programmatic access to project needs and metadata

    • Query interface for external tools and AI systems

    See the MCP server documentation for more details on using the MCP server.

  • ✨ Enhanced Graph View with Extended Depth

    Significant improvements to the need graph visualization:

    • Added toolbar with configurable maximum distance buttons for exploring need relationships

    • Extended depth graph traversal for better visualization of complex need hierarchies

    • You can also now open the needs graph view directly from a need directive in your rST files, or from the command pallete.

    Needs Graph View

    Needs Graph View

    See the needs graph view documentation for more information on using the graph view.

  • ✨ Project Comparison with Diff Command

    New CLI command ubc diff enables comparison of schemas and needs between two projects:

    • Compare need schemas across different project versions

    • Identify differences in need definitions, types, and configurations

    • Export comparison results in multiple formats

    • Useful for project evolution tracking and compatibility checking

    • Capability to look into the Git history

    See the CLI documentation for more information.

    ubc diff --project project1/ --project project2/
ubc diff --format html -o report.html --project project1/ --project project2/
ubc diff --needs _build/needs.json --project project2/
ubc diff git

  • ✨ Advanced Filtering Syntax

    Expanded filtering capabilities with new syntax support:

    • Variable-to-variable comparisons

    • Support for len(var) expressions in Python queries

    • Enhanced string operations like "text" in var.upper()

    • Improved type handling for list[bool] variables

    See the Filtering documentation for more details.

  • ✨ Variant Options Configuration

    Added needs.variant_options configuration option:

    • Define variant-specific need option sets

    • Support for conditional need field configurations

    • Enhanced flexibility in multi-variant documentation projects

    • Improved variant syntax parsing from sphinx-needs

    variant_options = ["status", "priority", "assignee"]

    See the Variant options configuration for more details.

  • ✨ Improved JSON Import/Export

    Enhanced handling of needs data in JSON format:

    • Better support for importing needs with complex type structures

    • Improved error handling when importing needs with invalid field types

    • More robust JSON export capabilities for needs data

    • Enhanced testing and validation of JSON import/export workflows

0.19.1

Released:

08.10.2025

  • 👌 Add --config-name option to CLI commands, for overriding the configuration file name (default ubproject.toml).

  • 🐛 Fix file discovery hanging. This reverts a change from 0.19.0, which caused file discovery to hang in certain cases.

0.19.0

Released:

18.09.2025

New and Improved

  • ✨ Add need graph view to VS Code extension

    This view shows a graphical representation of a need in the current project, along with its incoming and outgoing links.

    The graph is interactive, allowing for zooming, panning, and clicking on nodes to reveal more information about each need.

    See also

    The needs graph view documentation for more information on using the graph view.

0.18.1

Released:

09.09.2025

Fixes

  • 🐛 FIX: Relative paths in symlinked ubproject.toml

    Relative paths are now resolved relative to the location of the symlink, rather than the real file location it links to, for example:

    extend = "../parent.toml"
project.srcdir = "source"

    A key use-case this fixes is within Bazel use, when the entire project is symlinked to a different location.

  • 🐛 Fix OSS license detection in certain user environments

0.18.0

Released:

02.09.2025

New and Improved

  • ✨ Free usage for OSS repos

    ubCode is now free to use for open source projects! See the licensing section for more details.

  • ✨ Add doc references to VS Code std domain tree view

  • ✨ Add VS Code jump-to-definition for doc and term roles

  • 👌 Add --srcdir option to ubc build targets CLI command.

    To allow for override of the project.srcdir. Additionally, issue with generating docname’s are logged in debug mode.

0.17.0

Released:

21.08.2025

New and Improved

  • ✨ Add parsing of glossary directives and gathering of term reference targets, for example:

    .. glossary::

  term1
  term2
      Definition of term1.

    These are now viewable in the VS Code standard domain index tree view, and are output in the objects.inv, when running ubc build targets --format inv.

  • ✨ Add initial capture of reference target implicit titles, for example the target_name below will have the title A Title:

    .. _target_name:

A Title
=======

    These are now viewable in the VS Code standard domain index tree view, and are output in the objects.inv, when running ubc build targets --format inv.

0.16.0

Released:

12.08.2025

New and Improved

  • ✨ Add Jump to definition, for standard domain references, in the VS Code extension.

  • ✨ Experimental output of objects.inv via CLI: ubc build targets --format inv. This will output a Sphinx objects.inv file (see intersphinx), which can be used for cross-project references. Note, this is an experimental feature, that does not yet capture all data that sphinx does, and may change in future releases.

  • ✨ Capture document titles when indexing. This is taken from the first section heading in the document, if present, and is included in the built objects.inv file above as doc targets implicit titles.

  • ✨ Add ubc build list-documents CLI command, to print out a list of the documents that would be indexed for a project.

Fixes

  • 🐛 Fix source config include/exclude glob pattern resolution. This is intended to follow ruff file discovery, but was not resolving user supplied glob patterns relative to the root of the project. See source configuration for more details.

0.15.0

Released:

18.07.2025

New and Improved

✨ Added indexing, duplicate diagnostics and VS Code tree view support for standard cross-project reference targets.

Targets are gathered from reStructuredText block, inline and citation syntax, and certain directive name options, e.g.

.. _target_name:
.. [citation_name] A citation

.. note::
   :name: target_name2

   This is an _`inline` target.

Target names are case and whitespace normalised, as per the Sphinx specification.

Additionally, these targets, plus footnote and substitution definitions, are diagnosed for duplicate names at a local file level, and issues are highlighted in-line within the text editor. New diagnostic codes are:

  • std.duplicate_target

  • std.duplicate_citation

  • std.duplicate_footnote

  • std.duplicate_substitution

Fixes

  • 🐛 Fix substitution definition parsing and formatting. The content of substitution definitions is now correctly parsed, allowing for language features (e.g. autocompletion) to work within them.

    .. |substitution_name| replace:: This is replacement text with **bold** text and *italic* text.

0.14.0

Released:

02.07.2025

New and Improved

Added autocompletion and hover previews for image and figure directives in rST files.

Autocompletion is triggered after typing / as the last character of the argument, and if not a remote or embedded (data) image. As per sphinx, this will complete relative to project.srcdir (defaults to ubproject.toml folder) if the argument starts with / or relative to the document’s directory otherwise. Also as per sphinx, arguments are “normalised” to resolve backslash-escapes and remove unescaped spaces.

Completions will be shown for all image files found in the source tree, that (a) are not gitignored, and (b) adhere to a set of file patterns, configurable in ubproject.toml.

Hover previews will show if the image is remote, embedded or found locally and has an HTML compatible file extension, or if the extension is the * wildcard and a file with a compatible extension is found. This can also be activated or deactivated in the ubproject.toml file.

.. image:: /path/relative/to/srcdir/image.png
.. figure:: ./path/relative/to/document/image.*
.. image:: https://remote.server/image.png
.. image:: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...

[server]
image_file_patterns = ["*.jpg", "*.jpeg", "*.png", "*.gif", "*.svg", "*.webp", "*.bmp", "*.tiff", "*.tif", "*.ico", "*.heif", "*.heic", "*.avif", "*.eps", "*.psd", "*.ai", "*.pdf"]
hover_images = true

Fixes

  • 🐛 Show correct total issue count, for the VS Code diagnostic tree, when there are greater than 10,000 issues.

0.13.0

Released:

15.06.2025

New and Improved

Added quick look-up features for needs in the Language server and VS Code extension: ubCode now creates a fast-lookup index for needs, which allows for quick access to need details and references. This index has allowed for the following feature implementations, in this release, and more to come in the future.

  • ✨ need ID autocompletion (note these can be triggered by CTRL+SPACE):

    Autocompletion can be activated for need, need_incoming and need_outgoing roles, after the first backtick and for partial IDs, for example cursor positions:

    :need:`
       ^
:need_incoming:`partial`
                       ^

    They can also be autocompleted for directive link options, such as:

    .. req:: A need with a link
   :link_name1:
                ^
   :link_name2: id1,partial
                          ^

    New IDs are also suggested for the id option of need directive, based on the configured need type prefix (in ubproject.toml) and the “next available” integer suffix.

    .. req:: A need with no ID yet
   :id:
       ^

  • ✨ need ID hover information

    Hovering over a need ID in a role or directive link option will show basic details of that need.

    This can be enabled/disabled in the ubproject.toml, by setting the server.hover_need_id configuration option to true or false:

    [server]
hover_need_refs = true

Additionally, the following features have been added:

  • ✨ Added “Go to source” for links in VS Code needs tree view

  • 👌 Added part ID source retrieval for VS Code needs tree view

Fixes

  • 🐛 rST formatter: fix underline length for title with emojis

  • 🐛 quickstart: fix naming of incoming/outgoing link names

0.12.0

Released:

12.05.2025

New and Improved

This release introduces a new formatter for reStructuredText (rST) files. It can be used via:

  1. The VS Code extension, to format complete documents (ALT+SHIFT+F) or selections of text (CTRL+K CTRL+F)

  2. The ubc format CLI command to format one or more files/folders. Note, currently one must use ubc format --preview to run this command, since the functionality is in Beta.

  3. A ubc format --check CLI command option, to check if file contents would have changed during formatting, but not actually modify the files. If any would change then a non-zero exit code is emitted.

Note, in order to ensure the formatter preserves the original “syntax structure” of the text, a comparison is made, between the original and formatted syntax, before the formatted text is written to file. If there are differences, the formatting will error and the new content will not be written.

On trialling the formatter on known projects, it was found that this comparison could fail when formatting blockquotes, i.e. indented blocks of text, since changes in indenting relative to preceding syntax blocks could change its interpretation. Moreover, these existing blockquote blocks were often an unintended result of mis-indented text, e.g.

* bullet point

   block quote as part of bullet item

 block quote after bullet list

Therefore, a linting rule has also been added warning against bare blockquotes, in favour of using specific directives:

block.bare_blockquote: Bare blockquotes can lead to ambiguous parsing, instead use the pull-quote or epigraph directives.

This rule then encourages the more explicit syntax:

* bullet point

  .. pull-quote:: block quote as part of bullet item

.. pull-quote:: block quote after bullet list

0.11.0

Released:

17.04.2025

New and Improved

  • ✨ Add server.index_on_save configuration

    Setting server.index_on_save = true in the ubproject.toml will cause the project indexing be triggered for every save of a file in that project (currently only .rst files).

  • ✨ Add ubc quickstart

    For creating an new example ubCode project.

  • ✨ Add handling of need parts, including:

    • Parsing:

      • parse need_part / np roles and storing parts in the needs index

      • parse parts sections in needs.json, for external and imported needs

    • Diagnostics

      • Creating warnings for need_part / np roles that are not within need directives

      • Create warnings for need / need_incoming / need_outgoing that reference non-existent ID.PART_ID

    • Writing

      • Write parts section to needs.json

    • VS Code

      • Show parts in needs index tree view (including jump-to-part)

      • Jump to defining need_part / np role, from need / need_incoming / need_outgoing roles

      • Show references from need_part / np role

      • “Select ID” in needs index tree view, from need_part / np role

  • 👌 Correctly handle title_from_content option in needs directives

  • 👌 Correctly handle id_prefix for links in external and imported needs

Fixes

  • 🐛 Do not show empty outgoing link sections in VS Code needs index tree view

0.10.0

Released:

11.04.2025

New and Improved

  • ✨ Parse need, need_incoming and need_outgoing roles.

    These roles are now stored in the index, allowing for:

    • “Referencing Roles” section of the LSP needs index view, per need

    • “Jump-to-definition” and “Find all references” when selecting the role

    • Roles are included in “Find all references” for the need ID

    • needs.link_ref diagnostics are emitted for roles referencing unknown need IDs

  • ✨ Add config lint.lsp_select

    Specify a list of linting codes to select in LSP file diagnostics, which overrides the lint.ignore list. This is useful for users transitioning to ubcode, who want to ignore existing linting violations in CI checks, but show them to users in the VS Code extension.

0.9.0

Released:

07.04.2025

New and Improved

  • ✨ First official release on the VS Code Marketplace.

    With this version the ubCode extensions leaves the pre-release state.

    Note

    The extension is made available in a release state for better accessibility. It should be noted though, that ubCode is still in beta phase and not yet feature complete in terms of Sphinx-Needs support.

  • ✨ First official release of the ubCode CLI app ubc.

    The CLI provides a way to view all diagnostics of projects in the terminal. Projects can be built and exported to various formats. Finally, licenses can be viewed and activated.

    Download ubc for your platform from:

    Platform

    URL

    Windows (x64)

    https://download.useblocks.com/ubc/0.9.0/ubc-windows-x64-0.9.0.exe

    macOS (arm64)

    https://download.useblocks.com/ubc/0.9.0/ubc-darwin-arm64-0.9.0

    Linux (x64)

    https://download.useblocks.com/ubc/0.9.0/ubc-linux-x64-0.9.0

    Linux (arm64)

    https://download.useblocks.com/ubc/0.9.0/ubc-linux-arm64-0.9.0

    The files are directly executable on all platforms and have no dependencies. The first execution might be a bit slower due to the bootstrapping process of the application.

    See the Installation section for latest links and installation instructions.

  • ✨ Add dynamic function parsing

    ubCode is now aware of the dynamic function syntax (e.g. [[func()]]) and checks for syntax errors. Dynamic functions are not yet executed, but will no longer show in link ID lists.

  • ✨ Write Kuzu DB from needs.json

    A needs.json can now be converted to a Kùzu graph DB. Kùzu version is 0.9.0 (storage version 37).

Fixes

  • 🐛 Omit ignored diagnostics codes from diagnostic tree view

  • 🐛 Omit warnings for allowed global_options constraints/layout/style keys

0.8.0

Released:

13.03.2025

Breaking Changes

The handling of licenses has been refactored to handle more licensing scenarios, including offline licenses and system proxies for license activation.

This has necessitated a change in the configuration file format, from ubcode.key.text to ubcode.toml, and must now also include a user e-mail/identifier:

[license]
key = "AAAAA-BBBBB-CCCCC-DDDDD"
user = "mail@example.com"

See License configuration for more information.

New and Improved

  • ✨ Add Diagnostics tree view to VS Code.

    This view shows all diagnostics encountered during the project index, such as linting errors and duplicate need IDs, and allows for filtering by diagnostic code

  • ✨ Add handling of needs.global_options configuration.

    This allows for the definition of defaults for need fields. It follows the new format as introduced in sphinx-needs v5.1.0 (see needs_global_options for more information).

0.7.0

Released:

25.02.2025

Breaking Changes

New and Improved

  • ⚡️ Improve speed of index build: the index build is now ~33% faster for large projects.

  • ✨ Add support for Python filter expressions in need queries. See Python syntax for details.

    This is exposed in the needs index view in VS Code, using the “Select ubcode need ID or filter in view” command, and allows for support of the filter option in needimport and needextend directives.

  • ✨ Compute closest match for unknown directive name/option

    This is used to provide quick fixes for unknown directive names and need directive options.

0.6.2

Released:

04.02.2025

Fixes

  • 🐛 ubCode Marketplace URLs

0.6.1

Released:

04.02.2025

New and Improved

  • 👌 Add quickstart command

  • 👌 Add chain option to the scripts configuration

  • 📚 Improve the documentation

0.6.0

Released:

03.02.2025

New and Improved

  • 👌 Add diagnostic for unknown need directive options.

  • 👌 Add autocompletion of needextend directive options.

  • ✨ Add need directive status auto-completions, with items from needs.statuses configuration, if set.

  • 👌 Add config needs.external_needs.skip_in_ubcode, which will skip reading of the external source when indexing.

  • ✨ goto definition / references for need directive links, when cursor is on the link value:

    .. req::
  :link_name: value
              ^^^^^

  • ✨ Add “select ubcode ID in view” command. Available in command palette or right-click menu.

  • ✨ Add scripts configuration and use in VS Code, for defining/running commands in the terminal (see Configuring a project with ubproject.toml):

    [scripts]
sphinx = "sphinx-build -b html . _build/html {{filepath}}"
sphinx = { cmd = "sphinx-build -b html . _build/html {{filepath}}", env.SPHINXOPTS = "-W", terminal = "name", jinja = true }

    In VS Code they can be accessed via the command palette (Ctrl+Shift+P) by selecting “ubCode: Run Command in Terminal”.

  • 👌 Add Project item to needs index view, with configuration, current file and indexing issues children.

  • 👌 Add n.is_directive, l.type, o.id filter fields for needs index view.

  • 👌 Persist needs index view filter query, when re-starting VS Code.

  • ✨ Add context button to open external URLs in need index view, for needs originating from external sources. These are resolved from the base_url / target_url on the extend_needs configuration.

  • 👌 Add restart server button to home view.

0.5.0

Released:

29.01.2025

New and Improved

  • ✨ Cache license checks for offline use. The remote license check is now cached for 3 days, allowing for offline use during this time.

  • ✨ Add processing of needextend directives. These directives are now gathered and applied to the needs index. Needs with associated needextend can be filtered for in the index tree view, using the n.is_modified filter expression.

    Note, currently only needextend with “single ID” filters are applied; expression filter processing is planned for a future release.

  • 👌 Make external need reads more fault tolerant. External needs.json with invalid extra/link field value types will no longer error the entire read. Instead, the errors are stored (and reported in the tree view) and the fields are skipped.

  • ✨ Add Linux ARM64 build target

0.4.0

Released:

22.01.2025

New and Improved

  • ✨ Add external and import needs parsing:

    • Add needs.import_keys configuration

    • Add project.srcdir configuration (to resolve needimport sources starting with /)

    • Note, the filter option of needimport is not yet supported

  • VS Code index tree view:

    • ⚡️ Improve performance of updates and item expansion

    • ✨ Show need indexing issues

    • 👌 Expand querying capabilities

    • 👌 Add copy link ID to clipboard buttons for incoming/outgoing need links

  • 👌 Improve rst-preview CSS: do not word-wrap directive option names

  • 👌 Complete find references on directive id named_option

0.3.0

Released:

12.12.2024

New and Improved

  • ⚡️ Improve performance of diagnostics/needs index builds.

    Including parallel file reads, better caching, and background (non-blocking) processing.

  • ✨ Add initial filtering of needs in index tree-view.

    Using a sub-set of the Cypher query syntax.

    Note, currently it is constrained to n.id and n.type queries; this will be expanded in the future.

  • ✨ Add find references for need directives.

    Activated by placing the cursor on the directive name, and using the context menu or pressing SHIFT+F12.

  • ✨ Add quick fix for inline.role_no_name diagnostic.

  • 👌 Add index directive to built-ins.

  • ✨ Add “Re-index project” to VS Code command palette.

  • ✨ Add “Remove project cache” to VS Code command palette.

  • 👌 Open license path from VS Code Home tree.

0.2.3

Released:

03.12.2024

New and Improved

0.2.2

Released:

24.11.2024

Improved

  • ✨ Add extend configuration, for sharing configuration between multiple projects (see Configuring a project with ubproject.toml)

  • ✨ Add auto-completion and hover information of directives in rST files

  • 👌 Graph DB performance improvements

0.2.1

Released:

21.11.2024

Fixes

  • 🐛 Build manylinux2014 compatible wheels to support systems such as Ubuntu 20.04 LTS

0.2.0

Released:

20.11.2024

Initial release of the new ubCode VS Code extension.

This is a complete rewrite of the existing ubCode extension (v0.1.2).

This version features a new language server that understands RST, generates HTML previews in real-time and provides diagnostics for RST problems.

The extension integrates with Sphinx-Needs via a new ubproject.toml file format. The new needs index can be used to navigate to needs without running a Sphinx build.