@profullstack/g1tz 0.2.0

package/src/git.ts

@@ -0,0 +1,225 @@
+/**
+ * Everything g1tz knows about a repository, read by shelling out to git.
+ *
+ * Porcelain formats only, with explicit -z where a filename could contain a
+ * newline. Parsing `git status` output meant for humans is how a TUI ends up
+ * corrupting someone's working tree.
+ */
+import { spawnSync } from "node:child_process";
+
+export interface FileChange {
+  /** Index status, as git reports it: M, A, D, R, C, U or space. */
+  index: string;
+  /** Worktree status. */
+  work: string;
+  path: string;
+  /** Original path for a rename. */
+  from?: string;
+  staged: boolean;
+  unstaged: boolean;
+  untracked: boolean;
+  conflicted: boolean;
+}
+
+export interface Commit {
+  hash: string;
+  short: string;
+  subject: string;
+  author: string;
+  when: string;
+  refs: string;
+}
+
+export interface Branch {
+  name: string;
+  current: boolean;
+  upstream: string;
+  ahead: number;
+  behind: number;
+}
+
+export interface GitError {
+  command: string;
+  message: string;
+}
+
+export interface Repo {
+  root: string;
+  branch: string;
+  upstream: string;
+  ahead: number;
+  behind: number;
+  files: FileChange[];
+  commits: Commit[];
+  branches: Branch[];
+  errors: GitError[];
+}
+
+/** Run git and return stdout, or null when it fails. Never throws. */
+export function git(cwd: string, args: string[]): string | null {
+  const result = spawnSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    maxBuffer: 32 * 1024 * 1024,
+    // A pager or an editor would take the terminal away from the TUI.
+    env: { ...process.env, GIT_PAGER: "cat", GIT_EDITOR: "true", GIT_OPTIONAL_LOCKS: "0" },
+  });
+  if (result.error || result.status !== 0) return null;
+  return result.stdout;
+}
+
+export function repoRoot(cwd: string): string | null {
+  return git(cwd, ["rev-parse", "--show-toplevel"])?.trim() || null;
+}
+
+/**
+ * `git status --porcelain=v2 -z`. v2 rather than v1 because it reports the
+ * branch, the upstream and the ahead/behind counts in the same call, and -z
+ * because a path may contain anything but NUL.
+ */
+export function parseStatus(out: string): Pick<Repo, "branch" | "upstream" | "ahead" | "behind" | "files"> {
+  const result = { branch: "", upstream: "", ahead: 0, behind: 0, files: [] as FileChange[] };
+  const records = out.split("\0");
+  for (let i = 0; i < records.length; i++) {
+    const line = records[i] as string;
+    if (line === "") continue;
+    if (line.startsWith("# branch.head ")) {
+      result.branch = line.slice("# branch.head ".length);
+    } else if (line.startsWith("# branch.upstream ")) {
+      result.upstream = line.slice("# branch.upstream ".length);
+    } else if (line.startsWith("# branch.ab ")) {
+      const m = /\+(-?\d+) -(-?\d+)/.exec(line);
+      if (m) { result.ahead = Number(m[1]); result.behind = Number(m[2]); }
+    } else if (line.startsWith("1 ") || line.startsWith("2 ")) {
+      const rename = line.startsWith("2 ");
+      const parts = line.split(" ");
+      const xy = parts[1] ?? "..";
+      const index = xy[0] ?? ".";
+      const work = xy[1] ?? ".";
+      // Fields are fixed up to the path, which is the rest of the record.
+      const pathStart = rename ? 9 : 8;
+      const path = parts.slice(pathStart).join(" ");
+      // A rename's original path is the *next* NUL-separated record.
+      const from = rename ? (records[++i] as string | undefined) : undefined;
+      result.files.push({
+        index, work, path, from,
+        staged: index !== "." && index !== " ",
+        unstaged: work !== "." && work !== " ",
+        untracked: false,
+        conflicted: false,
+      });
+    } else if (line.startsWith("u ")) {
+      const parts = line.split(" ");
+      result.files.push({
+        index: "U", work: "U",
+        path: parts.slice(10).join(" "),
+        staged: false, unstaged: true, untracked: false, conflicted: true,
+      });
+    } else if (line.startsWith("? ")) {
+      result.files.push({
+        index: "?", work: "?", path: line.slice(2),
+        staged: false, unstaged: true, untracked: true, conflicted: false,
+      });
+    }
+  }
+  return result;
+}
+
+const LOG_FORMAT = "%H%x1f%h%x1f%s%x1f%an%x1f%ar%x1f%D";
+
+export function parseLog(out: string): Commit[] {
+  const commits: Commit[] = [];
+  for (const raw of out.split("\0")) {
+    // `--pretty=format:` puts a newline BETWEEN records, after the NUL, so
+    // every record but the first starts with one. Left in, it rode along on
+    // the hash and `git show` failed for every commit but the first.
+    const line = raw.replace(/^\n/, "");
+    if (line === "") continue;
+    const [hash, short, subject, author, when, refs] = line.split("\x1f");
+    if (!hash) continue;
+    commits.push({
+      hash, short: short ?? "", subject: subject ?? "",
+      author: author ?? "", when: when ?? "", refs: refs ?? "",
+    });
+  }
+  return commits;
+}
+
+const BRANCH_FORMAT = "%(HEAD)%1f%(refname:short)%1f%(upstream:short)%1f%(upstream:track)";
+
+export function parseBranches(out: string): Branch[] {
+  const branches: Branch[] = [];
+  for (const line of out.split("\n")) {
+    if (line.trim() === "") continue;
+    const [head, name, upstream, track] = line.split("\x1f");
+    if (!name) continue;
+    const ahead = /ahead (\d+)/.exec(track ?? "");
+    const behind = /behind (\d+)/.exec(track ?? "");
+    branches.push({
+      name,
+      current: head === "*",
+      upstream: upstream ?? "",
+      ahead: ahead ? Number(ahead[1]) : 0,
+      behind: behind ? Number(behind[1]) : 0,
+    });
+  }
+  return branches;
+}
+
+export function readRepo(cwd: string, logLimit = 200): Repo | null {
+  const root = repoRoot(cwd);
+  if (!root) return null;
+  const errors: GitError[] = [];
+  const run = (args: string[]): string => {
+    const out = git(root, args);
+    if (out === null) {
+      errors.push({ command: `git ${args[0]}`, message: "failed" });
+      return "";
+    }
+    return out;
+  };
+
+  // --untracked-files=all, because the default collapses a new directory to a
+  // single "? sub/" entry and you cannot stage or diff a directory here.
+  const status = parseStatus(
+    run(["status", "--porcelain=v2", "--branch", "--untracked-files=all", "-z"]),
+  );
+  // --no-show-signature: with log.showSignature set, git writes the
+  // verification text on stdout ahead of every record, glued to the hash.
+  const commits = parseLog(run(["log", "--no-show-signature", `--pretty=format:${LOG_FORMAT}%x00`, "-n", String(logLimit)]));
+  const branches = parseBranches(run(["for-each-ref", "--sort=-committerdate",
+    `--format=${BRANCH_FORMAT}`, "refs/heads"]));
+
+  return { root, ...status, commits, branches, errors };
+}
+
+/** The diff for one path, staged or not. Empty string when there is none. */
+export function fileDiff(root: string, file: FileChange, staged: boolean): string {
+  if (file.untracked) {
+    const out = git(root, ["diff", "--no-color", "--no-index", "/dev/null", file.path]);
+    // --no-index exits 1 when the files differ, which is always here.
+    return out ?? git(root, ["show", `:${file.path}`]) ?? "(untracked)";
+  }
+  const args = ["diff", "--no-color"];
+  if (staged) args.push("--cached");
+  args.push("--", file.path);
+  return git(root, args) ?? "";
+}
+
+/** Colour family for a diff line, as a theme key. */
+export function diffLineKind(line: string): "success" | "danger" | "accent" | "muted" | "foreground" {
+  if (line.startsWith("+++") || line.startsWith("---")) return "muted";
+  if (line.startsWith("@@")) return "accent";
+  if (line.startsWith("+")) return "success";
+  if (line.startsWith("-")) return "danger";
+  if (line.startsWith("diff ") || line.startsWith("index ")) return "muted";
+  return "foreground";
+}
+
+export function stage(root: string, file: FileChange): boolean {
+  return git(root, ["add", "--", file.path]) !== null;
+}
+
+export function unstage(root: string, file: FileChange): boolean {
+  return git(root, ["restore", "--staged", "--", file.path]) !== null;
+}

package/src/github.ts

@@ -0,0 +1,213 @@
+/**
+ * The GitHub half of Pulse: pull requests, issues, releases and stars over the
+ * period, read through the gh CLI. gh holds the login, so nothing here ever
+ * sees a token, and a machine without gh (or without a login) simply gets the
+ * git half on its own.
+ *
+ * Pages are walked newest-first and stop at the first item older than the
+ * period, under a small page budget, so a busy repository on "all time"
+ * cannot turn one keypress into a thousand requests. When the budget runs out
+ * the counts are floors and the result says so.
+ */
+import { execFile, spawnSync } from "node:child_process";
+import { git } from "./git.ts";
+
+export interface GitHubRepo {
+  owner: string;
+  name: string;
+}
+
+export interface GitHubItem {
+  number: number;
+  title: string;
+  user: string;
+  /** ISO date of the event this item is listed for: opened, merged or closed. */
+  at: string;
+}
+
+export interface GitHubRelease {
+  tag: string;
+  name: string;
+  at: string;
+}
+
+export interface GitHubPulse {
+  repo: string;
+  url: string;
+  description: string;
+  stars: number;
+  forks: number;
+  /** GitHub's open issue count, which includes open pull requests. */
+  openIssues: number;
+  prsOpened: GitHubItem[];
+  prsMerged: GitHubItem[];
+  /** Closed without merging. */
+  prsClosed: GitHubItem[];
+  issuesOpened: GitHubItem[];
+  issuesClosed: GitHubItem[];
+  releases: GitHubRelease[];
+  newStars: number;
+  /** A page budget ran out somewhere, so a count is a floor rather than a total. */
+  partial: boolean;
+}
+
+/**
+ * https, ssh and scp-style GitHub remotes, with or without .git, including
+ * GitHub's "SSH over the HTTPS port" form (ssh.github.com:443) and an explicit
+ * port. Anything else is null.
+ */
+export function parseGitHubRemote(url: string): GitHubRepo | null {
+  const m = /^(?:https?:\/\/(?:[^@/]+@)?|git@|ssh:\/\/(?:git@)?)(?:ssh\.)?github\.com(?::\d+)?[/:]([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/i.exec(url.trim());
+  return m ? { owner: m[1] as string, name: m[2] as string } : null;
+}
+
+export function githubRemote(root: string): GitHubRepo | null {
+  const url = git(root, ["remote", "get-url", "origin"]);
+  return url ? parseGitHubRemote(url) : null;
+}
+
+export const repoName = (repo: GitHubRepo): string => `${repo.owner}/${repo.name}`;
+
+/** One GitHub API call: a path relative to the API root, parsed JSON back. */
+export type Fetch = (path: string, headers?: Record<string, string>) => Promise<unknown>;
+
+let ghPresent: boolean | null = null;
+
+/** Whether gh is on the PATH. Asked once per process. */
+export function ghInstalled(): boolean {
+  if (ghPresent === null) ghPresent = spawnSync("gh", ["--version"], { encoding: "utf8" }).status === 0;
+  return ghPresent;
+}
+
+/** What to tell the user when gh could not answer. */
+export function ghErrorMessage(
+  error: { code?: string | number | null | undefined; signal?: string | null | undefined; killed?: boolean | undefined; message: string },
+  stderr: string,
+): string {
+  if (error.code === "ENOENT") return "gh is not installed";
+  // `killed` is execFile's own timeout; a signal is gh dying to something else. Neither leaves anything on stderr.
+  if (error.killed || error.signal) return "GitHub did not answer in time (gh was stopped after 60 seconds)";
+  const s = stderr.trim();
+  if (/gh auth login|not logged in|authentication required|HTTP 401/i.test(s)) return "gh is not logged in (run gh auth login)";
+  if (/rate limit/i.test(s)) return "GitHub API rate limit exceeded; try again later";
+  if (/HTTP 404/.test(s)) return "repository not found on GitHub, or the gh login cannot see it";
+  return s.split("\n")[0] || error.message;
+}
+
+export function ghFetch(path: string, headers: Record<string, string> = {}): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    const args = ["api", path];
+    for (const [k, v] of Object.entries(headers)) args.push("-H", `${k}: ${v}`);
+    execFile("gh", args, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024, timeout: 60_000 }, (error, stdout, stderr) => {
+      if (error) {
+        reject(new Error(ghErrorMessage(error, stderr)));
+        return;
+      }
+      try {
+        resolve(JSON.parse(stdout));
+      } catch {
+        reject(new Error("gh returned something that is not JSON"));
+      }
+    });
+  });
+}
+
+export interface PageBudget {
+  pulls: number;
+  issues: number;
+  releases: number;
+  stars: number;
+}
+
+export const PAGE_BUDGET: PageBudget = { pulls: 5, issues: 5, releases: 2, stars: 3 };
+
+interface UserJson { login?: string }
+interface PullJson { number: number; title: string; user?: UserJson; created_at: string; updated_at: string; closed_at: string | null; merged_at: string | null }
+interface IssueJson { number: number; title: string; user?: UserJson; created_at: string; updated_at: string; closed_at: string | null; pull_request?: unknown }
+interface ReleaseJson { tag_name: string; name: string | null; published_at: string | null; created_at: string; draft?: boolean }
+interface StarJson { starred_at: string }
+interface RepoJson { stargazers_count?: number; forks_count?: number; open_issues_count?: number; html_url?: string; description?: string | null }
+
+const STAR_HEADERS = { Accept: "application/vnd.github.star+json" };
+
+/** Walk numbered pages until `stop` says an item is older than needed, a short page ends the list, or the budget is spent. */
+async function walk<T>(fetch: Fetch, path: string, pages: number, stop: (item: T) => boolean): Promise<{ items: T[]; partial: boolean }> {
+  const items: T[] = [];
+  for (let page = 1; page <= pages; page++) {
+    const data = (await fetch(`${path}&page=${page}`)) as T[];
+    if (!Array.isArray(data) || data.length === 0) return { items, partial: false };
+    for (const item of data) {
+      if (stop(item)) return { items, partial: false };
+      items.push(item);
+    }
+    if (data.length < 100) return { items, partial: false };
+  }
+  return { items, partial: true };
+}
+
+/** GitHub lists stargazers oldest first, so the count of new ones starts at the last page and walks back. */
+async function countStars(fetch: Fetch, name: string, total: number, cutoff: number, pages: number): Promise<{ count: number; partial: boolean }> {
+  if (cutoff === 0 || total === 0) return { count: total, partial: false };
+  const lastPage = Math.max(1, Math.ceil(total / 100));
+  let count = 0;
+  for (let page = lastPage, used = 0; page >= 1; page--, used++) {
+    if (used >= pages) return { count, partial: true };
+    let data: StarJson[];
+    try {
+      data = (await fetch(`repos/${name}/stargazers?per_page=100&page=${page}`, STAR_HEADERS)) as StarJson[];
+    } catch {
+      // GitHub refuses the stargazers list of a very large repository (facebook/react
+      // answers 404 on every page), and a rate limit can land here after everything
+      // else answered. The star count is the only casualty, not the whole read.
+      return { count, partial: true };
+    }
+    if (!Array.isArray(data)) return { count, partial: false };
+    for (let i = data.length - 1; i >= 0; i--) {
+      if (Date.parse((data[i] as StarJson).starred_at) < cutoff) return { count, partial: false };
+      count++;
+    }
+  }
+  return { count, partial: false };
+}
+
+const item = (x: { number: number; title: string; user?: UserJson }, at: string): GitHubItem =>
+  ({ number: x.number, title: x.title, user: x.user?.login ?? "", at });
+const newest = (a: GitHubItem, b: GitHubItem): number => b.at.localeCompare(a.at);
+
+export async function readGitHubPulse(repo: GitHubRepo, since: Date | null, fetch: Fetch = ghFetch, budget: PageBudget = PAGE_BUDGET): Promise<GitHubPulse> {
+  const name = repoName(repo);
+  const cutoff = since ? since.getTime() : 0;
+  const inRange = (iso: string | null | undefined): boolean => iso !== null && iso !== undefined && Date.parse(iso) >= cutoff;
+  const stale = (iso: string | null | undefined): boolean => !inRange(iso);
+
+  const info = (await fetch(`repos/${name}`)) as RepoJson;
+  // Sorted by last update, newest first: the first one untouched in the period ends the walk.
+  const pulls = await walk<PullJson>(fetch, `repos/${name}/pulls?state=all&sort=updated&direction=desc&per_page=100`, budget.pulls, (p) => stale(p.updated_at));
+  const sinceParam = since ? `&since=${since.toISOString()}` : "";
+  const issues = await walk<IssueJson>(fetch, `repos/${name}/issues?state=all&sort=updated&direction=desc&per_page=100${sinceParam}`, budget.issues, (i) => stale(i.updated_at));
+  // Releases are listed by the tagged commit's date, not by when they were
+  // published, so a release cut this week for an older tag sits below older
+  // ones: no early stop, the budget's pages are read and published_at decides.
+  const releases = await walk<ReleaseJson>(fetch, `repos/${name}/releases?per_page=100`, budget.releases, () => false);
+  const stars = await countStars(fetch, name, info.stargazers_count ?? 0, cutoff, budget.stars);
+
+  return {
+    repo: name,
+    url: info.html_url ?? `https://github.com/${name}`,
+    description: info.description ?? "",
+    stars: info.stargazers_count ?? 0,
+    forks: info.forks_count ?? 0,
+    openIssues: info.open_issues_count ?? 0,
+    prsOpened: pulls.items.filter((p) => inRange(p.created_at)).map((p) => item(p, p.created_at)).sort(newest),
+    prsMerged: pulls.items.filter((p) => inRange(p.merged_at)).map((p) => item(p, p.merged_at as string)).sort(newest),
+    prsClosed: pulls.items.filter((p) => !p.merged_at && inRange(p.closed_at)).map((p) => item(p, p.closed_at as string)).sort(newest),
+    issuesOpened: issues.items.filter((i) => !i.pull_request && inRange(i.created_at)).map((i) => item(i, i.created_at)).sort(newest),
+    issuesClosed: issues.items.filter((i) => !i.pull_request && inRange(i.closed_at)).map((i) => item(i, i.closed_at as string)).sort(newest),
+    releases: releases.items
+      .filter((r) => !r.draft && inRange(r.published_at))
+      .map((r) => ({ tag: r.tag_name, name: r.name ?? r.tag_name, at: r.published_at as string }))
+      .sort((a, b) => b.at.localeCompare(a.at)),
+    newStars: stars.count,
+    partial: pulls.partial || issues.partial || releases.partial || stars.partial,
+  };
+}