Changelog

0.25.0

Released:

10.03.2026

✨ New Features

  • Mermaid diagram rendering in the RST preview

    The RST preview panel now renders .. mermaid:: directives as live diagrams, building on the image and figure rendering introduced in 0.23.0. Rendering is highly responsive — diagrams update instantly as you type, without flickering or disappearing while you edit other parts of the document. Diagrams also adapt automatically to your VS Code color theme.

    As with image preview, this feature requires ubcode.preview.experimentalRendering to be enabled in your VS Code settings (or toggled via the preview toolbar button).

    Caution

    External file references (e.g. .. mermaid:: path/to/file.mmd) are not yet supported; only inline diagram source is rendered. External file support is intended for a future improvement.

👌 Improvements

  • Significantly reduced needs index size

    The needs index now deduplicates field values that match their schema defaults, dramatically shrinking cached index files and speeding up load times. As a reference point, a project with ~40,000 needs and ~120 custom fields sees its cached index shrink from 109 MB to 31 MB and loads ~5x faster.

    This means noticeably faster startup for VS Code features that depend on the index — particularly the Needs Index tree view and the Need graph view — as well as faster incremental builds, CLI commands, and MCP queries.

0.24.1

Released:

04.03.2026

✨ New Features

  • Config override support in the VS Code extension

    The VS Code extension now exposes two new settings, ubcode.server.configOverride and ubcode.mcp.configOverride, that let you override any ubproject.toml value directly from your editor settings without modifying the project file.

    Each setting accepts a JSON object whose keys and values mirror the TOML configuration. The overrides are serialized to TOML and passed to the language server (via a -c CLI flag) and the MCP server (via the UBCODE_CONFIG_OVERRIDE environment variable), respectively.

    A prime use case is controlling variant resolution (added in 0.24.0) on the fly. For example, to change the active build_tags without editing ubproject.toml:

    {
  "ubcode.server.configOverride": {
    "build_tags": ["html", "draft"]
  }
}

    This makes it easy to switch between build variants while developing, and to preview how different tag combinations affect your requirements. Changes to either setting take effect immediately: the language server restarts and the MCP server definition is refreshed automatically.

0.24.0

Released:

03.03.2026

✨ New Features

  • Variant resolution for needs

    Need fields and links can now contain variant functions using the <<...>> syntax, allowing conditional values that resolve based on configured variants and filter data. This implements the Sphinx-Needs variant functions feature, bringing ubCode closer to full feature parity with sphinx-needs. See Supported toolchain for the full list of supported configurations, and Configuring a project with ubproject.toml for configuration details.

    Three expression forms are supported:

    • Named variants (<<name: value_if_match, fallback>>): name is looked up in the [needs.variants] configuration mapping.

    • Bracketed expressions (<<[expr]: value_if_match, fallback>>): expr is evaluated directly as a filter expression.

    • Fallback values: the last comma-separated value is used when no expression matches.

    For example:

    .. req:: My requirement
   :id: REQ_001
   :status: <<is_open: active, inactive>>

    Variant resolution runs after needextend processing, so extended field values are available to variant expressions. Resolved values are fully validated downstream. Parse and evaluation errors are surfaced as needs.variant diagnostics.

    Variant syntax is only parsed for fields that opt in: either by setting parse_variants = true in the field’s needs.fields schema (sphinx-needs v7+), or by listing the field name in variant_options.

    Incremental builds only re-resolve needs that have changed, and a pre-parsed expression cache avoids redundant work during parallel resolution.

  • build_tags configuration attribute

    A new build_tags list can be set in ubproject.toml to declare the active build tags for a project. This replicates the Sphinx tags feature, making the same set of tags available to variant filter expressions as a list variable and enabling build-target-conditional field values.

    For example, given the configuration:

    build_tags = ["html"]

[needs.variants]
is_html = "'html' in build_tags"

    a need with :status: <<is_html: web_only, general>> will resolve to web_only when html is in build_tags, or general otherwise.

    Tags can also be overridden from the CLI using the -c option, without modifying ubproject.toml:

    ubc build index -c "build_tags = ['html', 'draft']"

    or via the UBCODE_CONFIG_OVERRIDE environment variable.

    See Configuring a project with ubproject.toml for full documentation.

0.23.0

Released:

26.02.2026

✨ New Features

  • Experimental image preview rendering

    The RST preview panel can now render image and figure directives as actual images, rather than displaying them as generic directive markup. Both local images (resolved relative to the source or document directory) and remote URLs are supported. Local image paths are securely served via VS Code’s webview URI mechanism.

    Images in RST preview

    To enable this feature, set ubcode.preview.experimentalRendering to true in your VS Code settings, or use the new toolbar toggle button in the preview panel. The toggle state persists across sessions.

    This complements the existing hover previews and missing-image diagnostics (image.not_found) introduced in earlier releases, providing a more complete image authoring experience within the editor.

    This is the first step toward a richer preview experience that we eventually hope to include items such as admonitions, syntax-highlighted code blocks, math equations, and diagram rendering (PlantUML, Mermaid, Graphviz).

0.22.0b1

Released:

20.02.2026

pre-release:

♻️ Refactor

  • Ported ublicense from Python to Rust

    The license management library has been fully rewritten in Rust, replacing the previous Python implementation. The port is feature-complete and includes online/offline licensing, OSS license detection, machine identification, HMAC-signed caching, and proxy support.

    This brings several benefits:

    • Faster license validation and caching

    • Improved error reporting with more granular error types

    • Stronger cache integrity

    Please test this pre-release and report any licensing issues you encounter.

0.21.0

Released:

19.02.2026

This release consolidates all changes from the 0.20.x pre-release series (0.20.0b1 - 0.20.6b1).

✨ New Features

  • Comprehensive schema validation

    Need extra options and links are now validated against JSON Schema during indexing, with support for typed fields (string, bool, int, float, list variants), custom needs.fields definitions, and needs.schema_definitions_from_json ontology rules. Real-time LSP diagnostics cover a broad set of JSON Schema constraints. Also available via the ubc schema validate CLI command.

  • Dead link validation

    Outgoing links targeting non-existent need IDs or part IDs now emit needs.dead_link diagnostics, with incremental re-checking and per-link-type opt-out via allow_dead_links.

  • Fine-grained lint suppression

    New lint.per-file-ignores and lint.message-ignores options allow targeted suppression of diagnostics by file glob pattern, code, or message substring.

  • needs.links dict-based configuration

    A new dict-based [needs.links] format for defining link types, aligning with the upcoming sphinx-needs v7 release.

  • Model Context Protocol (MCP) server

    Built-in MCP server in the VS Code extension provides programmatic access to project needs and metadata for external tools and AI systems.

  • Enhanced graph view

    Need graph visualization with configurable depth, toolbar controls, back/forward navigation, zoom, and “Go to Source” action.

  • Project comparison with ubc diff

    CLI command for comparing schemas and needs between projects or Git revisions, with HTML export and --deny-externals option.

  • Advanced filtering and querying

    Regex matching (=~ / search()), variable-to-variable comparisons, len(var) expressions, filter_data custom variables, and docname availability in global_options and needextend filters.

  • Variant options configuration

    needs.variant_options for defining variant-specific need option sets, with improved variant syntax parsing from sphinx-needs.

  • RST preview enhancements

    Click-to-source navigation, scroll sync toggle, and modernized toolbar.

  • Needs Index tree view improvements

    Grouping by type/status/tags, optimized server calls, and better performance.

  • CLI improvements

    -c / --config override option, ubc license config-file command, and --config-name support.

  • Missing image/figure warnings

    The indexer now emits image.not_found diagnostics for missing image or figure files.

  • Source follow links configuration

    New source.follow_links option to control source file link resolution.

👌 Improvements

  • Sphinx-needs v6 type safety: full type validation for need extra options with schema definitions.

  • Schema validation aligned with sphinx-needs (docname, is_external, is_import fields; all link fields included).

  • Deterministic diagnostic ordering (sorted by ID).

  • Improved diagnostic location reporting for needs.statuses and needs.tags.

  • Extra links copy key now supported.

  • Improved JSON import/export with better type handling and error reporting.

  • Improved RST autocompletion for need directive options.

  • Extension version displayed in VS Code home tree view.

‼️ Breaking Changes

  • Removed deprecated Kuzu database support

    The ubc build json-to-kuzu command, kuzu format option, and related Python bindings have been removed. Migrate to parquet or json formats instead.

🐛 Fixes

  • Fixed parse_variants = true on core fields being incorrectly rejected.

  • Fixed race conditions in Windows cache directory creation and openNeedView command.

  • Fixed edge-case “ID already registered” errors from duplicate links in LSP endpoints.

  • Fixed needextend unknown variable diagnostics not being emitted.

  • Fixed MCP server crash when query_needs was called by Claude model.

  • Fixed needs graph view “Focus on main need” button and zoom behavior.

  • Fixed missing VS Code configuration options not being registered.

  • Fixed deployment issue with incorrect platform binaries (0.20.1b1).

  • Fixed machine code handling for recent Windows 11 versions.

0.20.6b1

Released:

19.02.2026

pre-release:

✨ New Features

  • Dead link validation during indexing

    Outgoing links from needs are now validated against the index during indexing. When a link targets a non-existent need ID or part ID, a needs.dead_link diagnostic is emitted. Validation supports incremental updates, so only affected links are re-checked when needs change.

    Individual link types can opt out via the allow_dead_links option on the link definition.

  • Fine-grained lint suppression by path and message

    Two new [lint] configuration options allow targeted suppression of diagnostics:

    • lint.per-file-ignores — suppress specific diagnostic codes for files matching glob patterns:

      [lint.per-file-ignores]
"tests/**/*.rst" = ["needs.dead_link", "needs.invalid_field_value"]

    • lint.message-ignores — suppress diagnostics whose message contains a given substring, optionally scoped to specific codes:

      [[lint.message-ignores]]
codes = ["needs.invalid_field_value"]
contains = "deprecated_field"

    These complement the existing lint.ignore (global code suppression) and lint.lsp_select (LSP-only override) options.

  • needs.links configuration

    Added a new dict-based [needs.links] configuration format for defining link types, as an alternative to the existing array-based [[needs.extra_links]] format. This aligns with the upcoming sphinx-needs v7 release (sphinx-needs#1649).

    [needs.links.implements]
incoming = "is implemented by"
outgoing = "implements"

[needs.links.tests]
incoming = "is tested by"
outgoing = "tests"
copy = true

👌 Improvements

  • Expanded real-time schema validation in the editor

    Quick schema validation for LSP diagnostics now checks a much broader set of JSON Schema constraints beyond enum values, including minLength, maxLength, minimum, maximum, minItems, maxItems, uniqueItems, and const. Link values are also now validated in real-time.

🐛 Fixes

  • Fixed parse_variants = true on core fields (status, tags, title) being incorrectly rejected when the field was not listed in variant_options. This now matches sphinx-needs behavior, which allows variants on these fields by default.

0.20.5b1

Released:

16.02.2026

pre-release:

👌 Improvements

  • Schema validation alignment with sphinx-needs

    Schema validation now includes docname, is_external, and is_import fields in the need JSON representation, enabling schema select clauses to filter by these properties. All defined link fields are now included in validation (even when empty), making link constraints like minItems validate consistently across all needs.

  • Deterministic diagnostic ordering

    Diagnostics related to needs are now emitted in a reproducible order, sorted by ID.

0.20.4b1

Released:

10.02.2026

pre-release:

✨ New Features

  • Schema definition validation now runs during indexing

    The needs.schema_definitions_from_json schema validation is now integrated into the indexing process, validating needs against your JSON Schema definitions automatically as you edit. Previously, this validation was only available via the CLI.

    This emits diagnostics with severity-specific codes:

    • needs.schema_definition_info - informational schema rules

    • needs.schema_definition_warning - warning-level schema rules

    • needs.schema_definition_violation - critical schema violations

    • needs.schema_network_info - informational network/link rules

    • needs.schema_network_warning - warning-level network rules

    • needs.schema_network_violation - critical network violations

    See Schema definitions configuration for more details.

  • Regex support in need query syntax

    Added search() function and regex matching syntax (=~) to the need query language, enabling powerful pattern matching when querying needs. String literals now also support escape sequences for special characters.

  • Field specialization with ``needs.fields`` configuration

    A new needs.fields configuration allows you to define specialized field schemas, enabling fine-grained validation of need extra options with JSON Schema. Fields now default to nullable with no default value, providing more flexibility.

    This will support the future sphinx-needs v7 release.

👌 Improvements

  • Schema validation speed and robustness

    • Schema validation now uses forward link expansion for better incremental performance, reducing re-validation overhead when editing needs.

    • Schema validation now handles errors gracefully without raising exceptions

    • Improved error messages for field schema compilation errors

    • Fixed array type injection in schema validation

  • Improved ``ubc schema validate`` CLI

    The ubc schema validate command now has a consistent user experience with ubc build index, including improved progress output and error reporting.

  • MCP server improvements

    • Fixed crash when query_needs was called by Claude model

    • Added aliases to SortDirection for improved usability

  • Needs graph view fixes

    Fixed “Focus on main need” button and zoom behavior in the needs graph view.

‼️ Breaking Changes

  • Removed deprecated Kuzu database support

    The Kuzu graph database feature (introduced in v0.9.0) has been removed due to Kuzu being deprecated. The following have been removed:

    • ubc build json-to-kuzu command

    • kuzu format option from ubc build needs (-f kuzu)

    If you were using Kuzu databases, consider migrating to the parquet or json formats instead.

🐛 Fixes

  • Fixed edge-case “ID already registered” errors in VS Code caused by duplicate links in LSP endpoints.

0.20.3b1

Released:

27.01.2026

pre-release:

✨ New Features

  • Enhanced Need schema validation

    Comprehensive schema validation for need extra options and extra links has been added to the indexing process.

    These diagnostics emit the codes:

    • needs.invalid_field_value

    • needs.invalid_link_value

    See Extra options configuration.

  • Grouping support in Needs Index tree view

    The Needs Index view now supports grouping needs by different properties (e.g., type, status, tags), making it easier to organize and navigate large sets of needs.

  • Click-to-source navigation in RST preview

    Clicking on elements in the RST preview now navigates directly to the corresponding source location in your editor.

  • Scroll sync toggle for RST preview

    A new toggle allows you to enable or disable scroll synchronization between the RST source and preview.

  • CLI configuration override option

    New -c / --config CLI option and UBCODE_CONFIG_OVERRIDE environment variable allow overriding configuration settings directly from the command line.

    See CLI documentation for more details.

  • Warning on missing image/figure files

    The indexer now warns when image or figure directive files are missing, helping catch broken references early.

    This diagnostic emits the code image.not_found code.

  • Source follow links configuration

    New source.follow_links configuration option to control how source file links are resolved. See source.follow_links configuration for more details.

👌 Improvements

  • Need Viewer enhancements:

    • Added back/forward navigation with history support

    • Added zoom controls for better readability

    • Added “Go to Source” context menu action

    • Improved performance with batch LSP endpoint for node data

  • RST preview toolbar modernization

    The RST preview toolbar has been updated to match the aesthetic of the Needs View.

  • Improved RST autocompletion for need directive options

    Better autocompletion suggestions when editing need directive options in RST files.

  • Improved diagnostic location reporting

    Diagnostic warnings for needs.statuses and needs.tags now report more accurate source locations.

  • Improved MCP server handshake

    Fixed compatibility issues with the VS Code MCP server handshake.

  • Needs Index tree view optimization

    Reduced server calls for improved performance when browsing needs.

  • Schema file handling

    The indexer now warns on missing schema files rather than erroring, improving resilience.

  • License CLI improvements

    Added ubc license config-file command and --user option to ubc license show.

  • Extension version in home tree view

    The VS Code extension version is now displayed in the home tree view for easier identification.

🐛 Fixes

  • Fixed race condition in Windows cache directory creation.

  • Fixed race condition in the openNeedView command.

  • Fixed missing VS Code configuration options not being registered.

‼️ Breaking Changes

  • Removed deprecated Kuzu database support

    The Kuzu graph database feature (introduced in v0.9.0) has been removed due to Kuzu being deprecated. The following have been removed:

    • ubc build json-to-kuzu command

    • kuzu format option from ubc build needs (-f kuzu)

    • kuzu Python dependency

    • kuzu_need_table_cmd Rust function and Python binding

    If you were using Kuzu databases, consider migrating to the parquet or json formats instead.

0.20.2b1

Released:

10.12.2025

pre-release:

👌 Improvements to filtering

Within needs.global_options predicate filters, needimport and needextend filters, the needs.filter_data configuration can now be used to define additional variables for use in filter expressions.

Within needs.global_options predicate filters, needextend filters, additionally, the docname variable is now available. For needextend this is derived from the document path containing the directive, and for needs.global_options it is derived from the document path the need is defined in, for need and needimport directives. The docname is the path relative to project.srcdir, without the file extension (as per Sphinx’s standard document naming).

This improves compatibility with sphinx-needs filtering.

For example:

project.srcdir = "docs/source"

[needs.filter_data]
my_var = "a"

[needs.global_options.status]
default = "open"
predicates = [
  ["my_var == 'a'", "closed"]
  ["docname == 'index'", "other"],
]

.. needextend:: docname == 'some_doc' and my_var == 'a'
   :status: another

👌 Additional improvements

  • The copy key of needs.extra_links item configurations is now supported, as per the logic of sphinx-needs. See Extra links configuration for more details.

  • Improvements to the Model Context Protocol (MCP) server: The need query input and return value schemas, and usage instructions, have been improved, to allow for easier interpretation by LLMs and reduce token usage.

  • Addition of the --deny-externals option to the ubc diff command. This filters out external needs from the diff analysis, which is helpful when reviewing Git history, to focus only on local project changes, and to avoid false positives when external needs.json files are dynamically generated and may not be available.

    If projects use dynamically generated external needs.json files, e.g. build via Bazel, those will not be available when running ubc diff git or before Bazel was called. The feature can be used to avoid false positives.

🐛 Fixes

  • Diagnostic warnings for unknown variables in needextend are now correctly captured and emitted. For example:

    .. needextend:: unknown_variable == 'value'
   :status: closed

  • ublicense: Fix machine code handling for recent versions of Windows 11

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.