@pablocm90/visual-review 0.0.0-stage → 0.1.0

package/dist/crate-modules.js

@@ -0,0 +1,103 @@
+import { basename, dirname, join } from 'node:path';
+import { crateId } from './crate-graph.js';
+import { edgeKey } from './graph.js';
+import { isCfgTest, itemsIn, parseRust } from './rust-syntax.js';
+const itemsOf = (text) => {
+    const root = parseRust(text);
+    if (root === undefined)
+        return [];
+    return itemsIn(root)
+        .filter(({ attributes }) => !attributes.some(isCfgTest))
+        .map(({ node }) => node);
+};
+const declaredModules = (items) => items.flatMap(node => node.type === 'mod_item' && node.childForFieldName('body') === null
+    ? [node.childForFieldName('name')?.text ?? '']
+    : []);
+const EXTERN_PRELUDE = '::';
+const segmentsOf = (node) => {
+    if (node === null)
+        return [EXTERN_PRELUDE];
+    if (node.type !== 'scoped_identifier')
+        return [node.text];
+    return [
+        ...segmentsOf(node.childForFieldName('path')),
+        node.childForFieldName('name')?.text ?? '',
+    ];
+};
+const pathsInUse = (node) => {
+    if (node.type === 'use_list')
+        return node.namedChildren.flatMap(pathsInUse);
+    if (node.type === 'use_as_clause')
+        return [segmentsOf(node.childForFieldName('path'))];
+    if (node.type === 'use_wildcard')
+        return [segmentsOf(node.namedChildren[0] ?? null)];
+    if (node.type === 'scoped_use_list') {
+        const prefix = segmentsOf(node.childForFieldName('path'));
+        const list = node.childForFieldName('list');
+        return (list === null ? [] : pathsInUse(list)).map(path => [...prefix, ...path]);
+    }
+    return [segmentsOf(node)];
+};
+const usedPaths = (items) => items.flatMap(node => {
+    const argument = node.type === 'use_declaration' ? node.childForFieldName('argument') : null;
+    return argument === null ? [] : pathsInUse(argument);
+});
+export const crateModules = ({ crate, roots, sources }) => {
+    const readModule = ({ path, segments, label }) => ({
+        label,
+        path,
+        segments,
+        items: itemsOf(sources[path] ?? ''),
+    });
+    const withChildren = ({ module, directory }) => [
+        module,
+        ...declaredModules(module.items).flatMap(name => {
+            const found = [join(directory, `${name}.rs`), join(directory, name, 'mod.rs')].find(candidate => sources[candidate] !== undefined);
+            if (found === undefined)
+                return [];
+            const segments = [...module.segments, name];
+            return withChildren({
+                module: readModule({ path: found, segments, label: segments.join('::') }),
+                directory: join(directory, name),
+            });
+        }),
+    ];
+    const idOf = (module) => `rust/mod/${crate}/${module.label}`;
+    const trees = roots.map(path => withChildren({
+        module: readModule({ path, segments: [], label: basename(path) }),
+        directory: dirname(path),
+    }));
+    const edges = trees.flatMap(tree => {
+        const byKey = new Map(tree.map(module => [module.segments.join('::'), module]));
+        const moduleAt = (segments) => byKey.get(segments.join('::'));
+        const startOf = (from, first) => {
+            if (first === 'crate')
+                return [];
+            if (first === 'self')
+                return from;
+            if (first === 'super')
+                return from.slice(0, -1);
+            return [...from, first];
+        };
+        const targetOf = (from, [first = '', ...rest]) => {
+            const absolute = rest.reduce((at, segment) => (segment === 'super' ? at.slice(0, -1) : at.concat(segment)), startOf(from, first));
+            return Array.from({ length: absolute.length + 1 }, (_, index) => moduleAt(absolute.slice(0, absolute.length - index))).find(module => module !== undefined);
+        };
+        return tree.flatMap(module => usedPaths(module.items).flatMap((path) => {
+            const target = targetOf(module.segments, path);
+            return target === undefined || target === module
+                ? []
+                : [{ from: idOf(module), to: idOf(target) }];
+        }));
+    });
+    return {
+        nodes: trees.flat().map((module) => ({
+            id: idOf(module),
+            kind: 'file',
+            label: module.label,
+            parent: crateId(crate),
+            path: module.path,
+        })),
+        edges: [...new Map(edges.map(edge => [edgeKey(edge), edge])).values()],
+    };
+};

package/dist/diff-graphs.d.ts

@@ -0,0 +1,31 @@
+import { type Graph, type GraphEdge, type GraphNode } from './graph.ts';
+import type { FilePatch, Rename } from './read-range.ts';
+type Diffed<T, KeptState> = T & {
+    readonly state: 'added' | 'removed' | KeptState;
+};
+export type GraphDiff = {
+    readonly nodes: ReadonlyArray<Diffed<GraphNode, 'modified' | 'unchanged'> & {
+        readonly renamedFrom?: string;
+        readonly formerLabel?: string;
+    }>;
+    readonly edges: ReadonlyArray<Diffed<GraphEdge, 'unchanged'>>;
+};
+type DiffGraphsOptions = {
+    readonly before: Graph;
+    readonly after: Graph;
+    readonly changedPaths: ReadonlyArray<string>;
+    readonly renames: ReadonlyArray<Rename>;
+};
+export declare const isAtOrUnder: (path: string, node: GraphNode) => boolean;
+export declare const diffGraphs: ({ before, after, changedPaths, renames, }: DiffGraphsOptions) => GraphDiff;
+export type DiffedNode = GraphDiff['nodes'][number];
+export type DiffedEdge = GraphDiff['edges'][number];
+type SplitPatchesOptions = {
+    readonly diff: GraphDiff;
+    readonly patches: ReadonlyArray<FilePatch>;
+};
+export declare const splitPatches: ({ diff, patches }: SplitPatchesOptions) => {
+    drawn: FilePatch[];
+    undrawn: FilePatch[];
+};
+export {};

package/dist/diff-graphs.js

@@ -0,0 +1,72 @@
+import { edgeKey } from './graph.js';
+const diffItems = ({ before, after, keyOf, stateOfKept, }) => {
+    const beforeKeys = new Set(before.map(keyOf));
+    const afterKeys = new Set(after.map(keyOf));
+    return [
+        ...after.map((item) => ({
+            ...item,
+            state: beforeKeys.has(keyOf(item)) ? stateOfKept(item) : 'added',
+        })),
+        ...before
+            .filter(item => !afterKeys.has(keyOf(item)))
+            .map((item) => ({ ...item, state: 'removed' })),
+    ];
+};
+export const isAtOrUnder = (path, node) => path === node.path || path.startsWith(`${node.path}/`);
+const pairNodes = ({ before, after, renames, }) => {
+    const beforeIds = new Set(before.nodes.map(node => node.id));
+    const afterIds = new Set(after.nodes.map(node => node.id));
+    const added = after.nodes.filter(node => !beforeIds.has(node.id));
+    const filesAcross = (from, to) => {
+        if (from.kind !== to.kind || from.path === '')
+            return 0;
+        if (from.path === to.path)
+            return Number.POSITIVE_INFINITY;
+        return renames.filter(rename => isAtOrUnder(rename.from, from) && isAtOrUnder(rename.to, to))
+            .length;
+    };
+    return new Map(before.nodes
+        .filter(node => !afterIds.has(node.id))
+        .flatMap(from => {
+        const [best] = added
+            .map(to => ({ to, files: filesAcross(from, to) }))
+            .filter(({ files }) => files > 0)
+            .sort((a, b) => b.files - a.files);
+        return best === undefined ? [] : [[from.id, { from, to: best.to }]];
+    }));
+};
+export const diffGraphs = ({ before, after, changedPaths, renames, }) => {
+    const isTouched = (node) => changedPaths.some(path => isAtOrUnder(path, node));
+    const pairs = pairNodes({ before, after, renames });
+    const pairedFrom = new Map([...pairs].map(([, { from, to }]) => [to.id, from]));
+    const renamedFrom = new Map(renames.map(({ from, to }) => [to, from]));
+    const idOf = (id) => pairs.get(id)?.to.id ?? id;
+    return {
+        nodes: diffItems({
+            before: before.nodes.map(node => ({ ...node, id: idOf(node.id) })),
+            after: after.nodes,
+            keyOf: node => node.id,
+            stateOfKept: node => (isTouched(node) ? 'modified' : 'unchanged'),
+        }).map(node => {
+            const former = pairedFrom.get(node.id);
+            const from = former === undefined ? renamedFrom.get(node.path) : former.path;
+            return {
+                ...node,
+                ...(from === undefined || from === node.path ? {} : { renamedFrom: from }),
+                ...(former === undefined || former.label === node.label
+                    ? {}
+                    : { formerLabel: former.label }),
+            };
+        }),
+        edges: diffItems({
+            before: before.edges.map(edge => ({ ...edge, from: idOf(edge.from), to: idOf(edge.to) })),
+            after: after.edges,
+            keyOf: edgeKey,
+            stateOfKept: () => 'unchanged',
+        }),
+    };
+};
+export const splitPatches = ({ diff, patches }) => {
+    const isDrawn = ({ path }) => diff.nodes.some(node => isAtOrUnder(path, node));
+    return { drawn: patches.filter(isDrawn), undrawn: patches.filter(patch => !isDrawn(patch)) };
+};

package/dist/graph.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A box in the review graph. `id` is the node's contract: notes are keyed by it, so a reader
+ * keeps it stable across versions. Ids are `<stack>/<word>/<name>` under the reader's stack id,
+ * e.g. `rust/crate/http-adapter`, `rust/mod/application/sign_up`, `web/module/utils`,
+ * `web/file/App.tsx`; the stack's own node is just `<stack>`. An edge is keyed `<from> -> <to>`.
+ */
+export type GraphNode = {
+    readonly id: string;
+    readonly kind: 'stack' | 'package' | 'module' | 'file';
+    readonly label: string;
+    readonly parent?: string;
+    readonly path: string;
+};
+export type GraphEdge = {
+    readonly from: string;
+    readonly to: string;
+    readonly via?: ReadonlyArray<string>;
+};
+export type Graph = {
+    readonly nodes: ReadonlyArray<GraphNode>;
+    readonly edges: ReadonlyArray<GraphEdge>;
+};
+export declare const edgeKey: (edge: GraphEdge) => string;
+export declare const stackOfIn: (nodes: ReadonlyArray<GraphNode>) => ((id: string) => string);

package/dist/graph.js

@@ -0,0 +1,9 @@
+export const edgeKey = (edge) => JSON.stringify([edge.from, edge.to]);
+export const stackOfIn = (nodes) => {
+    const parents = new Map(nodes.map(node => [node.id, node.parent]));
+    const stackOf = (id) => {
+        const parent = parents.get(id);
+        return parent === undefined ? id : stackOf(parent);
+    };
+    return stackOf;
+};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { Graph, GraphEdge, GraphNode } from './graph.ts';
+export type { DanglingCall, LinkedStack, Linker, LinkOptions, Links } from './linker.ts';
+export type { Checkout, OpenedCheckout, Reader } from './reader.ts';
+export type { ReadTest, TestLabel } from './test-statements.ts';

package/dist/index.js

@@ -0,0 +1 @@
+export {};

package/dist/linker.d.ts

@@ -0,0 +1,32 @@
+import type { LinkerName, ReaderName } from './config.ts';
+import type { GraphEdge, GraphNode } from './graph.ts';
+export type DanglingCall = {
+    readonly from: string;
+    readonly path: string;
+};
+export type LinkedStack = {
+    readonly stack: string;
+    readonly nodes: ReadonlyArray<GraphNode>;
+};
+export type Links = {
+    readonly edges: ReadonlyArray<GraphEdge>;
+    readonly dangling: ReadonlyArray<DanglingCall>;
+};
+export type LinkOptions = {
+    readonly directory: string;
+    readonly from: ReadonlyArray<LinkedStack>;
+    readonly to: ReadonlyArray<LinkedStack>;
+};
+/**
+ * Draws edges across stacks. `link` is given the checkout's directory and every stack the config
+ * keeps of the `from` reader and of the `to` reader, or those the config's `linkers` entry names,
+ * each with its nodes, whose paths are relative to the checkout; a skipped reader's stacks come
+ * with none. It returns edges between those nodes' ids, and the calls from a `from` node that
+ * reach nothing in the `to` stacks.
+ */
+export interface Linker {
+    readonly name: LinkerName;
+    readonly from: ReaderName;
+    readonly to: ReaderName;
+    readonly link: (options: LinkOptions) => Promise<Links>;
+}

package/dist/linker.js

@@ -0,0 +1 @@
+export {};

package/dist/linkers/fetch-axum.d.ts

@@ -0,0 +1,2 @@
+import type { Linker } from '../linker.ts';
+export declare const fetchAxumLinker: Linker;

package/dist/linkers/fetch-axum.js

@@ -0,0 +1,38 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { apiRoutes, callGraph, webCalls } from '../api-paths.js';
+const TABLE_HEADER = /^\[([^\]]*)\]/;
+const DEPENDENCY_TABLE = /^(target\..+\.)?dependencies$/;
+const AXUM_TABLE = /^(target\..+\.)?dependencies\.axum$/;
+const AXUM_KEY = /^\s*axum\s*[=.]/;
+const declaresAxum = (manifest) => manifest.split('\n').reduce(({ table, found }, line) => {
+    const header = TABLE_HEADER.exec(line)?.[1];
+    if (header !== undefined)
+        return { table: header, found: found || AXUM_TABLE.test(header) };
+    return { table, found: found || (DEPENDENCY_TABLE.test(table) && AXUM_KEY.test(line)) };
+}, { table: '', found: false }).found;
+const dependsOnAxum = async (directory, crate) => declaresAxum(await readFile(join(directory, crate.path, 'Cargo.toml'), 'utf8'));
+export const fetchAxumLinker = {
+    name: 'fetch-axum',
+    from: 'typescript',
+    to: 'rust',
+    link: async ({ directory, from, to }) => {
+        const files = from.flatMap(({ nodes }) => nodes.filter(({ kind }) => kind === 'file'));
+        const packages = to.flatMap(({ nodes }) => nodes.filter(({ kind }) => kind === 'package'));
+        const axum = await Promise.all(packages.map(crate => dependsOnAxum(directory, crate)));
+        const crates = packages.filter((_, index) => axum[index]);
+        if (crates.length === 0)
+            return { edges: [], dangling: [] };
+        const calls = webCalls(await Promise.all(files.map(async ({ id, path }) => ({
+            from: id,
+            text: await readFile(join(directory, path), 'utf8'),
+        }))));
+        const crateIds = new Set(crates.map(({ id }) => id));
+        const modules = to.flatMap(({ nodes }) => nodes.flatMap(({ parent, path }) => parent !== undefined && crateIds.has(parent) ? [{ crate: parent, path }] : []));
+        const routes = (await Promise.all(modules.map(async ({ crate, path }) => apiRoutes(await readFile(join(directory, path), 'utf8')).map(route => ({
+            to: crate,
+            path: route,
+        }))))).flat();
+        return callGraph({ calls, routes });
+    },
+};

package/dist/notes.d.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import type { GraphDiff } from './diff-graphs.ts';
+declare const ReviewNotesSchema: z.ZodReadonly<z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    version: z.ZodLiteral<1>;
+    summary: z.ZodReadonly<z.ZodArray<z.ZodReadonly<z.ZodObject<{
+        text: z.ZodString;
+        target: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>>;
+    tests: z.ZodString;
+    notes: z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodReadonly<z.ZodObject<{
+        text: z.ZodString;
+        flag: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>>;
+}, z.core.$strict>>;
+export type ReviewNotes = z.infer<typeof ReviewNotesSchema>;
+export type Note = ReviewNotes['notes'][string];
+export declare const notesJsonSchema: () => z.core.ZodStandardJSONSchemaPayload<z.ZodReadonly<z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    version: z.ZodLiteral<1>;
+    summary: z.ZodReadonly<z.ZodArray<z.ZodReadonly<z.ZodObject<{
+        text: z.ZodString;
+        target: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>>;
+    tests: z.ZodString;
+    notes: z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodReadonly<z.ZodObject<{
+        text: z.ZodString;
+        flag: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>>;
+}, z.core.$strict>>>;
+export declare const readNotes: (file: string) => Promise<ReviewNotes>;
+type NotesProblemsOptions = {
+    readonly diff: GraphDiff;
+    readonly notes: ReviewNotes;
+};
+export declare const notesProblems: ({ diff, notes }: NotesProblemsOptions) => ReadonlyArray<string>;
+export {};

package/dist/notes.js

@@ -0,0 +1,82 @@
+import { readFile } from 'node:fs/promises';
+import { z } from 'zod';
+import { edgeId, visibleDiff, visibleNodeOf, visibleNotes } from './viewer/visible-diff.js';
+const notesVersion = 1;
+const ReviewNotesSchema = z
+    .strictObject({
+    $schema: z.string().optional(),
+    version: z.literal(notesVersion).describe('The notes format this file is written in'),
+    summary: z
+        .array(z
+        .strictObject({
+        text: z.string(),
+        target: z.string().optional().describe('The id of the node or edge it is about'),
+    })
+        .readonly())
+        .readonly()
+        .describe("A few items on the change's shape as a whole"),
+    tests: z.string().describe('What the tests pin, and what the change leaves unpinned'),
+    notes: z
+        .record(z.string(), z
+        .strictObject({
+        text: z.string(),
+        flag: z.string().optional().describe('A short label for a structural concern'),
+    })
+        .readonly())
+        .readonly()
+        .describe('Notes by node id, or by `<from> -> <to>` for an edge'),
+})
+    .readonly();
+export const notesJsonSchema = () => z.toJSONSchema(ReviewNotesSchema, {
+    io: 'input',
+    override: ({ jsonSchema }) => {
+        delete jsonSchema.readOnly;
+    },
+});
+const VersionedSchema = z.object({ version: z.unknown() });
+const invalidNotes = (file, reason) => new Error(`Invalid notes file ${file}: ${reason}`);
+const versionProblem = (version) => `${version === undefined ? 'no "version"' : `version ${JSON.stringify(version)} is unknown`}; this visual-review reads version ${notesVersion}`;
+const contentsOf = async (file) => {
+    try {
+        return JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch (error) {
+        throw invalidNotes(file, error);
+    }
+};
+export const readNotes = async (file) => {
+    const contents = await contentsOf(file);
+    const version = VersionedSchema.safeParse(contents).data?.version;
+    if (version !== notesVersion) {
+        throw invalidNotes(file, versionProblem(version));
+    }
+    const notes = ReviewNotesSchema.safeParse(contents);
+    if (!notes.success) {
+        throw invalidNotes(file, notes.error);
+    }
+    return notes.data;
+};
+export const notesProblems = ({ diff, notes }) => {
+    const collapsedOf = visibleNodeOf({ diff, expanded: new Set() });
+    const endsOf = (id) => [...new Set([id, collapsedOf(id)])];
+    const known = new Set([
+        ...diff.nodes.filter(node => node.kind !== 'stack').map(node => node.id),
+        ...diff.edges.flatMap(edge => endsOf(edge.from).flatMap(from => endsOf(edge.to)
+            .filter(to => to !== from)
+            .map(to => edgeId({ from, to })))),
+    ]);
+    const collapsed = visibleDiff({ diff, expanded: new Set() });
+    const shown = visibleNotes({ diff, expanded: new Set(), notes: notes.notes });
+    const touched = [
+        ...collapsed.nodes
+            .filter(node => node.kind !== 'stack' && node.state !== 'unchanged')
+            .map(node => node.id),
+        ...collapsed.edges.filter(edge => edge.state !== 'unchanged').map(edgeId),
+    ];
+    return [
+        ...[...Object.keys(notes.notes), ...notes.summary.flatMap(item => item.target ?? [])]
+            .filter(id => !known.has(id))
+            .map(id => `unknown id ${id}`),
+        ...touched.filter(id => shown[id] === undefined).map(id => `no note on ${id}`),
+    ];
+};

package/dist/notes.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "type": "number",
+      "const": 1,
+      "description": "The notes format this file is written in"
+    },
+    "summary": {
+      "description": "A few items on the change's shape as a whole",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "text": {
+            "type": "string"
+          },
+          "target": {
+            "description": "The id of the node or edge it is about",
+            "type": "string"
+          }
+        },
+        "required": [
+          "text"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "tests": {
+      "type": "string",
+      "description": "What the tests pin, and what the change leaves unpinned"
+    },
+    "notes": {
+      "description": "Notes by node id, or by `<from> -> <to>` for an edge",
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "text": {
+            "type": "string"
+          },
+          "flag": {
+            "description": "A short label for a structural concern",
+            "type": "string"
+          }
+        },
+        "required": [
+          "text"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": [
+    "version",
+    "summary",
+    "tests",
+    "notes"
+  ],
+  "additionalProperties": false
+}

package/dist/on-path.d.ts

@@ -0,0 +1 @@
+export declare const onPath: (command: string) => boolean;

package/dist/on-path.js

@@ -0,0 +1,16 @@
+import { accessSync, constants, statSync } from 'node:fs';
+import { delimiter, isAbsolute, join } from 'node:path';
+const runs = (file) => {
+    try {
+        accessSync(file, constants.X_OK);
+        return statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+export const onPath = (command) => {
+    const path = process.env['PATH'];
+    return (path === undefined ||
+        path.split(delimiter).some(directory => isAbsolute(directory) && runs(join(directory, command))));
+};

package/dist/prune-reviews.d.ts

@@ -0,0 +1,6 @@
+type PruneReviewsOptions = {
+    readonly directory: string;
+    readonly keep: number;
+};
+export declare const pruneReviews: ({ directory, keep }: PruneReviewsOptions) => Promise<void>;
+export {};

package/dist/prune-reviews.js

@@ -0,0 +1,12 @@
+import { readdir, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+export const pruneReviews = async ({ directory, keep }) => {
+    const pages = await Promise.all((await readdir(directory))
+        .filter(file => file.endsWith('.html'))
+        .map(async (file) => ({
+        name: file.slice(0, -'.html'.length),
+        writtenAt: (await stat(join(directory, file))).mtimeMs,
+    })));
+    const older = pages.toSorted((one, other) => other.writtenAt - one.writtenAt).slice(keep);
+    await Promise.all(older.flatMap(({ name }) => ['html', 'json', 'notes.json'].map(extension => rm(join(directory, `${name}.${extension}`), { force: true }))));
+};

package/dist/pull-request.d.ts

@@ -0,0 +1,17 @@
+export type PullRequest = {
+    readonly number: number;
+    readonly title: string;
+    readonly url: string;
+};
+type PullRequestOptions = {
+    readonly repo: string;
+    readonly number: number;
+};
+export declare const readPullRequest: ({ repo, number }: PullRequestOptions) => Promise<{
+    from: string;
+    to: string;
+    number: number;
+    title: string;
+    url: string;
+}>;
+export {};

package/dist/pull-request.js

@@ -0,0 +1,41 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { z } from 'zod';
+const run = promisify(execFile);
+const PullRequestViewSchema = z.object({
+    baseRefName: z.string(),
+    mergeCommit: z.object({ oid: z.string() }).nullable(),
+    title: z.string(),
+    url: z.string(),
+});
+const namesRepository = (remoteUrl, repository) => {
+    const path = remoteUrl.replace(/\.git$/, '');
+    return path.endsWith(`/${repository}`) || path.endsWith(`:${repository}`);
+};
+export const readPullRequest = async ({ repo, number }) => {
+    const git = async (...args) => (await run('git', ['-C', repo, ...args])).stdout.trim();
+    const view = await run('gh', ['pr', 'view', String(number), '--json', 'baseRefName,mergeCommit,title,url'], { cwd: repo }).catch((error) => {
+        throw new Error(`Could not read PR #${number}: ${error.stderr.trim()}`);
+    });
+    const { baseRefName, mergeCommit, title, url } = PullRequestViewSchema.parse(JSON.parse(view.stdout));
+    const repository = new URL(url).pathname.split('/').slice(1, 3).join('/');
+    const remoteUrls = await git('config', '--get-regexp', '^remote\\..*\\.url$').catch(() => '');
+    const remote = remoteUrls.split('\n').flatMap(line => {
+        const [key = '', remoteUrl = ''] = line.split(' ');
+        return namesRepository(remoteUrl, repository)
+            ? [key.slice('remote.'.length, -'.url'.length)]
+            : [];
+    })[0];
+    if (remote === undefined)
+        throw new Error(`No git remote points at ${repository}`);
+    const fetched = async (ref) => {
+        await git('fetch', '--quiet', remote, ref).catch((error) => {
+            throw new Error(`Could not fetch PR #${number} from ${remote}: ${error.stderr.trim()}`);
+        });
+        return git('rev-parse', 'FETCH_HEAD');
+    };
+    const to = await fetched(`refs/pull/${number}/head`);
+    const baseTip = await fetched(`refs/heads/${baseRefName}`);
+    const base = mergeCommit === null ? baseTip : `${mergeCommit.oid}^1`;
+    return { from: await git('merge-base', base, to), to, number, title, url };
+};

package/dist/read-range.d.ts

@@ -0,0 +1,29 @@
+import { type Graph } from './graph.ts';
+import type { DanglingCall } from './linker.ts';
+import type { Skipped } from './skipped.ts';
+import { type TestFile } from './test-statements.ts';
+export type FilePatch = {
+    readonly path: string;
+    readonly patch: string;
+};
+export type Rename = {
+    readonly from: string;
+    readonly to: string;
+};
+export type RangeReading = {
+    readonly before: Graph;
+    readonly after: Graph;
+    readonly changedPaths: ReadonlyArray<string>;
+    readonly renames: ReadonlyArray<Rename>;
+    readonly patches: ReadonlyArray<FilePatch>;
+    readonly tests: ReadonlyArray<TestFile>;
+    readonly danglingCalls: ReadonlyArray<DanglingCall>;
+    readonly skipped: ReadonlyArray<Skipped>;
+};
+type ReadRangeOptions = {
+    readonly repo: string;
+    readonly from: string;
+    readonly to: string;
+};
+export declare const readRange: ({ repo, from, to }: ReadRangeOptions) => Promise<RangeReading>;
+export {};