@reviewflow/sdk 0.0.0-stage → 6.22.0

package/src/diff/types.ts

@@ -0,0 +1,141 @@
+/**
+ * `show` is git's plain diff. `hide` is `git diff -w`, GitHub's "Hide
+ * whitespace": a line whose only change is whitespace is not a change.
+ */
+export type DiffWhitespace = "hide" | "show";
+
+export const isDiffWhitespace = (value: unknown): value is DiffWhitespace =>
+  value === "hide" || value === "show";
+
+/**
+ * Where a diff read is at, for a caller that shows progress: the objects are
+ * being fetched into the checkout, or the patch is being computed.
+ */
+export type DiffStep = "diffing" | "fetching";
+
+/**
+ * `whitespace`: every change of the file is whitespace, and whitespace is
+ * hidden. Listed rather than dropped, since `git diff -w` names no such file
+ * and the reader would not know it changed.
+ */
+export type DiffOmittedReason = "binary" | "budget" | "tooLarge" | "whitespace";
+
+export interface DiffOmittedFile {
+  path: string;
+  reason: DiffOmittedReason;
+}
+
+/**
+ * The files of one package: the nearest directory above them holding a
+ * manifest (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`,
+ * `Gemfile`…), the repo root excepted. A file in no package goes under
+ * its first directory, and one at the root under `""`.
+ */
+export interface DiffGroup {
+  /** relative to the checkout; `""` is the root */
+  name: string;
+  /** as the patch names them, after any rename */
+  paths: string[];
+}
+
+export interface DiffReadingFile {
+  /** as the patch names it, after any rename */
+  path: string;
+  /** no other changed file of its package imports it, and it imports some */
+  entry: boolean;
+  /**
+   * a non-test TypeScript file no other changed file of its package imports:
+   * the entry points, and the files that import nothing changed either
+   */
+  root: boolean;
+  /** the tests and stories of this file, read below it */
+  attached: string[];
+}
+
+/**
+ * One package's changed files in reading order: from each entry point down
+ * through what it imports, depth first; then the files that are not
+ * TypeScript, in patch order; then the tests and stories covering no changed
+ * file.
+ */
+export interface DiffReadingGroup {
+  /** the package, as `DiffGroup.name` */
+  name: string;
+  /** every changed file of the package once, an attached one under its subject only */
+  files: DiffReadingFile[];
+}
+
+/**
+ * `GET /api/prs/reading-order?repo=<owner/repo>&number=<n>&head=<sha>&base=<sha>`
+ * — the files of the same range as `/api/prs/diff`, ordered for reading:
+ * packages from the one depending on the others down, files from the entry
+ * points down. Read from the registered checkout at `head` (relative
+ * TypeScript imports only); answered with a `DiffRefusal` without one.
+ */
+export interface DiffReadingOrderResponse {
+  groups: DiffReadingGroup[];
+}
+
+/**
+ * `GET /api/prs/diff?repo=<owner/repo>&number=<n>&head=<sha>&base=<sha>&whitespace=<hide|show>`
+ * — the pull request's changes: head against its merge base with the base tip,
+ * which is what GitHub shows. The two shas are the detail's, so the diff is of
+ * the pull request the screen shows.
+ *
+ * Read from **local git** when the repository is registered — the commits are
+ * fetched by sha into its checkout when missing, writing no ref — with size
+ * bounds (binary, too large and over-budget files are left out). From **GitHub's API** otherwise, or when git cannot: a
+ * repository with no configured checkout, a fetch refused. GitHub refuses a diff past
+ * 300 files or 20,000 lines, which git does not.
+ */
+export interface PullRequestDiffResponse {
+  source: "git" | "github";
+  /** why git was not the source, verbatim; null when it was, or no checkout exists */
+  fallbackReason: string | null;
+  /**
+   * What the patch did with whitespace, which is not always what was asked:
+   * GitHub's compare endpoint cannot hide it, so its answer is always `show`.
+   */
+  whitespace: DiffWhitespace;
+  /** a unified diff, `a/` and `b/` prefixes, the omitted files left out */
+  patch: string;
+  /**
+   * The commits the patch's two sides are read at (the merge base and the
+   * head), for `prFile`; null from GitHub, whose files are not read, so the
+   * unchanged lines stay folded.
+   */
+  sides: { old: string; new: string } | null;
+  /** binary, too large or over budget: left out of `patch` (git only) */
+  omitted: DiffOmittedFile[];
+  /**
+   * Every file in `patch`, by package when the repository is registered (its
+   * checkout says where the manifests are), by first directory otherwise.
+   */
+  groups: DiffGroup[];
+}
+
+/**
+ * `GET /api/prs/file?repo=<owner/repo>&number=<n>&sha=<sha>&path=<path>` — one
+ * file of the registered checkout at a commit, so the diff can unfold the lines
+ * the patch left out. Local git only; a 400 without a checkout.
+ */
+export interface PullRequestFileContentsResponse {
+  contents: string;
+}
+
+/**
+ * Why a diff was not read at all: the repository has no checkout the reader
+ * may use. Not an error: the user is shown `configPath` and the exact line to
+ * add to it.
+ *
+ * - `notConfigured`: `ownerRepo` is not in the config file.
+ * - `invalidPath`: it is, but the path is not a checkout of that repository
+ *   (`detail` says what was found).
+ */
+export interface DiffRefusal {
+  reason: "invalidPath" | "notConfigured";
+  ownerRepo: string;
+  /** the file to edit */
+  configPath: string;
+  detail: string;
+}

package/src/files/editableFile.ts

@@ -0,0 +1,163 @@
+import { randomBytes } from "node:crypto";
+import {
+  chmodSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+export interface EditableFile {
+  /** the text on disk; empty when the file does not exist */
+  source: string;
+  exists: boolean;
+}
+
+/**
+ * What a caller's `validate` answers: `{ error }` refuses the save, `{ warnings }`
+ * lets it through and travels back with the saved file.
+ */
+export type FileValidation = { error: string } | { warnings: string[] };
+
+export type ValidateEditableFile = (
+  source: string,
+) => FileValidation | Promise<FileValidation>;
+
+export interface SaveEditableFileParams {
+  path: string;
+  source: string;
+  /**
+   * What the editor opened on. `undefined` skips the check. A string is
+   * refused when the file has other text now, a missing file counting as the
+   * empty text so an editor opened on a file that did not exist can save it.
+   * `null` means the file must not exist yet (a creation).
+   */
+  expectedSource?: string | null | undefined;
+  validate: ValidateEditableFile;
+  /**
+   * End a non-empty source with a newline before it is validated and written.
+   * Default true: a text file ends with one, and the editor then reopens on
+   * the text that was saved.
+   */
+  trailingNewline?: boolean;
+}
+
+export type SaveEditableFileResult =
+  /** nothing was written; `source` is what the disk holds now, for the UI to offer a reload */
+  | { status: "conflict"; source: string; exists: boolean }
+  /** nothing was written */
+  | { status: "invalid"; error: string }
+  /** `source` is what is on disk now, which may differ from the input by its final newline */
+  | { status: "saved"; source: string; warnings: string[] };
+
+const isMissing = (error: unknown): boolean =>
+  (error as NodeJS.ErrnoException).code === "ENOENT";
+
+const readCurrent = (path: string): string | null => {
+  try {
+    return readFileSync(path, "utf8");
+  } catch (error) {
+    if (isMissing(error)) return null;
+    throw error;
+  }
+};
+
+/**
+ * The file as it is on disk right now. A missing file is a state, not an
+ * error: `{ source: "", exists: false }`. Always read from disk, never from a
+ * cache: a file edited in place by another tool must not make the next save
+ * refuse because an editor opened on a stale copy.
+ */
+export const readEditableFile = (path: string): EditableFile => {
+  const source = readCurrent(path);
+  return source === null
+    ? { source: "", exists: false }
+    : { source, exists: true };
+};
+
+const validationOf = async (
+  validate: ValidateEditableFile,
+  source: string,
+): Promise<FileValidation> => {
+  try {
+    return await validate(source);
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) };
+  }
+};
+
+/**
+ * Writes one text file. Every refusal comes before the write:
+ *
+ * - **A source `validate` refuses is not written**, whatever is on disk: only
+ *   what is about to be written is checked, so a broken file can be fixed.
+ * - **A file that changed since the editor opened it is refused**, with the
+ *   text now on disk. The same file is edited by hand or by another tool, and
+ *   the last writer winning would lose the other edit without either side
+ *   seeing it.
+ *
+ * Written beside the target and renamed over it, so a crash leaves the previous
+ * file rather than a truncated one; missing parent directories are created and
+ * the mode of an existing file is kept. A symlink is written through to its
+ * target: renaming over the link would replace it with a plain file and
+ * quietly detach it from the repository that holds the real one.
+ */
+export const saveEditableFile = async ({
+  path,
+  source,
+  expectedSource,
+  validate,
+  trailingNewline = true,
+}: SaveEditableFileParams): Promise<SaveEditableFileResult> => {
+  const text =
+    trailingNewline && source !== "" && !source.endsWith("\n")
+      ? `${source}\n`
+      : source;
+
+  const validation = await validationOf(validate, text);
+  if ("error" in validation) {
+    return { status: "invalid", error: validation.error };
+  }
+
+  const current = readCurrent(path);
+  if (expectedSource !== undefined) {
+    const conflicts =
+      expectedSource === null
+        ? current !== null
+        : (current ?? "") !== expectedSource;
+    if (conflicts) {
+      return {
+        status: "conflict",
+        source: current ?? "",
+        exists: current !== null,
+      };
+    }
+  }
+
+  mkdirSync(dirname(path), { recursive: true });
+  const target = current === null ? path : realpathSync(path);
+  const temporary = join(
+    dirname(target),
+    `.${basename(target)}.${String(process.pid)}.${randomBytes(4).toString("hex")}.tmp`,
+  );
+  try {
+    writeFileSync(temporary, text);
+    // the permission bits of the existing file, without its file-type bits
+    // oxlint-disable-next-line no-bitwise
+    if (current !== null) chmodSync(temporary, statSync(target).mode & 0o7777);
+    renameSync(temporary, target);
+  } catch (error) {
+    try {
+      unlinkSync(temporary);
+    } catch {
+      // the temporary file was never created
+    }
+    throw error;
+  }
+
+  return { status: "saved", source: text, warnings: validation.warnings };
+};

package/src/files.ts

@@ -0,0 +1,13 @@
+/**
+ * Node-only surface: a text file edited in place, read from disk and saved
+ * atomically behind a validation and a changed-since-opened check. Import it
+ * as `@reviewflow/sdk/files`; the root entry stays browser-safe.
+ */
+export { readEditableFile, saveEditableFile } from "./files/editableFile.ts";
+export type {
+  EditableFile,
+  FileValidation,
+  SaveEditableFileParams,
+  SaveEditableFileResult,
+  ValidateEditableFile,
+} from "./files/editableFile.ts";

package/src/git/groupDiffPaths.ts

@@ -0,0 +1,134 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { DiffGroup } from "../diff/types.ts";
+import { git } from "./run.ts";
+
+/**
+ * A monorepo's changes read by package: `apps/resident` and `.claude` rather
+ * than one flat list. The package is the nearest directory holding a manifest
+ * of any ecosystem — what every workspace tool agrees on — rather than one
+ * matched against each tool's workspace globs, which would mean parsing as
+ * many formats to answer the same question. The root's own manifest does not
+ * count, or every file would be in one group.
+ *
+ * Fixed names only: a manifest named after its package (`*.gemspec`,
+ * `*.csproj`) would need a directory listing per level instead of a stat.
+ *
+ * The caller says where the manifests are, as an `isPackage(directory)`
+ * predicate: `packagesAtTree` reads them from a commit's tree (a pull request's
+ * head, whatever the checkout has out), `packagesOnDisk` from a working tree.
+ * A file deleted along with its whole package falls back to its first
+ * directory: there is no manifest left to find.
+ */
+
+const manifestNames = [
+  // javascript
+  "package.json",
+  // python
+  "pyproject.toml",
+  "setup.py",
+  // ruby
+  "Gemfile",
+  // rust
+  "Cargo.toml",
+  // go
+  "go.mod",
+  // php
+  "composer.json",
+  // jvm
+  "pom.xml",
+  "build.gradle",
+  "build.gradle.kts",
+  // elixir
+  "mix.exs",
+  // dart
+  "pubspec.yaml",
+  // swift
+  "Package.swift",
+];
+
+const manifests = new Set(manifestNames);
+
+export const isManifestPath = (path: string): boolean =>
+  manifests.has(path.slice(path.lastIndexOf("/") + 1));
+
+export const packageOf = (
+  path: string,
+  isPackage: (directory: string) => boolean,
+): string => {
+  const directories = path.split("/").slice(0, -1);
+  for (let depth = directories.length; depth >= 1; depth--) {
+    const directory = directories.slice(0, depth).join("/");
+    if (isPackage(directory)) return directory;
+  }
+  return directories[0] ?? "";
+};
+
+export type IsPackage = (directory: string) => boolean;
+
+/** No manifest known: every file goes under its first directory. */
+export const noPackages: IsPackage = () => false;
+
+/** Every file at `sha`. The commit must be in the checkout. */
+export const listTree = async (
+  checkout: string,
+  sha: string,
+): Promise<string[]> => {
+  const listing = await git(
+    checkout,
+    ["ls-tree", "-r", "--name-only", "-z", sha],
+    {
+      maxBuffer: 256 * 1024 * 1024,
+    },
+  );
+  return listing.split("\0").filter((path) => path !== "");
+};
+
+/** The directories holding a manifest among `paths`. The root does not count. */
+export const packagesInListing = (paths: readonly string[]): IsPackage => {
+  const directories = new Set<string>();
+  for (const path of paths) {
+    const slash = path.lastIndexOf("/");
+    if (slash === -1) continue;
+    if (isManifestPath(path)) directories.add(path.slice(0, slash));
+  }
+  return (directory) => directories.has(directory);
+};
+
+/** The directories holding a manifest at `sha`, from one `git ls-tree`. */
+export const packagesAtTree = async (
+  checkout: string,
+  sha: string,
+): Promise<IsPackage> => packagesInListing(await listTree(checkout, sha));
+
+/** For a caller whose files are in a working tree, uncommitted ones included. */
+export const packagesOnDisk = (worktree: string): IsPackage => {
+  const known = new Map<string, boolean>();
+  return (directory) => {
+    const cached = known.get(directory);
+    if (cached !== undefined) return cached;
+    const found = manifestNames.some((manifest) =>
+      existsSync(join(worktree, directory, manifest)),
+    );
+    known.set(directory, found);
+    return found;
+  };
+};
+
+export const groupDiffPaths = (
+  isPackage: IsPackage,
+  paths: string[],
+): DiffGroup[] => {
+  const groups = new Map<string, string[]>();
+  for (const path of paths) {
+    const name = packageOf(path, isPackage);
+    const group = groups.get(name);
+    if (group === undefined) groups.set(name, [path]);
+    else group.push(path);
+  }
+  // The root first: its files (a lockfile, the root manifest, a README) are
+  // what the rest of the change is read against.
+  return [...groups]
+    .toSorted(([left], [right]) => Number(left !== "") - Number(right !== ""))
+    .map(([name, groupPaths]) => ({ name, paths: groupPaths }));
+};

package/src/git/manifests.ts

@@ -0,0 +1,96 @@
+import { resolveRelative, resolveSubpathImport } from "../diff/readingOrder.ts";
+import { catFiles } from "./run.ts";
+
+export type Manifest = Record<string, unknown>;
+
+/** The `package.json` holding `path`, the root's included: whose `imports` apply. */
+export const manifestDirectoryOf = (
+  path: string,
+  manifests: ReadonlyMap<string, Manifest>,
+): string | null => {
+  const directories = path.split("/").slice(0, -1);
+  for (let depth = directories.length; depth >= 0; depth--) {
+    const directory = directories.slice(0, depth).join("/");
+    if (manifests.has(directory)) return directory;
+  }
+  return null;
+};
+
+export interface ResolveLocalParams {
+  /** the file holding the specifier */
+  from: string;
+  specifier: string;
+  exists: (path: string) => boolean;
+  manifests: ReadonlyMap<string, Manifest>;
+}
+
+/**
+ * The file a relative or `#` (`imports` of the nearest `package.json`)
+ * specifier names, null when it names none or is neither.
+ */
+export const resolveLocalSpecifier = ({
+  from,
+  specifier,
+  exists,
+  manifests,
+}: ResolveLocalParams): string | null => {
+  if (!specifier.startsWith("#")) {
+    return resolveRelative(from, specifier, exists);
+  }
+  const directory = manifestDirectoryOf(from, manifests);
+  if (directory === null) return null;
+  return resolveSubpathImport(
+    specifier,
+    { directory, imports: manifests.get(directory)?.imports },
+    exists,
+  );
+};
+
+const dependencyFields = [
+  "dependencies",
+  "devDependencies",
+  "peerDependencies",
+] as const;
+
+/** The packages a manifest depends on, of any kind. */
+export const dependencyNamesOf = (manifest: Manifest): string[] =>
+  dependencyFields.flatMap((field) => {
+    const dependencies = manifest[field];
+    return typeof dependencies === "object" && dependencies !== null
+      ? Object.keys(dependencies)
+      : [];
+  });
+
+const parseManifest = (source: string): Manifest | null => {
+  try {
+    const parsed: unknown = JSON.parse(source);
+    return typeof parsed === "object" && parsed !== null
+      ? (parsed as Manifest)
+      : null;
+  } catch {
+    return null;
+  }
+};
+
+const directoryOfManifest = (path: string): string =>
+  path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : "";
+
+/** Every `package.json` at `head`, by directory; one that does not parse is left out. */
+export const readManifests = async (
+  checkout: string,
+  head: string,
+  tree: readonly string[],
+): Promise<Map<string, Manifest>> => {
+  const manifestPaths = tree.filter(
+    (path) =>
+      (path === "package.json" || path.endsWith("/package.json")) &&
+      !path.split("/").includes("node_modules"),
+  );
+  const contents = await catFiles(checkout, head, manifestPaths);
+  const manifests = new Map<string, Manifest>();
+  for (const [path, source] of contents) {
+    const manifest = parseManifest(source);
+    if (manifest !== null) manifests.set(directoryOfManifest(path), manifest);
+  }
+  return manifests;
+};