Add resolved-dependency override mechanism for DR-008

[Subramanian-K812]

DR-008: resolved-dependency resolve + override mechanism (PR 1 of 2)

Part of #264. This is the first of two PRs that split the original DR-008 Option 4
change. This PR adds only the mechanism; the follow-up
PR wires it into the test workflow.

What this PR does

Adds ResolvedDependencies — the mechanism DR-008 Option 4 needs to (1) resolve the full
integrated dependency set at the reference_integration root and (2) override those
resolved versions directly into an individual module.

• Resolve (root): merges the override directives ref_int actually declares
  (MODULE.bazel + bazel_common/*.MODULE.bazel) with the post-MVS registry versions
  from bazel mod graph --output=json, and serializes the result to a single
  resolved_versions.json manifest (--export / from_mod_graph / to_file).
• Override (into a module): scans a module's MODULE.bazel for every declared
  bazel_dep and appends a git_override / single_version_override for each one we
  have a resolved version for, so the module builds/tests against the resolved set
  (scan / overwrite). Injection is append-only and idempotent (marked with begin/end
  comments), always skips the module-under-test itself (the root is never overridden),
  always overwrites any dependency the module already declares an override for (ref_int's
  resolved version always wins), and is never committed back to module sources. A declared
  dependency with no entry in the resolved set is left to resolve on its own and logs a
  warning — this is expected to be effectively impossible once the resolved set comes from
  the full bazel mod graph (a superset of any module's own graph).

Files

File	Change
scripts/known_good/resolved_dependencies.py	New — the ResolvedDependencies mechanism (resolve + override) + CLI
scripts/known_good/tests/test_resolved_dependencies.py	New — 18 self-contained unit tests (no cloned repos / Bazel needed)
scripts/known_good/BUILD	New — py_library :known_good, py_binary :resolve_deps (Bazel-runnable), and score_py_pytest :known_good_tests so the unit tests run under Bazel
scripts/tooling/BUILD	Modified — alias :resolve_deps exposing it as bazel run //scripts/tooling:resolve_deps

Follow-up (PR 2)

The two-stage test_and_docs.yml (Stage 1 resolves + exports the manifest; Stage 2 checks
out each module, overrides deps via this mechanism, and runs its UT + coverage; then
aggregates), the module-context quality_runners.py, the dependency pin bumps, and the
associated config all land in the follow-up PR, which is stacked on this one.

[github-actions]

The created documentation from the pull request is available at: docu-html

[a-zw]

Why this alias? This is usually for backwards-compatibility but since this is new functionality it should not be necessary.

[Subramanian-K812]

The alias under //scripts/tooling provides reachability alongside other entry points. The implementation itself remains in //scripts/known_good since that’s where its models and tests live. The pipeline continues to call //scripts/known_good:resolve_deps directly; the alias simply exposes it without duplicating the target.

[a-zw]

I like this self-contained aspect. It allows to use this in an hermetic way.

However, the tradeoff is that we cannot parallelize the followup actions (build, test, docs, etc) via GitHub actions, can we?

[Subramanian-K812]

No, they can still run in parallel. Stage 1 resolves once and uploads resolved_versions.json as an artifact; each Stage 2 module job downloads that same artifact and does its own local override + build/test independently, still as a normal parallel matrix. The hermetic is only about the unit tests not needing real clones/bazel to validate scan()/overwrite() — it doesn't force any job serialization in the actual pipeline.

[OliverHeilwagen]

Please fix transitive dependency pinning gap

[OliverHeilwagen]

Please extend description for Stage 1.
bazel mod graph --output json > graph.json is required as prerequisite.

In the script please make use of BUILD_WORKING_DIRECTORY or BUILD_WORKSPACE_DIRECTORY environment variable so the graph.json file can be found without requiring to be in data = ["..."]

[OliverHeilwagen]

Please keep Stage 1 and Stage 2 in sync.
--resolved-deps artifacts/ or _resolved_deps in both.

[OliverHeilwagen]

Please make use of BUILD_WORKING_DIRECTORY or BUILD_WORKSPACE_DIRECTORY environment variable instead.

[OliverHeilwagen]

Please add support for multiple_version_override .

[OliverHeilwagen]

Please check file existence before using it.

[OliverHeilwagen]

Suggested change

	override_files = [repo_root / "MODULE.bazel", *sorted((repo_root / "bazel_common").glob("*.MODULE.bazel"))]
	override_files = [f for f in override_files if f.is_file()]
	override_files = [
	f for f in [repo_root / "MODULE.bazel", *sorted((repo_root / "bazel_common").glob("*.MODULE.bazel"))]
	if f.is_file()
	]

[OliverHeilwagen]

Transitive dependency pinning gap

overwrite() only injects overrides for modules the module-under-test directly declares
via bazel_dep. Transitive dependencies silently fall through to MVS resolution, which may
pick a different version than what ref_int validated against.

Example:

ref_int (resolved: flatbuffers @ 25.12.19)
    └── communication (module under test)
            └── bazel_dep(name = "score_baselibs")   ← override injected ✅
                    └── flatbuffers            ← transitive, NO override injected ❌
                                                 MVS picks its own version

Fix: For every module in the resolved set that is not directly declared by the
module-under-test, inject both a bazel_dep stub and the override into the injection block:

# brings the transitive dep into the root graph so the override is valid
bazel_dep(name = "flatbuffers", version = "0.0.0")
git_override(module_name = "flatbuffers", commit = "...", remote = "...")

This also means from_known_good is insufficient for the inject mode, as it only carries
first-party score modules and has no transitive registry versions; --resolved-deps (from the
Stage-1 manifest) must be the required source for Stage 2 injection.

In Stage-1 we should also takeover and store the given graph.json as it is needed for Stage-2 to be aware of the necessary transitive overrides for a given MODULE.bazel file. Identification can be done via regex for module(name = "...").