feat: Add benchmarks

benchmarks/README.md

@@ -0,0 +1,23 @@
+# Benchmarks
+
+Reproducible local benchmarks for `semble`.
+
+Pinned repositories live in `repos.json` and are checked out into `~/.cache/semble-bench`.
+
+## Setup
+
+```bash
+uv run python -m benchmarks.sync_repos
+uv run python -m benchmarks.sync_repos --check
+```
+
+## Run
+
+```bash
+uv run python -m benchmarks.run_benchmark
+uv run python -m benchmarks.run_benchmark --repo fastapi --repo axios
+uv run python -m benchmarks.run_benchmark --language python
+```
+
+Full runs (no `--repo`/`--language` filters) automatically save results to
+`benchmarks/results/<sha>.json`.

benchmarks/annotations/aiohttp.json

@@ -0,0 +1,90 @@
+[
+  {
+    "query": "how the async HTTP client session works",
+    "relevant": ["aiohttp/client.py"],
+    "secondary": []
+  },
+  {
+    "query": "connection pooling and TCP connector",
+    "relevant": ["aiohttp/connector.py"],
+    "secondary": []
+  },
+  {
+    "query": "WebSocket client implementation",
+    "relevant": ["aiohttp/client_ws.py"],
+    "secondary": ["aiohttp/_websocket/reader.py"]
+  },
+  {
+    "query": "request and response object internals",
+    "relevant": ["aiohttp/client_reqrep.py"],
+    "secondary": []
+  },
+  {
+    "query": "URL routing and resource dispatching",
+    "relevant": ["aiohttp/web_urldispatcher.py"],
+    "secondary": []
+  },
+  {
+    "query": "server-side middleware execution",
+    "relevant": ["aiohttp/web_middlewares.py"],
+    "secondary": ["aiohttp/web_app.py"]
+  },
+  {
+    "query": "multipart and form data handling",
+    "relevant": ["aiohttp/multipart.py"],
+    "secondary": ["aiohttp/formdata.py"]
+  },
+  {
+    "query": "response streaming and payload",
+    "relevant": ["aiohttp/streams.py"],
+    "secondary": ["aiohttp/payload.py"]
+  },
+  {
+    "query": "HTTP exception types and error responses",
+    "relevant": ["aiohttp/web_exceptions.py"],
+    "secondary": ["aiohttp/client_exceptions.py"]
+  },
+  {
+    "query": "request tracing and observability hooks",
+    "relevant": ["aiohttp/tracing.py"],
+    "secondary": []
+  },
+  {
+    "query": "how chunked transfer encoding is parsed",
+    "relevant": ["aiohttp/http_parser.py"],
+    "secondary": []
+  },
+  {
+    "query": "how DNS resolution is handled asynchronously",
+    "relevant": ["aiohttp/resolver.py"],
+    "secondary": ["aiohttp/connector.py"]
+  },
+  {
+    "query": "how backpressure and flow control work in streaming",
+    "relevant": ["aiohttp/streams.py"],
+    "secondary": []
+  },
+  {
+    "query": "how connection draining and cleanup happen on close",
+    "relevant": ["aiohttp/connector.py"],
+    "secondary": ["aiohttp/client_proto.py"]
+  },
+  {
+    "query": "how the web application sets up and tears down on startup",
+    "relevant": ["aiohttp/web_app.py"],
+    "secondary": ["aiohttp/web_runner.py"]
+  },
+  {"query": "ClientSession", "relevant": ["aiohttp/client.py"], "secondary": []},
+  {"query": "TCPConnector", "relevant": ["aiohttp/connector.py"], "secondary": []},
+  {"query": "UrlDispatcher", "relevant": ["aiohttp/web_urldispatcher.py"], "secondary": []},
+  {"query": "ClientResponse", "relevant": ["aiohttp/client_reqrep.py"], "secondary": []},
+  {"query": "TraceConfig", "relevant": ["aiohttp/tracing.py"], "secondary": []},
+  {
+    "query": "how ClientSession acquires and releases connections from the connector",
+    "relevant": ["aiohttp/client.py"],
+    "secondary": ["aiohttp/connector.py"],
+    "category": "architecture",
+    "seed": {"path": "aiohttp/client.py", "line": 374},
+    "related": ["aiohttp/connector.py"]
+  }
+]

benchmarks/annotations/alamofire.json

@@ -0,0 +1,99 @@
+[
+  {
+    "query": "how the Session manages the underlying URLSession and dispatches requests",
+    "relevant": ["Source/Core/Session.swift"],
+    "secondary": ["Source/Core/SessionDelegate.swift"],
+    "category": "architecture"
+  },
+  {
+    "query": "how request retrying is implemented with backoff and retry conditions",
+    "relevant": ["Source/Features/RetryPolicy.swift"],
+    "secondary": ["Source/Features/RequestInterceptor.swift"],
+    "category": "architecture"
+  },
+  {
+    "query": "how response validation checks status codes and content types",
+    "relevant": ["Source/Features/Validation.swift"],
+    "secondary": [],
+    "category": "semantic"
+  },
+  {
+    "query": "how response serialization decodes JSON, Decodable, and strings",
+    "relevant": ["Source/Features/ResponseSerialization.swift"],
+    "secondary": [],
+    "category": "semantic"
+  },
+  {
+    "query": "how multipart form data encodes fields and file attachments",
+    "relevant": ["Source/Features/MultipartFormData.swift"],
+    "secondary": ["Source/Features/MultipartUpload.swift"],
+    "category": "semantic"
+  },
+  {
+    "query": "how authentication interceptors handle credential challenges",
+    "relevant": ["Source/Features/AuthenticationInterceptor.swift"],
+    "secondary": [],
+    "category": "semantic"
+  },
+  {
+    "query": "how server trust evaluation handles SSL certificate pinning",
+    "relevant": ["Source/Features/ServerTrustEvaluation.swift"],
+    "secondary": [],
+    "category": "semantic"
+  },
+  {
+    "query": "how URL query parameters are encoded from Encodable values",
+    "relevant": ["Source/Features/URLEncodedFormEncoder.swift"],
+    "secondary": ["Source/Core/ParameterEncoder.swift"],
+    "category": "semantic"
+  },
+  {
+    "query": "how network reachability is monitored to detect connectivity changes",
+    "relevant": ["Source/Features/NetworkReachabilityManager.swift"],
+    "secondary": [],
+    "category": "semantic"
+  },
+  {
+    "query": "how download requests save responses to disk",
+    "relevant": ["Source/Core/DownloadRequest.swift"],
+    "secondary": [],
+    "category": "semantic"
+  },
+  {
+    "query": "how request and response events are logged via EventMonitor",
+    "relevant": ["Source/Features/EventMonitor.swift"],
+    "secondary": [],
+    "category": "semantic"
+  },
+  {
+    "query": "how the Request class tracks lifecycle state transitions",
+    "relevant": ["Source/Core/Request.swift"],
+    "secondary": [],
+    "category": "architecture"
+  },
+  {
+    "query": "Session",
+    "relevant": ["Source/Core/Session.swift"],
+    "secondary": []
+  },
+  {
+    "query": "AFError",
+    "relevant": ["Source/Core/AFError.swift"],
+    "secondary": []
+  },
+  {
+    "query": "RetryPolicy",
+    "relevant": ["Source/Features/RetryPolicy.swift"],
+    "secondary": []
+  },
+  {
+    "query": "ServerTrustEvaluating",
+    "relevant": ["Source/Features/ServerTrustEvaluation.swift"],
+    "secondary": []
+  },
+  {
+    "query": "HTTPHeaders",
+    "relevant": ["Source/Core/HTTPHeaders.swift"],
+    "secondary": []
+  }
+]

benchmarks/annotations/axios.json

@@ -0,0 +1,46 @@
+[
+  {
+    "query": "how HTTP requests are dispatched through the configured adapter",
+    "relevant": ["lib/core/dispatchRequest.js"],
+    "secondary": ["lib/adapters/adapters.js"],
+    "category": "architecture"
+  },
+  {
+    "query": "request and response interceptors",
+    "relevant": ["lib/core/InterceptorManager.js"],
+    "secondary": ["lib/core/Axios.js"],
+    "category": "semantic"
+  },
+  {
+    "query": "node HTTP adapter implementation",
+    "relevant": ["lib/adapters/http.js"],
+    "secondary": [],
+    "category": "semantic"
+  },
+  {
+    "query": "how config defaults are merged before a request is sent",
+    "relevant": ["lib/core/mergeConfig.js"],
+    "secondary": ["lib/core/Axios.js"],
+    "category": "architecture"
+  },
+  {
+    "query": "Axios",
+    "relevant": [{"path": "lib/core/Axios.js", "start_line": 22, "end_line": 61}],
+    "secondary": [],
+    "category": "symbol",
+    "seed": {"path": "lib/core/Axios.js", "line": 46},
+    "related": [{"path": "lib/core/Axios.js", "start_line": 179, "end_line": 239}]
+  },
+  {
+    "query": "InterceptorManager",
+    "relevant": [{"path": "lib/core/InterceptorManager.js", "start_line": 5, "end_line": 33}],
+    "secondary": [],
+    "category": "symbol"
+  },
+  {
+    "query": "mergeConfig",
+    "relevant": [{"path": "lib/core/mergeConfig.js", "start_line": 17, "end_line": 106}],
+    "secondary": [],
+    "category": "symbol"
+  }
+]

benchmarks/annotations/cats.json

@@ -0,0 +1,99 @@
+[
+  {
+    "query": "how the Functor type class defines mapping over a context",
+    "relevant": ["core/src/main/scala/cats/Functor.scala"],
+    "secondary": [],
+    "category": "architecture"
+  },
+  {
+    "query": "how Monad composes dependent effectful computations with flatMap",
+    "relevant": ["core/src/main/scala/cats/Monad.scala"],
+    "secondary": ["core/src/main/scala/cats/FlatMap.scala"],
+    "category": "architecture"
+  },
+  {
+    "query": "how Applicative combines independent effects",
+    "relevant": ["core/src/main/scala/cats/Applicative.scala"],
+    "secondary": ["core/src/main/scala/cats/Apply.scala"],
+    "category": "architecture"
+  },
+  {
+    "query": "how errors are handled and recovered in ApplicativeError and MonadError",
+    "relevant": ["core/src/main/scala/cats/ApplicativeError.scala"],
+    "secondary": ["core/src/main/scala/cats/MonadError.scala"],
+    "category": "semantic"
+  },
+  {
+    "query": "how Validated accumulates errors across independent computations",
+    "relevant": ["core/src/main/scala/cats/data/Validated.scala"],
+    "secondary": [],
+    "category": "semantic"
+  },
+  {
+    "query": "how EitherT combines the Either monad with another effect",
+    "relevant": ["core/src/main/scala/cats/data/EitherT.scala"],
+    "secondary": [],
+    "category": "semantic"
+  },
+  {
+    "query": "how Kleisli composes functions that return monadic values",
+    "relevant": ["core/src/main/scala/cats/data/Kleisli.scala"],
+    "secondary": [],
+    "category": "semantic"
+  },
+  {
+    "query": "how Eval provides lazy and memoized evaluation",
+    "relevant": ["core/src/main/scala/cats/Eval.scala"],
+    "secondary": [],
+    "category": "semantic"
+  },
+  {
+    "query": "how Foldable traverses and reduces elements in a container",
+    "relevant": ["core/src/main/scala/cats/Foldable.scala"],
+    "secondary": [],
+    "category": "semantic"
+  },
+  {
+    "query": "how Chain provides O(1) concatenation as an alternative to List",
+    "relevant": ["core/src/main/scala/cats/data/Chain.scala"],
+    "secondary": [],
+    "category": "semantic"
+  },
+  {
+    "query": "how natural transformations map between type constructors",
+    "relevant": ["core/src/main/scala/cats/arrow/FunctionK.scala"],
+    "secondary": [],
+    "category": "semantic"
+  },
+  {
+    "query": "how the Contravariant functor reverses the mapping direction",
+    "relevant": ["core/src/main/scala/cats/Contravariant.scala"],
+    "secondary": [],
+    "category": "semantic"
+  },
+  {
+    "query": "Monad",
+    "relevant": ["core/src/main/scala/cats/Monad.scala"],
+    "secondary": []
+  },
+  {
+    "query": "Functor",
+    "relevant": ["core/src/main/scala/cats/Functor.scala"],
+    "secondary": []
+  },
+  {
+    "query": "EitherT",
+    "relevant": ["core/src/main/scala/cats/data/EitherT.scala"],
+    "secondary": []
+  },
+  {
+    "query": "Validated",
+    "relevant": ["core/src/main/scala/cats/data/Validated.scala"],
+    "secondary": []
+  },
+  {
+    "query": "Kleisli",
+    "relevant": ["core/src/main/scala/cats/data/Kleisli.scala"],
+    "secondary": []
+  }
+]

benchmarks/annotations/chi.json

@@ -0,0 +1,32 @@
+[
+  {
+    "query": "HTTP router and middleware composition",
+    "relevant": ["mux.go"],
+    "secondary": ["chain.go"],
+    "category": "architecture"
+  },
+  {
+    "query": "radix tree path matching",
+    "relevant": ["tree.go"],
+    "secondary": [],
+    "category": "semantic"
+  },
+  {
+    "query": "request routing context storage",
+    "relevant": ["context.go"],
+    "secondary": ["mux.go"],
+    "category": "architecture"
+  },
+  {
+    "query": "request logging middleware",
+    "relevant": ["middleware/logger.go"],
+    "secondary": [],
+    "category": "semantic"
+  },
+  {
+    "query": "Mux",
+    "relevant": ["mux.go"],
+    "secondary": [],
+    "category": "symbol"
+  }
+]