fix: address review findings and refactor module handling

- Refactor Python tooling to use shared Module dataclass
  * Created tools/models/module.py with centralized module schema
  * Added methods: from_dict, parse_modules, owner_repo, to_dict
  * Migrated scripts to use dataclass: update_module_latest.py,
    update_module_from_known_good.py, override_known_good_repo.py,
    known_good_to_workspace_metadata.py, get_module_info.py
  * Eliminates duplicate parsing logic across tools

- Clean up override_known_good_repo.py
  * Renamed --repo-override to --module-override
  * Removed backward compatibility for deprecated flags
  * Extracted write_known_good() function for better reusability
  * Updated examples to reflect supported formats only

- Improve workflow documentation
  * Clarified ref_int_repo and ref_int_ref semantics in smoke-test workflow
  * Added detailed usage notes for private fork support
  * Updated workflow steps to use --module-override flag
  * Enhanced input descriptions for runner label selection

- Remove generated artifact from git
  * Deleted known_good.updated.json (build output)

Author: kgraeper

…b/workflows/module-integration-build.yml …workflows/reusable_integration-build.yml.github/workflows/module-integration-build.yml renamed to .github/workflows/reusable_integration-build.yml .github/workflows/module-integration-build.yml renamed to .github/workflows/reusable_integration-build.yml

@@ -1,3 +1,49 @@
+# Module Integration Build Workflow
+#
+# Summary:
+#   Builds all modules referenced in known_good.json with Bazel and runs the
+#   integration test script to validate module interoperability.
+#
+# What it does:
+#   - Checks out the reference integration repository
+#   - Updates score_modules.MODULE.bazel from the provided known_good.json
+#   - Builds all referenced modules (via scripts/integration_test.sh and Bazel)
+#   - Runs integration tests
+#   - Uploads logs from _logs/ as artifact: bazel-build-logs-${{ inputs.config }}
+#
+# Inputs:
+#   - known_good (string, required): JSON content used to pin module SHAs.
+#   - config (string, optional, default: bl-x86_64-linux): Bazel config passed as
+#     CONFIG to scripts/integration_test.sh.
+#   - repo_runner_labels (string, optional): Runner label(s). Accepts either a
+#     single label string (e.g., ubuntu-latest) or a JSON string representing a
+#     label or an array of labels (e.g., "\"ubuntu-latest\"" or
+#     "[\"self-hosted\",\"linux\",\"x64\"]").
+#   - ref_int_repo (string, optional, default: eclipse-score/reference_integration):
+#     Reference Integration repository to checkout.
+#   - ref_int_ref (string, optional, default: main): Ref/branch to checkout.
+#   - REPO_READ_TOKEN (secret, optional): Token for private module access; falls
+#     back to github.token when not provided.
+#
+# Runner selection:
+#   - Priority: `inputs.repo_runner_labels` > `vars.REPO_RUNNER_LABELS` > 'ubuntu-latest'.
+#   - `repo_runner_labels` can be provided as a single label string or as JSON
+#     (string or array). When JSON is used, it is parsed via fromJSON().
+#
+# Usage:
+#   This workflow is reusable and triggered via workflow_call from other workflows.
+#   Example:
+#     jobs:
+#       integration:
+#         uses: eclipse-score/reference_integration/.github/workflows/module-integration-build.yml@main
+#         with:
+#           known_good: |
+#             { "modules": [] }
+#           config: bl-x86_64-linux
+#           repo_runner_labels: '"ubuntu-latest"'
+#         secrets:
+#           REPO_READ_TOKEN: ${{ secrets.REPO_READ_TOKEN }}
+#
 name: Module Integration Build
 
 on:
@@ -7,10 +53,6 @@ on:
         description: 'GitHub token with read access to the score modules. Defaults to github.token'
         required: false
     inputs:
-      module_name:
-        description: 'Name of the module to override (e.g., score_baselibs). If not provided, uses repository URL.'
-        required: true
-        type: string
       known_good:
         description: 'Content of the known_good.json file to use for the integration test.'
         required: true
@@ -20,6 +62,10 @@ on:
         required: false
         type: string
         default: 'bl-x86_64-linux'
+      repo_runner_labels:
+        description: 'Runner label(s) for the job; single label or JSON string/array.'
+        required: false
+        type: string
       ref_int_ref:
         description: 'Reference Integration repository ref to checkout.'
         required: false
@@ -34,7 +80,7 @@ on:
 jobs:
   integration-test:
     name: Integration Test
-    runs-on: ubuntu-latest
+    runs-on: ${{ inputs.repo_runner_labels && fromJSON(inputs.repo_runner_labels) || 'ubuntu-latest' }}
     steps:
       - name: Show disk space before build
         run: |

.github/workflows/module-smoke-test.yml .github/workflows/reusable_smoke-test.yml.github/workflows/module-smoke-test.yml renamed to .github/workflows/reusable_smoke-test.yml

@@ -1,9 +1,58 @@
+# Module Smoke Test Workflow
+#
+# Summary:
+#   Orchestrates a fast validation of a single module by producing an
+#   updated known_good.json (optionally overriding one module to the current PR)
+#   and then invoking the integration build workflow to compile and test.
+#
+# What it does:
+#   - Checks out the reference integration repository
+#   - Generates known_good.updated.json:
+#       * If testing an external module PR: overrides `module_name` to the PR SHA
+#       * If testing this repo: updates modules to latest branches
+#   - Uploads known_good.updated.json as an artifact
+#   - Calls the Module Integration Build workflow with a matrix of configs
+#   - Publishes a summary to the GitHub Step Summary
+#
+# Inputs:
+#   - repo_runner_labels (string, required, default: ubuntu-latest): Runner label.
+#   - module_name (string, required): Module to override (e.g., score_baselibs).
+#   - ref_int_repo (string, optional, default: eclipse-score/reference_integration):
+#     The repository that provides the reusable integration workflows and tools.
+#     Use your private fork/org if you mirror this repo (e.g., my-org/reference_integration).
+#     Format: owner/repo
+#   - ref_int_ref (string, required, default: main):
+#     The ref on ref_int_repo to checkout via actions/checkout — can be a branch
+#     name, tag, or commit SHA. This ensures the workflow uses the exact version
+#     of the integration files you intend.
+#
+# Secrets:
+#   - REPO_READ_TOKEN (optional): Token for reading private repos; falls back to
+#     github.token when not provided.
+#
+# Usage:
+#   This workflow is reusable and triggered via workflow_call from other workflows.
+#   Example:
+#     jobs:
+#       smoke:
+#         uses: eclipse-score/reference_integration/.github/workflows/module-smoke-test.yml@main
+#         with:
+#           repo_runner_labels: ubuntu-latest
+#           module_name: score_baselibs
+#           ref_int_ref: main
+#           ref_int_repo: eclipse-score/reference_integration
+#         secrets:
+#           REPO_READ_TOKEN: ${{ secrets.REPO_READ_TOKEN }}
+#
+# Notes:
+#   - Extend the matrix in `integration-test` to cover additional configs.
+
 name: Module Smoke Test
 
 on:
   workflow_call:
     inputs:
-      runner_tag:
+      repo_runner_labels:
         description: 'The runner tag to use for the job'
         required: true
         type: string
@@ -13,12 +62,12 @@ on:
         required: true
         type: string
       ref_int_ref:
-        description: 'Reference Integration repository ref to checkout.'
+        description: 'Ref on ref_int_repo to checkout (branch, tag, or commit SHA).'
         required: true
         type: string
         default: 'main'
       ref_int_repo:
-        description: 'Reference Integration repository to use.'
+        description: 'Repository providing integration workflows (owner/repo). Supports private forks.'
         required: false
         type: string
         default: 'eclipse-score/reference_integration'
@@ -48,7 +97,7 @@ jobs:
             python3 tools/override_known_good_repo.py \
               --known known_good.json \
               --output known_good.updated.json \
-              --repo-override ${{ inputs.module_name }}@${{ github.event.repository.clone_url }}@${{ github.sha }}
+              --module-override ${{ inputs.module_name }}@${{ github.event.repository.clone_url }}@${{ github.sha }}
           else
             echo "Testing reference integration repository itself - updating to latest commits"
             echo "::group::get latest commits from module branches"
@@ -92,13 +141,13 @@ jobs:
           # Add more configs here as needed
           # - bl-aarch64-linux
           # - bl-x86_64-qnx
-    uses: ./.github/workflows/module-integration-build.yml
+    uses: ./.github/workflows/reusable_integration-build.yml
     secrets:
       REPO_READ_TOKEN: ${{ secrets.REPO_READ_TOKEN != '' && secrets.REPO_READ_TOKEN || github.token }}
     with:
-      module_name: ${{ inputs.module_name }}
       known_good: ${{ needs.preparation.outputs.known_good_updated }}
       config: ${{ matrix.config }}
+      repo_runner_labels: ${{ inputs.repo_runner_labels }}
       ref_int_ref: ${{ inputs.ref_int_ref }}
       ref_int_repo: ${{ inputs.ref_int_repo }}
 

.github/workflows/test_integration.yml

@@ -23,7 +23,7 @@ on:
   #   - cron: '30 2 * * *'  # Every night at 02:30 UTC on main branch
 jobs:
   integration_test:
-    uses: ./.github/workflows/module-smoke-test.yml
+    uses: ./.github/workflows/reusable_smoke-test.yml
     secrets: inherit
     with:
       runner_tag: 'ubuntu-latest'

known_good.updated.json

@@ -3,61 +3,66 @@
 
 import json
 import sys
-from typing import Dict, Any
+from typing import Optional
 
+from models import Module
 
-def load_module_data(known_good_file: str, module_name: str) -> Dict[str, Any]:
+
+def load_module(known_good_file: str, module_name: str) -> Optional[Module]:
     """
-    Load module data from known_good.json.
+    Load module from known_good.json.
     
     Args:
         known_good_file: Path to the known_good.json file
         module_name: Name of the module to look up
         
     Returns:
-        Dictionary with module data, or empty dict if not found
+        Module instance, or None if not found
     """
     try:
         with open(known_good_file, 'r') as f:
             data = json.load(f)
-        modules = data.get('modules', {})
-        return modules.get(module_name, {})
+        modules_dict = data.get('modules', {})
+        module_data = modules_dict.get(module_name)
+        
+        if not module_data:
+            return None
+        
+        return Module.from_dict(module_name, module_data)
     except Exception as e:
         # Log error to stderr for debugging
         print(f"Error loading {known_good_file}: {e}", file=sys.stderr)
-        return {}
+        return None
 
 
-def get_module_field(module_data: Dict[str, Any], field: str = 'hash') -> str:
+def get_module_field(module: Optional[Module], field: str = 'hash') -> str:
     """
-    Extract a specific field from module data.
+    Extract a specific field from module.
     
     Args:
-        module_data: Dictionary with module information
+        module: Module instance
         field: Field to extract ('hash', 'version', 'repo', or 'all')
         
     Returns:
         Requested field value, or 'N/A' if not found
-        For 'hash': truncated to 8 chars if longer
+        For 'hash': returns the hash value
         For 'all': returns hash/version (prefers hash, falls back to version)
     """
-    if not module_data:
+    if not module:
         return 'N/A'
 
     if field == 'repo':
-        repo = module_data.get('repo', 'N/A')
+        repo = module.repo or 'N/A'
         # Remove .git suffix if present
         if repo.endswith('.git'):
             repo = repo[:-4]
         return repo
     elif field == 'version':
-        return module_data.get('version', 'N/A')
+        return module.version or 'N/A'
     elif field == 'hash':
-        hash_val = module_data.get('hash', 'N/A')
-        return hash_val
+        return module.hash or 'N/A'
     else:  # field == 'all' or default
-        hash_val = module_data.get('hash', module_data.get('version', 'N/A'))
-        return hash_val
+        return module.hash or module.version or 'N/A'
 
 
 if __name__ == '__main__':
@@ -71,6 +76,6 @@ def get_module_field(module_data: Dict[str, Any], field: str = 'hash') -> str:
     module_name = sys.argv[2]
     field = sys.argv[3] if len(sys.argv) == 4 else 'all'
 
-    module_data = load_module_data(known_good_file, module_name)
-    result = get_module_field(module_data, field)
+    module = load_module(known_good_file, module_name)
+    result = get_module_field(module, field)
     print(result)

tools/get_module_info.py

@@ -3,6 +3,8 @@
 import json
 import csv
 
+from models import Module
+
 MODULES_CSV_HEADER = [
     "repo_url",
     "name",
@@ -22,25 +24,24 @@ def main():
     with open(args.known_good, "r") as f:
         data = json.load(f)
 
-    modules = data.get("modules", {})
+    modules_dict = data.get("modules", {})
+    
+    # Parse modules using Module dataclass
+    modules = Module.parse_modules(modules_dict)
 
     gita_metadata = []
-    for name, info in modules.items():
-        repo_url = info.get("repo", "")
-        if not repo_url:
-            raise RuntimeError("repo must not be empty")
-        
-        # default branch: main
-        branch = info.get("branch", "main")
+    for module in modules:
+        if not module.repo:
+            raise RuntimeError(f"Module {module.name}: repo must not be empty")
 
         # if no hash is given, use branch
-        hash_ = info.get("hash", branch)
+        hash_value = module.hash if module.hash else module.branch
 
         # workspace_path is not available in known_good.json, default to name of repository
-        workspace_path = name
+        workspace_path = module.name
 
         # gita format: {url},{name},{path},{prop['type']},{repo_flags},{branch}
-        row = [repo_url, name, workspace_path, "", "", hash_]
+        row = [module.repo, module.name, workspace_path, "", "", hash_value]
         gita_metadata.append(row)
 
     with open(args.gita_workspace, "w", newline="") as f:

tools/known_good_to_workspace_metadata.py

@@ -0,0 +1,5 @@
+"""Models for score reference integration tools."""
+
+from .module import Module
+
+__all__ = ["Module"]