Add new PURL type: 'brew' for Homebrew

purl-types-index.json

@@ -4,6 +4,7 @@
   "bazel",
   "bitbucket",
   "bitnami",
+  "brew",
   "cargo",
   "cocoapods",
   "composer",

tests/types/brew-test.json

@@ -0,0 +1,248 @@
+{
+  "$schema": "https://packageurl.org/schemas/purl-test.schema-0.1.json",
+  "tests": [
+    {
+      "description": "Simple Homebrew formula with version",
+      "test_group": "base",
+      "test_type": "parse",
+      "input": "pkg:brew/sqlite@3.43.2",
+      "expected_output": {
+        "type": "brew",
+        "namespace": null,
+        "name": "sqlite",
+        "version": "3.43.2",
+        "qualifiers": null,
+        "subpath": null
+      },
+      "expected_failure": false,
+      "expected_failure_reason": null
+    },
+    {
+      "description": "Simple Homebrew formula with version - roundtrip",
+      "test_group": "base",
+      "test_type": "roundtrip",
+      "input": "pkg:brew/sqlite@3.43.2",
+      "expected_output": "pkg:brew/sqlite@3.43.2",
+      "expected_failure": false,
+      "expected_failure_reason": null
+    },
+    {
+      "description": "Simple Homebrew formula with version - build",
+      "test_group": "base",
+      "test_type": "build",
+      "input": {
+        "type": "brew",
+        "namespace": null,
+        "name": "sqlite",
+        "version": "3.43.2",
+        "qualifiers": null,
+        "subpath": null
+      },
+      "expected_output": "pkg:brew/sqlite@3.43.2",
+      "expected_failure": false,
+      "expected_failure_reason": null
+    },
+    {
+      "description": "Homebrew formula without version (versionless purl)",
+      "test_group": "base",
+      "test_type": "parse",
+      "input": "pkg:brew/go",
+      "expected_output": {
+        "type": "brew",
+        "namespace": null,
+        "name": "go",
+        "version": null,
+        "qualifiers": null,
+        "subpath": null
+      },
+      "expected_failure": false,
+      "expected_failure_reason": null
+    },
+    {
+      "description": "Homebrew formula without version - roundtrip",
+      "test_group": "base",
+      "test_type": "roundtrip",
+      "input": "pkg:brew/go",
+      "expected_output": "pkg:brew/go",
+      "expected_failure": false,
+      "expected_failure_reason": null
+    },
+    {
+      "description": "Homebrew formula without version - build",
+      "test_group": "base",
+      "test_type": "build",
+      "input": {
+        "type": "brew",
+        "namespace": null,
+        "name": "go",
+        "version": null,
+        "qualifiers": null,
+        "subpath": null
+      },
+      "expected_output": "pkg:brew/go",
+      "expected_failure": false,
+      "expected_failure_reason": null
+    },
+    {
+      "description": "Versioned formula with @ in name (postgresql@12) - @ must be percent-encoded",
+      "test_group": "base",
+      "test_type": "parse",
+      "input": "pkg:brew/postgresql%4012@12.17",
+      "expected_output": {
+        "type": "brew",
+        "namespace": null,
+        "name": "postgresql@12",
+        "version": "12.17",
+        "qualifiers": null,
+        "subpath": null
+      },
+      "expected_failure": false,
+      "expected_failure_reason": null
+    },
+    {
+      "description": "Versioned formula with @ in name - roundtrip",
+      "test_group": "base",
+      "test_type": "roundtrip",
+      "input": "pkg:brew/postgresql%4012@12.17",
+      "expected_output": "pkg:brew/postgresql%4012@12.17",
+      "expected_failure": false,
+      "expected_failure_reason": null
+    },
+    {
+      "description": "Versioned formula with @ in name - build",
+      "test_group": "base",
+      "test_type": "build",
+      "input": {
+        "type": "brew",
+        "namespace": null,
+        "name": "postgresql@12",
+        "version": "12.17",
+        "qualifiers": null,
+        "subpath": null
+      },
+      "expected_output": "pkg:brew/postgresql%4012@12.17",
+      "expected_failure": false,
+      "expected_failure_reason": null
+    },
+    {
+      "description": "Homebrew formula with namespace (tap) - parse",
+      "test_group": "base",
+      "test_type": "parse",
+      "input": "pkg:brew/homebrew/core/sqlite@3.43.2",
+      "expected_output": {
+        "type": "brew",
+        "namespace": "homebrew/core",
+        "name": "sqlite",
+        "version": "3.43.2",
+        "qualifiers": null,
+        "subpath": null
+      },
+      "expected_failure": false,
+      "expected_failure_reason": null
+    },
+    {
+      "description": "Homebrew formula with namespace (tap) - roundtrip",
+      "test_group": "base",
+      "test_type": "roundtrip",
+      "input": "pkg:brew/homebrew/core/sqlite@3.43.2",
+      "expected_output": "pkg:brew/homebrew/core/sqlite@3.43.2",
+      "expected_failure": false,
+      "expected_failure_reason": null
+    },
+    {
+      "description": "Homebrew formula with namespace (tap) - build",
+      "test_group": "base",
+      "test_type": "build",
+      "input": {
+        "type": "brew",
+        "namespace": "homebrew/core",
+        "name": "sqlite",
+        "version": "3.43.2",
+        "qualifiers": null,
+        "subpath": null
+      },
+      "expected_output": "pkg:brew/homebrew/core/sqlite@3.43.2",
+      "expected_failure": false,
+      "expected_failure_reason": null
+    },
+    {
+      "description": "Homebrew formula with third-party tap and repository_url - parse",
+      "test_group": "base",
+      "test_type": "parse",
+      "input": "pkg:brew/some-org/some-tap/some-app@1.2.3?repository_url=https://github.com/some-org/homebrew-some-tap.git",
+      "expected_output": {
+        "type": "brew",
+        "namespace": "some-org/some-tap",
+        "name": "some-app",
+        "version": "1.2.3",
+        "qualifiers": {
+          "repository_url": "https://github.com/some-org/homebrew-some-tap.git"
+        },
+        "subpath": null
+      },
+      "expected_failure": false,
+      "expected_failure_reason": null
+    },
+    {
+      "description": "Homebrew formula with third-party tap and repository_url - roundtrip",
+      "test_group": "base",
+      "test_type": "roundtrip",
+      "input": "pkg:brew/some-org/some-tap/some-app@1.2.3?repository_url=https://github.com/some-org/homebrew-some-tap.git",
+      "expected_output": "pkg:brew/some-org/some-tap/some-app@1.2.3?repository_url=https:%2F%2Fgithub.com%2Fsome-org%2Fhomebrew-some-tap.git",
+      "expected_failure": false,
+      "expected_failure_reason": null
+    },
+    {
+      "description": "Homebrew formula with third-party tap and repository_url - build",
+      "test_group": "base",
+      "test_type": "build",
+      "input": {
+        "type": "brew",
+        "namespace": "some-org/some-tap",
+        "name": "some-app",
+        "version": "1.2.3",
+        "qualifiers": {
+          "repository_url": "https://github.com/some-org/homebrew-some-tap.git"
+        },
+        "subpath": null
+      },
+      "expected_output": "pkg:brew/some-org/some-tap/some-app@1.2.3?repository_url=https:%2F%2Fgithub.com%2Fsome-org%2Fhomebrew-some-tap.git",
+      "expected_failure": false,
+      "expected_failure_reason": null
+    },
+    {
+      "description": "Versioned formula with unencoded @ should parse (advanced)",
+      "test_group": "advanced",
+      "test_type": "roundtrip",
+      "input": "pkg:brew/node@20@20.10.0",
+      "expected_output": "pkg:brew/node%4020@20.10.0",
+      "expected_failure": false,
+      "expected_failure_reason": null
+    },
+    {
+      "description": "Homebrew cask example",
+      "test_group": "base",
+      "test_type": "parse",
+      "input": "pkg:brew/homebrew/cask/firefox@120.0",
+      "expected_output": {
+        "type": "brew",
+        "namespace": "homebrew/cask",
+        "name": "firefox",
+        "version": "120.0",
+        "qualifiers": null,
+        "subpath": null
+      },
+      "expected_failure": false,
+      "expected_failure_reason": null
+    },
+    {
+      "description": "Homebrew cask example - roundtrip",
+      "test_group": "base",
+      "test_type": "roundtrip",
+      "input": "pkg:brew/homebrew/cask/firefox@120.0",
+      "expected_output": "pkg:brew/homebrew/cask/firefox@120.0",
+      "expected_failure": false,
+      "expected_failure_reason": null
+    }
+  ]
+}

types-doc/brew-definition.md

@@ -0,0 +1,59 @@
+<!--  NOTE: Auto-generated from the JSON PURL type definition.
+Do not manually edit this file. Edit the JSON type definition instead. -->
+
+# PURL Type Definition: brew
+
+- **Type Name:** Homebrew
+- **Description:** Homebrew packages for macOS and Linux
+- **Schema ID:** `https://packageurl.org/types/brew-definition.json`
+
+## PURL Syntax
+
+The structure of a PURL for this package type is:
+
+    pkg:brew/<namespace>/<name>@<version>?<qualifiers>#<subpath>
+
+## Repository Information
+
+- **Use Repository:** Yes
+- **Default Repository URL:** https://formulae.brew.sh/
+- **Note:** The default repository is the Homebrew Formulae at https://formulae.brew.sh/. Homebrew also supports third-party taps (repositories) which can be specified using the namespace or repository_url qualifier.
+
+## Namespace definition
+
+- **Requirement:** Optional
+- **Native Label:** tap
+- **Note:** `The namespace is the Homebrew tap name, typically in the format 'owner/repo' (e.g., 'homebrew/core', 'some-org/some-tap'). When not specified, formulas are assumed to come from the default 'homebrew/core' tap.`
+
+## Name definition
+
+- **Requirement:** Required
+- **Case Sensitive:** Yes
+- **Native Label:** formula
+- **Note:** `The name is the Homebrew formula or cask name. Formula names containing '@' (used for versioned formulas like 'postgresql@12') must have the '@' character percent-encoded as '%40' in the PURL string.`
+
+## Version definition
+
+- **Requirement:** Optional
+- **Native Label:** version
+- **Note:** `The version is the Homebrew package version. Versions are optional to support use cases where the latest or any available version is acceptable.`
+
+## Qualifiers Definition
+
+| Key  | Requirement | Native name | Default Value | Description |
+|------|-------------|-------------|---------------|-------------|
+| repository_url | Optional |  |  | The git URL of the tap repository when using a non-default tap. For example, 'https://github.com/some-org/homebrew-some-tap.git'. |
+
+## Examples
+
+- `pkg:brew/sqlite@3.43.2`
+- `pkg:brew/go`
+- `pkg:brew/postgresql%4012@12.17`
+- `pkg:brew/homebrew/core/sqlite@3.43.2`
+- `pkg:brew/some-org/some-tap/some-app@1.2.3?repository_url=https://github.com/some-org/homebrew-some-tap.git`
+
+## Reference URLs
+
+- `https://brew.sh/`
+- `https://formulae.brew.sh/`
+- `https://docs.brew.sh/Taps`

types/brew-definition.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://packageurl.org/schemas/purl-type-definition.schema-1.0.json",
+  "$id": "https://packageurl.org/types/brew-definition.json",
+  "type": "brew",
+  "type_name": "Homebrew",
+  "description": "Homebrew packages for macOS and Linux",
+  "repository": {
+    "use_repository": true,
+    "default_repository_url": "https://formulae.brew.sh/",
+    "note": "The default repository is the Homebrew Formulae at https://formulae.brew.sh/. Homebrew also supports third-party taps (repositories) which can be specified using the namespace or repository_url qualifier."
+  },
+  "namespace_definition": {
+    "requirement": "optional",
+    "native_name": "tap",
+    "note": "The namespace is the Homebrew tap name, typically in the format 'owner/repo' (e.g., 'homebrew/core', 'some-org/some-tap'). When not specified, formulas are assumed to come from the default 'homebrew/core' tap."
+  },
+  "name_definition": {
+    "requirement": "required",
+    "native_name": "formula",
+    "case_sensitive": true,
+    "note": "The name is the Homebrew formula or cask name. Formula names containing '@' (used for versioned formulas like 'postgresql@12') must have the '@' character percent-encoded as '%40' in the PURL string."
+  },
+  "version_definition": {
+    "requirement": "optional",
+    "native_name": "version",
+    "note": "The version is the Homebrew package version. Versions are optional to support use cases where the latest or any available version is acceptable."
+  },
+  "qualifiers_definition": [
+    {
+      "key": "repository_url",
+      "description": "The git URL of the tap repository when using a non-default tap. For example, 'https://github.com/some-org/homebrew-some-tap.git'."
+    }
+  ],
+  "examples": [
+    "pkg:brew/sqlite@3.43.2",
+    "pkg:brew/go",
+    "pkg:brew/postgresql%4012@12.17",
+    "pkg:brew/homebrew/core/sqlite@3.43.2",
+    "pkg:brew/some-org/some-tap/some-app@1.2.3?repository_url=https://github.com/some-org/homebrew-some-tap.git"
+  ],
+  "reference_urls": [
+    "https://brew.sh/",
+    "https://formulae.brew.sh/",
+    "https://docs.brew.sh/Taps"
+  ]
+}