Add central RunOutputRoot class for deriving CI run output paths on S3

[ScottTodd]

This PR introduces a new RunOutputRoot class that centralizes path construction, clearly documents which files are uploaded where, and adds many new unit tests.

Motivation

We had multiple files constructing paths on S3 for CI outputs such as artifacts, logs, and reports. Each of these files needed to know what schema to follow and there was risk of the files not agreeing on conventions. Several files even used the retrieve_bucket_info() function which just returned a tuple of [EXTERNAL_REPO, BUCKET].

This is prerequisite work for:

• [CI] Build and test rocm Python packages as part of ci.yml #1559
  • I want to upload ROCm Python packages (with "dev" versioning) to S3 and this builds a foundation for new files
• [Feature]: ROCm submodule bisect tools #2608
  • I want to list and download ROCm artifacts from workflow runs without copying the URL structure again

Technical Details

Key changes:

1. Added new build_tools/_therock_utils/run_outputs.py file with a new RunOutputRoot class

2. Migrated existing code to use the new class, like so:

   - analysis_url = f"{bucket_url}/logs/{artifact_group}/build_time_analysis.html"
   + analysis_url = run_root.build_time_analysis_url(artifact_group)

   - s3_prefix = f"{external_repo}{run_id}-{platform}"
   + s3_prefix = run_root.prefix

3. Moved retrieve_bucket_info() from github_actions_utils.py to the new file as an implementation detail

4. Added new documentation for the directory structure of workflow run outputs in docs/development/run_outputs_layout.md

5. Added new unit tests

See also:

• Planning and notes: https://github.com/ScottTodd/claude-rocm-workspace/blob/main/tasks/active/run-outputs-layout.md
• Self-review at https://github.com/ScottTodd/claude-rocm-workspace/blob/main/reviews/local_005_run-outputs.md

Test Plan

• Added new unit tests and updated existing unit tests
• Watch CI for unexpected file paths, broken logs, errors, etc.

Note

I also want better ways to test these sorts of changes, so I added some follow-up plans in my plan/notes doc at Follow-up Work: Local Testing & Backend Abstraction. The main ideas are to

1. Add a --dry-run option to post_build_upload.py
2. Refactor uploading to use a "backend" abstraction that can choose between S3 and local, so a developer can "upload" a set of local files into a local folder with the same directory structure as the CI would upload to S3

Test Result

• CI jobs have the expected links to run outputs: https://github.com/ROCm/TheRock/actions/runs/21155514542?pr=3000#summary-60839570782
  • https://therock-ci-artifacts-external.s3.amazonaws.com/ROCm-TheRock/21155514542-linux/logs/gfx110X-all/index.html
  • https://therock-ci-artifacts-external.s3.amazonaws.com/ROCm-TheRock/21155514542-linux/logs/gfx110X-all/build_time_analysis.html
  • https://therock-ci-artifacts-external.s3.amazonaws.com/ROCm-TheRock/21155514542-linux/index-gfx110X-all.html
  • https://therock-ci-artifacts-external.s3.amazonaws.com/ROCm-TheRock/21155514542-linux/manifests/gfx110X-all/therock_manifest.json

Submission Checklist

• Look over the contributing guidelines at https://github.com/ROCm/ROCm/blob/develop/CONTRIBUTING.md#pull-requests.

[ScottTodd]

I'm redoing this PR, closing the draft.