From 8115643f68cbfc022002f67f32da04e84d8dc7b0 Mon Sep 17 00:00:00 2001 From: Thomas <87775189+MTG-Thomas@users.noreply.github.com> Date: Mon, 16 Nov 2026 12:50:40 -0500 Subject: [PATCH 1/2] Make the documented test commands work and unpin the portability test The portability test asserted exact versions (`version == "0.1.3"`, `vitest == "^4.1.11"`), so every dependency bump or downstream version label broke it. It now checks the properties it exists to protect: - the descriptor version is a valid PEP 440 version (local labels such as `0.1.3+site.1` are allowed; the platform compares with `packaging`); - no `bifrost` SDK dependency or `/api/sdk/download` URL in package.json or the lockfile, and no `node_modules/bifrost` lock entry; - Vitest is a dev dependency whose range agrees between package.json and the lockfile root, without pinning a version. The README's check commands failed on a clean machine: the Python command skipped requirements.txt and the `bifrost` Python SDK, and the app tests needed an authenticated `solution sdk update`. Both SDKs are served by any Bifrost instance without authentication, so the README now installs them from `$BIFROST_URL` directly. The web SDK goes into node_modules with `npm install --no-save`, so it is never recorded in package.json or the lockfile while the lockfile still pins the rest of the tree. Co-Authored-By: Claude Opus 5.5 --- README.md | 25 ++++++++++++++++++++--- tests/test_publication_portability.py | 29 +++++++++++++++++++++++---- 2 files changed, 47 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index cff6e47..016892d 100644 --- a/README.md +++ b/README.md @@ -48,15 +48,34 @@ Solution scope through its local proxy. The app never commits an instance URL or authentication token. The server-side Solution builder injects the API-matched web SDK during deployment. -After selecting the SDK with `solution sdk update`, run the focused checks from the repository root: +### Running the checks + +The tests need the Bifrost SDKs that match the instance you deploy to. A Bifrost +instance serves both without authentication, so a clean machine or CI runner can +fetch them directly. Set `BIFROST_URL` to that instance, for example +`https://bifrost.example.com`, and run from the repository root: ```bash -docker run --rm -v "$PWD:/workspace" -w /workspace python:3.12-slim \ - sh -lc 'pip install pytest pyyaml && python -m pytest -q tests' +export BIFROST_URL=https://bifrost.example.com + +# Python tests: requirements.txt, test tooling, and the instance's `bifrost` Python SDK. +docker run --rm -e BIFROST_URL -v "$PWD:/workspace" -w /workspace python:3.13-slim \ + sh -lc 'pip install pytest pytest-asyncio pydantic pyyaml packaging -r requirements.txt \ + "$BIFROST_URL/api/cli/download/bifrost-cli.tar.gz" && python -m pytest -q tests' + +# App tests and build (Node.js 22.12 or later). +npm --prefix apps/bifrost-docs ci +npm --prefix apps/bifrost-docs install --no-save "bifrost@$BIFROST_URL/api/sdk/download" npm --prefix apps/bifrost-docs test npm --prefix apps/bifrost-docs run build ``` +The second `npm` command adds the instance's web SDK to `node_modules` only, as +`bifrost solution sdk update` does: `--no-save` keeps it out of `package.json` and +`package-lock.json`, while the lockfile still pins every other package. In a bound +checkout, `bifrost solution sdk update . --app bifrost-docs` installs the SDK for +you. Never commit the SDK dependency; the portability test rejects it. + ## Optional IT Glue migration The `IT Glue` connection in `.bifrost/connections.yaml` is optional. To migrate diff --git a/tests/test_publication_portability.py b/tests/test_publication_portability.py index a72cc3a..809218f 100644 --- a/tests/test_publication_portability.py +++ b/tests/test_publication_portability.py @@ -6,6 +6,7 @@ from pathlib import Path import yaml +from packaging.version import InvalidVersion, Version ROOT = Path(__file__).resolve().parents[1] @@ -21,12 +22,32 @@ def test_solution_distribution_has_no_instance_sdk_or_private_delivery_artifacts vite_config = (ROOT / "apps/bifrost-docs/vite.config.ts").read_text() readme = (ROOT / "README.md").read_text() - assert descriptor["version"] == "0.1.3" + # Forks and downstream installs may carry PEP 440 local labels such as + # ``0.1.3+site.1``; the platform compares versions with ``packaging``. + version = str(descriptor["version"]) + try: + Version(version) + except InvalidVersion as exc: + raise AssertionError(f"descriptor version {version!r} is not PEP 440") from exc assert descriptor["allow_outbound_access"] is False - assert "bifrost" not in package["dependencies"] - assert package["devDependencies"]["vitest"] == "^4.1.11" - assert lockfile_data["packages"][""]["devDependencies"]["vitest"] == "^4.1.11" + + # The instance SDK is installed at build time and never recorded in the + # distributed manifests. + lock_root = lockfile_data["packages"][""] + for manifest in (package, lock_root): + for section in ("dependencies", "devDependencies", "optionalDependencies", "peerDependencies"): + assert "bifrost" not in manifest.get(section, {}) assert '"node_modules/bifrost"' not in lockfile + assert "/api/sdk/download" not in json.dumps(package) + assert "/api/sdk/download" not in lockfile + + # Vitest is a locked dev dependency; any version range is acceptable as + # long as package.json and the lockfile agree. + vitest_spec = package["devDependencies"].get("vitest") + assert isinstance(vitest_spec, str) and vitest_spec + assert "vitest" not in package.get("dependencies", {}) + assert lock_root["devDependencies"].get("vitest") == vitest_spec + assert lockfile_data["packages"]["node_modules/vitest"]["dev"] is True assert "VITE_BIFROST_SOLUTION_ID" in vite_config assert "solutionId: import.meta.env.VITE_BIFROST_SOLUTION_ID" in bootstrap assert "window.location.origin" not in bootstrap From cace7231c00735454bdf1b2d44a7f49625b3c640 Mon Sep 17 00:00:00 2001 From: Thomas <87775189+MTG-Thomas@users.noreply.github.com> Date: Mon, 16 Nov 2026 12:56:45 -0500 Subject: [PATCH 2/2] CI: test against the production SDKs and enforce version bumps on mtg Adds .github/workflows/ci.yml for pull requests into main and mtg and for pushes to mtg: - python-tests: requirements.txt plus test tooling and the instance's `bifrost` Python SDK (the public CLI sdist), then the Solution tests and the version-policy unit tests. - app-tests: `npm ci`, the instance's web SDK installed with `--no-save` so it never reaches package.json or the lockfile (asserted), `npm test`, and `npm run build`. - version-policy (PRs into mtg only): when a PR changes deployable paths, the head `bifrost.solution.yaml` version must be greater than the base version (PEP 440). The failure names the next `+mtg.N` version. Both SDKs come from `vars.BIFROST_URL` (default the production instance) without credentials. Actions are pinned to commit SHAs, the token is read-only, and superseded PR runs are cancelled. Co-Authored-By: Claude Opus 5.5 --- .github/scripts/test_version_policy.py | 175 +++++++++++++++++++++++++ .github/scripts/version_policy.py | 159 ++++++++++++++++++++++ .github/workflows/ci.yml | 105 +++++++++++++++ 3 files changed, 439 insertions(+) create mode 100644 .github/scripts/test_version_policy.py create mode 100644 .github/scripts/version_policy.py create mode 100644 .github/workflows/ci.yml diff --git a/.github/scripts/test_version_policy.py b/.github/scripts/test_version_policy.py new file mode 100644 index 0000000..1c99348 --- /dev/null +++ b/.github/scripts/test_version_policy.py @@ -0,0 +1,175 @@ +"""Unit tests for version_policy.py (run: python -m pytest -q .github/scripts).""" + +from __future__ import annotations + +import subprocess +import sys +from pathlib import Path + +import pytest +from packaging.version import Version + +sys.path.insert(0, str(Path(__file__).resolve().parent)) + +import version_policy as vp # noqa: E402 + + +def descriptor(version: str) -> str: + return f"slug: bifrost-docs\nname: Bifrost Docs\nversion: {version}\n" + + +@pytest.mark.parametrize( + "path", + [ + "README.md", + "SECURITY.md", + "docs/CUTOVER_RUNBOOK.md", + "docs/DESIGN_SYSTEM_PROVENANCE.json", + "tests/test_folders.py", + ".github/workflows/ci.yml", + ".github/scripts/version_policy.py", + "apps/bifrost-docs/README.md", + "apps/bifrost-docs/src/app.test.tsx", + "apps/bifrost-docs/src/lib/deep/thing.test.ts", + "apps/bifrost-docs/scripts/browser-qa.cjs", + ], +) +def test_non_deployable_paths(path: str) -> None: + assert not vp.is_deployable(path) + + +@pytest.mark.parametrize( + "path", + [ + "bifrost.solution.yaml", + "requirements.txt", + ".bifrost/tables.yaml", + "functions/docs_search.py", + "modules/indexing.py", + "apps/bifrost-docs/package.json", + "apps/bifrost-docs/package-lock.json", + "apps/bifrost-docs/src/app.tsx", + "apps/bifrost-docs/src/test-utils.ts", + "apps/bifrost-docs/vite.config.ts", + "tests.py", + "docsite/index.html", + "LICENSE", + ], +) +def test_deployable_paths(path: str) -> None: + assert vp.is_deployable(path) + + +@pytest.mark.parametrize( + ("base", "expected"), + [ + ("0.1.3", "0.1.3+mtg.1"), + ("0.1.3+mtg.1", "0.1.3+mtg.2"), + ("0.1.3+mtg.9", "0.1.3+mtg.10"), + ("0.1.4", "0.1.4+mtg.1"), + ], +) +def test_suggest_next(base: str, expected: str) -> None: + suggestion = vp.suggest_next(Version(base)) + assert suggestion == expected + assert Version(suggestion) > Version(base) + + +def test_pep440_ordering_matches_release_flow() -> None: + assert Version("0.1.3") < Version("0.1.3+mtg.1") < Version("0.1.3+mtg.2") < Version("0.1.4") + + +def test_non_deployable_change_needs_no_bump() -> None: + ok, message = vp.evaluate( + ["README.md", ".github/workflows/ci.yml", "tests/test_x.py"], + descriptor("0.1.3"), + descriptor("0.1.3"), + ) + assert ok, message + + +def test_deployable_change_without_bump_fails_with_suggestion() -> None: + ok, message = vp.evaluate( + ["functions/docs_search.py", "README.md"], + descriptor("0.1.3+mtg.1"), + descriptor("0.1.3+mtg.1"), + ) + assert not ok + assert "0.1.3+mtg.2" in message + assert "functions/docs_search.py" in message + assert "README.md" not in message + + +def test_deployable_change_with_downgrade_fails() -> None: + ok, _ = vp.evaluate(["modules/x.py"], descriptor("0.1.3+mtg.2"), descriptor("0.1.3+mtg.1")) + assert not ok + + +@pytest.mark.parametrize("head", ["0.1.3+mtg.1", "0.1.4", "0.2.0"]) +def test_deployable_change_with_bump_passes(head: str) -> None: + ok, message = vp.evaluate(["modules/x.py"], descriptor("0.1.3"), descriptor(head)) + assert ok, message + + +def test_invalid_head_version_fails() -> None: + ok, message = vp.evaluate(["modules/x.py"], descriptor("0.1.3"), descriptor("next")) + assert not ok + assert "PEP 440" in message + assert "0.1.3+mtg.1" in message + + +def _git(repo: Path, *args: str) -> str: + return subprocess.run( + ["git", "-C", str(repo), *args], check=True, capture_output=True, text=True + ).stdout.strip() + + +@pytest.fixture +def repo(tmp_path: Path) -> Path: + _git(tmp_path, "init", "-q", "-b", "mtg") + _git(tmp_path, "config", "user.email", "ci@example.invalid") + _git(tmp_path, "config", "user.name", "CI") + _git(tmp_path, "config", "commit.gpgsign", "false") + (tmp_path / "bifrost.solution.yaml").write_text(descriptor("0.1.3")) + (tmp_path / "modules").mkdir() + (tmp_path / "modules/x.py").write_text("x = 1\n") + _git(tmp_path, "add", ".") + _git(tmp_path, "commit", "-q", "-m", "base") + _git(tmp_path, "checkout", "-q", "-b", "feature") + return tmp_path + + +def _commit(repo: Path, path: str, text: str) -> str: + (repo / path).parent.mkdir(parents=True, exist_ok=True) + (repo / path).write_text(text) + _git(repo, "add", path) + _git(repo, "commit", "-q", "-m", f"change {path}") + return _git(repo, "rev-parse", "HEAD") + + +def _run(repo: Path, monkeypatch: pytest.MonkeyPatch, base: str, head: str) -> int: + monkeypatch.chdir(repo) + return vp.main(["--base", base, "--head", head]) + + +def test_main_end_to_end(repo: Path, monkeypatch: pytest.MonkeyPatch) -> None: + base = _git(repo, "rev-parse", "mtg") + head = _commit(repo, "docs/NOTES.md", "notes\n") + assert _run(repo, monkeypatch, base, head) == 0 + + head = _commit(repo, "modules/x.py", "x = 2\n") + assert _run(repo, monkeypatch, base, head) == 1 + + head = _commit(repo, "bifrost.solution.yaml", descriptor("0.1.3+mtg.1")) + assert _run(repo, monkeypatch, base, head) == 0 + + +def test_main_ignores_changes_that_landed_on_base( + repo: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + head = _commit(repo, "tests/test_y.py", "def test_y(): pass\n") + _git(repo, "checkout", "-q", "mtg") + base = _commit(repo, "modules/x.py", "x = 3\n") + _git(repo, "checkout", "-q", "feature") + # The base moved on with a deployable change; the PR itself only touches tests. + assert _run(repo, monkeypatch, base, head) == 0 diff --git a/.github/scripts/version_policy.py b/.github/scripts/version_policy.py new file mode 100644 index 0000000..b6e7f5d --- /dev/null +++ b/.github/scripts/version_policy.py @@ -0,0 +1,159 @@ +#!/usr/bin/env python3 +"""Require a Solution version bump for deployable changes merged into ``mtg``. + +Bifrost polls ``version:`` in ``bifrost.solution.yaml`` on the followed branch +and only offers an update when it increases (compared with ``packaging``). A +deployable change merged without a bump would never reach installs. + +Usage (from a full-history checkout):: + + python .github/scripts/version_policy.py --base --head + +Exit codes: 0 = policy satisfied, 1 = version bump missing or invalid. +""" + +from __future__ import annotations + +import argparse +import re +import subprocess +import sys +from collections.abc import Iterable, Sequence + +import yaml +from packaging.version import InvalidVersion, Version + +DESCRIPTOR = "bifrost.solution.yaml" +LOCAL_LABEL = "mtg" + +# Paths that never change what an install runs. Everything else is deployable. +NON_DEPLOYABLE_PATTERNS: tuple[str, ...] = ( + "docs/**", + "**/*.md", + "tests/**", + ".github/**", + "apps/*/src/**/*.test.*", + "apps/*/scripts/**", +) + + +def _glob_to_regex(pattern: str) -> re.Pattern[str]: + """Translate a path glob: ``*`` stays within a segment, ``**/`` spans any depth.""" + out: list[str] = [] + i = 0 + while i < len(pattern): + if pattern.startswith("**/", i): + out.append("(?:.*/)?") + i += 3 + elif pattern.startswith("**", i): + out.append(".*") + i += 2 + elif pattern[i] == "*": + out.append("[^/]*") + i += 1 + elif pattern[i] == "?": + out.append("[^/]") + i += 1 + else: + out.append(re.escape(pattern[i])) + i += 1 + return re.compile("".join(out) + r"\Z") + + +_NON_DEPLOYABLE = tuple(_glob_to_regex(p) for p in NON_DEPLOYABLE_PATTERNS) + + +def is_deployable(path: str) -> bool: + return not any(rx.match(path) for rx in _NON_DEPLOYABLE) + + +def deployable_paths(paths: Iterable[str]) -> list[str]: + return sorted({p for p in paths if p and is_deployable(p)}) + + +def parse_descriptor_version(text: str | None) -> Version | None: + """Return the descriptor's version, or None when the file is absent.""" + if text is None: + return None + data = yaml.safe_load(text) or {} + raw = data.get("version") + if raw is None: + raise ValueError(f"{DESCRIPTOR} has no `version:` field") + try: + return Version(str(raw)) + except InvalidVersion as exc: + raise ValueError(f"{DESCRIPTOR} version {raw!r} is not a valid PEP 440 version") from exc + + +def suggest_next(base: Version | None, label: str = LOCAL_LABEL) -> str: + """Next ``+