0.20.x

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 validation 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 Fields 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 Fields 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 Variants 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