Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions .github/workflows/fork-surface.yml
Original file line number Diff line number Diff line change
Expand Up @@ -87,3 +87,11 @@ jobs:
# "which upstream is this built on?" as guesswork.
- name: Check the upstream pin matches the tree
run: scripts/upstream-pin.py --verify

# The merge driver takes upstream's lockfile whole, and `yarn install`
# re-derives only what package.json asks for, so a sync silently undoes
# every fix main held in the lockfile alone. Compared against where this
# branch joins main, so a branch cut before main moved on is not held to
# versions it never saw.
- name: Check the lockfile holds main's versions
run: scripts/lockfile-floor.py
14 changes: 14 additions & 0 deletions .github/workflows/upstream-sync.yml
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,8 @@ jobs:
echo "branch=$branch" >> "$GITHUB_OUTPUT"
echo "Cutting $branch from $base"
git checkout -B "$branch" "$base"
# The lockfile floor is main as it stood at the cut, before any merge.
echo "base_sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"

# THE TEMPORARY LAYER COMES OFF BEFORE THE MERGE. Our security pins and
# patches are generated, not committed, precisely so the merge sees no
Expand Down Expand Up @@ -245,6 +247,8 @@ jobs:
steps.merge.outputs.status == 'clean' || steps.merge.outputs.status ==
'replayed'
continue-on-error: true # a failure must still surface a PR, not just red the run
env:
BASE_SHA: ${{ steps.branch.outputs.base_sha }}
run: |
corepack enable
# NOT --immutable: the lockfile is upstream's at this point (the merge
Expand All @@ -253,6 +257,16 @@ jobs:
# wrong one exactly here.
yarn install --mode=update-lockfile
yarn install
# Step 5 of docs/fork/sync-cycle.md. The driver took upstream's
# lockfile whole, so every fix main held in the lockfile alone came
# back older and `yarn install` did not notice. Re-resolve those
# packages inside their declared ranges, then fail if any is still
# below the version main held.
regressed="$(scripts/lockfile-floor.py --base "$BASE_SHA" --names)"
if [ -n "$regressed" ]; then
yarn up -R $regressed
fi
scripts/lockfile-floor.py --base "$BASE_SHA"
scripts/security-override.py --verify
scripts/upstream-pin.py --verify
# NOT `yarn build`: that is the DFE wrapper
Expand Down
1 change: 1 addition & 0 deletions docs/fork/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,7 @@ lockfile merge driver are all per-clone git config, and a fresh clone starts unp
| `.githooks/fork-surface-check.py --audit` | What is catalogued that should not be? |
| `scripts/security-override.py --verify` | Does the tree match the security register? |
| `scripts/upstream-pin.py --show` | Which upstream are we built on? |
| `scripts/lockfile-floor.py` | Does the lockfile resolve any package below main's version? |
| `scripts/security-triage.py --audit` | What is newly vulnerable, and is it reachable? |

`--drift` is the one to run before starting work. It is the cheap moment to
Expand Down
14 changes: 11 additions & 3 deletions docs/fork/sync-cycle.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,9 @@ git merge '@hyperdx/app@2.34.0' # 2
scripts/security-override.py --apply # 3
scripts/upstream-pin.py --set '@hyperdx/app@2.34.0' # 4
yarn install # 5
yarn up -R $(scripts/lockfile-floor.py --names)
scripts/security-override.py --verify # 6
scripts/lockfile-floor.py
scripts/upstream-pin.py --verify
yarn build && yarn test # 7
scripts/security-triage.py --audit --patches --carried # 8
Expand Down Expand Up @@ -179,9 +181,15 @@ right flag everywhere else and the wrong one at exactly this point.

`yarn install` re-derives only what our `package.json` asks for. A fix main
holds in the lockfile alone - a `yarn up -R` inside a declared range - is gone
after the merge, and nothing fails. Diff the resolved versions against
`origin/main` and run `yarn up -R` again on every package main had moved past
upstream. The 2.40.0 sync lost seven PRs of them, Next's RCE fix among them.
after the merge, and nothing fails. The 2.40.0 sync lost seven PRs of them,
Next's RCE fix among them.

`scripts/lockfile-floor.py` diffs the resolved versions against the base branch
and names every package that fell.
`yarn up -R $(scripts/lockfile-floor.py --names)` puts them back inside their
declared ranges, and the sync workflow runs both. `fork-surface.yml` runs the
check on every PR and fails one that leaves a package below main's. An intended
downgrade goes in `security/lockfile-floor-allow.txt` as `<package> <reason>`.

### 6. The invariants

Expand Down
268 changes: 268 additions & 0 deletions scripts/__tests__/test_lockfile_floor.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,268 @@
#!/usr/bin/env python3
# Project: dfe-hyperdx
# File: scripts/__tests__/test_lockfile_floor.py
# Purpose: Prove the lockfile floor check names what fell and ignores what did not
# Language: Python
#
# License: MIT (inherits upstream hyperdxio/hyperdx)
# Copyright: (c) 2026 HYPERI PTY LIMITED
"""Tests for lockfile-floor.py.

The comparison is pinned against small lockfiles written in yarn's own shape.
The command line runs the real script against a throwaway git repo, because the
base lockfile comes from `git show`.

Run::

python3 -m unittest discover -s scripts/__tests__ -v
"""

from __future__ import annotations

import importlib.util
import shutil
import subprocess
import sys
import tempfile
import unittest
from pathlib import Path

SOURCE = Path(__file__).resolve().parent.parent / "lockfile-floor.py"

_SPEC = importlib.util.spec_from_file_location("lockfile_floor", SOURCE)
assert _SPEC is not None and _SPEC.loader is not None
tool = importlib.util.module_from_spec(_SPEC)
sys.modules[_SPEC.name] = tool
_SPEC.loader.exec_module(tool)

Entry = tuple[tuple[str, ...], str, str, str]


def lock(*entries: Entry) -> str:
"""A lockfile with one entry per (descriptors, name, version, protocol)."""
out = ["__metadata:\n version: 8\n cacheKey: 10c0\n"]
for descriptors, name, version, protocol in entries:
header = ", ".join(descriptors)
out.append(
f'"{header}":\n version: {version}\n'
f' resolution: "{name}@{protocol}{version}"\n languageName: node\n'
)
return "\n".join(out)


def npm(descriptor: str, version: str) -> Entry:
name = descriptor.split("@npm:")[0]
return ((descriptor,), name, version, "npm:")


def fell(base: str, head: str) -> dict[str, list[str]]:
return tool.below_floor(tool.parse_lockfile(base), tool.parse_lockfile(head))


class VersionOrderTest(unittest.TestCase):
def test_semver_order(self) -> None:
ascending = [
"1.0.0-alpha",
"1.0.0-alpha.1",
"1.0.0-beta",
"1.0.0-rc.2",
"1.0.0",
"1.0.1",
"1.10.0",
"2.0.0-next.5",
"2.0.0-next.7",
"2.0.0",
]
keys = [tool.version_key(v) for v in ascending]
self.assertEqual(keys, sorted(keys))
self.assertEqual(len(set(keys)), len(keys))

def test_not_semver(self) -> None:
for value in ("", "latest", "1.0", "v1.2.3"):
with self.subTest(value=value):
self.assertIsNone(tool.version_key(value))


class ParseTest(unittest.TestCase):
def test_keeps_every_descriptor_of_an_entry(self) -> None:
text = lock(
(("tar@npm:^6.0.0", "tar@npm:^6.2.1"), "tar", "6.2.1", "npm:"),
npm("@babel/types@npm:^7.20.7", "7.29.11"),
)
self.assertEqual(
tool.parse_lockfile(text),
{
"tar@npm:^6.0.0": ("tar", "6.2.1"),
"tar@npm:^6.2.1": ("tar", "6.2.1"),
"@babel/types@npm:^7.20.7": ("@babel/types", "7.29.11"),
},
)

def test_skips_workspaces_and_patches(self) -> None:
text = lock(
(
("@hyperdx/api@workspace:packages/api",),
"@hyperdx/api",
"0.0.0",
"workspace:",
),
(("resolve@patch:resolve@npm%3A1.22.8",), "resolve", "1.22.8", "patch:"),
)
self.assertEqual(tool.parse_lockfile(text), {})


class BelowFloorTest(unittest.TestCase):
def test_cases(self) -> None:
cases = {
"same": (
lock(npm("tar@npm:^7.0.0", "7.5.22")),
lock(npm("tar@npm:^7.0.0", "7.5.22")),
[],
),
"raised": (
lock(npm("tar@npm:^7.0.0", "7.5.22")),
lock(npm("tar@npm:^7.0.0", "7.6.0")),
[],
),
"descriptor fell": (
lock(npm("tar@npm:^7.0.0", "7.5.22")),
lock(npm("tar@npm:^7.0.0", "6.2.1")),
["tar"],
),
"dropped dependency": (
lock(npm("tar@npm:^7.0.0", "7.5.22")),
lock(npm("other@npm:^1.0.0", "1.0.0")),
[],
),
"older copy resolves lower beside a current one": (
lock(
npm("@babel/types@npm:^7.0.0", "7.29.11"),
npm("@babel/types@npm:^7.29.7", "7.29.11"),
),
lock(
npm("@babel/types@npm:^7.0.0", "7.28.5"),
npm("@babel/types@npm:^7.29.7", "7.29.11"),
),
["@babel/types"],
),
"range renamed and the line fell": (
lock(npm("ip-address@npm:^10.1.0", "10.7.6")),
lock(npm("ip-address@npm:^10.0.0", "10.1.0")),
["ip-address"],
),
"range renamed and the line held": (
lock(npm("ip-address@npm:^10.1.0", "10.7.6")),
lock(npm("ip-address@npm:^10.0.0", "10.7.6")),
[],
),
"moved to a higher major": (
lock(npm("ip-address@npm:^9.0.0", "9.0.5")),
lock(npm("ip-address@npm:^10.0.0", "10.7.6")),
[],
),
"one of two lines fell": (
lock(
npm("tar@npm:^6.0.0", "6.2.1"),
npm("tar@npm:^7.0.0", "7.5.22"),
),
lock(
npm("tar@npm:^6.0.0", "6.2.1"),
npm("tar@npm:^7.0.0", "7.5.1"),
),
["tar"],
),
"prerelease below its release": (
lock(npm("resolve@npm:^2.0.0-next.5", "2.0.0-next.7")),
lock(npm("resolve@npm:^2.0.0-next.5", "2.0.0-next.5")),
["resolve"],
),
}
for label, (base, head, expected) in cases.items():
with self.subTest(label):
self.assertEqual(sorted(fell(base, head)), expected)

def test_evidence_names_the_descriptor(self) -> None:
found = fell(
lock(npm("axios@npm:^1.13.5", "1.20.0")),
lock(npm("axios@npm:^1.13.5", "1.18.1")),
)
self.assertEqual(
found, {"axios": ["axios@npm:^1.13.5 1.20.0 at base, now 1.18.1"]}
)


class CommandLineTest(unittest.TestCase):
def setUp(self) -> None:
self.dir = Path(tempfile.mkdtemp(prefix="lockfile-floor-"))
self.addCleanup(shutil.rmtree, self.dir, ignore_errors=True)
(self.dir / "scripts").mkdir()
(self.dir / "security").mkdir()
shutil.copy(SOURCE, self.dir / "scripts" / SOURCE.name)
self.git("init", "-q", "-b", "main")
self.git("config", "user.email", "test@dfe.hyperi.io")
self.git("config", "user.name", "test")
self.write_lock(npm("tar@npm:^7.0.0", "7.5.22"))
self.git("add", "-A")
self.git("commit", "-qm", "base")
self.git("update-ref", "refs/remotes/origin/main", "HEAD")

def git(self, *args: str) -> None:
subprocess.run(
["git", *args], cwd=self.dir, check=True, capture_output=True, text=True
)

def write_lock(self, *entries: Entry) -> None:
(self.dir / "yarn.lock").write_text(lock(*entries), encoding="utf-8")

def run_tool(self, *args: str) -> subprocess.CompletedProcess:
return subprocess.run(
[sys.executable, str(self.dir / "scripts" / SOURCE.name), *args],
cwd=self.dir,
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
check=False,
)

def test_unchanged_lockfile_passes(self) -> None:
result = self.run_tool()
self.assertEqual(result.returncode, 0, result.stderr)

def test_regression_fails_and_names_the_package(self) -> None:
self.write_lock(npm("tar@npm:^7.0.0", "6.2.1"))
result = self.run_tool()
self.assertEqual(result.returncode, 1)
self.assertIn("tar@npm:^7.0.0 7.5.22 at base, now 6.2.1", result.stdout)

def test_names_lists_one_package_per_line(self) -> None:
self.write_lock(npm("tar@npm:^7.0.0", "6.2.1"))
result = self.run_tool("--names")
self.assertEqual(result.returncode, 0)
self.assertEqual(result.stdout.split(), ["tar"])

def test_branch_cut_before_main_moved_is_not_held_to_main(self) -> None:
self.write_lock(npm("tar@npm:^7.0.0", "7.9.0"))
self.git("commit", "-qam", "main moves on")
self.git("update-ref", "refs/remotes/origin/main", "HEAD")
self.git("checkout", "-q", "-b", "older", "HEAD~1")
result = self.run_tool()
self.assertEqual(result.returncode, 0, result.stdout)

def test_allowed_downgrade_passes_and_needs_a_reason(self) -> None:
self.write_lock(npm("tar@npm:^7.0.0", "6.2.1"))
allow = self.dir / "security" / "lockfile-floor-allow.txt"
allow.write_text("tar upstream dropped 7.x on purpose\n", encoding="utf-8")
self.assertEqual(self.run_tool().returncode, 0)
allow.write_text("tar\n", encoding="utf-8")
result = self.run_tool()
self.assertNotEqual(result.returncode, 0)
self.assertIn("has no reason", result.stderr)

def test_unknown_base_is_an_error(self) -> None:
result = self.run_tool("--base", "no-such-ref")
self.assertEqual(result.returncode, 2)


if __name__ == "__main__":
unittest.main()
Loading
Loading