Add a BENCHMARKS.md with rendered benchmarks (#1211)

As a precursor to the release, I want to include a structured document
with detailed benchmarks.

Closes https://github.com/astral-sh/puffin/issues/1210.

scripts/bench/__main__.py

@@ -59,6 +59,9 @@ class Command(typing.NamedTuple):
 
 
 class Hyperfine(typing.NamedTuple):
+    benchmark: Benchmark
+    """The benchmark to run."""
+
     commands: list[Command]
     """The commands to benchmark."""
 
@@ -71,10 +74,18 @@ class Hyperfine(typing.NamedTuple):
     verbose: bool
     """Whether to print verbose output."""
 
+    json: bool
+    """Whether to export results to JSON."""
+
     def run(self) -> None:
         """Run the benchmark using `hyperfine`."""
         args = ["hyperfine"]
 
+        # Export to JSON.
+        if self.json:
+            args.append("--export-json")
+            args.append(f"{self.benchmark.value}.json")
+
         # Preamble: benchmark-wide setup.
         if self.verbose:
             args.append("--show-output")
@@ -716,6 +727,9 @@ def main():
     parser.add_argument(
         "--verbose", "-v", action="store_true", help="Print verbose output."
     )
+    parser.add_argument(
+        "--json", action="store_true", help="Export results to JSON."
+    )
     parser.add_argument(
         "--warmup",
         type=int,
@@ -789,6 +803,7 @@ def main():
     )
 
     verbose = args.verbose
+    json = args.json
     warmup = args.warmup
     min_runs = args.min_runs
 
@@ -858,10 +873,12 @@ def main():
 
             if commands:
                 hyperfine = Hyperfine(
+                    benchmark=benchmark,
                     commands=commands,
                     warmup=warmup,
                     min_runs=min_runs,
                     verbose=verbose,
+                    json=json,
                 )
                 hyperfine.run()