fix: exclude nested bundle mount roots

[AlexanderLanin]

Why this is needed

When a directory-backed documentation bundle is mounted below another Sphinx source tree, the same documents can be discovered twice: once by the containing directory walk and once by the bundle mount. That creates duplicate document names and Sphinx-Needs IDs, and makes nested module/component layouts unreliable. The ownership boundary must be based on directories rather than the manifest's current file list so files created during live preview remain discoverable.

What this PR achieves

This fixes #781 by making each directory-mounted bundle own its physical source subtree while excluding nested bundle roots from containing walks. For directory mounts, every document is therefore discovered by exactly one Sphinx source: the primary tree or its owning bundle mount.

Changes

• Add structural exclusions for bundle roots below the application's primary source directory.
• Add structural exclusions for child bundle roots below a parent directory mount.
• Preserve directory walking for directory mounts, including files created during live preview.
• Keep explicit docs_bundle(srcs = [...]) mounts in file-list mode.
• Extend the existing reference integration with module/component packages nested below each module's docs directory, covering both legacy data and modern external_needs APIs.
• Document the source-ownership boundaries and runtime behavior.

Known gap

Explicit docs_bundle(srcs = [...]) mounts are intended for generated documentation sources outside the primary source tree and remain in file-list mode. They are not included in the structural directory-exclusion calculation. If a workspace source file is explicitly mounted from below the primary source tree or another directory mount, it can still be discovered twice; handling that case with exact-file exclusions is left for a follow-up.

The regression coverage verifies the directory exclusion rules directly and renders the nested reference integration, including the module-level and integration-level component paths. Existing subdirectory-bundle coverage continues to verify nested bundle composition without duplicate Needs.

[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: 5f42996f-d071-4521-a4bd-a19eee45ad2b
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.747s
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-784: https://eclipse-score.github.io/docs-as-code/pr-784/

[Copilot]

🟡 Changes recommended

Explicit file-list mounts can still be discovered twice, violating the single-owner invariant.

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

Pull request overview

Adds directory-based ownership boundaries to prevent duplicate Sphinx discovery for nested documentation bundles.

Changes:

• Excludes nested bundle roots from primary and parent directory walks.
• Adds nested-package regression coverage and documentation.
• Preserves explicit file-list mounting.

Critical issue: Explicit file-list mounts are omitted from ownership exclusions, allowing containing directory walks to rediscover their files and cause duplicate document names or Need IDs.

File summaries

File	Description
src/tests/docs_bzl/test_subdirectory_bundle.py	Updates nested-bundle coverage.
src/tests/docs_bzl/test_reference_integration.py	Tests nested components.
src/tests/docs_bzl/scenarios/subdirectory_bundle/producer/docs/embedded/content/index.rst	Updates fixture content.
src/tests/docs_bzl/scenarios/subdirectory_bundle/producer/docs/embedded/BUILD	Defines the nested bundle.
src/tests/docs_bzl/scenarios/subdirectory_bundle/producer/BUILD	Relocates the embedded bundle fixture.
src/tests/docs_bzl/scenarios/reference_integration/modern_module/docs/components/component/index.rst	Updates modern component content.
src/tests/docs_bzl/scenarios/reference_integration/modern_module/docs/components/component/BUILD	Defines the modern component package.
src/tests/docs_bzl/scenarios/reference_integration/modern_module/BUILD	Mounts the modern component.
src/tests/docs_bzl/scenarios/reference_integration/legacy_module/docs/components/component/index.rst	Adds legacy component documentation.
src/tests/docs_bzl/scenarios/reference_integration/legacy_module/docs/components/component/BUILD	Defines the legacy component package.
src/tests/docs_bzl/scenarios/reference_integration/legacy_module/BUILD	Mounts the legacy component.
src/tests/docs_bzl/scenarios/reference_integration/BUILD	Describes the nested integration layout.
src/extensions/score_mounts/tests/test_excludes.py	Tests exclusion generation and serialization.
src/extensions/score_mounts/__init__.py	Implements structural exclusions, but omits file-list mounts from ownership processing.
src/extensions/docs/mounts_internals.rst	Documents internal exclusion behavior.
docs/concepts/mounts/index.rst	Documents source ownership boundaries.

Review details

• Files reviewed: 15/16 changed files
• Comments generated: 1
• Review effort level: Balanced

---

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