v0.29.1b1

see https://ubcode.useblocks.com/development/changelog.html#b1

✨ New Features

• content field on need items

  Need items now carry an optional content field that stores the raw body text of the directive. Content is included in JSON and Parquet exports, queryable in filter expressions (e.g. "keyword" in content), returned by the MCP single-need endpoint, and checked in ubc diff. Content is preserved through directive, import, and external need sources.

• follow_links configuration for codelinks source discovery

  A new follow_links option in [codelinks.projects.*.source_discover] controls whether symbolic links are followed during codelinks file discovery.

👌 Improvements

• Aligned codelinks file discovery behaviour with sphinx-codelinks, improving consistency between the IDE tooling and the Sphinx extension. The C/C++ recognised file extensions were updated (now .c, .ci, .cpp, .cc, .cxx, .h, .hpp, .hxx, .hh, .ihl).

🐛 Fixes

• Fixed mermaid diagram labels in the VS Code RST preview being clipped mid-word.

v0.29.0b1

see https://ubcode.useblocks.com/development/changelog.html#release-0-29-0b1

✨ New Features

• Source code traceability with codelinks

  ubCode now supports tracing requirements directly in source code comments, creating a live bidirectional link between documentation and code. This implements the sphinx-codelinks marker format natively in the IDE. Embed standardised markers in C++, Python, Rust, C#, or YAML comments and ubCode extracts them into need objects automatically.

  One-line need definitions let you create a new need from a single comment:

  # @Function Bar, IMPL_4, impl, [SPEC_1]
  def bar():
      ...

  Note: Need-ID references (@need-ids:) are not yet supported and are planned for a future release.

  The .. src-trace:: RST directive includes traced needs in your documentation, scoped by project, file, or directory.

  IDE features delivered through the language server:

  • Real-time diagnostics for malformed one-line markers (source: ubcode-codelinks; codes include too_few_fields, too_many_fields, missing_square_brackets, etc.)
  • Hover on markers shows a rich card with the need's type, ID, title, metadata fields, and link targets
  • Find References from a source code marker navigates to all RST documents that backlink via field values or :need: roles
  • Autocomplete for the :project: option in .. src-trace:: directives, populated from [codelinks.projects.*] keys in ubproject.toml

  Parsing is implemented in Rust (via tree-sitter) and runs incrementally — only changed files are re-parsed, keeping the feedback loop fast.

  See the usage guide and configuration reference for details.

• ubc build list-documents --codelinks CLI option

  The ubc build list-documents command now supports listing files from configured codelinks projects: --codelinks / --no-codelinks to include codelinks source files, --codelinks-project <name> to filter to a specific project, and --source-documents / --no-source-documents to toggle RST/MD source documents. These can be combined, e.g. --codelinks --no-source-documents to list only codelinks files.

• Configuration redirect with ubproject.redirect.toml

  A new redirect file mechanism lets ubCode find the ubproject.toml for files that live outside the documentation folder (e.g. source code files traced via codelinks). Place a ubproject.redirect.toml containing path = "../docs" in your source directory and ubCode follows the redirect during its configuration file search. Circular redirects are detected and handled gracefully.

  See the configuration reference for details.

👌 Improvements

• Labels on diagnostic source locations

  Diagnostics in the ubCode Issues panel now annotate each source location with a descriptive label (e.g. needimport-source, external-source), making it easier to understand the role of each location when a diagnostic spans multiple files, such as link constraint violations.

• Expanded and reorganised the user documentation, including new configuration examples and a codelinks usage guide.

v0.28.2

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

✨ New Features

• Pin project in VS Code views

  A new ubcode.views.pinnedProject VS Code setting lets you lock all views
  (Needs Index, Diagnostics, Needs JSON, Std Domain, Needs graph)
  to a specific ubproject.toml,
  so they no longer switch context when the active editor changes.
  Pin and Unpin buttons are available in the tree view toolbar and context menu.
  Path variables (${workspaceFolder}, ${userHome}, etc.) are also supported.

  

👌 Improvements

• Improved diagnostic locations for needextend and link conditions

  Validation diagnostics now include the source locations of needextend
  directives that modified a need, in addition to the original need definition.
  Link condition diagnostics likewise show the location of the target need
  (and any needextend on it).
  This makes it much easier to trace the root cause of validation failures.

• Smarter configuration cache invalidation

  The configuration cache now tracks modification times of external files
  referenced by ubproject.toml (e.g. schema JSON files),
  not just the config file itself.
  Changes to those files now correctly trigger a re-index.

• More flexible MCP tool parameter names

  The MCP server's query_needs_advanced and get_single_need tools now
  accept common aliases for their input fields
  (e.g. select for fields, need_id for id),
  and sort_direction accepts case-insensitive variants.
  This improves robustness when AI assistants call the MCP tools.

🐛 Fixes

• Fixed RuntimeError: Already borrowed crashes in the language server, caused by concurrent LSP requests.

v0.28.1

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

👌 Improvements

• Natural sort order in the Needs Index tree view

  The Needs Index tree view now sorts need IDs, group keys, and link types
  in natural sort order, so REQ_2 appears before REQ_10 instead of
  after it. Link targets within each type are also deduplicated and naturally
  sorted.

🐛 Fixes

• Fixed the @ubcode chat participant losing conversation context
  ("amnesia") when it invoked tools during a chat session.

v0.28.0

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

✨ New Features

• Chat participant

  The new @ubcode chat participant integrates with GitHub Copilot Chat to give
  you an AI assistant with deep knowledge of Sphinx-Needs and ubCode.
  Type @ubcode in the Copilot Chat panel followed by your question and the
  participant automatically fetches the most relevant documentation to generate a
  focused answer.

  

  For more information see the chat participant documentation

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.