mergie-cli 0.1.0

package/src/domain/context.ts

@@ -0,0 +1,32 @@
+/** The `matched` line plus up to `n` context lines on each side. */
+export interface ContextSlice {
+  /** Up to `n` lines before `matched`, top-to-bottom (clamped at file start). */
+  before: string[];
+  /** The matched line's text; empty string when `line` is out of range. */
+  matched: string;
+  /** Up to `n` lines after `matched`, top-to-bottom (clamped at file end). */
+  after: string[];
+}
+
+/**
+ * Slice `n` lines of context around a 1-based `line` within `lines`.
+ * Out-of-range lines yield an empty `matched` and no context.
+ * @param lines - The file's lines (0-based array, 1-based `line`).
+ * @param line - 1-based line number to centre on.
+ * @param n - Number of context lines to include on each side.
+ */
+export function sliceContext(
+  lines: readonly string[],
+  line: number,
+  n: number,
+): ContextSlice {
+  const idx = line - 1;
+  if (idx < 0 || idx >= lines.length) {
+    return { before: [], matched: "", after: [] };
+  }
+  return {
+    before: lines.slice(Math.max(0, idx - n), idx),
+    matched: lines[idx] ?? "",
+    after: lines.slice(idx + 1, idx + 1 + n),
+  };
+}

package/src/domain/diff.ts

@@ -0,0 +1,178 @@
+import { hunkHash } from "./hash.ts";
+
+/** How a file was changed in a diff. */
+export type FileStatus = "added" | "deleted" | "modified" | "renamed";
+
+/** Whether a diff line is unchanged context, an addition, or a deletion. */
+export type DiffLineKind = "ctx" | "add" | "del";
+
+/** A half-open character range `[start, end)` within a line's text. */
+export interface CharRange {
+  /** 0-based index of the first changed character. */
+  start: number;
+  /** 0-based index one past the last changed character. */
+  end: number;
+}
+
+/** A single line within a hunk. */
+export interface DiffLine {
+  /** Line kind. */
+  kind: DiffLineKind;
+  /** 1-based line number on the base (old) side; undefined for additions. */
+  oldNo?: number;
+  /** 1-based line number on the head (new) side; undefined for deletions. */
+  newNo?: number;
+  /** Line text without the leading +/-/space marker. */
+  text: string;
+  /**
+   * Intra-line changed character ranges (from the word-diff pass), for
+   * highlighting the exact edited words. Absent on unchanged lines and on
+   * near-total rewrites (where the whole-line background suffices).
+   */
+  changes?: CharRange[];
+}
+
+/** A contiguous block of changes within a file. */
+export interface Hunk {
+  /** The raw `@@ ... @@` header line (including any section heading). */
+  header: string;
+  /** 1-based start line on the base side. */
+  oldStart: number;
+  /** Line count on the base side. */
+  oldLines: number;
+  /** 1-based start line on the head side. */
+  newStart: number;
+  /** Line count on the head side. */
+  newLines: number;
+  /** The hunk's lines in order. */
+  lines: DiffLine[];
+  /** Content hash identifying this hunk (independent of line numbers). */
+  hash: string;
+}
+
+/** A single file's changes within a diff. */
+export interface FileDiff {
+  /** Path on the base side (equals newPath unless renamed/added). */
+  oldPath: string;
+  /** Path on the head side (equals oldPath unless renamed/deleted). */
+  newPath: string;
+  /** How the file changed. */
+  status: FileStatus;
+  /** True for binary files (no textual hunks are produced). */
+  isBinary: boolean;
+  /** The file's hunks (empty for binary / pure-rename files). */
+  hunks: Hunk[];
+}
+
+/**
+ * Parse `git diff` unified output into structured per-file diffs with per-hunk
+ * content hashes. Pure — performs no git or filesystem access.
+ */
+export function parseUnifiedDiff(text: string): FileDiff[] {
+  return splitFileChunks(text).map(parseFileChunk);
+}
+
+/** Split raw diff text into per-file line groups, each starting at `diff --git`. */
+function splitFileChunks(text: string): string[][] {
+  const chunks: string[][] = [];
+  let current: string[] | null = null;
+  for (const line of text.split("\n")) {
+    if (line.startsWith("diff --git ")) {
+      current = [line];
+      chunks.push(current);
+    } else if (current) {
+      current.push(line);
+    }
+  }
+  return chunks;
+}
+
+/** Strip an `a/` or `b/` prefix; return null for `/dev/null`. */
+function pathOf(raw: string): string | null {
+  if (raw === "/dev/null") return null;
+  return raw.startsWith("a/") || raw.startsWith("b/") ? raw.slice(2) : raw;
+}
+
+function parseFileChunk(lines: string[]): FileDiff {
+  const gitLine: string = lines[0] ?? "";
+  const gm = /^diff --git a\/(.+) b\/(.+)$/.exec(gitLine);
+  const meta = { oldPath: gm?.[1] ?? "", newPath: gm?.[2] ?? "", status: "modified" as FileStatus, isBinary: false };
+
+  const hunkStart: number = lines.findIndex((l) => l.startsWith("@@ "));
+  const headerLines: string[] = hunkStart === -1 ? lines.slice(1) : lines.slice(1, hunkStart);
+  applyHeaderLines(headerLines, meta);
+
+  const hashPath: string = meta.status === "deleted" ? meta.oldPath : meta.newPath;
+  const hunks: Hunk[] = hunkStart === -1 ? [] : parseHunks(lines.slice(hunkStart), hashPath);
+  return { ...meta, hunks };
+}
+
+/** Mutate a local metadata accumulator from a file's header lines. */
+function applyHeaderLines(headerLines: string[], meta: { oldPath: string; newPath: string; status: FileStatus; isBinary: boolean }): void {
+  for (const line of headerLines) {
+    if (line.startsWith("new file mode")) meta.status = "added";
+    else if (line.startsWith("deleted file mode")) meta.status = "deleted";
+    else if (line.startsWith("rename from ")) { meta.oldPath = line.slice(12); meta.status = "renamed"; }
+    else if (line.startsWith("rename to ")) { meta.newPath = line.slice(10); meta.status = "renamed"; }
+    else if (line.startsWith("Binary files ")) meta.isBinary = true;
+    else if (line.startsWith("--- ")) applyOldSide(pathOf(line.slice(4)), meta);
+    else if (line.startsWith("+++ ")) applyNewSide(pathOf(line.slice(4)), meta);
+  }
+}
+
+function applyOldSide(path: string | null, meta: { oldPath: string; status: FileStatus }): void {
+  if (path === null) meta.status = "added";
+  else meta.oldPath = path;
+}
+
+function applyNewSide(path: string | null, meta: { newPath: string; status: FileStatus }): void {
+  if (path === null) meta.status = "deleted";
+  else meta.newPath = path;
+}
+
+/** Parse the hunk region of a file into Hunk objects. */
+function parseHunks(lines: string[], hashPath: string): Hunk[] {
+  const hunks: Hunk[] = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line: string | undefined = lines[i];
+    if (line === undefined || !line.startsWith("@@ ")) { i++; continue; }
+    i++;
+    const body: string[] = [];
+    while (i < lines.length && !(lines[i] ?? "").startsWith("@@ ")) {
+      body.push(lines[i] ?? "");
+      i++;
+    }
+    hunks.push(buildHunk(line, body, hashPath));
+  }
+  return hunks;
+}
+
+/** Parse an `@@ -a,b +c,d @@` header; counts default to 1 when omitted. */
+function parseHunkHeader(header: string): Pick<Hunk, "oldStart" | "oldLines" | "newStart" | "newLines"> {
+  const m = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/.exec(header);
+  if (!m) throw new Error(`Malformed hunk header: ${header}`);
+  return {
+    oldStart: Number(m[1]),
+    oldLines: m[2] ? Number(m[2]) : 1,
+    newStart: Number(m[3]),
+    newLines: m[4] ? Number(m[4]) : 1,
+  };
+}
+
+function buildHunk(header: string, body: string[], hashPath: string): Hunk {
+  const ranges = parseHunkHeader(header);
+  let oldNo: number = ranges.oldStart;
+  let newNo: number = ranges.newStart;
+  const parsed: DiffLine[] = [];
+  const hashBody: string[] = [];
+  for (const raw of body) {
+    if (raw.startsWith("\\")) continue; // ""
+    const marker: string = raw[0] ?? "";
+    const text: string = raw.slice(1);
+    if (marker === "+") { parsed.push({ kind: "add", oldNo: undefined, newNo, text }); hashBody.push(raw); newNo++; }
+    else if (marker === "-") { parsed.push({ kind: "del", oldNo, newNo: undefined, text }); hashBody.push(raw); oldNo++; }
+    else if (marker === " ") { parsed.push({ kind: "ctx", oldNo, newNo, text }); hashBody.push(raw); oldNo++; newNo++; }
+  }
+  return { header, ...ranges, lines: parsed, hash: hunkHash(hashPath, hashBody.join("\n")) };
+}

package/src/domain/entities.ts

@@ -0,0 +1,92 @@
+/**
+ * A code entity from `sem entities <path> --json` — a function, method, class,
+ * type, etc. Used to enumerate all definitions of a name (sem's `context` only
+ * ever resolves one, so listing all definitions goes through `entities`).
+ */
+export interface SemEntity {
+  /**
+   * Repo-relative file the entity is in. Present when listing a directory
+   * (`sem entities .`); "" when listing a single file (the file is implied by
+   * the path argument — the caller fills it in).
+   */
+  file: string;
+  /** Entity name (the symbol). */
+  name: string;
+  /** Entity kind, e.g. "function", "method", "class", "type". */
+  type: string;
+  /** 1-based first line of the entity. */
+  startLine: number;
+  /** 1-based last line of the entity (inclusive). */
+  endLine: number;
+  /** Full id of the enclosing entity (e.g. `file::class::Foo`), or null. */
+  parentId: string | null;
+}
+
+/** Read a number, or a fallback, from an unknown record property. */
+function num(value: unknown, fallback: number): number {
+  return typeof value === "number" ? value : fallback;
+}
+
+/**
+ * Parse a `sem entities --json` payload (an array of raw entities) into typed
+ * {@link SemEntity} records. Returns [] on any shape error rather than throwing.
+ */
+export function parseEntities(raw: string): SemEntity[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed)) return [];
+  const out: SemEntity[] = [];
+  for (const item of parsed) {
+    if (typeof item !== "object" || item === null) continue;
+    const rec: Record<string, unknown> = { ...item };
+    if (typeof rec.name !== "string" || typeof rec.type !== "string") continue;
+    const parentId: string | null = typeof rec.parent_id === "string" ? rec.parent_id : null;
+    out.push({
+      file: typeof rec.file === "string" ? rec.file : "",
+      name: rec.name,
+      type: rec.type,
+      startLine: num(rec.start_line, 1),
+      endLine: num(rec.end_line, num(rec.start_line, 1)),
+      parentId,
+    });
+  }
+  return out;
+}
+
+/**
+ * The entities that are definitions of `name`: an exact name match, excluding
+ * non-code entities (markdown headings). Partial-name matches are excluded.
+ */
+export function matchEntities(entities: readonly SemEntity[], name: string): SemEntity[] {
+  return entities.filter((e) => e.name === name && e.type !== "heading");
+}
+
+/**
+ * The inclusive 1-based `[startLine, endLine]` slice of `lines` as a body
+ * string, plus its first non-empty line (a readable header for the preview).
+ * Bounds are clamped to the available lines.
+ */
+export function sliceBody(lines: string[], startLine: number, endLine: number): { body: string; matched: string } {
+  const from: number = Math.max(1, startLine);
+  const to: number = Math.min(lines.length, endLine);
+  const slice: string[] = lines.slice(from - 1, to);
+  const body: string = slice.join("\n");
+  const matched: string = slice.find((l) => l.trim() !== "") ?? "";
+  return { body, matched };
+}
+
+/**
+ * A human scope label for a definition: `Parent.name` when the entity is nested
+ * (e.g. a method of a class), otherwise the bare `name`. The parent name is the
+ * last `::`-delimited segment of the parent id.
+ */
+export function scopeLabel(parentId: string | null, name: string): string {
+  if (parentId === null || parentId === "") return name;
+  const segments: string[] = parentId.split("::");
+  const parent: string = segments[segments.length - 1] ?? "";
+  return parent === "" ? name : `${parent}.${name}`;
+}

package/src/domain/fuzzy.ts

@@ -0,0 +1,43 @@
+/** Characters that mark a "word boundary" in a path/filename. */
+const BOUNDARY = new Set(["/", "_", "-", ".", " "]);
+
+/**
+ * Score how well `query` fuzzy-matches `target` (case-insensitive subsequence).
+ * Higher is better; contiguous runs and matches at word boundaries score more.
+ *
+ * @returns The score, or `null` if `query` is not a subsequence of `target`.
+ */
+export function fuzzyScore(query: string, target: string): number | null {
+  if (query.length === 0) return 0;
+  const q: string = query.toLowerCase();
+  const t: string = target.toLowerCase();
+
+  let score = 0;
+  let qi = 0;
+  let prevMatch = -2;
+  for (let ti = 0; ti < t.length && qi < q.length; ti++) {
+    if (t[ti] !== q[qi]) continue;
+    score += 1;
+    if (ti === prevMatch + 1) score += 8; // contiguous run (weighted above boundaries)
+    if (ti === 0 || BOUNDARY.has(t[ti - 1] ?? "")) score += 6; // word boundary
+    prevMatch = ti;
+    qi++;
+  }
+  return qi === q.length ? score : null;
+}
+
+/**
+ * Filter and rank items by fuzzy match against `query`. An empty query returns
+ * the items unchanged; otherwise non-matches are dropped and matches are sorted
+ * by score (desc), breaking ties by shorter item then original order.
+ */
+export function fuzzyFilter(query: string, items: readonly string[]): string[] {
+  if (query.length === 0) return [...items];
+  const scored: Array<{ item: string; score: number; index: number }> = [];
+  items.forEach((item, index) => {
+    const score = fuzzyScore(query, item);
+    if (score !== null) scored.push({ item, score, index });
+  });
+  scored.sort((a, b) => b.score - a.score || a.item.length - b.item.length || a.index - b.index);
+  return scored.map((s) => s.item);
+}

package/src/domain/generated.ts

@@ -0,0 +1,33 @@
+/**
+ * Pure heuristic: does a repo-relative path look like test code?
+ *
+ * Matches a `__tests__/` directory, a `.test.`/`.spec.` filename infix, or a
+ * `test/` or `tests/` path segment. Segment matching is anchored on `/`
+ * boundaries so `latest/`, `contest/`, or `spectacular.ts` do NOT match.
+ *
+ * @param path - Repository-relative file path (forward-slash separated).
+ */
+export function isTestPath(path: string): boolean {
+  return (
+    path.includes("__tests__/") ||
+    path.includes(".test.") ||
+    path.includes(".spec.") ||
+    /(^|\/)tests?\//.test(path)
+  );
+}
+
+/**
+ * Whether a result's file should be treated as test/generated (hideable via
+ * the UI's "exclude tests & generated" toggle). Combines the caller-supplied
+ * lockfile/generated verdict (which uses backend glob patterns) with the pure
+ * test-path heuristic.
+ *
+ * @param path - Repository-relative file path.
+ * @param isLockfileOrGenerated - Result of the backend lockfile-glob matcher.
+ */
+export function isTestOrGenerated(
+  path: string,
+  isLockfileOrGenerated: boolean,
+): boolean {
+  return isLockfileOrGenerated || isTestPath(path);
+}

package/src/domain/lockfiles.ts

@@ -0,0 +1,20 @@
+import { basename } from "node:path";
+
+/**
+ * Decide whether a file path is a lock / generated file that should be
+ * hideable via the UI toggle.
+ *
+ * A path matches if any glob matches the full path, or (for convenience) the
+ * bare filename — so `package-lock.json` matches `web/package-lock.json`, and
+ * `*.min.js` matches `dist/app.min.js`.
+ *
+ * @param path     Repository-relative file path.
+ * @param patterns Glob patterns (from built-in defaults + user config).
+ */
+export function isLockfile(path: string, patterns: readonly string[]): boolean {
+  const name: string = basename(path);
+  return patterns.some((pattern) => {
+    const glob = new Bun.Glob(pattern);
+    return glob.match(path) || glob.match(name);
+  });
+}

package/src/domain/paths.ts

@@ -0,0 +1,59 @@
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { PullRequestRef } from "./url.ts";
+
+/**
+ * Environment injection for path resolution — lets tests supply env/home
+ * without touching real globals.
+ */
+export interface PathEnv {
+  /** Environment variables to read (defaults to `process.env`). */
+  env?: Record<string, string | undefined>;
+  /** Home directory (defaults to `os.homedir()`). */
+  home?: string;
+}
+
+/** Per-PR directory name, e.g. `pr_withastro_astro_17360`. */
+function prSlug(ref: PullRequestRef): string {
+  return `pr_${ref.owner}_${ref.repo}_${ref.number}`;
+}
+
+function resolveEnv(opts?: PathEnv): { env: Record<string, string | undefined>; home: string } {
+  return { env: opts?.env ?? process.env, home: opts?.home ?? homedir() };
+}
+
+/**
+ * Root of mergie's per-PR persistent data:
+ * `$XDG_DATA_HOME/mergie/pr_<owner>_<repo>_<n>`, falling back to
+ * `~/.local/share/mergie/...` when `XDG_DATA_HOME` is unset.
+ */
+export function dataDir(ref: PullRequestRef, opts?: PathEnv): string {
+  const { env, home } = resolveEnv(opts);
+  const base: string = env.XDG_DATA_HOME || join(home, ".local", "share");
+  return join(base, "mergie", prSlug(ref));
+}
+
+/**
+ * mergie's config directory: `$XDG_CONFIG_HOME/mergie`, falling back to
+ * `~/.config/mergie`.
+ */
+export function configDir(opts?: PathEnv): string {
+  const { env, home } = resolveEnv(opts);
+  const base: string = env.XDG_CONFIG_HOME || join(home, ".config");
+  return join(base, "mergie");
+}
+
+/** Reusable clone directory for a PR (inside its data dir). */
+export function cloneDir(ref: PullRequestRef, opts?: PathEnv): string {
+  return join(dataDir(ref, opts), "clone");
+}
+
+/** Directory holding AI-generated artifacts for a PR. */
+export function artifactsDir(ref: PullRequestRef, opts?: PathEnv): string {
+  return join(dataDir(ref, opts), "artifacts");
+}
+
+/** SQLite database file path for a PR. */
+export function dbPath(ref: PullRequestRef, opts?: PathEnv): string {
+  return join(dataDir(ref, opts), "mergie.db");
+}

package/src/domain/ranges.ts

@@ -0,0 +1,81 @@
+/** A pull request's commit topology for range resolution. */
+export interface PrCommits {
+  /** The "before-PR" baseline (merge-base with target); a valid range start. */
+  baselineSha: string;
+  /** PR commit SHAs, ordered oldest → newest. */
+  commits: string[];
+}
+
+/** A range the user has marked reviewed. */
+export interface ReviewedRange {
+  /** Range start SHA (excluded baseline). */
+  startSha: string;
+  /** Range end SHA. */
+  endSha: string;
+  /** Creation timestamp (ms) — used to find the most recent. */
+  createdAt: number;
+}
+
+/** A commit range: diff is startSha → endSha (start excluded). */
+export interface Range {
+  /** Baseline SHA (its own changes are excluded). */
+  startSha: string;
+  /** End SHA (inclusive). */
+  endSha: string;
+}
+
+/** All SHAs that are valid range endpoints for a PR. */
+function knownShas(pr: PrCommits): Set<string> {
+  return new Set<string>([pr.baselineSha, ...pr.commits]);
+}
+
+/** Ordinal position of a SHA (baseline = -1, commits 0..n-1); -Infinity if unknown. */
+function ordinal(sha: string, pr: PrCommits): number {
+  if (sha === pr.baselineSha) return -1;
+  const idx: number = pr.commits.indexOf(sha);
+  return idx === -1 ? Number.NEGATIVE_INFINITY : idx;
+}
+
+/** The head (latest) SHA of the PR. */
+function headSha(pr: PrCommits): string {
+  return pr.commits.at(-1) ?? pr.baselineSha;
+}
+
+/**
+ * Resolve the range shown when a PR first opens: the most recently reviewed
+ * range's end → head. If no non-stale reviewed range exists, the whole PR
+ * (baseline → head).
+ */
+export function resolveDefaultRange(pr: PrCommits, reviewed: ReviewedRange[]): Range {
+  const head: string = headSha(pr);
+  const known: Set<string> = knownShas(pr);
+  const latestValid: ReviewedRange | undefined = [...reviewed]
+    .sort((a, b) => b.createdAt - a.createdAt)
+    .find((r) => known.has(r.endSha));
+  return { startSha: latestValid?.endSha ?? pr.baselineSha, endSha: head };
+}
+
+/**
+ * True if the exact range (both endpoints) has already been marked reviewed.
+ * Used to reflect reviewed status on the "mark reviewed" control, since
+ * re-marking an already-reviewed range is a silent no-op.
+ */
+export function isRangeReviewed(range: Range, reviewed: ReviewedRange[]): boolean {
+  return reviewed.some((r) => r.startSha === range.startSha && r.endSha === range.endSha);
+}
+
+/** True if either endpoint of a range is no longer present in the PR. */
+export function isStale(range: Range, pr: PrCommits): boolean {
+  const known: Set<string> = knownShas(pr);
+  return !known.has(range.startSha) || !known.has(range.endSha);
+}
+
+/**
+ * Validate a candidate range: both endpoints must exist and start must come
+ * strictly before end in commit order.
+ */
+export function isValidRange(startSha: string, endSha: string, pr: PrCommits): boolean {
+  const known: Set<string> = knownShas(pr);
+  if (!known.has(startSha) || !known.has(endSha)) return false;
+  return ordinal(startSha, pr) < ordinal(endSha, pr);
+}

package/src/domain/references.ts

@@ -0,0 +1,36 @@
+/** An inclusive, 1-based line span `[start, end]`. */
+export type Span = [number, number];
+
+/** Escape a string for safe use as a literal inside a RegExp. */
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Find the 1-based line numbers within `span` where `symbol` appears as a
+ * whole word (word-boundary match). A `symbol` that is only a substring of a
+ * longer identifier (e.g. `foo` inside `fooBar`) does NOT match.
+ *
+ * The span is inclusive and 1-based; it is clamped to the file's bounds.
+ *
+ * @param lines - The file's lines (0-based array, 1-based line numbers).
+ * @param span - Inclusive `[start, end]` line range to search within.
+ * @param symbol - The identifier to look for.
+ * @returns Ascending, de-duplicated line numbers containing a real reference.
+ */
+export function findReferences(
+  lines: readonly string[],
+  span: Span,
+  symbol: string,
+): number[] {
+  const [start, end] = span;
+  const from = Math.max(1, start);
+  const to = Math.min(lines.length, end);
+  const pattern = new RegExp(`\\b${escapeRegExp(symbol)}\\b`);
+  const hits: number[] = [];
+  for (let line = from; line <= to; line++) {
+    const text = lines[line - 1];
+    if (text !== undefined && pattern.test(text)) hits.push(line);
+  }
+  return hits;
+}

package/src/domain/url.ts

@@ -0,0 +1,50 @@
+/**
+ * A parsed reference to a GitHub pull request, extracted from a PR URL.
+ */
+export interface PullRequestRef {
+  /** Git host, e.g. "github.com". */
+  host: string;
+  /** Repository owner / organisation, e.g. "withastro". */
+  owner: string;
+  /** Repository name, e.g. "astro". */
+  repo: string;
+  /** Pull request number (positive integer). */
+  number: number;
+}
+
+/**
+ * Parse a GitHub pull-request URL into its components.
+ *
+ * Tolerant of trailing segments (`/changes`, `/files`, a trailing slash) and
+ * of URL fragments/queries — only the `owner/repo/pull/<number>` portion is
+ * significant.
+ *
+ * @param input A pull-request URL such as
+ *   `https://github.com/withastro/astro/pull/17360/changes`.
+ * @returns The parsed {@link PullRequestRef}.
+ * @throws If the input is not a URL, or is not a `/pull/<number>` URL.
+ */
+export function parsePrUrl(input: string): PullRequestRef {
+  let url: URL;
+  try {
+    url = new URL(input);
+  } catch {
+    throw new Error(`Invalid PR URL: ${input}`);
+  }
+
+  const segments: string[] = url.pathname.split("/").filter(Boolean);
+  const [owner, repo, kind, rawNumber] = segments;
+
+  if (!owner || !repo || kind !== "pull" || !rawNumber) {
+    throw new Error(`Not a pull-request URL: ${input}`);
+  }
+  if (!/^\d+$/.test(rawNumber)) {
+    throw new Error(`Invalid PR number in URL: ${input}`);
+  }
+  const number: number = Number.parseInt(rawNumber, 10);
+  if (number <= 0) {
+    throw new Error(`Invalid PR number in URL: ${input}`);
+  }
+
+  return { host: url.hostname, owner, repo, number };
+}