github-search-cli 9.7.1 → 9.8.1

package/src/image-loader.ts

@@ -0,0 +1,277 @@
+/**
+ * README image loading — URL resolution, filtering and a small fetch cache.
+ *
+ * READMEs reference images in a half-dozen shapes: relative paths, absolute
+ * paths from a branch root, `github.com/.../blob/...` pages, media hosts and
+ * inline `data:` URIs. Only some of them are worth downloading, and all of
+ * the downloads are cached because a README is re-opened often.
+ */
+
+/** Reject anything bigger than this before buffering it. */
+export const MAX_IMAGE_BYTES = 6 * 1024 * 1024;
+
+/**
+ * Hosts that serve badges rather than pictures. They're tiny SVGs with text
+ * baked in — unreadable once rasterised, so they're skipped.
+ */
+const BADGE_HOST =
+  /(^|\.)(shields\.io|badgen\.net|badge\.fury\.io|codecov\.io|coveralls\.io|travis-ci\.(org|com)|snyk\.io|sonarcloud\.io|david-dm\.(org|io))$/i;
+
+/** Hosts whose repo-relative image paths we are allowed to fetch. */
+const RAW_HOSTS = new Set([
+  "raw.githubusercontent.com",
+  "camo.githubusercontent.com",
+  "user-images.githubusercontent.com",
+  "private-user-images.githubusercontent.com",
+  "avatars.githubusercontent.com",
+  "objects.githubusercontent.com",
+]);
+
+/** Formats the rasteriser cannot show — SVG is text, so it's skipped. */
+const RASTER_EXT = /\.(png|jpe?g|webp|gif|bmp|avif|heic|tiff?)(?:[?#]|$)/i;
+
+/** Cap on memoised downloads — a long session can open many READMEs. */
+const CACHE_LIMIT = 24;
+
+/**
+ * How many image downloads may be in flight at once. A README can reference
+ * dozens of images; firing them all at the same time makes them compete for
+ * bandwidth so the first one lands later, not sooner.
+ */
+export const MAX_CONCURRENT_IMAGE_FETCHES = 4;
+
+const cache = new Map<string, Promise<Uint8Array | null>>();
+
+let activeFetches = 0;
+const waiting: Array<() => void> = [];
+
+/** Hand the next queued caller its turn, if the cap allows it. */
+function releaseSlot(): void {
+  activeFetches--;
+  waiting.shift()?.();
+}
+
+/** Run `job` as soon as fewer than the cap are already running. */
+async function withSlot<T>(job: () => Promise<T>): Promise<T> {
+  if (activeFetches >= MAX_CONCURRENT_IMAGE_FETCHES) {
+    await new Promise<void>((resolve) => waiting.push(resolve));
+  }
+  activeFetches++;
+  try {
+    return await job();
+  } finally {
+    releaseSlot();
+  }
+}
+
+/** Drop memoised image downloads (used by tests). */
+export function clearImageByteCache(): void {
+  cache.clear();
+}
+
+/** Decode a `data:image/...;base64,...` URI into raw bytes. */
+function decodeDataUri(uri: string): Uint8Array | null {
+  const match = /^data:([^;,]+)?(;base64)?,(.*)$/is.exec(uri);
+  if (!match) return null;
+  const mime = (match[1] ?? "").toLowerCase();
+  if (mime.includes("svg")) return null;
+  const payload = match[3];
+  try {
+    if (match[2]) return new Uint8Array(Buffer.from(payload, "base64"));
+    return new Uint8Array(Buffer.from(decodeURIComponent(payload), "binary"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Rewrite GitHub web URLs (`.../blob/<ref>/<path>`, `.../raw/<ref>/<path>`)
+ * to their raw equivalents so they can be fetched as bytes.
+ */
+function toRawGitHubUrl(url: URL): URL {
+  if (url.hostname.toLowerCase() !== "github.com") return url;
+  const match = /^\/([^/]+)\/([^/]+)\/(?:blob|raw)\/(.+)$/.exec(url.pathname);
+  if (!match) return url;
+  const [, owner, repo, rest] = match;
+  return new URL(
+    `https://raw.githubusercontent.com/${owner}/${repo}/${rest}${url.search}`,
+  );
+}
+
+/**
+ * GitHub resolves `/foo.png` against the *repository* root, not the host
+ * root, so rebuild it on the base's `owner/repo/branch` prefix instead of
+ * letting `new URL()` swap the whole path out.
+ */
+function resolveRootRelative(path: string, base: string): URL | null {
+  let parsed: URL;
+  try {
+    parsed = new URL(base);
+  } catch {
+    return null;
+  }
+  if (parsed.hostname.toLowerCase() !== "raw.githubusercontent.com") {
+    return null;
+  }
+  const segments = parsed.pathname.split("/").filter(Boolean);
+  if (segments.length < 3) return null;
+  return new URL(`${parsed.origin}/${segments.slice(0, 3).join("/")}${path}`);
+}
+
+/**
+ * Resolve an image reference from a README into a fetchable URL, or `null`
+ * when it isn't something we can render (SVG, badges, mailto, …).
+ *
+ * `base` is the URL of the README itself, so relative paths resolve against
+ * the branch the README came from.
+ */
+export function resolveReadmeImageUrl(
+  raw: string,
+  base: string,
+): string | null {
+  const cleaned = raw.trim();
+  if (!cleaned) return null;
+
+  if (/^data:/i.test(cleaned)) {
+    return isRenderableImageUrl(cleaned) ? cleaned : null;
+  }
+
+  let url: URL | null = null;
+  try {
+    url = cleaned.startsWith("/")
+      ? resolveRootRelative(cleaned, base)
+      : new URL(cleaned, base);
+  } catch {
+    return null;
+  }
+  if (!url) return null;
+  url = toRawGitHubUrl(url);
+  if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+
+  url.hash = "";
+  const resolved = url.toString();
+  return isRenderableImageUrl(resolved) ? resolved : null;
+}
+
+/**
+ * Whether a URL is likely to be a picture we can rasterise. Skipped:
+ * SVG (vector text), badge services, and GitHub-hosted HTML pages.
+ */
+export function isRenderableImageUrl(url: string): boolean {
+  if (/^data:/i.test(url)) return !/svg/i.test(url.slice(0, 64));
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return false;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return false;
+  if (BADGE_HOST.test(parsed.hostname)) return false;
+
+  const path = parsed.pathname.toLowerCase();
+  if (path.endsWith(".svg") || path.endsWith(".svgz")) return false;
+  // GitHub's drag-and-drop uploads live under /user-attachments/ with opaque
+  // UUID paths and no file extension — the fetch decides what they are.
+  if (parsed.hostname.toLowerCase().endsWith("github.com")) {
+    if (/^\/user-attachments\//.test(path)) return true;
+    if (!RAW_HOSTS.has(parsed.hostname)) {
+      return /\.(png|jpe?g|webp|gif|bmp|avif|heic|tiff?)$/i.test(path);
+    }
+  }
+  // Unknown extension on a host we don't know: the fetch decides.
+  if (/\.[a-z0-9]{1,5}$/.test(path) && !RASTER_EXT.test(path)) return false;
+  return true;
+}
+
+/** Hosts that accept the caller's GitHub token. */
+function isGitHubHost(hostname: string): boolean {
+  return /(^|\.)githubusercontent\.com$|(^|\.)github\.com$/i.test(hostname);
+}
+
+/**
+ * Download image bytes, memoised per URL. Returns `null` for anything that
+ * fails, is too large, or turns out not to be an image.
+ */
+export async function fetchImageBytes(
+  url: string,
+  opts: { token?: string; fetchImpl?: typeof fetch; timeoutMs?: number } = {},
+): Promise<Uint8Array | null> {
+  const cached = cache.get(url);
+  if (cached) return cached;
+  const pending = withSlot(() => loadImageBytes(url, opts));
+  cache.set(url, pending);
+  // Map iteration order is insertion order, so the first key is the oldest.
+  while (cache.size > CACHE_LIMIT) {
+    const oldest = cache.keys().next().value;
+    if (oldest === undefined) break;
+    cache.delete(oldest);
+  }
+  return pending;
+}
+
+async function loadImageBytes(
+  url: string,
+  opts: { token?: string; fetchImpl?: typeof fetch; timeoutMs?: number },
+): Promise<Uint8Array | null> {
+  if (/^data:/i.test(url)) return decodeDataUri(url);
+
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const timeoutMs = opts.timeoutMs ?? 10_000;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const headers: Record<string, string> = {
+      "User-Agent": "ghfind/1.0",
+      Accept: "image/*,*/*;q=0.5",
+    };
+    let host = "";
+    try {
+      host = new URL(url).hostname;
+    } catch {
+      return null;
+    }
+    if (opts.token && isGitHubHost(host)) {
+      headers.Authorization = `Bearer ${opts.token}`;
+    }
+
+    const res = await fetchImpl(url, { headers, signal: controller.signal });
+    if (!res.ok) return null;
+
+    const contentType = res.headers.get("content-type") ?? "";
+    if (contentType && !/^image\//i.test(contentType)) {
+      // GitHub's attachment endpoints (user-uploads proxied via camo) serve
+      // real images as binary/octet-stream; the rasteriser rejects anything
+      // that isn't actually an image, so accept it there and let decoding
+      // decide.
+      const githubHost = isGitHubHost(host);
+      if (!githubHost || !/octet-stream/i.test(contentType)) return null;
+    }
+    if (/svg/i.test(contentType)) return null;
+
+    const declared = Number(res.headers.get("content-length") ?? "0");
+    if (declared > MAX_IMAGE_BYTES) return null;
+
+    const buffer = new Uint8Array(await res.arrayBuffer());
+    if (buffer.byteLength === 0 || buffer.byteLength > MAX_IMAGE_BYTES) {
+      return null;
+    }
+    return buffer;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Absolute URL of the README file itself, used as the base for relative
+ * image paths.
+ */
+export function readmeBaseUrl(
+  owner: string,
+  repo: string,
+  branch: string,
+  path = "README.md",
+): string {
+  return `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${path}`;
+}

package/src/image-render.ts

@@ -0,0 +1,209 @@
+/**
+ * Terminal image rendering — turns image bytes into half-block cells.
+ *
+ * A terminal cell is roughly twice as tall as it is wide, so one cell is
+ * drawn with `▀`: the foreground colour paints the top half and the
+ * background colour the bottom half. That gives two image pixels of
+ * vertical resolution per character row with no image protocol support
+ * needed — it works on any truecolor terminal, inside OpenTUI's own
+ * cell buffer.
+ */
+import { decodePng, type DecodedImage } from "./png";
+
+export type Rgb = readonly [number, number, number];
+
+export interface HalfBlockCell {
+  /** Colour of the top half of the cell. */
+  top: Rgb;
+  /** Colour of the bottom half of the cell. */
+  bottom: Rgb;
+}
+
+export interface HalfBlockImage {
+  cols: number;
+  rows: number;
+  /** Row-major, `cells[row][col]`. */
+  cells: HalfBlockCell[][];
+}
+
+/** A run of cells sharing the same top/bottom colours. */
+export interface ImageRun {
+  text: string;
+  top: Rgb;
+  bottom: Rgb;
+}
+
+export interface FitOptions {
+  /** Hard cap on the rendered width, in terminal cells. */
+  maxCols: number;
+  /** Hard cap on the rendered height, in terminal cells. */
+  maxRows: number;
+  /**
+   * Width ÷ height of one terminal cell. Real cells are about half as wide
+   * as tall, so the default keeps image proportions honest.
+   */
+  cellAspect?: number;
+}
+
+export interface RasterizeOptions extends FitOptions {
+  /** Painted behind transparent pixels. Defaults to black. */
+  background?: Rgb;
+}
+
+/** Default cell width ÷ height — standard terminal cells are ~1:2. */
+export const DEFAULT_CELL_ASPECT = 0.5;
+
+/** The character used to split a cell into two vertically stacked pixels. */
+export const HALF_BLOCK = "\u2580";
+
+/**
+ * Largest cell grid that shows the whole image inside the given bounds
+ * without distorting it.
+ */
+export function fitImageToCells(
+  imgWidth: number,
+  imgHeight: number,
+  opts: FitOptions,
+): { cols: number; rows: number } {
+  const cellAspect = opts.cellAspect ?? DEFAULT_CELL_ASPECT;
+  const minCols = Math.max(1, Math.min(opts.maxCols, 8));
+  if (imgWidth <= 0 || imgHeight <= 0) {
+    return { cols: minCols, rows: 1 };
+  }
+
+  // rows/cols = cellAspect * (imgHeight / imgWidth)
+  const rowsPerCol = cellAspect * (imgHeight / imgWidth);
+  let cols = Math.max(minCols, Math.floor(opts.maxCols));
+  let rows = Math.max(1, Math.round(cols * rowsPerCol));
+
+  if (rows > opts.maxRows) {
+    rows = Math.max(1, opts.maxRows);
+    cols = Math.max(
+      minCols,
+      Math.min(cols, Math.floor(rows / Math.max(rowsPerCol, 1e-6))),
+    );
+  }
+  return { cols, rows };
+}
+
+/** Sample RGBA at a pixel, compositing over `background` when translucent. */
+function pixelAt(
+  img: DecodedImage,
+  x: number,
+  y: number,
+  background: Rgb,
+): Rgb {
+  const o = (y * img.width + x) * 4;
+  const a = img.data[o + 3] / 255;
+  if (a >= 1) return [img.data[o], img.data[o + 1], img.data[o + 2]];
+  const mix = (channel: number, bg: number) =>
+    Math.round(channel * a + bg * (1 - a));
+  return [
+    mix(img.data[o], background[0]),
+    mix(img.data[o + 1], background[1]),
+    mix(img.data[o + 2], background[2]),
+  ];
+}
+
+/** Convert decoded pixels into half-block cells, row-major. */
+export function toHalfBlocks(
+  img: DecodedImage,
+  opts: { background?: Rgb } = {},
+): HalfBlockImage {
+  const background = opts.background ?? [0, 0, 0];
+  const cells: HalfBlockCell[][] = [];
+  for (let row = 0; row * 2 < img.height; row++) {
+    const cellsRow: HalfBlockCell[] = [];
+    const topY = row * 2;
+    const bottomY = topY + 1;
+    for (let x = 0; x < img.width; x++) {
+      const top = pixelAt(img, x, topY, background);
+      const bottom =
+        bottomY < img.height ? pixelAt(img, x, bottomY, background) : top;
+      cellsRow.push({ top, bottom });
+    }
+    cells.push(cellsRow);
+  }
+  return { cols: img.width, rows: cells.length, cells };
+}
+
+/** Collapse each cell row into runs of identical colours. */
+export function toImageRuns(image: HalfBlockImage): ImageRun[][] {
+  return image.cells.map((cells) => {
+    const runs: ImageRun[] = [];
+    for (const cell of cells) {
+      const last = runs[runs.length - 1];
+      if (
+        last &&
+        last.top[0] === cell.top[0] &&
+        last.top[1] === cell.top[1] &&
+        last.top[2] === cell.top[2] &&
+        last.bottom[0] === cell.bottom[0] &&
+        last.bottom[1] === cell.bottom[1] &&
+        last.bottom[2] === cell.bottom[2]
+      ) {
+        last.text += HALF_BLOCK;
+        continue;
+      }
+      runs.push({ text: HALF_BLOCK, top: cell.top, bottom: cell.bottom });
+    }
+    return runs;
+  });
+}
+
+/**
+ * Source image pixel budget. A README can link to anything, and a highly
+ * compressible 20k×20k PNG is a few kilobytes on the wire, so refuse absurd
+ * canvases before the decoder allocates for them.
+ */
+const MAX_SOURCE_PIXELS = 20_000_000;
+
+/**
+ * Decode any supported image format, scale it to the requested cell grid
+ * and convert it to half blocks.
+ *
+ * Anything `Bun.Image` can read (PNG, JPEG, WebP, GIF first frame, BMP,
+ * and HEIC/AVIF where the OS has a codec) is normalised to PNG here, so the
+ * decoder only ever sees one format. Returns `null` when the runtime has no
+ * image codec, the image is unreadable, or it is too large to bother with.
+ */
+export async function rasterizeImage(
+  bytes: Uint8Array,
+  opts: RasterizeOptions,
+): Promise<HalfBlockImage | null> {
+  const ImageCtor = (
+    globalThis as {
+      Bun?: {
+        Image?: new (
+          input: Uint8Array,
+          constructorOptions?: { maxPixels?: number },
+        ) => {
+          metadata(): Promise<{ width: number; height: number }>;
+          resize(
+            width: number,
+            height?: number,
+            options?: { fit?: "fill" | "inside" },
+          ): {
+            png(options?: { compressionLevel?: number }): {
+              bytes(): Promise<Uint8Array>;
+            };
+          };
+        };
+      };
+    }
+  ).Bun?.Image;
+  if (!ImageCtor) return null;
+
+  const source = new ImageCtor(bytes, { maxPixels: MAX_SOURCE_PIXELS });
+  try {
+    const meta = await source.metadata();
+    const { cols, rows } = fitImageToCells(meta.width, meta.height, opts);
+    const png = await source
+      .resize(cols, rows * 2, { fit: "fill" })
+      .png({ compressionLevel: 1 })
+      .bytes();
+    return toHalfBlocks(decodePng(png), { background: opts.background });
+  } catch {
+    return null;
+  }
+}

package/src/markdown-images.ts

@@ -0,0 +1,123 @@
+/**
+ * Markdown token helpers — pure functions over marked-shaped tokens.
+ *
+ * Kept free of any OpenTUI import so the token handling can be unit tested
+ * without a renderer.
+ */
+
+/** Minimal shape of a marked inline token. */
+export interface InlineTokenLike {
+  type?: string;
+  text?: string;
+  href?: string;
+  raw?: string;
+  tokens?: InlineTokenLike[];
+}
+
+/** Minimal shape of a marked block token. */
+export interface BlockTokenLike extends InlineTokenLike {
+  depth?: number;
+}
+
+export interface ImageRef {
+  href: string;
+  alt: string;
+}
+
+const IMG_TAG = /<img\b[^>]*?src\s*=\s*["']([^"']+)["'][^>]*>/gi;
+const ALT_ATTR = /\balt\s*=\s*["']([^"']*)["']/i;
+const HTML_TAG = /<\/?[a-z][^>]*>/gi;
+
+/** Images embedded as raw `<img>` tags, when there's no other content. */
+function imagesFromHtml(raw: string | undefined): ImageRef[] {
+  if (!raw || !/<img\b/i.test(raw)) return [];
+  // Anything other than an <img> tag with real text between the tags means
+  // this isn't a pure image block (e.g. a centered figure with a caption).
+  const withoutTags = raw
+    .replace(IMG_TAG, "")
+    .replace(/<\/?(?:p|div|center|br|a|picture|source)\b[^>]*>/gi, "")
+    .trim();
+  if (withoutTags) return [];
+
+  const refs: ImageRef[] = [];
+  for (const match of raw.matchAll(IMG_TAG)) {
+    const tag = match[0];
+    const alt = ALT_ATTR.exec(tag)?.[1] ?? "";
+    refs.push({ href: match[1], alt });
+  }
+  return refs;
+}
+
+/** Flatten inline tokens (bold, links, code, …) down to their text. */
+export function inlinePlainText(tokens: InlineTokenLike[] | undefined): string {
+  if (!tokens) return "";
+  let out = "";
+  for (const token of tokens) {
+    if (token.type === "image") continue;
+    if (token.type === "html") {
+      out += (token.raw ?? "").replace(HTML_TAG, "");
+      continue;
+    }
+    if (token.type === "br") {
+      out += "\n";
+      continue;
+    }
+    if (token.text && (!token.tokens || token.tokens.length === 0)) {
+      out += token.text;
+      continue;
+    }
+    if (token.tokens?.length) {
+      out += inlinePlainText(token.tokens);
+      continue;
+    }
+    if (token.raw) out += token.raw.replace(HTML_TAG, "");
+  }
+  return out;
+}
+
+/**
+ * Image references for a block token, or `null` when the block isn't a pure
+ * image block (markdown images and/or standalone `<img>` tags only).
+ */
+export function extractImageRefs(token: BlockTokenLike): ImageRef[] | null {
+  const images: ImageRef[] = [];
+
+  const collect = (inline: InlineTokenLike): boolean => {
+    if (inline.type === "image") {
+      if (inline.href)
+        images.push({ href: inline.href, alt: inline.text ?? "" });
+      return true;
+    }
+    if (inline.type === "html") {
+      const refs = imagesFromHtml(inline.raw);
+      if (refs.length > 0) {
+        images.push(...refs);
+        return true;
+      }
+      // Inline markup such as <br> doesn't disqualify the block.
+      return !(inline.raw ?? "").replace(HTML_TAG, "").trim();
+    }
+    // Whitespace-only text between images is fine; anything else means the
+    // block is a paragraph that happens to contain an image.
+    if (inline.type === "text" || inline.type === "escape") {
+      return !(inline.text ?? "").trim();
+    }
+    return false;
+  };
+
+  if (token.type === "image" && token.href) {
+    return [{ href: token.href, alt: token.text ?? "" }];
+  }
+
+  if (token.type === "html") {
+    const refs = imagesFromHtml(token.raw);
+    return refs.length > 0 ? refs : null;
+  }
+
+  const inline = token.tokens ?? [];
+  if (inline.length === 0) return null;
+  for (const child of inline) {
+    if (!collect(child)) return null;
+  }
+  return images.length > 0 ? images : null;
+}