0.40.x

0.40.0

Released:

19.11.2026

The story of this release, in four arcs:

  • With Sphinx-Needs 9.3.0: qualified need directives, namespaced ids and needs.json that travels — .. need:req:: always writes a need and directive_name settles a name another directive holds; namespaced ids (opt-in, experimental) and the draft needs.json format 2a1 (experimental); records read and needs.json written as Sphinx-Needs does; MiniJinja 3.1 templates and a TOML 1.1 ubproject.toml.

  • Answers you can click — the needs explorer and a Health view open inside the AI chat (MCP Apps, experimental), and one need graph serves the editor and the chat: capped, with +N pills for links to needs not shown, dead links drawn and hubs packed.

  • Code coverage that never hides code (alpha) — C and C++ are read as the build compiles them, Rust #[cfg] for one build configuration, and --test-coverage tells, per requirement, what its tests ran.

  • sphinx-design 0.8.0, sphinx-subfigure 0.3.0 and MyST-Parser 5.2.0, the week they shipped — accordions, asides, steps, subfigures and MyST §1.2 section references (alpha) render in the preview and both builds, and Markdown reads as markdown-it-py 4.3.0 and mdit-py-plugins 0.7.0 read it.

Also in this release:

  • A finding in an included file is reported at that file’s own line, naming the page that includes it.

  • Cypher streams, so memory follows what a query keeps, and gains the functions models write.

  • Large projects re-index faster, and ubc build needs fails on findings as the other builders do.

  • The open-source licence check works in git worktrees and decodes proxy credentials.

  • Codelinks reads PowerShell and VHDL.

New warnings can fire and some answers change on an unchanged project (see Breaking Changes).

This release is the ubCode half of a lockstep with Sphinx-Needs 9.3.0: need:<type> and directive_name; namespaced_ids with c.id.ns, c.id.local and c.in_namespace(); json_format_version "2a1" and the text "1"; MiniJinja 3.1 templates; and a TOML 1.1 ubproject.toml are read alike by both tools. The Sphinx side is Sphinx-Needs 9.3.0 with ub-needs-exchange 1.2.0; below Python 3.15, TOML 1.1 needs ub-project 1.3.0 and sphinx-mounts 0.4.0 (in a template context file, sphinx-ub-directives 0.2.0); PowerShell, VHDL and the compilation-database reading follow sphinx-codelinks 2.2.0.

✨ With Sphinx-Needs 9.3.0: qualified need directives, namespaced ids and needs.json that travels

  • Qualified need directives. Every need type can also be written need:<type> (.. need:req::, {need:req}), which always writes the need, and directive_name (under [needs] or per type) decides what the bare name is when another directive has it: "claim" (the default), "yield" (a step need type and sphinx-design’s step side by side) or "qualified". See When a type’s directive is another directive’s name.

  • Namespaced need ids (experimental). With [needs] namespaced_ids = true, an id holding :: is a namespace and a local id, split at its last :: (nc::m2::REQ_1 is REQ_1 in nc::m2); the id itself is unchanged. Filters read c.id.ns, c.id.local and c.in_namespace("nc"); id_regex checks the local id; completion finds nc::REQ_1 for REQ; an id_prefix ending in :: imports into a namespace. Off by default, as in Sphinx-Needs 9.3.0. See Namespaced ids and Filtering by namespace: c.id and c.in_namespace.

  • needs.json format 2a1, the draft of format 2 (experimental). [needs] json_format_version = "2a1" makes ubc build needs (and ubc build html with build_json) write each need with the places its text came through (its directive’s file and lines, each include, the needs.json it was imported from, the code of a marker, the test report); needimport and [[needs.external_needs]] read such a file with nothing to switch on. ubc diff, ubc build validate-json, the needs.json panel and ubc agent install --from-needs-json do not read it yet. See json_format_version.

  • TOML 1.1: ubproject.toml and a template’s .toml context file may hold multi-line inline tables, a trailing comma, \e and \xHH escapes and times without seconds. Taplo-based editor extensions may still flag it. See Configuring a project with ubproject.toml.

✨ Answers you can click

  • The needs explorer and Health, inside the chat (experimental). To a client that declares MCP Apps support (Claude Desktop, VS Code’s Copilot Chat), ubc serve mcp offers show_needs, show_health and need_graph: a query’s needs as a table to sort and filter, each need’s findings, links, fields and trace graph, and what ubc check reports, a finding opening its need. Views have no network access; other clients see no change. In VS Code, ubcode.mcp.apps = "off" turns them off. See Views in the chat (MCP Apps).

  • project_diagnostics for every MCP client: what ubc check reports (counts by grade and code, whether it would pass, the findings most severe first), narrowed by path, code, severity or need. See project_diagnostics.

  • One need graph, in the editor and the chat. The Needs graph view shows the nearest needs of a large graph and says so (ubcode.needViewer.maxNeeds, 200 by default, up to 2000), draws the links between the needs it shows, packs a hub’s many needs into columns, lays out top to bottom or left to right as the pane fits, and opens at a readable zoom; the MCP explorer draws the same graph. See Layout and zoom.

  • Links to needs not shown (beta): a need linking off the graph carries a +N pill (hover for the link types, click to centre on it), and a dead link is drawn dashed to a “no such need” card. See Links to needs not shown.

✨ Code coverage that never hides code

  • Requirements-based coverage (alpha). ubc codelinks coverage --test-coverage <PATH> reads the per-test coverage CI already writes (llvm-cov exports, gcov JSON and lcov tracefiles, coverage.py with test contexts) and tells, per requirement, which functions its tests ran, which traced ones they did not, and which untraced ones they ran. --inventory-at-coverage takes the report written where the coverage was collected, so code edited since is never credited. The MCP tool requirements_coverage answers the same; both need a licence. See Checking that each requirement’s tests run its code.

  • C and C++ read as your build compiles them (alpha). With analyse.preprocessor, each file is read for the target its compile_commands.json entry declares (--target, a compiler named like arm-none-eabi-gcc, or the new target setting), with clang’s builtin headers carried in ubc (resource_dir for others) and macros expanded before functions are named. A header is read through every entry that includes it; a file whose target or flags clang refuses is read as written, every arm kept. Known limits: a header no entry includes, and a cross compiler whose name has no triple (tricore-gcc), are read for target or the host, and a parse cached before a generated header existed is not refreshed until its entry changes. See analyse.preprocessor and Known limits.

  • Rust code of one build configuration (alpha). [codelinks_coverage.rust] with a target evaluates #[cfg] for that target, profile, packages and features; compiled-out code leaves the count (universe.inactive_units), and what a build script (unless build_scripts states it) or .cargo/config.toml may change is unknown, never guessed. A file behind #[cfg(test)] mod x; is test code, with or without the table. See Count the Rust code of one build configuration.

  • Codelinks: comment_type = "powershell" (Pester’s It blocks are tests) and comment_type = "vhdl"; a need_id_refs.markers entry can be { marker, field }, so Doxygen’s \satisfies and \verifies fill different fields; need-ID completion works in source comments, and every need-ID completion also finds a need by a word of its title. See Supported languages and Completing need IDs.

✨ sphinx-design 0.8.0, sphinx-subfigure 0.3.0 and MyST-Parser 5.2.0

  • Accordions, asides and steps (alpha), sphinx-design 0.8.0’s new components, in reStructuredText and MyST: an accordion of dropdowns that opens one at a time, an aside the text flows around, and steps / step, a numbered procedure. See Accordions, Asides and Steps.

  • sphinx-design 0.8.0’s options: vertical tabs (:orientation: vertical), :link-new-tab: on cards and :new-tab: on buttons, card :header: / :footer: and card-header / card-footer, badge and button tooltips, and Octicons 19.42.0. See Cards and Badge tooltips.

  • Subfigures (alpha). sphinx-subfigure 0.3.0’s subfigure is built in and on by default: images on a responsive grid as one numbered figure, with per-image captions; the PDF prints the grid as a table. See Subfigures.

  • MyST section references (alpha) and HTML admonitions. With section_ref, §1.2 links to the heading numbered 1.2 in the same document (std.section_ref when it resolves to none); with html_admonition, a <div class="admonition"> becomes an admonition. See Section references (section_ref) and Admonitions written as raw HTML.

  • Markdown as markdown-it-py 4.3.0, mdit-py-plugins 0.7.0 and MyST-Parser 5.2.0 read it: lines after a list item and the rest of a page after a deflist lazy line are kept; $$ math, HTML blocks, edge whitespace and a directive’s --- options read as in a Sphinx build; link titles, multi-line {table} captions and parsed-literal whitespace are kept.

✨ Findings that point where you can act

  • Included files: a finding in an included file is reported at that file’s own line with the including page beside it (included-from), so ubc check <page> and a per-file-ignores rule naming the page reach it; parser findings that were lost there now appear (see Breaking Changes). See Included files.

  • Cards and traced bodies: a finding inside a needextract card also names the page that shows it ((shown-by needextract)); one inside a src-trace body is at its source line. See per-file-ignores.

  • Paths outside the working directory climb with .. instead of printing absolute, in ubc check, the builders’ -w and ubc schema validate.

✨ Cypher

  • Memory follows what a query keeps: the last MATCH streams into RETURN, aggregates fold as rows arrive, DISTINCT keeps one row per value and an unordered LIMIT stops the match (a count over a 200,000-need cross product: about 1,910 MiB → 457 MiB); a collected list is iterated, indexed, sorted and de-duplicated without copies.

  • New functions: startNode and endNode (a need-selecting view can return them); trim, lTrim, rTrim, replace, left, right; e, exp, log, log10, pi, the trigonometric functions, degrees, radians, haversin; and stDev and stDevP. See Cypher syntax.

👌 Improvements

  • Large projects re-index faster: re-indexing more than a few changed files no longer scans every need of the project (for 500 changed files of a 200,000-need project, that step takes about 0.15 s, not 12 s; in the editor, after its first few edits), and ubc check is 7–9 % faster there. A Markdown page of many sibling blocks and a reStructuredText paragraph of many inline constructs no longer parse in quadratic time, and a runaway PlantUML diagram previews in bounded time and memory.

  • A wrong-typed [needs] setting is reported and ignored (id_required = "yes"), as Sphinx-Needs warns, instead of refusing ubproject.toml; a configuration that does not load names its file plainly.

  • The Diagnostics view lists every code with its true count, 500 at a time with a Load more row, where it stopped at 10,000 diagnostics. See Views.

  • Hover and go to definition inside a list2need item; ubc format prints a summary when it skips files; ubc serve mcp’s instructions say when file_path may be left out.

♻️ Changes

  • Templates are MiniJinja 3.1 (changed output) on every Jinja surface: template directives, needuml / needarch, needreport, ubc report, string links, target_url and ubc agent’s prompts. Values print as Python prints them (['a', 'b']), tojson spaces as json.dumps, round is half-even, 1 / 0 is an error and min / max ignore case, as in Sphinx-Needs 9.3.0. A template directive’s limit is one million units of work; template.value_limit is no longer reported (a [lint] ignore of it moves to template.compute_limit or template.output_limit). See The template language.

  • needs.json is written as Sphinx-Needs writes it: every need carries its docname (the including page for a need in an included file, null for an external one), "content": "" for a need with no body, and every declared link type, [] where it has none; doctype is the page’s suffix. A ubc diff of a 0.39.0 needs.json against a 0.40.0 one therefore lists every need as changed: --deny-core docname --deny-core doctype takes those two fields out of the comparison (the schema diff still reports docname as new, so the command exits 1), or compare the two projects (ubc diff -p old -p new). See JSON output.

  • A record is read as Sphinx-Needs reads it by needimport and external needs: a stated null is no value; a record with content keeps its description; :tags: extend string tags; an id_prefix reaches part links, link conditions and string links; :allow_type_coercion: false is honoured. A record whose content is not a string, or that takes a default its field cannot hold, is reported and skipped alone, where the need was imported empty or the file lost. See Importing needs.

  • A one-word needextend argument holding (, =, ' or " is a filter (.. needextend:: c.this_doc()); an id holding one is written <REQ_001(A)>, or the argument is reported as a filter that does not parse. See Extending needs.

  • A large compilation database costs more to read cold with analyse.preprocessor, since each header is read through every entry that includes it: about 91 s for a cold ubc check of 1,357 entries, roughly two and a half times what 0.39.0 took on the same database (measured in a separate session); warm, under a second. A cold ubc codelinks coverage, which also expands macros, takes about 150 s, roughly three and a half times what 0.39.0 took (measured in a separate session).

‼️ Breaking Changes

  • One-time full re-index and re-render on upgrade. The cache format moved (6.287 → 6.354) and the build manifest with it (154 → 182): the first run after upgrading re-indexes every project and ubc build html re-renders every page; nothing is lost and nothing needs doing. The link-check result cache and fetched intersphinx inventories are not discarded.

  • New warnings can fire on an unchanged project, and fail the default gate until ignored or fixed: codelinks.marker_above_conditional (a C/C++ marker directly above an #if, which traced its whole container: move it into the arm, or leave a blank line before the directive to mean the container); with analyse.preprocessor, codelinks.not_in_compile_database, codelinks.builtin_header, codelinks.preprocessor_target_unknown and codelinks.preprocessor_parse_refused; parser findings inside included files; ref.duplicate_target, ref.nonexistent_indirect, ref.circular_indirect, std.ref, std.duplicate_target and directive.table_malformed; needs.import / needs.external for the records above; needs.variant for non-string variant data in a string field; needs.src_trace for a marker stating external_url; config for a codelinks URL field named like a core field; a one-word needextend id holding (, = or a quote, now read as a filter; and ubc check <dir> now checks a Markdown-only project. A fragment several pages include is reported once per page, so --max-warnings counts can rise. Fix each, or ignore its code under [lint]. See Core options and Diagnostics.

  • Builders fail on findings: ubc build needs (and ubc build targets, experimental) still write the file, then exit non-zero on any warning, and take -w, --lint-extend-ignore, --deny and --max-warnings; --deny none keeps the old exit. See ubc build needs.

  • A JSON number in a string field refuses an imported or external record, reversing 0.39.0, where it was kept as text (1.10 became "1.1"). Write the value as a JSON string. See Fields.

  • ubc agent (alpha) stops on a source that cannot be read: every verb that builds the graph answers "reason": "unreadable_sources" and exits non-zero, and the editor’s agent views stop too. Re-save the file as UTF-8, or opt it out with a [lint] per-file ignore; ubc agent update brings the skills that know the stop. See the stop.

  • A codelinks source that is not UTF-8 is a read_error (an error) and skipped alone, where libclang decoded it lossily: re-save it as UTF-8, or ignore it per file. See Unreadable source files (read_error).

  • Directive names are now taken: accordion, aside, steps, step and subfigure. A project that declares one keeps it (information, config.port_directive_name_kept; a warning when [parse] extensions names the extension, config.conflicting_directive_registration): set a need type’s directive_name, rename the entry, or switch the extension off. One that silenced block.directive_unknown gets the new directive unless it adds an ignore_directives or extend_directives entry. A preset, template or extend_directives entry named need:…, and a need type whose directive holds :, are refused: rename them. See Accordions, asides and steps.

  • Answers change on an unchanged project: a Cypher query no longer evaluates rows its result does not need, so one failing only past its LIMIT answers, and (d)-[*]->(c {…}) may start from c (add ORDER BY for a stable order); the Needs graph view shows at most ubcode.needViewer.maxNeeds needs (200; raise it up to 2000); an MCP tool that fails answers an isError: true result, not a JSON-RPC error; ubc agent verdict-submit writes under the configuration’s folder (move earlier verdicts there), and a -c [quality] applies to every verb that reads the review state (drop the -c for the old answer); coverage counts move toward what the build compiles, and C++ unit IDs follow clang’s names in five shapes, and with analyse.preprocessor where a macro spelled the name (replace old IDs in justification ledgers, need symbol fields and symbol filters, and take a --baseline again); the anchors of overlined titles with markup and of glossary terms holding a substitution move; ubc check --output-format json gives a path outside the working directory as ../… and a src-trace body finding "column": null; include / exclude patterns without / stay inside the project and match at any depth, as the index reads them, and .ub_cache is excluded by default.

  • Licensing: proxy credentials are percent-decoded, so a literal % is written %25; the open-source check refuses an https:// environment proxy (give an http:// one); and a key is expired from the second it expires, not up to a day later. See Proxies.

🐛 Fixes

  • A source that cannot be read is named everywhere: ubc check’s read_error gives Python’s message at the bad byte’s line and column, VS Code’s Problems panel shows it for a closed file, ubc query and ubc codelinks coverage say so on stderr, and the MCP project tools list unreadable_sources. See Unreadable source files (read_error) and unreadable sources.

  • Built pages match Sphinx more closely: image alt, admonition classes, code-block blank lines, paragraphs in tight list items; references resolve as docutils resolves them (anonymous and embedded targets, mixed-case :ref:, targets inside needextract / needimport cards); no duplicate HTML ids for traced cards or tabs.

  • ubc check and ubc format see the files the build sees: a Markdown-only project, nested ubproject.toml files, -c overrides and [[source.variant_sources]]. See exclude.

  • Needs: link conditions such as REQ[status in ['open']] are kept, authored or imported; a :np: in an included file is collected; a variant default may name an id holding ::; ubc diff compares a value a need leaves out as its default, so declaring a field no longer marks every need changed. See How needs are compared.

  • Codelinks with analyse.preprocessor: an entry is parsed in its own directory, a -- in an entry (clang-cl) ends its options, and a file clang refuses is reported instead of dropped with a log line.

  • Licensing: the open-source check passes in a linked git worktree, of a bare repository or a submodule too; a proxy error never prints part of a password; ubc serve mcp answers at once, for two minutes, when the licence server cannot be reached. See Open Source.

  • ubc agent (alpha): verdict-submit and review-brief find the project as verdict-check does. The Needs graph view keeps a dragged card in place. ub-template :raw: reads its format as raw does; ubc build pdf (beta) draws \tag*; ubc build linkcheck no longer crashes on a page whose start tag holds very many quoted attributes.