v0.27.0

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

✨ New Features

• Conditional link assessment (sphinx-needs v8 compatibility)

  ubCode now supports inline conditions on need links, matching the conditional link assessment feature introduced in sphinx-needs 8.0.0.

  Append a filter expression in square brackets after a target ID to assert that the linked need satisfies a condition:

  .. spec:: My Specification
     :links:
       REQ_001[status=="open"],
       REQ_002[version>=3]

  Each condition is evaluated against the target need's fields at index time. Links without conditions continue to work exactly as before.

  When the condition contains square brackets (e.g. for list indexing), use multiple opening brackets — the parser matches N opening [ with N closing ]:

  .. spec:: My Specification
     :links: REQ_001[["important" in tags]]

  Two new diagnostic codes are emitted:

  • needs.link_condition_failed — the condition evaluated to false against the target need.
  • needs.link_condition_invalid — the condition has invalid syntax and could not be parsed.

  Condition evaluation is incremental: when a target need changes (e.g. its status field is updated), all needs linking to it with conditions are automatically re-validated.

  A new per-link-type parse_conditions option controls whether bracket syntax is interpreted as a condition expression or treated as literal ID text (defaults to true):

  [needs.links.raw_links]
  parse_conditions = false

🐛 Fixes

• Fixed Windows configuration directory path to match pre v0.22.0b1 behavior

  The Rust-based license checker introduced in v0.22.0b1 changed the ubCode config directory on Windows, which could break license activation. The pre v0.22.0b1 behavior is now restored, so the config file is expected at C:\Users\<username>\AppData\Local\useblocks\ubcode\ubcode.toml again. See the ublicense documentation for more details.

v0.26.0

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

✨ New Features

• Resolution of simple dynamic functions ([[...]] syntax)

  ubCode now resolves some built-in dynamic functions ([[...]] syntax) from sphinx-needs. If your documentation already uses dynamic functions, they were previously parsed and stored on need items but left unresolved — they will now be evaluated during indexing. Three built-in functions are supported in this initial release:

  • echo("text") — returns the given string unchanged
  • test(*args, **kwargs) — returns a debug string with the need ID and arguments
  • copy("field") — copies a field value from the current need (also supports lower and upper kwargs)

  For example:

  .. req:: My requirement
     :id: REQ_001
     :status: [[copy("priority")]]

  Dynamic functions are resolved alongside variant functions in the same resolution pass. Parse and execution errors are surfaced as needs.dynamic_function diagnostics.

  Dynamic function parsing is enabled by default and can be controlled via needs.parse_dynamic_functions globally, or overridden per-field or per-link. Variant function parsing (parse_variants) is also now configurable per-link. For example:

  [needs]
  parse_dynamic_functions = false  # disable globally
  
  [needs.fields.my_field]
  parse_dynamic_functions = true   # re-enable for this field
  
  [needs.links.implements]
  incoming = "is implemented by"
  outgoing = "implements"
  parse_dynamic_functions = true   # re-enable for this link
  parse_variants = true            # also enable variant parsing

  The LSP provides real-time syntax checking for dynamic function calls.

• Added core need fields: layout, style, collapse, hide

  Added support for the layout, style, collapse, and hide core need fields, aligning with sphinx-needs' presentation options. These fields are now recognised during indexing, validation, and autocompletion, and will appear in the VS Code Needs Index tree view, ubc build needs JSON output, MCP queries, and other need-aware features.

• ubc agent-skill CLI command

  New command that auto-generates a Markdown reference document (SKILLS.md) describing the full CLI for AI agents and copilots, aligned with the agentskills.io specification.

  ubc agent-skill          # print to stdout
  ubc agent-skill -o SKILLS.md  # write to file

🐛 Fixes

• Fixed TLS "UnknownIssuer" certificate errors when using the new Rust-based license checker (introduced in v0.22.0b1) behind corporate proxies or with custom enterprise CAs. License validation now delegates certificate verification to the operating system, matching the previous behavior.

• Fixed ubc CLI failures on Windows when the installation path was deeply nested, caused by exceeding the Windows 260-character path limit (MAX_PATH). This could manifest as "file not found" or "path too long" errors when running CLI commands.

v0.25.0

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

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

Note

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.

v0.24.1

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

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

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.