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 anddirective_namesettles a name another directive holds; namespaced ids (opt-in, experimental) and the draft needs.json format2a1(experimental); records read and needs.json written as Sphinx-Needs does; MiniJinja 3.1 templates and a TOML 1.1ubproject.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-coveragetells, 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.2section 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 needsfails 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, anddirective_name(under[needs]or per type) decides what the bare name is when another directive has it:"claim"(the default),"yield"(astepneed type and sphinx-design’sstepside 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_1isREQ_1innc::m2); the id itself is unchanged. Filters readc.id.ns,c.id.localandc.in_namespace("nc");id_regexchecks the local id; completion findsnc::REQ_1forREQ; anid_prefixending 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"makesubc build needs(andubc build htmlwithbuild_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);needimportand[[needs.external_needs]]read such a file with nothing to switch on.ubc diff,ubc build validate-json, the needs.json panel andubc agent install --from-needs-jsondo not read it yet. See json_format_version.TOML 1.1:
ubproject.tomland a template’s.tomlcontext file may hold multi-line inline tables, a trailing comma,\eand\xHHescapes 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 mcpoffersshow_needs,show_healthandneed_graph: a query’s needs as a table to sort and filter, each need’s findings, links, fields and trace graph, and whatubc checkreports, 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_diagnosticsfor every MCP client: whatubc checkreports (counts by grade and code, whether it would pass, the findings most severe first), narrowed bypath,code,severityorneed. 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-coveragetakes the report written where the coverage was collected, so code edited since is never credited. The MCP toolrequirements_coverageanswers 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 itscompile_commands.jsonentry declares (--target, a compiler named likearm-none-eabi-gcc, or the newtargetsetting), with clang’s builtin headers carried inubc(resource_dirfor 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 fortargetor 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 atargetevaluates#[cfg]for that target, profile, packages and features; compiled-out code leaves the count (universe.inactive_units), and what a build script (unlessbuild_scriptsstates it) or.cargo/config.tomlmay 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’sItblocks are tests) andcomment_type = "vhdl"; aneed_id_refs.markersentry can be{ marker, field }, so Doxygen’s\satisfiesand\verifiesfill 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
accordionof dropdowns that opens one at a time, anasidethe text flows around, andsteps/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:andcard-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
subfigureis 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.2links to the heading numbered 1.2 in the same document (std.section_refwhen it resolves to none); withhtml_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
deflistlazy 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 andparsed-literalwhitespace 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), soubc check <page>and aper-file-ignoresrule 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
needextractcard also names the page that shows it ((shown-by needextract)); one inside asrc-tracebody is at its source line. See per-file-ignores.Paths outside the working directory climb with
..instead of printing absolute, inubc check, the builders’-wandubc schema validate.
✨ Cypher¶
Memory follows what a query keeps: the last
MATCHstreams intoRETURN, aggregates fold as rows arrive,DISTINCTkeeps one row per value and an unorderedLIMITstops 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:
startNodeandendNode(a need-selecting view can return them);trim,lTrim,rTrim,replace,left,right;e,exp,log,log10,pi, the trigonometric functions,degrees,radians,haversin; andstDevandstDevP. 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 checkis 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 refusingubproject.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
list2needitem;ubc formatprints a summary when it skips files;ubc serve mcp’s instructions say whenfile_pathmay 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_urlandubc agent’s prompts. Values print as Python prints them (['a', 'b']),tojsonspaces asjson.dumps,roundis half-even,1 / 0is an error andmin/maxignore case, as in Sphinx-Needs 9.3.0. A template directive’s limit is one million units of work;template.value_limitis no longer reported (a[lint]ignore of it moves totemplate.compute_limitortemplate.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,nullfor an external one),"content": ""for a need with no body, and every declared link type,[]where it has none;doctypeis the page’s suffix. Aubc diffof a 0.39.0 needs.json against a 0.40.0 one therefore lists every need as changed:--deny-core docname --deny-core doctypetakes those two fields out of the comparison (the schema diff still reportsdocnameas 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
needimportand external needs: a statednullis no value; a record withcontentkeeps itsdescription;:tags:extend stringtags; anid_prefixreaches part links, link conditions and string links;:allow_type_coercion: falseis honoured. A record whosecontentis 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
needextendargument 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 coldubc checkof 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 coldubc 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 htmlre-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); withanalyse.preprocessor,codelinks.not_in_compile_database,codelinks.builtin_header,codelinks.preprocessor_target_unknownandcodelinks.preprocessor_parse_refused; parser findings inside included files;ref.duplicate_target,ref.nonexistent_indirect,ref.circular_indirect,std.ref,std.duplicate_targetanddirective.table_malformed;needs.import/needs.externalfor the records above;needs.variantfor non-string variant data in a string field;needs.src_tracefor a marker statingexternal_url;configfor a codelinks URL field named like a core field; a one-wordneedextendid holding(,=or a quote, now read as a filter; andubc check <dir>now checks a Markdown-only project. A fragment several pages include is reported once per page, so--max-warningscounts can rise. Fix each, or ignore its code under[lint]. See Core options and Diagnostics.Builders fail on findings:
ubc build needs(andubc build targets, experimental) still write the file, then exit non-zero on any warning, and take-w,--lint-extend-ignore,--denyand--max-warnings;--deny nonekeeps 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.10became"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 updatebrings 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,stepandsubfigure. A project that declares one keeps it (information,config.port_directive_name_kept; a warning when[parse] extensionsnames the extension,config.conflicting_directive_registration): set a need type’sdirective_name, rename the entry, or switch the extension off. One that silencedblock.directive_unknowngets the new directive unless it adds anignore_directivesorextend_directivesentry. A preset, template orextend_directivesentry namedneed:…, and a need type whosedirectiveholds:, 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
LIMITanswers, and(d)-[*]->(c {…})may start fromc(addORDER BYfor a stable order); the Needs graph view shows at mostubcode.needViewer.maxNeedsneeds (200; raise it up to 2000); an MCP tool that fails answers anisError: trueresult, not a JSON-RPC error;ubc agent verdict-submitwrites under the configuration’s folder (move earlier verdicts there), and a-c[quality]applies to every verb that reads the review state (drop the-cfor the old answer); coverage counts move toward what the build compiles, and C++ unit IDs follow clang’s names in five shapes, and withanalyse.preprocessorwhere a macro spelled the name (replace old IDs in justification ledgers, need symbol fields andsymbolfilters, and take a--baselineagain); the anchors of overlined titles with markup and of glossary terms holding a substitution move;ubc check --output-format jsongives a path outside the working directory as../…and asrc-tracebody finding"column": null;include/excludepatterns without/stay inside the project and match at any depth, as the index reads them, and.ub_cacheis excluded by default.Licensing: proxy credentials are percent-decoded, so a literal
%is written%25; the open-source check refuses anhttps://environment proxy (give anhttp://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’sread_errorgives Python’s message at the bad byte’s line and column, VS Code’s Problems panel shows it for a closed file,ubc queryandubc codelinks coveragesay so on stderr, and the MCP project tools listunreadable_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 insideneedextract/needimportcards); no duplicate HTML ids for traced cards or tabs.ubc checkandubc formatsee the files the build sees: a Markdown-only project, nestedubproject.tomlfiles,-coverrides 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 diffcompares 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 owndirectory, 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 mcpanswers at once, for two minutes, when the licence server cannot be reached. See Open Source.ubc agent(alpha):verdict-submitandreview-brieffind the project asverdict-checkdoes. The Needs graph view keeps a dragged card in place.ub-template:raw:reads its format asrawdoes;ubc build pdf(beta) draws\tag*;ubc build linkcheckno longer crashes on a page whose start tag holds very many quoted attributes.