v0.24.0

See https://ubcode.useblocks.com/development/changelog.html#release-0-24-0

✨ 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.

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.

v0.23.0

✨ 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.

  

  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).

v0.22.0b1

♻️ 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.

v0.21.0

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.