🐛 needflow: fix the graphviz label escaper, and stop bad configuration ending the build

[chrisjsewell]

Slice 1 of the #1770 split (see the plan there): the pure fixes, carved out so they can be
reviewed and merged ahead of any vocabulary discussion.

Five independent needflow defects, each with a regression test that fails on master, plus
one deliberate output change that is called out separately below. No new directive option,
no new configuration key, no deprecation, and no stored-data version change.

Fixes

• A wrapped graphviz label could break an HTML entity in two. A need title is wrapped
  to the label width and escaped for graphviz's HTML-like labels, but the escaping ran
  first, so the wrapper counted the characters of an entity and could break inside one. A
  title containing a quote wrapped to &quo<br/>t;, and graphviz then refuses the label
  outright: the build reports not well-formed (invalid token) and draws no diagram.
  Wrapping now happens first and each piece is escaped after, which also makes the wrap
  width count the characters the reader sees instead of the ones the escaper wrote.

• A needs_graphviz_styles element type holding something other than a mapping of
  attributes ended the build. The value travelled unchecked into the emitter, where
  'str' object has no attribute 'items' surfaced as an ExtensionError traceback from
  the doctree-resolved handler, naming no configuration key and no file. It is now
  reported where it is read, and the diagram is drawn without the offending style. (An
  entry that is not a mapping was already reported; only an element type got through.)

• An unknown needs_flow_engine value failed a bare assert. That ends the build with
  a traceback rather than a message, and python -O strips it entirely, leaving the
  unknown name to fail somewhere further downstream instead. It is now a needs.config
  warning, said once for the project, and the default engine draws the diagram. The
  :engine: option cannot reach this path, because docutils validates it as it is parsed.

• Naming several graphviz :config: styles leaked the merge into later diagrams. The
  merge took the first style's attribute mapping by reference and then update()d that
  same dictionary with the second style's, so the configured — and the built-in — styles
  were rewritten in place. Every later diagram naming the first style inherited the second
  one's attributes for the rest of the build, and in the built-in case for the life of the
  process, so a page rendered differently depending on which diagrams came before it. The
  attributes are now copied before they are merged.

Deliberate output change (not a fix)

• :debug: now renders the diagram source as a code block under the plantuml engine
  too. It emitted raw HTML — an unnumbered, unstyled <pre> — where graphviz emitted a
  literal block, so the same option gave the source line numbers and the theme's code
  styling on one engine only. Both now emit a literal block; the plantuml source is shown
  unhighlighted, because Pygments has no PlantUML lexer. A project that styles or scrapes
  the debug block will see the new markup, which is why this is listed as an improvement
  rather than a fix. One existing test assertion that matched the plantuml legend at the
  start of a line is rewritten not to depend on the line numbering, exactly as the
  graphviz half of the same test already does.

Also pinned, not changed: :class: reaches the plantuml output only because docutils
copies a replaced node's classes onto the first node replacing it, and graphviz writes the
class on the image rather than the figure. Both honour the option, in different places; the
new test records that so the placement cannot drift unnoticed.

Review notes

• Four commits, each self-contained: the label escaper, the :debug: block, the three
  configuration fixes (one code region), and the changelog.
• Everything is in sphinx_needs/directives/needflow/ — 70 changed lines of source across
  three files, the rest is tests, changelog and docs.
• The two whole-project assert warnings == "" fences in tests/test_needflow.py are
  untouched and still green: nothing here warns on a default path, and the two new warnings
  only fire on input that used to end the build.

[codecov]

Codecov Report

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

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1780      +/-   ##
==========================================
+ Coverage   86.87%   90.64%   +3.76%     
==========================================
  Files          56       76      +20     
  Lines        6532    11340    +4808     
==========================================
+ Hits         5675    10279    +4604     
- Misses        857     1061     +204     

Flag	Coverage Δ
pytests	90.64% <100.00%> (+3.76%)	⬆️

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.