@reviewflow/sdk 0.0.0-stage → 6.22.0

package/src/diff/diffPaths.ts

@@ -0,0 +1,78 @@
+const cEscapes: Record<string, number> = {
+  a: 7,
+  b: 8,
+  f: 12,
+  n: 10,
+  r: 13,
+  t: 9,
+  v: 11,
+  '"': 34,
+  "\\": 92,
+};
+
+/** git quotes a name holding a quote, a backslash or a control character C-style, bytes in octal */
+const unquoteGitPath = (quoted: string): string => {
+  const bytes: number[] = [];
+  const encoder = new TextEncoder();
+  for (let index = 1; index < quoted.length - 1; index++) {
+    const char = quoted[index]!;
+    if (char !== "\\") {
+      bytes.push(...encoder.encode(char));
+      continue;
+    }
+    const next = quoted[index + 1] ?? "";
+    const octal = /^[0-7]{3}/.exec(quoted.slice(index + 1));
+    if (octal) {
+      bytes.push(Number.parseInt(octal[0], 8));
+      index += 3;
+    } else {
+      bytes.push(cEscapes[next] ?? next.codePointAt(0) ?? 0);
+      index += 1;
+    }
+  }
+  return new TextDecoder().decode(new Uint8Array(bytes));
+};
+
+/**
+ * A `---`/`+++` name: git ends one holding a space with a tab, and quotes one
+ * holding special characters; `prefix` is `a/` or `b/`.
+ */
+const unquoted = (name: string): string =>
+  name.length > 1 && name.startsWith('"') && name.endsWith('"')
+    ? unquoteGitPath(name)
+    : name;
+
+const headerName = (raw: string, prefix: string): string | null => {
+  const name = unquoted(raw.endsWith("\t") ? raw.slice(0, -1) : raw);
+  return name.startsWith(prefix) ? name.slice(prefix.length) : null;
+};
+
+/**
+ * The file a block of a unified diff names after the change: `+++ b/…`, or
+ * `--- a/…` for a deletion, or the header's second half for a binary file or a
+ * pure rename, which carry no `+++` line.
+ */
+const pathOfBlock = (block: string): string | null => {
+  const added = /^\+\+\+ (.*)$/m.exec(block)?.[1];
+  const addedName = added === undefined ? null : headerName(added, "b/");
+  if (addedName !== null) return addedName;
+  const removed = /^--- (.*)$/m.exec(block)?.[1];
+  const removedName = removed === undefined ? null : headerName(removed, "a/");
+  if (removedName !== null) return removedName;
+  const renamed = /^rename to (.*)$/m.exec(block)?.[1];
+  if (renamed !== undefined) return unquoted(renamed);
+  const header = block.split("\n", 1)[0] ?? "";
+  const quotedSeparator = header.lastIndexOf(' "b/');
+  if (quotedSeparator !== -1) {
+    return headerName(header.slice(quotedSeparator + 1), "b/");
+  }
+  const separator = header.lastIndexOf(" b/");
+  return separator === -1 ? null : header.slice(separator + 3);
+};
+
+export const diffPaths = (patch: string): string[] =>
+  patch
+    .split(/^diff --git /m)
+    .slice(1)
+    .map(pathOfBlock)
+    .filter((path) => path !== null);

package/src/diff/impacts.ts

@@ -0,0 +1,47 @@
+export interface DiffImporter {
+  path: string;
+  /** `isAttachablePath`: a test, a story, a fixture */
+  test: boolean;
+}
+
+export interface DiffExportImpact {
+  name: string;
+  /** exported at the merge base, not at head */
+  removed: boolean;
+  importers: DiffImporter[];
+}
+
+export interface DiffFileImpacts {
+  path: string;
+  /** the touched exports used outside the diff only */
+  exports: DiffExportImpact[];
+}
+
+/**
+ * `GET /api/prs/impacts?repo=<owner/repo>&number=<n>&head=<sha>&base=<sha>`
+ * — for the range `/api/prs/diff` reads, the exports the change touches and
+ * the files outside the diff that use them, across the workspace packages.
+ * Read from the registered checkout at `head`; answered with a `DiffRefusal`
+ * without one. `tooLarge`: nothing is analyzed, because the tree is past the
+ * file budget (`reason: "files"`, which a retry does not change) or the parse
+ * time budget (`reason: "time"`: what was parsed stays cached server side, so a
+ * retry goes further).
+ */
+export type DiffImpactsResponse =
+  | {
+      tooLarge: false;
+      files: DiffFileImpacts[];
+      /** changed files not analyzed: not TypeScript, or deleted */
+      notAnalyzed: string[];
+      /**
+       * packages holding imports that could hide a user of a changed file: a
+       * path alias in a package holding a changed TypeScript file (a bare
+       * specifier that is no workspace package, no node built-in and no
+       * dependency of the importing package), or a workspace package specifier resolving to no file (its `exports`
+       * pointing at a build output) whose target package holds one. A relative
+       * or `#` specifier naming no file is never one: every changed file exists
+       * at `head`.
+       */
+      unresolvedIn: string[];
+    }
+  | { tooLarge: true; reason: "files" | "time" };

package/src/diff/readingOrder.ts

@@ -0,0 +1,428 @@
+import type { DiffGroup, DiffReadingFile, DiffReadingGroup } from "./types.ts";
+
+/**
+ * A change read the way its code runs: within a package, from the files no
+ * other changed file imports, down through what they import; packages from the
+ * one depending on the others down to its dependencies. A test or a story is
+ * read with the file it covers, below it.
+ *
+ * TypeScript only, imports within the package only (relative, or `#`
+ * through its `package.json` `imports`): what a package imports from another
+ * is told by the package order, not by file.
+ */
+
+const typescriptExtensions = [".ts", ".tsx", ".mts", ".cts"];
+
+const extensionOf = (path: string): string => {
+  const slash = path.lastIndexOf("/");
+  const dot = path.lastIndexOf(".");
+  return dot > slash ? path.slice(dot) : "";
+};
+
+export const isTypescriptPath = (path: string): boolean =>
+  typescriptExtensions.includes(extensionOf(path));
+
+const attachableSuffix = /\.(?:test|spec|stories)(?=\.[cm]?tsx?$)/;
+
+const testDirectories = new Set([
+  "__fixtures__",
+  "__mocks__",
+  "__tests__",
+  "fixtures",
+  "test",
+  "tests",
+]);
+
+/**
+ * A test, a story, or what only tests use (a helper, a mock, a fixture): read
+ * below the file it covers rather than on its own, and never what a test is
+ * read below.
+ */
+export const isAttachablePath = (path: string): boolean =>
+  isTypescriptPath(path) &&
+  (attachableSuffix.test(path) ||
+    path
+      .split("/")
+      .slice(0, -1)
+      .some((directory) => testDirectories.has(directory)));
+
+const javascriptToTypescript: Readonly<Record<string, string>> = {
+  ".js": ".ts",
+  ".jsx": ".tsx",
+  ".mjs": ".mts",
+  ".cjs": ".cts",
+};
+
+const directoryOf = (path: string): string => {
+  const slash = path.lastIndexOf("/");
+  return slash === -1 ? "" : path.slice(0, slash);
+};
+
+/** `a/b/../c/./d` as `a/c/d`; null when it climbs above the root. */
+const normalize = (path: string): string | null => {
+  const segments: string[] = [];
+  for (const segment of path.split("/")) {
+    if (segment === "" || segment === ".") continue;
+    if (segment === "..") {
+      if (segments.length === 0) return null;
+      segments.pop();
+    } else {
+      segments.push(segment);
+    }
+  }
+  return segments.join("/");
+};
+
+const candidatesOf = (target: string): string[] => {
+  const extension = extensionOf(target);
+  const rewritten = javascriptToTypescript[extension];
+  const declaration =
+    rewritten === undefined
+      ? `${target}.d.ts`
+      : `${target.slice(0, -extension.length)}.d.ts`;
+  return [
+    target,
+    ...(rewritten === undefined
+      ? []
+      : [target.slice(0, -extension.length) + rewritten]),
+    ...typescriptExtensions.map((typescript) => target + typescript),
+    declaration,
+    `${target}/index.ts`,
+    `${target}/index.tsx`,
+  ];
+};
+
+const resolveTarget = (
+  target: string | null,
+  exists: (path: string) => boolean,
+): string | null =>
+  target === null
+    ? null
+    : (candidatesOf(target).find(
+        (candidate) => isTypescriptPath(candidate) && exists(candidate),
+      ) ?? null);
+
+/**
+ * The TypeScript file a relative specifier names, as TypeScript resolves it
+ * under `moduleResolution: bundler`: as written, a `.js` written for its
+ * `.ts`, an extension left out, or a directory's `index`. null for a bare
+ * specifier, or one naming no TypeScript file at the commit.
+ */
+export const resolveRelative = (
+  from: string,
+  specifier: string,
+  exists: (path: string) => boolean,
+): string | null => {
+  if (!specifier.startsWith(".")) return null;
+  return resolveTarget(normalize(`${directoryOf(from)}/${specifier}`), exists);
+};
+
+const conditionOrder = ["types", "import", "default"];
+
+/** The target of an `exports` or `imports` value, under `types`, `import`, then `default`. */
+export const targetOf = (value: unknown): string | null => {
+  if (typeof value === "string") return value;
+  if (typeof value !== "object" || value === null) return null;
+  const conditions = value as Record<string, unknown>;
+  for (const condition of conditionOrder) {
+    const target = targetOf(conditions[condition]);
+    if (target !== null) return target;
+  }
+  return null;
+};
+
+/** What `*` stands for in `pattern` when it matches `specifier`; "" for an exact match. */
+export const expand = (pattern: string, specifier: string): string | null => {
+  const star = pattern.indexOf("*");
+  if (star === -1) return pattern === specifier ? "" : null;
+  const prefix = pattern.slice(0, star);
+  const suffix = pattern.slice(star + 1);
+  if (!specifier.startsWith(prefix) || !specifier.endsWith(suffix)) return null;
+  return specifier.slice(prefix.length, specifier.length - suffix.length);
+};
+
+/** As node matches them: an exact key, then the pattern with the longest prefix. */
+export const specificity = (pattern: string): number =>
+  pattern.includes("*") ? pattern.indexOf("*") : Number.MAX_SAFE_INTEGER;
+
+/**
+ * A `#` specifier through the `imports` field of the package's own
+ * `package.json` (`"#/*": "./src/*"`), then resolved as a relative one. The
+ * `types`, `import` and `default` conditions are read, in that order.
+ */
+export const resolveSubpathImport = (
+  specifier: string,
+  { directory, imports }: { directory: string; imports: unknown },
+  exists: (path: string) => boolean,
+): string | null => {
+  if (!specifier.startsWith("#")) return null;
+  if (typeof imports !== "object" || imports === null) return null;
+  const patterns = Object.entries(imports).toSorted(
+    ([left], [right]) => specificity(right) - specificity(left),
+  );
+  for (const [pattern, value] of patterns) {
+    const captured = expand(pattern, specifier);
+    const target = targetOf(value);
+    if (captured === null || target?.startsWith("./") !== true) continue;
+    return resolveTarget(
+      normalize(`${directory}/${target.replace("*", captured)}`),
+      exists,
+    );
+  }
+  return null;
+};
+
+const joinPath = (directory: string, name: string): string =>
+  directory === "" ? name : `${directory}/${name}`;
+
+/** Where the code a test covers sits: beside it, or above its `__tests__`. */
+const coveredDirectoriesOf = (path: string): string[] => {
+  const directory = directoryOf(path);
+  return directory.split("/").at(-1) === "__tests__"
+    ? [directory, directoryOf(directory)]
+    : [directory];
+};
+
+const attachableKinds = new Set(["spec", "stories", "test"]);
+
+/**
+ * The files a test or a story may cover, most likely first: every name its
+ * own name starts with, before its kind (`a.unit.test.ts` covers `a.unit.ts`,
+ * else `a.ts`).
+ */
+export const subjectsOf = (path: string): string[] => {
+  const parts = path
+    .slice(directoryOf(path).length)
+    .replace(/^\//, "")
+    .replace(/\.[cm]?tsx?$/, "")
+    .split(".");
+  const kind = parts.findIndex((part) => attachableKinds.has(part));
+  const stem = kind === -1 ? parts : parts.slice(0, kind);
+  const names = stem.map((_, dropped) =>
+    stem.slice(0, stem.length - dropped).join("."),
+  );
+  return coveredDirectoriesOf(path).flatMap((directory) =>
+    names.flatMap((name) =>
+      typescriptExtensions.map((extension) =>
+        joinPath(directory, name + extension),
+      ),
+    ),
+  );
+};
+
+export interface ReadingOrderInput {
+  /** the changed files, by package, in the order the patch names them */
+  groups: DiffGroup[];
+  /**
+   * The TypeScript files each read file imports, resolved, in source order:
+   * the changed files and the unchanged ones read on the way between them. A
+   * file absent from it was not read.
+   */
+  imports: ReadonlyMap<string, readonly string[]>;
+  /** the package directories each package directory depends on */
+  dependsOn: ReadonlyMap<string, ReadonlySet<string>>;
+}
+
+interface Reach {
+  /** the changed files of the package being ordered */
+  code: ReadonlySet<string>;
+  /** every changed file, of any package */
+  changed: ReadonlySet<string>;
+  imports: ReadonlyMap<string, readonly string[]>;
+}
+
+/**
+ * The files of `code` that `path` reaches, in import order: through the
+ * unchanged files it imports, never past a changed one.
+ */
+const reachedFrom = (
+  path: string,
+  { code, changed, imports }: Reach,
+): string[] => {
+  const reached: string[] = [];
+  const visited = new Set([path]);
+  const visit = (from: string): void => {
+    for (const target of imports.get(from) ?? []) {
+      if (visited.has(target)) continue;
+      visited.add(target);
+      if (code.has(target)) reached.push(target);
+      else if (!changed.has(target)) visit(target);
+    }
+  };
+  visit(path);
+  return reached;
+};
+
+const countReachable = (
+  entry: string,
+  edges: ReadonlyMap<string, readonly string[]>,
+): number => {
+  const seen = new Set([entry]);
+  const stack = [entry];
+  while (stack.length > 0) {
+    for (const target of edges.get(stack.pop()!) ?? []) {
+      if (seen.has(target)) continue;
+      seen.add(target);
+      stack.push(target);
+    }
+  }
+  return seen.size - 1;
+};
+
+/**
+ * Its subject by name; else, of the changed files it imports, one beside it
+ * (a test imports shared helpers, a logger, before what it tests); else the
+ * first.
+ */
+const attachTo = (
+  attachable: string,
+  code: ReadonlySet<string>,
+  reached: readonly string[],
+): string | null => {
+  const covered = coveredDirectoriesOf(attachable);
+  return (
+    subjectsOf(attachable).find((subject) => code.has(subject)) ??
+    reached.find((target) => covered.includes(directoryOf(target))) ??
+    reached[0] ??
+    null
+  );
+};
+
+const orderGroup = (
+  { name, paths }: DiffGroup,
+  changed: ReadonlySet<string>,
+  imports: ReadonlyMap<string, readonly string[]>,
+): DiffReadingGroup => {
+  const code = new Set(
+    paths.filter((path) => isTypescriptPath(path) && !isAttachablePath(path)),
+  );
+  const attachables = paths.filter(isAttachablePath);
+  const others = paths.filter((path) => !isTypescriptPath(path));
+  const reach: Reach = { code, changed, imports };
+
+  const edges = new Map(
+    [...code].map((path) => [path, reachedFrom(path, reach)]),
+  );
+  const imported = new Set([...edges.values()].flat());
+
+  const attached = new Map<string, string[]>();
+  const standalone: string[] = [];
+  for (const attachable of attachables) {
+    const subject = attachTo(attachable, code, reachedFrom(attachable, reach));
+    if (subject === null) standalone.push(attachable);
+    else attached.set(subject, [...(attached.get(subject) ?? []), attachable]);
+  }
+
+  const reachable = new Map(
+    [...code].map((path) => [path, countReachable(path, edges)]),
+  );
+  const byPath = (left: string, right: string): number =>
+    left.localeCompare(right);
+  const roots = [...code]
+    .filter((path) => !imported.has(path))
+    .toSorted(
+      (left, right) =>
+        reachable.get(right)! - reachable.get(left)! || byPath(left, right),
+    );
+
+  const ordered: string[] = [];
+  const visited = new Set<string>();
+  const visit = (path: string): void => {
+    if (visited.has(path)) return;
+    visited.add(path);
+    ordered.push(path);
+    for (const target of edges.get(path) ?? []) visit(target);
+  };
+  for (const root of roots) visit(root);
+  // what only a cycle imports has no root to be reached from
+  for (const path of [...code].toSorted(byPath)) visit(path);
+
+  const entries = new Set(
+    roots.filter((root) => (edges.get(root) ?? []).length > 0),
+  );
+  const rootPaths = new Set(roots);
+  const codeFile = (path: string): DiffReadingFile => ({
+    path,
+    entry: entries.has(path),
+    root: rootPaths.has(path),
+    attached: (attached.get(path) ?? []).toSorted(byPath),
+  });
+  const plainFile = (path: string): DiffReadingFile => ({
+    path,
+    entry: false,
+    root: false,
+    attached: [],
+  });
+
+  return {
+    name,
+    files: [
+      ...ordered.map(codeFile),
+      ...others.map(plainFile),
+      ...standalone.map(plainFile),
+    ],
+  };
+};
+
+const transitiveDependencies = (
+  name: string,
+  dependsOn: ReadonlyMap<string, ReadonlySet<string>>,
+): Set<string> => {
+  const found = new Set<string>();
+  const stack = [name];
+  while (stack.length > 0) {
+    for (const dependency of dependsOn.get(stack.pop()!) ?? []) {
+      if (found.has(dependency) || dependency === name) continue;
+      found.add(dependency);
+      stack.push(dependency);
+    }
+  }
+  return found;
+};
+
+/**
+ * The root first, as `groupDiffPaths` has it; then a package before every
+ * package it depends on, directly or through a package the change does not
+ * touch. Alphabetical between two unrelated packages, and to break a cycle.
+ */
+export const orderPackages = (
+  names: readonly string[],
+  dependsOn: ReadonlyMap<string, ReadonlySet<string>>,
+): string[] => {
+  const remaining = new Set(names.filter((name) => name !== ""));
+  const dependencies = new Map(
+    [...remaining].map((name) => [
+      name,
+      transitiveDependencies(name, dependsOn),
+    ]),
+  );
+  const isDependedOnByRemaining = (name: string): boolean =>
+    [...remaining].some(
+      (other) => other !== name && dependencies.get(other)!.has(name),
+    );
+
+  const ordered = names.includes("") ? [""] : [];
+  while (remaining.size > 0) {
+    const sorted = [...remaining].toSorted((left, right) =>
+      left.localeCompare(right),
+    );
+    const next =
+      sorted.find((name) => !isDependedOnByRemaining(name)) ?? sorted[0]!;
+    ordered.push(next);
+    remaining.delete(next);
+  }
+  return ordered;
+};
+
+export const orderForReading = ({
+  groups,
+  imports,
+  dependsOn,
+}: ReadingOrderInput): DiffReadingGroup[] => {
+  const byName = new Map(groups.map((group) => [group.name, group]));
+  const changed = new Set(groups.flatMap(({ paths }) => paths));
+  return orderPackages(
+    groups.map(({ name }) => name),
+    dependsOn,
+  ).map((name) => orderGroup(byName.get(name)!, changed, imports));
+};

package/src/diff/themes.ts

@@ -0,0 +1,105 @@
+/**
+ * The diff's syntax theme, as a family: each names a shiki theme for the light
+ * mode and one for the dark mode, so the diff follows the app's mode whichever
+ * is picked. Plain data, so a server can validate a stored setting against the
+ * same list the ui renders.
+ */
+export const diffThemes = [
+  "github",
+  "github-high-contrast",
+  "pierre",
+  "vscode",
+  "one",
+  "catppuccin",
+  "rose-pine",
+  "solarized",
+  "gruvbox",
+  "everforest",
+  "kanagawa",
+  "vitesse",
+  "ayu",
+  "material",
+  "night-owl",
+  "min",
+] as const;
+
+export type DiffTheme = (typeof diffThemes)[number];
+
+export const isDiffTheme = (value: unknown): value is DiffTheme =>
+  (diffThemes as readonly unknown[]).includes(value);
+
+interface DiffThemeFamily {
+  label: string;
+  /** shiki theme names, the pierre ones resolved by `@pierre/diffs` itself */
+  themes: { light: string; dark: string };
+}
+
+const families: Record<DiffTheme, DiffThemeFamily> = {
+  github: {
+    label: "GitHub",
+    themes: { light: "github-light-default", dark: "github-dark-default" },
+  },
+  "github-high-contrast": {
+    label: "GitHub high contrast",
+    themes: {
+      light: "github-light-high-contrast",
+      dark: "github-dark-high-contrast",
+    },
+  },
+  pierre: {
+    label: "Pierre",
+    themes: { light: "pierre-light", dark: "pierre-dark" },
+  },
+  vscode: {
+    label: "VS Code",
+    themes: { light: "light-plus", dark: "dark-plus" },
+  },
+  one: { label: "One", themes: { light: "one-light", dark: "one-dark-pro" } },
+  catppuccin: {
+    label: "Catppuccin",
+    themes: { light: "catppuccin-latte", dark: "catppuccin-mocha" },
+  },
+  "rose-pine": {
+    label: "Rosé Pine",
+    themes: { light: "rose-pine-dawn", dark: "rose-pine" },
+  },
+  solarized: {
+    label: "Solarized",
+    themes: { light: "solarized-light", dark: "solarized-dark" },
+  },
+  gruvbox: {
+    label: "Gruvbox",
+    themes: { light: "gruvbox-light-medium", dark: "gruvbox-dark-medium" },
+  },
+  everforest: {
+    label: "Everforest",
+    themes: { light: "everforest-light", dark: "everforest-dark" },
+  },
+  kanagawa: {
+    label: "Kanagawa",
+    themes: { light: "kanagawa-lotus", dark: "kanagawa-wave" },
+  },
+  vitesse: {
+    label: "Vitesse",
+    themes: { light: "vitesse-light", dark: "vitesse-dark" },
+  },
+  ayu: { label: "Ayu", themes: { light: "ayu-light", dark: "ayu-dark" } },
+  material: {
+    label: "Material",
+    themes: { light: "material-theme-lighter", dark: "material-theme" },
+  },
+  "night-owl": {
+    label: "Night Owl",
+    themes: { light: "night-owl-light", dark: "night-owl" },
+  },
+  min: { label: "Min", themes: { light: "min-light", dark: "min-dark" } },
+};
+
+export const diffThemeNames = (
+  theme: DiffTheme,
+): { light: string; dark: string } => families[theme].themes;
+
+export const diffThemeOptions = diffThemes.map((theme) => ({
+  value: theme,
+  label: families[theme].label,
+}));