feat: updating docs again

Author: benjivesterby

.crush.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://charm.land/crush.json",
+  "lsp": {
+    "go": {
+      "command": "gopls",
+      "env": {
+        "GOTOOLCHAIN": "go1.24.5"
+      }
+    }
+  }
+}

.envrc

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# shellcheck shell=bash
+
+################################################################################
+# Portable direnv bootstrap for Nix flakes – NixOS, Ubuntu/Debian and Alpine
+# Author: Benji (adapted)
+################################################################################
+set -euo pipefail
+
+###############################################################################
+# Helper functions
+###############################################################################
+warn()  { printf '\e[33m%s\e[0m\n' "$*" >&2; }
+fail()  { printf '\e[31m%s\e[0m\n' "$*" >&2; exit 1; }
+need()  { command -v "$1" &>/dev/null || return 1; }
+
+# Detect OS
+if [ -r /etc/os-release ]; then
+  . /etc/os-release
+else
+  fail "Unsupported system – no /etc/os-release"
+fi
+
+###############################################################################
+# Minimal prerequisites (curl & git) – only if Nix is missing
+###############################################################################
+if ! need nix; then
+  pkgs=""
+  need curl || pkgs+=" curl"
+  need git  || pkgs+=" git"
+
+  if [ -n "$pkgs" ]; then
+    if need sudo; then SUDO=sudo; else SUDO=""; fi
+    case "$ID" in
+      alpine)   $SUDO apk add --no-cache $pkgs ;;
+      debian|ubuntu) $SUDO apt-get update -y && $SUDO apt-get install -y $pkgs ;;
+      naxos)    ;; # already has nix
+      *)        warn "Unknown distro $ID – please install:$pkgs";;
+    esac
+  fi
+fi
+
+###############################################################################
+# Install Nix (if needed)
+###############################################################################
+if ! need nix; then
+  warn "Installing Nix package manager..."
+  case "$ID" in
+    alpine) sh <(curl -L https://nixos.org/nix/install) --no-daemon ;;
+    *)      sh <(curl -L https://nixos.org/nix/install) --daemon ;;
+  esac
+  # Load Nix into current shell – works for both install modes
+  if [ -f "$HOME/.nix-profile/etc/profile.d/nix.sh" ]; then
+    # shellcheck source=/dev/null
+    . "$HOME/.nix-profile/etc/profile.d/nix.sh"
+  elif [ -f /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh ]; then
+    # shellcheck source=/dev/null
+    . /nix/var/nix/profiles/default/etc/profile.d/nix-daemon.sh
+  fi
+fi
+
+###############################################################################
+# Ensure helper CLIs via Nix (gh, vault, cachix)
+###############################################################################
+ensure_cli() {
+  local cmd="$1" attr="$2"
+  need "$cmd" || nix-env -iA "nixpkgs.$attr" >/dev/null
+}
+export NIXPKGS_ALLOW_UNFREE=1
+ensure_cli gh     gh
+ensure_cli vault  vault
+ensure_cli cachix cachix
+
+###############################################################################
+# GitHub Token
+###############################################################################
+if [ -z "${GITHUB_TOKEN-}" ]; then
+  warn "Fetching GitHub token via GitHub CLI..."
+  GITHUB_TOKEN="$(gh auth token 2>/dev/null || true)"
+  [ -n "$GITHUB_TOKEN" ] || fail "No GITHUB_TOKEN found – set env var or run: gh auth login"
+  export GITHUB_TOKEN
+else
+  warn "Using existing GITHUB_TOKEN"
+fi
+
+###############################################################################
+# Vault login & secret retrieval
+###############################################################################
+export VAULT_ADDR=https://pki.devnw.com
+if ! vault token lookup -no-print &>/dev/null; then
+  vault login -no-print -method=github token="$GITHUB_TOKEN" || warn "Vault login failed"
+fi
+
+OPENAI_API_KEY="$(vault kv get -mount=secret -field=token /dev/openai/actions-primary 2>/dev/null || echo '')"
+export OPENAI_API_KEY
+CACHIX_AUTH_TOKEN="$(vault kv get -mount=secret -field=token /cicd/gh/cachix 2>/dev/null || echo '')"
+export CACHIX_AUTH_TOKEN
+
+###############################################################################
+# Nix configuration & Cachix
+###############################################################################
+NIX_CONFIG="experimental-features = nix-command flakes
+access-tokens = github.com=${GITHUB_TOKEN}
+trusted-users = root $(whoami)"
+export NIX_CONFIG
+
+# Configure trusted users in nix.conf if not already configured
+if ! grep -q "trusted-users.*$(whoami)" /etc/nix/nix.conf 2>/dev/null; then
+  warn "Adding $(whoami) as trusted user for Nix..."
+  echo "trusted-users = root $(whoami)" | sudo tee -a /etc/nix/nix.conf >/dev/null
+  sudo pkill nix-daemon 2>/dev/null || true
+  sleep 2
+fi
+
+# Setup Cachix auth and binary cache
+if [ -n "${CACHIX_AUTH_TOKEN-}" ]; then
+  cachix authtoken "$CACHIX_AUTH_TOKEN" >/dev/null 2>&1 || true
+  cachix use spyder >/dev/null 2>&1 || warn "Could not configure Cachix binary cache"
+fi
+
+###############################################################################
+# Finally: load the flake environment
+###############################################################################
+export FLAKE_PATH=.#          # override if desired
+export FLAKE_ARGS='--impure --accept-flake-config'
+
+source_up   # direnv helper – walk up to load any parent .envrc
+use flake "$FLAKE_PATH" $FLAKE_ARGS
+
+###############################################################################
+# Push newly built development shell to Cachix (non‑blocking)
+###############################################################################
+if [ -n "${CACHIX_AUTH_TOKEN-}" ]; then
+  # Push the development shell derivation to cachix
+  ( nix develop --dry-run --json $FLAKE_ARGS $FLAKE_PATH 2>/dev/null | jq -r '.devShell' | cachix push spyder 2>/dev/null || warn "Cachix push failed" ) &
+fi
+
+# End of .envrc

.github/AGENTS.md

@@ -0,0 +1 @@
+copilot-instructions.md

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @spyderorg/maintainers

.github/assets/bench.js

@@ -0,0 +1,78 @@
+// Benchmark page renderer: builds table + sparklines from bench JSON data.
+;(async function () {
+  const root = document.getElementById('bench-charts')
+  if (!root) return
+  function el(tag, attrs = {}, html = '') {
+    const e = document.createElement(tag)
+    for (const k in attrs) {
+      e.setAttribute(k, attrs[k])
+    }
+    if (html) e.innerHTML = html
+    return e
+  }
+  async function loadJSON(p) {
+    try {
+      const r = await fetch(p)
+      if (!r.ok) return null
+      return await r.json()
+    } catch (_) {
+      return null
+    }
+  }
+  const summary = await loadJSON('summary.json')
+  if (!summary) {
+    root.textContent = 'No benchmark summary available.'
+    return
+  }
+  if (!summary.benchmarks || !summary.benchmarks.length) {
+    root.textContent = 'Benchmark summary empty.'
+    return
+  }
+  root.textContent = ''
+  function spark(values, width = 160, height = 40, pad = 3) {
+    if (!values.length) return ''
+    const min = Math.min(...values),
+      max = Math.max(...values)
+    const span = max - min || 1
+    const pts = values
+      .map((v, i) => {
+        const x = pad + (i / (values.length - 1)) * (width - 2 * pad)
+        const y = pad + (1 - (v - min) / span) * (height - 2 * pad)
+        return x.toFixed(1) + ',' + y.toFixed(1)
+      })
+      .join(' ')
+    const last = values[values.length - 1]
+    const first = values[0]
+    const diff = last - first
+    const cls = diff < 0 ? 'better' : diff > 0 ? 'worse' : 'same'
+    return `<svg viewBox="0 0 ${width} ${height}" width="${width}" height="${height}" class="spark ${cls}"><polyline fill="none" stroke="currentColor" stroke-width="1.2" points="${pts}"/></svg>`
+  }
+  const table = el('table')
+  table.innerHTML =
+    '<thead><tr><th>Name</th><th>ns/op</th><th>bytes/op</th><th>allocs/op</th><th>trend</th></tr></thead><tbody></tbody>'
+  const tbody = table.querySelector('tbody')
+  for (const b of summary.benchmarks) {
+    const series = await loadJSON('data/' + b.file)
+    if (!series || !series.length) continue
+    const latest = series[series.length - 1]
+    const nsSeries = series.map((r) => r.ns_per_op)
+    const row = el('tr')
+    row.innerHTML = `<td><code>${
+      b.name
+    }</code></td><td>${latest.ns_per_op.toLocaleString()}</td><td>${
+      latest.bytes_per_op ?? ''
+    }</td><td>${latest.allocs_per_op ?? ''}</td><td>${spark(nsSeries)}</td>`
+    tbody.appendChild(row)
+  }
+  if (!tbody.children.length) {
+    root.textContent = 'No benchmark series data.'
+    return
+  }
+  const style = el(
+    'style',
+    {},
+    '.spark{background:var(--md-code-bg-color);border:1px solid var(--md-default-fg-color--light);border-radius:2px;margin:0 2px}.spark.better polyline{stroke:var(--md-typeset-color-success,#00aa55)}.spark.worse polyline{stroke:var(--md-typeset-color-error,#cc3344)} table{width:100%;border-collapse:collapse;margin-top:.75rem;font-size:.8rem}th,td{padding:4px 6px;border-bottom:1px solid var(--md-default-fg-color--light);}'
+  )
+  root.appendChild(style)
+  root.appendChild(table)
+})()

.github/compass-metrics.yml

@@ -0,0 +1,155 @@
+# Compass Metrics Configuration
+# This file maps metric names to their Compass metric source UUIDs
+# The full ARN is constructed as: {compass.base_arn}:metric-source/{component_uuid}/{metric_uuid}
+
+# Compass API Configuration
+compass:
+  # Your Atlassian instance URL
+  url: 'https://devnw.atlassian.net'
+
+  # Base Compass ARN (instance identifier)
+  base_arn: 'ari:cloud:compass:89436501-45fd-498f-9c7c-b0db10b968cb'
+
+  # Component UUID (extracted from compass.yml component ID)
+  # This will be auto-extracted from the component ID: only the first UUID (d819e7ce-7ec1-48ae-b718-cb3459fc6e06)
+  # Full component ID: ari:cloud:compass:...:component/d819e7ce-7ec1-48ae-b718-cb3459fc6e06/1420c0b0-56eb-401f-8c63-63f93faeea91
+  # You can also specify it manually here if needed:
+  # component_uuid: 'd819e7ce-7ec1-48ae-b718-cb3459fc6e06'
+
+# Metric Mappings
+# Each metric name maps to its specific metric source UUID
+# To get these UUIDs:
+# 1. Go to your Compass component page
+# 2. Navigate to the metric you want to configure
+# 3. Click "Copy cURL command"
+# 4. Extract the UUID from the "metricSourceId" (the part after the last /)
+metrics:
+  # Code Quality Metrics
+  test_coverage_percentage:
+    uuid: '11d716cf-5667-427f-b12a-b3a769654646'
+    description: 'Overall test coverage percentage of the codebase'
+
+  total_tests:
+    uuid: '4edc8ac9-ee6e-4e7d-9ab0-cdb5f56cd54b'
+    description: 'Total number of test functions'
+
+  failed_tests:
+    uuid: '61c8881f-c858-4b88-afdd-f8e68d3cfd64'
+    description: 'Number of failed tests'
+
+  passed_tests:
+    uuid: 'cd0a5e70-8bc1-4dde-a803-cc1411bbc99f'
+    description: 'Number of passed tests'
+
+  test_success_rate:
+    uuid: '8fb59d8d-545b-4fc3-9ee7-00a45879b89b'
+    description: 'Percentage of tests that pass'
+
+  # Code Complexity Metrics
+  avg_cyclomatic_complexity:
+    uuid: '91450e63-fc2c-4082-b216-f5c0f74c4337'
+    description: 'Average cyclomatic complexity across all functions'
+
+  high_complexity_functions:
+    uuid: 'f9413012-6459-4235-bc2b-227aa7f79256'
+    description: 'Number of functions with complexity > 10'
+
+  function_count:
+    uuid: '98f2173b-300a-4b8f-9493-03032e37bd60'
+    description: 'Total number of functions (excluding tests)'
+
+  test_function_count:
+    uuid: 'dddfb653-c4a3-40e9-bd07-f6f800f72474'
+    description: 'Number of test functions'
+
+  benchmark_function_count:
+    uuid: 'fa8e56c7-8e7a-4b59-9ad1-445972bcfa2f'
+    description: 'Number of benchmark functions'
+
+  # Repository Metrics
+  lines_of_code:
+    uuid: '6ff6fc77-b77a-4780-8441-dcd4e075d23e'
+    description: 'Total lines of Go code'
+
+  go_files_count:
+    uuid: 'a0e73f35-5207-41d6-a955-a8e617d5ec17'
+    description: 'Number of Go source files'
+
+  package_count:
+    uuid: '41798047-20de-4011-a42f-e4a17485d6d6'
+    description: 'Number of Go packages'
+
+  direct_dependencies:
+    uuid: '28392e75-9434-45dd-9119-b8bde436688f'
+    description: 'Number of direct Go module dependencies'
+
+  # Performance Metrics
+  benchmark_count:
+    uuid: '2ab5c86e-bf1f-434a-bea6-920907fccd1d'
+    description: 'Number of benchmark tests'
+
+  avg_benchmark_ns_per_op:
+    uuid: 'd4a2e683-69de-411b-b05c-2b5de50752c8'
+    description: 'Average nanoseconds per operation across benchmarks'
+
+  avg_benchmark_bytes_per_op:
+    uuid: 'ce949ae0-e67b-4de8-9dcf-d53eeb4b2484'
+    description: 'Average bytes per operation across benchmarks'
+
+  avg_benchmark_allocs_per_op:
+    uuid: 'aa4a0bbf-34cf-4748-96c2-62dbc5a2498e'
+    description: 'Average allocations per operation across benchmarks'
+
+  slowest_benchmark_ns_per_op:
+    uuid: 'acd737c6-3606-4eb7-9d04-6c884ed940de'
+    description: 'Slowest benchmark (highest ns/op)'
+
+  fastest_benchmark_ns_per_op:
+    uuid: '857c7ccc-030d-4ebc-a883-4cfc1406dc3d'
+    description: 'Fastest benchmark (lowest ns/op)'
+
+  benchmark_performance_variance:
+    uuid: 'a8abd71d-0d5a-4ec9-8862-587bae2ae003'
+    description: 'Standard deviation of benchmark performance'
+
+  # Development Activity Metrics
+  total_commits:
+    uuid: 'ed4fd8ea-79ad-47eb-83ae-24581e28b3b7'
+    description: 'Total number of commits in the repository'
+
+  commits_last_30_days:
+    uuid: '6dcb75d4-e5f1-47e1-9824-cffa8f634151'
+    description: 'Number of commits in the last 30 days'
+
+  # Additional Benchmark Metrics (from JSON parsing)
+  successful_benchmarks:
+    uuid: '47c1d92a-02a2-42c1-b584-3c1ef2dd81f0'
+    description: 'Number of successful benchmark runs'
+
+  failed_benchmarks:
+    uuid: '6cbcc1a2-5250-400b-b064-48aecb881c5a'
+    description: 'Number of failed benchmark runs'
+
+  benchmark_success_rate:
+    uuid: 'dc4c97bd-8574-458c-9a3b-090f32aedb75'
+    description: 'Percentage of benchmarks that pass'
+
+  total_benchmark_time_seconds:
+    uuid: '53d4eb4b-4cfb-4b7d-b087-833c679a50df'
+    description: 'Total benchmark execution time in seconds'
+
+# Configuration for metric pushing behavior
+settings:
+  # Whether to continue pushing other metrics if one fails
+  continue_on_error: true
+
+  # Whether to validate ARN format before pushing
+  validate_arn_format: true
+
+  # Timeout for each metric push request (in seconds)
+  request_timeout: 30
+
+  # Whether to log detailed responses for debugging
+  verbose_logging: true
+# NOTE: Replace all the example ARNs above with the actual metric source ARNs from your Compass instance
+# The ARNs shown are examples and will not work without being updated to match your actual metrics