Add repowatch: GitHub repository activity watcher and analyzer

Co-Authored-By: Claude Opus 4.5 <[e-mail]>

repowatch/PLAN.md

···
+# Repowatch GitHub Sync Implementation Plan
+
+This document outlines the implementation plan for adding GitHub GraphQL query support to repowatch, enabling it to fetch repository activity data and store it in the same format as ruminant's `data/gh/` directory structure.
+
+## Overview
+
+The goal is to implement a `repowatch sync` command that:
+1. Queries GitHub's GraphQL API for repository activity (issues, PRs, discussions)
+2. Queries GitHub's REST API for releases
+3. Filters data by ISO week
+4. Saves results in the ruminant JSON format
+
+## Reference Implementation Analysis
+
+Based on analysis of the Python ruminant codebase, the key implementation patterns are:
+
+### GraphQL Queries
+
+**Issues and PRs Query** - Fetches both in a single query with cursor-based pagination:
+```graphql
+query($owner: String!, $name: String!, $issuesAfter: String, $prsAfter: String) {
+  repository(owner: $owner, name: $name) {
+    issues(first: 25, after: $issuesAfter, orderBy: {field: UPDATED_AT, direction: DESC}) {
+      pageInfo { hasNextPage, endCursor }
+      nodes {
+        number, title, url, createdAt, updatedAt, closedAt, bodyText, state
+        author { login }
+        labels(first: 20) { nodes { name } }
+        comments(first: 10, orderBy: {field: UPDATED_AT, direction: DESC}) {
+          totalCount
+          nodes { author { login }, bodyText, createdAt, updatedAt }
+        }
+        timelineItems(first: 100, itemTypes: [ISSUE_COMMENT, LABELED_EVENT, UNLABELED_EVENT, CLOSED_EVENT, REOPENED_EVENT]) {
+          nodes {
+            __typename
+            ... on IssueComment { createdAt }
+            ... on LabeledEvent { createdAt }
+            ... on UnlabeledEvent { createdAt }
+            ... on ClosedEvent { createdAt }
+            ... on ReopenedEvent { createdAt }
+          }
+        }
+      }
+    }
+    pullRequests(first: 25, after: $prsAfter, orderBy: {field: UPDATED_AT, direction: DESC}) {
+      pageInfo { hasNextPage, endCursor }
+      nodes {
+        number, title, url, createdAt, updatedAt, closedAt, mergedAt, bodyText, state
+        additions, deletions, changedFiles, mergeable, isDraft
+        author { login }
+        labels(first: 20) { nodes { name } }
+        comments(first: 10, orderBy: {field: UPDATED_AT, direction: DESC}) {
+          totalCount
+          nodes { author { login }, bodyText, createdAt, updatedAt }
+        }
+        timelineItems(first: 100, itemTypes: [PULL_REQUEST_COMMIT, PULL_REQUEST_REVIEW, ISSUE_COMMENT, CLOSED_EVENT, REOPENED_EVENT, MERGED_EVENT]) {
+          nodes {
+            __typename
+            ... on PullRequestCommit { commit { committedDate } }
+            ... on PullRequestReview { createdAt }
+            ... on IssueComment { createdAt }
+            ... on ClosedEvent { createdAt }
+            ... on ReopenedEvent { createdAt }
+            ... on MergedEvent { createdAt }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Discussions Query** - Single-page fetch (no pagination):
+```graphql
+query($owner: String!, $name: String!) {
+  repository(owner: $owner, name: $name) {
+    discussions(first: 100, orderBy: {field: UPDATED_AT, direction: DESC}) {
+      nodes {
+        number, title, url, updatedAt, bodyText
+        author { login }
+        category { name }
+        comments { totalCount }
+        answerChosenAt
+      }
+    }
+  }
+}
+```
+
+### Pagination Strategy
+
+- Cursor-based pagination with `first: 25` items per page
+- Independent cursors for issues (`issuesAfter`) and PRs (`prsAfter`)
+- Safety limits: max 20 pages, early termination if no activity in 5 pages
+- Cursor change detection to prevent infinite loops
+
+### Authentication
+
+- Bearer token in `Authorization` header
+- Token sources (priority order):
+  1. Config file (`.ruminant-keys.toml` or our `config.toml`)
+  2. `GITHUB_TOKEN` environment variable
+
+### Rate Limiting
+
+- Monitor `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers
+- Exponential backoff: 1s, 2s, 4s delays on retryable errors
+- Max 3 retry attempts
+- HTTP 502/503/504 are retryable; HTTP 403 is not
+
+### Week Filtering
+
+Items included if ANY of:
+- Created during target week
+- Updated during target week
+- Timeline events during target week
+
+---
+
+## Implementation Plan
+
+### Phase 1: Core Types and GraphQL Module
+
+#### 1.1 GraphQL Types (`lib/graphql_types.mli`)
+
+```ocaml
+(** GraphQL response types for GitHub API *)
+
+module PageInfo : sig
+  type t
+  val has_next_page : t -> bool
+  val end_cursor : t -> string option
+end
+
+module Author : sig
+  type t
+  val login : t -> string  (* "ghost" if null *)
+end
+
+module Label : sig
+  type t
+  val name : t -> string
+end
+
+module Comment : sig
+  type t
+  val author : t -> Author.t
+  val body_text : t -> string
+  val created_at : t -> string
+  val updated_at : t -> string
+end
+
+module TimelineItem : sig
+  type t =
+    | Issue_comment of { created_at : string }
+    | Labeled_event of { created_at : string }
+    | Unlabeled_event of { created_at : string }
+    | Closed_event of { created_at : string }
+    | Reopened_event of { created_at : string }
+    | Pr_commit of { committed_date : string }
+    | Pr_review of { created_at : string }
+    | Merged_event of { created_at : string }
+    | Unknown
+end
+
+module Issue_node : sig
+  type t
+  val number : t -> int
+  val title : t -> string
+  val url : t -> string
+  val created_at : t -> string
+  val updated_at : t -> string
+  val closed_at : t -> string option
+  val body_text : t -> string
+  val state : t -> string
+  val author : t -> Author.t
+  val labels : t -> Label.t list
+  val comments : t -> Comment.t list
+  val timeline_items : t -> TimelineItem.t list
+end
+
+module Pr_node : sig
+  type t
+  (* Issue fields plus: *)
+  val merged_at : t -> string option
+  val additions : t -> int
+  val deletions : t -> int
+  val changed_files : t -> int
+  val mergeable : t -> string
+  val is_draft : t -> bool
+  (* ... other accessors ... *)
+end
+
+module Issues_connection : sig
+  type t
+  val page_info : t -> PageInfo.t
+  val nodes : t -> Issue_node.t list
+end
+
+module Prs_connection : sig
+  type t
+  val page_info : t -> PageInfo.t
+  val nodes : t -> Pr_node.t list
+end
+
+module Discussion_node : sig
+  type t
+  val number : t -> int
+  val title : t -> string
+  val url : t -> string
+  val updated_at : t -> string
+  val body_text : t -> string
+  val author : t -> Author.t
+  val category : t -> string
+  val comments_count : t -> int
+  val answered : t -> bool
+end
+
+module Repository_response : sig
+  type t
+  val issues : t -> Issues_connection.t
+  val pull_requests : t -> Prs_connection.t
+end
+
+module Discussions_response : sig
+  type t
+  val discussions : t -> Discussion_node.t list
+end
+```
+
+#### 1.2 GraphQL Codecs (`lib/graphql_codec.ml`)
+
+Jsont codecs for decoding GraphQL responses:
+
+```ocaml
+(* Example structure *)
+let page_info_jsont = ...
+let author_jsont = ...
+let label_jsont = ...
+let comment_jsont = ...
+let timeline_item_jsont = ...
+let issue_node_jsont = ...
+let pr_node_jsont = ...
+let issues_connection_jsont = ...
+let prs_connection_jsont = ...
+let repository_response_jsont = ...
+let discussion_node_jsont = ...
+let discussions_response_jsont = ...
+```
+
+#### 1.3 GraphQL Query Builder (`lib/graphql.mli`)
+
+```ocaml
+(** GraphQL query construction and execution *)
+
+type query_variables = {
+  owner : string;
+  name : string;
+  issues_after : string option;
+  prs_after : string option;
+}
+
+val issues_prs_query : string
+(** The GraphQL query string for fetching issues and PRs *)
+
+val discussions_query : string
+(** The GraphQL query string for fetching discussions *)
+
+val build_request_body : query:string -> variables:query_variables -> string
+(** Build JSON request body for GraphQL endpoint *)
+```
+
+### Phase 2: GitHub Client Module
+
+#### 2.1 Client Types (`lib/github.mli`)
+
+```ocaml
+(** GitHub API client *)
+
+type t
+(** GitHub API client with authentication and rate limiting *)
+
+type error =
+  | Rate_limited of { reset_at : float }
+  | Unauthorized
+  | Forbidden
+  | Not_found
+  | Server_error of int
+  | Network_error of string
+  | Parse_error of string
+
+val create :
+  sw:Eio.Switch.t ->
+  env:< clock: _ Eio.Time.clock; net: _ Eio.Net.t; .. > ->
+  token:string ->
+  t
+(** Create a GitHub client with authentication *)
+
+val create_from_env :
+  sw:Eio.Switch.t ->
+  env:< clock: _ Eio.Time.clock; net: _ Eio.Net.t; .. > ->
+  (t, string) result
+(** Create client using GITHUB_TOKEN environment variable *)
+
+(** {1 GraphQL API} *)
+
+val graphql :
+  t ->
+  query:string ->
+  variables:(string * Jsont.Json.t) list ->
+  (Jsont.Json.t, error) result
+(** Execute a GraphQL query *)
+
+(** {1 REST API} *)
+
+val get_releases :
+  t ->
+  owner:string ->
+  repo:string ->
+  page:int ->
+  (Jsont.Json.t, error) result
+(** Fetch releases using REST API *)
+
+val get_user :
+  t ->
+  username:string ->
+  (Jsont.Json.t, error) result
+(** Fetch user profile *)
+
+(** {1 Rate Limit Info} *)
+
+val rate_limit_remaining : t -> int option
+(** Current rate limit remaining (if known) *)
+
+val rate_limit_reset : t -> float option
+(** Rate limit reset time as Unix timestamp (if known) *)
+```
+
+#### 2.2 Client Implementation (`lib/github.ml`)
+
+Key implementation details:
+
+```ocaml
+(* Rate limit tracking *)
+type rate_limit = {
+  mutable remaining : int option;
+  mutable reset_at : float option;
+}
+
+(* Retry logic with exponential backoff *)
+let with_retry ~max_attempts ~clock f =
+  let rec loop attempt =
+    match f () with
+    | Ok _ as result -> result
+    | Error (Server_error code) when code >= 500 && attempt < max_attempts ->
+        let delay = Float.pow 2.0 (Float.of_int attempt) in
+        Eio.Time.sleep clock delay;
+        loop (attempt + 1)
+    | Error _ as err -> err
+  in
+  loop 0
+
+(* GraphQL endpoint *)
+let graphql_endpoint = "https://api.github.com/graphql"
+
+(* REST API base *)
+let rest_base = "https://api.github.com"
+
+(* Execute GraphQL query *)
+let graphql t ~query ~variables =
+  let body = Graphql.build_request_body ~query ~variables in
+  with_retry ~max_attempts:3 ~clock:t.clock (fun () ->
+    let resp = Requests.post t.session graphql_endpoint
+      ~headers:(Requests.Headers.empty
+        |> Requests.Headers.add "Content-Type" "application/json")
+      ~body:(Requests.Body.string body) in
+    update_rate_limits t resp;
+    match Requests.Response.status_code resp with
+    | 200 -> parse_graphql_response resp
+    | 401 -> Error Unauthorized
+    | 403 -> check_rate_limit_or_forbidden t resp
+    | 404 -> Error Not_found
+    | code when code >= 500 -> Error (Server_error code)
+    | code -> Error (Server_error code))
+```
+
+### Phase 3: Week-Based Filtering
+
+#### 3.1 Week Utilities (`lib/week.mli`)
+
+```ocaml
+(** ISO week calculations and date filtering *)
+
+type t
+(** An ISO week (year, week number) *)
+
+val of_date : year:int -> month:int -> day:int -> t
+(** Get the ISO week containing the given date *)
+
+val current : clock:_ Eio.Time.clock -> t
+(** Get the current ISO week *)
+
+val of_year_week : year:int -> week:int -> t
+(** Create from year and week number (1-53) *)
+
+val year : t -> int
+val week : t -> int
+
+val start_date : t -> string
+(** Monday of the week in ISO 8601 format (YYYY-MM-DD) *)
+
+val end_date : t -> string
+(** Sunday of the week in ISO 8601 format (YYYY-MM-DD) *)
+
+val contains_timestamp : t -> string -> bool
+(** Check if an ISO 8601 timestamp falls within this week *)
+
+val prev : t -> t
+(** Previous week *)
+
+val next : t -> t
+(** Next week *)
+
+val range : from:t -> to_:t -> t list
+(** Generate list of weeks in range (inclusive) *)
+```
+
+#### 3.2 Activity Filtering (`lib/filter.mli`)
+
+```ocaml
+(** Filter GitHub data by week *)
+
+val issue_active_in_week :
+  week:Week.t ->
+  Graphql_types.Issue_node.t ->
+  bool
+(** Check if issue has activity in the given week *)
+
+val pr_active_in_week :
+  week:Week.t ->
+  Graphql_types.Pr_node.t ->
+  bool
+(** Check if PR has activity in the given week *)
+
+val discussion_active_in_week :
+  week:Week.t ->
+  Graphql_types.Discussion_node.t ->
+  bool
+(** Check if discussion has activity in the given week *)
+
+val is_good_first_issue :
+  Graphql_types.Issue_node.t ->
+  bool
+(** Check if issue has good-first-issue labels *)
+```
+
+### Phase 4: Data Transformation
+
+#### 4.1 Transform Module (`lib/transform.mli`)
+
+```ocaml
+(** Transform GraphQL responses to repowatch types *)
+
+val issue_of_node : Graphql_types.Issue_node.t -> Types.Issue.t
+(** Convert GraphQL issue node to Issue.t *)
+
+val pr_of_node : Graphql_types.Pr_node.t -> Types.Pr.t
+(** Convert GraphQL PR node to Pr.t *)
+
+val discussion_of_node : Graphql_types.Discussion_node.t -> Types.Discussion.t
+(** Convert GraphQL discussion node to Discussion.t *)
+
+val release_of_json : Jsont.Json.t -> Types.Release.t option
+(** Convert REST API release JSON to Release.t *)
+
+val format_comment : author:string -> body:string -> string
+(** Format comment as "@author: body" *)
+```
+
+### Phase 5: Sync Engine
+
+#### 5.1 Sync Types (`lib/sync.mli`)
+
+```ocaml
+(** Repository sync engine *)
+
+type progress = {
+  phase : [ `Issues | `Prs | `Discussions | `Releases | `Users ];
+  current : int;
+  total : int option;
+}
+
+type sync_result = {
+  week_data : Types.Week_data.t;
+  issues_fetched : int;
+  prs_fetched : int;
+  pages_fetched : int;
+  rate_limit_remaining : int option;
+}
+
+val sync_week :
+  client:Github.t ->
+  owner:string ->
+  repo:string ->
+  week:Week.t ->
+  ?on_progress:(progress -> unit) ->
+  unit ->
+  (sync_result, Github.error) result
+(** Sync a single week of repository data *)
+
+val sync_range :
+  client:Github.t ->
+  owner:string ->
+  repo:string ->
+  from_week:Week.t ->
+  to_week:Week.t ->
+  ?on_progress:(progress -> unit) ->
+  unit ->
+  (sync_result list, Github.error) result
+(** Sync a range of weeks *)
+```
+
+#### 5.2 Sync Implementation (`lib/sync.ml`)
+
+Key implementation patterns:
+
+```ocaml
+(* Pagination state *)
+type pagination_state = {
+  mutable issues_cursor : string option;
+  mutable prs_cursor : string option;
+  mutable issues_done : bool;
+  mutable prs_done : bool;
+  mutable pages_without_activity : int;
+}
+
+(* Sync issues and PRs with pagination *)
+let sync_issues_prs ~client ~owner ~repo ~week =
+  let state = {
+    issues_cursor = None;
+    prs_cursor = None;
+    issues_done = false;
+    prs_done = false;
+    pages_without_activity = 0;
+  } in
+  let issues = ref [] in
+  let prs = ref [] in
+  let max_pages = 20 in
+  let early_exit_threshold = 5 in
+
+  let rec loop page_count =
+    if page_count >= max_pages then Ok ()
+    else if state.issues_done && state.prs_done then Ok ()
+    else if state.pages_without_activity >= early_exit_threshold then Ok ()
+    else begin
+      let variables = Graphql.{
+        owner;
+        name = repo;
+        issues_after = state.issues_cursor;
+        prs_after = state.prs_cursor;
+      } in
+      match Github.graphql client
+              ~query:Graphql.issues_prs_query
+              ~variables:(Graphql.variables_to_json variables) with
+      | Error e -> Error e
+      | Ok response ->
+          let repo_data = Graphql_codec.decode_repository_response response in
+          (* Process issues *)
+          let new_issues = process_issues ~week repo_data.issues in
+          (* Process PRs *)
+          let new_prs = process_prs ~week repo_data.pull_requests in
+          (* Update pagination state *)
+          update_pagination_state state repo_data;
+          (* Track activity *)
+          if List.is_empty new_issues && List.is_empty new_prs then
+            state.pages_without_activity <- state.pages_without_activity + 1
+          else
+            state.pages_without_activity <- 0;
+          (* Accumulate results *)
+          issues := new_issues @ !issues;
+          prs := new_prs @ !prs;
+          loop (page_count + 1)
+    end
+  in
+  match loop 0 with
+  | Ok () -> Ok (!issues, !prs)
+  | Error e -> Error e
+```
+
+### Phase 6: Storage Module
+
+#### 6.1 Storage Interface (`lib/storage.mli`)
+
+```ocaml
+(** Persistent storage for sync results *)
+
+val data_dir : fs:Eio.Fs.dir_ty Eio.Path.t -> owner:string -> repo:string ->
+  Eio.Fs.dir_ty Eio.Path.t
+(** Get directory for repository data: {base}/gh/{owner}/{repo}/ *)
+
+val week_file : week:Week.t -> string
+(** Get filename for week: week-{WW}-{YYYY}.json *)
+
+val save_week :
+  fs:Eio.Fs.dir_ty Eio.Path.t ->
+  base_dir:string ->
+  owner:string ->
+  repo:string ->
+  week:Week.t ->
+  data:Types.Week_data.t ->
+  unit
+(** Save week data to file, creating directories as needed *)
+
+val load_week :
+  fs:Eio.Fs.dir_ty Eio.Path.t ->
+  base_dir:string ->
+  owner:string ->
+  repo:string ->
+  week:Week.t ->
+  Types.Week_data.t option
+(** Load existing week data if present *)
+
+val list_cached_weeks :
+  fs:Eio.Fs.dir_ty Eio.Path.t ->
+  base_dir:string ->
+  owner:string ->
+  repo:string ->
+  Week.t list
+(** List all cached weeks for a repository *)
+```
+
+### Phase 7: User Extraction
+
+#### 7.1 User Module (`lib/users.mli`)
+
+```ocaml
+(** Extract and validate GitHub usernames *)
+
+val extract_from_week_data : Types.Week_data.t -> string list
+(** Extract all unique usernames from week data *)
+
+val extract_mentions : string -> string list
+(** Extract @mentions from text *)
+
+val is_valid_username : string -> bool
+(** Check if string is a valid GitHub username (not a common word, etc.) *)
+
+val excluded_words : string list
+(** List of words to exclude from username detection *)
+```
+
+Implementation notes:
+- Username regex: `@([a-zA-Z][a-zA-Z0-9-]{0,38})`
+- Exclude common words, programming terms, OCaml-specific terms
+- Exclude hex strings (commit SHA fragments)
+- Minimum 2 characters
+
+### Phase 8: CLI Commands
+
+#### 8.1 Sync Command (`bin/main.ml` additions)
+
+```ocaml
+(* sync command *)
+let sync_cmd =
+  let doc = "Sync repository data from GitHub" in
+  let info = Cmd.info "sync" ~doc in
+  let term =
+    let open Term.Syntax in
+    let+ xdg = xdg_term
+    and+ repos = Arg.(value & pos_all string [] & info [] ~docv:"REPO"
+        ~doc:"Repositories to sync (owner/repo format)")
+    and+ week = Arg.(value & opt (some int) None &
+        info ["w"; "week"] ~docv:"WEEK" ~doc:"ISO week number (default: current)")
+    and+ year = Arg.(value & opt (some int) None &
+        info ["y"; "year"] ~docv:"YEAR" ~doc:"Year (default: current)")
+    and+ weeks_back = Arg.(value & opt int 1 &
+        info ["n"; "weeks"] ~docv:"N" ~doc:"Number of weeks to sync (default: 1)")
+    and+ output_dir = Arg.(value & opt string "data/gh" &
+        info ["o"; "output"] ~docv:"DIR" ~doc:"Output directory (default: data/gh)")
+    and+ force = Arg.(value & flag &
+        info ["f"; "force"] ~doc:"Force re-sync even if cached")
+    and+ log_level = Logs_cli.level () in
+    (* Implementation *)
+    ...
+  in
+  Cmd.v info term
+```
+
+#### 8.2 Additional Commands
+
+```ocaml
+(* repos command - list configured repositories *)
+let repos_cmd = ...
+
+(* status command - show sync status *)
+let status_cmd = ...
+
+(* users command - fetch user profiles *)
+let users_cmd = ...
+```
+
+---
+
+## File Structure
+
+```
+repowatch/
+├── lib/
+│   ├── dune                    # Updated dependencies
+│   ├── repowatch.ml           # Updated exports
+│   ├── types.mli/ml           # (existing)
+│   ├── codec.mli/ml           # (existing)
+│   ├── loader.mli/ml          # (existing)
+│   ├── config.mli/ml          # (existing, extended for GitHub token)
+│   ├── printer.mli/ml         # (existing)
+│   ├── week.mli/ml            # NEW: ISO week utilities
+│   ├── graphql_types.mli/ml   # NEW: GraphQL response types
+│   ├── graphql_codec.mli/ml   # NEW: Jsont codecs for GraphQL
+│   ├── graphql.mli/ml         # NEW: Query building
+│   ├── github.mli/ml          # NEW: GitHub API client
+│   ├── filter.mli/ml          # NEW: Week-based filtering
+│   ├── transform.mli/ml       # NEW: Data transformation
+│   ├── sync.mli/ml            # NEW: Sync engine
+│   ├── storage.mli/ml         # NEW: File storage
+│   └── users.mli/ml           # NEW: Username extraction
+├── bin/
+│   ├── dune                   # (existing)
+│   └── main.ml               # Updated with sync commands
+└── test/
+    ├── dune                   # Updated
+    ├── test_codec.ml         # (existing)
+    ├── test_week.ml          # NEW
+    ├── test_graphql.ml       # NEW
+    ├── test_filter.ml        # NEW
+    └── test_users.ml         # NEW
+```
+
+---
+
+## Dependencies
+
+Update `lib/dune`:
+```dune
+(library
+ (name repowatch)
+ (public_name repowatch)
+ (libraries
+  jsont jsont.bytesrw
+  tomlt tomlt.bytesrw
+  eio
+  xdge
+  requests
+  logs
+  fmt
+  ptime ptime.clock.os))
+```
+
+---
+
+## Implementation Order
+
+### Week 1: Core Infrastructure
+1. `week.mli/ml` - ISO week calculations
+2. `graphql_types.mli/ml` - Response types
+3. `graphql_codec.mli/ml` - JSON parsing
+4. `graphql.mli/ml` - Query building
+5. Tests for above
+
+### Week 2: GitHub Client
+1. `github.mli/ml` - HTTP client with auth and rate limiting
+2. `filter.mli/ml` - Week-based filtering
+3. `transform.mli/ml` - Data transformation
+4. Tests for above
+
+### Week 3: Sync Engine
+1. `sync.mli/ml` - Pagination and sync logic
+2. `storage.mli/ml` - File persistence
+3. `users.mli/ml` - Username extraction
+4. Tests for above
+
+### Week 4: CLI Integration
+1. Update `main.ml` with sync command
+2. Update `config.mli/ml` for GitHub token
+3. End-to-end testing
+4. Documentation
+
+---
+
+## Testing Strategy
+
+### Unit Tests
+- Week calculations (edge cases: year boundaries, week 53)
+- GraphQL response parsing
+- Week filtering logic
+- Username extraction and validation
+- Data transformation
+
+### Integration Tests
+- Mock GitHub API responses
+- Full sync workflow with fixtures
+- Error handling (rate limits, auth failures)
+
+### End-to-End Tests
+- Sync real repository (with live API, opt-in)
+- Validate output matches ruminant format
+
+---
+
+## Error Handling
+
+All sync operations should:
+1. Return `Result` types for recoverable errors
+2. Log warnings for partial failures (e.g., some pages fail)
+3. Preserve partial results when possible
+4. Provide clear error messages with context
+
+Rate limit handling:
+- Detect via response headers
+- Calculate wait time from reset timestamp
+- Optionally wait and retry (with user confirmation for long waits)
+
+---
+
+## Configuration Extension
+
+Add to `config.toml`:
+```toml
+[github]
+token_env = "GITHUB_TOKEN"  # Or explicit token
+
+[sync]
+output_dir = "data/gh"
+max_pages = 20
+early_exit_pages = 5
+concurrent_repos = 2
+
+[[repositories]]
+owner = "ocaml"
+repo = "ocaml"
+group = "core"
+
+[[repositories]]
+owner = "ocaml"
+repo = "dune"
+group = "tooling"
+```
+
+---
+
+## Future Enhancements
+
+1. **Incremental Sync**: Only fetch new data since last sync
+2. **Parallel Repo Sync**: Sync multiple repos concurrently (respecting rate limits)
+3. **User Profile Caching**: Fetch and cache user profiles
+4. **Webhook Support**: React to GitHub webhooks for real-time updates
+5. **Export Formats**: Generate reports, RSS feeds, etc.

repowatch/bin/dune

···
+(executable
+ (name main)
+ (public_name repowatch)
+ (package repowatch)
+ (libraries repowatch cmdliner logs.fmt logs.cli fmt.tty fmt.cli eio_main))

repowatch/bin/main.ml

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+open Cmdliner
+
+let () =
+  Fmt.set_style_renderer Fmt.stdout `Ansi_tty;
+  Fmt.set_style_renderer Fmt.stderr `Ansi_tty;
+
+  Eio_main.run @@ fun env ->
+  Eio.Switch.run @@ fun sw ->
+  let fs = env#fs in
+
+  (* Helper to load data from either a file or directory *)
+  let load_path path =
+    let path_obj = Eio.Path.(fs / path) in
+    match Eio.Path.kind ~follow:true path_obj with
+    | `Regular_file -> (
+        match Repowatch.Loader.load_file fs path with
+        | Ok data -> ([data], [])
+        | Error e -> ([], [(path, e)]))
+    | `Directory ->
+        Repowatch.Loader.load_directory_partial fs path
+    | _ -> ([], [(path, "Not a file or directory")])
+  in
+
+  let xdg_term = Xdge.Cmd.term "repowatch" fs ~dirs:[ `Config; `Cache ] () in
+
+  let info =
+    Cmd.info "repowatch" ~version:"0.1.0"
+      ~doc:"GitHub repository activity watcher and analyzer"
+      ~man:
+        [
+          `S Manpage.s_description;
+          `P
+            "Repowatch parses and analyzes GitHub repository activity data \
+             from JSON files in the ruminant format. It provides commands for \
+             viewing issues, PRs, discussions, and releases with statistics \
+             and filtering capabilities.";
+          `S Manpage.s_commands;
+          `P "Use $(b,repowatch COMMAND --help) for detailed help on each command.";
+        ]
+  in
+
+  (* Path argument *)
+  let path_arg =
+    let doc = "Path to a JSON file or directory containing JSON files." in
+    Arg.(required & pos 0 (some string) None & info [] ~docv:"PATH" ~doc)
+  in
+
+  let path_arg_opt =
+    let doc = "Path to a JSON file or directory containing JSON files." in
+    Arg.(value & pos 0 (some string) None & info [] ~docv:"PATH" ~doc)
+  in
+
+  (* Parse command *)
+  let parse_cmd =
+    let doc = "Parse and display GitHub activity data." in
+    let info = Cmd.info "parse" ~doc in
+    let term =
+      let open Term.Syntax in
+      let+ (_xdg, _) = xdg_term
+      and+ path = path_arg
+      and+ short =
+        Arg.(value & flag & info [ "s"; "short" ] ~doc:"Show short output")
+      and+ log_level = Logs_cli.level () in
+      Logs.set_reporter (Logs_fmt.reporter ~app:Fmt.stdout ~dst:Fmt.stderr ());
+      Logs.set_level log_level;
+
+      let path_obj = Eio.Path.(fs / path) in
+      match Eio.Path.kind ~follow:true path_obj with
+      | `Regular_file -> (
+          match Repowatch.Loader.load_file fs path with
+          | Ok data ->
+              if short then Fmt.pr "%a@." Repowatch.Printer.pp_week_summary data
+              else Fmt.pr "%a@." Repowatch.Printer.pp_week_data data
+          | Error e -> Fmt.epr "Error: %s@." e)
+      | `Directory -> (
+          match Repowatch.Loader.load_directory fs path with
+          | Ok data_list ->
+              List.iter
+                (fun data ->
+                  if short then
+                    Fmt.pr "%a@.@." Repowatch.Printer.pp_week_summary data
+                  else Fmt.pr "%a@.---@.@." Repowatch.Printer.pp_week_data data)
+                data_list
+          | Error errors ->
+              List.iter
+                (fun (file, e) -> Fmt.epr "Error in %s: %s@." file e)
+                errors)
+      | _ -> Fmt.epr "Error: %s is not a file or directory@." path
+    in
+    Cmd.v info term
+  in
+
+  (* Stats command *)
+  let stats_cmd =
+    let doc = "Show aggregate statistics for activity data." in
+    let info = Cmd.info "stats" ~doc in
+    let term =
+      let open Term.Syntax in
+      let+ (_xdg, _) = xdg_term
+      and+ path = path_arg
+      and+ compact =
+        Arg.(value & flag & info [ "c"; "compact" ] ~doc:"Show compact output")
+      and+ log_level = Logs_cli.level () in
+      Logs.set_reporter (Logs_fmt.reporter ~app:Fmt.stdout ~dst:Fmt.stderr ());
+      Logs.set_level log_level;
+
+      let path_obj = Eio.Path.(fs / path) in
+      match Eio.Path.kind ~follow:true path_obj with
+      | `Regular_file -> (
+          match Repowatch.Loader.load_file fs path with
+          | Ok data ->
+              let stats = Repowatch.Printer.compute_stats data in
+              if compact then
+                Fmt.pr "%a@." Repowatch.Printer.pp_stats_compact stats
+              else Fmt.pr "%a@." Repowatch.Printer.pp_stats stats
+          | Error e -> Fmt.epr "Error: %s@." e)
+      | `Directory ->
+          let data_list, errors = Repowatch.Loader.load_directory_partial fs path in
+          if errors <> [] then
+            List.iter
+              (fun (file, e) -> Logs.warn (fun m -> m "Error in %s: %s" file e))
+              errors;
+          let stats_list = List.map Repowatch.Printer.compute_stats data_list in
+          let stats = Repowatch.Printer.aggregate_stats stats_list in
+          Fmt.pr "Aggregated statistics from %d files:@.@." (List.length data_list);
+          if compact then Fmt.pr "%a@." Repowatch.Printer.pp_stats_compact stats
+          else Fmt.pr "%a@." Repowatch.Printer.pp_stats stats
+      | _ -> Fmt.epr "Error: %s is not a file or directory@." path
+    in
+    Cmd.v info term
+  in
+
+  (* Validate command *)
+  let validate_cmd =
+    let doc = "Validate JSON files against the expected schema." in
+    let info = Cmd.info "validate" ~doc in
+    let term =
+      let open Term.Syntax in
+      let+ (_xdg, _) = xdg_term
+      and+ path = path_arg
+      and+ log_level = Logs_cli.level () in
+      Logs.set_reporter (Logs_fmt.reporter ~app:Fmt.stdout ~dst:Fmt.stderr ());
+      Logs.set_level log_level;
+
+      let path_obj = Eio.Path.(fs / path) in
+      match Eio.Path.kind ~follow:true path_obj with
+      | `Regular_file -> (
+          match Repowatch.Loader.load_file fs path with
+          | Ok _ -> Fmt.pr "OK: %s@." path
+          | Error e -> Fmt.pr "FAIL: %s - %s@." path e)
+      | `Directory ->
+          let files = Repowatch.Loader.find_json_files fs path in
+          let ok_count = ref 0 in
+          let fail_count = ref 0 in
+          List.iter
+            (fun file ->
+              match Repowatch.Loader.load_file fs file with
+              | Ok _ ->
+                  incr ok_count;
+                  Fmt.pr "OK: %s@." file
+              | Error e ->
+                  incr fail_count;
+                  Fmt.pr "FAIL: %s - %s@." file e)
+            files;
+          Fmt.pr "@.Validation complete: %d OK, %d FAILED@." !ok_count !fail_count
+      | _ -> Fmt.epr "Error: %s is not a file or directory@." path
+    in
+    Cmd.v info term
+  in
+
+  (* List command - list repositories in a data directory *)
+  let list_cmd =
+    let doc = "List repositories in a ruminant data directory." in
+    let info = Cmd.info "list" ~doc in
+    let term =
+      let open Term.Syntax in
+      let+ (_xdg, _) = xdg_term
+      and+ path = path_arg_opt
+      and+ log_level = Logs_cli.level () in
+      Logs.set_reporter (Logs_fmt.reporter ~app:Fmt.stdout ~dst:Fmt.stderr ());
+      Logs.set_level log_level;
+
+      let data_dir = Option.value path ~default:"." in
+      let repos = Repowatch.Loader.find_repos fs data_dir in
+      if repos = [] then Fmt.pr "No repositories found in %s@." data_dir
+      else (
+        Fmt.pr "Repositories in %s:@." data_dir;
+        List.iter (fun r -> Fmt.pr "  %s@." r) repos)
+    in
+    Cmd.v info term
+  in
+
+  (* Issues command - list issues *)
+  let issues_cmd =
+    let doc = "List issues from activity data." in
+    let info = Cmd.info "issues" ~doc in
+    let term =
+      let open Term.Syntax in
+      let+ (_xdg, _) = xdg_term
+      and+ path = path_arg
+      and+ state =
+        Arg.(
+          value
+          & opt (some string) None
+          & info [ "state" ] ~docv:"STATE" ~doc:"Filter by state (open/closed)")
+      and+ log_level = Logs_cli.level () in
+      Logs.set_reporter (Logs_fmt.reporter ~app:Fmt.stdout ~dst:Fmt.stderr ());
+      Logs.set_level log_level;
+
+      let data_list, errors = load_path path in
+      if errors <> [] then
+        List.iter
+          (fun (file, e) -> Logs.warn (fun m -> m "Error in %s: %s" file e))
+          errors;
+
+      let all_issues =
+        List.concat_map Repowatch.Types.Week_data.issues data_list
+      in
+      let filtered =
+        match state with
+        | Some s ->
+            List.filter (fun i -> Repowatch.Types.Issue.state i = s) all_issues
+        | None -> all_issues
+      in
+      Fmt.pr "Issues (%d):@." (List.length filtered);
+      List.iter
+        (fun i -> Fmt.pr "  %a@." Repowatch.Printer.pp_issue_short i)
+        filtered
+    in
+    Cmd.v info term
+  in
+
+  (* PRs command - list pull requests *)
+  let prs_cmd =
+    let doc = "List pull requests from activity data." in
+    let info = Cmd.info "prs" ~doc in
+    let term =
+      let open Term.Syntax in
+      let+ (_xdg, _) = xdg_term
+      and+ path = path_arg
+      and+ state =
+        Arg.(
+          value
+          & opt (some string) None
+          & info [ "state" ] ~docv:"STATE"
+              ~doc:"Filter by state (open/closed/merged)")
+      and+ draft =
+        Arg.(value & flag & info [ "draft" ] ~doc:"Show only draft PRs")
+      and+ log_level = Logs_cli.level () in
+      Logs.set_reporter (Logs_fmt.reporter ~app:Fmt.stdout ~dst:Fmt.stderr ());
+      Logs.set_level log_level;
+
+      let data_list, errors = load_path path in
+      if errors <> [] then
+        List.iter
+          (fun (file, e) -> Logs.warn (fun m -> m "Error in %s: %s" file e))
+          errors;
+
+      let all_prs = List.concat_map Repowatch.Types.Week_data.prs data_list in
+      let filtered =
+        all_prs
+        |> (fun prs ->
+             match state with
+             | Some "merged" ->
+                 List.filter
+                   (fun p -> Option.is_some (Repowatch.Types.Pr.merged_at p))
+                   prs
+             | Some s ->
+                 List.filter (fun p -> Repowatch.Types.Pr.state p = s) prs
+             | None -> prs)
+        |> fun prs ->
+        if draft then List.filter Repowatch.Types.Pr.draft prs else prs
+      in
+      Fmt.pr "Pull Requests (%d):@." (List.length filtered);
+      List.iter
+        (fun p -> Fmt.pr "  %a@." Repowatch.Printer.pp_pr_short p)
+        filtered
+    in
+    Cmd.v info term
+  in
+
+  (* Sync command - sync repository data from GitHub *)
+  let sync_cmd =
+    let doc = "Sync repository data from GitHub." in
+    let info =
+      Cmd.info "sync" ~doc
+        ~man:
+          [
+            `S Manpage.s_description;
+            `P
+              "Sync repository activity data from GitHub's GraphQL and REST \
+               APIs. Data is filtered by ISO week and saved in the ruminant \
+               JSON format.";
+            `S Manpage.s_examples;
+            `P "Sync current week for all configured repositories:";
+            `Pre "  repowatch sync";
+            `P "Sync a specific repository:";
+            `Pre "  repowatch sync ocaml/ocaml";
+            `P "Sync a specific week:";
+            `Pre "  repowatch sync -w 3 -y 2024 ocaml/ocaml";
+            `P "Update existing data (for daily cron jobs):";
+            `Pre "  repowatch sync --update";
+            `P
+              "The --update flag merges new activity with existing cached \
+               data, making it ideal for keeping the current week up-to-date \
+               via daily cron jobs.";
+          ]
+    in
+    let term =
+      let open Term.Syntax in
+      let+ (_xdg, _) = xdg_term
+      and+ repos =
+        Arg.(
+          value & pos_all string []
+          & info [] ~docv:"REPO" ~doc:"Repositories to sync (owner/repo format)")
+      and+ week =
+        Arg.(
+          value
+          & opt (some int) None
+          & info [ "w"; "week" ] ~docv:"WEEK"
+              ~doc:"ISO week number (default: current)")
+      and+ year =
+        Arg.(
+          value
+          & opt (some int) None
+          & info [ "y"; "year" ] ~docv:"YEAR" ~doc:"Year (default: current)")
+      and+ weeks_back =
+        Arg.(
+          value & opt int 1
+          & info [ "n"; "weeks" ] ~docv:"N"
+              ~doc:"Number of weeks to sync (default: 1)")
+      and+ output_dir =
+        Arg.(
+          value
+          & opt (some string) None
+          & info [ "o"; "output" ] ~docv:"DIR"
+              ~doc:"Output directory (default: from config or data/gh)")
+      and+ force =
+        Arg.(value & flag & info [ "f"; "force" ] ~doc:"Force re-sync even if cached")
+      and+ update =
+        Arg.(
+          value & flag
+          & info [ "u"; "update" ]
+              ~doc:
+                "Incremental update mode. Merge new data with existing cached \
+                 data. Useful for daily cron jobs to update the current week.")
+      and+ log_level = Logs_cli.level () in
+      Logs.set_reporter (Logs_fmt.reporter ~app:Fmt.stdout ~dst:Fmt.stderr ());
+      Logs.set_level log_level;
+
+      (* Load config *)
+      let config =
+        match Repowatch.Config.load_xdg_opt ~fs with
+        | Some c -> c
+        | None -> Repowatch.Config.default
+      in
+
+      (* Determine output directory *)
+      let out_dir =
+        match output_dir with
+        | Some d -> d
+        | None -> Repowatch.Config.Sync.output_dir (Repowatch.Config.sync config)
+      in
+
+      (* Get GitHub token *)
+      let github_config = Repowatch.Config.github config in
+      match Repowatch.Config.Github.get_token github_config with
+      | None ->
+          Fmt.epr
+            "Error: GitHub token not found. Set %s environment variable.@."
+            (Repowatch.Config.Github.token_env github_config)
+      | Some token -> (
+          (* Create GitHub client *)
+          let client = Repowatch.Github.create ~sw ~env ~token in
+
+          (* Determine which repositories to sync *)
+          let repos_to_sync =
+            if repos = [] then
+              (* Use configured repositories *)
+              let configured = Repowatch.Config.repositories config in
+              if configured = [] then (
+                Fmt.epr
+                  "Error: No repositories specified and none configured.@.";
+                Fmt.epr "Use: repowatch sync owner/repo@.";
+                Fmt.epr "Or add repositories to your config file.@.";
+                [])
+              else
+                List.map
+                  (fun r ->
+                    ( Repowatch.Config.Repository.owner r,
+                      Repowatch.Config.Repository.repo r ))
+                  configured
+            else
+              (* Parse command-line repos *)
+              List.filter_map
+                (fun s ->
+                  match String.split_on_char '/' s with
+                  | [ owner; repo ] -> Some (owner, repo)
+                  | _ ->
+                      Fmt.epr "Warning: Invalid repository format: %s@." s;
+                      None)
+                repos
+          in
+
+          if repos_to_sync = [] then ()
+          else
+            (* Determine week(s) to sync *)
+            let current_week = Repowatch.Week.current ~clock:env#clock in
+            let target_week =
+              match (week, year) with
+              | Some w, Some y -> Repowatch.Week.of_year_week ~year:y ~week:w
+              | Some w, None ->
+                  Repowatch.Week.of_year_week
+                    ~year:(Repowatch.Week.year current_week)
+                    ~week:w
+              | None, Some y ->
+                  Repowatch.Week.of_year_week ~year:y
+                    ~week:(Repowatch.Week.week current_week)
+              | None, None -> current_week
+            in
+
+            let weeks_to_sync =
+              if weeks_back <= 1 then [ target_week ]
+              else
+                let rec build_list acc n w =
+                  if n <= 0 then List.rev acc
+                  else build_list (w :: acc) (n - 1) (Repowatch.Week.prev w)
+                in
+                build_list [] weeks_back target_week
+            in
+
+            (* Sync each repository *)
+            List.iter
+              (fun (owner, repo) ->
+                Fmt.pr "Syncing %s/%s...@." owner repo;
+                List.iter
+                  (fun week ->
+                    let week_str = Repowatch.Week.to_string week in
+                    (* Check if already cached *)
+                    let cached =
+                      if force then None
+                      else
+                        Repowatch.Storage.load_week ~fs ~base_dir:out_dir ~owner
+                          ~repo ~week
+                    in
+                    (* Determine sync mode based on flags *)
+                    let should_sync, existing_data =
+                      match (cached, force, update) with
+                      | Some data, false, true ->
+                          (* Update mode: merge with existing *)
+                          (true, Some data)
+                      | Some _, false, false ->
+                          (* Cached and not forcing: skip *)
+                          (false, None)
+                      | _, true, _ ->
+                          (* Force: full re-sync *)
+                          (true, None)
+                      | None, _, true ->
+                          (* Update mode but no existing: full sync *)
+                          (true, None)
+                      | None, _, false ->
+                          (* No cache: full sync *)
+                          (true, None)
+                    in
+                    if not should_sync then
+                      Fmt.pr "  %s: cached (use -f to re-sync)@." week_str
+                    else (
+                      let mode_str =
+                        if Option.is_some existing_data then "updating"
+                        else "syncing"
+                      in
+                      Fmt.pr "  %s: %s...@." week_str mode_str;
+                      let on_progress p =
+                        let phase_str =
+                          match p.Repowatch.Sync.phase with
+                          | `Issues_prs -> "issues/PRs"
+                          | `Discussions -> "discussions"
+                          | `Releases -> "releases"
+                          | `Users -> "users"
+                        in
+                        Fmt.pr "    %s page %d@." phase_str p.current
+                      in
+                      let result =
+                        Repowatch.Sync.sync_week_incremental ~client ~owner
+                          ~repo ~week ~existing:existing_data ~on_progress ()
+                      in
+                      match result with
+                      | Error e ->
+                          Fmt.epr "    Error: %a@." Repowatch.Github.pp_error e
+                      | Ok result ->
+                          (* Save the data *)
+                          Repowatch.Storage.save_week ~fs ~base_dir:out_dir
+                            ~owner ~repo ~week ~data:result.week_data;
+                          Fmt.pr
+                            "    Done: %d issues, %d PRs, %d pages fetched@."
+                            result.issues_fetched result.prs_fetched
+                            result.pages_fetched;
+                          (match result.rate_limit_remaining with
+                          | Some remaining ->
+                              Fmt.pr "    Rate limit remaining: %d@." remaining
+                          | None -> ())))
+                  weeks_to_sync)
+              repos_to_sync)
+    in
+    Cmd.v info term
+  in
+
+  (* Repos command - list configured repositories *)
+  let repos_cmd =
+    let doc = "List configured repositories." in
+    let info = Cmd.info "repos" ~doc in
+    let term =
+      let open Term.Syntax in
+      let+ (_xdg, _) = xdg_term and+ log_level = Logs_cli.level () in
+      Logs.set_reporter (Logs_fmt.reporter ~app:Fmt.stdout ~dst:Fmt.stderr ());
+      Logs.set_level log_level;
+
+      match Repowatch.Config.load_xdg_opt ~fs with
+      | None -> Fmt.pr "No configuration file found.@."
+      | Some config ->
+          let repos = Repowatch.Config.repositories config in
+          if repos = [] then Fmt.pr "No repositories configured.@."
+          else (
+            Fmt.pr "Configured repositories:@.";
+            List.iter
+              (fun r ->
+                let group =
+                  match Repowatch.Config.Repository.group r with
+                  | Some g -> Printf.sprintf " [%s]" g
+                  | None -> ""
+                in
+                Fmt.pr "  %s%s@." (Repowatch.Config.Repository.full_name r) group)
+              repos)
+    in
+    Cmd.v info term
+  in
+
+  (* Status command - show sync status for configured repositories *)
+  let status_cmd =
+    let doc = "Show sync status for repositories." in
+    let info = Cmd.info "status" ~doc in
+    let term =
+      let open Term.Syntax in
+      let+ (_xdg, _) = xdg_term
+      and+ output_dir =
+        Arg.(
+          value
+          & opt (some string) None
+          & info [ "o"; "output" ] ~docv:"DIR" ~doc:"Data directory")
+      and+ log_level = Logs_cli.level () in
+      Logs.set_reporter (Logs_fmt.reporter ~app:Fmt.stdout ~dst:Fmt.stderr ());
+      Logs.set_level log_level;
+
+      let config =
+        match Repowatch.Config.load_xdg_opt ~fs with
+        | Some c -> c
+        | None -> Repowatch.Config.default
+      in
+
+      let out_dir =
+        match output_dir with
+        | Some d -> d
+        | None -> Repowatch.Config.Sync.output_dir (Repowatch.Config.sync config)
+      in
+
+      let repos = Repowatch.Config.repositories config in
+      if repos = [] then Fmt.pr "No repositories configured.@."
+      else (
+        let current_week = Repowatch.Week.current ~clock:env#clock in
+        Fmt.pr "Sync status (current week: %s):@.@."
+          (Repowatch.Week.to_string current_week);
+        List.iter
+          (fun r ->
+            let owner = Repowatch.Config.Repository.owner r in
+            let repo = Repowatch.Config.Repository.repo r in
+            let cached_weeks =
+              Repowatch.Storage.list_cached_weeks ~fs ~base_dir:out_dir ~owner
+                ~repo
+            in
+            let has_current =
+              List.exists (Repowatch.Week.equal current_week) cached_weeks
+            in
+            let status =
+              if has_current then "up-to-date" else "needs sync"
+            in
+            Fmt.pr "  %s/%s: %s (%d weeks cached)@." owner repo status
+              (List.length cached_weeks))
+          repos)
+    in
+    Cmd.v info term
+  in
+
+  (* Init command - create a default config file *)
+  let init_cmd =
+    let doc = "Initialize a new configuration file." in
+    let info = Cmd.info "init" ~doc in
+    let term =
+      let open Term.Syntax in
+      let+ (xdg, _) = xdg_term
+      and+ force =
+        Arg.(
+          value & flag
+          & info [ "f"; "force" ] ~doc:"Overwrite existing config")
+      and+ log_level = Logs_cli.level () in
+      Logs.set_reporter (Logs_fmt.reporter ~app:Fmt.stdout ~dst:Fmt.stderr ());
+      Logs.set_level log_level;
+
+      let config_dir = Xdge.config_dir xdg in
+      Repowatch.Storage.ensure_dir config_dir;
+      let config_path = Eio.Path.(config_dir / "config.toml") in
+
+      let exists =
+        try
+          ignore (Eio.Path.load config_path);
+          true
+        with _ -> false
+      in
+
+      if exists && not force then
+        Fmt.pr "Config file already exists: %a@.Use -f to overwrite.@."
+          Eio.Path.pp config_path
+      else (
+        let default_content =
+          {|# Repowatch configuration file
+
+[github]
+token_env = "GITHUB_TOKEN"
+
+[sync]
+output_dir = "data/gh"
+max_pages = 20
+early_exit_pages = 5
+
+[cache]
+ttl_hours = 24
+
+# Add repositories to watch:
+# [[repositories]]
+# owner = "ocaml"
+# repo = "ocaml"
+# group = "core"
+#
+# [[repositories]]
+# owner = "ocaml"
+# repo = "dune"
+# group = "tooling"
+|}
+        in
+        Eio.Path.save ~create:(`Or_truncate 0o644) config_path default_content;
+        Fmt.pr "Created config file: %a@." Eio.Path.pp config_path)
+    in
+    Cmd.v info term
+  in
+
+  let default_term =
+    let open Term.Syntax in
+    let+ _ = xdg_term and+ _ = Logs_cli.level () in
+    `Help (`Pager, None)
+  in
+  let default_term = Term.ret default_term in
+
+  let cmd =
+    Cmd.group info ~default:default_term
+      [
+        parse_cmd;
+        stats_cmd;
+        validate_cmd;
+        list_cmd;
+        issues_cmd;
+        prs_cmd;
+        sync_cmd;
+        repos_cmd;
+        status_cmd;
+        init_cmd;
+      ]
+  in
+
+  exit (Cmd.eval cmd)

repowatch/dune-project

···
+(lang dune 3.20)
+
+(name repowatch)
+
+(generate_opam_files true)
+
+(source
+ (github avsm/repowatch))
+
+(authors "Anil Madhavapeddy <[e-mail]>")
+
+(maintainers "Anil Madhavapeddy <[e-mail]>")
+
+(license ISC)
+
+(documentation "https://avsm.github.io/repowatch")
+
+(package
+ (name repowatch)
+ (synopsis "GitHub repository activity watcher and analyzer")
+ (description
+  "Repowatch parses and analyzes GitHub repository activity data from JSON files. It provides a CLI for viewing issues, PRs, discussions, and releases with statistics and filtering capabilities.")
+ (depends
+  (ocaml (>= 5.2.0))
+  (dune (>= 3.20))
+  (eio_main (>= 1.2))
+  (jsont (>= 0.1.0))
+  (tomlt (>= 0.1.0))
+  (xdge (>= 0.1.0))
+  (cmdliner (>= 1.3.0))
+  (logs (>= 0.7.0))
+  (fmt (>= 0.9.0))
+  (ptime (>= 1.0.0))
+  (odoc :with-doc)))

repowatch/lib/codec.ml

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+(* Codec for nullable strings - null decodes to None *)
+let nullable_string = Jsont.option Jsont.string
+
+let metadata =
+  let kind = "Metadata" in
+  Jsont.Object.map ~kind
+    (fun repo year week week_start week_end cached_at ->
+      Types.Metadata.make ~repo ~year ~week ~week_start ~week_end ~cached_at)
+  |> Jsont.Object.mem "repo" Jsont.string ~enc:Types.Metadata.repo
+  |> Jsont.Object.mem "year" Jsont.int ~enc:Types.Metadata.year
+  |> Jsont.Object.mem "week" Jsont.int ~enc:Types.Metadata.week
+  |> Jsont.Object.mem "week_start" Jsont.string ~enc:Types.Metadata.week_start
+  |> Jsont.Object.mem "week_end" Jsont.string ~enc:Types.Metadata.week_end
+  |> Jsont.Object.mem "cached_at" Jsont.string ~enc:Types.Metadata.cached_at
+  |> Jsont.Object.finish
+
+let issue =
+  let kind = "Issue" in
+  Jsont.Object.map ~kind
+    (fun id title url user created_at updated_at closed_at body labels state
+         comments ->
+      Types.Issue.make ~id ~title ~url ~user ~created_at ~updated_at ~closed_at
+        ~body ~labels ~state ~comments)
+  |> Jsont.Object.mem "id" Jsont.int ~enc:Types.Issue.id
+  |> Jsont.Object.mem "title" Jsont.string ~enc:Types.Issue.title
+  |> Jsont.Object.mem "url" Jsont.string ~enc:Types.Issue.url
+  |> Jsont.Object.mem "user" Jsont.string ~enc:Types.Issue.user
+  |> Jsont.Object.mem "created_at" Jsont.string ~enc:Types.Issue.created_at
+  |> Jsont.Object.mem "updated_at" Jsont.string ~enc:Types.Issue.updated_at
+  |> Jsont.Object.mem "closed_at" nullable_string ~dec_absent:None
+       ~enc:Types.Issue.closed_at
+  |> Jsont.Object.mem "body" Jsont.string ~enc:Types.Issue.body
+  |> Jsont.Object.mem "labels" (Jsont.list Jsont.string) ~enc:Types.Issue.labels
+  |> Jsont.Object.mem "state" Jsont.string ~enc:Types.Issue.state
+  |> Jsont.Object.mem "comments" (Jsont.list Jsont.string)
+       ~enc:Types.Issue.comments
+  |> Jsont.Object.finish
+
+let pr =
+  let kind = "PR" in
+  Jsont.Object.map ~kind
+    (fun id title url user created_at updated_at closed_at merged_at body
+         labels state comments additions deletions changed_files mergeable draft ->
+      Types.Pr.make ~id ~title ~url ~user ~created_at ~updated_at ~closed_at
+        ~merged_at ~body ~labels ~state ~comments ~additions ~deletions
+        ~changed_files ~mergeable ~draft)
+  |> Jsont.Object.mem "id" Jsont.int ~enc:Types.Pr.id
+  |> Jsont.Object.mem "title" Jsont.string ~enc:Types.Pr.title
+  |> Jsont.Object.mem "url" Jsont.string ~enc:Types.Pr.url
+  |> Jsont.Object.mem "user" Jsont.string ~enc:Types.Pr.user
+  |> Jsont.Object.mem "created_at" Jsont.string ~enc:Types.Pr.created_at
+  |> Jsont.Object.mem "updated_at" Jsont.string ~enc:Types.Pr.updated_at
+  |> Jsont.Object.mem "closed_at" nullable_string ~dec_absent:None
+       ~enc:Types.Pr.closed_at
+  |> Jsont.Object.mem "merged_at" nullable_string ~dec_absent:None
+       ~enc:Types.Pr.merged_at
+  |> Jsont.Object.mem "body" Jsont.string ~enc:Types.Pr.body
+  |> Jsont.Object.mem "labels" (Jsont.list Jsont.string) ~enc:Types.Pr.labels
+  |> Jsont.Object.mem "state" Jsont.string ~enc:Types.Pr.state
+  |> Jsont.Object.mem "comments" (Jsont.list Jsont.string) ~enc:Types.Pr.comments
+  |> Jsont.Object.mem "additions" Jsont.int ~enc:Types.Pr.additions
+  |> Jsont.Object.mem "deletions" Jsont.int ~enc:Types.Pr.deletions
+  |> Jsont.Object.mem "changed_files" Jsont.int ~enc:Types.Pr.changed_files
+  |> Jsont.Object.mem "mergeable" Jsont.string ~enc:Types.Pr.mergeable
+  |> Jsont.Object.mem "draft" Jsont.bool ~enc:Types.Pr.draft
+  |> Jsont.Object.finish
+
+let discussion =
+  let kind = "Discussion" in
+  Jsont.Object.map ~kind
+    (fun id title url user updated_at body category comments answered ->
+      Types.Discussion.make ~id ~title ~url ~user ~updated_at ~body ~category
+        ~comments ~answered)
+  |> Jsont.Object.mem "id" Jsont.int ~enc:Types.Discussion.id
+  |> Jsont.Object.mem "title" Jsont.string ~enc:Types.Discussion.title
+  |> Jsont.Object.mem "url" Jsont.string ~enc:Types.Discussion.url
+  |> Jsont.Object.mem "user" Jsont.string ~enc:Types.Discussion.user
+  |> Jsont.Object.mem "updated_at" Jsont.string ~enc:Types.Discussion.updated_at
+  |> Jsont.Object.mem "body" Jsont.string ~enc:Types.Discussion.body
+  |> Jsont.Object.mem "category" Jsont.string ~enc:Types.Discussion.category
+  |> Jsont.Object.mem "comments" Jsont.int ~enc:Types.Discussion.comments
+  |> Jsont.Object.mem "answered" Jsont.bool ~enc:Types.Discussion.answered
+  |> Jsont.Object.finish
+
+let asset =
+  let kind = "Asset" in
+  Jsont.Object.map ~kind
+    (fun name download_count size ->
+      Types.Asset.make ~name ~download_count ~size)
+  |> Jsont.Object.mem "name" Jsont.string ~enc:Types.Asset.name
+  |> Jsont.Object.mem "download_count" Jsont.int ~enc:Types.Asset.download_count
+  |> Jsont.Object.mem "size" Jsont.int ~enc:Types.Asset.size
+  |> Jsont.Object.finish
+
+let release =
+  let kind = "Release" in
+  Jsont.Object.map ~kind
+    (fun tag_name name published_at author html_url body prerelease draft
+         assets ->
+      Types.Release.make ~tag_name ~name ~published_at ~author ~html_url ~body
+        ~prerelease ~draft ~assets)
+  |> Jsont.Object.mem "tag_name" Jsont.string ~enc:Types.Release.tag_name
+  |> Jsont.Object.mem "name" Jsont.string ~enc:Types.Release.name
+  |> Jsont.Object.mem "published_at" Jsont.string ~enc:Types.Release.published_at
+  |> Jsont.Object.mem "author" Jsont.string ~enc:Types.Release.author
+  |> Jsont.Object.mem "html_url" Jsont.string ~enc:Types.Release.html_url
+  |> Jsont.Object.mem "body" Jsont.string ~enc:Types.Release.body
+  |> Jsont.Object.mem "prerelease" Jsont.bool ~enc:Types.Release.prerelease
+  |> Jsont.Object.mem "draft" Jsont.bool ~enc:Types.Release.draft
+  |> Jsont.Object.mem "assets" (Jsont.list asset) ~enc:Types.Release.assets
+  |> Jsont.Object.finish
+
+let week_data =
+  let kind = "Week_data" in
+  Jsont.Object.map ~kind
+    (fun metadata issues prs good_first_issues discussions releases users ->
+      Types.Week_data.make ~metadata ~issues ~prs ~good_first_issues
+        ~discussions ~releases ~users)
+  |> Jsont.Object.mem "metadata" metadata ~enc:Types.Week_data.metadata
+  |> Jsont.Object.mem "issues" (Jsont.list issue) ~enc:Types.Week_data.issues
+  |> Jsont.Object.mem "prs" (Jsont.list pr) ~enc:Types.Week_data.prs
+  |> Jsont.Object.mem "good_first_issues" (Jsont.list issue)
+       ~enc:Types.Week_data.good_first_issues
+  |> Jsont.Object.mem "discussions" (Jsont.list discussion)
+       ~enc:Types.Week_data.discussions
+  |> Jsont.Object.mem "releases" (Jsont.list release)
+       ~enc:Types.Week_data.releases
+  |> Jsont.Object.mem "users" (Jsont.list Jsont.string) ~dec_absent:[]
+       ~enc:Types.Week_data.users
+  |> Jsont.Object.finish
+
+let decode_string s =
+  Jsont_bytesrw.decode_string week_data s
+
+let decode_file fs path =
+  let content = Eio.Path.(load (fs / path)) in
+  decode_string content
+
+let encode_string data =
+  match Jsont_bytesrw.encode_string week_data data with
+  | Ok s -> s
+  | Error e -> failwith ("encode failed: " ^ e)

repowatch/lib/codec.mli

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+(** JSON codecs for GitHub activity data types.
+
+    This module provides jsont codecs for encoding and decoding the types
+    defined in {!Types}. *)
+
+(** {1 Codecs} *)
+
+val metadata : Types.Metadata.t Jsont.t
+(** Codec for {!Types.Metadata.t}. *)
+
+val issue : Types.Issue.t Jsont.t
+(** Codec for {!Types.Issue.t}. *)
+
+val pr : Types.Pr.t Jsont.t
+(** Codec for {!Types.Pr.t}. *)
+
+val discussion : Types.Discussion.t Jsont.t
+(** Codec for {!Types.Discussion.t}. *)
+
+val asset : Types.Asset.t Jsont.t
+(** Codec for {!Types.Asset.t}. *)
+
+val release : Types.Release.t Jsont.t
+(** Codec for {!Types.Release.t}. *)
+
+val week_data : Types.Week_data.t Jsont.t
+(** Codec for {!Types.Week_data.t}. *)
+
+(** {1 Decoding} *)
+
+val decode_string : string -> (Types.Week_data.t, string) result
+(** Decode a JSON string to week data. *)
+
+val decode_file :
+  Eio.Fs.dir_ty Eio.Path.t -> string -> (Types.Week_data.t, string) result
+(** Decode a JSON file to week data. *)
+
+(** {1 Encoding} *)
+
+val encode_string : Types.Week_data.t -> string
+(** Encode week data to a JSON string. *)

repowatch/lib/config.ml

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+module Repository = struct
+  type t = {
+    owner : string;
+    repo : string;
+    group : string option;
+  }
+
+  let make ~owner ~repo ?group () = { owner; repo; group }
+  let owner t = t.owner
+  let repo t = t.repo
+  let group t = t.group
+  let full_name t = Printf.sprintf "%s/%s" t.owner t.repo
+
+  let codec =
+    Tomlt.(
+      Table.(
+        obj (fun owner repo group -> { owner; repo; group })
+        |> mem "owner" string ~enc:(fun t -> t.owner)
+        |> mem "repo" string ~enc:(fun t -> t.repo)
+        |> opt_mem "group" string ~enc:(fun t -> t.group)
+        |> finish))
+end
+
+module Github = struct
+  type t = { token_env : string }
+
+  let default_token_env = "GITHUB_TOKEN"
+  let make ?(token_env = default_token_env) () = { token_env }
+  let token_env t = t.token_env
+  let get_token t = Sys.getenv_opt t.token_env
+
+  let codec =
+    Tomlt.(
+      Table.(
+        obj (fun token_env -> { token_env })
+        |> mem "token_env" string ~dec_absent:default_token_env
+             ~enc:(fun t -> t.token_env)
+        |> finish))
+end
+
+module Cache = struct
+  type t = {
+    directory : string option;
+    ttl_hours : int;
+  }
+
+  let default_ttl_hours = 24
+  let make ?directory ?(ttl_hours = default_ttl_hours) () = { directory; ttl_hours }
+  let directory t = t.directory
+  let ttl_hours t = t.ttl_hours
+
+  let codec =
+    Tomlt.(
+      Table.(
+        obj (fun directory ttl_hours -> { directory; ttl_hours })
+        |> opt_mem "directory" string ~enc:(fun t -> t.directory)
+        |> mem "ttl_hours" int ~dec_absent:default_ttl_hours
+             ~enc:(fun t -> t.ttl_hours)
+        |> finish))
+end
+
+module Sync = struct
+  type t = {
+    output_dir : string;
+    max_pages : int;
+    early_exit_pages : int;
+  }
+
+  let default_output_dir = "data/gh"
+  let default_max_pages = 20
+  let default_early_exit_pages = 5
+
+  let make ?(output_dir = default_output_dir) ?(max_pages = default_max_pages)
+      ?(early_exit_pages = default_early_exit_pages) () =
+    { output_dir; max_pages; early_exit_pages }
+
+  let output_dir t = t.output_dir
+  let max_pages t = t.max_pages
+  let early_exit_pages t = t.early_exit_pages
+
+  let codec =
+    Tomlt.(
+      Table.(
+        obj (fun output_dir max_pages early_exit_pages ->
+            { output_dir; max_pages; early_exit_pages })
+        |> mem "output_dir" string ~dec_absent:default_output_dir
+             ~enc:(fun t -> t.output_dir)
+        |> mem "max_pages" int ~dec_absent:default_max_pages
+             ~enc:(fun t -> t.max_pages)
+        |> mem "early_exit_pages" int ~dec_absent:default_early_exit_pages
+             ~enc:(fun t -> t.early_exit_pages)
+        |> finish))
+end
+
+type t = {
+  github : Github.t;
+  repositories : Repository.t list;
+  cache : Cache.t;
+  sync : Sync.t;
+}
+
+let default_github = Github.make ()
+let default_cache = Cache.make ()
+let default_sync = Sync.make ()
+
+let make ?(github = default_github) ?(repositories = []) ?(cache = default_cache)
+    ?(sync = default_sync) () =
+  { github; repositories; cache; sync }
+
+let default = make ()
+let github t = t.github
+let repositories t = t.repositories
+let cache t = t.cache
+let sync t = t.sync
+
+let codec =
+  Tomlt.(
+    Table.(
+      obj (fun github repositories cache sync ->
+          { github; repositories; cache; sync })
+      |> mem "github" Github.codec ~dec_absent:default_github
+           ~enc:(fun t -> t.github)
+      |> mem "repositories" (list Repository.codec) ~dec_absent:[]
+           ~enc:(fun t -> t.repositories)
+      |> mem "cache" Cache.codec ~dec_absent:default_cache
+           ~enc:(fun t -> t.cache)
+      |> mem "sync" Sync.codec ~dec_absent:default_sync ~enc:(fun t -> t.sync)
+      |> finish))
+
+let load_from_path path =
+  let content = Eio.Path.load path in
+  match Tomlt_bytesrw.decode_string codec content with
+  | Ok config -> config
+  | Error e -> failwith (Tomlt.Error.to_string e)
+
+let load_from_path_opt path =
+  try
+    let content = Eio.Path.load path in
+    match Tomlt_bytesrw.decode_string codec content with
+    | Ok config -> Some config
+    | Error _ -> None
+  with _ -> None
+
+let xdg ~fs = Xdge.create fs "repowatch"
+
+let load_xdg ~fs =
+  let xdg = xdg ~fs in
+  match Xdge.find_config_file xdg "config.toml" with
+  | Some path -> load_from_path path
+  | None -> failwith "No repowatch configuration found in XDG config directories"
+
+let load_xdg_opt ~fs =
+  let xdg = xdg ~fs in
+  match Xdge.find_config_file xdg "config.toml" with
+  | Some path -> load_from_path_opt path
+  | None -> None
+
+let config_dir ~fs =
+  let xdg = xdg ~fs in
+  Xdge.config_dir xdg

repowatch/lib/config.mli

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+(** Configuration file handling for repowatch.
+
+    Configuration is stored in TOML format. The default location follows
+    XDG conventions: [$XDG_CONFIG_HOME/repowatch/config.toml]. *)
+
+(** {1 Repository Configuration} *)
+
+module Repository : sig
+  type t
+  (** A repository to watch. *)
+
+  val make : owner:string -> repo:string -> ?group:string -> unit -> t
+  (** Create a repository configuration. *)
+
+  val owner : t -> string
+  (** Repository owner. *)
+
+  val repo : t -> string
+  (** Repository name. *)
+
+  val group : t -> string option
+  (** Optional group name for categorization. *)
+
+  val full_name : t -> string
+  (** Full name in "owner/repo" format. *)
+end
+
+(** {1 GitHub Configuration} *)
+
+module Github : sig
+  type t
+  (** GitHub API configuration. *)
+
+  val make : ?token_env:string -> unit -> t
+  (** Create GitHub configuration.
+
+      @param token_env Name of environment variable containing the token
+                       (default: "GITHUB_TOKEN") *)
+
+  val token_env : t -> string
+  (** Environment variable name for the GitHub token. *)
+
+  val get_token : t -> string option
+  (** Attempt to read the token from the environment. *)
+end
+
+(** {1 Cache Configuration} *)
+
+module Cache : sig
+  type t
+  (** Cache configuration. *)
+
+  val make : ?directory:string -> ?ttl_hours:int -> unit -> t
+  (** Create cache configuration.
+
+      @param directory Cache directory path (default: uses XDG cache dir)
+      @param ttl_hours Hours before cached data is considered stale (default: 24) *)
+
+  val directory : t -> string option
+  (** Cache directory path. None means use XDG default. *)
+
+  val ttl_hours : t -> int
+  (** Time-to-live in hours for cached data. *)
+end
+
+(** {1 Sync Configuration} *)
+
+module Sync : sig
+  type t
+  (** Sync operation configuration. *)
+
+  val make :
+    ?output_dir:string ->
+    ?max_pages:int ->
+    ?early_exit_pages:int ->
+    unit ->
+    t
+  (** Create sync configuration.
+
+      @param output_dir Output directory for synced data (default: "data/gh")
+      @param max_pages Maximum pages to fetch per query (default: 20)
+      @param early_exit_pages Pages without activity before stopping (default: 5) *)
+
+  val output_dir : t -> string
+  (** Output directory for synced data. *)
+
+  val max_pages : t -> int
+  (** Maximum GraphQL pages to fetch. *)
+
+  val early_exit_pages : t -> int
+  (** Pages without relevant activity before early exit. *)
+end
+
+(** {1 Configuration} *)
+
+type t
+(** Complete repowatch configuration. *)
+
+val make :
+  ?github:Github.t ->
+  ?repositories:Repository.t list ->
+  ?cache:Cache.t ->
+  ?sync:Sync.t ->
+  unit ->
+  t
+(** Create a configuration with optional components. *)
+
+val default : t
+(** Default configuration with no repositories. *)
+
+val github : t -> Github.t
+(** GitHub configuration. *)
+
+val repositories : t -> Repository.t list
+(** List of repositories to watch. *)
+
+val cache : t -> Cache.t
+(** Cache configuration. *)
+
+val sync : t -> Sync.t
+(** Sync configuration. *)
+
+(** {1 Loading and Saving} *)
+
+val codec : t Tomlt.t
+(** TOML codec for configuration. *)
+
+val load_from_path : Eio.Fs.dir_ty Eio.Path.t -> t
+(** Load configuration from a path. Raises on error. *)
+
+val load_from_path_opt : Eio.Fs.dir_ty Eio.Path.t -> t option
+(** Load configuration from a path, returning None on error. *)
+
+val load_xdg : fs:Eio.Fs.dir_ty Eio.Path.t -> t
+(** Load configuration from XDG config directory. Raises if not found. *)
+
+val load_xdg_opt : fs:Eio.Fs.dir_ty Eio.Path.t -> t option
+(** Load configuration from XDG config directory, returning None if not found. *)
+
+val config_dir : fs:Eio.Fs.dir_ty Eio.Path.t -> Eio.Fs.dir_ty Eio.Path.t
+(** Get the XDG configuration directory for repowatch. *)

repowatch/lib/dune

···
+(library
+ (name repowatch)
+ (public_name repowatch)
+ (libraries jsont jsont.bytesrw eio xdge tomlt tomlt.bytesrw logs fmt ptime ptime.clock.os requests unix))

repowatch/lib/filter.ml

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+module G = Graphql_types
+
+let timestamp_in_week week timestamp = Week.contains_timestamp week timestamp
+
+let any_timeline_event_in_week week items =
+  List.exists
+    (fun item ->
+      match G.Timeline_item.created_at item with
+      | Some ts -> timestamp_in_week week ts
+      | None -> false)
+    items
+
+let issue_active_in_week ~week issue =
+  timestamp_in_week week (G.Issue_node.created_at issue)
+  || timestamp_in_week week (G.Issue_node.updated_at issue)
+  || any_timeline_event_in_week week (G.Issue_node.timeline_items issue)
+
+let pr_active_in_week ~week pr =
+  timestamp_in_week week (G.Pr_node.created_at pr)
+  || timestamp_in_week week (G.Pr_node.updated_at pr)
+  || (match G.Pr_node.merged_at pr with
+     | Some ts -> timestamp_in_week week ts
+     | None -> false)
+  || any_timeline_event_in_week week (G.Pr_node.timeline_items pr)
+
+let discussion_active_in_week ~week discussion =
+  timestamp_in_week week (G.Discussion_node.updated_at discussion)
+
+let string_equal_ci a b = String.lowercase_ascii a = String.lowercase_ascii b
+
+let has_label name issue =
+  List.exists
+    (fun label -> string_equal_ci name (G.Label.name label))
+    (G.Issue_node.labels issue)
+
+let has_label_pr name pr =
+  List.exists
+    (fun label -> string_equal_ci name (G.Label.name label))
+    (G.Pr_node.labels pr)
+
+let good_first_issue_labels =
+  [
+    "good first issue";
+    "good-first-issue";
+    "beginner";
+    "beginner-friendly";
+    "easy";
+    "help wanted";
+  ]
+
+let is_good_first_issue issue =
+  List.exists (fun label_name -> has_label label_name issue) good_first_issue_labels

repowatch/lib/filter.mli

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+(** Week-based filtering for GitHub data.
+
+    This module provides functions to filter GitHub issues, PRs, and discussions
+    based on whether they had activity during a specific ISO week. Activity
+    includes creation, updates, and timeline events. *)
+
+(** {1 Activity Checking} *)
+
+val issue_active_in_week : week:Week.t -> Graphql_types.Issue_node.t -> bool
+(** [issue_active_in_week ~week issue] returns [true] if the issue has any
+    activity during the given week.
+
+    Activity is detected if any of:
+    - The issue was created during the week
+    - The issue was updated during the week
+    - Any timeline event occurred during the week *)
+
+val pr_active_in_week : week:Week.t -> Graphql_types.Pr_node.t -> bool
+(** [pr_active_in_week ~week pr] returns [true] if the PR has any
+    activity during the given week.
+
+    Activity is detected if any of:
+    - The PR was created during the week
+    - The PR was updated during the week
+    - The PR was merged during the week
+    - Any timeline event occurred during the week *)
+
+val discussion_active_in_week :
+  week:Week.t -> Graphql_types.Discussion_node.t -> bool
+(** [discussion_active_in_week ~week discussion] returns [true] if the
+    discussion was updated during the given week. *)
+
+(** {1 Label Helpers} *)
+
+val is_good_first_issue : Graphql_types.Issue_node.t -> bool
+(** [is_good_first_issue issue] returns [true] if the issue has a label
+    commonly used to mark issues suitable for newcomers.
+
+    Recognized labels include:
+    - "good first issue"
+    - "good-first-issue"
+    - "beginner"
+    - "beginner-friendly"
+    - "easy"
+    - "help wanted" *)
+
+val has_label : string -> Graphql_types.Issue_node.t -> bool
+(** [has_label name issue] returns [true] if the issue has a label matching
+    the given name (case-insensitive). *)
+
+val has_label_pr : string -> Graphql_types.Pr_node.t -> bool
+(** [has_label_pr name pr] returns [true] if the PR has a label matching
+    the given name (case-insensitive). *)

repowatch/lib/github.ml

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+type error =
+  | Rate_limited of { reset_at : float }
+  | Unauthorized
+  | Forbidden
+  | Not_found
+  | Server_error of int
+  | Network_error of string
+  | Parse_error of string
+
+let pp_error fmt = function
+  | Rate_limited { reset_at } ->
+      Format.fprintf fmt "Rate limited (resets at %f)" reset_at
+  | Unauthorized -> Format.fprintf fmt "Unauthorized (401)"
+  | Forbidden -> Format.fprintf fmt "Forbidden (403)"
+  | Not_found -> Format.fprintf fmt "Not found (404)"
+  | Server_error code -> Format.fprintf fmt "Server error (%d)" code
+  | Network_error msg -> Format.fprintf fmt "Network error: %s" msg
+  | Parse_error msg -> Format.fprintf fmt "Parse error: %s" msg
+
+type rate_limit = {
+  mutable remaining : int option;
+  mutable reset_at : float option;
+}
+
+type t = {
+  session : Requests.t;
+  clock : float Eio.Time.clock_ty Eio.Resource.t;
+  rate_limit : rate_limit;
+}
+
+let graphql_endpoint = "https://api.github.com/graphql"
+let rest_base = "https://api.github.com"
+
+let create ~sw ~env ~token =
+  let session =
+    Requests.create ~sw env
+    |> fun s -> Requests.set_auth s (Requests.Auth.bearer ~token)
+    |> fun s -> Requests.set_default_header s "Accept" "application/json"
+    |> fun s -> Requests.set_default_header s "User-Agent" "repowatch/1.0"
+  in
+  let clock = env#clock in
+  let rate_limit = { remaining = None; reset_at = None } in
+  { session; clock; rate_limit }
+
+let create_from_env ~sw ~env =
+  match Sys.getenv_opt "GITHUB_TOKEN" with
+  | Some token -> Ok (create ~sw ~env ~token)
+  | None -> Error "GITHUB_TOKEN environment variable not set"
+
+let update_rate_limits t headers =
+  (match Requests.Headers.get_string "X-RateLimit-Remaining" headers with
+  | Some s -> (
+      try t.rate_limit.remaining <- Some (int_of_string s) with _ -> ())
+  | None -> ());
+  match Requests.Headers.get_string "X-RateLimit-Reset" headers with
+  | Some s -> (
+      try t.rate_limit.reset_at <- Some (float_of_string s) with _ -> ())
+  | None -> ()
+
+let rate_limit_remaining t = t.rate_limit.remaining
+let rate_limit_reset t = t.rate_limit.reset_at
+
+let handle_response t response =
+  let headers = Requests.Response.headers response in
+  update_rate_limits t headers;
+  let status = Requests.Response.status_code response in
+  match status with
+  | 200 | 201 ->
+      let body = Requests.Response.text response in
+      Ok body
+  | 401 -> Error Unauthorized
+  | 403 ->
+      (* Check if it's rate limiting *)
+      let remaining = t.rate_limit.remaining in
+      let reset_at = t.rate_limit.reset_at in
+      if remaining = Some 0 then
+        Error (Rate_limited { reset_at = Option.value reset_at ~default:0.0 })
+      else Error Forbidden
+  | 404 -> Error Not_found
+  | code when code >= 500 -> Error (Server_error code)
+  | code -> Error (Server_error code)
+
+let with_retry ~clock ~max_attempts f =
+  let rec loop attempt =
+    match f () with
+    | Ok _ as result -> result
+    | Error (Server_error _) when attempt < max_attempts ->
+        let delay = Float.pow 2.0 (Float.of_int attempt) in
+        Eio.Time.sleep clock delay;
+        loop (attempt + 1)
+    | Error _ as err -> err
+  in
+  loop 0
+
+let graphql t ~query ~variables =
+  let body = Graphql.build_request_body ~query ~variables in
+  with_retry ~clock:t.clock ~max_attempts:3 (fun () ->
+      try
+        let response =
+          Requests.post t.session graphql_endpoint
+            ~headers:
+              (Requests.Headers.empty
+              |> Requests.Headers.content_type Requests.Mime.json)
+            ~body:(Requests.Body.of_string Requests.Mime.json body)
+        in
+        handle_response t response
+      with
+      | Eio.Io (Eio.Net.E (Eio.Net.Connection_failure _), _) as exn ->
+          Error (Network_error (Printexc.to_string exn))
+      | exn -> Error (Network_error (Printexc.to_string exn)))
+
+let get_releases t ~owner ~repo ~page =
+  let url =
+    Printf.sprintf "%s/repos/%s/%s/releases?page=%d&per_page=100" rest_base
+      owner repo page
+  in
+  with_retry ~clock:t.clock ~max_attempts:3 (fun () ->
+      try
+        let response = Requests.get t.session url in
+        handle_response t response
+      with exn -> Error (Network_error (Printexc.to_string exn)))
+
+let get_user t ~username =
+  let url = Printf.sprintf "%s/users/%s" rest_base username in
+  with_retry ~clock:t.clock ~max_attempts:3 (fun () ->
+      try
+        let response = Requests.get t.session url in
+        handle_response t response
+      with exn -> Error (Network_error (Printexc.to_string exn)))

repowatch/lib/github.mli

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+(** GitHub API client with authentication and rate limiting.
+
+    This module provides a client for GitHub's GraphQL and REST APIs with
+    automatic rate limit handling and retry logic. *)
+
+(** {1 Types} *)
+
+type t
+(** GitHub API client with authentication and rate limiting. *)
+
+type error =
+  | Rate_limited of { reset_at : float }
+      (** Request was rate limited. [reset_at] is Unix timestamp when
+          the rate limit resets. *)
+  | Unauthorized
+      (** Authentication failed (HTTP 401). *)
+  | Forbidden
+      (** Access forbidden (HTTP 403), not rate limiting. *)
+  | Not_found
+      (** Resource not found (HTTP 404). *)
+  | Server_error of int
+      (** GitHub server error (HTTP 5xx). *)
+  | Network_error of string
+      (** Network-level error. *)
+  | Parse_error of string
+      (** JSON parsing error. *)
+
+val pp_error : Format.formatter -> error -> unit
+(** Pretty-print an error. *)
+
+(** {1 Client Creation} *)
+
+val create :
+  sw:Eio.Switch.t ->
+  env:
+    < clock : float Eio.Time.clock_ty Eio.Resource.t
+    ; net : _ Eio.Net.t
+    ; fs : Eio.Fs.dir_ty Eio.Path.t
+    ; .. > ->
+  token:string ->
+  t
+(** [create ~sw ~env ~token] creates a GitHub client with the given
+    authentication token.
+
+    @param sw Switch for resource management
+    @param env Eio environment with clock, net, and fs capabilities
+    @param token GitHub personal access token or OAuth token *)
+
+val create_from_env :
+  sw:Eio.Switch.t ->
+  env:
+    < clock : float Eio.Time.clock_ty Eio.Resource.t
+    ; net : _ Eio.Net.t
+    ; fs : Eio.Fs.dir_ty Eio.Path.t
+    ; .. > ->
+  (t, string) result
+(** [create_from_env ~sw ~env] creates a client using the [GITHUB_TOKEN]
+    environment variable. Returns [Error msg] if the variable is not set. *)
+
+(** {1 GraphQL API} *)
+
+val graphql :
+  t ->
+  query:string ->
+  variables:Graphql.query_variables ->
+  (string, error) result
+(** [graphql t ~query ~variables] executes a GraphQL query against GitHub's
+    API and returns the raw JSON response body.
+
+    This function automatically:
+    - Retries on server errors with exponential backoff
+    - Handles rate limiting with appropriate delays
+    - Updates internal rate limit tracking *)
+
+(** {1 REST API} *)
+
+val get_releases :
+  t ->
+  owner:string ->
+  repo:string ->
+  page:int ->
+  (string, error) result
+(** [get_releases t ~owner ~repo ~page] fetches releases using the REST API.
+    Returns the raw JSON response body. Page numbering starts at 1. *)
+
+val get_user : t -> username:string -> (string, error) result
+(** [get_user t ~username] fetches a user profile using the REST API.
+    Returns the raw JSON response body. *)
+
+(** {1 Rate Limit Information} *)
+
+val rate_limit_remaining : t -> int option
+(** [rate_limit_remaining t] returns the current rate limit remaining,
+    if known from previous responses. *)
+
+val rate_limit_reset : t -> float option
+(** [rate_limit_reset t] returns the Unix timestamp when the rate limit
+    resets, if known from previous responses. *)

repowatch/lib/graphql.ml

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+type query_variables = {
+  owner : string;
+  name : string;
+  issues_after : string option;
+  prs_after : string option;
+}
+
+let issues_prs_query =
+  {|query($owner: String!, $name: String!, $issuesAfter: String, $prsAfter: String) {
+  repository(owner: $owner, name: $name) {
+    issues(first: 25, after: $issuesAfter, orderBy: {field: UPDATED_AT, direction: DESC}) {
+      pageInfo {
+        hasNextPage
+        endCursor
+      }
+      nodes {
+        number
+        title
+        url
+        createdAt
+        updatedAt
+        closedAt
+        bodyText
+        state
+        author {
+          login
+        }
+        labels(first: 20) {
+          nodes {
+            name
+          }
+        }
+        comments(first: 10, orderBy: {field: UPDATED_AT, direction: DESC}) {
+          totalCount
+          nodes {
+            author {
+              login
+            }
+            bodyText
+            createdAt
+            updatedAt
+          }
+        }
+        timelineItems(first: 100, itemTypes: [ISSUE_COMMENT, LABELED_EVENT, UNLABELED_EVENT, CLOSED_EVENT, REOPENED_EVENT]) {
+          nodes {
+            __typename
+            ... on IssueComment {
+              createdAt
+            }
+            ... on LabeledEvent {
+              createdAt
+            }
+            ... on UnlabeledEvent {
+              createdAt
+            }
+            ... on ClosedEvent {
+              createdAt
+            }
+            ... on ReopenedEvent {
+              createdAt
+            }
+          }
+        }
+      }
+    }
+    pullRequests(first: 25, after: $prsAfter, orderBy: {field: UPDATED_AT, direction: DESC}) {
+      pageInfo {
+        hasNextPage
+        endCursor
+      }
+      nodes {
+        number
+        title
+        url
+        createdAt
+        updatedAt
+        closedAt
+        mergedAt
+        bodyText
+        state
+        additions
+        deletions
+        changedFiles
+        mergeable
+        isDraft
+        author {
+          login
+        }
+        labels(first: 20) {
+          nodes {
+            name
+          }
+        }
+        comments(first: 10, orderBy: {field: UPDATED_AT, direction: DESC}) {
+          totalCount
+          nodes {
+            author {
+              login
+            }
+            bodyText
+            createdAt
+            updatedAt
+          }
+        }
+        timelineItems(first: 100, itemTypes: [PULL_REQUEST_COMMIT, PULL_REQUEST_REVIEW, ISSUE_COMMENT, CLOSED_EVENT, REOPENED_EVENT, MERGED_EVENT]) {
+          nodes {
+            __typename
+            ... on PullRequestCommit {
+              commit {
+                committedDate
+              }
+            }
+            ... on PullRequestReview {
+              createdAt
+            }
+            ... on IssueComment {
+              createdAt
+            }
+            ... on ClosedEvent {
+              createdAt
+            }
+            ... on ReopenedEvent {
+              createdAt
+            }
+            ... on MergedEvent {
+              createdAt
+            }
+          }
+        }
+      }
+    }
+  }
+}|}
+
+let discussions_query =
+  {|query($owner: String!, $name: String!) {
+  repository(owner: $owner, name: $name) {
+    discussions(first: 100, orderBy: {field: UPDATED_AT, direction: DESC}) {
+      nodes {
+        number
+        title
+        url
+        updatedAt
+        bodyText
+        author {
+          login
+        }
+        category {
+          name
+        }
+        comments {
+          totalCount
+        }
+        answerChosenAt
+      }
+    }
+  }
+}|}
+
+(* JSON escape a string *)
+let escape_json_string s =
+  let b = Buffer.create (String.length s * 2) in
+  String.iter
+    (function
+      | '"' -> Buffer.add_string b "\\\""
+      | '\\' -> Buffer.add_string b "\\\\"
+      | '\n' -> Buffer.add_string b "\\n"
+      | '\r' -> Buffer.add_string b "\\r"
+      | '\t' -> Buffer.add_string b "\\t"
+      | c when Char.code c < 32 ->
+          Buffer.add_string b (Printf.sprintf "\\u%04x" (Char.code c))
+      | c -> Buffer.add_char b c)
+    s;
+  Buffer.contents b
+
+let variables_to_json vars =
+  let add_if_some key opt acc =
+    match opt with
+    | Some v -> (key, Jsont.Json.string v) :: acc
+    | None -> acc
+  in
+  [ ("owner", Jsont.Json.string vars.owner); ("name", Jsont.Json.string vars.name) ]
+  |> add_if_some "issuesAfter" vars.issues_after
+  |> add_if_some "prsAfter" vars.prs_after
+
+let build_request_body ~query ~variables =
+  (* Build the JSON manually for efficiency and control *)
+  let vars_json =
+    let parts =
+      let base =
+        [
+          Printf.sprintf "\"owner\": \"%s\"" (escape_json_string variables.owner);
+          Printf.sprintf "\"name\": \"%s\"" (escape_json_string variables.name);
+        ]
+      in
+      let with_issues =
+        match variables.issues_after with
+        | Some cursor ->
+            base
+            @ [ Printf.sprintf "\"issuesAfter\": \"%s\""
+                  (escape_json_string cursor) ]
+        | None -> base
+      in
+      match variables.prs_after with
+      | Some cursor ->
+          with_issues
+          @ [ Printf.sprintf "\"prsAfter\": \"%s\"" (escape_json_string cursor) ]
+      | None -> with_issues
+    in
+    "{" ^ String.concat ", " parts ^ "}"
+  in
+  Printf.sprintf "{\"query\": \"%s\", \"variables\": %s}"
+    (escape_json_string query) vars_json

repowatch/lib/graphql.mli

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+(** GraphQL query construction for GitHub API.
+
+    This module provides the GraphQL query strings and request body building
+    functions for fetching repository data from GitHub's GraphQL API. *)
+
+(** {1 Query Variables} *)
+
+type query_variables = {
+  owner : string;  (** Repository owner (user or organization). *)
+  name : string;  (** Repository name. *)
+  issues_after : string option;  (** Cursor for issues pagination. *)
+  prs_after : string option;  (** Cursor for PRs pagination. *)
+}
+(** Variables for the issues/PRs GraphQL query. *)
+
+(** {1 Query Strings} *)
+
+val issues_prs_query : string
+(** The GraphQL query string for fetching issues and pull requests.
+
+    This query fetches both issues and PRs in a single request with:
+    - Cursor-based pagination (first 25 items per page)
+    - Ordering by UPDATED_AT descending
+    - Author information (handles deleted users)
+    - Labels (first 20)
+    - Recent comments (first 10)
+    - Timeline events for activity tracking *)
+
+val discussions_query : string
+(** The GraphQL query string for fetching discussions.
+
+    This is a simpler query that fetches the first 100 discussions
+    ordered by UPDATED_AT descending, without pagination. *)
+
+(** {1 Request Building} *)
+
+val build_request_body : query:string -> variables:query_variables -> string
+(** [build_request_body ~query ~variables] builds the JSON request body
+    for the GitHub GraphQL endpoint.
+
+    Returns a JSON string of the form:
+    [\{"query": "...", "variables": \{...\}\}] *)
+
+val variables_to_json : query_variables -> (string * Jsont.Json.t) list
+(** [variables_to_json vars] converts query variables to a JSON-compatible
+    association list for use with other GraphQL clients. *)

repowatch/lib/graphql_codec.ml

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+module G = Graphql_types
+
+(* Helper for nullable strings *)
+let nullable_string = Jsont.option Jsont.string
+
+(* Helper for nullable integers that default to 0 *)
+let nullable_int_zero =
+  Jsont.map
+    ~dec:(fun v -> Option.value v ~default:0)
+    ~enc:(fun v -> Some v)
+    (Jsont.option Jsont.int)
+
+let page_info =
+  Jsont.Object.map ~kind:"PageInfo"
+    (fun has_next_page end_cursor -> G.Page_info.make ~has_next_page ~end_cursor)
+  |> Jsont.Object.mem "hasNextPage" Jsont.bool ~enc:G.Page_info.has_next_page
+  |> Jsont.Object.mem "endCursor" nullable_string ~dec_absent:None
+       ~enc:G.Page_info.end_cursor
+  |> Jsont.Object.finish
+
+(* Author can be null in GitHub responses (deleted users become "ghost") *)
+let author_inner =
+  Jsont.Object.map ~kind:"Author" (fun login -> G.Author.make ~login)
+  |> Jsont.Object.mem "login" Jsont.string ~enc:G.Author.login
+  |> Jsont.Object.finish
+
+let author =
+  Jsont.map
+    ~dec:(fun opt -> Option.value opt ~default:G.Author.ghost)
+    ~enc:(fun a -> if G.Author.login a = "ghost" then None else Some a)
+    (Jsont.option author_inner)
+
+let label =
+  Jsont.Object.map ~kind:"Label" (fun name -> G.Label.make ~name)
+  |> Jsont.Object.mem "name" Jsont.string ~enc:G.Label.name
+  |> Jsont.Object.finish
+
+let comment =
+  Jsont.Object.map ~kind:"Comment" (fun author body_text created_at updated_at ->
+      G.Comment.make ~author ~body_text ~created_at ~updated_at)
+  |> Jsont.Object.mem "author" author ~enc:G.Comment.author
+  |> Jsont.Object.mem "bodyText" Jsont.string ~enc:G.Comment.body_text
+  |> Jsont.Object.mem "createdAt" Jsont.string ~enc:G.Comment.created_at
+  |> Jsont.Object.mem "updatedAt" Jsont.string ~enc:G.Comment.updated_at
+  |> Jsont.Object.finish
+
+(* Codec for the nested commit object in PullRequestCommit timeline events *)
+let commit_committed_date =
+  Jsont.Object.map ~kind:"Commit" (fun committed_date -> committed_date)
+  |> Jsont.Object.mem "committedDate" nullable_string ~dec_absent:None
+       ~enc:(fun s -> s)
+  |> Jsont.Object.finish
+
+(* Timeline items use __typename to discriminate between types *)
+let timeline_item =
+  let open G.Timeline_item in
+  (* Helper to decode based on __typename *)
+  Jsont.Object.map ~kind:"TimelineItem"
+    (fun typename created_at committed_date ->
+      match typename with
+      | "IssueComment" ->
+          Issue_comment { created_at = Option.value created_at ~default:"" }
+      | "LabeledEvent" ->
+          Labeled_event { created_at = Option.value created_at ~default:"" }
+      | "UnlabeledEvent" ->
+          Unlabeled_event { created_at = Option.value created_at ~default:"" }
+      | "ClosedEvent" ->
+          Closed_event { created_at = Option.value created_at ~default:"" }
+      | "ReopenedEvent" ->
+          Reopened_event { created_at = Option.value created_at ~default:"" }
+      | "PullRequestCommit" ->
+          let date =
+            Option.bind committed_date Fun.id |> Option.value ~default:""
+          in
+          Pr_commit { committed_date = date }
+      | "PullRequestReview" ->
+          Pr_review { created_at = Option.value created_at ~default:"" }
+      | "MergedEvent" ->
+          Merged_event { created_at = Option.value created_at ~default:"" }
+      | _ -> Unknown)
+  |> Jsont.Object.mem "__typename" Jsont.string ~enc:(fun item ->
+         match item with
+         | Issue_comment _ -> "IssueComment"
+         | Labeled_event _ -> "LabeledEvent"
+         | Unlabeled_event _ -> "UnlabeledEvent"
+         | Closed_event _ -> "ClosedEvent"
+         | Reopened_event _ -> "ReopenedEvent"
+         | Pr_commit _ -> "PullRequestCommit"
+         | Pr_review _ -> "PullRequestReview"
+         | Merged_event _ -> "MergedEvent"
+         | Unknown -> "Unknown")
+  |> Jsont.Object.mem "createdAt" nullable_string ~dec_absent:None
+       ~enc:(fun item ->
+         match item with
+         | Issue_comment { created_at }
+         | Labeled_event { created_at }
+         | Unlabeled_event { created_at }
+         | Closed_event { created_at }
+         | Reopened_event { created_at }
+         | Pr_review { created_at }
+         | Merged_event { created_at } ->
+             Some created_at
+         | Pr_commit _ | Unknown -> None)
+  |> Jsont.Object.mem "commit" (Jsont.option commit_committed_date)
+       ~dec_absent:None
+       ~enc:(fun item ->
+         match item with
+         | Pr_commit { committed_date } -> Some (Some committed_date)
+         | _ -> None)
+  |> Jsont.Object.finish
+
+(* Labels connection - extract nodes *)
+let labels_nodes =
+  Jsont.Object.map ~kind:"LabelsConnection" (fun labels -> labels)
+  |> Jsont.Object.mem "nodes" (Jsont.list label) ~enc:(fun x -> x)
+  |> Jsont.Object.finish
+
+(* Comments connection - extract nodes and totalCount *)
+let comments_connection =
+  Jsont.Object.map ~kind:"CommentsConnection"
+    (fun total_count nodes -> (total_count, nodes))
+  |> Jsont.Object.mem "totalCount" Jsont.int ~enc:fst
+  |> Jsont.Object.mem "nodes" (Jsont.list comment) ~enc:snd
+  |> Jsont.Object.finish
+
+(* Timeline items connection - extract nodes *)
+let timeline_nodes =
+  Jsont.Object.map ~kind:"TimelineConnection" (fun items -> items)
+  |> Jsont.Object.mem "nodes" (Jsont.list timeline_item) ~enc:(fun x -> x)
+  |> Jsont.Object.finish
+
+let issue_node =
+  Jsont.Object.map ~kind:"IssueNode"
+    (fun number title url created_at updated_at closed_at body_text state author
+         labels (comments_total_count, comments) timeline_items ->
+      G.Issue_node.make ~number ~title ~url ~created_at ~updated_at ~closed_at
+        ~body_text ~state ~author ~labels ~comments ~comments_total_count
+        ~timeline_items)
+  |> Jsont.Object.mem "number" Jsont.int ~enc:G.Issue_node.number
+  |> Jsont.Object.mem "title" Jsont.string ~enc:G.Issue_node.title
+  |> Jsont.Object.mem "url" Jsont.string ~enc:G.Issue_node.url
+  |> Jsont.Object.mem "createdAt" Jsont.string ~enc:G.Issue_node.created_at
+  |> Jsont.Object.mem "updatedAt" Jsont.string ~enc:G.Issue_node.updated_at
+  |> Jsont.Object.mem "closedAt" nullable_string ~dec_absent:None
+       ~enc:G.Issue_node.closed_at
+  |> Jsont.Object.mem "bodyText" Jsont.string ~enc:G.Issue_node.body_text
+  |> Jsont.Object.mem "state" Jsont.string ~enc:G.Issue_node.state
+  |> Jsont.Object.mem "author" author ~enc:G.Issue_node.author
+  |> Jsont.Object.mem "labels" labels_nodes ~enc:G.Issue_node.labels
+  |> Jsont.Object.mem "comments" comments_connection
+       ~enc:(fun n ->
+         (G.Issue_node.comments_total_count n, G.Issue_node.comments n))
+  |> Jsont.Object.mem "timelineItems" timeline_nodes
+       ~enc:G.Issue_node.timeline_items
+  |> Jsont.Object.finish
+
+let pr_node =
+  Jsont.Object.map ~kind:"PrNode"
+    (fun number title url created_at updated_at closed_at merged_at body_text
+         state additions deletions changed_files mergeable is_draft author labels
+         (comments_total_count, comments) timeline_items ->
+      G.Pr_node.make ~number ~title ~url ~created_at ~updated_at ~closed_at
+        ~merged_at ~body_text ~state ~additions ~deletions ~changed_files
+        ~mergeable ~is_draft ~author ~labels ~comments ~comments_total_count
+        ~timeline_items)
+  |> Jsont.Object.mem "number" Jsont.int ~enc:G.Pr_node.number
+  |> Jsont.Object.mem "title" Jsont.string ~enc:G.Pr_node.title
+  |> Jsont.Object.mem "url" Jsont.string ~enc:G.Pr_node.url
+  |> Jsont.Object.mem "createdAt" Jsont.string ~enc:G.Pr_node.created_at
+  |> Jsont.Object.mem "updatedAt" Jsont.string ~enc:G.Pr_node.updated_at
+  |> Jsont.Object.mem "closedAt" nullable_string ~dec_absent:None
+       ~enc:G.Pr_node.closed_at
+  |> Jsont.Object.mem "mergedAt" nullable_string ~dec_absent:None
+       ~enc:G.Pr_node.merged_at
+  |> Jsont.Object.mem "bodyText" Jsont.string ~enc:G.Pr_node.body_text
+  |> Jsont.Object.mem "state" Jsont.string ~enc:G.Pr_node.state
+  |> Jsont.Object.mem "additions" nullable_int_zero ~enc:G.Pr_node.additions
+  |> Jsont.Object.mem "deletions" nullable_int_zero ~enc:G.Pr_node.deletions
+  |> Jsont.Object.mem "changedFiles" nullable_int_zero
+       ~enc:G.Pr_node.changed_files
+  |> Jsont.Object.mem "mergeable" Jsont.string ~enc:G.Pr_node.mergeable
+  |> Jsont.Object.mem "isDraft" Jsont.bool ~enc:G.Pr_node.is_draft
+  |> Jsont.Object.mem "author" author ~enc:G.Pr_node.author
+  |> Jsont.Object.mem "labels" labels_nodes ~enc:G.Pr_node.labels
+  |> Jsont.Object.mem "comments" comments_connection
+       ~enc:(fun n -> (G.Pr_node.comments_total_count n, G.Pr_node.comments n))
+  |> Jsont.Object.mem "timelineItems" timeline_nodes
+       ~enc:G.Pr_node.timeline_items
+  |> Jsont.Object.finish
+
+let issues_connection =
+  Jsont.Object.map ~kind:"IssuesConnection"
+    (fun page_info nodes -> G.Issues_connection.make ~page_info ~nodes)
+  |> Jsont.Object.mem "pageInfo" page_info ~enc:G.Issues_connection.page_info
+  |> Jsont.Object.mem "nodes" (Jsont.list issue_node)
+       ~enc:G.Issues_connection.nodes
+  |> Jsont.Object.finish
+
+let prs_connection =
+  Jsont.Object.map ~kind:"PrsConnection"
+    (fun page_info nodes -> G.Prs_connection.make ~page_info ~nodes)
+  |> Jsont.Object.mem "pageInfo" page_info ~enc:G.Prs_connection.page_info
+  |> Jsont.Object.mem "nodes" (Jsont.list pr_node) ~enc:G.Prs_connection.nodes
+  |> Jsont.Object.finish
+
+(* Category is a nested object with just a name *)
+let category_name =
+  Jsont.Object.map ~kind:"Category" (fun name -> name)
+  |> Jsont.Object.mem "name" Jsont.string ~enc:(fun x -> x)
+  |> Jsont.Object.finish
+
+(* Comments for discussion is just totalCount *)
+let discussion_comments_count =
+  Jsont.Object.map ~kind:"DiscussionComments" (fun count -> count)
+  |> Jsont.Object.mem "totalCount" Jsont.int ~enc:(fun x -> x)
+  |> Jsont.Object.finish
+
+let discussion_node =
+  Jsont.Object.map ~kind:"DiscussionNode"
+    (fun number title url updated_at body_text author category comments_count
+         answer_chosen_at ->
+      let answered = Option.is_some answer_chosen_at in
+      G.Discussion_node.make ~number ~title ~url ~updated_at ~body_text ~author
+        ~category ~comments_count ~answered)
+  |> Jsont.Object.mem "number" Jsont.int ~enc:G.Discussion_node.number
+  |> Jsont.Object.mem "title" Jsont.string ~enc:G.Discussion_node.title
+  |> Jsont.Object.mem "url" Jsont.string ~enc:G.Discussion_node.url
+  |> Jsont.Object.mem "updatedAt" Jsont.string ~enc:G.Discussion_node.updated_at
+  |> Jsont.Object.mem "bodyText" Jsont.string ~enc:G.Discussion_node.body_text
+  |> Jsont.Object.mem "author" author ~enc:G.Discussion_node.author
+  |> Jsont.Object.mem "category" category_name ~enc:G.Discussion_node.category
+  |> Jsont.Object.mem "comments" discussion_comments_count
+       ~enc:G.Discussion_node.comments_count
+  |> Jsont.Object.mem "answerChosenAt" nullable_string ~dec_absent:None
+       ~enc:(fun d -> if G.Discussion_node.answered d then Some "" else None)
+  |> Jsont.Object.finish
+
+(* Repository wrapper for issues/PRs query *)
+let repository_inner =
+  Jsont.Object.map ~kind:"Repository"
+    (fun issues pull_requests ->
+      G.Repository_response.make ~issues ~pull_requests)
+  |> Jsont.Object.mem "issues" issues_connection
+       ~enc:G.Repository_response.issues
+  |> Jsont.Object.mem "pullRequests" prs_connection
+       ~enc:G.Repository_response.pull_requests
+  |> Jsont.Object.finish
+
+(* Data wrapper for issues/PRs response *)
+let data_repository =
+  Jsont.Object.map ~kind:"DataRepository" (fun repo -> repo)
+  |> Jsont.Object.mem "repository" repository_inner ~enc:(fun x -> x)
+  |> Jsont.Object.finish
+
+let repository_response =
+  Jsont.Object.map ~kind:"RepositoryResponse" (fun data -> data)
+  |> Jsont.Object.mem "data" data_repository ~enc:(fun x -> x)
+  |> Jsont.Object.finish
+
+(* Discussions connection wrapper *)
+let discussions_nodes =
+  Jsont.Object.map ~kind:"DiscussionsConnection" (fun nodes -> nodes)
+  |> Jsont.Object.mem "nodes" (Jsont.list discussion_node) ~enc:(fun x -> x)
+  |> Jsont.Object.finish
+
+(* Repository wrapper for discussions query *)
+let repository_discussions_inner =
+  Jsont.Object.map ~kind:"RepositoryDiscussions"
+    (fun discussions -> G.Discussions_response.make ~discussions)
+  |> Jsont.Object.mem "discussions" discussions_nodes
+       ~enc:G.Discussions_response.discussions
+  |> Jsont.Object.finish
+
+(* Data wrapper for discussions response *)
+let data_discussions =
+  Jsont.Object.map ~kind:"DataDiscussions" (fun repo -> repo)
+  |> Jsont.Object.mem "repository" repository_discussions_inner ~enc:(fun x -> x)
+  |> Jsont.Object.finish
+
+let discussions_response =
+  Jsont.Object.map ~kind:"DiscussionsResponse" (fun data -> data)
+  |> Jsont.Object.mem "data" data_discussions ~enc:(fun x -> x)
+  |> Jsont.Object.finish
+
+let decode_repository_response s =
+  Jsont_bytesrw.decode_string repository_response s
+
+let decode_discussions_response s =
+  Jsont_bytesrw.decode_string discussions_response s

repowatch/lib/graphql_codec.mli

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+(** Jsont codecs for GitHub GraphQL API responses.
+
+    This module provides type-safe JSON codecs for decoding the responses
+    from GitHub's GraphQL API for issues, pull requests, and discussions. *)
+
+(** {1 Component Codecs} *)
+
+val page_info : Graphql_types.Page_info.t Jsont.t
+(** Codec for GraphQL pagination info. *)
+
+val author : Graphql_types.Author.t Jsont.t
+(** Codec for GitHub user/author. Handles null authors as "ghost". *)
+
+val label : Graphql_types.Label.t Jsont.t
+(** Codec for issue/PR labels. *)
+
+val comment : Graphql_types.Comment.t Jsont.t
+(** Codec for comments. *)
+
+val timeline_item : Graphql_types.Timeline_item.t Jsont.t
+(** Codec for timeline events. Uses __typename to determine event type. *)
+
+(** {1 Issue/PR Codecs} *)
+
+val issue_node : Graphql_types.Issue_node.t Jsont.t
+(** Codec for GitHub issue nodes from GraphQL. *)
+
+val pr_node : Graphql_types.Pr_node.t Jsont.t
+(** Codec for GitHub PR nodes from GraphQL. *)
+
+val issues_connection : Graphql_types.Issues_connection.t Jsont.t
+(** Codec for paginated issues connection. *)
+
+val prs_connection : Graphql_types.Prs_connection.t Jsont.t
+(** Codec for paginated PRs connection. *)
+
+(** {1 Discussion Codecs} *)
+
+val discussion_node : Graphql_types.Discussion_node.t Jsont.t
+(** Codec for GitHub discussion nodes from GraphQL. *)
+
+(** {1 Response Codecs} *)
+
+val repository_response : Graphql_types.Repository_response.t Jsont.t
+(** Codec for the full issues/PRs query response. Expects the response to
+    be wrapped in [\{"data": \{"repository": ...\}\}]. *)
+
+val discussions_response : Graphql_types.Discussions_response.t Jsont.t
+(** Codec for the discussions query response. Expects the response to
+    be wrapped in [\{"data": \{"repository": ...\}\}]. *)
+
+(** {1 Decoding Functions} *)
+
+val decode_repository_response :
+  string -> (Graphql_types.Repository_response.t, string) result
+(** Decode a JSON string as an issues/PRs response. *)
+
+val decode_discussions_response :
+  string -> (Graphql_types.Discussions_response.t, string) result
+(** Decode a JSON string as a discussions response. *)

repowatch/lib/graphql_types.ml

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+module Page_info = struct
+  type t = { has_next_page : bool; end_cursor : string option }
+
+  let make ~has_next_page ~end_cursor = { has_next_page; end_cursor }
+  let has_next_page t = t.has_next_page
+  let end_cursor t = t.end_cursor
+end
+
+module Author = struct
+  type t = { login : string }
+
+  let make ~login = { login }
+  let ghost = { login = "ghost" }
+  let login t = t.login
+end
+
+module Label = struct
+  type t = { name : string }
+
+  let make ~name = { name }
+  let name t = t.name
+end
+
+module Comment = struct
+  type t = {
+    author : Author.t;
+    body_text : string;
+    created_at : string;
+    updated_at : string;
+  }
+
+  let make ~author ~body_text ~created_at ~updated_at =
+    { author; body_text; created_at; updated_at }
+
+  let author t = t.author
+  let body_text t = t.body_text
+  let created_at t = t.created_at
+  let updated_at t = t.updated_at
+end
+
+module Timeline_item = struct
+  type t =
+    | Issue_comment of { created_at : string }
+    | Labeled_event of { created_at : string }
+    | Unlabeled_event of { created_at : string }
+    | Closed_event of { created_at : string }
+    | Reopened_event of { created_at : string }
+    | Pr_commit of { committed_date : string }
+    | Pr_review of { created_at : string }
+    | Merged_event of { created_at : string }
+    | Unknown
+
+  let created_at = function
+    | Issue_comment { created_at } -> Some created_at
+    | Labeled_event { created_at } -> Some created_at
+    | Unlabeled_event { created_at } -> Some created_at
+    | Closed_event { created_at } -> Some created_at
+    | Reopened_event { created_at } -> Some created_at
+    | Pr_commit { committed_date } -> Some committed_date
+    | Pr_review { created_at } -> Some created_at
+    | Merged_event { created_at } -> Some created_at
+    | Unknown -> None
+end
+
+module Issue_node = struct
+  type t = {
+    number : int;
+    title : string;
+    url : string;
+    created_at : string;
+    updated_at : string;
+    closed_at : string option;
+    body_text : string;
+    state : string;
+    author : Author.t;
+    labels : Label.t list;
+    comments : Comment.t list;
+    comments_total_count : int;
+    timeline_items : Timeline_item.t list;
+  }
+
+  let make ~number ~title ~url ~created_at ~updated_at ~closed_at ~body_text
+      ~state ~author ~labels ~comments ~comments_total_count ~timeline_items =
+    {
+      number;
+      title;
+      url;
+      created_at;
+      updated_at;
+      closed_at;
+      body_text;
+      state;
+      author;
+      labels;
+      comments;
+      comments_total_count;
+      timeline_items;
+    }
+
+  let number t = t.number
+  let title t = t.title
+  let url t = t.url
+  let created_at t = t.created_at
+  let updated_at t = t.updated_at
+  let closed_at t = t.closed_at
+  let body_text t = t.body_text
+  let state t = t.state
+  let author t = t.author
+  let labels t = t.labels
+  let comments t = t.comments
+  let comments_total_count t = t.comments_total_count
+  let timeline_items t = t.timeline_items
+end
+
+module Pr_node = struct
+  type t = {
+    number : int;
+    title : string;
+    url : string;
+    created_at : string;
+    updated_at : string;
+    closed_at : string option;
+    merged_at : string option;
+    body_text : string;
+    state : string;
+    additions : int;
+    deletions : int;
+    changed_files : int;
+    mergeable : string;
+    is_draft : bool;
+    author : Author.t;
+    labels : Label.t list;
+    comments : Comment.t list;
+    comments_total_count : int;
+    timeline_items : Timeline_item.t list;
+  }
+
+  let make ~number ~title ~url ~created_at ~updated_at ~closed_at ~merged_at
+      ~body_text ~state ~additions ~deletions ~changed_files ~mergeable
+      ~is_draft ~author ~labels ~comments ~comments_total_count ~timeline_items
+      =
+    {
+      number;
+      title;
+      url;
+      created_at;
+      updated_at;
+      closed_at;
+      merged_at;
+      body_text;
+      state;
+      additions;
+      deletions;
+      changed_files;
+      mergeable;
+      is_draft;
+      author;
+      labels;
+      comments;
+      comments_total_count;
+      timeline_items;
+    }
+
+  let number t = t.number
+  let title t = t.title
+  let url t = t.url
+  let created_at t = t.created_at
+  let updated_at t = t.updated_at
+  let closed_at t = t.closed_at
+  let merged_at t = t.merged_at
+  let body_text t = t.body_text
+  let state t = t.state
+  let additions t = t.additions
+  let deletions t = t.deletions
+  let changed_files t = t.changed_files
+  let mergeable t = t.mergeable
+  let is_draft t = t.is_draft
+  let author t = t.author
+  let labels t = t.labels
+  let comments t = t.comments
+  let comments_total_count t = t.comments_total_count
+  let timeline_items t = t.timeline_items
+end
+
+module Issues_connection = struct
+  type t = { page_info : Page_info.t; nodes : Issue_node.t list }
+
+  let make ~page_info ~nodes = { page_info; nodes }
+  let page_info t = t.page_info
+  let nodes t = t.nodes
+end
+
+module Prs_connection = struct
+  type t = { page_info : Page_info.t; nodes : Pr_node.t list }
+
+  let make ~page_info ~nodes = { page_info; nodes }
+  let page_info t = t.page_info
+  let nodes t = t.nodes
+end
+
+module Discussion_node = struct
+  type t = {
+    number : int;
+    title : string;
+    url : string;
+    updated_at : string;
+    body_text : string;
+    author : Author.t;
+    category : string;
+    comments_count : int;
+    answered : bool;
+  }
+
+  let make ~number ~title ~url ~updated_at ~body_text ~author ~category
+      ~comments_count ~answered =
+    {
+      number;
+      title;
+      url;
+      updated_at;
+      body_text;
+      author;
+      category;
+      comments_count;
+      answered;
+    }
+
+  let number t = t.number
+  let title t = t.title
+  let url t = t.url
+  let updated_at t = t.updated_at
+  let body_text t = t.body_text
+  let author t = t.author
+  let category t = t.category
+  let comments_count t = t.comments_count
+  let answered t = t.answered
+end
+
+module Repository_response = struct
+  type t = {
+    issues : Issues_connection.t;
+    pull_requests : Prs_connection.t;
+  }
+
+  let make ~issues ~pull_requests = { issues; pull_requests }
+  let issues t = t.issues
+  let pull_requests t = t.pull_requests
+end
+
+module Discussions_response = struct
+  type t = { discussions : Discussion_node.t list }
+
+  let make ~discussions = { discussions }
+  let discussions t = t.discussions
+end

repowatch/lib/graphql_types.mli

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+(** GraphQL response types for GitHub API.
+
+    This module defines types for decoding GitHub GraphQL API responses for
+    issues, pull requests, and discussions queries. *)
+
+(** {1 Pagination} *)
+
+module Page_info : sig
+  type t
+  (** Pagination information from a GraphQL connection. *)
+
+  val make : has_next_page:bool -> end_cursor:string option -> t
+  (** Create pagination info. *)
+
+  val has_next_page : t -> bool
+  (** Whether there are more pages available. *)
+
+  val end_cursor : t -> string option
+  (** Cursor for fetching the next page, if any. *)
+end
+
+(** {1 User Information} *)
+
+module Author : sig
+  type t
+  (** A GitHub user or organization. *)
+
+  val make : login:string -> t
+  (** Create an author. *)
+
+  val ghost : t
+  (** The "ghost" author, used when the original author has been deleted. *)
+
+  val login : t -> string
+  (** The user's login name. Returns "ghost" for deleted users. *)
+end
+
+(** {1 Labels} *)
+
+module Label : sig
+  type t
+  (** A GitHub issue or PR label. *)
+
+  val make : name:string -> t
+  (** Create a label. *)
+
+  val name : t -> string
+  (** The label name. *)
+end
+
+(** {1 Comments} *)
+
+module Comment : sig
+  type t
+  (** A comment on an issue, PR, or discussion. *)
+
+  val make :
+    author:Author.t ->
+    body_text:string ->
+    created_at:string ->
+    updated_at:string ->
+    t
+  (** Create a comment. *)
+
+  val author : t -> Author.t
+  (** The comment author. *)
+
+  val body_text : t -> string
+  (** The plain text body of the comment. *)
+
+  val created_at : t -> string
+  (** When the comment was created (ISO 8601). *)
+
+  val updated_at : t -> string
+  (** When the comment was last updated (ISO 8601). *)
+end
+
+(** {1 Timeline Events} *)
+
+module Timeline_item : sig
+  type t =
+    | Issue_comment of { created_at : string }
+    | Labeled_event of { created_at : string }
+    | Unlabeled_event of { created_at : string }
+    | Closed_event of { created_at : string }
+    | Reopened_event of { created_at : string }
+    | Pr_commit of { committed_date : string }
+    | Pr_review of { created_at : string }
+    | Merged_event of { created_at : string }
+    | Unknown
+        (** Timeline events from an issue or PR.
+
+      These track activity that may have occurred during a given week,
+      enabling filtering of items by their recent activity. *)
+
+  val created_at : t -> string option
+  (** Extract the timestamp from any timeline item, if present. *)
+end
+
+(** {1 Issues} *)
+
+module Issue_node : sig
+  type t
+  (** A GitHub issue from the GraphQL API. *)
+
+  val make :
+    number:int ->
+    title:string ->
+    url:string ->
+    created_at:string ->
+    updated_at:string ->
+    closed_at:string option ->
+    body_text:string ->
+    state:string ->
+    author:Author.t ->
+    labels:Label.t list ->
+    comments:Comment.t list ->
+    comments_total_count:int ->
+    timeline_items:Timeline_item.t list ->
+    t
+  (** Create an issue node. *)
+
+  val number : t -> int
+  (** The issue number. *)
+
+  val title : t -> string
+  (** The issue title. *)
+
+  val url : t -> string
+  (** URL to the issue on GitHub. *)
+
+  val created_at : t -> string
+  (** When the issue was created (ISO 8601). *)
+
+  val updated_at : t -> string
+  (** When the issue was last updated (ISO 8601). *)
+
+  val closed_at : t -> string option
+  (** When the issue was closed, if closed. *)
+
+  val body_text : t -> string
+  (** The plain text body of the issue. *)
+
+  val state : t -> string
+  (** The issue state: "OPEN" or "CLOSED". *)
+
+  val author : t -> Author.t
+  (** The issue author. *)
+
+  val labels : t -> Label.t list
+  (** Labels applied to the issue. *)
+
+  val comments : t -> Comment.t list
+  (** Recent comments on the issue. *)
+
+  val comments_total_count : t -> int
+  (** Total number of comments. *)
+
+  val timeline_items : t -> Timeline_item.t list
+  (** Recent timeline events. *)
+end
+
+(** {1 Pull Requests} *)
+
+module Pr_node : sig
+  type t
+  (** A GitHub pull request from the GraphQL API. *)
+
+  val make :
+    number:int ->
+    title:string ->
+    url:string ->
+    created_at:string ->
+    updated_at:string ->
+    closed_at:string option ->
+    merged_at:string option ->
+    body_text:string ->
+    state:string ->
+    additions:int ->
+    deletions:int ->
+    changed_files:int ->
+    mergeable:string ->
+    is_draft:bool ->
+    author:Author.t ->
+    labels:Label.t list ->
+    comments:Comment.t list ->
+    comments_total_count:int ->
+    timeline_items:Timeline_item.t list ->
+    t
+  (** Create a PR node. *)
+
+  val number : t -> int
+  (** The PR number. *)
+
+  val title : t -> string
+  (** The PR title. *)
+
+  val url : t -> string
+  (** URL to the PR on GitHub. *)
+
+  val created_at : t -> string
+  (** When the PR was created (ISO 8601). *)
+
+  val updated_at : t -> string
+  (** When the PR was last updated (ISO 8601). *)
+
+  val closed_at : t -> string option
+  (** When the PR was closed, if closed. *)
+
+  val merged_at : t -> string option
+  (** When the PR was merged, if merged. *)
+
+  val body_text : t -> string
+  (** The plain text body of the PR. *)
+
+  val state : t -> string
+  (** The PR state: "OPEN", "CLOSED", or "MERGED". *)
+
+  val additions : t -> int
+  (** Lines added. *)
+
+  val deletions : t -> int
+  (** Lines deleted. *)
+
+  val changed_files : t -> int
+  (** Number of files changed. *)
+
+  val mergeable : t -> string
+  (** Mergeable state: "MERGEABLE", "CONFLICTING", or "UNKNOWN". *)
+
+  val is_draft : t -> bool
+  (** Whether this is a draft PR. *)
+
+  val author : t -> Author.t
+  (** The PR author. *)
+
+  val labels : t -> Label.t list
+  (** Labels applied to the PR. *)
+
+  val comments : t -> Comment.t list
+  (** Recent comments on the PR. *)
+
+  val comments_total_count : t -> int
+  (** Total number of comments. *)
+
+  val timeline_items : t -> Timeline_item.t list
+  (** Recent timeline events. *)
+end
+
+(** {1 Connections (Paginated Lists)} *)
+
+module Issues_connection : sig
+  type t
+  (** A paginated list of issues. *)
+
+  val make : page_info:Page_info.t -> nodes:Issue_node.t list -> t
+  (** Create an issues connection. *)
+
+  val page_info : t -> Page_info.t
+  (** Pagination information. *)
+
+  val nodes : t -> Issue_node.t list
+  (** The issues in this page. *)
+end
+
+module Prs_connection : sig
+  type t
+  (** A paginated list of pull requests. *)
+
+  val make : page_info:Page_info.t -> nodes:Pr_node.t list -> t
+  (** Create a PRs connection. *)
+
+  val page_info : t -> Page_info.t
+  (** Pagination information. *)
+
+  val nodes : t -> Pr_node.t list
+  (** The PRs in this page. *)
+end
+
+(** {1 Discussions} *)
+
+module Discussion_node : sig
+  type t
+  (** A GitHub discussion from the GraphQL API. *)
+
+  val make :
+    number:int ->
+    title:string ->
+    url:string ->
+    updated_at:string ->
+    body_text:string ->
+    author:Author.t ->
+    category:string ->
+    comments_count:int ->
+    answered:bool ->
+    t
+  (** Create a discussion node. *)
+
+  val number : t -> int
+  (** The discussion number. *)
+
+  val title : t -> string
+  (** The discussion title. *)
+
+  val url : t -> string
+  (** URL to the discussion on GitHub. *)
+
+  val updated_at : t -> string
+  (** When the discussion was last updated (ISO 8601). *)
+
+  val body_text : t -> string
+  (** The plain text body of the discussion. *)
+
+  val author : t -> Author.t
+  (** The discussion author. *)
+
+  val category : t -> string
+  (** The discussion category name. *)
+
+  val comments_count : t -> int
+  (** Number of comments. *)
+
+  val answered : t -> bool
+  (** Whether the discussion has an accepted answer. *)
+end
+
+(** {1 API Responses} *)
+
+module Repository_response : sig
+  type t
+  (** Response from the issues/PRs GraphQL query. *)
+
+  val make : issues:Issues_connection.t -> pull_requests:Prs_connection.t -> t
+  (** Create a repository response. *)
+
+  val issues : t -> Issues_connection.t
+  (** The issues connection. *)
+
+  val pull_requests : t -> Prs_connection.t
+  (** The pull requests connection. *)
+end
+
+module Discussions_response : sig
+  type t
+  (** Response from the discussions GraphQL query. *)
+
+  val make : discussions:Discussion_node.t list -> t
+  (** Create a discussions response. *)
+
+  val discussions : t -> Discussion_node.t list
+  (** The discussions list. *)
+end

repowatch/lib/loader.ml

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+let load_file fs path = Codec.decode_file fs path
+
+let load_file_exn fs path =
+  match load_file fs path with
+  | Ok data -> data
+  | Error e -> failwith e
+
+let is_json_file name =
+  String.length name > 5 && String.sub name (String.length name - 5) 5 = ".json"
+
+let rec find_json_files_rec fs dir acc =
+  let path = Eio.Path.(fs / dir) in
+  let entries =
+    try Eio.Path.read_dir path
+    with _ -> []
+  in
+  List.fold_left
+    (fun acc entry ->
+      let entry_path = Filename.concat dir entry in
+      let full_path = Eio.Path.(fs / entry_path) in
+      match Eio.Path.kind ~follow:true full_path with
+      | `Directory -> find_json_files_rec fs entry_path acc
+      | `Regular_file when is_json_file entry -> entry_path :: acc
+      | _ -> acc)
+    acc entries
+
+let find_json_files fs dir =
+  find_json_files_rec fs dir [] |> List.sort String.compare
+
+let load_directory fs dir =
+  let files = find_json_files fs dir in
+  let results =
+    List.map
+      (fun file ->
+        match load_file fs file with
+        | Ok data -> `Ok (file, data)
+        | Error e -> `Error (file, e))
+      files
+  in
+  let successes, errors =
+    List.partition_map
+      (function
+        | `Ok (_, data) -> Either.Left data
+        | `Error (file, e) -> Either.Right (file, e))
+      results
+  in
+  if errors = [] then Ok successes else Error errors
+
+let load_directory_partial fs dir =
+  let files = find_json_files fs dir in
+  List.fold_left
+    (fun (data, errors) file ->
+      match load_file fs file with
+      | Ok d -> (d :: data, errors)
+      | Error e -> (data, (file, e) :: errors))
+    ([], []) files
+  |> fun (data, errors) -> (List.rev data, List.rev errors)
+
+let find_repos fs data_dir =
+  let path = Eio.Path.(fs / data_dir) in
+  let owners =
+    try Eio.Path.read_dir path
+    with _ -> []
+  in
+  List.fold_left
+    (fun acc owner ->
+      let owner_path = Eio.Path.(fs / Filename.concat data_dir owner) in
+      match Eio.Path.kind ~follow:true owner_path with
+      | `Directory ->
+          let repos =
+            try Eio.Path.read_dir owner_path
+            with _ -> []
+          in
+          List.fold_left
+            (fun acc repo ->
+              let repo_path =
+                Eio.Path.(fs / Filename.concat (Filename.concat data_dir owner) repo)
+              in
+              match Eio.Path.kind ~follow:true repo_path with
+              | `Directory -> Printf.sprintf "%s/%s" owner repo :: acc
+              | _ -> acc)
+            acc repos
+      | _ -> acc)
+    [] owners
+  |> List.sort String.compare
+
+let load_repo fs ~data_dir ~owner ~repo =
+  let dir = Filename.concat (Filename.concat data_dir owner) repo in
+  load_directory fs dir

repowatch/lib/loader.mli

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+(** File loading utilities for GitHub activity data.
+
+    This module provides functions for loading JSON files from the filesystem
+    and discovering files in directory structures. *)
+
+(** {1 File Loading} *)
+
+val load_file :
+  Eio.Fs.dir_ty Eio.Path.t -> string -> (Types.Week_data.t, string) result
+(** [load_file fs path] loads and parses a single JSON file.
+
+    @param fs The filesystem capability
+    @param path Path to the JSON file *)
+
+val load_file_exn : Eio.Fs.dir_ty Eio.Path.t -> string -> Types.Week_data.t
+(** [load_file_exn fs path] loads and parses a single JSON file.
+    Raises [Failure] on error. *)
+
+(** {1 Directory Loading} *)
+
+val find_json_files : Eio.Fs.dir_ty Eio.Path.t -> string -> string list
+(** [find_json_files fs dir] finds all JSON files in a directory tree.
+
+    Files are returned in sorted order, which for the week-NN-YYYY.json format
+    results in chronological ordering.
+
+    @param fs The filesystem capability
+    @param dir Root directory to search *)
+
+val load_directory :
+  Eio.Fs.dir_ty Eio.Path.t ->
+  string ->
+  (Types.Week_data.t list, (string * string) list) result
+(** [load_directory fs dir] loads all JSON files from a directory.
+
+    Returns [Ok data] if all files parse successfully, or [Error errors] with
+    a list of (filename, error message) pairs for files that failed to parse. *)
+
+val load_directory_partial :
+  Eio.Fs.dir_ty Eio.Path.t ->
+  string ->
+  Types.Week_data.t list * (string * string) list
+(** [load_directory_partial fs dir] loads all JSON files, returning both
+    successfully parsed data and errors.
+
+    This is useful when you want to process whatever data is available
+    even if some files fail to parse. *)
+
+(** {1 Repository Discovery} *)
+
+val find_repos : Eio.Fs.dir_ty Eio.Path.t -> string -> string list
+(** [find_repos fs data_dir] finds repository paths in a ruminant data directory.
+
+    The ruminant format stores data in [data/gh/{owner}/{repo}/] structure.
+    This function returns a list of "owner/repo" strings.
+
+    @param fs The filesystem capability
+    @param data_dir Root of the ruminant data directory (e.g., "data/gh") *)
+
+val load_repo :
+  Eio.Fs.dir_ty Eio.Path.t ->
+  data_dir:string ->
+  owner:string ->
+  repo:string ->
+  (Types.Week_data.t list, (string * string) list) result
+(** [load_repo fs ~data_dir ~owner ~repo] loads all data for a repository.
+
+    @param fs The filesystem capability
+    @param data_dir Root of the ruminant data directory
+    @param owner Repository owner
+    @param repo Repository name *)

repowatch/lib/printer.ml

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+let truncate_string max_len s =
+  if String.length s <= max_len then s
+  else String.sub s 0 (max_len - 3) ^ "..."
+
+let pp_metadata ppf m =
+  let open Types.Metadata in
+  Fmt.pf ppf "@[<v>Repository: %s@,Year: %d, Week: %d@,Period: %s to %s@,Cached: %s@]"
+    (repo m) (year m) (week m) (week_start m) (week_end m) (cached_at m)
+
+let pp_labels ppf labels =
+  if labels = [] then ()
+  else Fmt.pf ppf " [%a]" Fmt.(list ~sep:(any ", ") string) labels
+
+let pp_issue ppf i =
+  let open Types.Issue in
+  Fmt.pf ppf "@[<v>#%d %s@,  Author: @%s@,  State: %s%a@,  Created: %s@,  Updated: %s%a@]"
+    (id i) (title i) (user i) (state i) pp_labels (labels i)
+    (created_at i) (updated_at i)
+    (fun ppf -> function
+      | Some ca -> Fmt.pf ppf "@,  Closed: %s" ca
+      | None -> ())
+    (closed_at i)
+
+let pp_issue_short ppf i =
+  let open Types.Issue in
+  let state_mark = if state i = "open" then "o" else "x" in
+  Fmt.pf ppf "[%s] #%-5d %-60s @%s"
+    state_mark (id i) (truncate_string 60 (title i)) (user i)
+
+let pp_pr ppf p =
+  let open Types.Pr in
+  Fmt.pf ppf
+    "@[<v>#%d %s%s@,  Author: @%s@,  State: %s%a@,  +%d -%d (%d files)@,  \
+     Mergeable: %s@,  Created: %s@,  Updated: %s%a%a@]"
+    (id p) (title p) (if draft p then " [DRAFT]" else "")
+    (user p) (state p) pp_labels (labels p)
+    (additions p) (deletions p) (changed_files p)
+    (mergeable p) (created_at p) (updated_at p)
+    (fun ppf -> function
+      | Some ca -> Fmt.pf ppf "@,  Closed: %s" ca
+      | None -> ())
+    (closed_at p)
+    (fun ppf -> function
+      | Some ma -> Fmt.pf ppf "@,  Merged: %s" ma
+      | None -> ())
+    (merged_at p)
+
+let pp_pr_short ppf p =
+  let open Types.Pr in
+  let state_mark =
+    match merged_at p with
+    | Some _ -> "M"
+    | None -> if state p = "open" then "o" else "x"
+  in
+  let draft_mark = if draft p then "D" else " " in
+  Fmt.pf ppf "[%s%s] #%-5d +%-5d -%-5d %-50s @%s"
+    state_mark draft_mark (id p) (additions p) (deletions p)
+    (truncate_string 50 (title p)) (user p)
+
+let pp_discussion ppf d =
+  let open Types.Discussion in
+  Fmt.pf ppf "@[<v>#%d %s@,  Author: @%s@,  Category: %s@,  Comments: %d%s@,  Updated: %s@]"
+    (id d) (title d) (user d) (category d) (comments d)
+    (if answered d then " [ANSWERED]" else "")
+    (updated_at d)
+
+let pp_discussion_short ppf d =
+  let open Types.Discussion in
+  let answered_mark = if answered d then "A" else " " in
+  Fmt.pf ppf "[%s] #%-5d %-50s (%s) @%s"
+    answered_mark (id d) (truncate_string 50 (title d)) (category d) (user d)
+
+let pp_asset ppf a =
+  let open Types.Asset in
+  let size_kb = size a / 1024 in
+  Fmt.pf ppf "  - %s (%d KB, %d downloads)" (name a) size_kb (download_count a)
+
+let pp_release ppf r =
+  let open Types.Release in
+  Fmt.pf ppf "@[<v>%s (%s)%s%s@,  Author: @%s@,  Published: %s@,  URL: %s%a@]"
+    (tag_name r) (name r)
+    (if prerelease r then " [PRE-RELEASE]" else "")
+    (if draft r then " [DRAFT]" else "")
+    (author r) (published_at r) (html_url r)
+    (fun ppf assets ->
+      if assets <> [] then
+        Fmt.pf ppf "@,  Assets:@,  %a"
+          Fmt.(list ~sep:(any "@,  ") pp_asset) assets)
+    (assets r)
+
+let pp_release_short ppf r =
+  let open Types.Release in
+  let marks =
+    (if prerelease r then "P" else " ") ^
+    (if draft r then "D" else " ")
+  in
+  Fmt.pf ppf "[%s] %-20s %-40s @%s"
+    marks (tag_name r) (truncate_string 40 (name r)) (author r)
+
+let pp_week_summary ppf w =
+  let open Types.Week_data in
+  let m = metadata w in
+  let num_issues = List.length (issues w) in
+  let num_prs = List.length (prs w) in
+  let num_gfi = List.length (good_first_issues w) in
+  let num_discussions = List.length (discussions w) in
+  let num_releases = List.length (releases w) in
+  let num_users = List.length (users w) in
+  Fmt.pf ppf "@[<v>%a@,@,Activity: %d issues, %d PRs, %d discussions, %d releases@,\
+              Good first issues: %d@,Active users: %d@]"
+    pp_metadata m num_issues num_prs num_discussions num_releases
+    num_gfi num_users
+
+let pp_week_data ppf w =
+  let open Types.Week_data in
+  Fmt.pf ppf "@[<v>%a@,@,"
+    pp_week_summary w;
+  if issues w <> [] then
+    Fmt.pf ppf "Issues:@,  @[<v>%a@]@,@,"
+      Fmt.(list ~sep:(any "@,@,  ") pp_issue) (issues w);
+  if prs w <> [] then
+    Fmt.pf ppf "Pull Requests:@,  @[<v>%a@]@,@,"
+      Fmt.(list ~sep:(any "@,@,  ") pp_pr) (prs w);
+  if discussions w <> [] then
+    Fmt.pf ppf "Discussions:@,  @[<v>%a@]@,@,"
+      Fmt.(list ~sep:(any "@,@,  ") pp_discussion) (discussions w);
+  if releases w <> [] then
+    Fmt.pf ppf "Releases:@,  @[<v>%a@]@,"
+      Fmt.(list ~sep:(any "@,@,  ") pp_release) (releases w);
+  Fmt.pf ppf "@]"
+
+type stats = {
+  total_issues : int;
+  open_issues : int;
+  closed_issues : int;
+  total_prs : int;
+  open_prs : int;
+  merged_prs : int;
+  closed_prs : int;
+  draft_prs : int;
+  total_discussions : int;
+  answered_discussions : int;
+  total_releases : int;
+  total_users : int;
+  total_additions : int;
+  total_deletions : int;
+  total_files_changed : int;
+}
+
+let empty_stats = {
+  total_issues = 0;
+  open_issues = 0;
+  closed_issues = 0;
+  total_prs = 0;
+  open_prs = 0;
+  merged_prs = 0;
+  closed_prs = 0;
+  draft_prs = 0;
+  total_discussions = 0;
+  answered_discussions = 0;
+  total_releases = 0;
+  total_users = 0;
+  total_additions = 0;
+  total_deletions = 0;
+  total_files_changed = 0;
+}
+
+let compute_stats w =
+  let open Types in
+  let issues = Week_data.issues w in
+  let prs = Week_data.prs w in
+  let discussions = Week_data.discussions w in
+  let releases = Week_data.releases w in
+  let users = Week_data.users w in
+  let open_issues, closed_issues =
+    List.fold_left
+      (fun (o, c) i ->
+        if Issue.state i = "open" then (o + 1, c) else (o, c + 1))
+      (0, 0) issues
+  in
+  let open_prs, merged_prs, closed_prs, draft_prs, additions, deletions, files =
+    List.fold_left
+      (fun (op, mp, cp, dp, a, d, f) p ->
+        let op, mp, cp =
+          match Pr.merged_at p with
+          | Some _ -> (op, mp + 1, cp)
+          | None -> if Pr.state p = "open" then (op + 1, mp, cp) else (op, mp, cp + 1)
+        in
+        let dp = if Pr.draft p then dp + 1 else dp in
+        (op, mp, cp, dp, a + Pr.additions p, d + Pr.deletions p, f + Pr.changed_files p))
+      (0, 0, 0, 0, 0, 0, 0) prs
+  in
+  let answered_discussions =
+    List.fold_left
+      (fun acc d -> if Discussion.answered d then acc + 1 else acc)
+      0 discussions
+  in
+  {
+    total_issues = List.length issues;
+    open_issues;
+    closed_issues;
+    total_prs = List.length prs;
+    open_prs;
+    merged_prs;
+    closed_prs;
+    draft_prs;
+    total_discussions = List.length discussions;
+    answered_discussions;
+    total_releases = List.length releases;
+    total_users = List.length users;
+    total_additions = additions;
+    total_deletions = deletions;
+    total_files_changed = files;
+  }
+
+let aggregate_stats stats_list =
+  List.fold_left
+    (fun acc s ->
+      {
+        total_issues = acc.total_issues + s.total_issues;
+        open_issues = acc.open_issues + s.open_issues;
+        closed_issues = acc.closed_issues + s.closed_issues;
+        total_prs = acc.total_prs + s.total_prs;
+        open_prs = acc.open_prs + s.open_prs;
+        merged_prs = acc.merged_prs + s.merged_prs;
+        closed_prs = acc.closed_prs + s.closed_prs;
+        draft_prs = acc.draft_prs + s.draft_prs;
+        total_discussions = acc.total_discussions + s.total_discussions;
+        answered_discussions = acc.answered_discussions + s.answered_discussions;
+        total_releases = acc.total_releases + s.total_releases;
+        total_users = acc.total_users + s.total_users;
+        total_additions = acc.total_additions + s.total_additions;
+        total_deletions = acc.total_deletions + s.total_deletions;
+        total_files_changed = acc.total_files_changed + s.total_files_changed;
+      })
+    empty_stats stats_list
+
+let pp_stats ppf s =
+  Fmt.pf ppf "@[<v>\
+    Issues:      %d total (%d open, %d closed)@,\
+    Pull Reqs:   %d total (%d open, %d merged, %d closed, %d draft)@,\
+    Discussions: %d total (%d answered)@,\
+    Releases:    %d@,\
+    Users:       %d@,\
+    Code:        +%d -%d (%d files)@]"
+    s.total_issues s.open_issues s.closed_issues
+    s.total_prs s.open_prs s.merged_prs s.closed_prs s.draft_prs
+    s.total_discussions s.answered_discussions
+    s.total_releases s.total_users
+    s.total_additions s.total_deletions s.total_files_changed
+
+let pp_stats_compact ppf s =
+  Fmt.pf ppf "I:%d P:%d D:%d R:%d (+%d -%d)"
+    s.total_issues s.total_prs s.total_discussions s.total_releases
+    s.total_additions s.total_deletions

repowatch/lib/printer.mli

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+(** Pretty-printing for GitHub activity data.
+
+    This module provides formatters for displaying activity data in
+    human-readable formats. *)
+
+(** {1 Basic Formatters} *)
+
+val pp_metadata : Types.Metadata.t Fmt.t
+(** Format metadata information. *)
+
+val pp_issue : Types.Issue.t Fmt.t
+(** Format an issue. *)
+
+val pp_issue_short : Types.Issue.t Fmt.t
+(** Format an issue in short form (one line). *)
+
+val pp_pr : Types.Pr.t Fmt.t
+(** Format a pull request. *)
+
+val pp_pr_short : Types.Pr.t Fmt.t
+(** Format a pull request in short form (one line). *)
+
+val pp_discussion : Types.Discussion.t Fmt.t
+(** Format a discussion. *)
+
+val pp_discussion_short : Types.Discussion.t Fmt.t
+(** Format a discussion in short form (one line). *)
+
+val pp_asset : Types.Asset.t Fmt.t
+(** Format a release asset. *)
+
+val pp_release : Types.Release.t Fmt.t
+(** Format a release. *)
+
+val pp_release_short : Types.Release.t Fmt.t
+(** Format a release in short form (one line). *)
+
+(** {1 Summary Formatters} *)
+
+val pp_week_summary : Types.Week_data.t Fmt.t
+(** Format a summary of weekly activity. *)
+
+val pp_week_data : Types.Week_data.t Fmt.t
+(** Format complete weekly data. *)
+
+(** {1 Statistics} *)
+
+type stats = {
+  total_issues : int;
+  open_issues : int;
+  closed_issues : int;
+  total_prs : int;
+  open_prs : int;
+  merged_prs : int;
+  closed_prs : int;
+  draft_prs : int;
+  total_discussions : int;
+  answered_discussions : int;
+  total_releases : int;
+  total_users : int;
+  total_additions : int;
+  total_deletions : int;
+  total_files_changed : int;
+}
+(** Statistics computed from weekly data. *)
+
+val compute_stats : Types.Week_data.t -> stats
+(** Compute statistics from weekly data. *)
+
+val aggregate_stats : stats list -> stats
+(** Aggregate multiple stats into one. *)
+
+val pp_stats : stats Fmt.t
+(** Format statistics. *)
+
+val pp_stats_compact : stats Fmt.t
+(** Format statistics in compact form. *)

repowatch/lib/repowatch.ml

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+(** Repowatch - GitHub repository activity watcher and analyzer.
+
+    This library provides types and utilities for parsing and analyzing
+    GitHub repository activity data in the ruminant JSON format. *)
+
+module Types = Types
+module Codec = Codec
+module Loader = Loader
+module Config = Config
+module Printer = Printer
+module Week = Week
+module Graphql_types = Graphql_types
+module Graphql_codec = Graphql_codec
+module Graphql = Graphql
+module Filter = Filter
+module Transform = Transform
+module Github = Github
+module Storage = Storage
+module Users = Users
+module Sync = Sync

repowatch/lib/storage.ml

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+let data_dir ~base_dir ~owner ~repo =
+  Eio.Path.(base_dir / "gh" / owner / repo)
+
+let week_filename ~week =
+  Printf.sprintf "week-%02d-%04d.json" (Week.week week) (Week.year week)
+
+let ensure_dir path =
+  (* Create directory tree if it doesn't exist *)
+  try Eio.Path.mkdirs ~exists_ok:true ~perm:0o755 path
+  with Eio.Io _ -> ()
+
+let save_week ~fs ~base_dir ~owner ~repo ~week ~data =
+  let dir = data_dir ~base_dir:(Eio.Path.(fs / base_dir)) ~owner ~repo in
+  ensure_dir dir;
+  let filename = week_filename ~week in
+  let filepath = Eio.Path.(dir / filename) in
+  let json = Codec.encode_string data in
+  Eio.Path.save ~create:(`Or_truncate 0o644) filepath json
+
+let load_week ~fs ~base_dir ~owner ~repo ~week =
+  let dir = data_dir ~base_dir:(Eio.Path.(fs / base_dir)) ~owner ~repo in
+  let filename = week_filename ~week in
+  let filepath = Eio.Path.(dir / filename) in
+  try
+    let content = Eio.Path.load filepath in
+    match Codec.decode_string content with
+    | Ok data -> Some data
+    | Error _ -> None
+  with Eio.Io _ -> None
+
+let parse_week_filename filename =
+  (* Parse "week-WW-YYYY.json" *)
+  try
+    if String.length filename < 17 then None
+    else if not (String.sub filename 0 5 = "week-") then None
+    else if not (String.sub filename (String.length filename - 5) 5 = ".json")
+    then None
+    else
+      let week_str = String.sub filename 5 2 in
+      let year_str = String.sub filename 8 4 in
+      let week_num = int_of_string week_str in
+      let year = int_of_string year_str in
+      Some (Week.of_year_week ~year ~week:week_num)
+  with _ -> None
+
+let list_cached_weeks ~fs ~base_dir ~owner ~repo =
+  let dir = data_dir ~base_dir:(Eio.Path.(fs / base_dir)) ~owner ~repo in
+  try
+    let entries = Eio.Path.read_dir dir in
+    entries
+    |> List.filter_map parse_week_filename
+    |> List.sort Week.compare
+  with Eio.Io _ -> []

repowatch/lib/storage.mli

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+(** Persistent storage for sync results.
+
+    This module provides functions to save and load weekly repository data
+    in the ruminant JSON format, maintaining the directory structure
+    [data/gh/{owner}/{repo}/]. *)
+
+(** {1 Path Construction} *)
+
+val data_dir :
+  base_dir:Eio.Fs.dir_ty Eio.Path.t ->
+  owner:string ->
+  repo:string ->
+  Eio.Fs.dir_ty Eio.Path.t
+(** [data_dir ~base_dir ~owner ~repo] returns the directory path for
+    repository data: [base_dir/gh/{owner}/{repo}/]. *)
+
+val week_filename : week:Week.t -> string
+(** [week_filename ~week] returns the filename for a week's data:
+    [week-{WW}-{YYYY}.json]. *)
+
+(** {1 Saving Data} *)
+
+val save_week :
+  fs:Eio.Fs.dir_ty Eio.Path.t ->
+  base_dir:string ->
+  owner:string ->
+  repo:string ->
+  week:Week.t ->
+  data:Types.Week_data.t ->
+  unit
+(** [save_week ~fs ~base_dir ~owner ~repo ~week ~data] saves the weekly
+    data to a JSON file, creating directories as needed.
+
+    The file is written to [{base_dir}/gh/{owner}/{repo}/week-{WW}-{YYYY}.json]. *)
+
+(** {1 Loading Data} *)
+
+val load_week :
+  fs:Eio.Fs.dir_ty Eio.Path.t ->
+  base_dir:string ->
+  owner:string ->
+  repo:string ->
+  week:Week.t ->
+  Types.Week_data.t option
+(** [load_week ~fs ~base_dir ~owner ~repo ~week] loads existing week data
+    if present. Returns [None] if the file does not exist. *)
+
+val list_cached_weeks :
+  fs:Eio.Fs.dir_ty Eio.Path.t ->
+  base_dir:string ->
+  owner:string ->
+  repo:string ->
+  Week.t list
+(** [list_cached_weeks ~fs ~base_dir ~owner ~repo] lists all cached weeks
+    for a repository, sorted by date. *)
+
+(** {1 Directory Management} *)
+
+val ensure_dir : Eio.Fs.dir_ty Eio.Path.t -> unit
+(** [ensure_dir path] creates the directory and all parent directories
+    if they don't exist. *)

repowatch/lib/sync.ml

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+module G = Graphql_types
+
+type phase =
+  [ `Issues_prs
+  | `Discussions
+  | `Releases
+  | `Users
+  ]
+
+type progress = { phase : phase; current : int; total : int option }
+
+type sync_result = {
+  week_data : Types.Week_data.t;
+  issues_fetched : int;
+  prs_fetched : int;
+  pages_fetched : int;
+  rate_limit_remaining : int option;
+}
+
+let max_pages = 20
+let early_exit_threshold = 5
+
+(* Pagination state for issues/PRs sync *)
+type pagination_state = {
+  mutable issues_cursor : string option;
+  mutable prs_cursor : string option;
+  mutable issues_done : bool;
+  mutable prs_done : bool;
+  mutable pages_without_activity : int;
+}
+
+let sync_issues_prs ~client ~owner ~repo ~week ~on_progress =
+  let state =
+    {
+      issues_cursor = None;
+      prs_cursor = None;
+      issues_done = false;
+      prs_done = false;
+      pages_without_activity = 0;
+    }
+  in
+  let all_issues = ref [] in
+  let all_prs = ref [] in
+  let rec loop page_count =
+    if page_count >= max_pages then Ok page_count
+    else if state.issues_done && state.prs_done then Ok page_count
+    else if state.pages_without_activity >= early_exit_threshold then
+      Ok page_count
+    else
+      let variables =
+        Graphql.
+          {
+            owner;
+            name = repo;
+            issues_after = state.issues_cursor;
+            prs_after = state.prs_cursor;
+          }
+      in
+      Option.iter
+        (fun f ->
+          f { phase = `Issues_prs; current = page_count + 1; total = None })
+        on_progress;
+      match Github.graphql client ~query:Graphql.issues_prs_query ~variables with
+      | Error e -> Error e
+      | Ok response_body -> (
+          match Graphql_codec.decode_repository_response response_body with
+          | Error msg -> Error (Github.Parse_error msg)
+          | Ok response ->
+              (* Process issues *)
+              let issues_conn = G.Repository_response.issues response in
+              let issues_page_info = G.Issues_connection.page_info issues_conn in
+              let issue_nodes = G.Issues_connection.nodes issues_conn in
+              let new_issues =
+                List.filter (Filter.issue_active_in_week ~week) issue_nodes
+              in
+              all_issues := !all_issues @ new_issues;
+              (* Update issues pagination *)
+              if G.Page_info.has_next_page issues_page_info then
+                state.issues_cursor <- G.Page_info.end_cursor issues_page_info
+              else state.issues_done <- true;
+              (* Process PRs *)
+              let prs_conn = G.Repository_response.pull_requests response in
+              let prs_page_info = G.Prs_connection.page_info prs_conn in
+              let pr_nodes = G.Prs_connection.nodes prs_conn in
+              let new_prs =
+                List.filter (Filter.pr_active_in_week ~week) pr_nodes
+              in
+              all_prs := !all_prs @ new_prs;
+              (* Update PRs pagination *)
+              if G.Page_info.has_next_page prs_page_info then
+                state.prs_cursor <- G.Page_info.end_cursor prs_page_info
+              else state.prs_done <- true;
+              (* Track activity for early exit *)
+              if List.length new_issues = 0 && List.length new_prs = 0 then
+                state.pages_without_activity <-
+                  state.pages_without_activity + 1
+              else state.pages_without_activity <- 0;
+              loop (page_count + 1))
+  in
+  match loop 0 with
+  | Ok pages -> Ok (!all_issues, !all_prs, pages)
+  | Error e -> Error e
+
+let sync_discussions ~client ~owner ~repo ~week ~on_progress =
+  let variables =
+    Graphql.{ owner; name = repo; issues_after = None; prs_after = None }
+  in
+  Option.iter
+    (fun f -> f { phase = `Discussions; current = 1; total = Some 1 })
+    on_progress;
+  match Github.graphql client ~query:Graphql.discussions_query ~variables with
+  | Error e -> Error e
+  | Ok response_body -> (
+      match Graphql_codec.decode_discussions_response response_body with
+      | Error msg -> Error (Github.Parse_error msg)
+      | Ok response ->
+          let discussions = G.Discussions_response.discussions response in
+          let active =
+            List.filter (Filter.discussion_active_in_week ~week) discussions
+          in
+          Ok active)
+
+let sync_releases ~client ~owner ~repo ~week ~on_progress =
+  let week_start = Week.start_ptime week in
+  let week_end = Week.end_ptime week in
+  let rec loop page acc =
+    if page > 5 then
+      (* Max 5 pages of releases *)
+      Ok acc
+    else (
+      Option.iter
+        (fun f -> f { phase = `Releases; current = page; total = None })
+        on_progress;
+      match Github.get_releases client ~owner ~repo ~page with
+      | Error e -> Error e
+      | Ok response_body -> (
+          match Jsont_bytesrw.decode_string (Jsont.list Jsont.json) response_body
+          with
+          | Error msg -> Error (Github.Parse_error msg)
+          | Ok releases_json ->
+              if List.length releases_json = 0 then Ok acc
+              else
+                let releases =
+                  List.filter_map Transform.release_of_json releases_json
+                in
+                (* Filter by week *)
+                let active =
+                  List.filter
+                    (fun r ->
+                      match
+                        Ptime.of_rfc3339 (Types.Release.published_at r)
+                      with
+                      | Ok (t, _, _) ->
+                          Ptime.compare t week_start >= 0
+                          && Ptime.compare t week_end <= 0
+                      | Error _ -> false)
+                    releases
+                in
+                (* Check if all releases are before the week *)
+                let all_before =
+                  List.for_all
+                    (fun r ->
+                      match
+                        Ptime.of_rfc3339 (Types.Release.published_at r)
+                      with
+                      | Ok (t, _, _) -> Ptime.compare t week_start < 0
+                      | Error _ -> true)
+                    releases
+                in
+                if all_before then Ok (acc @ active)
+                else loop (page + 1) (acc @ active)))
+  in
+  loop 1 []
+
+let sync_week ~client ~owner ~repo ~week ?on_progress () =
+  (* Sync issues and PRs *)
+  match sync_issues_prs ~client ~owner ~repo ~week ~on_progress with
+  | Error e -> Error e
+  | Ok (issue_nodes, pr_nodes, pages) -> (
+      (* Sync discussions *)
+      match sync_discussions ~client ~owner ~repo ~week ~on_progress with
+      | Error e -> Error e
+      | Ok discussion_nodes -> (
+          (* Sync releases *)
+          match sync_releases ~client ~owner ~repo ~week ~on_progress with
+          | Error e -> Error e
+          | Ok releases ->
+              (* Transform to Types *)
+              let issues = List.map Transform.issue_of_node issue_nodes in
+              let prs = List.map Transform.pr_of_node pr_nodes in
+              let discussions =
+                List.map Transform.discussion_of_node discussion_nodes
+              in
+              let good_first_issues =
+                issue_nodes
+                |> List.filter Filter.is_good_first_issue
+                |> List.map Transform.issue_of_node
+              in
+              (* Get current time for metadata *)
+              let cached_at =
+                Option.value
+                  (Ptime.of_float_s (Unix.gettimeofday ()))
+                  ~default:Ptime.epoch
+              in
+              let metadata =
+                Transform.make_metadata ~owner ~repo ~week ~cached_at
+              in
+              (* Create week data *)
+              let week_data =
+                Types.Week_data.make ~metadata ~issues ~prs ~good_first_issues
+                  ~discussions ~releases ~users:[]
+              in
+              (* Extract users *)
+              let users = Users.extract_from_week_data week_data in
+              let week_data =
+                Types.Week_data.make ~metadata ~issues ~prs ~good_first_issues
+                  ~discussions ~releases ~users
+              in
+              Ok
+                {
+                  week_data;
+                  issues_fetched = List.length issue_nodes;
+                  prs_fetched = List.length pr_nodes;
+                  pages_fetched = pages;
+                  rate_limit_remaining = Github.rate_limit_remaining client;
+                }))
+
+let sync_range ~client ~owner ~repo ~from_week ~to_week ?on_progress () =
+  let weeks = Week.range ~from:from_week ~to_:to_week in
+  let rec loop results = function
+    | [] -> Ok (List.rev results)
+    | week :: rest -> (
+        match sync_week ~client ~owner ~repo ~week ?on_progress () with
+        | Error e -> Error e
+        | Ok result -> loop (result :: results) rest)
+  in
+  loop [] weeks
+
+(* Merge utilities for incremental sync *)
+
+let merge_issues ~existing ~new_items =
+  (* Build a map of new items by ID *)
+  let new_map =
+    List.fold_left
+      (fun acc item -> (Types.Issue.id item, item) :: acc)
+      [] new_items
+  in
+  (* Keep existing items that aren't in new, then add all new *)
+  let existing_filtered =
+    List.filter
+      (fun item -> not (List.mem_assoc (Types.Issue.id item) new_map))
+      existing
+  in
+  existing_filtered @ new_items
+
+let merge_prs ~existing ~new_items =
+  let new_map =
+    List.fold_left (fun acc item -> (Types.Pr.id item, item) :: acc) [] new_items
+  in
+  let existing_filtered =
+    List.filter
+      (fun item -> not (List.mem_assoc (Types.Pr.id item) new_map))
+      existing
+  in
+  existing_filtered @ new_items
+
+let merge_discussions ~existing ~new_items =
+  let new_map =
+    List.fold_left
+      (fun acc item -> (Types.Discussion.id item, item) :: acc)
+      [] new_items
+  in
+  let existing_filtered =
+    List.filter
+      (fun item -> not (List.mem_assoc (Types.Discussion.id item) new_map))
+      existing
+  in
+  existing_filtered @ new_items
+
+let merge_releases ~existing ~new_items =
+  let new_map =
+    List.fold_left
+      (fun acc item -> (Types.Release.tag_name item, item) :: acc)
+      [] new_items
+  in
+  let existing_filtered =
+    List.filter
+      (fun item -> not (List.mem_assoc (Types.Release.tag_name item) new_map))
+      existing
+  in
+  existing_filtered @ new_items
+
+let merge_users ~existing ~new_items =
+  List.sort_uniq String.compare (existing @ new_items)
+
+let merge_week_data ~existing new_data =
+  let issues =
+    merge_issues
+      ~existing:(Types.Week_data.issues existing)
+      ~new_items:(Types.Week_data.issues new_data)
+  in
+  let prs =
+    merge_prs
+      ~existing:(Types.Week_data.prs existing)
+      ~new_items:(Types.Week_data.prs new_data)
+  in
+  let good_first_issues =
+    merge_issues
+      ~existing:(Types.Week_data.good_first_issues existing)
+      ~new_items:(Types.Week_data.good_first_issues new_data)
+  in
+  let discussions =
+    merge_discussions
+      ~existing:(Types.Week_data.discussions existing)
+      ~new_items:(Types.Week_data.discussions new_data)
+  in
+  let releases =
+    merge_releases
+      ~existing:(Types.Week_data.releases existing)
+      ~new_items:(Types.Week_data.releases new_data)
+  in
+  let users =
+    merge_users
+      ~existing:(Types.Week_data.users existing)
+      ~new_items:(Types.Week_data.users new_data)
+  in
+  (* Use the new metadata (has updated cached_at timestamp) *)
+  let metadata = Types.Week_data.metadata new_data in
+  Types.Week_data.make ~metadata ~issues ~prs ~good_first_issues ~discussions
+    ~releases ~users
+
+let sync_week_incremental ~client ~owner ~repo ~week ~existing ?on_progress () =
+  match sync_week ~client ~owner ~repo ~week ?on_progress () with
+  | Error e -> Error e
+  | Ok result ->
+      let merged_data =
+        match existing with
+        | None -> result.week_data
+        | Some existing_data -> merge_week_data ~existing:existing_data result.week_data
+      in
+      Ok { result with week_data = merged_data }

repowatch/lib/sync.mli

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+(** Repository sync engine.
+
+    This module provides the sync engine for fetching repository data from
+    GitHub and transforming it into the ruminant format. It handles pagination,
+    rate limiting, and week-based filtering. *)
+
+(** {1 Progress Reporting} *)
+
+type phase =
+  [ `Issues_prs
+  | `Discussions
+  | `Releases
+  | `Users
+  ]
+(** Sync phases. *)
+
+type progress = {
+  phase : phase;  (** Current sync phase. *)
+  current : int;  (** Current page or item number. *)
+  total : int option;  (** Total pages/items if known. *)
+}
+(** Progress information for sync callbacks. *)
+
+(** {1 Sync Results} *)
+
+type sync_result = {
+  week_data : Types.Week_data.t;  (** The synced week data. *)
+  issues_fetched : int;  (** Number of issues fetched. *)
+  prs_fetched : int;  (** Number of PRs fetched. *)
+  pages_fetched : int;  (** Total GraphQL pages fetched. *)
+  rate_limit_remaining : int option;  (** Rate limit remaining after sync. *)
+}
+(** Result of a successful sync operation. *)
+
+(** {1 Sync Operations} *)
+
+val sync_week :
+  client:Github.t ->
+  owner:string ->
+  repo:string ->
+  week:Week.t ->
+  ?on_progress:(progress -> unit) ->
+  unit ->
+  (sync_result, Github.error) result
+(** [sync_week ~client ~owner ~repo ~week ()] fetches all repository
+    activity for the given week.
+
+    This function:
+    - Queries GitHub GraphQL API for issues and PRs with pagination
+    - Queries for discussions (single page)
+    - Fetches releases via REST API
+    - Filters all data to include only items active during the week
+    - Extracts usernames from the data
+
+    @param client GitHub API client
+    @param owner Repository owner (user or organization)
+    @param repo Repository name
+    @param week ISO week to sync
+    @param on_progress Optional callback for progress updates *)
+
+val sync_range :
+  client:Github.t ->
+  owner:string ->
+  repo:string ->
+  from_week:Week.t ->
+  to_week:Week.t ->
+  ?on_progress:(progress -> unit) ->
+  unit ->
+  (sync_result list, Github.error) result
+(** [sync_range ~client ~owner ~repo ~from_week ~to_week ()] syncs a
+    range of weeks. Stops on the first error. *)
+
+(** {1 Incremental Sync} *)
+
+val merge_week_data : existing:Types.Week_data.t -> Types.Week_data.t -> Types.Week_data.t
+(** [merge_week_data ~existing new_data] merges new data into existing data.
+
+    Merging rules:
+    - Issues/PRs/Discussions: newer entries (by ID) replace older ones
+    - Releases: deduplicated by tag_name, newer replaces older
+    - Users: union of both lists
+    - Metadata: uses the new data's metadata (updated cached_at) *)
+
+val sync_week_incremental :
+  client:Github.t ->
+  owner:string ->
+  repo:string ->
+  week:Week.t ->
+  existing:Types.Week_data.t option ->
+  ?on_progress:(progress -> unit) ->
+  unit ->
+  (sync_result, Github.error) result
+(** [sync_week_incremental ~client ~owner ~repo ~week ~existing ()]
+    fetches repository activity and merges with existing data if present.
+
+    This is designed for daily cron jobs that incrementally update the
+    current week's data. New items are added and existing items are
+    updated with fresh data from GitHub. *)
+
+(** {1 Configuration} *)
+
+val max_pages : int
+(** Maximum number of GraphQL pages to fetch (default: 20). *)
+
+val early_exit_threshold : int
+(** Number of pages without relevant activity before stopping early
+    (default: 5). *)

repowatch/lib/transform.ml

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+module G = Graphql_types
+
+let format_comment ~author ~body =
+  Printf.sprintf "@%s: %s" author body
+
+let issue_of_node node =
+  let labels =
+    List.map G.Label.name (G.Issue_node.labels node)
+  in
+  let comments =
+    List.map
+      (fun c ->
+        format_comment
+          ~author:(G.Author.login (G.Comment.author c))
+          ~body:(G.Comment.body_text c))
+      (G.Issue_node.comments node)
+  in
+  let state = String.lowercase_ascii (G.Issue_node.state node) in
+  Types.Issue.make
+    ~id:(G.Issue_node.number node)
+    ~title:(G.Issue_node.title node)
+    ~url:(G.Issue_node.url node)
+    ~user:(G.Author.login (G.Issue_node.author node))
+    ~created_at:(G.Issue_node.created_at node)
+    ~updated_at:(G.Issue_node.updated_at node)
+    ~closed_at:(G.Issue_node.closed_at node)
+    ~body:(G.Issue_node.body_text node)
+    ~labels
+    ~state
+    ~comments
+
+let pr_of_node node =
+  let labels =
+    List.map G.Label.name (G.Pr_node.labels node)
+  in
+  let comments =
+    List.map
+      (fun c ->
+        format_comment
+          ~author:(G.Author.login (G.Comment.author c))
+          ~body:(G.Comment.body_text c))
+      (G.Pr_node.comments node)
+  in
+  (* Normalize state: GraphQL returns "OPEN", "CLOSED", "MERGED" *)
+  let state =
+    let raw_state = G.Pr_node.state node in
+    match String.lowercase_ascii raw_state with
+    | "merged" -> "merged"
+    | "closed" ->
+        (* Check if it was merged even though state is CLOSED *)
+        if Option.is_some (G.Pr_node.merged_at node) then "merged"
+        else "closed"
+    | _ -> "open"
+  in
+  Types.Pr.make
+    ~id:(G.Pr_node.number node)
+    ~title:(G.Pr_node.title node)
+    ~url:(G.Pr_node.url node)
+    ~user:(G.Author.login (G.Pr_node.author node))
+    ~created_at:(G.Pr_node.created_at node)
+    ~updated_at:(G.Pr_node.updated_at node)
+    ~closed_at:(G.Pr_node.closed_at node)
+    ~merged_at:(G.Pr_node.merged_at node)
+    ~body:(G.Pr_node.body_text node)
+    ~labels
+    ~state
+    ~comments
+    ~additions:(G.Pr_node.additions node)
+    ~deletions:(G.Pr_node.deletions node)
+    ~changed_files:(G.Pr_node.changed_files node)
+    ~mergeable:(G.Pr_node.mergeable node)
+    ~draft:(G.Pr_node.is_draft node)
+
+let discussion_of_node node =
+  Types.Discussion.make
+    ~id:(G.Discussion_node.number node)
+    ~title:(G.Discussion_node.title node)
+    ~url:(G.Discussion_node.url node)
+    ~user:(G.Author.login (G.Discussion_node.author node))
+    ~updated_at:(G.Discussion_node.updated_at node)
+    ~body:(G.Discussion_node.body_text node)
+    ~category:(G.Discussion_node.category node)
+    ~comments:(G.Discussion_node.comments_count node)
+    ~answered:(G.Discussion_node.answered node)
+
+(* Codec for REST API release *)
+let nullable_string = Jsont.option Jsont.string
+
+let rest_asset =
+  Jsont.Object.map ~kind:"RestAsset"
+    (fun name download_count size ->
+      Types.Asset.make ~name ~download_count ~size)
+  |> Jsont.Object.mem "name" Jsont.string ~enc:Types.Asset.name
+  |> Jsont.Object.mem "download_count" Jsont.int ~enc:Types.Asset.download_count
+  |> Jsont.Object.mem "size" Jsont.int ~enc:Types.Asset.size
+  |> Jsont.Object.finish
+
+let rest_author_login =
+  Jsont.Object.map ~kind:"RestAuthor" (fun login -> login)
+  |> Jsont.Object.mem "login" Jsont.string ~enc:(fun x -> x)
+  |> Jsont.Object.finish
+
+let rest_release =
+  Jsont.Object.map ~kind:"RestRelease"
+    (fun tag_name name published_at author html_url body prerelease draft assets ->
+      let name = Option.value name ~default:tag_name in
+      let body = Option.value body ~default:"" in
+      Types.Release.make ~tag_name ~name ~published_at ~author ~html_url ~body
+        ~prerelease ~draft ~assets)
+  |> Jsont.Object.mem "tag_name" Jsont.string ~enc:Types.Release.tag_name
+  |> Jsont.Object.mem "name" nullable_string ~dec_absent:None
+       ~enc:(fun r -> Some (Types.Release.name r))
+  |> Jsont.Object.mem "published_at" Jsont.string ~enc:Types.Release.published_at
+  |> Jsont.Object.mem "author" rest_author_login ~enc:Types.Release.author
+  |> Jsont.Object.mem "html_url" Jsont.string ~enc:Types.Release.html_url
+  |> Jsont.Object.mem "body" nullable_string ~dec_absent:None
+       ~enc:(fun r -> Some (Types.Release.body r))
+  |> Jsont.Object.mem "prerelease" Jsont.bool ~enc:Types.Release.prerelease
+  |> Jsont.Object.mem "draft" Jsont.bool ~enc:Types.Release.draft
+  |> Jsont.Object.mem "assets" (Jsont.list rest_asset) ~enc:Types.Release.assets
+  |> Jsont.Object.finish
+
+let release_of_json json =
+  match Jsont.Json.decode rest_release json with
+  | Ok release -> Some release
+  | Error _ -> None
+
+let ptime_to_iso8601 t =
+  let (y, m, d), ((hh, mm, ss), _tz) = Ptime.to_date_time t in
+  Printf.sprintf "%04d-%02d-%02dT%02d:%02d:%02dZ" y m d hh mm ss
+
+let make_metadata ~owner ~repo ~week ~cached_at =
+  Types.Metadata.make
+    ~repo:(Printf.sprintf "%s/%s" owner repo)
+    ~year:(Week.year week)
+    ~week:(Week.week week)
+    ~week_start:(Week.start_date week)
+    ~week_end:(Week.end_date week)
+    ~cached_at:(ptime_to_iso8601 cached_at)
+
+let issues_of_nodes ~week nodes =
+  nodes
+  |> List.filter (Filter.issue_active_in_week ~week)
+  |> List.map issue_of_node
+
+let prs_of_nodes ~week nodes =
+  nodes
+  |> List.filter (Filter.pr_active_in_week ~week)
+  |> List.map pr_of_node
+
+let discussions_of_nodes ~week nodes =
+  nodes
+  |> List.filter (Filter.discussion_active_in_week ~week)
+  |> List.map discussion_of_node

repowatch/lib/transform.mli

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+(** Transform GraphQL responses to repowatch types.
+
+    This module provides functions to convert the raw GraphQL response types
+    into the normalized [Types] representations used for storage and analysis. *)
+
+(** {1 Issue Transformation} *)
+
+val issue_of_node : Graphql_types.Issue_node.t -> Types.Issue.t
+(** [issue_of_node node] converts a GraphQL issue node to [Types.Issue.t].
+
+    Comments are formatted as "@author: body" strings. *)
+
+(** {1 Pull Request Transformation} *)
+
+val pr_of_node : Graphql_types.Pr_node.t -> Types.Pr.t
+(** [pr_of_node node] converts a GraphQL PR node to [Types.Pr.t].
+
+    The state is normalized to lowercase ("open", "closed", "merged"). *)
+
+(** {1 Discussion Transformation} *)
+
+val discussion_of_node : Graphql_types.Discussion_node.t -> Types.Discussion.t
+(** [discussion_of_node node] converts a GraphQL discussion node to
+    [Types.Discussion.t]. *)
+
+(** {1 Release Transformation} *)
+
+val release_of_json : Jsont.Json.t -> Types.Release.t option
+(** [release_of_json json] attempts to decode a release from the GitHub REST
+    API JSON format. Returns [None] if decoding fails. *)
+
+(** {1 Comment Formatting} *)
+
+val format_comment : author:string -> body:string -> string
+(** [format_comment ~author ~body] formats a comment as "@author: body". *)
+
+(** {1 Metadata Construction} *)
+
+val make_metadata :
+  owner:string ->
+  repo:string ->
+  week:Week.t ->
+  cached_at:Ptime.t ->
+  Types.Metadata.t
+(** [make_metadata ~owner ~repo ~week ~cached_at] creates metadata for a
+    weekly snapshot. *)
+
+(** {1 Batch Transformation} *)
+
+val issues_of_nodes :
+  week:Week.t -> Graphql_types.Issue_node.t list -> Types.Issue.t list
+(** [issues_of_nodes ~week nodes] filters and transforms issues that were
+    active during the given week. *)
+
+val prs_of_nodes :
+  week:Week.t -> Graphql_types.Pr_node.t list -> Types.Pr.t list
+(** [prs_of_nodes ~week nodes] filters and transforms PRs that were
+    active during the given week. *)
+
+val discussions_of_nodes :
+  week:Week.t ->
+  Graphql_types.Discussion_node.t list ->
+  Types.Discussion.t list
+(** [discussions_of_nodes ~week nodes] filters and transforms discussions
+    that were updated during the given week. *)

repowatch/lib/types.ml

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+module Metadata = struct
+  type t = {
+    repo : string;
+    year : int;
+    week : int;
+    week_start : string;
+    week_end : string;
+    cached_at : string;
+  }
+
+  let make ~repo ~year ~week ~week_start ~week_end ~cached_at =
+    { repo; year; week; week_start; week_end; cached_at }
+
+  let repo t = t.repo
+  let year t = t.year
+  let week t = t.week
+  let week_start t = t.week_start
+  let week_end t = t.week_end
+  let cached_at t = t.cached_at
+end
+
+module Issue = struct
+  type t = {
+    id : int;
+    title : string;
+    url : string;
+    user : string;
+    created_at : string;
+    updated_at : string;
+    closed_at : string option;
+    body : string;
+    labels : string list;
+    state : string;
+    comments : string list;
+  }
+
+  let make ~id ~title ~url ~user ~created_at ~updated_at ~closed_at ~body
+      ~labels ~state ~comments =
+    { id; title; url; user; created_at; updated_at; closed_at; body; labels;
+      state; comments }
+
+  let id t = t.id
+  let title t = t.title
+  let url t = t.url
+  let user t = t.user
+  let created_at t = t.created_at
+  let updated_at t = t.updated_at
+  let closed_at t = t.closed_at
+  let body t = t.body
+  let labels t = t.labels
+  let state t = t.state
+  let comments t = t.comments
+end
+
+module Pr = struct
+  type t = {
+    id : int;
+    title : string;
+    url : string;
+    user : string;
+    created_at : string;
+    updated_at : string;
+    closed_at : string option;
+    merged_at : string option;
+    body : string;
+    labels : string list;
+    state : string;
+    comments : string list;
+    additions : int;
+    deletions : int;
+    changed_files : int;
+    mergeable : string;
+    draft : bool;
+  }
+
+  let make ~id ~title ~url ~user ~created_at ~updated_at ~closed_at ~merged_at
+      ~body ~labels ~state ~comments ~additions ~deletions ~changed_files
+      ~mergeable ~draft =
+    { id; title; url; user; created_at; updated_at; closed_at; merged_at;
+      body; labels; state; comments; additions; deletions; changed_files;
+      mergeable; draft }
+
+  let id t = t.id
+  let title t = t.title
+  let url t = t.url
+  let user t = t.user
+  let created_at t = t.created_at
+  let updated_at t = t.updated_at
+  let closed_at t = t.closed_at
+  let merged_at t = t.merged_at
+  let body t = t.body
+  let labels t = t.labels
+  let state t = t.state
+  let comments t = t.comments
+  let additions t = t.additions
+  let deletions t = t.deletions
+  let changed_files t = t.changed_files
+  let mergeable t = t.mergeable
+  let draft t = t.draft
+end
+
+module Discussion = struct
+  type t = {
+    id : int;
+    title : string;
+    url : string;
+    user : string;
+    updated_at : string;
+    body : string;
+    category : string;
+    comments : int;
+    answered : bool;
+  }
+
+  let make ~id ~title ~url ~user ~updated_at ~body ~category ~comments ~answered =
+    { id; title; url; user; updated_at; body; category; comments; answered }
+
+  let id t = t.id
+  let title t = t.title
+  let url t = t.url
+  let user t = t.user
+  let updated_at t = t.updated_at
+  let body t = t.body
+  let category t = t.category
+  let comments t = t.comments
+  let answered t = t.answered
+end
+
+module Asset = struct
+  type t = {
+    name : string;
+    download_count : int;
+    size : int;
+  }
+
+  let make ~name ~download_count ~size = { name; download_count; size }
+  let name t = t.name
+  let download_count t = t.download_count
+  let size t = t.size
+end
+
+module Release = struct
+  type t = {
+    tag_name : string;
+    name : string;
+    published_at : string;
+    author : string;
+    html_url : string;
+    body : string;
+    prerelease : bool;
+    draft : bool;
+    assets : Asset.t list;
+  }
+
+  let make ~tag_name ~name ~published_at ~author ~html_url ~body ~prerelease
+      ~draft ~assets =
+    { tag_name; name; published_at; author; html_url; body; prerelease; draft;
+      assets }
+
+  let tag_name t = t.tag_name
+  let name t = t.name
+  let published_at t = t.published_at
+  let author t = t.author
+  let html_url t = t.html_url
+  let body t = t.body
+  let prerelease t = t.prerelease
+  let draft t = t.draft
+  let assets t = t.assets
+end
+
+module Week_data = struct
+  type t = {
+    metadata : Metadata.t;
+    issues : Issue.t list;
+    prs : Pr.t list;
+    good_first_issues : Issue.t list;
+    discussions : Discussion.t list;
+    releases : Release.t list;
+    users : string list;
+  }
+
+  let make ~metadata ~issues ~prs ~good_first_issues ~discussions ~releases
+      ~users =
+    { metadata; issues; prs; good_first_issues; discussions; releases; users }
+
+  let metadata t = t.metadata
+  let issues t = t.issues
+  let prs t = t.prs
+  let good_first_issues t = t.good_first_issues
+  let discussions t = t.discussions
+  let releases t = t.releases
+  let users t = t.users
+end

repowatch/lib/types.mli

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+(** Type definitions for GitHub repository activity data.
+
+    These types correspond to the JSON schema used by the ruminant data format
+    for weekly repository activity snapshots. *)
+
+(** {1 Metadata} *)
+
+module Metadata : sig
+  type t
+  (** Metadata about a weekly activity snapshot. *)
+
+  val make :
+    repo:string ->
+    year:int ->
+    week:int ->
+    week_start:string ->
+    week_end:string ->
+    cached_at:string ->
+    t
+  (** Create metadata for a weekly snapshot.
+
+      @param repo Repository in "owner/repo" format
+      @param year The year
+      @param week ISO week number (1-53)
+      @param week_start Start date in ISO 8601 format
+      @param week_end End date in ISO 8601 format
+      @param cached_at Timestamp when data was cached *)
+
+  val repo : t -> string
+  (** Repository identifier in "owner/repo" format. *)
+
+  val year : t -> int
+  (** The year this snapshot covers. *)
+
+  val week : t -> int
+  (** ISO week number (1-53). *)
+
+  val week_start : t -> string
+  (** Start date of the week in ISO 8601 format. *)
+
+  val week_end : t -> string
+  (** End date of the week in ISO 8601 format. *)
+
+  val cached_at : t -> string
+  (** Timestamp when the data was cached. *)
+end
+
+(** {1 Issues} *)
+
+module Issue : sig
+  type t
+  (** A GitHub issue. *)
+
+  val make :
+    id:int ->
+    title:string ->
+    url:string ->
+    user:string ->
+    created_at:string ->
+    updated_at:string ->
+    closed_at:string option ->
+    body:string ->
+    labels:string list ->
+    state:string ->
+    comments:string list ->
+    t
+  (** Create an issue record. *)
+
+  val id : t -> int
+  (** Issue number. *)
+
+  val title : t -> string
+  (** Issue title. *)
+
+  val url : t -> string
+  (** URL to the issue on GitHub. *)
+
+  val user : t -> string
+  (** Username who created the issue. *)
+
+  val created_at : t -> string
+  (** Creation timestamp in ISO 8601 format. *)
+
+  val updated_at : t -> string
+  (** Last update timestamp. *)
+
+  val closed_at : t -> string option
+  (** Closure timestamp if closed. *)
+
+  val body : t -> string
+  (** Issue body text. *)
+
+  val labels : t -> string list
+  (** Labels applied to the issue. *)
+
+  val state : t -> string
+  (** Issue state ("open" or "closed"). *)
+
+  val comments : t -> string list
+  (** List of comment texts. *)
+end
+
+(** {1 Pull Requests} *)
+
+module Pr : sig
+  type t
+  (** A GitHub pull request. *)
+
+  val make :
+    id:int ->
+    title:string ->
+    url:string ->
+    user:string ->
+    created_at:string ->
+    updated_at:string ->
+    closed_at:string option ->
+    merged_at:string option ->
+    body:string ->
+    labels:string list ->
+    state:string ->
+    comments:string list ->
+    additions:int ->
+    deletions:int ->
+    changed_files:int ->
+    mergeable:string ->
+    draft:bool ->
+    t
+  (** Create a pull request record. *)
+
+  val id : t -> int
+  (** PR number. *)
+
+  val title : t -> string
+  (** PR title. *)
+
+  val url : t -> string
+  (** URL to the PR on GitHub. *)
+
+  val user : t -> string
+  (** Username who created the PR. *)
+
+  val created_at : t -> string
+  (** Creation timestamp. *)
+
+  val updated_at : t -> string
+  (** Last update timestamp. *)
+
+  val closed_at : t -> string option
+  (** Closure timestamp if closed. *)
+
+  val merged_at : t -> string option
+  (** Merge timestamp if merged. *)
+
+  val body : t -> string
+  (** PR body text. *)
+
+  val labels : t -> string list
+  (** Labels applied to the PR. *)
+
+  val state : t -> string
+  (** PR state ("open", "closed", or "merged"). *)
+
+  val comments : t -> string list
+  (** List of comment texts. *)
+
+  val additions : t -> int
+  (** Number of lines added. *)
+
+  val deletions : t -> int
+  (** Number of lines deleted. *)
+
+  val changed_files : t -> int
+  (** Number of files changed. *)
+
+  val mergeable : t -> string
+  (** Merge status ("MERGEABLE", "CONFLICTING", etc.). *)
+
+  val draft : t -> bool
+  (** Whether this is a draft PR. *)
+end
+
+(** {1 Discussions} *)
+
+module Discussion : sig
+  type t
+  (** A GitHub discussion. *)
+
+  val make :
+    id:int ->
+    title:string ->
+    url:string ->
+    user:string ->
+    updated_at:string ->
+    body:string ->
+    category:string ->
+    comments:int ->
+    answered:bool ->
+    t
+  (** Create a discussion record. *)
+
+  val id : t -> int
+  (** Discussion ID. *)
+
+  val title : t -> string
+  (** Discussion title. *)
+
+  val url : t -> string
+  (** URL to the discussion on GitHub. *)
+
+  val user : t -> string
+  (** Username who created the discussion. *)
+
+  val updated_at : t -> string
+  (** Last update timestamp. *)
+
+  val body : t -> string
+  (** Discussion body text. *)
+
+  val category : t -> string
+  (** Discussion category. *)
+
+  val comments : t -> int
+  (** Number of comments. *)
+
+  val answered : t -> bool
+  (** Whether the discussion has been marked answered. *)
+end
+
+(** {1 Release Assets} *)
+
+module Asset : sig
+  type t
+  (** A release asset (downloadable file). *)
+
+  val make : name:string -> download_count:int -> size:int -> t
+  (** Create an asset record. *)
+
+  val name : t -> string
+  (** Asset filename. *)
+
+  val download_count : t -> int
+  (** Number of downloads. *)
+
+  val size : t -> int
+  (** Asset size in bytes. *)
+end
+
+(** {1 Releases} *)
+
+module Release : sig
+  type t
+  (** A GitHub release. *)
+
+  val make :
+    tag_name:string ->
+    name:string ->
+    published_at:string ->
+    author:string ->
+    html_url:string ->
+    body:string ->
+    prerelease:bool ->
+    draft:bool ->
+    assets:Asset.t list ->
+    t
+  (** Create a release record. *)
+
+  val tag_name : t -> string
+  (** Git tag name for the release. *)
+
+  val name : t -> string
+  (** Release title. *)
+
+  val published_at : t -> string
+  (** Publication timestamp. *)
+
+  val author : t -> string
+  (** Username who created the release. *)
+
+  val html_url : t -> string
+  (** URL to the release on GitHub. *)
+
+  val body : t -> string
+  (** Release notes body text. *)
+
+  val prerelease : t -> bool
+  (** Whether this is a prerelease. *)
+
+  val draft : t -> bool
+  (** Whether this is a draft release. *)
+
+  val assets : t -> Asset.t list
+  (** Downloadable assets attached to the release. *)
+end
+
+(** {1 Weekly Data} *)
+
+module Week_data : sig
+  type t
+  (** Complete weekly activity snapshot for a repository. *)
+
+  val make :
+    metadata:Metadata.t ->
+    issues:Issue.t list ->
+    prs:Pr.t list ->
+    good_first_issues:Issue.t list ->
+    discussions:Discussion.t list ->
+    releases:Release.t list ->
+    users:string list ->
+    t
+  (** Create a weekly data snapshot. *)
+
+  val metadata : t -> Metadata.t
+  (** Snapshot metadata. *)
+
+  val issues : t -> Issue.t list
+  (** Issues with activity during the week. *)
+
+  val prs : t -> Pr.t list
+  (** Pull requests with activity during the week. *)
+
+  val good_first_issues : t -> Issue.t list
+  (** Issues labeled "good first issue". *)
+
+  val discussions : t -> Discussion.t list
+  (** Discussions with activity during the week. *)
+
+  val releases : t -> Release.t list
+  (** Releases published during the week. *)
+
+  val users : t -> string list
+  (** Usernames who were active during the week. *)
+end

repowatch/lib/users.ml

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+(* Common words to exclude from username detection *)
+let excluded_words =
+  [
+    (* Common English words that might appear with @ *)
+    "all";
+    "everyone";
+    "here";
+    "channel";
+    "team";
+    "author";
+    "authors";
+    "maintainer";
+    "maintainers";
+    "reviewer";
+    "reviewers";
+    "user";
+    "users";
+    "admin";
+    "admins";
+    "bot";
+    "bots";
+    "ghost";
+    (* Programming terms *)
+    "param";
+    "params";
+    "return";
+    "returns";
+    "type";
+    "types";
+    "value";
+    "values";
+    "deprecated";
+    "since";
+    "see";
+    "link";
+    "code";
+    "example";
+    "note";
+    "warning";
+    "todo";
+    "fixme";
+    "hack";
+    (* OCaml-specific terms *)
+    "raise";
+    "raises";
+    "inline";
+    "ocaml";
+    "opam";
+    "dune";
+    "module";
+    "functor";
+    "mli";
+    "cma";
+    "cmo";
+    "cmx";
+    "cmi";
+    (* Git/GitHub terms *)
+    "dependabot";
+    "github";
+    "actions";
+    "codecov";
+    "renovate";
+  ]
+
+(* Check if a string looks like a hex hash (commit SHA fragment) *)
+let looks_like_hex s =
+  String.length s >= 6
+  && String.for_all
+       (fun c -> (c >= '0' && c <= '9') || (c >= 'a' && c <= 'f'))
+       (String.lowercase_ascii s)
+
+let is_valid_username s =
+  let len = String.length s in
+  if len < 2 || len > 39 then false
+  else if List.mem (String.lowercase_ascii s) excluded_words then false
+  else if looks_like_hex s then false
+  else
+    (* Must start with letter *)
+    let first = s.[0] in
+    if not ((first >= 'a' && first <= 'z') || (first >= 'A' && first <= 'Z'))
+    then false
+    else
+      (* Must not start or end with hyphen *)
+      if s.[0] = '-' || s.[len - 1] = '-' then false
+      else
+        (* Must contain only alphanumeric and single hyphens *)
+        let rec check i prev_hyphen =
+          if i >= len then true
+          else
+            let c = s.[i] in
+            if c = '-' then
+              if prev_hyphen then false (* consecutive hyphens *)
+              else check (i + 1) true
+            else if
+              (c >= 'a' && c <= 'z')
+              || (c >= 'A' && c <= 'Z')
+              || (c >= '0' && c <= '9')
+            then check (i + 1) false
+            else false
+        in
+        check 0 false
+
+(* Extract @mentions from text *)
+let extract_mentions text =
+  let len = String.length text in
+  let rec find_at i acc =
+    if i >= len then acc
+    else if text.[i] = '@' then
+      let rec read_username j =
+        if j >= len then j
+        else
+          let c = text.[j] in
+          if
+            (c >= 'a' && c <= 'z')
+            || (c >= 'A' && c <= 'Z')
+            || (c >= '0' && c <= '9')
+            || c = '-'
+          then read_username (j + 1)
+          else j
+      in
+      let end_pos = read_username (i + 1) in
+      if end_pos > i + 1 then
+        let username = String.sub text (i + 1) (end_pos - i - 1) in
+        if is_valid_username username then find_at end_pos (username :: acc)
+        else find_at end_pos acc
+      else find_at (i + 1) acc
+    else find_at (i + 1) acc
+  in
+  find_at 0 [] |> List.sort_uniq String.compare
+
+(* Extract username from comment format "@username: body" *)
+let extract_comment_author comment =
+  if String.length comment > 1 && comment.[0] = '@' then
+    try
+      let colon_pos = String.index comment ':' in
+      let username = String.sub comment 1 (colon_pos - 1) in
+      if is_valid_username username then Some username else None
+    with Not_found -> None
+  else None
+
+let extract_from_week_data data =
+  let users = ref [] in
+  let add u = if is_valid_username u then users := u :: !users in
+  (* Issue authors and mentions *)
+  List.iter
+    (fun issue ->
+      add (Types.Issue.user issue);
+      List.iter (fun m -> add m) (extract_mentions (Types.Issue.body issue));
+      List.iter
+        (fun comment ->
+          Option.iter add (extract_comment_author comment);
+          List.iter (fun m -> add m) (extract_mentions comment))
+        (Types.Issue.comments issue))
+    (Types.Week_data.issues data);
+  (* PR authors and mentions *)
+  List.iter
+    (fun pr ->
+      add (Types.Pr.user pr);
+      List.iter (fun m -> add m) (extract_mentions (Types.Pr.body pr));
+      List.iter
+        (fun comment ->
+          Option.iter add (extract_comment_author comment);
+          List.iter (fun m -> add m) (extract_mentions comment))
+        (Types.Pr.comments pr))
+    (Types.Week_data.prs data);
+  (* Good first issues *)
+  List.iter
+    (fun issue ->
+      add (Types.Issue.user issue);
+      List.iter (fun m -> add m) (extract_mentions (Types.Issue.body issue)))
+    (Types.Week_data.good_first_issues data);
+  (* Discussion authors *)
+  List.iter
+    (fun disc ->
+      add (Types.Discussion.user disc);
+      List.iter (fun m -> add m) (extract_mentions (Types.Discussion.body disc)))
+    (Types.Week_data.discussions data);
+  (* Release authors *)
+  List.iter
+    (fun rel -> add (Types.Release.author rel))
+    (Types.Week_data.releases data);
+  (* Return unique sorted list *)
+  !users |> List.sort_uniq String.compare

repowatch/lib/users.mli

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+(** Extract and validate GitHub usernames.
+
+    This module provides functions to extract GitHub usernames from
+    weekly activity data and validate them against common patterns
+    that shouldn't be treated as usernames. *)
+
+(** {1 Username Extraction} *)
+
+val extract_from_week_data : Types.Week_data.t -> string list
+(** [extract_from_week_data data] extracts all unique usernames from
+    the week data. This includes:
+    - Issue and PR authors
+    - Comment authors (extracted from "@user: comment" format)
+    - Discussion authors
+    - Release authors
+    - Usernames mentioned in issue/PR bodies and comments *)
+
+val extract_mentions : string -> string list
+(** [extract_mentions text] extracts mentions (usernames prefixed with [\@])
+    from text. Returns a list of unique usernames found. *)
+
+(** {1 Validation} *)
+
+val is_valid_username : string -> bool
+(** [is_valid_username s] returns [true] if the string looks like a
+    valid GitHub username and is not in the exclusion list.
+
+    GitHub usernames:
+    - Start with a letter
+    - Contain only alphanumeric characters and hyphens
+    - Are 1-39 characters long
+    - Don't start or end with a hyphen
+    - Don't contain consecutive hyphens *)
+
+val excluded_words : string list
+(** List of words that look like mentions but should be excluded.
+    Includes common programming terms, OCaml-specific terms, and
+    common English words. *)

repowatch/lib/week.ml

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+type t = { year : int; week : int }
+
+(* Number of ISO weeks in a year. A year has 53 weeks if:
+   - January 1 is a Thursday, or
+   - January 1 is a Wednesday and it's a leap year *)
+let weeks_in_year year =
+  let jan1_weekday =
+    (* Zeller's congruence for January 1 *)
+    let y = if 1 <= 1 then year - 1 else year in
+    let m = 13 in
+    (* January treated as month 13 of previous year *)
+    let q = 1 in
+    let k = y mod 100 in
+    let j = y / 100 in
+    let h = (q + ((13 * (m + 1)) / 5) + k + (k / 4) + (j / 4) - (2 * j)) mod 7
+    in
+    (* Convert to ISO weekday (1=Monday, 7=Sunday) *)
+    ((h + 5) mod 7) + 1
+  in
+  let is_leap = year mod 4 = 0 && (year mod 100 <> 0 || year mod 400 = 0) in
+  if jan1_weekday = 4 || (jan1_weekday = 3 && is_leap) then 53 else 52
+
+let of_year_week ~year ~week =
+  let max_weeks = weeks_in_year year in
+  if week < 1 || week > max_weeks then
+    invalid_arg
+      (Printf.sprintf "Week %d is out of range for year %d (max: %d)" week year
+         max_weeks)
+  else { year; week }
+
+let year t = t.year
+let week t = t.week
+
+(* Convert Gregorian date to ISO week date *)
+let of_date ~year ~month ~day =
+  (* Algorithm based on ISO 8601 week date calculation *)
+  (* First, calculate the day of year *)
+  let days_before_month =
+    [| 0; 31; 59; 90; 120; 151; 181; 212; 243; 273; 304; 334 |]
+  in
+  let is_leap = year mod 4 = 0 && (year mod 100 <> 0 || year mod 400 = 0) in
+  let doy =
+    days_before_month.(month - 1)
+    + day
+    + (if month > 2 && is_leap then 1 else 0)
+  in
+  (* Calculate day of week (1=Monday, 7=Sunday) using a known reference *)
+  (* January 1, 2000 was a Saturday (day 6 in ISO) *)
+  let days_since_2000 =
+    let years_diff = year - 2000 in
+    let leap_years =
+      if years_diff >= 0 then
+        let prev_year = year - 1 in
+        (prev_year / 4) - (prev_year / 100) + (prev_year / 400)
+        - ((1999 / 4) - (1999 / 100) + (1999 / 400))
+      else
+        let prev_year = year - 1 in
+        (prev_year / 4) - (prev_year / 100) + (prev_year / 400)
+        - ((1999 / 4) - (1999 / 100) + (1999 / 400))
+    in
+    (years_diff * 365) + leap_years + doy - 1
+  in
+  (* January 1, 2000 was Saturday = day 6 *)
+  let dow = ((days_since_2000 mod 7) + 6 - 1 + 7) mod 7 + 1 in
+  (* ISO week number calculation *)
+  let week_num = (doy - dow + 10) / 7 in
+  if week_num < 1 then
+    (* Belongs to last week of previous year *)
+    { year = year - 1; week = weeks_in_year (year - 1) }
+  else if week_num > weeks_in_year year then
+    (* Belongs to first week of next year *)
+    { year = year + 1; week = 1 }
+  else { year; week = week_num }
+
+let of_ptime ptime =
+  let (y, m, d), _ = Ptime.to_date_time ptime in
+  of_date ~year:y ~month:m ~day:d
+
+let current ~clock =
+  let now = Eio.Time.now clock in
+  match Ptime.of_float_s now with
+  | Some ptime -> of_ptime ptime
+  | None ->
+      (* Fallback to epoch if conversion fails *)
+      of_date ~year:1970 ~month:1 ~day:1
+
+(* Calculate the Monday of week 1 for a given ISO week-year *)
+let monday_of_week1 year =
+  (* Week 1 contains January 4, so find the Monday of that week *)
+  let jan4_days_since_2000 =
+    let years_diff = year - 2000 in
+    let prev_year = year - 1 in
+    let leap_years =
+      (prev_year / 4) - (prev_year / 100) + (prev_year / 400)
+      - ((1999 / 4) - (1999 / 100) + (1999 / 400))
+    in
+    (years_diff * 365) + leap_years + 4 - 1
+  in
+  let jan4_dow = ((jan4_days_since_2000 mod 7) + 6 - 1 + 7) mod 7 + 1 in
+  (* Monday of week 1 = January 4 - (weekday of Jan 4 - 1) *)
+  jan4_days_since_2000 - (jan4_dow - 1)
+
+let days_since_2000_to_date days =
+  (* Approximate year *)
+  let approx_year = 2000 + (days / 365) in
+  let rec find_year y =
+    let start_of_year =
+      let years_diff = y - 2000 in
+      let prev_year = y - 1 in
+      let leap_years =
+        (prev_year / 4) - (prev_year / 100) + (prev_year / 400)
+        - ((1999 / 4) - (1999 / 100) + (1999 / 400))
+      in
+      (years_diff * 365) + leap_years
+    in
+    if start_of_year > days then find_year (y - 1) else (y, days - start_of_year)
+  in
+  let year, doy = find_year approx_year in
+  let doy = doy + 1 in
+  (* Convert to 1-based day of year *)
+  let is_leap = year mod 4 = 0 && (year mod 100 <> 0 || year mod 400 = 0) in
+  let days_in_month =
+    [| 31; (if is_leap then 29 else 28); 31; 30; 31; 30; 31; 31; 30; 31; 30; 31 |]
+  in
+  let rec find_month m remaining =
+    if remaining <= days_in_month.(m - 1) then (m, remaining)
+    else find_month (m + 1) (remaining - days_in_month.(m - 1))
+  in
+  let month, day = find_month 1 doy in
+  (year, month, day)
+
+let start_ptime t =
+  let monday_w1 = monday_of_week1 t.year in
+  let monday = monday_w1 + ((t.week - 1) * 7) in
+  let year, month, day = days_since_2000_to_date monday in
+  match Ptime.of_date (year, month, day) with
+  | Some pt -> pt
+  | None -> Ptime.epoch
+
+let end_ptime t =
+  let monday_w1 = monday_of_week1 t.year in
+  let sunday = monday_w1 + ((t.week - 1) * 7) + 6 in
+  let year, month, day = days_since_2000_to_date sunday in
+  match Ptime.of_date_time ((year, month, day), ((23, 59, 59), 0)) with
+  | Some pt -> pt
+  | None -> Ptime.epoch
+
+let start_date t =
+  let pt = start_ptime t in
+  let (y, m, d), _ = Ptime.to_date_time pt in
+  Printf.sprintf "%04d-%02d-%02d" y m d
+
+let end_date t =
+  let pt = end_ptime t in
+  let (y, m, d), _ = Ptime.to_date_time pt in
+  Printf.sprintf "%04d-%02d-%02d" y m d
+
+let contains_ptime t time =
+  let start = start_ptime t in
+  let end_ = end_ptime t in
+  Ptime.compare time start >= 0 && Ptime.compare time end_ <= 0
+
+let parse_iso8601 s =
+  (* Parse ISO 8601 timestamp like "2024-01-15T10:30:00Z" *)
+  try
+    let len = String.length s in
+    if len < 10 then None
+    else
+      let year = int_of_string (String.sub s 0 4) in
+      let month = int_of_string (String.sub s 5 2) in
+      let day = int_of_string (String.sub s 8 2) in
+      if len >= 19 then
+        let hour = int_of_string (String.sub s 11 2) in
+        let min = int_of_string (String.sub s 14 2) in
+        let sec = int_of_string (String.sub s 17 2) in
+        Ptime.of_date_time ((year, month, day), ((hour, min, sec), 0))
+      else Ptime.of_date (year, month, day)
+  with _ -> None
+
+let contains_timestamp t timestamp =
+  match parse_iso8601 timestamp with
+  | Some time -> contains_ptime t time
+  | None -> false
+
+let prev t =
+  if t.week > 1 then { year = t.year; week = t.week - 1 }
+  else { year = t.year - 1; week = weeks_in_year (t.year - 1) }
+
+let next t =
+  let max_weeks = weeks_in_year t.year in
+  if t.week < max_weeks then { year = t.year; week = t.week + 1 }
+  else { year = t.year + 1; week = 1 }
+
+let compare a b =
+  match Int.compare a.year b.year with 0 -> Int.compare a.week b.week | c -> c
+
+let equal a b = a.year = b.year && a.week = b.week
+
+let range ~from ~to_ =
+  let rec loop acc current =
+    if compare current from < 0 then acc
+    else loop (current :: acc) (prev current)
+  in
+  if compare from to_ > 0 then [] else loop [] to_
+
+let to_string t = Printf.sprintf "%04d-W%02d" t.year t.week
+let pp fmt t = Format.fprintf fmt "%s" (to_string t)

repowatch/lib/week.mli

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+(** ISO week calculations and date filtering.
+
+    This module provides utilities for working with ISO 8601 week dates,
+    which are used to partition GitHub activity data into weekly buckets.
+
+    An ISO week always starts on Monday and ends on Sunday. Week 1 is the
+    week containing the first Thursday of the year (equivalently, the week
+    containing January 4th). *)
+
+type t
+(** An ISO week represented as a year and week number (1-53). *)
+
+(** {1 Constructors} *)
+
+val of_date : year:int -> month:int -> day:int -> t
+(** [of_date ~year ~month ~day] returns the ISO week containing the given
+    Gregorian date. Month is 1-12, day is 1-31. *)
+
+val of_ptime : Ptime.t -> t
+(** [of_ptime t] returns the ISO week containing the given timestamp. *)
+
+val current : clock:_ Eio.Time.clock -> t
+(** [current ~clock] returns the current ISO week based on the system clock. *)
+
+val of_year_week : year:int -> week:int -> t
+(** [of_year_week ~year ~week] creates an ISO week from year and week number.
+    Week number should be 1-53. Raises [Invalid_argument] if week is out of
+    range for the given year. *)
+
+(** {1 Accessors} *)
+
+val year : t -> int
+(** [year t] returns the ISO week-year. Note that this may differ from the
+    Gregorian year for dates near year boundaries. *)
+
+val week : t -> int
+(** [week t] returns the ISO week number (1-53). *)
+
+(** {1 Date Boundaries} *)
+
+val start_date : t -> string
+(** [start_date t] returns the Monday of the week in ISO 8601 format
+    (YYYY-MM-DD). *)
+
+val end_date : t -> string
+(** [end_date t] returns the Sunday of the week in ISO 8601 format
+    (YYYY-MM-DD). *)
+
+val start_ptime : t -> Ptime.t
+(** [start_ptime t] returns the Monday of the week at 00:00:00 UTC. *)
+
+val end_ptime : t -> Ptime.t
+(** [end_ptime t] returns the Sunday of the week at 23:59:59 UTC. *)
+
+(** {1 Timestamp Filtering} *)
+
+val contains_timestamp : t -> string -> bool
+(** [contains_timestamp t timestamp] returns [true] if the ISO 8601 timestamp
+    falls within this week. Accepts timestamps in the format used by GitHub
+    API (e.g., "2024-01-15T10:30:00Z"). Returns [false] if the timestamp
+    cannot be parsed. *)
+
+val contains_ptime : t -> Ptime.t -> bool
+(** [contains_ptime t time] returns [true] if [time] falls within this week. *)
+
+(** {1 Navigation} *)
+
+val prev : t -> t
+(** [prev t] returns the previous week. *)
+
+val next : t -> t
+(** [next t] returns the next week. *)
+
+val range : from:t -> to_:t -> t list
+(** [range ~from ~to_] generates a list of weeks from [from] to [to_]
+    (inclusive). Returns an empty list if [from] is after [to_]. *)
+
+(** {1 Comparison} *)
+
+val compare : t -> t -> int
+(** [compare a b] compares two weeks. Returns a negative integer if [a] is
+    before [b], zero if equal, and a positive integer if [a] is after [b]. *)
+
+val equal : t -> t -> bool
+(** [equal a b] returns [true] if [a] and [b] represent the same week. *)
+
+(** {1 Formatting} *)
+
+val to_string : t -> string
+(** [to_string t] returns a string representation in ISO week format
+    (e.g., "2024-W03"). *)
+
+val pp : Format.formatter -> t -> unit
+(** [pp fmt t] pretty-prints the week. *)

repowatch/repowatch.opam

···
+# This file is generated by dune, edit dune-project instead
+opam-version: "2.0"
+synopsis: "GitHub repository activity watcher and analyzer"
+description:
+  "Repowatch parses and analyzes GitHub repository activity data from JSON files. It provides a CLI for viewing issues, PRs, discussions, and releases with statistics and filtering capabilities."
+maintainer: ["Anil Madhavapeddy <[e-mail]>"]
+authors: ["Anil Madhavapeddy <[e-mail]>"]
+license: "ISC"
+homepage: "https://github.com/avsm/repowatch"
+doc: "https://avsm.github.io/repowatch"
+bug-reports: "https://github.com/avsm/repowatch/issues"
+depends: [
+  "ocaml" {>= "5.2.0"}
+  "dune" {>= "3.20" & >= "3.20"}
+  "eio_main" {>= "1.2"}
+  "jsont" {>= "0.1.0"}
+  "tomlt" {>= "0.1.0"}
+  "xdge" {>= "0.1.0"}
+  "cmdliner" {>= "1.3.0"}
+  "logs" {>= "0.7.0"}
+  "fmt" {>= "0.9.0"}
+  "ptime" {>= "1.0.0"}
+  "odoc" {with-doc}
+]
+build: [
+  ["dune" "subst"] {dev}
+  [
+    "dune"
+    "build"
+    "-p"
+    name
+    "-j"
+    jobs
+    "@install"
+    "@runtest" {with-test}
+    "@doc" {with-doc}
+  ]
+]
+dev-repo: "git+https://github.com/avsm/repowatch.git"
+x-maintenance-intent: ["(latest)"]

repowatch/test/dune

···
+(test
+ (name test_codec)
+ (libraries repowatch eio_main))
+
+(test
+ (name test_week)
+ (libraries repowatch))

repowatch/test/test_codec.ml

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+let test_decode_metadata () =
+  let json =
+    {|{
+      "metadata": {
+        "repo": "test/repo",
+        "year": 2025,
+        "week": 1,
+        "week_start": "2025-01-01",
+        "week_end": "2025-01-07",
+        "cached_at": "2025-01-08T00:00:00"
+      },
+      "issues": [],
+      "prs": [],
+      "good_first_issues": [],
+      "discussions": [],
+      "releases": [],
+      "users": []
+    }|}
+  in
+  match Repowatch.Codec.decode_string json with
+  | Ok data ->
+      let m = Repowatch.Types.Week_data.metadata data in
+      assert (Repowatch.Types.Metadata.repo m = "test/repo");
+      assert (Repowatch.Types.Metadata.year m = 2025);
+      assert (Repowatch.Types.Metadata.week m = 1);
+      Printf.printf "test_decode_metadata: PASS\n"
+  | Error e ->
+      Printf.printf "test_decode_metadata: FAIL - %s\n" e;
+      exit 1
+
+let test_decode_issue () =
+  let json =
+    {|{
+      "metadata": {
+        "repo": "test/repo",
+        "year": 2025,
+        "week": 1,
+        "week_start": "2025-01-01",
+        "week_end": "2025-01-07",
+        "cached_at": "2025-01-08T00:00:00"
+      },
+      "issues": [
+        {
+          "id": 123,
+          "title": "Test issue",
+          "url": "https://github.com/test/repo/issues/123",
+          "user": "testuser",
+          "created_at": "2025-01-01T00:00:00Z",
+          "updated_at": "2025-01-02T00:00:00Z",
+          "closed_at": null,
+          "body": "This is a test issue",
+          "labels": ["bug", "help wanted"],
+          "state": "open",
+          "comments": []
+        }
+      ],
+      "prs": [],
+      "good_first_issues": [],
+      "discussions": [],
+      "releases": [],
+      "users": ["testuser"]
+    }|}
+  in
+  match Repowatch.Codec.decode_string json with
+  | Ok data ->
+      let issues = Repowatch.Types.Week_data.issues data in
+      assert (List.length issues = 1);
+      let i = List.hd issues in
+      assert (Repowatch.Types.Issue.id i = 123);
+      assert (Repowatch.Types.Issue.title i = "Test issue");
+      assert (Repowatch.Types.Issue.state i = "open");
+      assert (Repowatch.Types.Issue.closed_at i = None);
+      assert (List.length (Repowatch.Types.Issue.labels i) = 2);
+      Printf.printf "test_decode_issue: PASS\n"
+  | Error e ->
+      Printf.printf "test_decode_issue: FAIL - %s\n" e;
+      exit 1
+
+let test_decode_pr () =
+  let json =
+    {|{
+      "metadata": {
+        "repo": "test/repo",
+        "year": 2025,
+        "week": 1,
+        "week_start": "2025-01-01",
+        "week_end": "2025-01-07",
+        "cached_at": "2025-01-08T00:00:00"
+      },
+      "issues": [],
+      "prs": [
+        {
+          "id": 456,
+          "title": "Test PR",
+          "url": "https://github.com/test/repo/pull/456",
+          "user": "pruser",
+          "created_at": "2025-01-01T00:00:00Z",
+          "updated_at": "2025-01-02T00:00:00Z",
+          "closed_at": null,
+          "merged_at": null,
+          "body": "This is a test PR",
+          "labels": ["enhancement"],
+          "state": "open",
+          "comments": [],
+          "additions": 100,
+          "deletions": 50,
+          "changed_files": 5,
+          "mergeable": "MERGEABLE",
+          "draft": false
+        }
+      ],
+      "good_first_issues": [],
+      "discussions": [],
+      "releases": [],
+      "users": ["pruser"]
+    }|}
+  in
+  match Repowatch.Codec.decode_string json with
+  | Ok data ->
+      let prs = Repowatch.Types.Week_data.prs data in
+      assert (List.length prs = 1);
+      let p = List.hd prs in
+      assert (Repowatch.Types.Pr.id p = 456);
+      assert (Repowatch.Types.Pr.additions p = 100);
+      assert (Repowatch.Types.Pr.deletions p = 50);
+      assert (Repowatch.Types.Pr.changed_files p = 5);
+      assert (not (Repowatch.Types.Pr.draft p));
+      Printf.printf "test_decode_pr: PASS\n"
+  | Error e ->
+      Printf.printf "test_decode_pr: FAIL - %s\n" e;
+      exit 1
+
+let test_roundtrip () =
+  let json =
+    {|{
+      "metadata": {
+        "repo": "test/repo",
+        "year": 2025,
+        "week": 1,
+        "week_start": "2025-01-01",
+        "week_end": "2025-01-07",
+        "cached_at": "2025-01-08T00:00:00"
+      },
+      "issues": [],
+      "prs": [],
+      "good_first_issues": [],
+      "discussions": [],
+      "releases": [],
+      "users": []
+    }|}
+  in
+  match Repowatch.Codec.decode_string json with
+  | Ok data ->
+      let encoded = Repowatch.Codec.encode_string data in
+      (match Repowatch.Codec.decode_string encoded with
+      | Ok data2 ->
+          let m1 = Repowatch.Types.Week_data.metadata data in
+          let m2 = Repowatch.Types.Week_data.metadata data2 in
+          assert (Repowatch.Types.Metadata.repo m1 = Repowatch.Types.Metadata.repo m2);
+          assert (Repowatch.Types.Metadata.year m1 = Repowatch.Types.Metadata.year m2);
+          Printf.printf "test_roundtrip: PASS\n"
+      | Error e ->
+          Printf.printf "test_roundtrip: FAIL (decode after encode) - %s\n" e;
+          exit 1)
+  | Error e ->
+      Printf.printf "test_roundtrip: FAIL (initial decode) - %s\n" e;
+      exit 1
+
+let test_stats () =
+  let json =
+    {|{
+      "metadata": {
+        "repo": "test/repo",
+        "year": 2025,
+        "week": 1,
+        "week_start": "2025-01-01",
+        "week_end": "2025-01-07",
+        "cached_at": "2025-01-08T00:00:00"
+      },
+      "issues": [
+        {
+          "id": 1,
+          "title": "Open issue",
+          "url": "https://github.com/test/repo/issues/1",
+          "user": "user1",
+          "created_at": "2025-01-01T00:00:00Z",
+          "updated_at": "2025-01-02T00:00:00Z",
+          "closed_at": null,
+          "body": "Open",
+          "labels": [],
+          "state": "open",
+          "comments": []
+        },
+        {
+          "id": 2,
+          "title": "Closed issue",
+          "url": "https://github.com/test/repo/issues/2",
+          "user": "user2",
+          "created_at": "2025-01-01T00:00:00Z",
+          "updated_at": "2025-01-02T00:00:00Z",
+          "closed_at": "2025-01-03T00:00:00Z",
+          "body": "Closed",
+          "labels": [],
+          "state": "closed",
+          "comments": []
+        }
+      ],
+      "prs": [
+        {
+          "id": 10,
+          "title": "Merged PR",
+          "url": "https://github.com/test/repo/pull/10",
+          "user": "user1",
+          "created_at": "2025-01-01T00:00:00Z",
+          "updated_at": "2025-01-02T00:00:00Z",
+          "closed_at": "2025-01-03T00:00:00Z",
+          "merged_at": "2025-01-03T00:00:00Z",
+          "body": "Merged",
+          "labels": [],
+          "state": "closed",
+          "comments": [],
+          "additions": 50,
+          "deletions": 25,
+          "changed_files": 3,
+          "mergeable": "UNKNOWN",
+          "draft": false
+        }
+      ],
+      "good_first_issues": [],
+      "discussions": [],
+      "releases": [],
+      "users": ["user1", "user2"]
+    }|}
+  in
+  match Repowatch.Codec.decode_string json with
+  | Ok data ->
+      let stats = Repowatch.Printer.compute_stats data in
+      assert (stats.total_issues = 2);
+      assert (stats.open_issues = 1);
+      assert (stats.closed_issues = 1);
+      assert (stats.total_prs = 1);
+      assert (stats.merged_prs = 1);
+      assert (stats.total_additions = 50);
+      assert (stats.total_deletions = 25);
+      assert (stats.total_users = 2);
+      Printf.printf "test_stats: PASS\n"
+  | Error e ->
+      Printf.printf "test_stats: FAIL - %s\n" e;
+      exit 1
+
+let () =
+  Printf.printf "Running repowatch codec tests...\n";
+  test_decode_metadata ();
+  test_decode_issue ();
+  test_decode_pr ();
+  test_roundtrip ();
+  test_stats ();
+  Printf.printf "All tests passed!\n"

repowatch/test/test_week.ml

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2026 Anil Madhavapeddy <[e-mail]>. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+(* Tests for Week module - ISO week calculations *)
+
+let check_equal name expected actual =
+  if expected <> actual then begin
+    Printf.printf "FAIL %s: expected %s, got %s\n" name expected actual;
+    exit 1
+  end
+  else Printf.printf "PASS %s\n" name
+
+let check_bool name expected actual =
+  if expected <> actual then begin
+    Printf.printf "FAIL %s: expected %b, got %b\n" name expected actual;
+    exit 1
+  end
+  else Printf.printf "PASS %s\n" name
+
+let check_int name expected actual =
+  if expected <> actual then begin
+    Printf.printf "FAIL %s: expected %d, got %d\n" name expected actual;
+    exit 1
+  end
+  else Printf.printf "PASS %s\n" name
+
+let test_of_date () =
+  (* Test well-known ISO week dates *)
+
+  (* January 1, 2024 is a Monday - it's in week 1 of 2024 *)
+  let w = Repowatch.Week.of_date ~year:2024 ~month:1 ~day:1 in
+  check_int "2024-01-01 year" 2024 (Repowatch.Week.year w);
+  check_int "2024-01-01 week" 1 (Repowatch.Week.week w);
+
+  (* December 31, 2023 is a Sunday - last day of week 52 of 2023 *)
+  let w = Repowatch.Week.of_date ~year:2023 ~month:12 ~day:31 in
+  check_int "2023-12-31 year" 2023 (Repowatch.Week.year w);
+  check_int "2023-12-31 week" 52 (Repowatch.Week.week w);
+
+  (* January 1, 2023 is a Sunday - it's still in week 52 of 2022 *)
+  let w = Repowatch.Week.of_date ~year:2023 ~month:1 ~day:1 in
+  check_int "2023-01-01 year" 2022 (Repowatch.Week.year w);
+  check_int "2023-01-01 week" 52 (Repowatch.Week.week w);
+
+  (* January 2, 2023 is a Monday - it's week 1 of 2023 *)
+  let w = Repowatch.Week.of_date ~year:2023 ~month:1 ~day:2 in
+  check_int "2023-01-02 year" 2023 (Repowatch.Week.year w);
+  check_int "2023-01-02 week" 1 (Repowatch.Week.week w);
+
+  (* December 28, 2020 is a Monday in week 53 of 2020 (leap year) *)
+  let w = Repowatch.Week.of_date ~year:2020 ~month:12 ~day:28 in
+  check_int "2020-12-28 year" 2020 (Repowatch.Week.year w);
+  check_int "2020-12-28 week" 53 (Repowatch.Week.week w);
+
+  Printf.printf "All of_date tests passed\n"
+
+let test_of_year_week () =
+  let w = Repowatch.Week.of_year_week ~year:2024 ~week:3 in
+  check_int "2024-W03 year" 2024 (Repowatch.Week.year w);
+  check_int "2024-W03 week" 3 (Repowatch.Week.week w);
+  check_equal "2024-W03 string" "2024-W03" (Repowatch.Week.to_string w);
+
+  (* Test that invalid weeks are rejected *)
+  (try
+     let _ = Repowatch.Week.of_year_week ~year:2024 ~week:0 in
+     Printf.printf "FAIL of_year_week invalid week 0: should have raised\n";
+     exit 1
+   with Invalid_argument _ -> Printf.printf "PASS of_year_week invalid week 0\n");
+
+  (try
+     let _ = Repowatch.Week.of_year_week ~year:2024 ~week:53 in
+     Printf.printf
+       "FAIL of_year_week invalid week 53 for 2024: should have raised\n";
+     exit 1
+   with Invalid_argument _ ->
+     Printf.printf "PASS of_year_week invalid week 53 for 2024\n");
+
+  (* 2020 has 53 weeks, so this should work *)
+  let w = Repowatch.Week.of_year_week ~year:2020 ~week:53 in
+  check_int "2020-W53 week" 53 (Repowatch.Week.week w);
+
+  Printf.printf "All of_year_week tests passed\n"
+
+let test_start_end_date () =
+  (* Week 3 of 2024: Monday Jan 15 to Sunday Jan 21 *)
+  let w = Repowatch.Week.of_year_week ~year:2024 ~week:3 in
+  check_equal "2024-W03 start" "2024-01-15" (Repowatch.Week.start_date w);
+  check_equal "2024-W03 end" "2024-01-21" (Repowatch.Week.end_date w);
+
+  (* Week 1 of 2024: Monday Jan 1 to Sunday Jan 7 *)
+  let w = Repowatch.Week.of_year_week ~year:2024 ~week:1 in
+  check_equal "2024-W01 start" "2024-01-01" (Repowatch.Week.start_date w);
+  check_equal "2024-W01 end" "2024-01-07" (Repowatch.Week.end_date w);
+
+  (* Week 1 of 2023: Monday Jan 2 to Sunday Jan 8 *)
+  let w = Repowatch.Week.of_year_week ~year:2023 ~week:1 in
+  check_equal "2023-W01 start" "2023-01-02" (Repowatch.Week.start_date w);
+  check_equal "2023-W01 end" "2023-01-08" (Repowatch.Week.end_date w);
+
+  Printf.printf "All start_end_date tests passed\n"
+
+let test_contains_timestamp () =
+  let w = Repowatch.Week.of_year_week ~year:2024 ~week:3 in
+
+  (* Monday at midnight should be included *)
+  check_bool "contains monday start" true
+    (Repowatch.Week.contains_timestamp w "2024-01-15T00:00:00Z");
+
+  (* Sunday at 23:59:59 should be included *)
+  check_bool "contains sunday end" true
+    (Repowatch.Week.contains_timestamp w "2024-01-21T23:59:59Z");
+
+  (* Middle of the week *)
+  check_bool "contains wednesday" true
+    (Repowatch.Week.contains_timestamp w "2024-01-17T14:30:00Z");
+
+  (* Saturday before should not be included *)
+  check_bool "excludes saturday before" false
+    (Repowatch.Week.contains_timestamp w "2024-01-14T23:59:59Z");
+
+  (* Monday after should not be included *)
+  check_bool "excludes monday after" false
+    (Repowatch.Week.contains_timestamp w "2024-01-22T00:00:00Z");
+
+  (* Invalid timestamp should return false *)
+  check_bool "invalid timestamp" false
+    (Repowatch.Week.contains_timestamp w "not-a-timestamp");
+
+  Printf.printf "All contains_timestamp tests passed\n"
+
+let test_prev_next () =
+  let w = Repowatch.Week.of_year_week ~year:2024 ~week:3 in
+
+  let prev = Repowatch.Week.prev w in
+  check_int "prev year" 2024 (Repowatch.Week.year prev);
+  check_int "prev week" 2 (Repowatch.Week.week prev);
+
+  let next = Repowatch.Week.next w in
+  check_int "next year" 2024 (Repowatch.Week.year next);
+  check_int "next week" 4 (Repowatch.Week.week next);
+
+  (* Test year boundary *)
+  let w1 = Repowatch.Week.of_year_week ~year:2024 ~week:1 in
+  let prev_year = Repowatch.Week.prev w1 in
+  check_int "prev crosses year - year" 2023 (Repowatch.Week.year prev_year);
+  check_int "prev crosses year - week" 52 (Repowatch.Week.week prev_year);
+
+  let w52 = Repowatch.Week.of_year_week ~year:2023 ~week:52 in
+  let next_year = Repowatch.Week.next w52 in
+  check_int "next crosses year - year" 2024 (Repowatch.Week.year next_year);
+  check_int "next crosses year - week" 1 (Repowatch.Week.week next_year);
+
+  Printf.printf "All prev_next tests passed\n"
+
+let test_range () =
+  let from = Repowatch.Week.of_year_week ~year:2024 ~week:2 in
+  let to_ = Repowatch.Week.of_year_week ~year:2024 ~week:5 in
+  let range = Repowatch.Week.range ~from ~to_ in
+  check_int "range length" 4 (List.length range);
+  check_equal "range[0]" "2024-W02"
+    (Repowatch.Week.to_string (List.nth range 0));
+  check_equal "range[3]" "2024-W05"
+    (Repowatch.Week.to_string (List.nth range 3));
+
+  (* Empty range when from > to *)
+  let empty_range = Repowatch.Week.range ~from:to_ ~to_:from in
+  check_int "empty range" 0 (List.length empty_range);
+
+  (* Single week range *)
+  let single = Repowatch.Week.range ~from ~to_:from in
+  check_int "single week range" 1 (List.length single);
+
+  Printf.printf "All range tests passed\n"
+
+let test_compare () =
+  let w1 = Repowatch.Week.of_year_week ~year:2024 ~week:3 in
+  let w2 = Repowatch.Week.of_year_week ~year:2024 ~week:5 in
+  let w3 = Repowatch.Week.of_year_week ~year:2023 ~week:52 in
+
+  check_bool "w1 < w2" true (Repowatch.Week.compare w1 w2 < 0);
+  check_bool "w2 > w1" true (Repowatch.Week.compare w2 w1 > 0);
+  check_bool "w1 = w1" true (Repowatch.Week.compare w1 w1 = 0);
+  check_bool "w3 < w1" true (Repowatch.Week.compare w3 w1 < 0);
+  check_bool "w1 equal w1" true (Repowatch.Week.equal w1 w1);
+  check_bool "w1 not equal w2" false (Repowatch.Week.equal w1 w2);
+
+  Printf.printf "All compare tests passed\n"
+
+let () =
+  Printf.printf "Running Week module tests...\n\n";
+  test_of_date ();
+  test_of_year_week ();
+  test_start_end_date ();
+  test_contains_timestamp ();
+  test_prev_next ();
+  test_range ();
+  test_compare ();
+  Printf.printf "\nAll Week module tests passed!\n"