@profullstack/g1tz 0.2.0

package/dist/pulse.js

@@ -0,0 +1,348 @@
+/**
+ * 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 { git } from "./git.js";
+export const RANGE_KEYS = ["day", "week", "month", "quarter", "year", "all"];
+const DAY_MS = 86_400_000;
+export const RANGE_MS = {
+    day: DAY_MS,
+    week: 7 * DAY_MS,
+    month: 30 * DAY_MS,
+    quarter: 91 * DAY_MS,
+    year: 365 * DAY_MS,
+    all: Number.POSITIVE_INFINITY,
+};
+export const RANGE_LABEL = {
+    day: "last 24 hours",
+    week: "last week",
+    month: "last month",
+    quarter: "last quarter",
+    year: "last year",
+    all: "all time",
+};
+export const RANGE_HOTKEY = { day: "d", week: "w", month: "m", quarter: "q", year: "y", all: "a" };
+const RANGE_ALIASES = {
+    "24h": "day", "1d": "day", today: "day",
+    "7d": "week", "1w": "week",
+    "30d": "month", "1m": "month",
+    "90d": "quarter", "3m": "quarter",
+    "365d": "year", "1y": "year", "12m": "year",
+    ever: "all", forever: "all",
+};
+export function parseRangeKey(text) {
+    const key = text.trim().toLowerCase();
+    if (RANGE_KEYS.includes(key))
+        return key;
+    return RANGE_ALIASES[key] ?? null;
+}
+export function rangeForHotkey(key) {
+    return RANGE_KEYS.find((k) => RANGE_HOTKEY[k] === key) ?? null;
+}
+/** The start of a range, or null for all time. */
+export function sinceFor(range, now) {
+    return range === "all" ? null : new Date(now.getTime() - RANGE_MS[range]);
+}
+// ---------------------------------------------------------------- parsers
+const LOG_FORMAT = "%H%x1f%h%x1f%an%x1f%ae%x1f%cI%x1f%P%x1f%s";
+/** `git log --format=<fields>%x00`: one NUL-terminated record per commit, fields separated by 0x1f. */
+export function parsePulseLog(out) {
+    const commits = [];
+    for (const raw of out.split("\0")) {
+        // A newline between records is separator noise, not part of the hash.
+        const record = raw.replace(/^\n/, "");
+        if (record === "")
+            continue;
+        const [hash, short, author, email, at, parents, subject] = record.split("\x1f");
+        if (!hash)
+            continue;
+        commits.push({
+            hash,
+            short: short ?? "",
+            author: author ?? "",
+            email: email ?? "",
+            at: at ?? "",
+            subject: subject ?? "",
+            merge: (parents ?? "").split(" ").filter(Boolean).length > 1,
+        });
+    }
+    return commits;
+}
+/**
+ * `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 function parseNumstat(out) {
+    const files = [];
+    const tokens = out.split("\0");
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token === "")
+            continue;
+        const m = /^(\d+|-)\t(\d+|-)\t([^]*)$/.exec(token);
+        if (!m)
+            continue;
+        const binary = m[1] === "-";
+        const added = binary ? 0 : Number(m[1]);
+        const deleted = binary ? 0 : Number(m[2]);
+        if (m[3] === "") {
+            // A rename: the two paths follow as their own records.
+            const from = tokens[++i] ?? "";
+            const path = tokens[++i] ?? "";
+            files.push({ path, from, added, deleted, binary });
+        }
+        else {
+            files.push({ path: m[3], added, deleted, binary });
+        }
+    }
+    return files;
+}
+/** `git diff --shortstat`: " 3 files changed, 12 insertions(+), 4 deletions(-)", any part of which may be missing. */
+export function parseShortstat(out) {
+    const files = /(\d+) files? changed/.exec(out);
+    const ins = /(\d+) insertions?\(\+\)/.exec(out);
+    const del = /(\d+) deletions?\(-\)/.exec(out);
+    return {
+        filesChanged: files ? Number(files[1]) : 0,
+        additions: ins ? Number(ins[1]) : 0,
+        deletions: del ? Number(del[1]) : 0,
+    };
+}
+/** `git for-each-ref --format=%(refname:short)%1f%(<date>:iso-strict)`, one ref per line. */
+export function parseRefDates(out) {
+    const refs = [];
+    for (const line of out.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        const [name, at] = line.split("\x1f");
+        if (name)
+            refs.push({ name, at: at ?? "" });
+    }
+    return refs;
+}
+export function refsSince(refs, since) {
+    if (!since)
+        return refs;
+    return refs.filter((r) => Date.parse(r.at) >= since.getTime());
+}
+/** Merges excluded, as GitHub counts them; busiest first, then by name. */
+export function countAuthors(commits) {
+    const counts = new Map();
+    for (const c of commits) {
+        if (c.merge)
+            continue;
+        counts.set(c.author, (counts.get(c.author) ?? 0) + 1);
+    }
+    return [...counts]
+        .map(([name, n]) => ({ name, commits: n }))
+        .sort((a, b) => b.commits - a.commits || a.name.localeCompare(b.name));
+}
+// ---------------------------------------------------------------- buckets
+export function unitFor(range) {
+    switch (range) {
+        case "day": return "hour";
+        case "week":
+        case "month": return "day";
+        case "quarter":
+        case "year": return "week";
+        default: return "month";
+    }
+}
+/** The start of the bucket holding `time`, in UTC. Weeks start on Monday. */
+function floorTo(time, unit) {
+    const t = new Date(time);
+    t.setUTCMinutes(0, 0, 0);
+    if (unit === "hour")
+        return t;
+    t.setUTCHours(0);
+    if (unit === "day")
+        return t;
+    if (unit === "week") {
+        t.setUTCDate(t.getUTCDate() - ((t.getUTCDay() + 6) % 7));
+        return t;
+    }
+    t.setUTCDate(1);
+    return t;
+}
+function next(t, unit) {
+    const n = new Date(t.getTime());
+    if (unit === "hour")
+        n.setUTCHours(n.getUTCHours() + 1);
+    else if (unit === "day")
+        n.setUTCDate(n.getUTCDate() + 1);
+    else if (unit === "week")
+        n.setUTCDate(n.getUTCDate() + 7);
+    else
+        n.setUTCMonth(n.getUTCMonth() + 1);
+    return n;
+}
+function labelFor(t, unit) {
+    const iso = t.toISOString();
+    if (unit === "hour")
+        return `${iso.slice(11, 13)}:00`;
+    if (unit === "month")
+        return iso.slice(0, 7);
+    return iso.slice(5, 10);
+}
+/** More buckets than this and the range is not one anybody can read; the newest ones win. */
+export 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 function bucketCommits(commits, since, until, unit) {
+    const times = [];
+    let earliest = Number.POSITIVE_INFINITY;
+    for (const c of commits) {
+        const t = Date.parse(c.at);
+        if (!Number.isFinite(t))
+            continue;
+        times.push(t);
+        if (t < earliest)
+            earliest = t;
+    }
+    const from = since ? since.getTime() : times.length ? earliest : until.getTime();
+    const buckets = [];
+    const starts = [];
+    for (let t = floorTo(from, unit); t.getTime() <= until.getTime() && buckets.length < BUCKET_CAP; t = next(t, unit)) {
+        buckets.push({ label: labelFor(t, unit), start: t.toISOString(), count: 0 });
+        starts.push(t.getTime());
+    }
+    for (const time of times) {
+        // The last bucket starting at or before this commit; a commit from the
+        // future (a wrong clock) lands in the newest one.
+        let lo = 0;
+        let hi = starts.length - 1;
+        let idx = -1;
+        while (lo <= hi) {
+            const mid = (lo + hi) >> 1;
+            if (starts[mid] <= time) {
+                idx = mid;
+                lo = mid + 1;
+            }
+            else
+                hi = mid - 1;
+        }
+        if (idx >= 0)
+            buckets[idx].count += 1;
+    }
+    return buckets;
+}
+/** At most `max` buckets, merging neighbours; a group takes the label of its first. */
+export function foldBuckets(buckets, max) {
+    if (max < 1 || buckets.length <= max)
+        return [...buckets];
+    const per = Math.ceil(buckets.length / max);
+    const out = [];
+    for (let i = 0; i < buckets.length; i += per) {
+        const group = buckets.slice(i, i + per);
+        const first = group[0];
+        out.push({ label: first.label, start: first.start, count: group.reduce((t, b) => t + b.count, 0) });
+    }
+    return out;
+}
+// ---------------------------------------------------------------- reading
+/** The hash of the empty tree, so the diff for all time (or from a root commit) has something to diff against. */
+export const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+export const COMMIT_CAP = 50_000;
+export const FILE_CAP = 500;
+const churn = (f) => f.added + f.deleted;
+export function readPulse(root, range, now = new Date()) {
+    const since = sinceFor(range, now);
+    const sinceArgs = since ? [`--since=${since.toISOString()}`] : [];
+    const errors = [];
+    const run = (args) => {
+        const out = git(root, args);
+        if (out === null) {
+            errors.push({ command: `git ${args[0]}`, message: "failed" });
+            return "";
+        }
+        return out;
+    };
+    const branch = git(root, ["symbolic-ref", "--quiet", "--short", "HEAD"])?.trim() ?? "";
+    // An unborn HEAD (a repository with no commits yet) fails every read below;
+    // the pulse is then simply empty rather than a list of errors.
+    const hasHead = git(root, ["rev-parse", "--verify", "--quiet", "HEAD"]) !== null;
+    // "--" after HEAD everywhere: a file named HEAD in the root would otherwise
+    // make the revision ambiguous. --no-show-signature: with log.showSignature
+    // set, git writes the verification text on stdout ahead of every record.
+    const commits = hasHead
+        ? parsePulseLog(run(["log", "--no-show-signature", `--format=${LOG_FORMAT}%x00`, `--max-count=${COMMIT_CAP}`, ...sinceArgs, "HEAD", "--"]))
+        : [];
+    // Not gated on HEAD: an orphan branch being born has no HEAD commit while the other branches still moved.
+    const allBranchCommits = Number(run(["rev-list", "--branches", "--no-merges", "--count", ...sinceArgs]).trim()) || 0;
+    // The tree at the start of the period is the first parent of the oldest
+    // first-parent commit in range: what the branch pointed at before any of
+    // this landed, whether it arrived by merge, rebase or fast-forward. All
+    // time, and a root commit inside the period, diff from the empty tree. A
+    // shallow clone's grafted commit has no parent either, but that is not a
+    // root: the tree before the period is simply not in this clone.
+    let boundary = null;
+    if (hasHead) {
+        if (!since)
+            boundary = EMPTY_TREE;
+        else {
+            const oldest = run(["rev-list", "--first-parent", ...sinceArgs, "HEAD", "--"]).trim().split("\n").filter(Boolean).at(-1);
+            if (oldest) {
+                const parent = git(root, ["rev-parse", "--verify", "--quiet", `${oldest}^`])?.trim();
+                if (parent)
+                    boundary = parent;
+                else if (git(root, ["rev-parse", "--is-shallow-repository"])?.trim() === "true") {
+                    errors.push({ command: "git diff", message: "shallow clone: the tree before the period is not available" });
+                }
+                else
+                    boundary = EMPTY_TREE;
+            }
+        }
+    }
+    let filesChanged = 0;
+    let additions = 0;
+    let deletions = 0;
+    let files = [];
+    if (boundary) {
+        ({ filesChanged, additions, deletions } = parseShortstat(run(["diff", "--shortstat", "-M", boundary, "HEAD", "--"])));
+        files = parseNumstat(run(["diff", "--numstat", "-z", "-M", boundary, "HEAD", "--"]))
+            .sort((a, b) => churn(b) - churn(a) || a.path.localeCompare(b.path))
+            .slice(0, FILE_CAP);
+    }
+    const branches = refsSince(parseRefDates(run([
+        "for-each-ref", "--sort=-committerdate", "--format=%(refname:short)%1f%(committerdate:iso-strict)", "refs/heads",
+    ])), since);
+    const tags = refsSince(parseRefDates(run([
+        "for-each-ref", "--sort=-creatordate", "--format=%(refname:short)%1f%(creatordate:iso-strict)", "refs/tags",
+    ])), since);
+    const unit = unitFor(range);
+    return {
+        range,
+        since: since ? since.toISOString() : null,
+        until: now.toISOString(),
+        branch,
+        commits,
+        commitsTruncated: commits.length >= COMMIT_CAP,
+        allBranchCommits,
+        authors: countAuthors(commits),
+        filesChanged,
+        additions,
+        deletions,
+        files,
+        unit,
+        buckets: bucketCommits(commits, since, now, unit),
+        branches,
+        tags,
+        errors,
+    };
+}

package/dist/traffic.d.ts

@@ -0,0 +1,37 @@
+export interface TrafficDay {
+    day: string;
+    count: number;
+    uniques: number;
+}
+export interface TrafficReferrer {
+    referrer: string;
+    count: number;
+    uniques: number;
+}
+export interface TrafficPath {
+    path: string;
+    count: number;
+    uniques: number;
+}
+export interface Traffic {
+    repo: string;
+    url: string;
+    /** When the report was written. */
+    reportAt: string;
+    stars: number;
+    forks: number;
+    views14d: TrafficDay[];
+    clones14d: TrafficDay[];
+    referrers: TrafficReferrer[];
+    paths: TrafficPath[];
+}
+export declare function ghPulseDataDir(env?: NodeJS.ProcessEnv): string;
+export declare function ghPulseReportPath(dir?: string): string;
+/**
+ * The repository's row out of a gh-pulse report. The report only carries the
+ * repositories that moved, so a quiet one is null even when the report is
+ * fresh, and every field is read defensively: the report is another tool's
+ * output, not this one's.
+ */
+export declare function trafficFromReport(report: unknown, repo: string): Traffic | null;
+export declare function readTraffic(repo: string, dir?: string): Traffic | null;

package/dist/traffic.js

@@ -0,0 +1,68 @@
+/**
+ * Traffic for this repository, from a gh-pulse report.
+ *
+ * GitHub only serves a repository's views and clones through its traffic API,
+ * and only the last fourteen days of them. gh-pulse (profullstack/cli-tools)
+ * reads that every day for every repository the login can see and writes a
+ * report under ~/.local/share/gh-pulse; when one is there, the Pulse screen
+ * draws this repository's series from it. Nothing is fetched here: it is a
+ * file read, and a missing file is not an error.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function ghPulseDataDir(env = process.env) {
+    return env["GH_PULSE_DATA"] ?? join(homedir(), ".local", "share", "gh-pulse");
+}
+export function ghPulseReportPath(dir = ghPulseDataDir()) {
+    return join(dir, "out", "latest.json");
+}
+const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+const str = (v) => (typeof v === "string" ? v : "");
+const isRecord = (v) => !!v && typeof v === "object";
+function days(v) {
+    if (!Array.isArray(v))
+        return [];
+    return v.filter(isRecord).map((d) => ({ day: str(d["day"]), count: num(d["count"]), uniques: num(d["uniques"]) }));
+}
+/**
+ * The repository's row out of a gh-pulse report. The report only carries the
+ * repositories that moved, so a quiet one is null even when the report is
+ * fresh, and every field is read defensively: the report is another tool's
+ * output, not this one's.
+ */
+export function trafficFromReport(report, repo) {
+    if (!isRecord(report) || !Array.isArray(report["movers"]))
+        return null;
+    const want = repo.toLowerCase();
+    const mover = report["movers"].find((m) => isRecord(m) && str(m["repo"]).toLowerCase() === want);
+    if (!isRecord(mover))
+        return null;
+    const name = str(mover["repo"]);
+    return {
+        repo: name,
+        url: str(mover["url"]) || `https://github.com/${name}`,
+        reportAt: str(report["at"]),
+        stars: num(mover["stars"]),
+        forks: num(mover["forks"]),
+        views14d: days(mover["views14d"]),
+        clones14d: days(mover["clones14d"]),
+        referrers: Array.isArray(mover["referrers"])
+            ? mover["referrers"].filter(isRecord).map((r) => ({ referrer: str(r["referrer"]), count: num(r["count"]), uniques: num(r["uniques"]) }))
+            : [],
+        paths: Array.isArray(mover["paths"])
+            ? mover["paths"].filter(isRecord).map((p) => ({ path: str(p["path"]), count: num(p["count"]), uniques: num(p["uniques"]) }))
+            : [],
+    };
+}
+export function readTraffic(repo, dir = ghPulseDataDir()) {
+    const file = ghPulseReportPath(dir);
+    if (!existsSync(file))
+        return null;
+    try {
+        return trafficFromReport(JSON.parse(readFileSync(file, "utf8")), repo);
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@profullstack/g1tz",
+  "version": "0.2.0",
+  "description": "A git TUI that shows you the repository, not a menu of git commands.",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://github.com/profullstack/g1tz",
+  "bin": {
+    "g1tz": "./bin/g1tz.mjs"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.1",
+    "node": ">=22.6"
+  },
+  "scripts": {
+    "start": "bun src/main.ts",
+    "build": "bun x tsc -p tsconfig.json",
+    "typecheck": "bun x tsc -p tsconfig.json --noEmit",
+    "test": "bun test test",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@profullstack/hqtui": "^0.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26",
+    "typescript": "^7.0.2"
+  },
+  "keywords": [
+    "git",
+    "tui",
+    "terminal",
+    "lazygit",
+    "hqtui",
+    "pulse",
+    "github",
+    "activity"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/profullstack/g1tz.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/diff.ts

@@ -0,0 +1,147 @@
+/**
+ * Diff rendering, as spans.
+ *
+ * A whole line coloured green tells you it changed. Colouring only the words
+ * that actually differ tells you *what* changed, which is the thing you were
+ * squinting at the line to work out.
+ */
+import type { SpanLine } from "@profullstack/hqtui";
+import { diffLineKind } from "./git.ts";
+
+export interface DiffPalette {
+  add: number;
+  remove: number;
+  hunk: number;
+  meta: number;
+  context: number;
+  /** Background emphasis for the words that actually differ. */
+  addEmphasis: number;
+  removeEmphasis: number;
+}
+
+/** Split into words and the separators between them, both kept. */
+export function words(line: string): string[] {
+  return line.split(/(\W)/).filter((part) => part !== "");
+}
+
+export interface Segment {
+  text: string;
+  changed: boolean;
+}
+
+/**
+ * The differing middle of two lines, found by trimming the common prefix and
+ * suffix. Not a full Myers diff: for the single-line case a prefix/suffix trim
+ * is what people actually read, and it cannot produce the confetti that a
+ * token-level LCS gives you on a reformatted line.
+ */
+export function intraLine(before: string, after: string): { before: Segment[]; after: Segment[] } {
+  const a = words(before);
+  const b = words(after);
+
+  let head = 0;
+  while (head < a.length && head < b.length && a[head] === b[head]) head++;
+
+  let tail = 0;
+  while (
+    tail < a.length - head &&
+    tail < b.length - head &&
+    a[a.length - 1 - tail] === b[b.length - 1 - tail]
+  ) tail++;
+
+  const build = (parts: string[]): Segment[] => {
+    const middle = parts.slice(head, parts.length - tail).join("");
+    const out: Segment[] = [];
+    const prefix = parts.slice(0, head).join("");
+    const suffix = parts.slice(parts.length - tail).join("");
+    if (prefix) out.push({ text: prefix, changed: false });
+    if (middle) out.push({ text: middle, changed: true });
+    if (suffix) out.push({ text: suffix, changed: false });
+    return out;
+  };
+
+  return { before: build(a), after: build(b) };
+}
+
+/**
+ * Pair each removed line with the added line that replaced it.
+ *
+ * Only runs of equal length are paired. An unequal run is a genuine insertion
+ * or deletion rather than an edit, and pretending otherwise produces word
+ * highlighting that points at the wrong thing.
+ */
+export function pairRuns(lines: string[]): Map<number, number> {
+  const pairs = new Map<number, number>();
+  let i = 0;
+  while (i < lines.length) {
+    if (!isRemoval(lines[i] as string)) { i++; continue; }
+    let removals = 0;
+    while (i + removals < lines.length && isRemoval(lines[i + removals] as string)) removals++;
+    let additions = 0;
+    while (
+      i + removals + additions < lines.length &&
+      isAddition(lines[i + removals + additions] as string)
+    ) additions++;
+    if (removals === additions && removals > 0) {
+      for (let k = 0; k < removals; k++) pairs.set(i + k, i + removals + k);
+    }
+    i += removals + additions;
+  }
+  return pairs;
+}
+
+function isRemoval(line: string): boolean {
+  return line.startsWith("-") && !line.startsWith("---");
+}
+
+function isAddition(line: string): boolean {
+  return line.startsWith("+") && !line.startsWith("+++");
+}
+
+/** A whole diff as span lines, with the changed words emphasised. */
+export function highlightDiff(lines: string[], palette: DiffPalette): SpanLine[] {
+  const pairs = pairRuns(lines);
+  const partnerOf = new Map<number, number>();
+  for (const [from, to] of pairs) partnerOf.set(to, from);
+
+  const colorFor = (line: string): number => {
+    switch (diffLineKind(line)) {
+      case "success": return palette.add;
+      case "danger": return palette.remove;
+      case "accent": return palette.hunk;
+      case "muted": return palette.meta;
+      default: return palette.context;
+    }
+  };
+
+  return lines.map((line, index) => {
+    const base = colorFor(line);
+
+    const partner = pairs.has(index)
+      ? (lines[pairs.get(index) as number] as string)
+      : partnerOf.has(index)
+        ? (lines[partnerOf.get(index) as number] as string)
+        : undefined;
+
+    if (partner === undefined) {
+      return line === "" ? [] : [{ text: line, fg: base }];
+    }
+
+    const removed = isRemoval(line);
+    const { before, after } = intraLine(
+      (removed ? line : partner).slice(1),
+      (removed ? partner : line).slice(1),
+    );
+    const segments = removed ? before : after;
+    const emphasis = removed ? palette.removeEmphasis : palette.addEmphasis;
+
+    return [
+      { text: line.slice(0, 1), fg: base },
+      ...segments.map((segment) => ({
+        text: segment.text,
+        fg: base,
+        ...(segment.changed ? { bg: emphasis, bold: true } : {}),
+      })),
+    ];
+  });
+}