co-maintainer 0.4.0-beta.1

package/dist/src/services/credentials.js

@@ -0,0 +1,146 @@
+/** Probe GitHub credentials before they are saved. A token that cannot
+ * authenticate, or an App missing the permissions in PLAN.md Section 6,
+ * is rejected instead of stored and failing later on a review. */
+import { githubFetch, GitHubHttpError } from "../github/client.js";
+import { AppJwtClient } from "../github/app.js";
+import { GhClient } from "../github/gh.js";
+const APP_NEED = {
+    metadata: "read",
+    contents: "read",
+    issues: "write",
+    pull_requests: "write",
+    checks: "write",
+};
+export function missingAppPermissions(permissions) {
+    const got = permissions ?? {};
+    const missing = [];
+    for (const [name, need] of Object.entries(APP_NEED)) {
+        const value = got[name];
+        if (need === "write") {
+            if (value !== "write")
+                missing.push(`${name} write`);
+        }
+        else if (value !== "read" && value !== "write") {
+            missing.push(`${name} read`);
+        }
+    }
+    return missing;
+}
+export async function testGithubAccess(opts) {
+    if (opts.auth === "pat")
+        return await testPat(opts.githubPat ?? "");
+    return await testGh();
+}
+export async function testAppAccess(opts) {
+    if (!opts.appId.trim() || !opts.privateKeyPem.trim()) {
+        return { ok: false, message: "App ID and private key are required." };
+    }
+    try {
+        const app = new AppJwtClient(opts.appId, opts.privateKeyPem);
+        const installations = await app.listInstallations();
+        for (const installation of installations) {
+            const missing = missingAppPermissions(installation.permissions);
+            if (missing.length === 0)
+                continue;
+            const account = installation.account?.login ?? `installation ${installation.id}`;
+            return {
+                ok: false,
+                message: `The App on ${account} is missing ${missing.join(" and ")}.`,
+            };
+        }
+        return { ok: true, installations: installations.length };
+    }
+    catch (error) {
+        return { ok: false, message: humanGithubError(error) };
+    }
+}
+async function testPat(token) {
+    if (!token.trim()) {
+        return {
+            ok: false,
+            message: "A personal access token is required for PAT access.",
+        };
+    }
+    const user = await githubGet("user", token);
+    if (user.status === 401) {
+        return { ok: false, message: "This personal access token was rejected." };
+    }
+    if (!user.ok) {
+        return { ok: false, message: "GitHub rejected this token." };
+    }
+    const scopes = user.scopes;
+    if (scopes.length > 0) {
+        const canRead = scopes.includes("repo") || scopes.includes("public_repo");
+        if (!canRead) {
+            return {
+                ok: false,
+                message: "This token cannot read repositories. Grant the repo scope.",
+            };
+        }
+        return { ok: true, login: user.login };
+    }
+    const repos = await githubGet("user/repos?per_page=1", token);
+    if (repos.status === 403 || repos.status === 401) {
+        return {
+            ok: false,
+            message: "This token cannot list repositories. Grant repository access.",
+        };
+    }
+    if (!repos.ok) {
+        return { ok: false, message: "GitHub rejected this token." };
+    }
+    return { ok: true, login: user.login };
+}
+async function testGh() {
+    try {
+        const user = await new GhClient().request("user");
+        if (!user.login) {
+            return { ok: false, message: "gh CLI did not return a GitHub login." };
+        }
+        return { ok: true, login: user.login };
+    }
+    catch {
+        return {
+            ok: false,
+            message: "gh CLI could not reach GitHub. Sign in with gh auth login.",
+        };
+    }
+}
+async function githubGet(endpoint, token) {
+    const response = await githubFetch(`https://api.github.com/${endpoint}`, {
+        headers: {
+            Accept: "application/vnd.github+json",
+            Authorization: `Bearer ${token}`,
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+    });
+    const scopes = (response.headers.get("x-oauth-scopes") ?? "")
+        .split(",")
+        .map((scope) => scope.trim())
+        .filter(Boolean);
+    if (!response.ok) {
+        return { ok: false, status: response.status, scopes };
+    }
+    let login;
+    try {
+        const body = (await response.json());
+        login = body.login;
+    }
+    catch {
+        login = undefined;
+    }
+    return { ok: true, status: response.status, login, scopes };
+}
+function humanGithubError(error) {
+    if (error instanceof GitHubHttpError) {
+        if (error.status === 401) {
+            return "GitHub rejected this App ID or private key.";
+        }
+        return "GitHub rejected this App.";
+    }
+    const text = error instanceof Error ? error.message : String(error);
+    if (text.toLowerCase().includes("private key")) {
+        return "This private key could not be read.";
+    }
+    return "GitHub rejected this App.";
+}

package/dist/src/services/dashboard.d.ts

@@ -0,0 +1,165 @@
+import { getDrift } from "../store/drift.ts";
+import { reviewStats } from "../store/reviews.ts";
+import type { DeliveryRow, JobRow, RepoRow, ReviewRow } from "../store/rows.ts";
+export declare function requireActiveRepo(fullName: string): RepoRow;
+export declare class RepoNotFound extends Error {
+    constructor(fullName: string);
+}
+export declare function statsForRange(range: string): {
+    days: number;
+    since: string;
+    totals: import("../store/reviews.ts").ReviewStats;
+    previous: import("../store/reviews.ts").ReviewStats;
+    change: {
+        pullRequests: number | undefined;
+        findings: number | undefined;
+        cost: number | undefined;
+    };
+    byRepo: (import("../store/reviews.ts").ReviewStats & {
+        repo: string;
+    })[];
+    byDay: {
+        day: string;
+        reviews: number;
+        findings: number;
+        cost: number;
+    }[];
+    byModel: (import("../store/reviews.ts").ReviewStats & {
+        model: string;
+    })[];
+    byRemoteToken: {
+        tokenId: string;
+        tokenName: string;
+        reviews: number;
+        cost: number;
+        findings: number;
+    }[];
+    bySeverity: import("../store/findings.ts").SeverityStats[];
+};
+export type RepoListItem = {
+    repo: RepoRow;
+    drift: ReturnType<typeof getDrift>;
+    stats: ReturnType<typeof reviewStats>;
+    latestJob: JobRow | undefined;
+};
+export declare function listReposForHome(): RepoListItem[];
+export declare function repoOverview(fullName: string): {
+    repo: RepoRow;
+    drift: import("../store/rows.ts").DriftRow | undefined;
+    stats: import("../store/reviews.ts").ReviewStats;
+    recentPulls: ReviewRow[];
+    latestJob: JobRow | undefined;
+};
+export declare function repoRemoteReviews(fullName: string, limit?: number): {
+    items: ReviewRow[];
+    stats: import("../store/reviews.ts").ReviewStats;
+};
+export declare function repoPulls(fullName: string, page: number, per: number): {
+    items: import("../store/reviews.ts").PullSummary[];
+    page: number;
+    per: number;
+    total: number;
+    stats: import("../store/reviews.ts").ReviewStats;
+};
+export declare function prDetail(fullName: string, prNumber: number): {
+    prNumber: number;
+    reviews: {
+        findings: {
+            repeatOf: string | undefined;
+            id: string;
+            review_id: string;
+            severity: string;
+            path: string | null;
+            line_from: number | null;
+            line_to: number | null;
+            title: string;
+            body_md: string;
+            posted_comment_id: string | null;
+            thread_comment_id: string | null;
+            first_seen_review_id: string | null;
+            anchor_text: string | null;
+            state: string;
+            carried_from_finding_id: string | null;
+            close_reason: string | null;
+        }[];
+        id: string;
+        kind: string;
+        subject_id: string | null;
+        repo: string;
+        pr_number: number | null;
+        branch: string | null;
+        token_id: string | null;
+        token_name: string | null;
+        job_id: string;
+        head_sha: string | null;
+        base_sha: string | null;
+        scope: string;
+        model: string;
+        findings_count: number;
+        open_count: number;
+        closed_count: number;
+        tokens_in: number;
+        tokens_out: number;
+        cost: number | null;
+        duration_ms: number | null;
+        posted_review_id: string | null;
+        status: string;
+        created_at: string;
+        round: number;
+        trigger: string | null;
+        check_run_id: string | null;
+        posted_fallback: number;
+        guide_built_at: string | null;
+        codegraph: string | null;
+    }[];
+};
+export declare function repoKnowledge(fullName: string): Promise<{
+    repo: RepoRow;
+    drift: import("../store/rows.ts").DriftRow | undefined;
+    docs: ({
+        bytes: number;
+        text: string;
+        id: "guide";
+        file: "PR_REVIEW_GUIDE.md";
+        title: "Review guide";
+        covers: "Checks learned from past review comments";
+    } | {
+        bytes: number;
+        text: string;
+        id: "detailed";
+        file: "PR_REVIEW_DETAILED_GUIDE.md";
+        title: "Detailed guide";
+        covers: "Evidence behind the review checks";
+    } | {
+        bytes: number;
+        text: string;
+        id: "codebase";
+        file: "CODEBASE.md";
+        title: "Codebase notes";
+        covers: "Layout, style and test conventions";
+    } | {
+        bytes: number;
+        text: string;
+        id: "skill";
+        file: "SKILL.md";
+        title: "Contribution skill";
+        covers: "How to build, test and ship here";
+    })[];
+}>;
+export type ActivityItem = {
+    kind: "job";
+    at: string;
+    job: JobRow;
+} | {
+    kind: "review";
+    at: string;
+    review: ReviewRow;
+};
+export declare function activityFeed(page: number, per: number): {
+    items: ActivityItem[];
+    page: number;
+    per: number;
+    total: number;
+};
+export declare function runningJobs(): JobRow[];
+export declare function skippedDeliveries(): DeliveryRow[];

package/dist/src/services/dashboard.js

@@ -0,0 +1,200 @@
+/** Read models for dashboard pages and the JSON APIs that mirror them. */
+import { reposDir } from "../config.js";
+import { getDrift } from "../store/drift.js";
+import { refreshDrift } from "./drift.js";
+import { listSkipped } from "../store/deliveries.js";
+import { listJobs } from "../store/jobs.js";
+import { getRepo, listActiveRepos } from "../store/repos.js";
+import { listLatestReviewsForRepo, listPullSummaries, listRecentReviews, listReviewsForPr, reviewStats, reviewStatsByDay, reviewStatsByModel, reviewStatsByRemoteToken, listRemoteReviewsForRepo, reviewStatsByRepo, } from "../store/reviews.js";
+import { findingStatsBySeverity, listFindingsForReview, } from "../store/findings.js";
+import { daysAgoIso } from "../util/time.js";
+import { isNotFound, readTextFile } from "../util/runtime.js";
+export function requireActiveRepo(fullName) {
+    const row = getRepo(fullName);
+    if (!row || row.active !== 1) {
+        throw new RepoNotFound(fullName);
+    }
+    return row;
+}
+export class RepoNotFound extends Error {
+    constructor(fullName) {
+        super(`no active repository ${fullName}`);
+        this.name = "RepoNotFound";
+    }
+}
+/** Undefined rather than a made up percentage when the earlier window had
+ * nothing to grow from, so the page can leave the trend line out instead of
+ * printing an infinite jump. */
+function percentChange(before, after) {
+    if (!before)
+        return undefined;
+    return Math.round(((after - before) / before) * 100);
+}
+/** A day with no reviews still has to occupy a slot, otherwise the bar chart
+ * silently closes the gap and a quiet week reads like a busy one. */
+function fillDays(days, rows) {
+    const byDay = new Map(rows.map((row) => [row.day, row]));
+    const out = [];
+    for (let back = days - 1; back >= 0; back--) {
+        const day = daysAgoIso(back).slice(0, 10);
+        out.push(byDay.get(day) ?? { day, reviews: 0, findings: 0, cost: 0 });
+    }
+    return out;
+}
+export function statsForRange(range) {
+    const days = range === "7d" ? 7 : range === "90d" ? 90 : 30;
+    const since = daysAgoIso(days);
+    const totals = reviewStats(since);
+    const previous = reviewStats(daysAgoIso(days * 2), undefined, since);
+    return {
+        days,
+        since,
+        totals,
+        previous,
+        change: {
+            pullRequests: percentChange(previous.pullRequests, totals.pullRequests),
+            findings: percentChange(previous.findings, totals.findings),
+            cost: percentChange(previous.cost, totals.cost),
+        },
+        byRepo: reviewStatsByRepo(since),
+        byDay: fillDays(days, reviewStatsByDay(since)),
+        byModel: reviewStatsByModel(since),
+        byRemoteToken: reviewStatsByRemoteToken(since),
+        bySeverity: findingStatsBySeverity(since),
+    };
+}
+function latestSetupJob(fullName) {
+    return listJobs({ repo: fullName }).find((job) => job.type === "init" || job.type === "remake");
+}
+export function listReposForHome() {
+    const since = daysAgoIso(30);
+    return listActiveRepos().map((repo) => ({
+        repo,
+        drift: getDrift(repo.full_name),
+        stats: reviewStats(since, repo.full_name),
+        latestJob: latestSetupJob(repo.full_name),
+    }));
+}
+export function repoOverview(fullName) {
+    const repo = requireActiveRepo(fullName);
+    const since = daysAgoIso(30);
+    return {
+        repo,
+        drift: getDrift(fullName),
+        stats: reviewStats(since, fullName),
+        recentPulls: listLatestReviewsForRepo(fullName, 8),
+        latestJob: latestSetupJob(fullName),
+    };
+}
+export function repoRemoteReviews(fullName, limit = 30) {
+    requireActiveRepo(fullName);
+    const since = daysAgoIso(30);
+    return {
+        items: listRemoteReviewsForRepo(fullName, limit, 0, since),
+        stats: reviewStats(since, fullName),
+    };
+}
+export function repoPulls(fullName, page, per) {
+    requireActiveRepo(fullName);
+    const safePage = Number.isFinite(page) && page > 0 ? Math.floor(page) : 1;
+    const safePer = Number.isFinite(per) && per > 0 ? Math.min(per, 50) : 20;
+    const { items, total } = listPullSummaries(fullName, safePer, (safePage - 1) * safePer);
+    return {
+        items,
+        page: safePage,
+        per: safePer,
+        total,
+        stats: reviewStats(daysAgoIso(30), fullName),
+    };
+}
+export function prDetail(fullName, prNumber) {
+    requireActiveRepo(fullName);
+    const reviews = listReviewsForPr(fullName, prNumber);
+    return {
+        prNumber,
+        reviews: reviews.map((review) => ({
+            ...review,
+            findings: listFindingsForReview(review.id).map((finding) => ({
+                ...finding,
+                repeatOf: finding.first_seen_review_id ?? undefined,
+            })),
+        })),
+    };
+}
+const KNOWLEDGE_DOCS = [
+    {
+        id: "guide",
+        file: "PR_REVIEW_GUIDE.md",
+        title: "Review guide",
+        covers: "Checks learned from past review comments",
+    },
+    {
+        id: "detailed",
+        file: "PR_REVIEW_DETAILED_GUIDE.md",
+        title: "Detailed guide",
+        covers: "Evidence behind the review checks",
+    },
+    {
+        id: "codebase",
+        file: "CODEBASE.md",
+        title: "Codebase notes",
+        covers: "Layout, style and test conventions",
+    },
+    {
+        id: "skill",
+        file: "SKILL.md",
+        title: "Contribution skill",
+        covers: "How to build, test and ship here",
+    },
+];
+export async function repoKnowledge(fullName) {
+    const repo = requireActiveRepo(fullName);
+    const { withKnowledgeLock } = await import("../review/guides.js");
+    return withKnowledgeLock(fullName, async () => {
+        const docs = [];
+        for (const doc of KNOWLEDGE_DOCS) {
+            const path = `${reposDir()}/${fullName}/${doc.file}`;
+            try {
+                const text = await readTextFile(path);
+                docs.push({
+                    ...doc,
+                    bytes: new TextEncoder().encode(text).byteLength,
+                    text,
+                });
+            }
+            catch (error) {
+                if (!isNotFound(error))
+                    throw error;
+            }
+        }
+        return { repo, drift: await refreshDrift(fullName), docs };
+    });
+}
+export function activityFeed(page, per) {
+    const safePage = Number.isFinite(page) && page > 0 ? Math.floor(page) : 1;
+    const safePer = Number.isFinite(per) && per > 0 ? Math.min(per, 50) : 20;
+    const items = [
+        ...listJobs().map((job) => ({
+            kind: "job",
+            at: job.created_at,
+            job,
+        })),
+        ...listRecentReviews(500).map((review) => ({
+            kind: "review",
+            at: review.created_at,
+            review,
+        })),
+    ].sort((a, b) => b.at.localeCompare(a.at));
+    const total = items.length;
+    const slice = items.slice((safePage - 1) * safePer, safePage * safePer);
+    return { items: slice, page: safePage, per: safePer, total };
+}
+export function runningJobs() {
+    return [
+        ...listJobs({ status: "running" }),
+        ...listJobs({ status: "queued" }),
+    ];
+}
+export function skippedDeliveries() {
+    return listSkipped();
+}

package/dist/src/services/drift.d.ts

@@ -0,0 +1,13 @@
+import type { DriftRow } from "../store/rows.ts";
+import type { GitHubClient } from "../types.ts";
+/** GitHub caps a compare response at 300 files, so a very large drift
+ * reports 300 and the UI reads "300+". */
+export declare const COMPARE_FILE_CAP = 300;
+/** The fallback path pages through commits, so it stops counting rather than
+ * walking a year of history. Pages read this ceiling the same way. */
+export declare const MAX_COMMITS_COUNTED = 500;
+export declare function computeDrift(client: GitHubClient, repo: string, builtAt: string, baseSha: string | null): Promise<DriftRow>;
+/** Returns the stored row, refreshing it first when it is missing or older
+ * than the freshness window. A GitHub failure keeps the previous row so a
+ * dashboard page still renders. */
+export declare function refreshDrift(fullName: string, client?: GitHubClient): Promise<DriftRow | undefined>;

package/dist/src/services/drift.js

@@ -0,0 +1,76 @@
+/** How far the repository has moved since the knowledge guide was built.
+ * The numbers come from GitHub, so they are recomputed on a timer rather
+ * than on every page render. */
+import { getRepo } from "../store/repos.js";
+import { getDrift, upsertDrift } from "../store/drift.js";
+import { clientFor } from "./review.js";
+import { nowIso } from "../util/time.js";
+const FRESH_MS = 15 * 60 * 1000;
+/** GitHub caps a compare response at 300 files, so a very large drift
+ * reports 300 and the UI reads "300+". */
+export const COMPARE_FILE_CAP = 300;
+/** The fallback path pages through commits, so it stops counting rather than
+ * walking a year of history. Pages read this ceiling the same way. */
+export const MAX_COMMITS_COUNTED = 500;
+function isCommitSha(value) {
+    return !!value && /^[0-9a-f]{40}$/.test(value);
+}
+function isFresh(row, nowMs) {
+    if (!row)
+        return false;
+    const at = Date.parse(row.as_of);
+    return Number.isFinite(at) && nowMs - at < FRESH_MS;
+}
+async function searchCount(client, query) {
+    const result = await client.request(`search/issues?per_page=1&q=${encodeURIComponent(query)}`);
+    return result.total_count ?? 0;
+}
+/** Commits and changed files in one call when we know the sha the guide was
+ * built from, otherwise a date-bounded commit list with no file count. */
+async function codeDrift(client, repo, baseSha, builtAt, defaultBranch) {
+    if (isCommitSha(baseSha)) {
+        const compare = await client.request(`repos/${repo}/compare/${baseSha}...${encodeURIComponent(defaultBranch)}`);
+        return {
+            commits: compare.total_commits ?? 0,
+            files: Math.min(compare.files?.length ?? 0, COMPARE_FILE_CAP),
+        };
+    }
+    const commits = await client.pages(`repos/${repo}/commits?sha=${encodeURIComponent(defaultBranch)}&since=${encodeURIComponent(builtAt)}`, MAX_COMMITS_COUNTED);
+    return { commits: commits.length, files: 0 };
+}
+export async function computeDrift(client, repo, builtAt, baseSha) {
+    const meta = await client.request(`repos/${repo}`);
+    const defaultBranch = String(meta.default_branch ?? "main");
+    const [opened, touched, code] = await Promise.all([
+        searchCount(client, `repo:${repo} type:pr created:>${builtAt}`),
+        searchCount(client, `repo:${repo} type:pr updated:>${builtAt} created:<${builtAt}`),
+        codeDrift(client, repo, baseSha, builtAt, defaultBranch),
+    ]);
+    return {
+        repo,
+        as_of: nowIso(),
+        prs_since: opened,
+        prs_updated: touched,
+        commits_since: code.commits,
+        files_changed: code.files,
+    };
+}
+/** Returns the stored row, refreshing it first when it is missing or older
+ * than the freshness window. A GitHub failure keeps the previous row so a
+ * dashboard page still renders. */
+export async function refreshDrift(fullName, client) {
+    const stored = getDrift(fullName);
+    if (isFresh(stored, Date.now()))
+        return stored;
+    const repo = getRepo(fullName);
+    if (!repo?.knowledge_built_at || repo.installation_id === null)
+        return stored;
+    try {
+        const row = await computeDrift(client ?? clientFor(repo.installation_id), fullName, repo.knowledge_built_at, repo.knowledge_base_sha);
+        upsertDrift(row);
+        return row;
+    }
+    catch {
+        return stored;
+    }
+}

package/dist/src/services/jobs.d.ts

@@ -0,0 +1,34 @@
+import type { JobLogRow, JobRow } from "../store/rows.ts";
+export type LogFn = (level: string, message: string) => void;
+export type JobHandler = {
+    run(job: JobRow, log: LogFn, signal: AbortSignal): Promise<void>;
+    /** Called instead of `run` for a job found in `status = 'running'` at
+     * boot: reconciles against whatever might already have happened rather
+     * than blindly repeating side effects. Omit it when `run` is idempotent. */
+    reconcile?(job: JobRow, log: LogFn): Promise<"done" | "canceled" | void>;
+};
+export declare function registerHandler(type: string, handler: JobHandler): void;
+type Subscriber = (line: JobLogRow) => void;
+export declare function subscribeToLogs(jobId: string, fn: Subscriber): () => void;
+export declare function getLogsSince(jobId: string, fromSeq?: number): JobLogRow[];
+export declare function enqueue(input: {
+    type: string;
+    repo: string;
+    prNumber?: number;
+    args?: unknown;
+    deliveryId?: string;
+    debounceMs?: number;
+    queueKey?: string;
+}): {
+    id: string;
+    debounced: boolean;
+};
+export declare function claimAndRun(): Promise<boolean>;
+export declare function startWorkerLoop(intervalMs?: number): void;
+export declare function stopWorkerLoop(): Promise<void>;
+/** Cooperative: aborts a running job's `AbortSignal` if this process is
+ * running it, or cancels it outright if it is merely queued. Returns false
+ * if neither applies (already finished, or running in another process). */
+export declare function cancel(jobId: string, reason?: string): boolean;
+export declare function recoverOrphans(): Promise<number>;
+export {};