@ascribed/review 0.1.2-next.2

package/dist/shared/git.js

@@ -0,0 +1,29 @@
+// Running `git` with a fixed argument list, never through a shell.
+import { execFile } from "node:child_process";
+import { ReviewError } from "./errors.js";
+/** Runs `git` in `cwd` and resolves with its standard output. */
+export function git(cwd, args) {
+    return new Promise((resolve, reject) => {
+        execFile("git", ["-c", "core.quotepath=off", ...args], { cwd, maxBuffer: 256 * 1024 * 1024, encoding: "utf8" }, (error, stdout, stderr) => {
+            if (error === null) {
+                resolve(stdout);
+                return;
+            }
+            const missing = error.code === "ENOENT";
+            const detail = stderr.trim() || error.message;
+            reject(new ReviewError("git", missing ? "`git` isn't on the path." : `\`git ${args.join(" ")}\` failed: ${detail}`, { cause: error }));
+        });
+    });
+}
+/** Like `git`, but resolves with `undefined` instead of rejecting when git exits non-zero. */
+export async function gitMaybe(cwd, args) {
+    try {
+        return await git(cwd, args);
+    }
+    catch (error) {
+        if (error instanceof ReviewError && error.message.startsWith("`git` isn't"))
+            throw error;
+        return undefined;
+    }
+}
+//# sourceMappingURL=git.js.map

package/dist/shared/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../../src/shared/git.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,iEAAiE;AACjE,MAAM,UAAU,GAAG,CAAC,GAAW,EAAE,IAAuB;IACtD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,QAAQ,CACN,KAAK,EACL,CAAC,IAAI,EAAE,oBAAoB,EAAE,GAAG,IAAI,CAAC,EACrC,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,EACvD,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;YACxB,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,OAAO,CAAC,MAAM,CAAC,CAAC;gBAChB,OAAO;YACT,CAAC;YACD,MAAM,OAAO,GAAI,KAA+B,CAAC,IAAI,KAAK,QAAQ,CAAC;YACnE,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,OAAO,CAAC;YAC9C,MAAM,CACJ,IAAI,WAAW,CACb,KAAK,EACL,OAAO,CAAC,CAAC,CAAC,0BAA0B,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,cAAc,MAAM,EAAE,EACpF,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CACF,CAAC;QACJ,CAAC,CACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,8FAA8F;AAC9F,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,GAAW,EAAE,IAAuB;IACjE,IAAI,CAAC;QACH,OAAO,MAAM,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,WAAW,IAAI,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC;YAAE,MAAM,KAAK,CAAC;QACzF,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/shared/types.d.ts

@@ -0,0 +1,56 @@
+/** A comment's author: `null` when GitHub reports none (a deleted account). */
+export interface Author {
+    login: string;
+    avatarUrl: string | undefined;
+}
+/** A comment in a thread. `body` is Markdown from other people, unrendered. */
+export interface ThreadComment {
+    id: string;
+    author: Author | null;
+    body: string;
+    createdAt: string;
+    url: string;
+    /** Whether it's in the viewer's pending review: only the viewer sees it. */
+    pending: boolean;
+}
+/** Which side of the pull request's diff a thread is on: new text, or removed text. */
+export type Side = "RIGHT" | "LEFT";
+/**
+ * A review thread, or a conversation comment with a hidden anchor marker
+ * (`kind: "conversation"`), which GitHub can't resolve.
+ */
+export interface Thread {
+    id: string;
+    kind: "review" | "conversation";
+    /** The file's path in the repository, with `/`. */
+    repositoryPath: string;
+    /** `"file"` for a thread on a whole file, which has no lines. */
+    subject: "line" | "file";
+    side: Side;
+    /** The thread's last line at the pull request's head, or `null` when it's outdated. */
+    line: number | null;
+    /** Its first line, for a multi-line thread. */
+    startLine: number | null;
+    /** Its last line at `originalCommit`. */
+    originalLine: number | null;
+    originalStartLine: number | null;
+    /** The commit `line` is counted at. */
+    commit: string | undefined;
+    /** The commit the thread was made at. */
+    originalCommit: string | undefined;
+    resolved: boolean;
+    outdated: boolean;
+    canResolve: boolean;
+    canUnresolve: boolean;
+    canReply: boolean;
+    comments: ThreadComment[];
+    /** GitHub's diff hunk ending at the thread's line. */
+    diffHunk: string | undefined;
+    /** For a conversation comment: the block source and build its marker names. */
+    marker: {
+        source: string;
+        build: string | undefined;
+    } | undefined;
+    /** The text the thread is on, when known: quoted by a conversation comment, or read from git. */
+    quote: string | undefined;
+}

package/dist/shared/types.js

@@ -0,0 +1,3 @@
+// The shapes threads take, shared by `./github` and `./place`.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/shared/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"AAAA,+DAA+D"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@ascribed/review",
+  "version": "0.1.2-next.2",
+  "description": "Reviewing Ascribe pages as readers see them: changed blocks marked on the rendered page, and a pull request's review threads beside them.",
+  "type": "module",
+  "license": "MPL-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ascribed-dev/ascribe.git",
+    "directory": "packages/review"
+  },
+  "homepage": "https://github.com/ascribed-dev/ascribe/tree/main/packages/review#readme",
+  "bugs": "https://github.com/ascribed-dev/ascribe/issues",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src/marks/marks.css",
+    "README.md"
+  ],
+  "exports": {
+    "./marks": {
+      "types": "./dist/marks/index.d.ts",
+      "default": "./dist/marks/index.js"
+    },
+    "./marks.css": "./src/marks/marks.css",
+    "./overlay": {
+      "types": "./dist/overlay/index.d.ts",
+      "default": "./dist/overlay/index.js"
+    },
+    "./github": {
+      "types": "./dist/github/index.d.ts",
+      "default": "./dist/github/index.js"
+    },
+    "./place": {
+      "types": "./dist/place/index.d.ts",
+      "default": "./dist/place/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "devDependencies": {
+    "@ascribed/elements": "0.1.2-next.2",
+    "@types/node": "^24.0.0",
+    "esbuild": "^0.28.2",
+    "jsdom": "^30.1.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "smol-toml": "^1.9.0"
+  },
+  "gitHead": "1291a4b1db8edd88650e70f417d8037e26bceb38",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "embed": "node embed.ts"
+  }
+}

package/src/marks/marks.css

@@ -0,0 +1,361 @@
+/*
+ * @ascribed/review/marks.css: how changed blocks look on a rendered page.
+ *
+ * `markChanges` (@ascribed/review/marks) puts the marks on the page and
+ * `setShow` picks what it shows, with `data-ascribe-show` on the page's root:
+ * `changes`, `will` (the page as it will be), or `was` (as it was). Every
+ * mark has a label as well as a bar of its own shape, so no change is told by
+ * color alone. Theme it with the --ascribe-review-* custom properties.
+ *
+ * The colors follow the reader's color scheme. A page whose own colors don't
+ * sets `data-ascribe-scheme="light"` or `"dark"` on its root element.
+ */
+
+:root {
+  --ascribe-review-added: #1a7f37;
+  --ascribe-review-added-background: #dcf7e3;
+  --ascribe-review-changed: #8a5a00;
+  --ascribe-review-changed-background: #fff1c2;
+  --ascribe-review-removed: #c4222d;
+  --ascribe-review-removed-background: #ffe4e2;
+  --ascribe-review-moved: #7a3fd0;
+  --ascribe-review-moved-background: #f0e6ff;
+  --ascribe-review-muted: #5b6475;
+  --ascribe-review-surface: #ffffff;
+  --ascribe-review-flash: #fff6bf;
+  --ascribe-review-focus: #1f6feb;
+  --ascribe-review-mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
+  /* The review overlay's threads and controls (@ascribed/review/overlay). */
+  --ascribe-review-text: #1d2330;
+  --ascribe-review-border: #d3d8e0;
+  --ascribe-review-thread: #f5f7fb;
+  --ascribe-review-input: #ffffff;
+  --ascribe-review-accent-text: #ffffff;
+  --ascribe-review-blend: multiply;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-ascribe-scheme="light"]) {
+    --ascribe-review-added: #4fc572;
+    --ascribe-review-added-background: #133520;
+    --ascribe-review-changed: #dcb13a;
+    --ascribe-review-changed-background: #3a2f0d;
+    --ascribe-review-removed: #ff8279;
+    --ascribe-review-removed-background: #401918;
+    --ascribe-review-moved: #c59bff;
+    --ascribe-review-moved-background: #2d2440;
+    --ascribe-review-muted: #929bab;
+    --ascribe-review-surface: #1e2026;
+    --ascribe-review-flash: #3b3514;
+    --ascribe-review-focus: #5aa2ff;
+    --ascribe-review-text: #d9dde5;
+    --ascribe-review-border: #343a45;
+    --ascribe-review-thread: #272b33;
+    --ascribe-review-input: #1e2026;
+    --ascribe-review-accent-text: #0b1220;
+    --ascribe-review-blend: screen;
+  }
+}
+
+:root[data-ascribe-scheme="dark"] {
+  --ascribe-review-added: #4fc572;
+  --ascribe-review-added-background: #133520;
+  --ascribe-review-changed: #dcb13a;
+  --ascribe-review-changed-background: #3a2f0d;
+  --ascribe-review-removed: #ff8279;
+  --ascribe-review-removed-background: #401918;
+  --ascribe-review-moved: #c59bff;
+  --ascribe-review-moved-background: #2d2440;
+  --ascribe-review-muted: #929bab;
+  --ascribe-review-surface: #1e2026;
+  --ascribe-review-flash: #3b3514;
+  --ascribe-review-focus: #5aa2ff;
+  --ascribe-review-text: #d9dde5;
+  --ascribe-review-border: #343a45;
+  --ascribe-review-thread: #272b33;
+  --ascribe-review-input: #1e2026;
+  --ascribe-review-accent-text: #0b1220;
+  --ascribe-review-blend: screen;
+}
+
+.ascribe-marks {
+  position: relative;
+}
+
+/* The bar: a left border whose color and style differ by kind. */
+.ascribe-marks [data-ascribe-change] {
+  position: relative;
+  border-inline-start: 3px solid transparent;
+  padding-inline-start: 9px;
+  margin-inline-start: -12px;
+  border-radius: 0 3px 3px 0;
+}
+
+.ascribe-marks li[data-ascribe-change] {
+  margin-inline-start: 0;
+  padding-inline-start: 6px;
+}
+
+[data-ascribe-show="changes"] [data-ascribe-change="added"] {
+  border-inline-start-color: var(--ascribe-review-added);
+  background: var(--ascribe-review-added-background);
+}
+
+[data-ascribe-show="changes"] [data-ascribe-change="changed"] {
+  border-inline-start-color: var(--ascribe-review-changed);
+  border-inline-start-style: dashed;
+}
+
+[data-ascribe-show="changes"] [data-ascribe-change="moved"] {
+  border-inline-start-color: var(--ascribe-review-moved);
+  border-inline-start-style: double;
+  background: var(--ascribe-review-moved-background);
+}
+
+[data-ascribe-show="changes"] [data-ascribe-change="removed"] {
+  border-inline-start-color: var(--ascribe-review-removed);
+  border-inline-start-style: dotted;
+  background: var(--ascribe-review-removed-background);
+}
+
+/* The labels: Added, Changed, Removed, Moved. */
+.ascribe-label {
+  display: none;
+  font-size: 10.5px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  margin-inline-end: 6px;
+  font-style: normal;
+}
+
+[data-ascribe-show="changes"] .ascribe-label {
+  display: inline-block;
+}
+
+[data-ascribe-show="changes"] .ascribe-label-before {
+  display: block;
+  margin-block: 8px -4px;
+}
+
+.ascribe-label[data-ascribe-label="added"] {
+  color: var(--ascribe-review-added);
+}
+
+.ascribe-label[data-ascribe-label="changed"] {
+  color: var(--ascribe-review-changed);
+}
+
+.ascribe-label[data-ascribe-label="removed"] {
+  color: var(--ascribe-review-removed);
+}
+
+.ascribe-label[data-ascribe-label="moved"] {
+  color: var(--ascribe-review-moved);
+}
+
+/* On a tab's label and a <details>' summary: what's changed inside. */
+.ascribe-hint {
+  display: none;
+  margin-inline-start: 2px;
+  font-size: 11px;
+  font-weight: 600;
+  font-style: normal;
+}
+
+[data-ascribe-show="changes"] .ascribe-hint {
+  display: inline;
+}
+
+.ascribe-hint[data-ascribe-hint="added"] {
+  color: var(--ascribe-review-added);
+}
+
+.ascribe-hint[data-ascribe-hint="changed"] {
+  color: var(--ascribe-review-changed);
+}
+
+/* Words inside a changed block. */
+.ascribe-ins {
+  text-decoration: none;
+}
+
+.ascribe-del {
+  display: none;
+  text-decoration: none;
+}
+
+[data-ascribe-show="changes"] .ascribe-ins {
+  background: var(--ascribe-review-added-background);
+  box-shadow: inset 0 -2px 0 var(--ascribe-review-added);
+}
+
+[data-ascribe-show="changes"] .ascribe-del {
+  display: inline;
+  background: var(--ascribe-review-removed-background);
+  text-decoration: line-through;
+  color: var(--ascribe-review-muted);
+}
+
+/* A removed block: collapsed to one line, struck through, with Show. */
+.ascribe-removed {
+  display: none;
+  list-style: none;
+}
+
+[data-ascribe-show="changes"] .ascribe-removed {
+  display: flex;
+  gap: 6px;
+  align-items: baseline;
+  margin-block: 8px;
+}
+
+[data-ascribe-show="changes"] .ascribe-removed-body {
+  flex: 1;
+  min-width: 0;
+  max-height: 1.6em;
+  overflow: hidden;
+  text-decoration: line-through;
+  color: var(--ascribe-review-muted);
+}
+
+[data-ascribe-show="changes"] .ascribe-removed-body > * {
+  margin-block: 0;
+}
+
+[data-ascribe-show="changes"] .ascribe-removed:not(.ascribe-open) .ascribe-removed-body,
+[data-ascribe-show="changes"] .ascribe-removed:not(.ascribe-open) .ascribe-removed-body > * {
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+[data-ascribe-show="changes"] .ascribe-removed.ascribe-open .ascribe-removed-body {
+  max-height: none;
+}
+
+[data-ascribe-show="changes"] .ascribe-removed.ascribe-open .ascribe-removed-body > * {
+  margin-block: 0.5em;
+}
+
+.ascribe-toggle,
+.ascribe-move-link {
+  font: inherit;
+  font-size: 12px;
+  white-space: nowrap;
+  color: var(--ascribe-review-focus);
+  background: none;
+  border: 0;
+  padding: 0 2px;
+  cursor: pointer;
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+[data-ascribe-show="was"] .ascribe-removed {
+  display: block;
+}
+
+[data-ascribe-show="was"] .ascribe-removed > .ascribe-label,
+[data-ascribe-show="was"] .ascribe-toggle {
+  display: none;
+}
+
+/* A move: the block where it is now, and a stub where it was. */
+.ascribe-move-note {
+  display: none;
+  font-size: 12px;
+  color: var(--ascribe-review-moved);
+}
+
+[data-ascribe-show="changes"] .ascribe-move-note {
+  display: inline;
+}
+
+[data-ascribe-show="changes"] .ascribe-move-after {
+  display: block;
+  margin-block: -4px 8px;
+}
+
+.ascribe-moved-from {
+  display: none;
+  list-style: none;
+}
+
+[data-ascribe-show="changes"] .ascribe-moved-from {
+  display: block;
+  border-inline-start: 3px double var(--ascribe-review-moved);
+  padding-inline-start: 9px;
+  margin: 6px 0 6px -12px;
+}
+
+[data-ascribe-show="was"] .ascribe-moved-from {
+  display: block;
+}
+
+[data-ascribe-show="was"] .ascribe-moved-from > .ascribe-move-note {
+  display: none;
+}
+
+/* What only the page as it was shows: a changed block before, a moved block
+   at its old place. */
+[data-ascribe-was-only] {
+  display: none;
+}
+
+[data-ascribe-show="was"] [data-ascribe-was-only] {
+  display: block;
+}
+
+[data-ascribe-show="was"] li[data-ascribe-was-only] {
+  display: list-item;
+}
+
+[data-ascribe-show="was"] [data-ascribe-change="added"],
+[data-ascribe-show="was"] [data-ascribe-change="moved"],
+[data-ascribe-show="was"] [data-ascribe-change="moved"] + .ascribe-move-after,
+[data-ascribe-show="was"] [data-ascribe-has-was],
+[data-ascribe-show="was"] .ascribe-label-before,
+[data-ascribe-show="was"] .ascribe-ins {
+  display: none;
+}
+
+[data-ascribe-show="was"] .ascribe-del {
+  display: inline;
+}
+
+/* A block's source, on hover and focus. */
+.ascribe-where {
+  position: absolute;
+  inset-inline-end: 0;
+  transform: translateY(-100%);
+  font-family: var(--ascribe-review-mono);
+  font-size: 10.5px;
+  color: var(--ascribe-review-muted);
+  background: var(--ascribe-review-surface);
+  padding: 0 4px;
+  pointer-events: none;
+  white-space: nowrap;
+  z-index: 1;
+}
+
+.ascribe-flash {
+  animation: ascribe-flash 1.4s ease-out;
+}
+
+.ascribe-marks [tabindex="-1"]:focus {
+  outline: none;
+}
+
+@keyframes ascribe-flash {
+  from {
+    background: var(--ascribe-review-flash);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ascribe-flash {
+    animation: none;
+    outline: 2px solid var(--ascribe-review-focus);
+  }
+}