📝 Add docstrings to codex/extend-ci-pipeline-with-performance-thresholds

Docstrings generation was requested by @shayancoin.

* #123 (comment)

The following files were modified:

* `frontend/tests/perf/run-perf-budget.ts`
* `scripts/ci/check_canary_metrics.py`

Author: coderabbitai[bot]

frontend/tests/perf/run-perf-budget.ts

@@ -101,6 +101,12 @@ const rootDir = path.resolve(__dirname, '../../..');
 const configPath = path.join(rootDir, '.perf-budget.yml');
 const resultsDir = path.join(rootDir, 'perf-results');
 
+/**
+ * Load and validate the performance budget configuration from disk.
+ *
+ * @returns The parsed PerfBudgetConfig read from the configured config path
+ * @throws Error if the configuration is missing a top-level `scenarios` array
+ */
 function readConfig(): PerfBudgetConfig {
   const file = fs.readFileSync(configPath, 'utf-8');
   const parsed = yaml.parse(file) as PerfBudgetConfig;
@@ -110,6 +116,22 @@ function readConfig(): PerfBudgetConfig {
   return parsed;
 }
 
+/**
+ * Applies CPU and network emulation to the given browser context/page according to the provided throttling settings.
+ *
+ * When `throttling` is omitted, no emulation is applied. If `cpu_slowdown_multiplier` is a positive number,
+ * a CDP session is used to set the CPU throttling rate. If any of `download_throughput_kbps`, `upload_throughput_kbps`,
+ * or `request_latency_ms` are provided, network emulation is enabled and those values are applied (throughput values
+ * are converted from kbps to bytes/sec as required by the CDP).
+ *
+ * @param context - The Playwright BrowserContext to create a CDP session on.
+ * @param page - The Playwright Page associated with the context (used to bind the CDP session).
+ * @param throttling - Optional throttling parameters:
+ *   - `cpu_slowdown_multiplier`: CPU slowdown multiplier (greater than 0 enables CPU throttling).
+ *   - `download_throughput_kbps`: Download throughput in kilobits per second.
+ *   - `upload_throughput_kbps`: Upload throughput in kilobits per second.
+ *   - `request_latency_ms`: Additional request latency in milliseconds.
+ */
 async function applyThrottling(context: BrowserContext, page: Page, throttling?: ThrottlingConfig) {
   if (!throttling) {
     return;
@@ -132,6 +154,16 @@ async function applyThrottling(context: BrowserContext, page: Page, throttling?:
   }
 }
 
+/**
+ * Installs in-page performance observers that record LCP entries, cumulative layout shift, and total blocking time into a global store.
+ *
+ * Injects a global `__perfBudget` object on the target page and registers PerformanceObserver instances that populate:
+ * - `lcpEntries`: array of LCP PerformanceEntry objects
+ * - `cls`: cumulative layout shift value
+ * - `tbt`: accumulated total blocking time (ms)
+ *
+ * @param page - The Playwright `Page` to attach the observers to
+ */
 async function setupPerformanceObservers(page: Page) {
   await page.addInitScript(() => {
     const globalAny = globalThis as any;
@@ -185,6 +217,11 @@ async function setupPerformanceObservers(page: Page) {
   });
 }
 
+/**
+ * Performs a configured wait step on the given page, supporting selector and network-idle waits.
+ *
+ * @param wait - Wait step configuration. If `type` is `"selector"`, waits for `selector` with a default timeout of 30000 ms unless `timeout_ms` is provided. If `type` is `"networkidle"`, waits for the page network to become idle with a default timeout of 60000 ms unless `timeout_ms` is provided; if `idle_ms` is set and greater than zero, waits an additional `idle_ms` milliseconds after network idle.
+ */
 async function performWait(page: Page, wait: WaitStep) {
   if (wait.type === 'selector') {
     await page.waitForSelector(wait.selector, { timeout: wait.timeout_ms ?? 30000 });
@@ -196,6 +233,17 @@ async function performWait(page: Page, wait: WaitStep) {
   }
 }
 
+/**
+ * Execute a single scenario step against the provided Playwright page.
+ *
+ * Supports three step types:
+ * - `goto`: navigates the page to `step.url` and waits until the specified `step.wait_until` event (defaults to `load`) or navigation completes.
+ * - `wait_for_selector`: waits for the given `step.selector` to appear (optional `step.timeout_ms` in milliseconds).
+ * - `wait_for_timeout`: waits for `step.timeout_ms` milliseconds.
+ *
+ * @param page - The Playwright Page to operate on.
+ * @param step - The step configuration describing the action to perform.
+ */
 async function performScenarioStep(page: Page, step: ScenarioStep) {
   if (step.type === 'goto') {
     await page.goto(step.url, { waitUntil: step.wait_until ?? 'load', timeout: 60000 });
@@ -206,6 +254,15 @@ async function performScenarioStep(page: Page, step: ScenarioStep) {
   }
 }
 
+/**
+ * Runs a single performance scenario in a new browser context and returns collected runtime metrics.
+ *
+ * @param scenario - The scenario configuration to execute (URL or ordered steps, waits, and scenario id).
+ * @param browser - Playwright browser instance used to create an isolated context for the run.
+ * @param defaults - Default perf budget settings (e.g., throttling) applied to the run when present.
+ * @returns A `RunMetrics` map of metric identifier to numeric value or `null` when a measurement is not available.
+ * @throws Error if the provided scenario contains neither `url` nor `steps`.
+ */
 async function executeScenarioRun(
   scenario: ScenarioConfig,
   browser: Browser,
@@ -260,6 +317,12 @@ async function executeScenarioRun(
   return metrics;
 }
 
+/**
+ * Aggregate an array of per-run metric objects into buckets of numeric samples keyed by metric identifier.
+ *
+ * @param metrics - Array of run metric maps produced by individual scenario executions
+ * @returns A mapping from each metric id to an array of finite numeric samples collected across runs
+ */
 function collectScenarioMetrics(metrics: RunMetrics[]): ScenarioMetrics {
   const result: ScenarioMetrics = {};
   for (const run of metrics) {
@@ -275,6 +338,13 @@ function collectScenarioMetrics(metrics: RunMetrics[]): ScenarioMetrics {
   return result;
 }
 
+/**
+ * Computes the requested percentile from a sorted numeric array.
+ *
+ * @param sorted - Array of numbers sorted in ascending order.
+ * @param percentileValue - Percentile to compute, between 0 and 1 inclusive (for example, `0.5` for the median).
+ * @returns The interpolated percentile value for `percentileValue`; `NaN` if `sorted` is empty.
+ */
 function percentile(sorted: number[], percentileValue: number): number {
   if (sorted.length === 0) {
     return NaN;
@@ -288,6 +358,16 @@ function percentile(sorted: number[], percentileValue: number): number {
   return sorted[lower] + (sorted[upper] - sorted[lower]) * (index - lower);
 }
 
+/**
+ * Compute an aggregate statistic from a list of numeric samples.
+ *
+ * Supported aggregations: 'mean', 'median' (alias 'p50'), 'p75', 'p90', 'p95'.
+ *
+ * @param values - The numeric samples to aggregate
+ * @param aggregation - The aggregation method to apply
+ * @returns The aggregated numeric value; `NaN` if `values` is empty
+ * @throws Error if `aggregation` is not one of the supported methods
+ */
 function aggregate(values: number[], aggregation: Aggregation | string): number {
   if (values.length === 0) {
     return NaN;
@@ -310,6 +390,12 @@ function aggregate(values: number[], aggregation: Aggregation | string): number
   }
 }
 
+/**
+ * Builds a JUnit-compatible report representing scenario metric results and budget violations.
+ *
+ * @param results - Array of scenario results to include in the report
+ * @returns A JUnitReport containing one test suite per scenario; each metric is a test case and metrics that exceeded their thresholds are represented as failures
+ */
 function createJUnitReport(results: ScenarioResult[]): JUnitReport {
   const suites: JUnitSuite[] = [];
   let totalTests = 0;
@@ -351,6 +437,13 @@ function createJUnitReport(results: ScenarioResult[]): JUnitReport {
   };
 }
 
+/**
+ * Serialize a JUnitReport to XML and write it to the perf-results/perf-budget-junit.xml file.
+ *
+ * Creates the results directory if it does not exist before writing the file.
+ *
+ * @param report - The JUnit report object to serialize and persist
+ */
 function writeJUnitReport(report: JUnitReport) {
   const xmlLines: string[] = [];
   xmlLines.push('<?xml version="1.0" encoding="UTF-8"?>');
@@ -380,6 +473,12 @@ function writeJUnitReport(report: JUnitReport) {
   fs.writeFileSync(path.join(resultsDir, 'perf-budget-junit.xml'), xmlLines.join('\n'), 'utf-8');
 }
 
+/**
+ * Escape XML special characters in a string for safe inclusion in XML.
+ *
+ * @param value - The string to escape
+ * @returns The input string with `&`, `"` , `<`, and `>` replaced by their XML entities (`&amp;`, `&quot;`, `&lt;`, `&gt;`)
+ */
 function escapeXml(value: string): string {
   return value
     .replace(/&/g, '&amp;')
@@ -388,11 +487,23 @@ function escapeXml(value: string): string {
     .replace(/>/g, '&gt;');
 }
 
+/**
+ * Persist the provided performance summary to perf-results/perf-budget-summary.json.
+ *
+ * Ensures the results directory exists and writes `summary` as pretty-printed JSON to the file.
+ *
+ * @param summary - The aggregated performance summary to save
+ */
 function writeSummary(summary: Summary) {
   fs.mkdirSync(resultsDir, { recursive: true });
   fs.writeFileSync(path.join(resultsDir, 'perf-budget-summary.json'), JSON.stringify(summary, null, 2), 'utf-8');
 }
 
+/**
+ * Executes all configured performance scenarios, aggregates their metrics, and produces reports.
+ *
+ * Reads the performance budget configuration, runs each scenario the configured number of times, aggregates metric samples according to each metric's aggregation strategy, evaluates them against thresholds, writes a JSON summary and a JUnit XML report to the results directory, and sets a non-zero process exit code when any metric violates its threshold.
+ */
 async function run() {
   const config = readConfig();
   const defaults = config.defaults ?? {};
@@ -463,4 +574,4 @@ async function run() {
 run().catch((error) => {
   console.error('Failed to execute performance budgets', error);
   process.exitCode = 1;
-});
+});

scripts/ci/check_canary_metrics.py

@@ -30,19 +30,45 @@ class CanaryCheckError(RuntimeError):
 
 
 def _float_or_none(value: Any) -> Optional[float]:
+    """
+    Convert the given value to a float, returning None if the value cannot be converted.
+    
+    Returns:
+        float_value (Optional[float]): The value converted to a `float`, or `None` if conversion raises `TypeError` or `ValueError`.
+    """
     try:
         return float(value)
     except (TypeError, ValueError):
         return None
 
 
 def _http_get_json(url: str, params: Optional[Dict[str, str]] = None) -> Dict[str, Any]:
+    """
+    Fetches JSON from the given URL, optionally adding URL-encoded query parameters, and returns the parsed payload.
+    
+    Parameters:
+        url (str): The request URL or base endpoint.
+        params (Optional[Dict[str, str]]): Query parameters to URL-encode and append to the URL.
+    
+    Returns:
+        Dict[str, Any]: The parsed JSON response as a Python dictionary.
+    """
     query = f"{url}?{urllib.parse.urlencode(params)}" if params else url
     with urllib.request.urlopen(query, timeout=10) as response:
         return json.loads(response.read().decode("utf-8"))
 
 
 def _extract_prom_value(payload: Dict[str, Any]) -> Optional[float]:
+    """
+    Extracts a numeric sample value from a Prometheus-style query response.
+    
+    Parameters:
+        payload (dict): The JSON-decoded response from Prometheus' HTTP API.
+    
+    Returns:
+        float: The extracted numeric value when present.
+        None: If the response status is not "success", contains no results, or a numeric sample cannot be determined.
+    """
     if payload.get("status") != "success":
         return None
     data = payload.get("data", {})
@@ -61,6 +87,12 @@ def _extract_prom_value(payload: Dict[str, Any]) -> Optional[float]:
 
 
 def _query_prometheus(base_url: str, query: str) -> Optional[float]:
+    """
+    Query a Prometheus instant query endpoint and return the numeric result if present.
+    
+    Returns:
+        float: Numeric value extracted from the Prometheus response, or `None` if the HTTP request failed or the response did not contain a usable numeric result.
+    """
     endpoint = f"{base_url.rstrip('/')}/api/v1/query"
     try:
         payload = _http_get_json(endpoint, {"query": query})
@@ -71,6 +103,21 @@ def _query_prometheus(base_url: str, query: str) -> Optional[float]:
 
 
 def _load_fixture(path: str) -> CanaryMetrics:
+    """
+    Load canary metrics from a JSON fixture file.
+    
+    Parameters:
+        path (str): Filesystem path to a JSON fixture containing top-level keys
+            "current", "previous", "tempo", and "metadata". Missing numeric fields
+            default to 0.0 or None as appropriate.
+    
+    Returns:
+        CanaryMetrics: Instance populated from the fixture:
+          - latency_p95_ms and error_rate taken from `current`.
+          - trace_latency_p95_ms taken from `tempo`.
+          - previous_latency_p95_ms and previous_error_rate taken from `previous`.
+          - build, previous_build, and generated_at taken from `metadata`.
+    """
     with open(path, "r", encoding="utf-8") as handle:
         payload = json.load(handle)
     current = payload.get("current", {})
@@ -90,6 +137,20 @@ def _load_fixture(path: str) -> CanaryMetrics:
 
 
 def _collect_metrics_from_services() -> Optional[CanaryMetrics]:
+    """
+    Collect canary metrics from Prometheus and Tempo based on environment configuration.
+    
+    Attempts to query Prometheus for current P95 latency and error rate and, when configured, previous-period metrics and Tempo trace P95 latency. Required environment variables for live collection are PROMETHEUS_URL, PROMETHEUS_LATENCY_QUERY, and PROMETHEUS_ERROR_QUERY. Optional environment variables:
+    - PROMETHEUS_PREVIOUS_LATENCY_QUERY, PROMETHEUS_PREVIOUS_ERROR_QUERY: queries for previous metrics.
+    - TEMPO_URL, TEMPO_TRACE_QUERY: Tempo search API and query for trace latency.
+    - BUILD_TAG or GITHUB_SHA: current build identifier.
+    - PREVIOUS_BUILD_TAG: previous build identifier.
+    
+    If Prometheus is unreachable, missing required configuration, or returns no data for the primary latency or error queries, the function returns None to signal that callers should fall back to fixture data. On success, returns a CanaryMetrics instance populated with collected values (including trace_latency_p95_ms when available), previous values when provided, build metadata, and a UTC ISO-like generated_at timestamp.
+    
+    Returns:
+        Optional[CanaryMetrics]: A populated CanaryMetrics object when live collection succeeds, or `None` when live data is unavailable and a fixture should be used.
+    """
     prom_url = os.environ.get("PROMETHEUS_URL")
     latency_query = os.environ.get("PROMETHEUS_LATENCY_QUERY")
     error_query = os.environ.get("PROMETHEUS_ERROR_QUERY")
@@ -148,6 +209,14 @@ def _collect_metrics_from_services() -> Optional[CanaryMetrics]:
 
 
 def _load_metrics() -> CanaryMetrics:
+    """
+    Load canary metrics from configured services, falling back to a JSON fixture when live collection is unavailable.
+    
+    If environment and service queries provide metrics, those are returned; otherwise the fixture path from CANARY_METRICS_FIXTURE (or the default "tests/perf/canary-metrics.fixture.json") is used and its contents are returned. The chosen fixture path is printed when the fallback is used.
+    
+    Returns:
+        CanaryMetrics: Collected canary metrics and metadata, sourced from live services when available or from the fixture otherwise.
+    """
     metrics = _collect_metrics_from_services()
     if metrics:
         return metrics
@@ -158,6 +227,13 @@ def _load_metrics() -> CanaryMetrics:
 
 
 def _write_summary(metrics: CanaryMetrics, passed: bool) -> None:
+    """
+    Write a JSON summary of the provided canary metrics and pass/fail result to perf-results/canary-metrics-summary.json.
+    
+    Parameters:
+        metrics (CanaryMetrics): Collected canary metrics and metadata to include in the summary.
+        passed (bool): Whether the canary checks passed; written as the `passed` field in the summary.
+    """
     summary_path = os.path.join("perf-results", "canary-metrics-summary.json")
     os.makedirs(os.path.dirname(summary_path), exist_ok=True)
     payload = {
@@ -176,6 +252,21 @@ def _write_summary(metrics: CanaryMetrics, passed: bool) -> None:
 
 
 def _evaluate(metrics: CanaryMetrics) -> None:
+    """
+    Validate the provided canary metrics against configured thresholds and raise on any violations.
+    
+    Checks performed:
+    - P95 latency exceeds P95_THRESHOLD_MS (default 3000).
+    - Error rate exceeds ERROR_RATE_THRESHOLD (default 0.02).
+    - Latency regression relative to previous_latency_p95_ms exceeds REGRESSION_TOLERANCE_PCT (default 0.1).
+    - Error rate regression relative to previous_error_rate exceeds REGRESSION_TOLERANCE_PCT.
+    
+    Parameters:
+        metrics (CanaryMetrics): Current canary metrics; when present, previous_latency_p95_ms and previous_error_rate are used for regression checks.
+    
+    Raises:
+        CanaryCheckError: If any threshold or regression check fails. The exception message contains a semicolon-separated list of failure descriptions.
+    """
     latency_budget = float(os.environ.get("P95_THRESHOLD_MS", 3000))
     error_budget = float(os.environ.get("ERROR_RATE_THRESHOLD", 0.02))
     regression_tolerance_pct = float(os.environ.get("REGRESSION_TOLERANCE_PCT", 0.1))
@@ -216,6 +307,14 @@ def _evaluate(metrics: CanaryMetrics) -> None:
 
 
 def main() -> int:
+    """
+    Run the canary metric validation flow, emit a human-readable summary, write a pass/fail summary file, and return an exit code.
+    
+    The function loads metrics, evaluates them against configured thresholds, prints status and comparisons to stdout/stderr, writes a JSON summary file indicating pass or fail, and exits with a code appropriate to the result.
+    
+    Returns:
+        int: `0` if all checks pass, `1` if any check fails.
+    """
     metrics = _load_metrics()
     try:
         _evaluate(metrics)
@@ -245,4 +344,4 @@ def main() -> int:
 
 
 if __name__ == "__main__":
-    sys.exit(main())
+    sys.exit(main())