ci: require version and reason for dependency overrides

Author: rvagg

ci/README.md

@@ -116,21 +116,27 @@ and npm `gitHead` when available.
 
 ## Overrides
 
-Some profile selections can include an optional `overrides` object:
+Some profile selections can include an optional `overrides` object. Each entry
+maps a package name to a `version` and a `reason` explaining why the override
+exists:
 
 ```json
 {
   "strategy": "git_tag",
   "tag": "synapse-sdk-v1.0.1",
   "overrides": {
-    "nanoid": "3.3.13"
+    "nanoid": {
+      "version": "3.3.13",
+      "reason": "nanoid 5.x is ESM-only and breaks the CJS build"
+    }
   }
 }
 ```
 
-Overrides are explicit profile policy. The resolver validates that this is a
-string-to-string map and copies it into resolved metadata. It does not infer
-overrides from package metadata.
+Overrides are explicit profile policy. Both `version` and `reason` are required
+non-empty strings; the resolver rejects any override missing either field, so an
+override cannot be added without documenting why. The reason is logged when the
+override is applied. The resolver does not infer overrides from package metadata.
 
 Overrides are currently allowed only for:
 

scenarios/dependencies.py

@@ -79,8 +79,8 @@ def format_markdown_table(metadata: dict | None = None) -> str:
         overrides = value.get("overrides") or {}
         overrides_text = (
             ", ".join(
-                f"`{package}={override_version}`"
-                for package, override_version in sorted(overrides.items())
+                f"`{package}={spec['version']}`"
+                for package, spec in sorted(overrides.items())
             )
             or "-"
         )

scenarios/synapse.py

@@ -43,16 +43,12 @@ def apply_pnpm_workspace_overrides(sdk_dir: Path, overrides: dict) -> bool:
     if updated and updated[-1]:
         updated.append("")
     updated.append("overrides:")
-    for package, version in sorted(overrides.items()):
-        updated.append(f"  {json.dumps(package)}: {json.dumps(version)}")
+    for package, spec in sorted(overrides.items()):
+        updated.append(f"  {json.dumps(package)}: {json.dumps(spec['version'])}")
 
     workspace.write_text("\n".join(updated) + "\n")
-    info(
-        "Applied pnpm workspace overrides: "
-        + ", ".join(
-            f"{package}={version}" for package, version in sorted(overrides.items())
-        )
-    )
+    for package, spec in sorted(overrides.items()):
+        info(f"pnpm override {package}={spec['version']} ({spec['reason']})")
     return True
 
 

scenarios/test_multi_copy_upload.py

@@ -134,11 +134,12 @@ def setup_filecoin_pin(work_dir: Path) -> tuple[list[str], Path]:
             "type=module",
             f"dependencies.filecoin-pin={dependency['version']}",
         ]
-        for package, version in sorted(overrides.items()):
+        for package, spec in sorted(overrides.items()):
+            info(f"npm override {package}={spec['version']} ({spec['reason']})")
             package_fields.extend(
                 [
-                    f"dependencies.{package}={version}",
-                    f"overrides.{package}={version}",
+                    f"dependencies.{package}={spec['version']}",
+                    f"overrides.{package}={spec['version']}",
                 ]
             )
         run_cmd(

scripts/resolve-ci-dependencies.py

@@ -189,11 +189,19 @@ def npm_metadata(package: str, version: str, runner=run_command) -> dict:
 def validate_overrides(name: str, strategy: str, overrides) -> dict:
     if overrides is None:
         return {}
-    if not isinstance(overrides, dict) or not all(
-        isinstance(key, str) and isinstance(value, str)
-        for key, value in overrides.items()
-    ):
-        raise ResolutionError(f"{name} overrides must be a string map")
+    if not isinstance(overrides, dict):
+        raise ResolutionError(f"{name} overrides must be a map")
+    for package, spec in overrides.items():
+        if (
+            not isinstance(package, str)
+            or not isinstance(spec, dict)
+            or set(spec) != {"version", "reason"}
+            or not all(isinstance(spec[key], str) and spec[key] for key in spec)
+        ):
+            raise ResolutionError(
+                f"{name} override {package!r} must be an object with non-empty "
+                "string 'version' and 'reason' fields"
+            )
 
     if name == "synapse-sdk":
         return dict(sorted(overrides.items()))

scripts/tests/test_resolve_ci_dependencies.py

@@ -151,7 +151,7 @@ def test_profile_overrides_are_copied_to_resolved_component(self):
             "default": {
                 "strategy": "npm_version",
                 "version": "1.0.1",
-                "overrides": {"multiformats": "14.0.2"},
+                "overrides": {"nanoid": {"version": "3.3.13", "reason": "test"}},
             },
         }
         runner = FakeRunner(
@@ -177,16 +177,19 @@ def test_profile_overrides_are_copied_to_resolved_component(self):
             "filecoin-pin", component, "default", runner
         )
 
-        self.assertEqual(resolved["overrides"], {"multiformats": "14.0.2"})
+        self.assertEqual(
+            resolved["overrides"],
+            {"nanoid": {"version": "3.3.13", "reason": "test"}},
+        )
 
-    def test_profile_overrides_must_be_string_map(self):
+    def test_profile_overrides_require_version_and_reason(self):
         component = {
             "repository": "https://example.test/filecoin-pin.git",
             "npm_package": "filecoin-pin",
             "default": {
                 "strategy": "npm_version",
                 "version": "1.0.1",
-                "overrides": {"multiformats": 14},
+                "overrides": {"nanoid": {"version": "3.3.13"}},
             },
         }
         runner = FakeRunner(
@@ -208,7 +211,7 @@ def test_profile_overrides_must_be_string_map(self):
             }
         )
 
-        with self.assertRaisesRegex(resolver.ResolutionError, "overrides"):
+        with self.assertRaisesRegex(resolver.ResolutionError, "reason"):
             resolver.resolve_component("filecoin-pin", component, "default", runner)
 
     def test_overrides_are_rejected_for_core_git_components(self):
@@ -217,7 +220,7 @@ def test_overrides_are_rejected_for_core_git_components(self):
             "frontier": {
                 "strategy": "git_branch",
                 "branch": "master",
-                "overrides": {"nanoid": "3.3.13"},
+                "overrides": {"nanoid": {"version": "3.3.13", "reason": "test"}},
             },
         }
         runner = FakeRunner(
@@ -240,7 +243,7 @@ def test_overrides_are_rejected_for_source_built_filecoin_pin(self):
             "frontier": {
                 "strategy": "git_branch",
                 "branch": "master",
-                "overrides": {"multiformats": "14.0.2"},
+                "overrides": {"nanoid": {"version": "3.3.13", "reason": "test"}},
             },
         }
         runner = FakeRunner(

scripts/tests/test_scenario_dependencies.py

@@ -21,13 +21,12 @@ def test_dependency_table_contains_all_resolved_components(self):
                     "source": "git",
                     "version": "0.41.0",
                     "commit": "bbb",
-                    "overrides": {"nanoid": "3.3.13"},
+                    "overrides": {"nanoid": {"version": "3.3.13", "reason": "test"}},
                 },
                 "filecoin-pin": {
                     "source": "npm",
                     "version": "1.0.1",
                     "commit": "ccc",
-                    "overrides": {"multiformats": "14.0.2"},
                 },
             }
         }
@@ -37,11 +36,9 @@ def test_dependency_table_contains_all_resolved_components(self):
             "synapse-sdk",
             "filecoin-pin",
             "nanoid",
-            "multiformats",
             "aaa",
             "1.0.1",
             "3.3.13",
-            "14.0.2",
         ):
             self.assertIn(expected, table)
 
@@ -53,7 +50,7 @@ def test_dependency_table_contains_all_resolved_components(self):
             "repository": "https://example.test/synapse.git",
             "ref": "sdk-v1.0.0",
             "commit": "deadbeef",
-            "overrides": {"nanoid": "3.3.13"},
+            "overrides": {"nanoid": {"version": "3.3.13", "reason": "test"}},
         },
     )
     def test_synapse_checkout_uses_resolved_commit(self, _component, run_cmd, _sh):
@@ -86,7 +83,7 @@ def fake_run_cmd(command, **_kwargs):
         return_value={
             "source": "npm",
             "version": "1.0.1",
-            "overrides": {"multiformats": "14.0.2"},
+            "overrides": {"nanoid": {"version": "3.3.13", "reason": "test"}},
         },
     )
     def test_filecoin_pin_npm_install_path(self, _component, run_cmd):
@@ -99,11 +96,11 @@ def test_filecoin_pin_npm_install_path(self, _component, run_cmd):
             run_cmd.call_args_list[1].args[0],
         )
         self.assertIn(
-            "dependencies.multiformats=14.0.2",
+            "dependencies.nanoid=3.3.13",
             run_cmd.call_args_list[1].args[0],
         )
         self.assertIn(
-            "overrides.multiformats=14.0.2",
+            "overrides.nanoid=3.3.13",
             run_cmd.call_args_list[1].args[0],
         )