hyperweave 0.2.7__tar.gz → 0.2.9__tar.gz

{hyperweave-0.2.7 → hyperweave-0.2.9}/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to HyperWeave are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.9] - 2026-04-21
+
+### Fixed
+
+- **Star history charts now render an authentic growth curve for any repo size.** v0.2.8 fetched only the most-recent 2,000 stargazers for any repo with more than ~2,000 stars, which meant both the 361,000-star `openclaw/openclaw` and the 40,000-star `JuliusBrussee/caveman` rendered as flat horizontal lines near their total-star value — the captured window's variation was invisible on the full-range Y-axis. Star history now uses GraphQL cursor-offset sampling to pull 12 real stargazer timestamps evenly distributed across the repository's full lifetime, regardless of whether the repo has 30 stars or 500,000. The resulting curve shows actual adoption shape — slow-early, explosive-middle, tapering-late — rather than either a hockey-stick or a flat line.
+- **X-axis date labels adapt to the repository's lifetime.** A viral repo that went from 0 to 40K stars in two weeks was being labeled with a single "2026" at the center of its axis; a mature repo with 10 years of history showed the same year-only format. The axis now selects granularity from the actual temporal span — daily labels ("Apr 05", "Apr 12") when the span is under two weeks, weekly under 90 days, month-plus-year under two years, yearly up to ten years, and every-other-year beyond. Labels maintain a minimum 48-pixel horizontal gap so they never collide — the "202324" pileup is gone.
+
+### Changed
+
+- **Parallel GraphQL dispatch is now bounded.** Cold fetches fan out twelve cursor-offset queries across four concurrent in-flight requests via `asyncio.Semaphore`. This keeps cold-fetch latency under ~1 second while staying well below per-minute abuse-detection thresholds that bursty same-token parallelism could otherwise trip.
+
+## [0.2.8] - 2026-04-20
+
+### Fixed
+
+- **Star history charts now render readably on large repositories.** Previously, repos with more than ~40,000 stars produced a flat-then-vertical "hockey stick" because GitHub's stargazer REST endpoint hard-caps deep pagination, so the only data reachable was a small cluster of early-history stars followed by a single jump to today. Star history now sources from GitHub's GraphQL API and adapts its sampling window to the repo: small repos continue to get full lifetime views, large repos get a detailed recent-growth curve similar to the one star-history.com shows.
+- **Star-count milestone labels no longer stack on top of each other.** When sampled points clustered temporally, the milestone labels (`500`, `1K`, `5K`, `10K`, ...) would render in a single illegible pile on top of the crossing point. Milestones now maintain a minimum 40-pixel horizontal gap; any labels that would overlap with an already-placed one are dropped in favor of the first (lowest-threshold) milestone in the cluster.
+
+### Changed
+
+- **All chart rendering now flows through template partials.** The chart engine's remaining rendering paths — axes, gridlines, polyline, area fill, milestones, and the empty-state overlay — joined the marker layer in Jinja. The engine module returns structured Python data; Jinja partials under `templates/components/` produce the final SVG. No visual change; output is byte-identical for the shipped genomes on unchanged inputs.
+
+### Added
+
+- **`fetch_graphql` connector primitive.** New async helper in the connector layer that handles POST with JSON bodies, GitHub bearer-token rotation, circuit-breaker coordination, and SSRF validation — mirroring the existing `fetch_json` contract. This unlocks future migration of the stats card's six REST sub-fetches to a single GraphQL call, and keeps a single canonical place for authenticated-POST plumbing.
+
+### Dev
+
+- GraphQL stargazer pipeline is covered by unit tests for the primary path, REST fallback on failure, no-token skip, mega-repo window cap, small-repo history exhaustion, downsampling correctness, and current-UTC now-point stamping.
+
 ## [0.2.7] - 2026-04-20
 
 ### Fixed

{hyperweave-0.2.7 → hyperweave-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperweave
-Version: 0.2.7
+Version: 0.2.9
 Summary: Headless visual output layer for AI agents. One API call → self-contained SVG.
 Project-URL: Repository, https://github.com/InnerAura/hyperweave
 Project-URL: Issues, https://github.com/InnerAura/hyperweave/issues

{hyperweave-0.2.7 → hyperweave-0.2.9}/src/hyperweave/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.7'
-__version_tuple__ = version_tuple = (0, 2, 7)
+__version__ = version = '0.2.9'
+__version_tuple__ = version_tuple = (0, 2, 9)
 
 __commit_id__ = commit_id = None

{hyperweave-0.2.7 → hyperweave-0.2.9}/src/hyperweave/compose/context.py

@@ -337,12 +337,16 @@ def _ctx_chart(spec: ComposeSpec, resolved: ResolvedArtifact, css: dict[str, str
     ctx["chart_viewport_w"] = 0
     ctx["chart_viewport_h"] = 0
     ctx["chart_defs"] = ""
-    ctx["chart_axes"] = ""
-    ctx["chart_gridlines"] = ""
-    ctx["chart_area"] = ""
-    ctx["chart_polyline"] = ""
+    # Post-v0.2.8: axes / gridlines / milestones / markers all return structured
+    # lists; polyline / area / empty_state are dicts or None so templates can
+    # use ``{% if %}`` to guard includes without a StrictUndefined trap.
+    ctx["chart_axes"] = []
+    ctx["chart_gridlines"] = []
+    ctx["chart_area"] = None
+    ctx["chart_polyline"] = None
     ctx["chart_markers"] = []
-    ctx["chart_milestones"] = ""
+    ctx["chart_milestones"] = []
+    ctx["chart_empty_state"] = None
     ctx["data_hw_status"] = "fresh"
     ctx.update(resolved.frame_context)
     return ctx

{hyperweave-0.2.7 → hyperweave-0.2.9}/src/hyperweave/connectors/base.py

@@ -216,3 +216,66 @@ async def fetch_text(
         merged.update(headers)
     response = await fetch(url, provider=provider, headers=merged)
     return response.text
+
+
+# GraphQL POST
+
+_GITHUB_GRAPHQL_URL: str = "https://api.github.com/graphql"
+
+
+async def fetch_graphql(
+    query: str,
+    variables: dict[str, Any] | None = None,
+    *,
+    provider: str = "github",
+    url: str = _GITHUB_GRAPHQL_URL,
+) -> dict[str, Any]:
+    """POST a GraphQL query and return the parsed JSON response.
+
+    Mirrors :func:`fetch_json`'s contract (SSRF validation, per-provider
+    circuit breaker, timeouts, GitHub Bearer-token injection) but speaks
+    POST with a JSON body. The single GraphQL endpoint for GitHub is
+    baked into the default URL so callers don't have to remember it.
+
+    GraphQL always returns HTTP 200 with a ``data`` field and an optional
+    ``errors`` list — HTTP-level failures trip the breaker, but query-level
+    errors (invalid field, missing perms) come through as response body
+    and are the caller's responsibility to inspect.
+    """
+    validate_url(url)
+
+    breaker = get_breaker(provider)
+    if not breaker.allow_request():
+        raise CircuitOpenError(
+            f"Circuit breaker open for provider {provider!r}. Retry after {breaker.recovery_timeout}s."
+        )
+
+    merged_headers: dict[str, str] = {
+        "User-Agent": f"HyperWeave/{__version__} (https://hyperweave.app)",
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+    }
+    if provider == "github":
+        token = _get_github_token()
+        if token:
+            merged_headers["Authorization"] = f"Bearer {token}"
+
+    timeout = httpx.Timeout(
+        connect=CONNECT_TIMEOUT,
+        read=TOTAL_TIMEOUT,
+        write=TOTAL_TIMEOUT,
+        pool=TOTAL_TIMEOUT,
+    )
+
+    body: dict[str, Any] = {"query": query, "variables": variables or {}}
+
+    try:
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            response = await client.post(url, headers=merged_headers, json=body)
+            response.raise_for_status()
+            breaker.record_success()
+            data: dict[str, Any] = response.json()
+            return data
+    except (httpx.HTTPStatusError, httpx.RequestError) as exc:
+        breaker.record_failure()
+        raise ConnectorError(f"GraphQL fetch failed for {provider!r}: {exc}") from exc

{hyperweave-0.2.7 → hyperweave-0.2.9}/src/hyperweave/connectors/github.py

@@ -3,12 +3,20 @@
 from __future__ import annotations
 
 import asyncio
+import base64
 import math
 import re
 from datetime import UTC, datetime
 from typing import Any
 
-from hyperweave.connectors.base import fetch_json, fetch_text
+from hyperweave.connectors.base import (
+    CircuitOpenError,
+    ConnectorError,
+    _get_github_token,
+    fetch_graphql,
+    fetch_json,
+    fetch_text,
+)
 from hyperweave.connectors.cache import get_cache
 
 PROVIDER = "github"
@@ -144,6 +152,47 @@ _STARGAZER_PAGE_SIZE = 100
 _STARGAZER_PAGE_CAP = 400
 _STARGAZER_ACCEPT_HEADER = "application/vnd.github.v3.star+json"
 
+# GraphQL cursor-offset sampling constants.
+#
+# GitHub's GraphQL cursors decode to the literal text ``cursor:<N>`` where
+# N is a 0-indexed offset into the stargazer list. By Base64-encoding
+# ``cursor:<N-1>`` we can construct an ``after:`` anchor that lets ``first: 1``
+# return exactly the Nth stargazer. This bypasses GitHub's 400-page REST cap
+# and lets us sample any offset in a 500K-star repo cheaply.
+#
+# 12 offsets * 1 node per call = 12 GraphQL points per cold fetch.
+# ``asyncio.Semaphore(_GRAPHQL_CONCURRENCY)`` caps fan-out so bursty
+# same-token parallelism doesn't trigger GitHub's per-minute abuse detection.
+_DEFAULT_SAMPLE_COUNT = 12
+_GRAPHQL_CONCURRENCY = 4
+
+_CURSOR_OFFSET_QUERY = """
+query StargazerAtOffset($owner: String!, $repo: String!, $cursor: String) {
+  repository(owner: $owner, name: $repo) {
+    stargazerCount
+    stargazers(first: 1, after: $cursor) {
+      edges { starredAt }
+    }
+  }
+}
+"""
+
+
+def _cursor_for_offset(offset: int) -> str | None:
+    """Return the Base64-encoded cursor for a 1-indexed stargazer position.
+
+    GitHub's GraphQL cursors decode to ``cursor:<N>`` where N is 0-indexed.
+    Constructing them lets us sample any offset within a repo's stargazer
+    list, bypassing both the REST 400-page cap and the cost of walking
+    every page via cursor pagination.
+
+    Returns None for ``offset <= 1`` (no cursor needed — this IS the first
+    entry; passing ``after: None`` to GraphQL starts from the beginning).
+    """
+    if offset <= 1:
+        return None
+    return base64.b64encode(f"cursor:{offset - 1}".encode()).decode()
+
 
 async def fetch_stargazer_history(
     owner: str,
@@ -152,19 +201,14 @@ async def fetch_stargazer_history(
 ) -> dict[str, Any]:
     """Fetch sampled star history for ``owner/repo`` as cumulative data points.
 
-    Strategy:
-      1. GET ``/repos/{owner}/{repo}`` → total ``stargazers_count``.
-      2. Compute total pages (30 per page on the stargazers endpoint).
-      3. Sample ``sample_pages`` evenly distributed page numbers across
-         ``[1, total_pages]`` and fetch them concurrently with the
-         ``application/vnd.github.v3.star+json`` ``Accept`` header so each
-         element contains a ``starred_at`` timestamp.
-      4. From each sampled page take the FIRST starred_at and use it as the
-         time marker for the cumulative count at ``(page - 1) * 30``.
-      5. Cache under ``github:{owner}/{repo}:stargazer-history``.
-
-    Returns a dict with keys ``points`` (list of ``{date, count}``), ``current_stars``,
-    ``repo``, ``ttl``. Raises ``ValueError`` on invalid identifier.
+    Public dispatcher. Prefers GraphQL when a token is available (unlocks the
+    recent-growth window on mega-repos beyond GitHub's 400-page REST cap);
+    falls back to REST sampling on GraphQL failure or missing token. Caches
+    successful results under ``github:{owner}/{repo}:stargazer-history``.
+
+    Returns a dict with keys ``points`` (list of ``{date, count}``),
+    ``current_stars``, ``repo``, ``ttl``. Raises ``ValueError`` on invalid
+    identifier.
     """
     if not owner or not repo:
         raise ValueError("fetch_stargazer_history requires owner and repo")
@@ -176,25 +220,171 @@ async def fetch_stargazer_history(
     if cached is not None:
         return cached  # type: ignore[no-any-return]
 
+    result: dict[str, Any] | None = None
+
+    # Primary path: GraphQL cursor-offset sampling (requires auth). Constructs
+    # cursors for N evenly-distributed stargazer offsets across [1, total_stars]
+    # and fetches one stargazer per offset. Bypasses GitHub's 400-page REST cap,
+    # so a 361K-star repo gets 12 real points across its full lifetime instead
+    # of a hockey-stick or flat line.
+    if _get_github_token():
+        try:
+            result = await _fetch_stargazer_history_graphql(owner, repo, sample_pages)
+        except (ConnectorError, CircuitOpenError):
+            result = None  # fall through to REST
+
+    if result is None:
+        # Fallback path: REST sampling. Works unauth at 60 req/hr but caps at
+        # ~40k stars on mega-repos (GitHub's deep-pagination wall).
+        result = await _fetch_stargazer_history_rest(owner, repo, sample_pages)
+
+    cache.set(cache_key, result, STARGAZER_HISTORY_TTL)
+    return result
+
+
+async def _fetch_stargazer_history_graphql(
+    owner: str,
+    repo: str,
+    sample_count: int = _DEFAULT_SAMPLE_COUNT,
+) -> dict[str, Any]:
+    """Sample N stargazer timestamps at evenly-distributed cursor offsets.
+
+    Strategy: given a repo's ``total_stars``, fetch one stargazer at each of
+    N evenly-spaced offsets across ``[1, total_stars]``. Each offset maps to
+    a constructed cursor (``base64("cursor:<N-1>")``); GraphQL returns that
+    stargazer's ``starred_at``. Pair with the known offset to form a
+    ``{date, count}`` point. Appends a now-point at ``total_stars``.
+
+    Works for any repo size — 30 stars, 2938 stars, 361k stars — because
+    cursor-offset sampling is not subject to GitHub's 400-page REST cap.
+
+    Concurrency is bounded at ``_GRAPHQL_CONCURRENCY`` to avoid tripping
+    per-minute abuse-detection heuristics on bursty parallel fan-out.
+    """
+    identifier = f"{owner}/{repo}"
+
+    # First query: learn total_stars and pick up the first stargazer's
+    # timestamp in the same round-trip (offset 1 uses no cursor anyway).
+    first_response = await fetch_graphql(
+        _CURSOR_OFFSET_QUERY,
+        {"owner": owner, "repo": repo, "cursor": None},
+        provider=PROVIDER,
+    )
+    repo_data = (first_response.get("data") or {}).get("repository")
+    if not repo_data:
+        return _empty_stargazer_result(identifier)
+
+    total_stars = int(repo_data.get("stargazerCount", 0))
+    if total_stars == 0:
+        return _empty_stargazer_result(identifier)
+
+    first_edges = (repo_data.get("stargazers") or {}).get("edges") or []
+    first_starred_at: str | None = None
+    if first_edges and isinstance(first_edges[0], dict):
+        first_starred_at = first_edges[0].get("starredAt")
+
+    # Clamp sample count to total_stars — small repos get every star sampled
+    # (no point requesting 12 offsets from a 5-star repo).
+    effective_samples = min(sample_count, total_stars)
+
+    # Compute evenly-distributed offsets across the full stargazer list.
+    # Always includes position 1 (oldest) and position total_stars (newest).
+    if effective_samples <= 1:
+        offsets = [1]
+    else:
+        step = (total_stars - 1) / (effective_samples - 1)
+        offsets = sorted({max(1, round(1 + step * i)) for i in range(effective_samples)})
+
+    # Bounded concurrent fan-out: semaphore throttles to _GRAPHQL_CONCURRENCY
+    # in-flight requests at a time. For 12 offsets at concurrency 4, that's
+    # 3 waves of ≤4 calls each → ~1s cold-fetch latency.
+    sem = asyncio.Semaphore(_GRAPHQL_CONCURRENCY)
+
+    async def _fetch_one(offset: int) -> tuple[int, str | None]:
+        # Offset 1 is already in hand from the total_stars lookup.
+        if offset == 1 and first_starred_at is not None:
+            return offset, first_starred_at
+        cursor = _cursor_for_offset(offset)
+        async with sem:
+            resp = await fetch_graphql(
+                _CURSOR_OFFSET_QUERY,
+                {"owner": owner, "repo": repo, "cursor": cursor},
+                provider=PROVIDER,
+            )
+        edges_data = (((resp.get("data") or {}).get("repository") or {}).get("stargazers") or {}).get("edges") or []
+        starred_at: str | None = None
+        if edges_data and isinstance(edges_data[0], dict):
+            starred_at = edges_data[0].get("starredAt")
+        return offset, starred_at
+
+    results = await asyncio.gather(
+        *[_fetch_one(off) for off in offsets],
+        return_exceptions=True,
+    )
+
+    points: list[dict[str, Any]] = []
+    for item in results:
+        if isinstance(item, BaseException):
+            continue
+        offset, starred_at = item
+        if starred_at is None:
+            continue
+        points.append({"date": starred_at, "count": offset})
+
+    # Append the honest now-point: current timestamp at the real total count.
+    if points:
+        points.append({"date": datetime.now(UTC).isoformat(), "count": total_stars})
+    points.sort(key=lambda p: p["date"])
+
+    return {
+        "points": points,
+        "current_stars": total_stars,
+        "repo": identifier,
+        "ttl": STARGAZER_HISTORY_TTL,
+    }
+
+
+def _empty_stargazer_result(identifier: str) -> dict[str, Any]:
+    """Shared empty-state shape for zero-star or missing-repo cases."""
+    return {
+        "points": [],
+        "current_stars": 0,
+        "repo": identifier,
+        "ttl": STARGAZER_HISTORY_TTL,
+    }
+
+
+async def _fetch_stargazer_history_rest(
+    owner: str,
+    repo: str,
+    sample_pages: int = 12,
+) -> dict[str, Any]:
+    """REST-based stargazer sampling — the v0.2.7 behavior preserved as fallback.
+
+    Used when no ``HW_GITHUB_TOKENS`` is set or when the GraphQL path fails.
+    Samples evenly across pages ``[1, min(total_pages, 400)]`` and stamps the
+    now-point with the current UTC timestamp. Bounded by GitHub's 400-page
+    deep-pagination cap: produces a truthful but limited view of mega-repos.
+    """
+    identifier = f"{owner}/{repo}"
+
     # Step 1: total stars
     repo_url = f"https://api.github.com/repos/{identifier}"
     repo_data = await fetch_json(repo_url, provider=PROVIDER)
     total_stars = int(repo_data.get("stargazers_count", 0))
     if total_stars == 0:
-        empty_result: dict[str, Any] = {
+        return {
             "points": [],
             "current_stars": 0,
             "repo": identifier,
             "ttl": STARGAZER_HISTORY_TTL,
         }
-        cache.set(cache_key, empty_result, STARGAZER_HISTORY_TTL)
-        return empty_result
 
     # Step 2: compute total pages (clamped at GitHub's deep-pagination cap)
     total_pages = max(1, math.ceil(total_stars / _STARGAZER_PAGE_SIZE))
     effective_pages = min(total_pages, _STARGAZER_PAGE_CAP)
 
-    # Single-page case: repo has ≤ 30 stars. The "first starred_at of the page"
+    # Single-page case: repo has ≤ 100 stars. The "first starred_at of the page"
     # sampling trick would otherwise collapse to a single aggregated point plus
     # a duplicate-date "now" point, producing a zero time-range polyline. Use
     # each stargazer's own timestamp instead — the whole page fits in one call.
@@ -210,14 +400,12 @@ async def fetch_stargazer_history(
             for idx, entry in enumerate(page_payload):
                 if isinstance(entry, dict) and entry.get("starred_at"):
                     single_page_points.append({"date": entry["starred_at"], "count": idx + 1})
-        single_page_result: dict[str, Any] = {
+        return {
             "points": single_page_points,
             "current_stars": total_stars,
             "repo": identifier,
             "ttl": STARGAZER_HISTORY_TTL,
         }
-        cache.set(cache_key, single_page_result, STARGAZER_HISTORY_TTL)
-        return single_page_result
 
     # Cap the sample count at the number of reachable pages.
     sample_count = min(sample_pages, effective_pages)
@@ -264,14 +452,12 @@ async def fetch_stargazer_history(
         points.append({"date": datetime.now(UTC).isoformat(), "count": total_stars})
     points.sort(key=lambda p: p["date"])
 
-    result: dict[str, Any] = {
+    return {
         "points": points,
         "current_stars": total_stars,
         "repo": identifier,
         "ttl": STARGAZER_HISTORY_TTL,
     }
-    cache.set(cache_key, result, STARGAZER_HISTORY_TTL)
-    return result
 
 
 # ── Session 2A+2B: contribution calendar scraping ──────────────────────────