Skip to main content

quarb_github/
lib.rs

1//! GitHub API adapter for the Quarb query engine.
2//!
3//! GitHub is three shapes at once, and the arbor keeps each in
4//! its native register. The **tree** mirrors github.com URLs:
5//! users and organizations at the root (addressed by login —
6//! the root does not enumerate GitHub), their repositories as
7//! direct children (`/torvalds/linux`), and each repository's
8//! sections below (`files`, `issues`, `pulls`, `releases`).
9//! File content, issue bodies, and release notes are node
10//! *values*. The **social graph** is edge fabric, every label
11//! API-backed in both directions: `follows` (`<-follows` are
12//! the followers), `starred` (`<-starred` the stargazers),
13//! `owner`, `parent` (`<-parent` the forks), `author` /
14//! `assignee`, `org` (`<-org` the members), and `contributor`
15//! — whose edge carries data: `$-::contributions`. The
16//! **metadata** splits by kind: counts and scalars are
17//! properties (`::stars`, `::language`, timestamps as
18//! instants), while boolean flags (`<fork>`, `<archived>`,
19//! `<open>`, `<merged>`), issue labels (`<label:bug>`), and repo
20//! topics (`<topic:cli>`) are traits — unary facts filter, values
21//! compare. Labels and topics sit in their own namespaces, so a
22//! label never collides with a fixed trait like `<draft>`, and
23//! `<label:*>` / `<topic:*>` sweep each family.
24//!
25//! Direct addressing skips enumeration: `/rust-lang/rust` is
26//! one GET, `/rust-lang/rust/issues/12345` another (closed
27//! issues included — enumeration lists open ones, the API's
28//! default). Everything loads lazily and is cached for the
29//! session; listing costs one paginated sweep per touched
30//! container. Read-only — the adapter only ever GETs.
31//!
32//! **Transport and auth**: the adapter shells out to `gh api`,
33//! so authentication, hosts, and rate limits behave exactly as
34//! the gh CLI does. Target: `github:` (whole GitHub, address
35//! from the root), `github:OWNER`, or `github:OWNER/REPO` to
36//! anchor the arbor. `QUARB_GH` overrides the binary.
37
38use quarb::temporal::parse_iso;
39use quarb::{AstAdapter, NodeId, Value};
40use serde_json::Value as Json;
41use std::cell::RefCell;
42use std::collections::HashMap;
43use std::rc::Rc;
44
45/// An error connecting to or reading GitHub.
46#[derive(Debug, thiserror::Error)]
47pub enum GithubError {
48    #[error("gh: {0}")]
49    Gh(String),
50    #[error("github target: {0} (expected github:[OWNER[/REPO]])")]
51    Target(String),
52}
53
54/// A repository's fixed sections.
55#[derive(Clone, Copy, PartialEq)]
56enum Sec {
57    Files,
58    Issues,
59    Pulls,
60    Releases,
61}
62
63impl Sec {
64    const ALL: [Sec; 4] = [Sec::Files, Sec::Issues, Sec::Pulls, Sec::Releases];
65    fn name(self) -> &'static str {
66        match self {
67            Sec::Files => "files",
68            Sec::Issues => "issues",
69            Sec::Pulls => "pulls",
70            Sec::Releases => "releases",
71        }
72    }
73}
74
75/// What a node is. Entity JSON hangs off the node (lazily
76/// completed for users and repositories, whose edge-listing
77/// appearances are partial objects).
78enum Kind {
79    Root,
80    /// A user or organization, by login.
81    User {
82        login: String,
83    },
84    /// A repository; `key` is `owner/name`.
85    Repo {
86        key: String,
87    },
88    Section {
89        repo: String,
90        sec: Sec,
91    },
92    /// An issue, pull request, or release (told apart by their
93    /// JSON: releases carry `tag_name`, pulls `head` or
94    /// `pull_request`).
95    Item,
96    /// A directory in a repository's default-branch tree.
97    Dir {
98        repo: String,
99        path: String,
100    },
101    /// A file (or symlink/submodule); content is the value.
102    File {
103        repo: String,
104        path: String,
105    },
106}
107
108struct Node {
109    kind: Kind,
110    name: Option<String>,
111    parent: Option<NodeId>,
112    children: RefCell<Option<Vec<NodeId>>>,
113    data: RefCell<Option<Rc<Json>>>,
114}
115
116/// A string value; RFC 3339 timestamps become instants.
117fn str_value(s: &str) -> Value {
118    if s.contains('T')
119        && let Some((secs, nanos, offset_min)) = parse_iso(s)
120    {
121        return Value::Instant {
122            secs,
123            nanos,
124            offset_min,
125            calendar: Default::default(),
126        };
127    }
128    Value::Str(s.to_string())
129}
130
131/// A byte count as the size quantity (spec: a measured property is
132/// minted as a quantity in the source's unit); anything but a whole
133/// number passes through.
134fn bytes(v: Value) -> Value {
135    match v {
136        Value::Int(n) => Value::bytes(n),
137        other => other,
138    }
139}
140
141/// A kibibyte count as a size quantity written in KiB.
142fn kib(v: Value) -> Value {
143    match v {
144        Value::Int(n) => Value::Quantity {
145            value: n as f64 * 8192.0,
146            base: "b".to_string(),
147            written: Some((n as f64, "KiB".to_string())),
148        },
149        other => other,
150    }
151}
152
153fn json_scalar(v: &Json) -> Option<Value> {
154    match v {
155        Json::String(s) => Some(str_value(s)),
156        Json::Number(n) => Some(match n.as_i64() {
157            Some(i) => Value::Int(i),
158            None => Value::Float(n.as_f64()?),
159        }),
160        Json::Bool(b) => Some(Value::Bool(*b)),
161        _ => None,
162    }
163}
164
165/// Standard base64 (the contents API's encoding; padding
166/// required, whitespace ignored).
167fn base64_decode(s: &str) -> Option<Vec<u8>> {
168    let mut out = Vec::new();
169    let mut acc: u32 = 0;
170    let mut bits = 0;
171    for c in s.bytes() {
172        let v = match c {
173            b'A'..=b'Z' => c - b'A',
174            b'a'..=b'z' => c - b'a' + 26,
175            b'0'..=b'9' => c - b'0' + 52,
176            b'+' => 62,
177            b'/' => 63,
178            b'=' | b'\n' | b'\r' | b' ' => continue,
179            _ => return None,
180        };
181        acc = (acc << 6) | v as u32;
182        bits += 6;
183        if bits >= 8 {
184            bits -= 8;
185            out.push((acc >> bits) as u8);
186        }
187    }
188    Some(out)
189}
190
191/// GitHub, exposed as an arbor.
192pub struct GithubAdapter {
193    gh: String,
194    /// The anchor's root children (empty for a bare `github:`).
195    anchor: Vec<NodeId>,
196    nodes: RefCell<Vec<Node>>,
197    users: RefCell<HashMap<String, NodeId>>,
198    repos: RefCell<HashMap<String, NodeId>>,
199    /// `owner/name#number` → issue/pull node.
200    items: RefCell<HashMap<String, NodeId>>,
201    /// `owner/name@login` → contributions (edge data).
202    contributions: RefCell<HashMap<String, i64>>,
203    /// `owner/name:path` → decoded file content.
204    contents: RefCell<HashMap<String, Option<String>>>,
205}
206
207impl GithubAdapter {
208    /// Connect to `github:`, `github:OWNER`, or
209    /// `github:OWNER/REPO`.
210    pub fn connect(target: &str) -> Result<Self, GithubError> {
211        let anchor = target
212            .strip_prefix("github:")
213            .ok_or_else(|| GithubError::Target(target.to_string()))?;
214        let gh = std::env::var("QUARB_GH").unwrap_or_else(|_| "gh".to_string());
215        let adapter = GithubAdapter {
216            gh,
217            anchor: Vec::new(),
218            nodes: RefCell::new(vec![Node {
219                kind: Kind::Root,
220                name: None,
221                parent: None,
222                children: RefCell::new(None),
223                data: RefCell::new(None),
224            }]),
225            users: RefCell::new(HashMap::new()),
226            repos: RefCell::new(HashMap::new()),
227            items: RefCell::new(HashMap::new()),
228            contributions: RefCell::new(HashMap::new()),
229            contents: RefCell::new(HashMap::new()),
230        };
231        let mut adapter = adapter;
232        match anchor.split_once('/') {
233            None if anchor.is_empty() => {
234                // Probe: auth and reachability surface here.
235                adapter
236                    .call("/rate_limit")
237                    .map_err(|e| GithubError::Gh(format!("{e} (is `gh auth login` done?)")))?;
238            }
239            None => {
240                let u = adapter
241                    .fetch_user(anchor)
242                    .ok_or_else(|| GithubError::Gh(format!("no such user: {anchor}")))?;
243                adapter.anchor = vec![u];
244            }
245            Some((owner, repo)) => {
246                let key = format!("{owner}/{repo}");
247                let r = adapter
248                    .fetch_repo(&key)
249                    .ok_or_else(|| GithubError::Gh(format!("no such repository: {key}")))?;
250                adapter.anchor = vec![r];
251            }
252        }
253        Ok(adapter)
254    }
255
256    /// A human-readable locator: the github.com-shaped path.
257    pub fn locator(&self, node: NodeId) -> String {
258        let nodes = self.nodes.borrow();
259        let mut parts = Vec::new();
260        let mut cur = Some(node);
261        while let Some(n) = cur {
262            if let Some(name) = &nodes[n.0 as usize].name {
263                parts.push(name.clone());
264            }
265            cur = nodes[n.0 as usize].parent;
266        }
267        parts.reverse();
268        format!("/{}", parts.join("/"))
269    }
270
271    fn call(&self, path: &str) -> Result<Json, String> {
272        let out = std::process::Command::new(&self.gh)
273            .args(["api", path])
274            .output()
275            .map_err(|e| format!("running {}: {e}", self.gh))?;
276        if !out.status.success() {
277            return Err(format!(
278                "api {path}: {}",
279                String::from_utf8_lossy(&out.stderr).trim()
280            ));
281        }
282        serde_json::from_slice(&out.stdout).map_err(|e| format!("decoding {path}: {e}"))
283    }
284
285    /// A fully paginated array endpoint. A failure on the first
286    /// page is an empty listing (the `children` contract); a
287    /// failure mid-pagination fails loud rather than cache a
288    /// silently-short answer.
289    fn call_paged(&self, path: &str) -> Vec<Json> {
290        let sep = if path.contains('?') { '&' } else { '?' };
291        let mut out = Vec::new();
292        for page in 1.. {
293            let url = format!("{path}{sep}per_page=100&page={page}");
294            let items = match self.call(&url) {
295                Ok(Json::Array(a)) => a,
296                Ok(_) => break,
297                // Mid-pagination failure: refused (the query errors)
298                // rather than a silently short answer cached.
299                Err(e) if page > 1 => {
300                    quarb::record_refusal(format!(
301                        "github: listing {path} truncated at page {page}: {e}"
302                    ));
303                    break;
304                }
305                Err(_) => break,
306            };
307            let n = items.len();
308            out.extend(items);
309            if n < 100 {
310                break;
311            }
312        }
313        out
314    }
315
316    fn push_node(
317        &self,
318        kind: Kind,
319        name: Option<String>,
320        parent: Option<NodeId>,
321        data: Option<Json>,
322    ) -> NodeId {
323        let mut nodes = self.nodes.borrow_mut();
324        let id = NodeId(nodes.len() as u64);
325        nodes.push(Node {
326            kind,
327            name,
328            parent,
329            children: RefCell::new(None),
330            data: RefCell::new(data.map(Rc::new)),
331        });
332        id
333    }
334
335    fn data(&self, node: NodeId) -> Option<Rc<Json>> {
336        self.nodes.borrow()[node.0 as usize].data.borrow().clone()
337    }
338
339    fn set_data(&self, node: NodeId, data: Json) -> Rc<Json> {
340        let rc = Rc::new(data);
341        *self.nodes.borrow()[node.0 as usize].data.borrow_mut() = Some(rc.clone());
342        rc
343    }
344
345    /// The user node for a login, interned once; `seed` is a
346    /// possibly-partial object from an edge listing.
347    fn user_node(&self, login: &str, seed: Option<&Json>) -> NodeId {
348        if let Some(&n) = self.users.borrow().get(login) {
349            return n;
350        }
351        let n = self.push_node(
352            Kind::User {
353                login: login.to_string(),
354            },
355            Some(login.to_string()),
356            Some(NodeId(0)),
357            seed.cloned(),
358        );
359        self.users.borrow_mut().insert(login.to_string(), n);
360        n
361    }
362
363    /// A user's data, completed to the full profile when the
364    /// cached object is a partial edge-listing one (partials
365    /// lack `created_at`).
366    fn user_data(&self, node: NodeId, login: &str) -> Option<Rc<Json>> {
367        if let Some(d) = self.data(node)
368            && d.get("created_at").is_some()
369        {
370            return Some(d);
371        }
372        let d = self.call(&format!("/users/{login}")).ok()?;
373        Some(self.set_data(node, d))
374    }
375
376    fn fetch_user(&self, login: &str) -> Option<NodeId> {
377        let n = self.user_node(login, None);
378        self.user_data(n, login).map(|_| n)
379    }
380
381    /// The repo node for `owner/name`, interned once.
382    fn repo_node(&self, key: &str, seed: Option<&Json>) -> NodeId {
383        if let Some(&n) = self.repos.borrow().get(key) {
384            return n;
385        }
386        let (owner, name) = key.split_once('/').unwrap_or((key, key));
387        let parent = self.user_node(owner, None);
388        let n = self.push_node(
389            Kind::Repo {
390                key: key.to_string(),
391            },
392            Some(name.to_string()),
393            Some(parent),
394            seed.cloned(),
395        );
396        self.repos.borrow_mut().insert(key.to_string(), n);
397        n
398    }
399
400    /// A repo's data; refetched singly when a needed field is
401    /// missing from a listing object (`full` forces that).
402    fn repo_data(&self, node: NodeId, key: &str, full: bool) -> Option<Rc<Json>> {
403        if let Some(d) = self.data(node)
404            && (!full || d.get("subscribers_count").is_some())
405        {
406            return Some(d);
407        }
408        let d = self.call(&format!("/repos/{key}")).ok()?;
409        Some(self.set_data(node, d))
410    }
411
412    fn fetch_repo(&self, key: &str) -> Option<NodeId> {
413        let n = self.repo_node(key, None);
414        self.repo_data(n, key, true).map(|_| n)
415    }
416
417    /// An issue/pull/release node, interned by a repo-scoped key.
418    fn item_node(&self, key: String, name: String, parent: Option<NodeId>, data: Json) -> NodeId {
419        if let Some(&n) = self.items.borrow().get(&key) {
420            return n;
421        }
422        let n = self.push_node(Kind::Item, Some(name), parent, Some(data));
423        self.items.borrow_mut().insert(key, n);
424        n
425    }
426
427    fn section_node(&self, repo_node: NodeId, repo: &str, sec: Sec) -> NodeId {
428        self.push_node(
429            Kind::Section {
430                repo: repo.to_string(),
431                sec,
432            },
433            Some(sec.name().to_string()),
434            Some(repo_node),
435            None,
436        )
437    }
438
439    /// A directory listing (the contents API), as Dir/File nodes.
440    fn dir_children(&self, parent: NodeId, repo: &str, path: &str) -> Vec<NodeId> {
441        let url = match path.is_empty() {
442            true => format!("/repos/{repo}/contents/"),
443            false => format!("/repos/{repo}/contents/{path}"),
444        };
445        let Ok(Json::Array(entries)) = self.call(&url) else {
446            return Vec::new();
447        };
448        entries
449            .iter()
450            .filter_map(|e| {
451                let name = e.get("name")?.as_str()?.to_string();
452                let epath = e.get("path")?.as_str()?.to_string();
453                let kind = match e.get("type")?.as_str()? {
454                    "dir" => Kind::Dir {
455                        repo: repo.to_string(),
456                        path: epath,
457                    },
458                    _ => Kind::File {
459                        repo: repo.to_string(),
460                        path: epath,
461                    },
462                };
463                Some(self.push_node(kind, Some(name), Some(parent), Some(e.clone())))
464            })
465            .collect()
466    }
467
468    /// A file's decoded content (one GET, cached; `None` for
469    /// binary or oversized files).
470    fn file_content(&self, repo: &str, path: &str) -> Option<String> {
471        let key = format!("{repo}:{path}");
472        if let Some(c) = self.contents.borrow().get(&key) {
473            return c.clone();
474        }
475        let content = self
476            .call(&format!("/repos/{repo}/contents/{path}"))
477            .ok()
478            .and_then(|d| {
479                let b64 = d.get("content")?.as_str()?.to_string();
480                String::from_utf8(base64_decode(&b64)?).ok()
481            });
482        self.contents.borrow_mut().insert(key, content.clone());
483        content
484    }
485
486    /// List a section's items (issues and pulls list the open
487    /// ones — the API's default; direct addressing reaches any).
488    fn section_children(&self, node: NodeId, repo: &str, sec: Sec) -> Vec<NodeId> {
489        match sec {
490            Sec::Files => self.dir_children(node, repo, ""),
491            Sec::Issues => self
492                .call_paged(&format!("/repos/{repo}/issues"))
493                .iter()
494                // The issues listing interleaves pull requests.
495                .filter(|i| i.get("pull_request").is_none())
496                .filter_map(|i| {
497                    let num = i.get("number")?.as_i64()?;
498                    Some(self.item_node(
499                        format!("{repo}#{num}"),
500                        num.to_string(),
501                        Some(node),
502                        i.clone(),
503                    ))
504                })
505                .collect(),
506            Sec::Pulls => self
507                .call_paged(&format!("/repos/{repo}/pulls"))
508                .iter()
509                .filter_map(|i| {
510                    let num = i.get("number")?.as_i64()?;
511                    Some(self.item_node(
512                        format!("{repo}#{num}"),
513                        num.to_string(),
514                        Some(node),
515                        i.clone(),
516                    ))
517                })
518                .collect(),
519            Sec::Releases => self
520                .call_paged(&format!("/repos/{repo}/releases"))
521                .iter()
522                .filter_map(|r| {
523                    let tag = r.get("tag_name")?.as_str()?.to_string();
524                    Some(self.item_node(format!("{repo}@{tag}"), tag, Some(node), r.clone()))
525                })
526                .collect(),
527        }
528    }
529
530    /// The item's author edge target.
531    fn author_of(&self, data: &Json) -> Option<NodeId> {
532        let u = data.get("user").or_else(|| data.get("author"))?;
533        let login = u.get("login")?.as_str()?;
534        Some(self.user_node(login, Some(u)))
535    }
536}
537
538impl AstAdapter for GithubAdapter {
539    fn root(&self) -> NodeId {
540        NodeId(0)
541    }
542
543    fn children(&self, node: NodeId) -> Vec<NodeId> {
544        if let Some(c) = self.nodes.borrow()[node.0 as usize]
545            .children
546            .borrow()
547            .as_ref()
548        {
549            return c.clone();
550        }
551        enum Plan {
552            Root,
553            User(String),
554            Repo(String),
555            Section(String, Sec),
556            Dir(String, String),
557            Leaf,
558        }
559        let plan = match &self.nodes.borrow()[node.0 as usize].kind {
560            Kind::Root => Plan::Root,
561            Kind::User { login } => Plan::User(login.clone()),
562            Kind::Repo { key } => Plan::Repo(key.clone()),
563            Kind::Section { repo, sec } => Plan::Section(repo.clone(), *sec),
564            Kind::Dir { repo, path } => Plan::Dir(repo.clone(), path.clone()),
565            Kind::Item | Kind::File { .. } => Plan::Leaf,
566        };
567        let ids = match plan {
568            // The root does not enumerate GitHub; an anchored
569            // target roots its entity here.
570            Plan::Root => self.anchor.clone(),
571            Plan::User(login) => self
572                .call_paged(&format!("/users/{login}/repos"))
573                .iter()
574                .filter_map(|r| {
575                    let key = r.get("full_name")?.as_str()?;
576                    Some(self.repo_node(key, Some(r)))
577                })
578                .collect(),
579            Plan::Repo(key) => Sec::ALL
580                .iter()
581                .map(|&sec| self.section_node(node, &key, sec))
582                .collect(),
583            Plan::Section(repo, sec) => self.section_children(node, &repo, sec),
584            Plan::Dir(repo, path) => self.dir_children(node, &repo, &path),
585            Plan::Leaf => Vec::new(),
586        };
587        *self.nodes.borrow()[node.0 as usize].children.borrow_mut() = Some(ids.clone());
588        ids
589    }
590
591    /// Direct addressing: a login at the root, a repository
592    /// under its owner, an issue or pull by number (closed ones
593    /// included) — one GET each, no enumeration.
594    fn children_named(&self, node: NodeId, name: &str) -> Vec<NodeId> {
595        enum Plan {
596            Root,
597            User(String),
598            Section(String, Sec),
599            Other,
600        }
601        let plan = match &self.nodes.borrow()[node.0 as usize].kind {
602            Kind::Root => Plan::Root,
603            Kind::User { login } => Plan::User(login.clone()),
604            Kind::Section {
605                repo,
606                sec: sec @ (Sec::Issues | Sec::Pulls),
607            } => Plan::Section(repo.clone(), *sec),
608            _ => Plan::Other,
609        };
610        match plan {
611            Plan::Root => {
612                // An anchored target roots its entity here, so its
613                // own name answers first: under `github:ada/boiler`
614                // the root lists `boiler`, and `/boiler` must reach
615                // what `/*` lists (a name at the root was always a
616                // login, and the step answered nothing). Any other
617                // name is a login, as ever.
618                let anchored: Vec<NodeId> = self
619                    .anchor
620                    .iter()
621                    .copied()
622                    .filter(|n| {
623                        self.nodes.borrow()[n.0 as usize]
624                            .name
625                            .as_deref()
626                            .is_some_and(|own| own.eq_ignore_ascii_case(name))
627                    })
628                    .collect();
629                if !anchored.is_empty() {
630                    return anchored;
631                }
632                if let Some(&n) = self.users.borrow().get(name) {
633                    return vec![n];
634                }
635                self.fetch_user(name).into_iter().collect()
636            }
637            Plan::User(login) => {
638                let key = format!("{login}/{name}");
639                if let Some(&n) = self.repos.borrow().get(&key) {
640                    return vec![n];
641                }
642                self.fetch_repo(&key).into_iter().collect()
643            }
644            Plan::Section(repo, sec) => {
645                let Ok(num) = name.parse::<i64>() else {
646                    return Vec::new();
647                };
648                if let Some(&n) = self.items.borrow().get(&format!("{repo}#{num}")) {
649                    return vec![n];
650                }
651                let path = match sec {
652                    Sec::Pulls => format!("/repos/{repo}/pulls/{num}"),
653                    _ => format!("/repos/{repo}/issues/{num}"),
654                };
655                let Ok(d) = self.call(&path) else {
656                    return Vec::new();
657                };
658                vec![self.item_node(format!("{repo}#{num}"), num.to_string(), Some(node), d)]
659            }
660            Plan::Other => {
661                // Default: enumerate and filter by name.
662                self.children(node)
663                    .into_iter()
664                    .filter(|&c| self.name(c).as_deref() == Some(name))
665                    .collect()
666            }
667        }
668    }
669
670    fn name(&self, node: NodeId) -> Option<String> {
671        self.nodes.borrow()[node.0 as usize].name.clone()
672    }
673
674    fn parent(&self, node: NodeId) -> Option<NodeId> {
675        self.nodes.borrow()[node.0 as usize].parent
676    }
677
678    /// The kind first (spec: Traits): `<forge>` at the root, then
679    /// type traits (`<user>`, `<repo>`, `<issue>`…), boolean
680    /// flags (`<fork>`, `<archived>`, `<open>`, `<merged>`,
681    /// `<draft>`, `<prerelease>`), issue labels verbatim
682    /// (`<bug>`), and repository topics (`<cli>`).
683    fn traits(&self, node: NodeId) -> Vec<String> {
684        enum Shape {
685            Fixed(&'static str),
686            User(String),
687            Repo,
688            Item,
689            File,
690        }
691        let shape = match &self.nodes.borrow()[node.0 as usize].kind {
692            Kind::Root => Shape::Fixed("forge"),
693            Kind::Section { .. } => Shape::Fixed("section"),
694            Kind::Dir { .. } => Shape::Fixed("dir"),
695            Kind::User { login } => Shape::User(login.clone()),
696            Kind::Repo { .. } => Shape::Repo,
697            Kind::Item => Shape::Item,
698            Kind::File { .. } => Shape::File,
699        };
700        let data = self.data(node);
701        let d = data.as_deref();
702        let flag = |k: &str| d.and_then(|d| d.get(k)).and_then(|v| v.as_bool()) == Some(true);
703        let set = |k: &str| d.and_then(|d| d.get(k)).map(|v| !v.is_null()) == Some(true);
704        match shape {
705            Shape::Fixed(t) => vec![t.to_string()],
706            Shape::User(login) => {
707                // The type rides on even partial objects; fetch
708                // only if there is no object at all.
709                let t = d
710                    .and_then(|d| d.get("type"))
711                    .and_then(|v| v.as_str())
712                    .map(str::to_string)
713                    .or_else(|| {
714                        let n = *self.users.borrow().get(&login)?;
715                        let d = self.user_data(n, &login)?;
716                        Some(d.get("type")?.as_str()?.to_string())
717                    })
718                    .unwrap_or_else(|| "User".to_string());
719                // An organization also answers <org> (the
720                // universal shorthand) and the forge-neutral
721                // <group> (GitLab's native word), so container
722                // filters read the same on both forges.
723                match t.as_str() {
724                    "Organization" => vec![
725                        "organization".to_string(),
726                        "org".to_string(),
727                        "group".to_string(),
728                    ],
729                    _ => vec![t.to_lowercase()],
730                }
731            }
732            Shape::Repo => {
733                let mut ts = vec!["repo".to_string()];
734                for f in ["fork", "archived", "private", "is_template"] {
735                    if flag(f) {
736                        ts.push(f.trim_start_matches("is_").to_string());
737                    }
738                }
739                if let Some(topics) = d.and_then(|d| d.get("topics")).and_then(|v| v.as_array()) {
740                    ts.extend(
741                        topics
742                            .iter()
743                            .filter_map(|t| t.as_str().map(|t| format!("topic:{t}"))),
744                    );
745                }
746                ts
747            }
748            Shape::Item => {
749                let mut ts = Vec::new();
750                let kind = if d.is_some_and(|d| d.get("tag_name").is_some()) {
751                    "release"
752                } else if d
753                    .is_some_and(|d| d.get("head").is_some() || d.get("pull_request").is_some())
754                {
755                    "pull"
756                } else {
757                    "issue"
758                };
759                ts.push(kind.to_string());
760                if let Some(state) = d.and_then(|d| d.get("state")).and_then(|v| v.as_str()) {
761                    ts.push(state.to_string());
762                }
763                if set("merged_at") {
764                    ts.push("merged".to_string());
765                }
766                if flag("draft") {
767                    ts.push("draft".to_string());
768                }
769                if flag("prerelease") {
770                    ts.push("prerelease".to_string());
771                }
772                if let Some(labels) = d.and_then(|d| d.get("labels")).and_then(|v| v.as_array()) {
773                    ts.extend(labels.iter().filter_map(|l| {
774                        l.get("name")
775                            .and_then(|v| v.as_str())
776                            .map(|l| format!("label:{l}"))
777                    }));
778                }
779                ts
780            }
781            Shape::File => {
782                let t = d
783                    .and_then(|d| d.get("type"))
784                    .and_then(|v| v.as_str())
785                    .unwrap_or("file");
786                vec![t.to_string()]
787            }
788        }
789    }
790
791    /// Curated scalars per kind; timestamps answer as instants,
792    /// `::topics` and `::labels` as lists.
793    fn property(&self, node: NodeId, name: &str) -> Option<Value> {
794        enum Shape {
795            User(String),
796            Repo(String),
797            Item,
798            Entry,
799        }
800        let shape = match &self.nodes.borrow()[node.0 as usize].kind {
801            Kind::User { login } => Shape::User(login.clone()),
802            Kind::Repo { key } => Shape::Repo(key.clone()),
803            Kind::Item => Shape::Item,
804            Kind::File { .. } | Kind::Dir { .. } => Shape::Entry,
805            _ => return None,
806        };
807        let at = |d: &Json, ptr: &str| d.pointer(ptr).and_then(json_scalar);
808        match shape {
809            Shape::User(login) => {
810                let d = self.user_data(node, &login)?;
811                let key = match name {
812                    "login" => "/login",
813                    "name" => "/name",
814                    "bio" => "/bio",
815                    "company" => "/company",
816                    "location" => "/location",
817                    "blog" => "/blog",
818                    "email" => "/email",
819                    "followers" => "/followers",
820                    "following" => "/following",
821                    "repos" => "/public_repos",
822                    "gists" => "/public_gists",
823                    "created" => "/created_at",
824                    "updated" => "/updated_at",
825                    "type" => "/type",
826                    _ => return None,
827                };
828                at(&d, key)
829            }
830            Shape::Repo(rkey) => {
831                // Listing objects cover most reads; watchers and
832                // license force the full object.
833                let full = matches!(name, "watchers" | "license");
834                let d = self.repo_data(node, &rkey, full)?;
835                match name {
836                    "topics" => {
837                        let ts = d.get("topics")?.as_array()?;
838                        Some(Value::list(
839                            ts.iter()
840                                .filter_map(|t| Some(Value::Str(t.as_str()?.to_string())))
841                                .collect(),
842                        ))
843                    }
844                    "owner" => at(&d, "/owner/login"),
845                    // A listing object omits `parent`; a fork
846                    // completes itself before answering.
847                    "parent" => {
848                        let d = if d.get("parent").is_none()
849                            && d.get("fork").and_then(|v| v.as_bool()) == Some(true)
850                        {
851                            self.repo_data(node, &rkey, true)?
852                        } else {
853                            d
854                        };
855                        at(&d, "/parent/full_name")
856                    }
857                    "license" => at(&d, "/license/spdx_id"),
858                    _ => {
859                        let key = match name {
860                            "name" => "/name",
861                            "full-name" => "/full_name",
862                            "description" => "/description",
863                            "stars" => "/stargazers_count",
864                            "forks" => "/forks_count",
865                            "watchers" => "/subscribers_count",
866                            "open-issues" => "/open_issues_count",
867                            "language" => "/language",
868                            "default-branch" => "/default_branch",
869                            "homepage" => "/homepage",
870                            // The API reports a repository's size in
871                            // kibibytes; minted in that unit (spec:
872                            // adapters mint a measure as a quantity).
873                            "size" => return at(&d, "/size").map(kib),
874                            "created" => "/created_at",
875                            "updated" => "/updated_at",
876                            "pushed" => "/pushed_at",
877                            _ => return None,
878                        };
879                        at(&d, key)
880                    }
881                }
882            }
883            Shape::Item => {
884                let d = self.data(node)?;
885                match name {
886                    "labels" => {
887                        let ls = d.get("labels")?.as_array()?;
888                        Some(Value::list(
889                            ls.iter()
890                                .filter_map(|l| {
891                                    Some(Value::Str(l.get("name")?.as_str()?.to_string()))
892                                })
893                                .collect(),
894                        ))
895                    }
896                    "author" => at(&d, "/user/login").or_else(|| at(&d, "/author/login")),
897                    "milestone" => at(&d, "/milestone/title"),
898                    "base" => at(&d, "/base/ref"),
899                    "head" => at(&d, "/head/ref"),
900                    _ => {
901                        let key = match name {
902                            "number" => "/number",
903                            "title" => "/title",
904                            "state" => "/state",
905                            "comments" => "/comments",
906                            "created" => "/created_at",
907                            "updated" => "/updated_at",
908                            "closed" => "/closed_at",
909                            "merged" => "/merged_at",
910                            "tag" => "/tag_name",
911                            "name" => "/name",
912                            "published" => "/published_at",
913                            _ => return None,
914                        };
915                        at(&d, key)
916                    }
917                }
918            }
919            Shape::Entry => {
920                let d = self.data(node)?;
921                match name {
922                    // An entry's size in bytes, a quantity.
923                    "size" => at(&d, "/size").map(bytes),
924                    "type" => at(&d, "/type"),
925                    _ => None,
926                }
927            }
928        }
929    }
930
931    /// A file's decoded content; an issue's, pull's, or
932    /// release's body text.
933    fn default_value(&self, node: NodeId) -> Option<Value> {
934        let (repo, path) = match &self.nodes.borrow()[node.0 as usize].kind {
935            Kind::File { repo, path } => (repo.clone(), path.clone()),
936            Kind::Item => {
937                let d = self.data(node)?;
938                let body = d.get("body")?.as_str()?;
939                return Some(Value::Str(body.to_string()));
940            }
941            _ => return None,
942        };
943        self.file_content(&repo, &path).map(Value::Str)
944    }
945
946    /// The `:::` keys this adapter answers (`:meta` lists the ones
947
948    /// a node answers).
949
950    fn metadata_catalogue(&self) -> &'static [&'static str] {
951        &["path", "url", "contributor"]
952    }
953
954    fn metadata(&self, node: NodeId, key: &str) -> Option<Value> {
955        match key {
956            "path" => Some(Value::Str(self.locator(node))),
957            "url" => {
958                let d = self.data(node)?;
959                Some(Value::Str(d.get("html_url")?.as_str()?.to_string()))
960            }
961            _ => None,
962        }
963    }
964
965    /// `::owner-->`, `::parent-->` (a fork's upstream),
966    /// `::author-->`.
967    fn resolve(&self, node: NodeId, property: &str, _hint: Option<&str>) -> Option<NodeId> {
968        let kind_key = match &self.nodes.borrow()[node.0 as usize].kind {
969            Kind::Repo { key } => Some(key.clone()),
970            Kind::Item => None,
971            _ => return None,
972        };
973        match (kind_key, property) {
974            (Some(key), "owner") => {
975                let d = self.repo_data(node, &key, false)?;
976                let login = d.pointer("/owner/login")?.as_str()?;
977                Some(self.user_node(login, d.get("owner")))
978            }
979            (Some(key), "parent") => {
980                let d = self.repo_data(node, &key, false)?;
981                let d = if d.get("parent").is_none()
982                    && d.get("fork").and_then(|v| v.as_bool()) == Some(true)
983                {
984                    self.repo_data(node, &key, true)?
985                } else {
986                    d
987                };
988                let pkey = d.pointer("/parent/full_name")?.as_str()?.to_string();
989                Some(self.repo_node(&pkey, d.get("parent")))
990            }
991            (None, "author") => {
992                let d = self.data(node)?;
993                self.author_of(&d)
994            }
995            _ => None,
996        }
997    }
998
999    /// The outgoing fabric: `follows`, `starred`, and `org`
1000    /// from a user; `owner`, `parent`, and `contributor` from a
1001    /// repository; `author` and `assignee` from an item.
1002    fn links(&self, node: NodeId) -> Vec<(String, NodeId)> {
1003        enum Shape {
1004            User(String),
1005            Repo(String),
1006            Item,
1007        }
1008        let shape = match &self.nodes.borrow()[node.0 as usize].kind {
1009            Kind::User { login } => Shape::User(login.clone()),
1010            Kind::Repo { key } => Shape::Repo(key.clone()),
1011            Kind::Item => Shape::Item,
1012            _ => return Vec::new(),
1013        };
1014        let mut out = Vec::new();
1015        match shape {
1016            Shape::User(login) => {
1017                for u in self.call_paged(&format!("/users/{login}/following")) {
1018                    if let Some(l) = u.get("login").and_then(|v| v.as_str()) {
1019                        out.push(("follows".to_string(), self.user_node(l, Some(&u))));
1020                    }
1021                }
1022                for r in self.call_paged(&format!("/users/{login}/starred")) {
1023                    if let Some(k) = r.get("full_name").and_then(|v| v.as_str()) {
1024                        out.push(("starred".to_string(), self.repo_node(k, Some(&r))));
1025                    }
1026                }
1027                for o in self.call_paged(&format!("/users/{login}/orgs")) {
1028                    if let Some(l) = o.get("login").and_then(|v| v.as_str()) {
1029                        out.push(("org".to_string(), self.user_node(l, Some(&o))));
1030                    }
1031                }
1032            }
1033            Shape::Repo(key) => {
1034                if let Some(n) = self.resolve(node, "owner", None) {
1035                    out.push(("owner".to_string(), n));
1036                }
1037                if let Some(n) = self.resolve(node, "parent", None) {
1038                    out.push(("parent".to_string(), n));
1039                }
1040                for c in self.call_paged(&format!("/repos/{key}/contributors")) {
1041                    let Some(l) = c.get("login").and_then(|v| v.as_str()) else {
1042                        continue;
1043                    };
1044                    if let Some(n) = c.get("contributions").and_then(|v| v.as_i64()) {
1045                        self.contributions
1046                            .borrow_mut()
1047                            .insert(format!("{key}@{l}"), n);
1048                    }
1049                    out.push(("contributor".to_string(), self.user_node(l, Some(&c))));
1050                }
1051            }
1052            Shape::Item => {
1053                let Some(d) = self.data(node) else {
1054                    return out;
1055                };
1056                if let Some(n) = self.author_of(&d) {
1057                    out.push(("author".to_string(), n));
1058                }
1059                if let Some(assignees) = d.get("assignees").and_then(|v| v.as_array()) {
1060                    for a in assignees {
1061                        if let Some(l) = a.get("login").and_then(|v| v.as_str()) {
1062                            out.push(("assignee".to_string(), self.user_node(l, Some(a))));
1063                        }
1064                    }
1065                }
1066            }
1067        }
1068        out
1069    }
1070
1071    /// The incoming fabric, from the API's own reverse indexes:
1072    /// a user's followers (`<-follows`), an org's members
1073    /// (`<-org`), a repository's stargazers (`<-starred`) and
1074    /// forks (`<-parent`).
1075    fn backlinks(&self, node: NodeId) -> Vec<(String, NodeId)> {
1076        enum Shape {
1077            User(String),
1078            Repo(String),
1079        }
1080        let shape = match &self.nodes.borrow()[node.0 as usize].kind {
1081            Kind::User { login } => Shape::User(login.clone()),
1082            Kind::Repo { key } => Shape::Repo(key.clone()),
1083            _ => return Vec::new(),
1084        };
1085        let mut out = Vec::new();
1086        match shape {
1087            Shape::User(login) => {
1088                for u in self.call_paged(&format!("/users/{login}/followers")) {
1089                    if let Some(l) = u.get("login").and_then(|v| v.as_str()) {
1090                        out.push(("follows".to_string(), self.user_node(l, Some(&u))));
1091                    }
1092                }
1093                let is_org = self.traits(node).contains(&"organization".to_string());
1094                if is_org {
1095                    for m in self.call_paged(&format!("/orgs/{login}/members")) {
1096                        if let Some(l) = m.get("login").and_then(|v| v.as_str()) {
1097                            out.push(("org".to_string(), self.user_node(l, Some(&m))));
1098                        }
1099                    }
1100                }
1101            }
1102            Shape::Repo(key) => {
1103                for u in self.call_paged(&format!("/repos/{key}/stargazers")) {
1104                    if let Some(l) = u.get("login").and_then(|v| v.as_str()) {
1105                        out.push(("starred".to_string(), self.user_node(l, Some(&u))));
1106                    }
1107                }
1108                for r in self.call_paged(&format!("/repos/{key}/forks")) {
1109                    if let Some(k) = r.get("full_name").and_then(|v| v.as_str()) {
1110                        out.push(("parent".to_string(), self.repo_node(k, Some(&r))));
1111                    }
1112                }
1113            }
1114        }
1115        out
1116    }
1117
1118    /// The contributor edge carries its commit count:
1119    /// `$-::contributions`.
1120    fn link_property(
1121        &self,
1122        source: NodeId,
1123        label: &str,
1124        target: NodeId,
1125        name: &str,
1126    ) -> Option<Value> {
1127        if label != "contributor" || name != "contributions" {
1128            return None;
1129        }
1130        let key = match &self.nodes.borrow()[source.0 as usize].kind {
1131            Kind::Repo { key } => key.clone(),
1132            _ => return None,
1133        };
1134        let login = match &self.nodes.borrow()[target.0 as usize].kind {
1135            Kind::User { login } => login.clone(),
1136            _ => return None,
1137        };
1138        self.contributions
1139            .borrow()
1140            .get(&format!("{key}@{login}"))
1141            .copied()
1142            .map(Value::Int)
1143    }
1144}
1145
1146#[cfg(test)]
1147mod tests {
1148    use super::*;
1149    use serde_json::json;
1150
1151    #[test]
1152    fn base64_roundtrip() {
1153        assert_eq!(
1154            base64_decode("aGVsbG8gcXVhcmI=").as_deref(),
1155            Some(b"hello quarb".as_slice())
1156        );
1157        assert_eq!(
1158            base64_decode("aGVsbG8g\ncXVhcmI=\n").as_deref(),
1159            Some(b"hello quarb".as_slice())
1160        );
1161        assert!(base64_decode("not!base64").is_none());
1162    }
1163
1164    #[test]
1165    fn timestamps_become_instants() {
1166        assert!(matches!(
1167            str_value("2011-01-25T18:44:36Z"),
1168            Value::Instant { .. }
1169        ));
1170        assert!(matches!(str_value("v1.0.0"), Value::Str(_)));
1171    }
1172
1173    #[test]
1174    fn item_traits_from_shape() {
1175        let a = GithubAdapter {
1176            gh: "false".into(),
1177            anchor: Vec::new(),
1178            nodes: RefCell::new(vec![Node {
1179                kind: Kind::Root,
1180                name: None,
1181                parent: None,
1182                children: RefCell::new(None),
1183                data: RefCell::new(None),
1184            }]),
1185            users: RefCell::new(HashMap::new()),
1186            repos: RefCell::new(HashMap::new()),
1187            items: RefCell::new(HashMap::new()),
1188            contributions: RefCell::new(HashMap::new()),
1189            contents: RefCell::new(HashMap::new()),
1190        };
1191        let issue = a.push_node(
1192            Kind::Item,
1193            Some("1".into()),
1194            None,
1195            Some(json!({"number": 1, "state": "open",
1196                "labels": [{"name": "bug"}, {"name": "good first issue"}]})),
1197        );
1198        assert_eq!(
1199            a.traits(issue),
1200            ["issue", "open", "label:bug", "label:good first issue"]
1201        );
1202        let pull = a.push_node(
1203            Kind::Item,
1204            Some("2".into()),
1205            None,
1206            Some(json!({"number": 2, "state": "closed", "head": {"ref": "x"},
1207                "merged_at": "2026-01-01T00:00:00Z", "labels": []})),
1208        );
1209        assert_eq!(a.traits(pull), ["pull", "closed", "merged"]);
1210        let release = a.push_node(
1211            Kind::Item,
1212            Some("v1".into()),
1213            None,
1214            Some(json!({"tag_name": "v1", "prerelease": true})),
1215        );
1216        assert_eq!(a.traits(release), ["release", "prerelease"]);
1217    }
1218
1219    #[test]
1220    fn repo_traits_include_flags_and_topics() {
1221        let a = GithubAdapter {
1222            gh: "false".into(),
1223            anchor: Vec::new(),
1224            nodes: RefCell::new(vec![Node {
1225                kind: Kind::Root,
1226                name: None,
1227                parent: None,
1228                children: RefCell::new(None),
1229                data: RefCell::new(None),
1230            }]),
1231            users: RefCell::new(HashMap::new()),
1232            repos: RefCell::new(HashMap::new()),
1233            items: RefCell::new(HashMap::new()),
1234            contributions: RefCell::new(HashMap::new()),
1235            contents: RefCell::new(HashMap::new()),
1236        };
1237        let r = a.push_node(
1238            Kind::Repo { key: "o/r".into() },
1239            Some("r".into()),
1240            None,
1241            Some(json!({"fork": true, "archived": false,
1242                "topics": ["cli", "rust"]})),
1243        );
1244        assert_eq!(a.traits(r), ["repo", "fork", "topic:cli", "topic:rust"]);
1245    }
1246
1247    #[test]
1248    fn target_needs_the_scheme() {
1249        assert!(matches!(
1250            GithubAdapter::connect("gh:torvalds"),
1251            Err(GithubError::Target(_))
1252        ));
1253    }
1254}