feat: treat generated bundle docs as sources

[AlexanderLanin]

Summary

• Add explicit docs_bundle(srcs = [...]) support for generated documentation sources.
• Keep docs_bundle(data = [...]) for supporting/runtime files.
• Preserve generated source roots through the bundle manifest and resolve them from bazel-bin under bazel run.
• Migrate the metamodel bundle and the generated-source integration fixture.
• Update the generated-docs and Bazel macro documentation.

Design notes

The generated metamodel RST and Mermaid output remain together in srcs, because the RST references the Mermaid file by a relative path and both files form one documentation source tree. Explicit bundle sources must share one parent directory and cannot be combined with source_dir.

Validation

• pre-commit run --all-files
• bazel test //src/extensions/score_mounts:score_mounts_tests --noshow_progress
• bazel run //src/tests/docs_bzl/scenarios/data_files_runfiles:docs --noshow_progress
• bazel run //src/tests/docs_bzl/scenarios/nested_bundles:docs --noshow_progress
• bazel build //:needs_json --noshow_progress
• bazel run //:docs --noshow_progress

[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: 1c6863b1-0e4b-45a1-972d-ad1ae7ab50db
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: 5.734s
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-786: https://eclipse-score.github.io/docs-as-code/pr-786/

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

docs.bzl:125

• The documented srcs contract omits a second enforced restriction: _source_targets_runtime_path rejects any mix of workspace and generated files, even when they have the same logical parent. A caller following this doc could put a handwritten page and generated diagram in one explicit bundle and receive an undocumented analysis failure. Document that all entries must also be uniformly workspace or generated sources (and keep the reference documentation in sync).

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 1 comment.

[Copilot]

🟡 Changes recommended

The unresolved moderate issues affect bundle composition, source isolation, and portable generated-path serialization.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Suppressed comments (2)

Previously missed (2) — in code that hasn't changed since the last review.

bzl/bundle_rules.bzl:338

• Explicit bundles are still deduplicated solely by entry.runtime_path in _ensure_unique_entries. Consequently, two bundles that select different files from the same parent directory now collide during composition, even though file-list mode keeps those source sets independent and the public contract only requires each bundle's files to share a parent. Update uniqueness validation to compare explicit file identities/allowlists (while retaining directory-mount conflicts) so disjoint explicit bundles can share a parent.
  src/extensions/score_sync_toml/_mounts.py:25
• Resolving the path before classifying it makes generated srcs unstable in the generated ubproject.toml: under bazel run, <workspace>/bazel-bin is a symlink, so path.resolve() turns bazel-bin/pkg/index.rst into a machine-specific Bazel cache path outside both the Git root and runfiles tree. The new file-list mount is therefore serialized as an absolute cache path instead of bazel-bin/... (and external runfile symlinks have the same issue). Classify the lexical absolute path first, then fall back to the resolved path for existing canonical-path cases.

• Files reviewed: 19/19 changed files
• Comments generated: 2
• Review effort level: Balanced

[AlexanderLanin]

Thanks, this is valid for the transitional compatibility implementation, but I am intentionally not fixing it in this PR. The recursive data mount exists only to preserve legacy docs_bundle(data = [...]) behavior. Once legacy data discovery is removed, explicit-source bundles will no longer receive that recursive data mount, so the srcs file allowlist cannot be bypassed. I will address this as part of removing the legacy behavior rather than add a separate temporary mounting path here.

[AlexanderLanin]

Agreed, the current wording describes the intended new API but not the transitional compatibility behavior. I am intentionally not changing the documentation in this PR because legacy data discovery is being retained only temporarily. When that behavior is removed, data will be strictly supporting/runtime input and srcs will be the documentation-source path, so the existing wording will become accurate again. I will update the documentation together with that legacy removal instead of documenting a behavior that is about to disappear.

[AlexanderLanin]

Regarding Copilot's suppressed note at docs.bzl:125 about mixing workspace and generated srcs: I agree this identifies an implementation restriction, but I am intentionally not changing this PR. It is an uncommon edge case without a current supported use case, and adding it to the public documentation would add noise around an internal limitation. The existing analysis error already names the restriction. If mixed source kinds become a required use case, I would redesign the runtime path resolution and update the public contract then, rather than expand the documentation now.

[MaximilianSoerenPollak]

Some questions but overall this looks quiet good I would say.

Lot's we already talked about in the call yesterday so I only commented what I now saw and noticed.

[AlexanderLanin]

Addressed the two suppressed findings from review 5086178986 in 2f93014:

• _ensure_unique_entries now keys explicit entries by their declared file paths relative to the shared source root. Disjoint srcs bundles may share a parent; directory mounts and overlapping explicit files still fail. The new shared_parent_bundle analysis regression test covers this.
• _toml_path now classifies the lexical absolute path before resolving symlinks. This preserves bazel-bin/... and stable external runfile spellings, while retaining the resolved-path fallback for canonical entries. Regression tests cover both cases.

Validation: pre-commit passed and bazel test --lockfile_mode=error //... --build_tests_only passed (21/21).

These were suppressed review findings rather than inline threads, so GitHub provides no individual threads to resolve.

[MaximilianSoerenPollak]

Seems fine now for me.

THe comments make it a bit clearer and hopefully will help us in the future whne we look at this again.