[PR3] Add local Needs exports for documentation bundles

[AlexanderLanin]

Why this matters

Reusable source-bearing documentation bundles currently contribute content but do not expose a standalone Needs artifact. That prevents a bundle’s own Needs from being validated or consumed independently.

This change establishes the local-export layer for the bundle split. It intentionally supports self-contained bundles only: references to Needs owned outside the bundle remain unresolved and fail strict builds. Cross-bundle resolution and propagation are reserved for PR4.

What changed

• Generate <name>.__internal__.needs_local for every source-bearing bundle.
• Build the export from the bundle’s direct documentation sources.
• Use the bundle’s checked-in conf.py, or its generated configuration when none is provided.
• Use the standard Docs-as-Code dependencies and remove bundle-specific dependency/configuration plumbing.
• Keep local export metadata independent of the host project URL while preserving the project-wide docs():needs_json export.
• Document the internal target and cover a self-contained bundle scenario.

This is the logical PR3 layer on top of the PR0–PR2 history. The upstream PR necessarily targets main because the prerequisite branches are in the contributor fork.

[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: 8afcb2ee-913d-4584-abc8-9ae1d7d3d015
Computing main repo mapping: 
Loading: 
Loading: 0 packages loaded
Loading: 0 packages loaded
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.987s
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-772: https://eclipse-score.github.io/docs-as-code/pr-772/

[MaximilianSoerenPollak]

It seems alright to me.

I think it's hard to judge some edgecases and see if this covers all of the useages we might need.
Easiest to slowly test it in the modules that need it and see what is missing / not quiet right.
Great starting point though. 💯

[Copilot]

Pull request overview

Adds reusable local and upward Needs exports for source-bearing documentation bundles.

Changes:

• Adds upward_bundles hierarchy support and generated Needs targets.
• Extends external Needs resolution for bundle exports.
• Adds documentation and integration/unit coverage.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
docs.bzl	Generates local and upward Needs exports.
bzl/bundle_rules.bzl	Propagates hierarchy metadata.
default_conf.py.tpl	Supports bundle entry documents.
docs/reference/bazel_macros.rst	Documents the new API and flow.
src/extensions/score_metamodel/external_needs.py	Resolves upward exports from runfiles.
src/extensions/score_metamodel/tests/test_external_needs.py	Tests bundle export resolution.
src/tests/docs_bzl/test_upward_bundles.py	Tests bundle export behavior.
src/tests/docs_bzl/README.md	Registers the new scenario.
src/tests/docs_bzl/scenarios/upward_bundles/BUILD	Defines the hierarchy fixture.
src/tests/docs_bzl/scenarios/upward_bundles/platform/index.rst	Provides ancestor Needs.
src/tests/docs_bzl/scenarios/upward_bundles/component/index.rst	Provides dependent Needs.
src/tests/docs_bzl/scenarios/data_files_runfiles/BUILD	Documents data-only behavior.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 3 comments.

[AlexanderLanin]

I am intentionally not applying the suggested change. upward_bundles is defined as an explicit direct-dependency list; resolving needs_upward here would import the ancestor chain implicitly and violate the no-transitive-dependencies contract. Source-less hierarchy groups are now rejected explicitly with an analysis-time error (1d33c85), and consumers must list the source-bearing ancestors they need directly. Leaving this thread open because the proposed behavior conflicts with that contract.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 2 comments.