v0.30.0b1

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

✨ New Features

• Markdown (MyST) authoring support

  Projects can now define needs in Markdown (MyST) files alongside reStructuredText.
  The new [parse.parsers.<name>] configuration tables declare the parsers a project uses,
  select the files each parser owns, and route every discovered file to the right one:

  [parse.parsers.rst]
  
  [parse.parsers.md]
  flavour = "myst"
  include = ["docs/**/*.md"]

  Need directives in Markdown files are indexed, validated, and queryable
  just like their reStructuredText counterparts.
  Projects that declare no parsers keep the existing behaviour:
  every file discovered via [source] is parsed as reStructuredText.
  See the parsers and file routing documentation for details.

  ubc build list-documents also gained a --parser flag
  that shows which parser each source document is routed to.

  Note that language-server features for Markdown files in the VS Code extension
  (such as in-editor diagnostics, as already available for reStructuredText)
  are not yet supported, but are planned for a future release.

• HTML report templates

  ubCode can now render user-authored Jinja templates (*.html.j2)
  against the project's needs index,
  producing a single self-contained HTML file:

  • The new ubc report command renders a template by name
    (or lists the available templates with --list).
  • The new [reports] configuration section sets the templates directory
    and an output size limit.
  • In VS Code, a new Reports view in the ubCode sidebar
    lists the project's templates,
    with in-editor preview and Open in Browser actions;
    render failures are reported in the Problems panel.
  • ubc quickstart now scaffolds a runnable starter template
    demonstrating grouped tables and an inline SVG chart.
  

  See the reports documentation for more details.

• Query needs from the command line

  The new ubc query filter command filters the needs of a project
  using Python-style filter expressions,
  printing the results as a human-readable table
  or as JSON (--format json) that pipes cleanly to tools like jq:

  $ ubc query filter 'type == "req" and status == "open"' --field id --field title

  The project is automatically (and incrementally) re-indexed before querying,
  so results are always up to date;
  use --no-cache to bypass the on-disk cache entirely.

• Variant data for build-variant-aware projects

  Filter expressions can now reference external build-variant data
  via the new needs.variant_data / needs.variant_data_file configuration
  and the var.* namespace,
  e.g. var.platform == "windows" or "arm" in var.archs.
  Need field and link values can also pull values directly from the variant data
  using the new <{ var.* }> reference syntax:

  .. req:: Example
     :id: REQ_001
     :platform: <{ var.platform }>

  See the variant builds
  and variant data documentation for more details.

  These features mirror the upcoming additions to
  sphinx-needs
  (currently on its master branch, to be released soon).
  The if directive
  is not yet handled, but support is hoped to land soon.

  Relatedly, ubc diff gained a --config option
  for comparing a project against itself under a configuration override,
  e.g. ubc diff -c "needs.variant_data_file = 'variants2.json'".

• Native Rust ubc CLI

  The standalone ubc binary is now the native Rust implementation of the CLI,
  replacing the previous Python-based bundle,
  with faster startup and indexing.
  The command surface, output, and exit codes match the Python implementation.

v0.29.3

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

This release promotes the 0.29.x pre-release series to a stable release.
See the pre-release entries for details:

• v0.29.2b1 — Free-text filter in the Needs Index view
• v0.29.1b1 — Need content field
• v0.29.0b1 — Codelinks source traceability

🐛 Fixes

• Stabilized changelog anchors for pre-release versions in the documentation.

v0.29.2b1

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

✨ New Features

• Free-text filter in the Needs Index view

  The VS Code Needs Index now offers a free text filter type
  that searches across the textual fields id, title, and content
  of each need in one go.

  

👌 Improvements

• Need content available via the MCP query_needs tool

  The MCP server's query_needs tool now exposes the content field
  alongside the other need attributes,
  matching the get_data_for_single_need endpoint and the build artefacts.
  AI assistants and other MCP clients can retrieve and filter
  on the directive body text directly,
  without a follow-up per-need lookup.

• Opt out of need content in build artefacts

  The ubc build needs command gained a
  --no-content / --content toggle
  controlling whether the directive body text
  (the content field introduced in release 0.29.1b1)
  is emitted into the build artefacts.
  Use --no-content to keep generated JSON / Parquet output compact
  when downstream tooling does not consume the body text.

v0.29.1b1

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

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