Visitar URL original
feat(ecosystems): add Homebrew ecosystem and pkg:brew purl mapping · andrew/osv.dev@95e3714 · GitHub
Skip to content

Commit 95e3714

Browse files
committed
feat(ecosystems): add Homebrew ecosystem and pkg:brew purl mapping
Add Homebrew as an OrderedEcosystem with a version comparator that ports Homebrew's PkgVersion/Version#<=> (tokenised two-pointer walk with alpha/beta/pre/rc below the release, string/patch/post above, numeric zero equal to a missing token, then _N revision as a numeric tie-breaker) and a coarse_version over the leading numeric prefix. Map the ecosystem to the pkg:brew purl type (no namespace) and add formulae.brew.sh as the package_urls entry. Comparison test cases are lifted from Homebrew's own version_spec.rb; a hypothesis strategy covers coarse-version monotonicity. Refs google#5659 Signed-off-by: Andrew Nesbitt <andrewnez@gmail.com>
1 parent 1986f5b commit 95e3714

6 files changed

Lines changed: 359 additions & 0 deletions

File tree

‎osv/ecosystems/_ecosystems.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@
2323
from .echo import Echo
2424
from .haskell import Hackage, GHC
2525
from .hex import Hex
26+
from .homebrew import Homebrew
2627
from .maven import Maven
2728
from .nuget import NuGet
2829
from .opam import Opam
@@ -57,6 +58,7 @@
5758
'Go': SemverEcosystem,
5859
'Hackage': Hackage,
5960
'Hex': Hex,
61+
'Homebrew': Homebrew,
6062
'Julia': SemverEcosystem,
6163
'Mageia': RPM,
6264
'Maven': Maven,
@@ -118,6 +120,7 @@ def is_known(ecosystem: str) -> bool:
118120
'Go': 'https://',
119121
'Hackage': 'https://hackage.haskell.org/package/',
120122
'Hex': 'https://hex.pm/packages/',
123+
'Homebrew': 'https://formulae.brew.sh/formula/',
121124
'Mageia': 'https://madb.mageia.org/show?rpm=',
122125
'npm': 'https://www.npmjs.com/package/',
123126
'NuGet': 'https://www.nuget.org/packages/',

‎osv/ecosystems/coarse_version_monotonicity_test.py‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@
2525
from . import cran
2626
from . import debian
2727
from . import haskell
28+
from . import homebrew
2829
from . import maven
2930
from . import nuget
3031
from . import packagist
@@ -59,6 +60,14 @@
5960
# Matches Haskell versions: dot-separated integers (e.g. 1.2.3).
6061
hackage_version_strategy = st.from_regex(r'^[0-9]+(\.[0-9]+)*$')
6162

63+
# Matches Homebrew PkgVersions: dot/dash-separated numerics with an optional
64+
# prerelease (alpha/beta/pre/rc) or patch (p/post) marker or trailing letter,
65+
# and an optional `_N` revision suffix.
66+
homebrew_version_strategy = st.from_regex(
67+
r'^[0-9]+([.-][0-9]+)*'
68+
r'(alpha[0-9]*|beta[0-9]*|pre[0-9]*|rc[0-9]*|-p[0-9]+|\.post[0-9]+|[a-z])?'
69+
r'(_[0-9]+)?$')
70+
6271
# Matches Maven versions: flexible sequence of numbers or identifiers
6372
# separated by dots or dashes.
6473
maven_version_strategy = st.from_regex(r'^(([0-9]*|[A-Za-z+]*)[.-]?)*$')
@@ -134,6 +143,12 @@ def test_dpkg(self, v1_str, v2_str):
134143
def test_hackage(self, v1_str, v2_str):
135144
check_coarse_version_monotonic(self, haskell.Hackage(), v1_str, v2_str)
136145

146+
@given(homebrew_version_strategy, homebrew_version_strategy)
147+
@example('2.1.0-p194', '2.1-p195')
148+
@example('1.81.6_5', '1.81.6_6')
149+
def test_homebrew(self, v1_str, v2_str):
150+
check_coarse_version_monotonic(self, homebrew.Homebrew(), v1_str, v2_str)
151+
137152
@given(maven_version_strategy, maven_version_strategy)
138153
def test_maven(self, v1_str, v2_str):
139154
check_coarse_version_monotonic(self, maven.Maven(), v1_str, v2_str)

‎osv/ecosystems/homebrew.py‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# Copyright 2026 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
"""Homebrew ecosystem helper.
15+
16+
Version comparison ports Homebrew's `PkgVersion` and `Version#<=>`
17+
(https://github.com/Homebrew/brew/blob/HEAD/Library/Homebrew/version.rb,
18+
https://github.com/Homebrew/brew/blob/HEAD/Library/Homebrew/pkg_version.rb):
19+
tokenise into numeric / prerelease-marker / patch-marker / string parts and
20+
compare with a two-pointer walk that treats a numeric zero as equal to a
21+
missing token, then break ties on the numeric `_N` revision suffix.
22+
"""
23+
24+
import functools
25+
import re
26+
27+
from .ecosystems_base import OrderedEcosystem, coarse_version_generic
28+
29+
# Token kinds. Negative kinds are prerelease markers (sort below a missing
30+
# token); NUMERIC 0 is equal to a missing token; STRING/PATCH/POST sort above.
31+
_ALPHA, _BETA, _PRE, _RC = -4, -3, -2, -1
32+
_NULL = 0
33+
_STRING, _PATCH, _POST, _NUMERIC = 1, 2, 3, 4
34+
35+
# Matches Homebrew's Version::SCAN_PATTERN. Order matters: prerelease/post
36+
# markers must be tried before the generic numeric/string fallbacks.
37+
_TOKEN_PATTERNS = (
38+
(_ALPHA, r'alpha[0-9]*|a[0-9]+'),
39+
(_BETA, r'beta[0-9]*|b[0-9]+'),
40+
(_PRE, r'pre[0-9]*'),
41+
(_RC, r'rc[0-9]*'),
42+
(_PATCH, r'p[0-9]*'),
43+
(_POST, r'.post[0-9]+'),
44+
(_NUMERIC, r'[0-9]+'),
45+
(_STRING, r'[a-z]+'),
46+
)
47+
_SCAN_RE = re.compile('|'.join(f'({p})' for _, p in _TOKEN_PATTERNS), re.I)
48+
_PKG_VERSION_RE = re.compile(r'\A(.+?)(?:_(\d+))?\Z')
49+
50+
_NULL_TOKEN = (_NULL, 0)
51+
52+
53+
def _classify(match: re.Match) -> tuple[int, int | str]:
54+
"""Return (kind, value) for a token regex match."""
55+
for i, (kind, _) in enumerate(_TOKEN_PATTERNS, start=1):
56+
text = match.group(i)
57+
if text is None:
58+
continue
59+
if kind == _NUMERIC:
60+
return (_NUMERIC, int(text))
61+
if kind == _STRING:
62+
return (_STRING, text.lower())
63+
# Composite tokens (alpha/beta/pre/rc/patch/post): compare by the
64+
# trailing numeric part within the same kind.
65+
m = re.search(r'[0-9]+', text)
66+
return (kind, int(m.group(0)) if m else 0)
67+
raise ValueError('unreachable')
68+
69+
70+
def _tokenise(version: str) -> list[tuple[int, int | str]]:
71+
return [_classify(m) for m in _SCAN_RE.finditer(version)]
72+
73+
74+
def _cmp_token(a: tuple[int, int | str], b: tuple[int, int | str]) -> int:
75+
"""Port of Homebrew's per-token `<=>` for the same-shape (both numeric,
76+
both non-numeric, or one side null) case."""
77+
ak, av = a
78+
bk, bv = b
79+
if ak == _NULL:
80+
if bk == _NULL:
81+
return 0
82+
if bk == _NUMERIC:
83+
return 0 if bv == 0 else -1
84+
# Prerelease markers sort below release; string/patch/post above.
85+
return 1 if bk < 0 else -1
86+
if bk == _NULL:
87+
return -_cmp_token(b, a) # pylint: disable=arguments-out-of-order
88+
if ak == bk:
89+
return (av > bv) - (av < bv)
90+
# Cross-kind for non-numeric composites falls through to string comparison
91+
# in Homebrew (e.g. PatchToken vs PostToken); use kind rank as a total order
92+
# over the marker kinds, which matches every case Homebrew's spec covers.
93+
return (ak > bk) - (ak < bk)
94+
95+
96+
def _cmp_version(lt: list, rt: list) -> int:
97+
"""Port of Homebrew's two-pointer `Version#<=>` walk.
98+
99+
When one side is numeric and the other is not, a positive numeric wins
100+
outright; a numeric zero is skipped so `2.1.0-p194` and `2.1-p194` align.
101+
"""
102+
n = max(len(lt), len(rt))
103+
li = ri = 0
104+
while li < n:
105+
a = lt[li] if li < len(lt) else _NULL_TOKEN
106+
b = rt[ri] if ri < len(rt) else _NULL_TOKEN
107+
if a == b:
108+
li += 1
109+
ri += 1
110+
continue
111+
a_num = a[0] == _NUMERIC
112+
b_num = b[0] == _NUMERIC
113+
if a_num and not b_num:
114+
if _cmp_token(a, _NULL_TOKEN) > 0:
115+
return 1
116+
li += 1
117+
elif b_num and not a_num:
118+
if _cmp_token(b, _NULL_TOKEN) > 0:
119+
return -1
120+
ri += 1
121+
else:
122+
return _cmp_token(a, b)
123+
return 0
124+
125+
126+
@functools.total_ordering
127+
class HomebrewPkgVersion:
128+
"""Comparable Homebrew `PkgVersion` (upstream version + `_N` revision)."""
129+
130+
__slots__ = ('_raw', '_tokens', '_revision')
131+
132+
def __init__(self, version: str):
133+
m = _PKG_VERSION_RE.match(version)
134+
if not m or not m.group(1):
135+
raise ValueError(f'Invalid version: {version!r}')
136+
self._raw = version
137+
self._tokens = _tokenise(m.group(1))
138+
self._revision = int(m.group(2)) if m.group(2) else 0
139+
140+
def __repr__(self) -> str:
141+
return f'HomebrewPkgVersion({self._raw!r})'
142+
143+
def __eq__(self, other) -> bool:
144+
if not isinstance(other, HomebrewPkgVersion):
145+
return NotImplemented
146+
return (_cmp_version(self._tokens, other._tokens) == 0 and
147+
self._revision == other._revision)
148+
149+
def __lt__(self, other) -> bool:
150+
if not isinstance(other, HomebrewPkgVersion):
151+
return NotImplemented
152+
c = _cmp_version(self._tokens, other._tokens)
153+
if c != 0:
154+
return c < 0
155+
return self._revision < other._revision
156+
157+
158+
class Homebrew(OrderedEcosystem):
159+
"""Homebrew ecosystem helper."""
160+
161+
def _sort_key(self, version):
162+
return HomebrewPkgVersion(version)
163+
164+
def coarse_version(self, version: str) -> str:
165+
"""Coarse version.
166+
167+
Strips any `_N` revision suffix, then treats the version segment as
168+
dot-separated with implicit digit/non-digit splits, truncating at the
169+
first non-numeric token so prerelease/patch markers do not violate
170+
monotonicity (e.g. `1.2.3rc1 < 1.2.3` while both coarse to
171+
`00:00000001.00000002.00000003`).
172+
"""
173+
self._sort_key(version)
174+
m = _PKG_VERSION_RE.match(version)
175+
return coarse_version_generic(
176+
m.group(1),
177+
separators_regex=r'[._\-+~]',
178+
truncate_regex=None,
179+
implicit_split=True,
180+
)

‎osv/ecosystems/homebrew_test.py‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# Copyright 2026 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
"""Homebrew ecosystem helper tests.
15+
16+
Comparison cases are taken from
17+
https://github.com/Homebrew/brew/blob/HEAD/Library/Homebrew/test/version_spec.rb
18+
plus PkgVersion `_N` revision-suffix cases.
19+
"""
20+
21+
import unittest
22+
23+
from .. import ecosystems
24+
from .homebrew import HomebrewPkgVersion
25+
26+
27+
class HomebrewVersionCompareTest(unittest.TestCase):
28+
"""Homebrew Version#<=> parity tests."""
29+
30+
# (a, op, b) where op is '<', '>' or '=='.
31+
_cases = [
32+
# basic ordering
33+
('0.1', '<', '0.2'),
34+
('1.2.3', '>', '1.2.2'),
35+
('1.2.4', '<', '1.2.4.1'),
36+
# prerelease markers sort below the release
37+
('1.2.3', '>', '1.2.3alpha4'),
38+
('1.2.3', '>', '1.2.3beta2'),
39+
('1.2.3', '>', '1.2.3rc3'),
40+
('1.2.3alpha', '<', '1.2.3'),
41+
# bare trailing letter is a StringToken, sorts above the release
42+
('1.2.3', '<', '1.2.3a'),
43+
# patch marker sorts above the release
44+
('1.2.3', '<', '1.2.3-p34'),
45+
('1.2.3-p34', '>', '1.2.3'),
46+
('1.2.3-p34', '==', '1.2.3-P34'),
47+
('1.2.3-p34', '>', '1.2.3-p33'),
48+
('1.2.3-p34', '<', '1.2.3-p35'),
49+
('1.2.3-p34', '>', '1.2.3-p9'),
50+
# alpha
51+
('1.2.3alpha4', '>', '1.2.3alpha3'),
52+
('1.2.3alpha4', '<', '1.2.3alpha5'),
53+
('1.2.3alpha4', '<', '1.2.3alpha10'),
54+
('1.2.3alpha4', '<', '1.2.3beta2'),
55+
('1.2.3alpha4', '<', '1.2.3rc3'),
56+
('1.2.3alpha4', '<', '1.2.3-p34'),
57+
# beta
58+
('1.2.3beta2', '>', '1.2.3beta1'),
59+
('1.2.3beta2', '<', '1.2.3beta10'),
60+
('1.2.3beta2', '>', '1.2.3alpha4'),
61+
('1.2.3beta2', '<', '1.2.3rc3'),
62+
('1.2.3beta2', '<', '1.2.3-p34'),
63+
# pre
64+
('1.2.3pre9', '>', '1.2.3pre8'),
65+
('1.2.3pre9', '<', '1.2.3pre10'),
66+
('1.2.3pre3', '>', '1.2.3alpha4'),
67+
('1.2.3pre3', '>', '1.2.3beta5'),
68+
('1.2.3pre3', '<', '1.2.3rc2'),
69+
('1.2.3pre3', '<', '1.2.3'),
70+
('1.2.3pre3', '<', '1.2.3-p2'),
71+
# rc
72+
('1.2.3rc3', '>', '1.2.3rc2'),
73+
('1.2.3rc3', '<', '1.2.3rc10'),
74+
('1.2.3rc3', '>', '1.2.3beta2'),
75+
('1.2.3rc3', '<', '1.2.3-p34'),
76+
# post
77+
('1.2.3.post34', '>', '1.2.3.post33'),
78+
('1.2.3.post34', '<', '1.2.3.post35'),
79+
('1.2.3.post34', '>', '1.2.3rc35'),
80+
('1.2.3.post34', '>', '1.2.3alpha35'),
81+
('1.2.3.post34', '>', '1.2.3'),
82+
# zero-skip: unevenly-padded versions align
83+
('2.1.0-p194', '<', '2.1-p195'),
84+
('2.1-p195', '>', '2.1.0-p194'),
85+
('2.1-p194', '<', '2.1.0-p195'),
86+
('2.1.0-p195', '>', '2.1-p194'),
87+
('2-p194', '<', '2.1-p195'),
88+
# PkgVersion revision suffix
89+
('1.81.6_5', '<', '1.81.6_6'),
90+
('1.81.6_6', '<', '1.82.0'),
91+
('1.81.6', '<', '1.81.6_1'),
92+
('1.81.6_0', '==', '1.81.6'),
93+
('6.0_8', '>', '6.0_6'),
94+
('0.12.20_1', '>', '0.12.20'),
95+
]
96+
97+
def test_ordering(self):
98+
"""Compare each pair and its reverse."""
99+
for a, op, b in self._cases:
100+
with self.subTest(f'{a} {op} {b}'):
101+
va, vb = HomebrewPkgVersion(a), HomebrewPkgVersion(b)
102+
if op == '<':
103+
self.assertLess(va, vb)
104+
self.assertGreater(vb, va)
105+
elif op == '>':
106+
self.assertGreater(va, vb)
107+
self.assertLess(vb, va)
108+
else:
109+
self.assertEqual(va, vb)
110+
self.assertEqual(vb, va)
111+
112+
113+
class HomebrewEcosystemTest(unittest.TestCase):
114+
"""Homebrew OrderedEcosystem tests."""
115+
116+
def setUp(self):
117+
self.ecosystem = ecosystems.get('Homebrew')
118+
119+
def test_registered(self):
120+
self.assertIsNotNone(self.ecosystem)
121+
122+
def test_sort_key(self):
123+
self.assertLess(
124+
self.ecosystem.sort_key('1.81.6_5'),
125+
self.ecosystem.sort_key('1.81.6_6'))
126+
self.assertLess(
127+
self.ecosystem.sort_key('0'), self.ecosystem.sort_key('0.12.20_1'))
128+
self.assertTrue(self.ecosystem.sort_key('').is_invalid)
129+
130+
def test_sort_versions(self):
131+
versions = ['1.82.0', '1.81.6_6', '1.81.6', '1.81.6_5', '1.81.6rc1']
132+
self.ecosystem.sort_versions(versions)
133+
self.assertEqual(versions,
134+
['1.81.6rc1', '1.81.6', '1.81.6_5', '1.81.6_6', '1.82.0'])
135+
136+
def test_coarse_version(self):
137+
"""Test coarse_version output and local monotonicity."""
138+
self.assertEqual(
139+
self.ecosystem.coarse_version('1.81.6_6'),
140+
'00:00000001.00000081.00000006')
141+
self.assertEqual(
142+
self.ecosystem.coarse_version('6.0_8'), '00:00000006.00000000.00000000')
143+
# Prerelease/patch markers truncate; must not exceed the release's coarse.
144+
self.assertLessEqual(
145+
self.ecosystem.coarse_version('1.2.3rc1'),
146+
self.ecosystem.coarse_version('1.2.3'))
147+
self.assertLessEqual(
148+
self.ecosystem.coarse_version('1.2.3'),
149+
self.ecosystem.coarse_version('1.2.3-p34'))
150+
151+
152+
if __name__ == '__main__':
153+
unittest.main()

0 commit comments

Comments
 (0)