[metadata] Implement encoder for purls (part 1)

docs/metadata/README.md

@@ -46,11 +46,12 @@ If you are a module author and want to annotate your module, you will need to ta
     > Modules typically need only a single `package_metadata` target. However, multiple targets can be required in some cases (e.g., when some targets are licensed under a different license).
 
     ```starlark
+    load("@package_metadata//purl:purl.bzl", "purl")
     load("@package_metadata//rules:package_metadata.bzl", "package_metadata")
 
     package_metadata(
         name = "package_metadata",
-        purl = "pkg:bazel/{}@{}".format(module_name(), module_version()),
+        purl = purl.bazel(module_name(), module_version()),
         attributes = [
             # ...
         ],
@@ -128,6 +129,10 @@ If you are a module author and want to annotate your module, you will need to ta
 
   - [@package_metadata//rules:package_metadata.bzl](./rules/package_metadata.md)
 
+#### Utils
+
+  - [@package_metadata//purl:purl.bzl](./purl/purl.md)
+
 
 ### Licenses
 

docs/metadata/defs.md

@@ -70,3 +70,50 @@ package_metadata(*, <a href="#package_metadata-name">name</a>, <a href="#package
 | <a id="package_metadata-visibility"></a>visibility |  <p align="center"> - </p>   |  `None` |
 
 
+<a id="purl.bazel"></a>
+
+## purl.bazel
+
+<pre>
+load("@package_metadata//:defs.bzl", "purl")
+
+purl.bazel(<a href="#purl.bazel-name">name</a>, <a href="#purl.bazel-version">version</a>)
+</pre>
+
+Defines a `purl` for a Bazel module.
+
+This is typically used to construct `purl` for `package_metadata` targets in
+Bazel modules.
+
+This is **NOT** supported in `WORKSPACE` mode.
+
+Example:
+
+```starlark
+load("@package_metadata//purl:purl.bzl", "purl")
+
+package_metadata(
+    name = "package_metadata",
+    purl = purl.bazel(module_name(), module_version()),
+    attributes = [
+        # ...
+    ],
+    visibility = ["//visibility:public"],
+)
+```
+
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="purl.bazel-name"></a>name |  The name of the Bazel module. Typically [module_name()](https://bazel.build/rules/lib/globals/build#module_name).   |  none |
+| <a id="purl.bazel-version"></a>version |  The version of the Bazel module. Typically [module_version()](https://bazel.build/rules/lib/globals/build#module_version). May be empty or `None`.   |  none |
+
+**RETURNS**
+
+The `purl` for the Bazel module (e.g. `pkg:bazel/foo` or
+  `pkg:bazel/[email protected]`).
+
+

docs/metadata/purl/BUILD

@@ -0,0 +1,17 @@
+load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
+load("@stardoc//stardoc:stardoc.bzl", "stardoc")
+
+stardoc(
+    name = "purl",
+    out = "purl.generated.md",
+    input = "@package_metadata//purl:purl.bzl",
+    deps = [
+        "@package_metadata//purl:srcs",
+    ],
+)
+
+diff_test(
+    name = "purl_test",
+    file1 = ":purl",
+    file2 = "purl.md",
+)

docs/metadata/purl/purl.md

@@ -0,0 +1,51 @@
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+Module defining urils for [purl](https://github.com/package-url/purl-spec)s.
+
+<a id="purl.bazel"></a>
+
+## purl.bazel
+
+<pre>
+load("@package_metadata//purl:purl.bzl", "purl")
+
+purl.bazel(<a href="#purl.bazel-name">name</a>, <a href="#purl.bazel-version">version</a>)
+</pre>
+
+Defines a `purl` for a Bazel module.
+
+This is typically used to construct `purl` for `package_metadata` targets in
+Bazel modules.
+
+This is **NOT** supported in `WORKSPACE` mode.
+
+Example:
+
+```starlark
+load("@package_metadata//purl:purl.bzl", "purl")
+
+package_metadata(
+    name = "package_metadata",
+    purl = purl.bazel(module_name(), module_version()),
+    attributes = [
+        # ...
+    ],
+    visibility = ["//visibility:public"],
+)
+```
+
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="purl.bazel-name"></a>name |  The name of the Bazel module. Typically [module_name()](https://bazel.build/rules/lib/globals/build#module_name).   |  none |
+| <a id="purl.bazel-version"></a>version |  The version of the Bazel module. Typically [module_version()](https://bazel.build/rules/lib/globals/build#module_version). May be empty or `None`.   |  none |
+
+**RETURNS**
+
+The `purl` for the Bazel module (e.g. `pkg:bazel/foo` or
+  `pkg:bazel/[email protected]`).
+
+

maintainers/tools/purl_tables/main.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+
+"""Tool for updating the tables for PURL."""
+
+import argparse
+import json
+import os
+import sys
+
+from typing import List
+from urllib.parse import quote
+
+
+def _percent_encode(s: str) -> str:
+    """
+    Percent-encodes a character according to the [PURL specification](https://github.com/package-url/purl-spec/blob/main/PURL-SPECIFICATION.rst#character-encoding).
+    """
+
+    try:
+        return quote(s, encoding=None).replace("%3A", ":")
+    except:
+        return None
+
+
+def _run(args) -> int:
+    lc_all = os.environ.get("LC_ALL")
+    if lc_all != "en_US.UTF-8":
+        print("Your environment settings will reorder the file badly.")
+        print("Please rerun as:")
+        print('  LC_ALL="en_US.UTF-8"', " ".join(sys.argv))
+        return 0
+
+    percent_encoding_tests = [
+        "foo",
+        "Hello, World!",
+        "path: /foo",
+        # German
+        "München",
+        "Köln",
+        # Swedish
+        "Småland",
+        # French
+        "française",
+        # Spanish
+        "¡Hola Mundo!",
+        # Arabic
+        "مرحبا بالعالم!",
+        # Chinese
+        "你好世界！",
+        # Japanese
+        "こんにちは世界！",
+        # Emoji,
+        "🙎",
+        "🙊",
+        # Emoji with modifiers.
+        str(
+            b"\xf0\x9f\x99\x8e\xf0\x9f\x8f\xbe\xe2\x80\x8d\xe2\x99\x80\xef\xb8\x8f",
+            "utf8",
+        ),
+    ]
+
+    tables = {
+        "percent_encoding": {
+            "encode": {str(i): _percent_encode(bytes([i])) for i in range(0, 256, 1)},
+            "tests": {s: _percent_encode(s) for s in percent_encoding_tests},
+        },
+    }
+
+    with open(args.output, "w") as f:
+        # Json-encode twice to get a valid Starlark string for the JSON object.
+        f.write(
+            f"""
+# Generated by maintainers/tools/purl_tables/main.py. DO NOT EDIT.
+
+visibility([
+    "//purl/...",
+])
+
+tables = json.decode({json.dumps(json.dumps(tables))})
+""".strip()
+        )
+        f.write("\n")
+
+    return 0
+
+
+def main(argv: List[str]) -> int:
+    """Main program.
+    Args:
+      argv: command-line arguments, such as sys.argv (including the program name
+      in argv[0]).
+    Returns:
+      Zero on successful program termination, non-zero otherwise.
+    """
+
+    parser = argparse.ArgumentParser(description="Update tables for PURL.")
+    parser.add_argument("--output", required=True, help="The .bzl file to write to.")
+
+    return _run(parser.parse_args(argv[1:]))
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

metadata/BUILD

@@ -1,4 +1,5 @@
 load("//licenses/rules:license.bzl", "license")
+load("//purl:purl.bzl", "purl")
 load("//rules:package_metadata.bzl", "package_metadata")
 
 exports_files(
@@ -14,6 +15,7 @@ filegroup(
         "defs.bzl",
     ] + [
         "//providers:srcs",
+        "//purl:srcs",
         "//rules:srcs",
     ],
     visibility = ["//visibility:public"],
@@ -24,7 +26,7 @@ package_metadata(
     attributes = [
         ":license",
     ],
-    purl = "pkg:bazel/{}@{}".format(
+    purl = purl.bazel(
         module_name(),
         module_version(),
     ),

metadata/MODULE.bazel

@@ -1,6 +1,6 @@
 module(
     name = "package_metadata",
-    version = "HEAD",  # Automatically updated by release pipeline.
+    version = "",  # Automatically updated by release pipeline.
 )
 
 # This is a fundamental module that's depended on by virtually every bazel

metadata/defs.bzl

@@ -2,6 +2,7 @@
 
 load("//providers:package_attribute_info.bzl", _PackageAttributeInfo = "PackageAttributeInfo")
 load("//providers:package_metadata_info.bzl", _PackageMetadataInfo = "PackageMetadataInfo")
+load("//purl:purl.bzl", _purl = "purl")
 load("//rules:package_metadata.bzl", _package_metadata = "package_metadata")
 
 visibility("public")
@@ -12,3 +13,6 @@ PackageMetadataInfo = _PackageMetadataInfo
 
 # Rules
 package_metadata = _package_metadata
+
+# Utils
+purl = _purl

metadata/purl/BUILD

@@ -0,0 +1,22 @@
+load("//purl:percent_encoding_test.bzl", "percent_encoding_test")
+load("//purl:tables.bzl", "percent_encoding")
+
+exports_files(
+    [
+        "purl.bzl",
+    ],
+    visibility = ["//visibility:public"],
+)
+
+filegroup(
+    name = "srcs",
+    srcs = [
+        "purl.bzl",
+    ],
+    visibility = ["//visibility:public"],
+)
+
+percent_encoding_test(
+    name = "percent_encoding_test",
+    cases = percent_encoding.tests,
+)

metadata/purl/percent_encoding.bzl

@@ -0,0 +1,37 @@
+"""Utils for [purl](https://github.com/package-url/purl-spec)'s `percent encoding`.
+
+Spec: https://github.com/package-url/purl-spec/blob/main/PURL-SPECIFICATION.rst#character-encoding
+"""
+
+load("//purl:string.bzl", "string")
+load("//purl:tables.bzl", "percent_encoding")
+
+visibility([
+    "//purl/...",
+])
+
+def _encode_byte(b):
+    """Encodes a single byte.
+
+    Args:
+      c: The byte to encode.
+    Returns:
+      The encoded string.
+    """
+
+    encoded = percent_encoding.encode.get(b, None)
+    if not encoded:
+        fail("Cannot encode {} (type={})".format(b, type(b)))
+
+    return encoded
+
+def percent_encode(value):
+    """Encodes the provided string.
+
+    Args:
+      value (string): The string to encode.
+    Returns:
+      The encoded string.
+    """
+
+    return "".join([_encode_byte(b) for b in string.to_bytes(value)])