feat: needs.json merger

[AlexanderLanin]

Summary

• add a Bazel CLI to merge Sphinx-Needs needs.json inventories
• validate input structure and reject conflicting Need definitions
• write output atomically and preserve existing results on failure
• add unit and Sphinx app-level coverage, including empty inventories
• reuse public docs_bundle targets for test data instead of redundant source filegroups

Validation

• bazel test //scripts_bazel/tests:merge_needs_json_unit_tests //scripts_bazel/tests:merge_needs_json_app_tests --test_output=errors
• bazel build //scripts_bazel:merge_needs_json
• commit hooks: Ruff, BasedPyright, copyright checks

[github-actions]

License Check Results

🚀 The license check job ran with the Bazel command:

bazel run --lockfile_mode=error //src:license-check

Status: ⚠️ Needs Review

Click to expand output

[License Check Output]
Extracting Bazel installation...
Starting local Bazel server (8.6.0) and connecting to it...
INFO: Invocation ID: aa563b95-3d54-4e90-88bf-dfb8700316f1
Computing main repo mapping: 
Loading: 
Loading: 0 packages loaded
Loading: 0 packages loaded
Loading: 0 packages loaded
    currently loading: src
WARNING: Target pattern parsing failed.
ERROR: Skipping '//src:license-check': no such target '//src:license-check': target 'license-check' not declared in package 'src' defined by /home/runner/work/docs-as-code/docs-as-code/src/BUILD
ERROR: no such target '//src:license-check': target 'license-check' not declared in package 'src' defined by /home/runner/work/docs-as-code/docs-as-code/src/BUILD
INFO: Elapsed time: 6.232s
INFO: 0 processes.
ERROR: Build did NOT complete successfully
ERROR: Build failed. Not running target

[github-actions]

Documentation preview for this pull request is available at:
pr-733: https://eclipse-score.github.io/docs-as-code/pr-733/

[a-zw]

You really need it as a script, not a bazel rule?

[AlexanderLanin]

Bazel rule might be easier to use, but harder to write. No big disadvantage in using python AFAIK.

[AlexanderLanin]

You are right that the Bazel-facing interface should be a rule. We will add a dedicated Bazel rule wrapper in a follow-up, while keeping the Python merger as the action implementation.

A pure Starlark implementation is not a good fit here because rule analysis cannot read the contents of generated needs.json inputs; the merge has to run as an execution action. Conversely, exposing only the Python CLI keeps its path-based inputs and manually selected output outside Bazel’s action graph, so consumers lose declared dependencies, caching, sandboxing, incremental rebuilds, and straightforward target composition.

The wrapper gives us the useful split: a Bazel rule as the public API, with label-based inputs and a declared output, invoking the focused and independently testable Python tool internally.

— Generated by GPT-5.6-Sol-Med

[a-zw]

That is a very expensive test if you run Sphinx to verify if your needs-merging works. Test would probably run a lot faster if it relies on static json files instead of generating them with Sphinx.

[a-zw]

Actually this whole "app test" seems unnecessary to me. It rather tests the Sphinx-Needs behavior instead of the merging because the unit tests cover the merging behavior already.

[AlexanderLanin]

unit tests verify artificial json files/pieces, I wanted to test with real json files. I did not create static copies of real json files, as this way they will verify that it still works when we update sphinx-needs. So basically these are black box end to end tests incl sphinx behavior.

On the other hand everything will break horribly anyway when the format changes 😆

[AlexanderLanin]

discussed in call @AlexanderLanin @a-zw @MaximilianSoerenPollak: drop app tests, they will be executed implicitly in bundle tests soon