[chrisjsewell]

Seven independently evidenced needflow defects, each with a regression test. No new
options, no deprecations, no refactor — the two engines keep their current behaviour
everywhere else. (First slice of the needflow portable-options work; the option
abstraction itself comes separately.)

Fixes

• :show_legend: crashed the build for a need type without a color (needflow nodes extremely dark under dark mode (Sphinx 9.1.0, Sphinx‑Needs 7.0.0) #1664).
  color is optional in needs_types, but diagrams_common.create_legend
  (plantuml) and _graphviz._create_legend both subscripted it, so the build ended with
  KeyError: 'color' on either engine. The type now keeps its legend row with a blank
  swatch instead of being dropped, and a type whose color is an empty string no longer
  emits an empty swatch value. This is the other half of needflow nodes extremely dark under dark mode (Sphinx 9.1.0, Sphinx‑Needs 7.0.0) #1664, whose fix covered the node
  colour only — its fixture had no :show_legend:, so the legend path was never covered.
• PlantUML drew two needs as one node when their ids differed only in punctuation.
  PlantUML entity names cannot contain punctuation, so R-1 and R=1 both became R_1,
  and the second need plus its edges silently disappeared (the edge became the self-loop
  R_1 --> R_1). Entity names are now assigned per diagram from a stable, injective
  mapping. The shared make_entity_name is deliberately unchanged, because needuml
  imports it and its entity names are user-visible references there.
• :border_color: mishandled a leading #, and a variant matching nothing.
  #00FF00 reached graphviz as ##00FF00 and PlantUML as line:#00FF00, which PlantUML
  rejects outright (the diagram failed to render). Separately, graphviz wrapped
  match_variants in str(...), so an unmatched variant expression became the literal
  colour #None. Both engines now normalise the value through one helper and add their own
  prefix, and an unset result means "no border colour" on both. The two graphviz code paths
  — plain node and subgraph — are covered by the same test and must agree.
• :highlight: filters that consult needs failed for a need with parts or children.
  Graphviz draws such a need as a subgraph, and that path called filter_single_need
  without the needs list, while the plain-node path passed it. An expression like
  len(needs) > 1 therefore raised NeedsInvalidFilter: name 'needs' is not defined and
  failed the whole build, purely because a need happened to have a child.
• A graphviz needflow image had no alternative text. The directive always stored an
  alt, so the intended alt="needflow graphviz diagram" default was unreachable and
  every image was published with alt="". The placeholder now applies when :alt: is
  absent; writing :alt: with no value still gives alt="" for a diagram that is purely
  decorative. This is the one user-visible rendering change in the PR.
• Two warning defects. The unknown-:config: warning named need_flows_configs,
  which does not exist (it is needs_flow_configs), and the graphviz unknown-:link_types:
  warning was emitted without a location, so it arrived with no file:line — unlike the
  plantuml one.

Environment version

ENV_DATA_VERSION goes 5 → 6, because the alt fix changes how the option is recorded
when it is not given ("" → None) and that value is persisted in doctrees. Without the
bump the two halves can disagree within one version: an older reader over a newer doctree
publishes the literal alt="None", and a newer reader over an older doctree leaves the fix
silently inert. The first build after upgrading re-reads every document.

Tests

• tests/test_github_issues.py::test_doc_github_1664_legend (both engines), on the
  existing doc_test/doc_github_issue_1664 project extended with a :show_legend: page.
• Seven new tests in tests/test_needflow.py, parameterised over both engines where the
  behaviour is shared, asserting on the :debug: diagram source (and, for alt, on the
  built <img>): node-id injectivity, border_color normalisation, highlight with
  needs, both :config: warning texts, the link-type warning location, the three
  alt cases, and the entity-name fallback contract (value + warning) covered directly.
• Each behavioural fix's test was recorded failing against the unfixed code before its
  fix landed; the commits are ordered test-then-fix per defect.
• The plantuml entity-name lookup warns if an id reaches it unmapped, which cannot happen
  today — the two assert warnings == "" tests in tests/test_needflow.py are what keeps
  it that way, and they stay green.
• The full suite passes (1214 passed, 11 skipped) with no snapshot changes.

Documentation

docs/changelog.rst gains a Bug fixes section under Unreleased, and the alt section
of docs/directives/needflow.rst now documents the graphviz default and the
explicitly-empty case. The border_color reference needs no change: accepting a leading
# is a tolerance, not a contradiction of what it documents.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.14%. Comparing base (4e10030) to head (5d19b44).
⚠️ Report is 320 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1768      +/-   ##
==========================================
+ Coverage   86.87%   90.14%   +3.26%     
==========================================
  Files          56       74      +18     
  Lines        6532    11128    +4596     
==========================================
+ Hits         5675    10031    +4356     
- Misses        857     1097     +240     

Flag	Coverage Δ
pytests	90.14% <100.00%> (+3.26%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.