@profullstack/g1tz 0.2.0

package/dist/pulse-view.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The Pulse screen: what moved in this repository over a period.
+ *
+ * Git on the left (overview, commits over time, authors), the wider world on
+ * the right (the files that changed, GitHub's pull requests, issues, releases
+ * and stars, and the repository's views and clones from a gh-pulse report).
+ * Pure: everything drawn comes from PulseState, so the screen is asserted on
+ * as text in the tests and captured for the hqtui.com gallery the same way.
+ */
+import { type Container, type Theme } from "@profullstack/hqtui";
+import type { GitHubPulse } from "./github.ts";
+import { type Pulse, type RangeKey } from "./pulse.ts";
+import type { Traffic } from "./traffic.ts";
+export type GitHubStatus = "idle" | "loading" | "ready" | "unavailable";
+export interface PulseState {
+    range: RangeKey;
+    data: Pulse | null;
+    github: GitHubPulse | null;
+    githubStatus: GitHubStatus;
+    /** Why GitHub is unavailable, when it is. */
+    githubNote: string;
+    /** Ticket of the latest GitHub request; a reply to an older one is dropped. */
+    githubRequest: number;
+    traffic: Traffic | null;
+    filesOffset: number;
+    note: string;
+}
+export declare function createPulseState(range?: RangeKey): PulseState;
+export interface PulseActions {
+    pickRange: (key: RangeKey) => void;
+    refresh: () => void;
+    /** Back to the repository screen. */
+    back: () => void;
+    /** Open the Pulse screen from the repository screen. */
+    pulse: () => void;
+}
+export declare const NO_ACTIONS: PulseActions;
+export interface ViewArgs {
+    ui: Container;
+    theme: Theme;
+    width: number;
+    height: number;
+    elapsed: number;
+}
+/** Keep the tail of a path, which is the part that tells files apart; the library's own truncation keeps the head. */
+export declare function shortenPath(path: string, max: number): string;
+export declare const clampOffset: (offset: number, total: number) => number;
+/**
+ * Content columns of the two panes: the body splits 1fr : 1.2fr with a gap of
+ * one, and a panel's border and padding take two on each side. An estimate,
+ * since the layout is not known until it is solved; a column short is fine,
+ * a column over is a truncated axis label.
+ */
+export declare const leftPaneColumns: (width: number) => number;
+export declare const rightPaneColumns: (width: number) => number;
+export declare function commitTotals(pulse: Pulse): {
+    commits: number;
+    merges: number;
+};
+/** What the status bar says on the right: the GitHub read, or nothing. */
+export declare function githubLine(state: PulseState, elapsed: number): string;
+export declare function pulseView({ ui, theme, width, height, elapsed }: ViewArgs, state: PulseState, root: string, actions?: PulseActions): void;

package/dist/pulse-view.js

@@ -0,0 +1,244 @@
+/**
+ * The Pulse screen: what moved in this repository over a period.
+ *
+ * Git on the left (overview, commits over time, authors), the wider world on
+ * the right (the files that changed, GitHub's pull requests, issues, releases
+ * and stars, and the repository's views and clones from a gh-pulse report).
+ * Pure: everything drawn comes from PulseState, so the screen is asserted on
+ * as text in the tests and captured for the hqtui.com gallery the same way.
+ */
+import { widgets } from "@profullstack/hqtui";
+import { RANGE_KEYS, RANGE_LABEL, foldBuckets } from "./pulse.js";
+export function createPulseState(range = "week") {
+    return {
+        range,
+        data: null,
+        github: null,
+        githubStatus: "idle",
+        githubNote: "",
+        githubRequest: 0,
+        traffic: null,
+        filesOffset: 0,
+        note: "",
+    };
+}
+export const NO_ACTIONS = { pickRange: () => { }, refresh: () => { }, back: () => { }, pulse: () => { } };
+const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+const fmtStamp = (iso) => iso.replace("T", " ").slice(0, 16);
+const names = (refs, max) => `${refs.slice(0, max).map((r) => r.name).join(", ")}${refs.length > max ? ", …" : ""}`;
+/** Keep the tail of a path, which is the part that tells files apart; the library's own truncation keeps the head. */
+export function shortenPath(path, max) {
+    if (max < 4 || path.length <= max)
+        return path;
+    return `…${path.slice(path.length - (max - 1))}`;
+}
+export const clampOffset = (offset, total) => Math.max(0, Math.min(Math.max(0, total - 1), offset));
+/**
+ * Content columns of the two panes: the body splits 1fr : 1.2fr with a gap of
+ * one, and a panel's border and padding take two on each side. An estimate,
+ * since the layout is not known until it is solved; a column short is fine,
+ * a column over is a truncated axis label.
+ */
+export const leftPaneColumns = (width) => Math.max(10, Math.floor((width - 1) / 2.2) - 4);
+export const rightPaneColumns = (width) => Math.max(10, Math.floor(((width - 1) * 1.2) / 2.2) - 4);
+export function commitTotals(pulse) {
+    let merges = 0;
+    for (const c of pulse.commits)
+        if (c.merge)
+            merges++;
+    return { commits: pulse.commits.length - merges, merges };
+}
+/** What the status bar says on the right: the GitHub read, or nothing. */
+export function githubLine(state, elapsed) {
+    switch (state.githubStatus) {
+        case "loading": return `${widgets.spinnerFrame(elapsed, widgets.SPINNER_FRAMES.dots)} GitHub`;
+        case "unavailable": return `GitHub: ${state.githubNote}`;
+        case "ready": return state.github?.partial ? "GitHub counts are floors (page budget)" : "";
+        default: return "";
+    }
+}
+function overviewPanel(col, theme, pulse) {
+    col.panel({ title: "Overview", size: 9 }, (p) => {
+        if (!pulse) {
+            p.label("Press r to read the repository.");
+            return;
+        }
+        const { commits, merges } = commitTotals(pulse);
+        const authors = pulse.authors;
+        p.keyValues([
+            {
+                label: "Commits",
+                value: `${commits} on ${pulse.branch || "HEAD"}${merges ? `, ${plural(merges, "merge")}` : ""}${pulse.commitsTruncated ? " (capped)" : ""}`,
+                color: theme.accent,
+            },
+            { label: "All branches", value: `${plural(pulse.allBranchCommits, "commit")}, merges excluded` },
+            {
+                label: "Authors",
+                value: authors.length ? `${authors.length}: ${authors.slice(0, 3).map((a) => a.name).join(", ")}${authors.length > 3 ? ", …" : ""}` : "none",
+            },
+            { label: "Changed", value: `${plural(pulse.filesChanged, "file")}, +${pulse.additions} −${pulse.deletions}`, color: theme.success },
+            { label: "Branches", value: pulse.branches.length ? `${pulse.branches.length} active: ${names(pulse.branches, 3)}` : "none active" },
+            { label: "Tags", value: pulse.tags.length ? `${pulse.tags.length} new: ${names(pulse.tags, 4)}` : "none" },
+            { label: "Period", value: `${pulse.since ? fmtStamp(pulse.since) : "the first commit"} to ${fmtStamp(pulse.until)}` },
+        ]);
+    });
+}
+function activityPanel(col, theme, pulse, label, cols) {
+    col.panel({ title: pulse ? `Commits per ${pulse.unit}` : "Commits", size: 8 }, (p) => {
+        if (!pulse)
+            return;
+        const buckets = foldBuckets(pulse.buckets, Math.max(1, Math.floor(cols / 2)));
+        const peak = buckets.reduce((m, b) => Math.max(m, b.count), 0);
+        if (peak === 0) {
+            p.label(`No commits, ${label}.`);
+            return;
+        }
+        // Each bucket is widened to fill the pane, as one column per bucket would leave most of it empty.
+        const per = Math.max(1, Math.floor(cols / Math.max(1, buckets.length)));
+        p.text(`${plural(pulse.commits.length, "commit")}, peak ${peak} in one ${pulse.unit}`, { fg: theme.muted, size: 1 });
+        p.histogram({ values: buckets.flatMap((b) => Array(per).fill(b.count)), color: theme.accent, size: 4 });
+        const first = buckets[0]?.label ?? "";
+        const last = buckets.at(-1)?.label ?? "";
+        p.text(`${first}${" ".repeat(Math.max(1, cols - first.length - last.length))}${last}`, { fg: theme.muted, size: 1 });
+    });
+}
+function authorsPanel(col, theme, pulse, label) {
+    col.panel({ title: `Authors (${pulse?.authors.length ?? 0})`, size: "1fr" }, (p) => {
+        if (!pulse || pulse.authors.length === 0) {
+            p.label(`No commits, ${label}.`);
+            return;
+        }
+        const total = pulse.authors.reduce((t, a) => t + a.commits, 0);
+        p.table({
+            rows: pulse.authors,
+            header: false,
+            scrollbar: true,
+            columns: [
+                { key: "name", title: "", min: 8, color: theme.foreground },
+                { key: "commits", title: "", width: 6, align: "right", color: theme.accent, render: (a) => String(a.commits) },
+                {
+                    key: "share",
+                    title: "",
+                    width: 16,
+                    color: theme.muted,
+                    render: (a) => {
+                        const filled = Math.round((a.commits / total) * 10);
+                        return `${"█".repeat(filled)}${"·".repeat(10 - filled)} ${Math.round((100 * a.commits) / total)}%`;
+                    },
+                },
+            ],
+        });
+    });
+}
+function filesPanel(col, theme, state, label, cols) {
+    const pulse = state.data;
+    const title = pulse ? `Files changed (${pulse.filesChanged})  +${pulse.additions} −${pulse.deletions}` : "Files changed";
+    col.panel({ title, size: "1fr" }, (p) => {
+        if (!pulse || pulse.files.length === 0) {
+            p.label(`Nothing changed, ${label}.`);
+            return;
+        }
+        const pathWidth = Math.max(8, cols - 16);
+        p.table({
+            rows: pulse.files,
+            offset: state.filesOffset,
+            header: false,
+            scrollbar: true,
+            onScroll: (delta) => { state.filesOffset = clampOffset(state.filesOffset + delta, pulse.files.length); },
+            columns: [
+                { key: "path", title: "", min: 8, color: theme.foreground, render: (f) => shortenPath(f.from ? `${f.from} → ${f.path}` : f.path, pathWidth) },
+                { key: "added", title: "", width: 7, align: "right", color: theme.success, render: (f) => (f.binary ? "bin" : `+${f.added}`) },
+                { key: "deleted", title: "", width: 7, align: "right", color: theme.danger, render: (f) => (f.binary ? "" : `−${f.deleted}`) },
+            ],
+        });
+    });
+}
+function githubPanel(col, theme, state, label, elapsed) {
+    const g = state.github;
+    col.panel({ title: g ? `GitHub  ${g.repo}` : "GitHub", size: 10 }, (p) => {
+        if (state.githubStatus === "loading") {
+            p.spinner({ label: "asking GitHub", text: label, elapsed });
+            return;
+        }
+        if (state.githubStatus !== "ready" || !g) {
+            p.text(state.githubNote || "Pull requests, issues, releases and stars appear here when gh is logged in.", { fg: theme.muted, wrap: true });
+            return;
+        }
+        p.keyValues([
+            {
+                label: "Pull requests",
+                value: `${g.prsMerged.length} merged, ${g.prsOpened.length} opened, ${g.prsClosed.length} closed unmerged`,
+                color: theme.accent,
+            },
+            { label: "Issues", value: `${g.issuesOpened.length} opened, ${g.issuesClosed.length} closed, ${g.openIssues} open now` },
+            { label: "Releases", value: g.releases.length ? `${g.releases.length}: ${g.releases.slice(0, 4).map((r) => r.tag).join(", ")}` : "none" },
+            { label: "Stars", value: `+${g.newStars}${g.partial ? " or more" : ""}, ${g.stars} total, ${plural(g.forks, "fork")}` },
+        ]);
+        const lines = [];
+        for (const pr of g.prsMerged.slice(0, 2))
+            lines.push(`merged #${pr.number} ${pr.title} (${pr.user})`);
+        for (const pr of g.prsOpened.slice(0, 1))
+            lines.push(`opened #${pr.number} ${pr.title} (${pr.user})`);
+        for (const is of g.issuesOpened.slice(0, 1))
+            lines.push(`issue #${is.number} ${is.title} (${is.user})`);
+        if (lines.length)
+            p.text(lines.join("\n"), { fg: theme.muted });
+    });
+}
+function trafficPanel(col, theme, t) {
+    col.panel({ title: t ? `Traffic  gh-pulse ${fmtStamp(t.reportAt)}` : "Traffic", size: 7 }, (p) => {
+        if (!t) {
+            p.text("Views and clones appear here when a gh-pulse report exists on this machine (~/.local/share/gh-pulse).", { fg: theme.muted, wrap: true });
+            return;
+        }
+        const sum = (series, k) => series.reduce((n, d) => n + d[k], 0);
+        const series = (s) => (s.length ? s.map((d) => d.count) : [0]);
+        p.sparkline({ values: series(t.views14d), label: "Views 14d", text: `${sum(t.views14d, "count")} / ${sum(t.views14d, "uniques")} unique`, color: theme.info, size: 1 });
+        p.sparkline({ values: series(t.clones14d), label: "Clones 14d", text: `${sum(t.clones14d, "count")} / ${sum(t.clones14d, "uniques")} unique`, color: theme.warning, size: 1 });
+        p.text(t.referrers.length ? `Referrers: ${t.referrers.slice(0, 4).map((r) => `${r.referrer} ${r.count}`).join(" · ")}` : "No referrers in the report.", { fg: theme.muted, size: 1 });
+        p.text(t.paths.length ? `Popular: ${t.paths.slice(0, 3).map((q) => `${q.path.replace(`/${t.repo}`, "") || "/"} ${q.count}`).join(" · ")}` : "No popular paths in the report.", { fg: theme.muted, size: 1 });
+        p.text(`${t.url}/graphs/traffic`, { fg: theme.muted, size: 1 });
+    });
+}
+export function pulseView({ ui, theme, width, height, elapsed }, state, root, actions = NO_ACTIONS) {
+    const pulse = state.data;
+    const label = RANGE_LABEL[state.range];
+    ui.row({ size: 1 }, (header) => {
+        header.text(" g1tz", { fg: theme.title, bold: true, size: 7 });
+        header.text("pulse", { fg: theme.accent, size: 7 });
+        header.text(pulse ? pulse.branch || "(detached)" : "", { fg: theme.accent, size: 24 });
+        header.text(label, { fg: theme.muted });
+        header.text(`${root}  d w m q y a range  p repo  ctrl+c quit `, { fg: theme.muted, align: "right" });
+    });
+    // One button per range, the current one lit, all clickable. `focused` is
+    // pinned off: the library would otherwise paint whichever button holds its
+    // focus index (the first) in the strong style, beside the real range.
+    ui.buttons(RANGE_KEYS.map((k) => ({
+        label: k,
+        variant: (state.range === k ? "primary" : "ghost"),
+        focused: false,
+        onPress: () => actions.pickRange(k),
+    })), { size: 1 });
+    ui.row({ size: height - 3, gap: 1 }, (row) => {
+        row.column({ width: "1fr", gap: 1 }, (left) => {
+            overviewPanel(left, theme, pulse);
+            activityPanel(left, theme, pulse, label, leftPaneColumns(width));
+            authorsPanel(left, theme, pulse, label);
+        });
+        row.column({ width: "1.2fr", gap: 1 }, (right) => {
+            filesPanel(right, theme, state, label, rightPaneColumns(width));
+            githubPanel(right, theme, state, label, elapsed);
+            trafficPanel(right, theme, state.traffic);
+        });
+    });
+    ui.statusBar({
+        items: [
+            { key: "d w m q y a", label, active: true },
+            { key: "↑↓", label: "Files" },
+            { key: "r", label: "Refresh", onPress: actions.refresh },
+            { key: "p", label: "Repo", onPress: actions.back },
+            { key: "ctrl+c", label: "Quit" },
+        ],
+        right: [{ label: state.note || githubLine(state, elapsed) }],
+    });
+}

package/dist/pulse.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Pulse: what moved in this repository over a period, read from git.
+ *
+ * The same idea as GitHub's Insights > Pulse tab, worked out locally so it is
+ * there offline and for repositories that are not on GitHub at all: commits
+ * and authors on the current branch and across every branch, the net change
+ * to the tree since the period began, the branches that saw commits and the
+ * tags that were created. GitHub's own side (pull requests, issues, stars and
+ * releases) is an optional, separate read in github.ts; views and clones come
+ * from a gh-pulse report when one exists (traffic.ts).
+ *
+ * Everything here is read-only, which is why the file list can afford
+ * display-grade path handling: a munged path on this screen cannot touch the
+ * working tree, unlike one in the Files pane.
+ */
+import { type GitError } from "./git.ts";
+export declare const RANGE_KEYS: readonly ["day", "week", "month", "quarter", "year", "all"];
+export type RangeKey = (typeof RANGE_KEYS)[number];
+export declare const RANGE_MS: Record<RangeKey, number>;
+export declare const RANGE_LABEL: Record<RangeKey, string>;
+export declare const RANGE_HOTKEY: Record<RangeKey, string>;
+export declare function parseRangeKey(text: string): RangeKey | null;
+export declare function rangeForHotkey(key: string): RangeKey | null;
+/** The start of a range, or null for all time. */
+export declare function sinceFor(range: RangeKey, now: Date): Date | null;
+export interface PulseCommit {
+    hash: string;
+    short: string;
+    author: string;
+    email: string;
+    /** Committer date, ISO 8601. --since selects on it, so a bucket never falls outside the range. */
+    at: string;
+    subject: string;
+    merge: boolean;
+}
+export interface PulseAuthor {
+    name: string;
+    commits: number;
+}
+export interface PulseFile {
+    path: string;
+    /** Original path for a rename. */
+    from?: string;
+    added: number;
+    deleted: number;
+    binary: boolean;
+}
+export interface PulseRef {
+    name: string;
+    at: string;
+}
+export type BucketUnit = "hour" | "day" | "week" | "month";
+export interface Bucket {
+    label: string;
+    /** ISO start of the bucket. */
+    start: string;
+    count: number;
+}
+export interface Pulse {
+    range: RangeKey;
+    /** ISO start of the period, or null for all time. */
+    since: string | null;
+    until: string;
+    branch: string;
+    /** Every commit reachable from HEAD in the period, merges included, newest first. */
+    commits: PulseCommit[];
+    commitsTruncated: boolean;
+    /** Commits on every local branch in the period, merges excluded. */
+    allBranchCommits: number;
+    /** Merges excluded, busiest first. */
+    authors: PulseAuthor[];
+    filesChanged: number;
+    additions: number;
+    deletions: number;
+    /** The net change per file since the period began, biggest first. */
+    files: PulseFile[];
+    unit: BucketUnit;
+    buckets: Bucket[];
+    /** Local branches that received a commit in the period. */
+    branches: PulseRef[];
+    /** Tags created in the period. */
+    tags: PulseRef[];
+    errors: GitError[];
+}
+/** `git log --format=<fields>%x00`: one NUL-terminated record per commit, fields separated by 0x1f. */
+export declare function parsePulseLog(out: string): PulseCommit[];
+/**
+ * `git diff --numstat -z`: `added TAB deleted TAB path NUL`. A rename is
+ * `added TAB deleted TAB NUL old NUL new NUL`, and a binary file has `-` for
+ * both counts. Paths are raw, so one with a newline in it still parses.
+ */
+export declare function parseNumstat(out: string): PulseFile[];
+/** `git diff --shortstat`: " 3 files changed, 12 insertions(+), 4 deletions(-)", any part of which may be missing. */
+export declare function parseShortstat(out: string): {
+    filesChanged: number;
+    additions: number;
+    deletions: number;
+};
+/** `git for-each-ref --format=%(refname:short)%1f%(<date>:iso-strict)`, one ref per line. */
+export declare function parseRefDates(out: string): PulseRef[];
+export declare function refsSince(refs: PulseRef[], since: Date | null): PulseRef[];
+/** Merges excluded, as GitHub counts them; busiest first, then by name. */
+export declare function countAuthors(commits: readonly PulseCommit[]): PulseAuthor[];
+export declare function unitFor(range: RangeKey): BucketUnit;
+/** More buckets than this and the range is not one anybody can read; the newest ones win. */
+export declare const BUCKET_CAP = 2000;
+/**
+ * Contiguous buckets from the start of the period (or the first commit, for
+ * all time) to now, with the commits counted into them. Every bucket is
+ * present even when empty, so a quiet week shows as a gap rather than
+ * vanishing.
+ */
+export declare function bucketCommits(commits: readonly PulseCommit[], since: Date | null, until: Date, unit: BucketUnit): Bucket[];
+/** At most `max` buckets, merging neighbours; a group takes the label of its first. */
+export declare function foldBuckets(buckets: readonly Bucket[], max: number): Bucket[];
+/** The hash of the empty tree, so the diff for all time (or from a root commit) has something to diff against. */
+export declare const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+export declare const COMMIT_CAP = 50000;
+export declare const FILE_CAP = 500;
+export declare function readPulse(root: string, range: RangeKey, now?: Date): Pulse;