@ascribed/review 0.1.2-next.2

package/dist/github/transport.js

@@ -0,0 +1,206 @@
+// How requests reach GitHub's GraphQL API: through the GitHub CLI, or with a
+// token the host supplies. Neither stores a token or puts one in an error.
+import { spawn } from "node:child_process";
+import { ReviewError, scrub } from "../shared/errors.js";
+/** The oldest `gh` this package runs. */
+export const MIN_GH_VERSION = "2.0.0";
+/**
+ * A transport that runs `gh api graphql` with a fixed argument list: the
+ * query on standard input, each variable as an argument. `gh` uses its own
+ * sign-in for the host.
+ */
+export function ghTransport(options = {}) {
+    const host = options.host ?? "github.com";
+    const command = options.command ?? "gh";
+    let checked;
+    return {
+        async graphql(query, variables) {
+            checked ??= checkGh(command);
+            try {
+                await checked;
+            }
+            catch (error) {
+                checked = undefined;
+                throw error;
+            }
+            const args = ["api", "graphql", "--hostname", host, "-F", "query=@-"];
+            for (const [name, value] of Object.entries(variables)) {
+                if (value === undefined)
+                    continue;
+                if (typeof value === "string")
+                    args.push("-f", `${name}=${value}`);
+                else if (typeof value === "number" || typeof value === "boolean" || value === null) {
+                    args.push("-F", `${name}=${String(value)}`);
+                }
+                else {
+                    throw new TypeError(`ghTransport can't pass the variable ${name}: ${typeof value}`);
+                }
+            }
+            const result = await run(command, args, query);
+            const body = parseBody(result.stdout);
+            if (result.code === 0 && body !== undefined && body.errors === undefined) {
+                return body.data;
+            }
+            throw ghError(result, body, host);
+        },
+    };
+}
+async function checkGh(command) {
+    const result = await run(command, ["--version"], "");
+    const version = /gh version (\d+)\.(\d+)\.(\d+)/.exec(result.stdout);
+    if (result.code !== 0 || version === null) {
+        throw new ReviewError("gh-too-old", "Couldn't read the GitHub CLI's version (`gh --version`).");
+    }
+    const found = version.slice(1, 4).map(Number);
+    const min = MIN_GH_VERSION.split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        const a = found[i] ?? 0;
+        const b = min[i] ?? 0;
+        if (a > b)
+            return;
+        if (a < b) {
+            throw new ReviewError("gh-too-old", `The GitHub CLI is version ${found.join(".")}; review needs ${MIN_GH_VERSION} or later. Update it from https://cli.github.com.`);
+        }
+    }
+}
+function run(command, args, input) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            stdio: ["pipe", "pipe", "pipe"],
+            env: { ...process.env, GH_PROMPT_DISABLED: "1", GH_NO_UPDATE_NOTIFIER: "1", NO_COLOR: "1" },
+            windowsHide: true,
+        });
+        const stdout = [];
+        const stderr = [];
+        child.stdout.on("data", (chunk) => stdout.push(chunk));
+        child.stderr.on("data", (chunk) => stderr.push(chunk));
+        child.on("error", (error) => {
+            if (error.code === "ENOENT") {
+                reject(new ReviewError("gh-missing", "The GitHub CLI (`gh`) isn't on the path. Install it from https://cli.github.com and run `gh auth login`.", { cause: error }));
+            }
+            else {
+                reject(new ReviewError("network", `Couldn't run \`gh\`: ${error.message}`, { cause: error }));
+            }
+        });
+        child.on("close", (code) => {
+            resolve({
+                code: code ?? 1,
+                stdout: Buffer.concat(stdout).toString("utf8"),
+                stderr: Buffer.concat(stderr).toString("utf8"),
+            });
+        });
+        // gh may exit before reading its input; the exit code says what happened.
+        child.stdin.on("error", () => undefined);
+        child.stdin.end(input);
+    });
+}
+function parseBody(text) {
+    try {
+        const value = JSON.parse(text);
+        return typeof value === "object" && value !== null ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function ghError(result, body, host) {
+    const stderr = result.stderr.replace(/^gh: /gm, "").trim();
+    // gh exits with 4 when a command needs authentication it doesn't have.
+    if (result.code === 4 ||
+        /gh auth login|not logged in|HTTP 401|Bad credentials/i.test(result.stderr)) {
+        return new ReviewError("not-signed-in", `The GitHub CLI isn't signed in to ${host}. Run \`gh auth login --hostname ${host}\`.`);
+    }
+    if (body?.errors !== undefined)
+        return graphqlError(body.errors);
+    if (/rate limit/i.test(stderr))
+        return rateLimited(undefined, stderr);
+    return new ReviewError("refused", `GitHub refused the request: ${stderr || body?.message || `gh exited with ${result.code}`}`);
+}
+function graphqlError(errors) {
+    const message = errors.map((error) => error.message ?? "unknown error").join("; ");
+    if (errors.some((error) => error.type === "RATE_LIMITED"))
+        return rateLimited(undefined, message);
+    if (errors.every((error) => error.type === "NOT_FOUND")) {
+        return new ReviewError("not-found", `GitHub couldn't find it: ${message}`);
+    }
+    return new ReviewError("refused", `GitHub refused the request: ${message}`);
+}
+function rateLimited(retryAfter, detail) {
+    const wait = retryAfter === undefined
+        ? "Wait a minute"
+        : `Wait ${retryAfter} second${retryAfter === 1 ? "" : "s"}`;
+    return new ReviewError("rate-limited", `GitHub is limiting how fast requests can be made. ${wait} and try again. (${detail})`, retryAfter === undefined ? {} : { retryAfter });
+}
+/**
+ * A transport that posts to the GraphQL API with `fetch`, using a token from
+ * `getToken`, which is called for each request so the host can refresh it.
+ */
+export function tokenTransport(getToken, options = {}) {
+    const host = options.host ?? "github.com";
+    const url = graphqlUrl(host);
+    return {
+        async graphql(query, variables) {
+            const doFetch = options.fetch ?? globalThis.fetch;
+            const token = await getToken();
+            if (token === undefined || token === "") {
+                throw new ReviewError("not-signed-in", `There's no GitHub sign-in for ${host}.`);
+            }
+            let response;
+            try {
+                response = await doFetch(url, {
+                    method: "POST",
+                    headers: {
+                        authorization: `bearer ${token}`,
+                        "content-type": "application/json",
+                        accept: "application/json",
+                        "user-agent": "ascribe-review",
+                    },
+                    body: JSON.stringify({ query, variables }),
+                });
+            }
+            catch (error) {
+                const detail = error instanceof Error ? error.message : String(error);
+                throw new ReviewError("network", `Couldn't reach ${host}: ${detail}`, { cause: error });
+            }
+            const text = await response.text();
+            const body = parseBody(text);
+            if (response.status === 401) {
+                throw new ReviewError("not-signed-in", `${host} didn't accept the GitHub sign-in.`);
+            }
+            if (response.status === 403 || response.status === 429) {
+                const retryAfter = retryAfterOf(response.headers);
+                if (response.status === 429 ||
+                    retryAfter !== undefined ||
+                    /rate limit/i.test(body?.message ?? text)) {
+                    throw rateLimited(retryAfter, scrub(body?.message ?? `HTTP ${response.status}`));
+                }
+            }
+            if (!response.ok) {
+                throw new ReviewError("refused", `GitHub refused the request (HTTP ${response.status}): ${scrub(body?.message ?? text.slice(0, 200))}`);
+            }
+            if (body === undefined) {
+                throw new ReviewError("network", `${host} answered with something that isn't JSON.`);
+            }
+            if (body.errors !== undefined && body.errors.length > 0)
+                throw graphqlError(body.errors);
+            return body.data;
+        },
+    };
+}
+/** The GraphQL endpoint for a host. */
+export function graphqlUrl(host) {
+    return host === "github.com" ? "https://api.github.com/graphql" : `https://${host}/api/graphql`;
+}
+function retryAfterOf(headers) {
+    const after = headers.get("retry-after");
+    if (after !== null && /^\d+$/.test(after))
+        return Number(after);
+    if (headers.get("x-ratelimit-remaining") === "0") {
+        const reset = Number(headers.get("x-ratelimit-reset"));
+        if (Number.isFinite(reset) && reset > 0) {
+            return Math.max(0, Math.ceil(reset - Date.now() / 1000));
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=transport.js.map

package/dist/github/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/github/transport.ts"],"names":[],"mappings":"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"}

package/dist/marks/index.d.ts

@@ -0,0 +1,92 @@
+/** Where a block is written: the anchor grammar's `source` and `via`. */
+export interface Anchor {
+    source: string;
+    via: string[];
+}
+/** The words that differ inside a changed block of prose. */
+export interface Words {
+    /** `[start, end)` ranges, in characters, of `now_text`. */
+    now: [number, number][];
+    /** `[start, end)` ranges, in characters, of `was_text`. */
+    was: [number, number][];
+    now_text: string;
+    was_text: string;
+}
+/** One block's change, as `ascribe diff --format json` writes it. */
+export interface Change {
+    kind: "changed" | "added" | "removed" | "moved";
+    now?: Anchor;
+    was?: Anchor;
+    words?: Words;
+    after?: Anchor;
+    parent?: Anchor;
+    text?: string;
+}
+/** What the page shows: its changes, the page as it will be, or as it was. */
+export type Show = "changes" | "will" | "was";
+export interface MarkOptions {
+    /**
+     * The page as it was, rendered with anchors. Removed blocks, and moved
+     * blocks at their old place, are copied from it; without it they're shown
+     * from the change's `text`, and "as it was" shows changed prose from its
+     * words.
+     */
+    was?: ParentNode | null;
+}
+/** A change as marked on the page. */
+export interface Mark {
+    change: Change;
+    /** The element to go to: the block now, or what stands for a removed one. */
+    element: HTMLElement;
+}
+/** A parsed anchor source: the path, decoded, and the lines. */
+export interface Source {
+    path: string;
+    first: number;
+    last: number;
+}
+/** Parses `<path>:<first>-<last>`, splitting at the last `:`. */
+export declare function parseSource(source: string): Source | undefined;
+/** `guides/install.md:12`, or `guides/install.md:12-14`, and its includes. */
+export declare function describeSource(source: string, via?: string | null): string;
+/**
+ * The element of a block: the one with exactly its anchor, or, when there's
+ * none (a paragraph in a tight list item has no element of its own), the
+ * smallest anchored element with the same file and includes whose lines
+ * contain it.
+ */
+export declare function findBlock(root: ParentNode, anchor: Anchor): HTMLElement | null;
+/**
+ * Marks `changes` on the page in `root`, and returns the marks in page
+ * order. Marks already there are cleared first.
+ */
+export declare function markChanges(root: HTMLElement, changes: readonly Change[], options?: MarkOptions): Mark[];
+/**
+ * The button that selects an `<ascribe-tab>`, in its group's tab list, or
+ * null before `@ascribed/elements` has made the list.
+ */
+export declare function tabButton(tab: Element): HTMLButtonElement | null;
+/** Removes every mark from the page in `root`. */
+export declare function clearMarks(root: HTMLElement): void;
+/** Shows the changes, the page as it will be, or the page as it was. */
+export declare function setShow(root: HTMLElement, show: Show): void;
+/**
+ * Makes `element` visible: opens the `<details>` and selects the tabs it's
+ * in.
+ */
+export declare function reveal(element: HTMLElement): void;
+/** Reveals `element`, scrolls to it, and flashes it. */
+export declare function goTo(element: HTMLElement): void;
+/**
+ * Shows each block's source on hover and focus: `guides/install.md:12`,
+ * from its anchor. Returns a function that stops.
+ */
+export declare function showSources(root: HTMLElement): () => void;
+/**
+ * Takes out of a page's HTML what could run script or take the reader
+ * elsewhere: scripts, `<meta>` and `<base>`, event handler attributes, and
+ * `javascript:` URLs. A page under review comes from the change being
+ * reviewed, so a host disarms it before showing it, whatever its content
+ * security policy also blocks.
+ */
+export declare function disarm(fragment: DocumentFragment): void;