@m0saic/templates 0.2.0

package/dist/m0saic/github/client.js

@@ -0,0 +1,161 @@
+"use strict";
+/**
+ * GitHub REST client for the `repo-facts-fetcher` (F5).
+ *
+ * Low-level transport ONLY — auth-header assembly, Link-header pagination,
+ * `202` warm-up retry for `stats/*`, a per-run call-budget ledger, and thin
+ * typed wrappers for the endpoints in the F5 plan (Seam B). It returns
+ * close-to-raw GitHub JSON; normalizing that into the bounded `GithubRepoFacts`
+ * sheet (coverage record, degradation ladder, star-Δ walk) is the fetcher's job
+ * (Phase 2), not this file's.
+ *
+ * `fetch` and `sleep` are INJECTABLE (constructor args, sane global defaults) so
+ * unit tests stub transport + retry timing without module hacks or real waits.
+ *
+ * GitHub-API only. `baseUrl` targets `api.github.com` or a GitHub Enterprise
+ * host that speaks the same REST API — NOT a Gitea/Forgejo forge (their `/api/v1`
+ * shapes differ; e.g. FFmpeg's `code.ffmpeg.org` uses `stars_count`, not
+ * `stargazers_count`). A forge connector is a separate, deferred publisher.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GithubClient = void 0;
+exports.parseLinkHeader = parseLinkHeader;
+exports.windowToSinceUntil = windowToSinceUntil;
+const week_math_1 = require("./week-math");
+const DEFAULT_BASE = "https://api.github.com";
+const API_VERSION = "2022-11-28";
+const JSON_ACCEPT = "application/vnd.github+json";
+const STAR_ACCEPT = "application/vnd.github.star+json";
+/** Parse a GitHub `Link` header into rel-targets. */
+function parseLinkHeader(header) {
+    const links = {};
+    if (!header)
+        return links;
+    for (const part of header.split(",")) {
+        const m = /<([^>]+)>;\s*rel="(next|prev|first|last)"/.exec(part.trim());
+        if (m)
+            links[m[2]] = m[1];
+    }
+    return links;
+}
+/** Committer-date window → GitHub `since`/`until` query params.
+ *  `end` is inclusive Sunday, so `until` is `end + 1 day` at 00:00Z. */
+function windowToSinceUntil(window) {
+    return {
+        since: `${window.startISO}T00:00:00Z`,
+        until: `${(0, week_math_1.addDaysISO)(window.endISO, 1)}T00:00:00Z`,
+    };
+}
+class GithubClient {
+    constructor(opts = {}) {
+        var _a, _b, _c, _d, _e;
+        this.calls = 0;
+        this.baseUrl = (((_a = opts.baseUrl) === null || _a === void 0 ? void 0 : _a.trim()) || DEFAULT_BASE).replace(/\/+$/, "");
+        this.token = opts.token && opts.token.length > 0 ? opts.token : undefined;
+        this.authenticated = this.token !== undefined;
+        this.fetchImpl = (_b = opts.fetchImpl) !== null && _b !== void 0 ? _b : globalThis.fetch;
+        this.sleep = (_c = opts.sleep) !== null && _c !== void 0 ? _c : ((ms) => new Promise((r) => setTimeout(r, ms)));
+        this.callBudget = (_d = opts.callBudget) !== null && _d !== void 0 ? _d : Infinity;
+        this.userAgent = (_e = opts.userAgent) !== null && _e !== void 0 ? _e : "m0saic-github-connector";
+        this.signal = opts.signal;
+    }
+    /** API calls made so far (for the fetcher's coverage/truncation record). */
+    callsMade() {
+        return this.calls;
+    }
+    headers(accept) {
+        const h = {
+            Accept: accept,
+            "User-Agent": this.userAgent,
+            "X-GitHub-Api-Version": API_VERSION,
+        };
+        // Secret hygiene: the token exists ONLY in this request header.
+        if (this.token)
+            h.Authorization = `Bearer ${this.token}`;
+        return h;
+    }
+    /** One raw request. Never throws on HTTP status; budget-exhaustion returns a
+     *  `budgetHit` sentinel so the fetcher can record truncation instead of dying. */
+    async request(path, accept = JSON_ACCEPT) {
+        var _a, _b, _c;
+        if (this.calls >= this.callBudget) {
+            return { status: 0, ok: false, body: undefined, links: {}, budgetHit: true };
+        }
+        this.calls++;
+        const url = path.startsWith("http") ? path : `${this.baseUrl}${path.startsWith("/") ? "" : "/"}${path}`;
+        const res = await this.fetchImpl(url, { headers: this.headers(accept), signal: this.signal });
+        const lim = (_a = res.headers) === null || _a === void 0 ? void 0 : _a.get("x-ratelimit-limit");
+        const rem = (_b = res.headers) === null || _b === void 0 ? void 0 : _b.get("x-ratelimit-remaining");
+        if (lim != null && rem != null)
+            this.rateLimit = { limit: Number(lim), remaining: Number(rem) };
+        let body;
+        try {
+            body = (await res.json());
+        }
+        catch {
+            body = undefined;
+        }
+        return { status: res.status, ok: res.ok, body, links: parseLinkHeader((_c = res.headers) === null || _c === void 0 ? void 0 : _c.get("link")), budgetHit: false };
+    }
+    /** Walk `rel="next"` pages, concatenating arrays, until exhausted / capped /
+     *  budget-hit. Stops on the first non-200 or non-array page. */
+    async paginate(path, opts = {}) {
+        var _a, _b;
+        const accept = (_a = opts.accept) !== null && _a !== void 0 ? _a : JSON_ACCEPT;
+        const maxItems = (_b = opts.maxItems) !== null && _b !== void 0 ? _b : Infinity;
+        const items = [];
+        let url = path;
+        while (url) {
+            const r = await this.request(url, accept);
+            if (r.budgetHit)
+                return { items, truncated: true, budgetHit: true };
+            if (r.status !== 200 || !Array.isArray(r.body))
+                break;
+            items.push(...r.body);
+            if (items.length >= maxItems)
+                return { items: items.slice(0, maxItems), truncated: true, budgetHit: false };
+            url = r.links.next;
+        }
+        return { items, truncated: false, budgetHit: false };
+    }
+    /** `stats/*` endpoints answer `202` while GitHub computes — bounded retry via
+     *  the injected `sleep`. Returns the last response (may still be 202/422). */
+    async getStats(path, opts = {}) {
+        var _a, _b;
+        const retries = (_a = opts.retries) !== null && _a !== void 0 ? _a : 3;
+        const waitMs = (_b = opts.waitMs) !== null && _b !== void 0 ? _b : 1500;
+        let r = await this.request(path);
+        for (let i = 0; i < retries && r.status === 202 && !r.budgetHit; i++) {
+            await this.sleep(waitMs);
+            r = await this.request(path);
+        }
+        return r;
+    }
+    // ── typed thin wrappers (Seam B endpoints) ──────────────────────────────
+    getRepo(repo) {
+        return this.request(`/repos/${repo}`);
+    }
+    /** Window commits (the API filters `since`/`until` on COMMITTER date). */
+    listCommits(repo, window, opts = {}) {
+        const { since, until } = windowToSinceUntil(window);
+        return this.paginate(`/repos/${repo}/commits?since=${since}&until=${until}&per_page=100`, { maxItems: opts.maxItems });
+    }
+    getCommitDetail(repo, sha) {
+        return this.request(`/repos/${repo}/commits/${sha}`);
+    }
+    getCommitActivity(repo) {
+        return this.getStats(`/repos/${repo}/stats/commit_activity`);
+    }
+    getCodeFrequency(repo) {
+        return this.getStats(`/repos/${repo}/stats/code_frequency`);
+    }
+    /** One page of stargazers WITH `starred_at` (the `star+json` media type).
+     *  Anonymous requests get `401` here — the fetcher degrades on that. */
+    getStargazersPage(repo, page) {
+        return this.request(`/repos/${repo}/stargazers?per_page=100&page=${page}`, STAR_ACCEPT);
+    }
+    getRateLimit() {
+        return this.request(`/rate_limit`);
+    }
+}
+exports.GithubClient = GithubClient;

package/dist/m0saic/github/connection.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `github@default` — the host connection for the GitHub data connector (F5).
+ *
+ * Declares what the fetcher needs (a GitHub API base URL + an optional PAT) so
+ * the host renders a form under Settings → Integrations, and a probe that
+ * distinguishes reachable-vs-authenticated by hitting `/rate_limit` (which costs
+ * no rate budget). Registration is a module-eval side effect — importing this
+ * file (via the `github/` barrel, re-exported from the templates registry)
+ * makes `github@default` appear in both the Electron app and the CLI.
+ *
+ * Secret handling: the token is a `secret`-kind field stored in the OS keychain;
+ * the fetcher reads it back via `ctx.secrets.get(mintConnectionSecretRef(id,
+ * "token"))`. Cleartext reaches the probe only (host process), never a document.
+ */
+import type { MosaicHostConnectionProbe, MosaicHostConnectionRegistration, MosaicHostConnectionSchema } from "@m0saic/types";
+/** Canonical connection id. `publisher` = `github`, `profile` = `default`. */
+export declare const GITHUB_CONNECTION_ID: import("@m0saic/types").MosaicHostConnectionId;
+/** The `secret`-kind field key the fetcher mints a SecretRef for. */
+export declare const GITHUB_TOKEN_FIELD = "token";
+export declare const GITHUB_CONNECTION_SCHEMA: MosaicHostConnectionSchema;
+/** Probe: `GET {baseUrl}/rate_limit`. `authenticated` iff a token was sent and
+ *  accepted (a rejected token 401s; anonymous succeeds with the 60/hr bucket). */
+export declare const githubConnectionProbe: MosaicHostConnectionProbe;
+export declare const GITHUB_CONNECTION_REGISTRATION: MosaicHostConnectionRegistration;

package/dist/m0saic/github/connection.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * `github@default` — the host connection for the GitHub data connector (F5).
+ *
+ * Declares what the fetcher needs (a GitHub API base URL + an optional PAT) so
+ * the host renders a form under Settings → Integrations, and a probe that
+ * distinguishes reachable-vs-authenticated by hitting `/rate_limit` (which costs
+ * no rate budget). Registration is a module-eval side effect — importing this
+ * file (via the `github/` barrel, re-exported from the templates registry)
+ * makes `github@default` appear in both the Electron app and the CLI.
+ *
+ * Secret handling: the token is a `secret`-kind field stored in the OS keychain;
+ * the fetcher reads it back via `ctx.secrets.get(mintConnectionSecretRef(id,
+ * "token"))`. Cleartext reaches the probe only (host process), never a document.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GITHUB_CONNECTION_REGISTRATION = exports.githubConnectionProbe = exports.GITHUB_CONNECTION_SCHEMA = exports.GITHUB_TOKEN_FIELD = exports.GITHUB_CONNECTION_ID = void 0;
+const types_1 = require("@m0saic/types");
+const template_utils_1 = require("@m0saic/template-utils");
+const client_1 = require("./client");
+/** Canonical connection id. `publisher` = `github`, `profile` = `default`. */
+exports.GITHUB_CONNECTION_ID = (0, types_1.asMosaicHostConnectionId)("github@default");
+/** The `secret`-kind field key the fetcher mints a SecretRef for. */
+exports.GITHUB_TOKEN_FIELD = "token";
+exports.GITHUB_CONNECTION_SCHEMA = {
+    id: exports.GITHUB_CONNECTION_ID,
+    version: 1,
+    label: "GitHub",
+    description: "Read-only access to a GitHub repository's public activity (commits, contributors, stars) for data templates like the Weekly Pulse.",
+    publisher: "github",
+    fields: [
+        {
+            kind: "url",
+            key: "baseUrl",
+            label: "API base URL",
+            required: false,
+            placeholder: "https://api.github.com",
+            description: "GitHub or GitHub Enterprise REST API base. Must speak the GitHub REST API — NOT a Gitea/Forgejo forge (e.g. code.ffmpeg.org). Leave blank for github.com.",
+        },
+        {
+            kind: "secret",
+            key: exports.GITHUB_TOKEN_FIELD,
+            label: "Personal access token",
+            required: false,
+            storage: "keychain",
+            description: "Optional fine-grained PAT with read-only Contents + Metadata scope. Without it, requests are anonymous (60 req/hr) and coverage degrades — no per-commit file stats, no star deltas.",
+        },
+    ],
+};
+/** Probe: `GET {baseUrl}/rate_limit`. `authenticated` iff a token was sent and
+ *  accepted (a rejected token 401s; anonymous succeeds with the 60/hr bucket). */
+exports.githubConnectionProbe = {
+    async probe(values, opts) {
+        var _a, _b, _c;
+        const baseUrl = typeof values.baseUrl === "string" ? values.baseUrl : undefined;
+        const token = typeof values.token === "string" ? values.token : undefined;
+        const tokenProvided = token !== undefined && token.length > 0;
+        // Best-effort timeout when the host didn't pass its own signal.
+        let signal = opts === null || opts === void 0 ? void 0 : opts.signal;
+        const AS = globalThis.AbortSignal;
+        if (!signal && typeof (AS === null || AS === void 0 ? void 0 : AS.timeout) === "function") {
+            signal = AS.timeout((_a = opts === null || opts === void 0 ? void 0 : opts.timeoutMs) !== null && _a !== void 0 ? _a : 10000);
+        }
+        const client = new client_1.GithubClient({ baseUrl, token, fetchImpl: opts === null || opts === void 0 ? void 0 : opts.fetchImpl, signal });
+        let res;
+        try {
+            res = await client.getRateLimit();
+        }
+        catch (e) {
+            return { ok: false, code: "UNREACHABLE", message: `Could not reach ${client.baseUrl}: ${e instanceof Error ? e.message : String(e)}` };
+        }
+        if (res.status === 401) {
+            return { ok: false, code: "AUTH_FAILED", message: "The access token was rejected (HTTP 401)." };
+        }
+        if (res.status !== 200) {
+            return { ok: false, code: "UNREACHABLE", message: `Unexpected response from ${client.baseUrl}/rate_limit (HTTP ${res.status}).` };
+        }
+        const core = (_c = (_b = res.body) === null || _b === void 0 ? void 0 : _b.resources) === null || _c === void 0 ? void 0 : _c.core;
+        return {
+            ok: true,
+            reachable: true,
+            authenticated: tokenProvided,
+            ...(core ? { info: { limit: core.limit, remaining: core.remaining } } : {}),
+        };
+    },
+};
+exports.GITHUB_CONNECTION_REGISTRATION = {
+    schema: exports.GITHUB_CONNECTION_SCHEMA,
+    probe: exports.githubConnectionProbe,
+};
+(0, template_utils_1.registerHostConnection)(exports.GITHUB_CONNECTION_REGISTRATION);

package/dist/m0saic/github/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * GitHub data connector pack (F5). The FIRST real consumer of the F1
+ * capability surface (host connections + secrets + upstream threading).
+ *
+ *   - connection.ts  : the `github@default` host connection (side-effect
+ *                      registered on import — reaches the app AND the CLI).
+ *   - client.ts      : injectable-fetch GitHub REST client.
+ *   - week-math.ts   : pure ISO-week / Monday-window arithmetic.
+ *
+ * Phases 2–3 add `repo-facts-fetcher/v1` (capability-tier fetcher →
+ * `githubRepoFacts`) and `weekly-pulse-adapter/v1` (core-tier pure adapter →
+ * `weeklyPulse`), exported here as they land.
+ */
+export * from "./connection";
+export * from "./client";
+export * from "./week-math";
+export * from "./repo-facts-fetcher";
+export * from "./weekly-pulse-adapter";
+export * from "./weekly-pulse";
+export * from "./year-card";

package/dist/m0saic/github/index.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * GitHub data connector pack (F5). The FIRST real consumer of the F1
+ * capability surface (host connections + secrets + upstream threading).
+ *
+ *   - connection.ts  : the `github@default` host connection (side-effect
+ *                      registered on import — reaches the app AND the CLI).
+ *   - client.ts      : injectable-fetch GitHub REST client.
+ *   - week-math.ts   : pure ISO-week / Monday-window arithmetic.
+ *
+ * Phases 2–3 add `repo-facts-fetcher/v1` (capability-tier fetcher →
+ * `githubRepoFacts`) and `weekly-pulse-adapter/v1` (core-tier pure adapter →
+ * `weeklyPulse`), exported here as they land.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Side-effect: registers the `github@default` host connection.
+__exportStar(require("./connection"), exports);
+__exportStar(require("./client"), exports);
+__exportStar(require("./week-math"), exports);
+// Side-effect: registers `@m0saic/github/repo-facts-fetcher/v1`.
+__exportStar(require("./repo-facts-fetcher"), exports);
+// Side-effect: registers `@m0saic/github/weekly-pulse-adapter/v1`.
+__exportStar(require("./weekly-pulse-adapter"), exports);
+// Side-effect: registers `@m0saic/github/weekly-pulse/v1` (the app-runnable,
+// capability-tier live pulse — fetch + derive + render in one template).
+__exportStar(require("./weekly-pulse"), exports);
+// Side-effect: registers `@m0saic/github/year-card/v1` (a year of contributions on one card).
+__exportStar(require("./year-card"), exports);

package/dist/m0saic/github/repo-facts-fetcher/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./v1/repo-facts-fetcher";
+export * from "./v1/facts";
+export * from "./v1/sample-facts";
+export * from "./v1/build-facts";

package/dist/m0saic/github/repo-facts-fetcher/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./v1/repo-facts-fetcher"), exports);
+__exportStar(require("./v1/facts"), exports);
+__exportStar(require("./v1/sample-facts"), exports);
+__exportStar(require("./v1/build-facts"), exports);

package/dist/m0saic/github/repo-facts-fetcher/v1/build-facts.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Live assembly: turn GitHub REST responses (via the injectable {@link
+ * GithubClient}) into a bounded {@link GithubRepoFacts} sheet.
+ *
+ * All nondeterminism lives here and is quarantined behind the client — the
+ * template's replay path never calls this, and every unit test drives it with a
+ * stubbed-fetch client. Coverage is RECORDED, never assumed: an anonymous fetch,
+ * a mirror repo, a 422 on `code_frequency`, or a spent call-budget each drop
+ * fields and say so in `coverage`.
+ *
+ * The token is used ONLY inside the client's request headers — it never reaches
+ * the facts sheet (verified by test).
+ */
+import type { GithubClient } from "../../client";
+import type { GithubIssueFacts, GithubPullFacts, GithubRepoFacts } from "./facts";
+export type BuildFactsOptions = {
+    repo: string;
+    window: {
+        startISO: string;
+        endISO: string;
+    };
+    commitDetails: "auto" | "full" | "none";
+    maxCommits: number;
+    filesPerCommit?: number;
+};
+/** Split a commit message into its headline + trailers, stripping emails from
+ *  trailer values (keeps `Reviewed-by: Name`, drops `<name@host>`). */
+export declare function parseCommitMessage(message: string): {
+    headline: string;
+    trailers?: Record<string, string[]>;
+};
+/** Count stargazers whose `starred_at` falls in the window / previous week, by
+ *  back-paginating from the newest page. ISO timestamps sort lexicographically,
+ *  so no `Date` is needed. Returns `undefined` (→ coverage.starDeltas=false) on
+ *  any 401 / budget-hit — anonymous star+json is 401, and partial counts lie. */
+export declare function computeStarDeltas(client: GithubClient, repo: string, window: {
+    startISO: string;
+    endISO: string;
+}): Promise<{
+    deltaInWindow: number;
+    deltaPrevWindow: number;
+} | undefined>;
+/** PR / issue windowed counts via the search API. Gated on `authenticated &&
+ *  hasIssues` — a mirror (hasIssues:false, e.g. FFmpeg) records both absent, so
+ *  the adapter drops PR/issue KPIs. Any failed count degrades that group to
+ *  absent rather than publishing a partial one. */
+export declare function fetchPullsIssues(client: GithubClient, repo: string, window: {
+    startISO: string;
+    endISO: string;
+}, hasIssues: boolean): Promise<{
+    pulls?: GithubPullFacts;
+    issues?: GithubIssueFacts;
+}>;
+export declare function buildRepoFacts(client: GithubClient, opts: BuildFactsOptions): Promise<GithubRepoFacts>;

package/dist/m0saic/github/repo-facts-fetcher/v1/build-facts.js

@@ -0,0 +1,238 @@
+"use strict";
+/**
+ * Live assembly: turn GitHub REST responses (via the injectable {@link
+ * GithubClient}) into a bounded {@link GithubRepoFacts} sheet.
+ *
+ * All nondeterminism lives here and is quarantined behind the client — the
+ * template's replay path never calls this, and every unit test drives it with a
+ * stubbed-fetch client. Coverage is RECORDED, never assumed: an anonymous fetch,
+ * a mirror repo, a 422 on `code_frequency`, or a spent call-budget each drop
+ * fields and say so in `coverage`.
+ *
+ * The token is used ONLY inside the client's request headers — it never reaches
+ * the facts sheet (verified by test).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCommitMessage = parseCommitMessage;
+exports.computeStarDeltas = computeStarDeltas;
+exports.fetchPullsIssues = fetchPullsIssues;
+exports.buildRepoFacts = buildRepoFacts;
+const week_math_1 = require("../../week-math");
+/** UNIX seconds → `"YYYY-MM-DD"` (Date-free, via the civil day-count). */
+function unixToISODate(sec) {
+    return (0, week_math_1.formatISODate)((0, week_math_1.civilFromDays)(Math.floor(sec / 86400)));
+}
+/** Split a commit message into its headline + trailers, stripping emails from
+ *  trailer values (keeps `Reviewed-by: Name`, drops `<name@host>`). */
+function parseCommitMessage(message) {
+    var _a;
+    const lines = (message || "").split("\n");
+    const headline = lines[0] || "";
+    const trailers = {};
+    const re = /^([A-Za-z][A-Za-z-]+):\s*(.+)$/;
+    for (const line of lines.slice(1)) {
+        const m = re.exec(line.trim());
+        if (!m || !/-by$/i.test(m[1]))
+            continue; // Reviewed-by, Signed-off-by, Co-authored-by, Tested-by, …
+        const value = m[2].replace(/\s*<[^>]*>/g, "").trim();
+        if (value)
+            (trailers[_a = m[1]] || (trailers[_a] = [])).push(value);
+    }
+    return Object.keys(trailers).length ? { headline, trailers } : { headline };
+}
+/** Count stargazers whose `starred_at` falls in the window / previous week, by
+ *  back-paginating from the newest page. ISO timestamps sort lexicographically,
+ *  so no `Date` is needed. Returns `undefined` (→ coverage.starDeltas=false) on
+ *  any 401 / budget-hit — anonymous star+json is 401, and partial counts lie. */
+async function computeStarDeltas(client, repo, window) {
+    const first = await client.getStargazersPage(repo, 1);
+    if (first.budgetHit || first.status !== 200 || !Array.isArray(first.body))
+        return undefined;
+    const lastMatch = first.links.last ? /[?&]page=(\d+)/.exec(first.links.last) : null;
+    const lastPage = lastMatch ? Number(lastMatch[1]) : 1;
+    const winStart = `${window.startISO}T00:00:00Z`;
+    const winEnd = `${(0, week_math_1.addDaysISO)(window.endISO, 1)}T00:00:00Z`;
+    const prevStart = `${(0, week_math_1.addDaysISO)(window.startISO, -7)}T00:00:00Z`;
+    let inWindow = 0;
+    let inPrev = 0;
+    for (let page = lastPage; page >= 1; page--) {
+        const r = page === 1 ? first : await client.getStargazersPage(repo, page);
+        if (r.budgetHit || r.status !== 200 || !Array.isArray(r.body) || r.body.length === 0) {
+            if (r.budgetHit)
+                return undefined;
+            break;
+        }
+        for (const s of r.body) {
+            const at = s.starred_at;
+            if (at >= winStart && at < winEnd)
+                inWindow++;
+            else if (at >= prevStart && at < winStart)
+                inPrev++;
+        }
+        // Ascending order: if this page's newest entry predates prevStart, all
+        // older pages are irrelevant.
+        if (r.body[r.body.length - 1].starred_at < prevStart)
+            break;
+    }
+    return { deltaInWindow: inWindow, deltaPrevWindow: inPrev };
+}
+/** PR / issue windowed counts via the search API. Gated on `authenticated &&
+ *  hasIssues` — a mirror (hasIssues:false, e.g. FFmpeg) records both absent, so
+ *  the adapter drops PR/issue KPIs. Any failed count degrades that group to
+ *  absent rather than publishing a partial one. */
+async function fetchPullsIssues(client, repo, window, hasIssues) {
+    if (!client.authenticated || !hasIssues)
+        return {};
+    const range = `${window.startISO}..${window.endISO}`;
+    const count = async (q) => {
+        var _a;
+        const r = await client.request(`/search/issues?q=${encodeURIComponent(q)}&per_page=1`);
+        return r.status === 200 && typeof ((_a = r.body) === null || _a === void 0 ? void 0 : _a.total_count) === "number" ? r.body.total_count : undefined;
+    };
+    const [pOpen, pOpened, pMerged, iOpen, iOpened, iClosed] = await Promise.all([
+        count(`repo:${repo} is:pr is:open`),
+        count(`repo:${repo} is:pr created:${range}`),
+        count(`repo:${repo} is:pr is:merged merged:${range}`),
+        count(`repo:${repo} is:issue is:open`),
+        count(`repo:${repo} is:issue created:${range}`),
+        count(`repo:${repo} is:issue closed:${range}`),
+    ]);
+    const pulls = pOpen !== undefined && pOpened !== undefined && pMerged !== undefined
+        ? { open: pOpen, openedInWindow: pOpened, mergedInWindow: pMerged }
+        : undefined;
+    const issues = iOpen !== undefined && iOpened !== undefined && iClosed !== undefined
+        ? { open: iOpen, openedInWindow: iOpened, closedInWindow: iClosed }
+        : undefined;
+    return { pulls, issues };
+}
+async function buildRepoFacts(client, opts) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
+    const { repo, window } = opts;
+    const filesPerCommit = (_a = opts.filesPerCommit) !== null && _a !== void 0 ? _a : 40;
+    const truncated = {};
+    // 1. repo scalars (operational error if this fails — nothing to publish).
+    const repoRes = await client.getRepo(repo);
+    if (repoRes.status !== 200 || !repoRes.body) {
+        throw new Error(`repo-facts-fetcher: could not fetch repo ${JSON.stringify(repo)} (HTTP ${repoRes.status}).`);
+    }
+    const R = repoRes.body;
+    const repoFacts = {
+        fullName: R.full_name,
+        name: R.name,
+        defaultBranch: R.default_branch,
+        ...(R.description ? { description: R.description } : {}),
+        stars: R.stargazers_count,
+        forks: R.forks_count,
+        watchers: R.subscribers_count,
+        openIssues: R.open_issues_count,
+        hasIssues: R.has_issues,
+        pushedAt: R.pushed_at,
+    };
+    // 2. window commits (API `since`/`until` filter on committer date).
+    const commitList = await client.listCommits(repo, window, { maxItems: opts.maxCommits });
+    if (commitList.truncated && commitList.items.length >= opts.maxCommits)
+        truncated.commits = opts.maxCommits;
+    if (commitList.budgetHit)
+        truncated.callBudgetHit = true;
+    const detailMode = opts.commitDetails === "auto" ? (client.authenticated ? "full" : "none") : opts.commitDetails;
+    let detailCoverage = detailMode === "none" ? "none" : "full";
+    let detailStopped = false;
+    const commits = [];
+    for (const c of commitList.items) {
+        const cm = (_b = c.commit) !== null && _b !== void 0 ? _b : {};
+        const { headline, trailers } = parseCommitMessage((_c = cm.message) !== null && _c !== void 0 ? _c : "");
+        const entry = {
+            sha: c.sha,
+            committedISO: (_e = (_d = cm.committer) === null || _d === void 0 ? void 0 : _d.date) !== null && _e !== void 0 ? _e : "",
+            authoredISO: (_g = (_f = cm.author) === null || _f === void 0 ? void 0 : _f.date) !== null && _g !== void 0 ? _g : "",
+            headline,
+            ...(trailers ? { trailers } : {}),
+            authorName: (_j = (_h = cm.author) === null || _h === void 0 ? void 0 : _h.name) !== null && _j !== void 0 ? _j : "(unknown)", // git author name, never the email
+            ...(((_k = c.author) === null || _k === void 0 ? void 0 : _k.login) ? { authorLogin: c.author.login } : {}),
+            ...(((_l = c.author) === null || _l === void 0 ? void 0 : _l.avatar_url) ? { avatarUrl: c.author.avatar_url } : {}),
+        };
+        if (detailMode === "full" && !detailStopped) {
+            const d = await client.getCommitDetail(repo, c.sha);
+            if (d.budgetHit) {
+                detailCoverage = "partial";
+                truncated.callBudgetHit = true;
+                detailStopped = true; // stop spending on details; remaining commits go bare
+            }
+            else if (d.status === 200 && ((_m = d.body) === null || _m === void 0 ? void 0 : _m.stats)) {
+                entry.additions = d.body.stats.additions;
+                entry.deletions = d.body.stats.deletions;
+                const allFiles = (_o = d.body.files) !== null && _o !== void 0 ? _o : [];
+                entry.files = allFiles.slice(0, filesPerCommit).map((f) => ({
+                    path: f.filename,
+                    additions: f.additions,
+                    deletions: f.deletions,
+                    status: f.status,
+                }));
+                if (allFiles.length > filesPerCommit)
+                    truncated.filesPerCommit = filesPerCommit;
+            }
+            else {
+                detailCoverage = "partial"; // a detail call failed but budget remains
+            }
+        }
+        commits.push(entry);
+    }
+    // 3. trailing 8 Monday-weeks (window + 7 prior) → grid + deltas.
+    const trailingStart = (0, week_math_1.addDaysISO)(window.startISO, -49);
+    const trailingList = await client.listCommits(repo, { startISO: trailingStart, endISO: window.endISO }, { maxItems: 5000 });
+    if (trailingList.budgetHit)
+        truncated.callBudgetHit = true;
+    const trailing8WeekCommitsLite = trailingList.items.map((c) => {
+        var _a, _b, _c, _d, _e, _f, _g;
+        return ({
+            sha: c.sha,
+            committedISO: (_c = (_b = (_a = c.commit) === null || _a === void 0 ? void 0 : _a.committer) === null || _b === void 0 ? void 0 : _b.date) !== null && _c !== void 0 ? _c : "",
+            ...(((_d = c.author) === null || _d === void 0 ? void 0 : _d.login) ? { authorLogin: c.author.login } : {}),
+            authorName: (_g = (_f = (_e = c.commit) === null || _e === void 0 ? void 0 : _e.author) === null || _f === void 0 ? void 0 : _f.name) !== null && _g !== void 0 ? _g : "(unknown)",
+        });
+    });
+    // 4. weekly activity (Sunday-start; may be empty if stats stayed 202).
+    const ca = await client.getCommitActivity(repo);
+    const weeklyActivity = ca.status === 200 && Array.isArray(ca.body)
+        ? ca.body.map((w) => ({ weekStartISO: unixToISODate(w.week), days: w.days, total: w.total }))
+        : [];
+    // 5. weekly code frequency (absent on 422 — repos too large, e.g. FFmpeg).
+    const cf = await client.getCodeFrequency(repo);
+    const weeklyCodeFrequency = cf.status === 200 && Array.isArray(cf.body)
+        ? cf.body.map((w) => ({ weekStartISO: unixToISODate(w[0]), additions: w[1], deletions: w[2] }))
+        : undefined;
+    // 6. stars (+ deltas when authenticated).
+    let stars = { total: R.stargazers_count };
+    let starDeltas = false;
+    if (client.authenticated) {
+        const d = await computeStarDeltas(client, repo, window);
+        if (d) {
+            stars = { total: R.stargazers_count, ...d };
+            starDeltas = true;
+        }
+    }
+    // 7. pulls / issues (authenticated + non-mirror only).
+    const { pulls, issues } = await fetchPullsIssues(client, repo, window, R.has_issues);
+    const coverage = {
+        authenticated: client.authenticated,
+        commitDetails: detailCoverage,
+        pulls: pulls !== undefined,
+        issues: issues !== undefined,
+        starDeltas,
+        ...(Object.keys(truncated).length ? { truncated } : {}),
+    };
+    return {
+        schemaVersion: 1,
+        repo: repoFacts,
+        window: { startISO: window.startISO, endISO: window.endISO },
+        commits,
+        trailing8WeekCommitsLite,
+        weeklyActivity,
+        ...(weeklyCodeFrequency ? { weeklyCodeFrequency } : {}),
+        stars,
+        ...(pulls ? { pulls } : {}),
+        ...(issues ? { issues } : {}),
+        coverage,
+        ...(client.rateLimit ? { rateLimit: client.rateLimit } : {}),
+    };
+}