@ascribed/astro 0.1.0 → 0.1.2-next.2

package/dist/rehype.js

@@ -1,5 +1,5 @@
-// The attribute marker as a rehype plugin, for Astro's `unified()` markdown
-// processor (`@astrojs/markdown-remark`).
+// The attribute marker and source anchors as a rehype plugin, for Astro's
+// `unified()` markdown processor (`@astrojs/markdown-remark`).
 //
 // Astro builds that processor as: remark-parse, remark-gfm, remark-smartypants,
 // the user's remark plugins, remark-collect-images, remark-rehype (raw HTML
@@ -10,14 +10,28 @@
 // and `rehypeHeadingIds` keeps an id a heading already has and records it for
 // the table of contents. A rehype plugin, not a remark one, so that both of
 // Astro's processors can share `findEdits`.
-import { findEdits, toProperty } from "./attributes.js";
-/** Applies the site output's attribute markers (`ascribe-attributes`). */
+import { findAnchors, findEdits, toProperty } from "./attributes.js";
+/** Applies the site output's attribute markers (`ascribe-attributes`) and source anchors. */
 export default function rehypeAscribeAttributes() {
     return (tree) => {
         const edits = findEdits(tree);
-        if (edits.length === 0)
+        const anchors = findAnchors(tree);
+        if (edits.length === 0 && anchors.length === 0)
             return;
         const removed = new Set();
+        for (const anchor of anchors) {
+            for (const { node, attributes } of anchor.targets) {
+                const properties = (node.properties ??= {});
+                for (const attribute of attributes) {
+                    const [name, value] = toProperty(attribute);
+                    properties[name] = value;
+                }
+            }
+            if (anchor.replace)
+                anchor.replace.node.value = anchor.replace.value;
+            for (const node of anchor.remove)
+                removed.add(node);
+        }
         for (const edit of edits) {
             const properties = (edit.target.properties ??= {});
             for (const attribute of edit.attributes) {

package/dist/rehype.js.map

@@ -1 +1 @@
-{"version":3,"file":"rehype.js","sourceRoot":"","sources":["../src/rehype.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,0CAA0C;AAC1C,EAAE;AACF,gFAAgF;AAChF,4EAA4E;AAC5E,4EAA4E;AAC5E,+EAA+E;AAC/E,8EAA8E;AAC9E,6EAA6E;AAC7E,8EAA8E;AAC9E,4EAA4E;AAC5E,4CAA4C;AAG5C,OAAO,EAAE,SAAS,EAAE,UAAU,EAAiB,MAAM,iBAAiB,CAAC;AAEvE,0EAA0E;AAC1E,MAAM,CAAC,OAAO,UAAU,uBAAuB;IAC7C,OAAO,CAAC,IAAI,EAAE,EAAE;QACd,MAAM,KAAK,GAAG,SAAS,CAAC,IAAgB,CAAC,CAAC;QAC1C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAC/B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAY,CAAC;QACpC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,UAAU,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,KAAK,EAAE,CAAC,CAAC;YACnD,KAAK,MAAM,SAAS,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;gBACxC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC;gBAC5C,UAAU,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;YAC3B,CAAC;YACD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,MAAM;gBAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAClD,KAAK,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBACxC,IAAI,KAAK,KAAK,EAAE;oBAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;;oBAC/B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;YAC1B,CAAC;QACH,CAAC;QACD,SAAS,CAAC,IAAgB,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,IAAc,EAAE,OAAsB;IACvD,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;QAAE,OAAO;IACxC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;IACrE,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ;QAAE,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;AAC/D,CAAC"}
+{"version":3,"file":"rehype.js","sourceRoot":"","sources":["../src/rehype.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,+DAA+D;AAC/D,EAAE;AACF,gFAAgF;AAChF,4EAA4E;AAC5E,4EAA4E;AAC5E,+EAA+E;AAC/E,8EAA8E;AAC9E,6EAA6E;AAC7E,8EAA8E;AAC9E,4EAA4E;AAC5E,4CAA4C;AAG5C,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAiB,MAAM,iBAAiB,CAAC;AAEpF,6FAA6F;AAC7F,MAAM,CAAC,OAAO,UAAU,uBAAuB;IAC7C,OAAO,CAAC,IAAI,EAAE,EAAE;QACd,MAAM,KAAK,GAAG,SAAS,CAAC,IAAgB,CAAC,CAAC;QAC1C,MAAM,OAAO,GAAG,WAAW,CAAC,IAAgB,CAAC,CAAC;QAC9C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QACvD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAY,CAAC;QACpC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,KAAK,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;gBAClD,MAAM,UAAU,GAAG,CAAC,IAAI,CAAC,UAAU,KAAK,EAAE,CAAC,CAAC;gBAC5C,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;oBACnC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC;oBAC5C,UAAU,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;gBAC3B,CAAC;YACH,CAAC;YACD,IAAI,MAAM,CAAC,OAAO;gBAAE,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;YACrE,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,MAAM;gBAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACtD,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,UAAU,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,KAAK,EAAE,CAAC,CAAC;YACnD,KAAK,MAAM,SAAS,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;gBACxC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC;gBAC5C,UAAU,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;YAC3B,CAAC;YACD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,MAAM;gBAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAClD,KAAK,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBACxC,IAAI,KAAK,KAAK,EAAE;oBAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;;oBAC/B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;YAC1B,CAAC;QACH,CAAC;QACD,SAAS,CAAC,IAAgB,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,IAAc,EAAE,OAAsB;IACvD,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;QAAE,OAAO;IACxC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;IACrE,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ;QAAE,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;AAC/D,CAAC"}

package/dist/review/devfile.d.ts

@@ -0,0 +1,21 @@
+import type { AddressInfo } from "node:net";
+/** What `dev.json` holds. */
+export interface DevFile {
+    /** The site's address: origin and base path, `http://localhost:4321/docs/`. */
+    url: string;
+    /** The build the dev server shows. */
+    build: string;
+    /** The dev server's process, so another server's file isn't removed. */
+    pid: number;
+}
+/** `<project>/.ascribe/dev.json`. */
+export declare function devFilePath(projectDir: string): string;
+/** The site's address from the server's: a wildcard or loopback host is `localhost`. */
+export declare function siteUrl(address: AddressInfo, options: {
+    https: boolean;
+    base: string;
+}): string;
+/** Writes `dev.json`. A failure is the caller's to log: it only costs the editor its link. */
+export declare function writeDevFile(projectDir: string, file: DevFile): void;
+/** Removes `dev.json` if this process wrote it. */
+export declare function removeDevFile(projectDir: string, pid: number): void;

package/dist/review/devfile.js

@@ -0,0 +1,39 @@
+// `.ascribe/dev.json`: where the dev server is, for the editor's Open Site
+// Preview. Written when the server starts, removed when it stops. A server
+// that crashed leaves it behind, so a reader checks the URL answers first.
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+/** `<project>/.ascribe/dev.json`. */
+export function devFilePath(projectDir) {
+    return path.join(projectDir, ".ascribe", "dev.json");
+}
+/** The site's address from the server's: a wildcard or loopback host is `localhost`. */
+export function siteUrl(address, options) {
+    let host = address.address;
+    if (["::", "0.0.0.0", "::1", "", "localhost"].includes(host))
+        host = "localhost";
+    else if (host.includes(":"))
+        host = `[${host}]`;
+    const base = options.base.endsWith("/") ? options.base : `${options.base}/`;
+    return `${options.https ? "https" : "http"}://${host}:${address.port}${base.startsWith("/") ? base : `/${base}`}`;
+}
+/** Writes `dev.json`. A failure is the caller's to log: it only costs the editor its link. */
+export function writeDevFile(projectDir, file) {
+    const target = devFilePath(projectDir);
+    mkdirSync(path.dirname(target), { recursive: true });
+    writeFileSync(target, `${JSON.stringify(file, null, 2)}\n`);
+}
+/** Removes `dev.json` if this process wrote it. */
+export function removeDevFile(projectDir, pid) {
+    const target = devFilePath(projectDir);
+    try {
+        const current = JSON.parse(readFileSync(target, "utf8"));
+        if (current.pid !== pid)
+            return;
+    }
+    catch {
+        return;
+    }
+    rmSync(target, { force: true });
+}
+//# sourceMappingURL=devfile.js.map

package/dist/review/devfile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"devfile.js","sourceRoot":"","sources":["../../src/review/devfile.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,2EAA2E;AAC3E,2EAA2E;AAC3E,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEzE,OAAO,IAAI,MAAM,WAAW,CAAC;AAY7B,qCAAqC;AACrC,MAAM,UAAU,WAAW,CAAC,UAAkB;IAC5C,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC;AACvD,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,OAAO,CAAC,OAAoB,EAAE,OAAyC;IACrF,IAAI,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC;IAC3B,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,IAAI,GAAG,WAAW,CAAC;SAC5E,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,IAAI,GAAG,IAAI,IAAI,GAAG,CAAC;IAChD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,GAAG,CAAC;IAC5E,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,MAAM,IAAI,IAAI,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;AACpH,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,YAAY,CAAC,UAAkB,EAAE,IAAa;IAC5D,MAAM,MAAM,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;IACvC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACrD,aAAa,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;AAC9D,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,aAAa,CAAC,UAAkB,EAAE,GAAW;IAC3D,MAAM,MAAM,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;IACvC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAqB,CAAC;QAC7E,IAAI,OAAO,CAAC,GAAG,KAAK,GAAG;YAAE,OAAO;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;IACD,MAAM,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAClC,CAAC"}

package/dist/review/diff.d.ts

@@ -0,0 +1,21 @@
+import type { DiffBase, DiffPage } from "./protocol.js";
+/** One build's changes against a base. */
+export interface DiffResult {
+    base: DiffBase;
+    pages: DiffPage[];
+    /** How many errors `ascribe check` finds in the working tree for the build. */
+    errors: number;
+}
+/**
+ * Compares the build's pages with `base` (the default branch when it's
+ * `undefined`). Rejects with `ascribe diff`'s reason as the message.
+ */
+export declare function runDiff(options: {
+    binary: string;
+    configPath: string;
+    build: string;
+    cwd: string;
+    base: string | undefined;
+}): Promise<DiffResult>;
+/** The build's part of `ascribe diff --format json`'s output. */
+export declare function parseDiff(json: string, build: string): DiffResult;

package/dist/review/diff.js

@@ -0,0 +1,47 @@
+// Running `ascribe diff --format json` for the integration's build.
+import { execFile } from "node:child_process";
+/**
+ * Compares the build's pages with `base` (the default branch when it's
+ * `undefined`). Rejects with `ascribe diff`'s reason as the message.
+ */
+export function runDiff(options) {
+    const args = [
+        "diff",
+        "--format",
+        "json",
+        "--build",
+        options.build,
+        "--config",
+        options.configPath,
+        "--color",
+        "never",
+    ];
+    if (options.base !== undefined)
+        args.push("--base", options.base);
+    return new Promise((resolve, reject) => {
+        execFile(options.binary, args, { cwd: options.cwd, maxBuffer: 256 * 1024 * 1024, windowsHide: true }, (error, stdout, stderr) => {
+            if (error !== null) {
+                const reason = stderr.trim();
+                reject(new Error(reason === "" ? error.message : reason, { cause: error }));
+                return;
+            }
+            try {
+                resolve(parseDiff(stdout, options.build));
+            }
+            catch (cause) {
+                reject(new Error("`ascribe diff` wrote output that isn't its JSON.", { cause }));
+            }
+        });
+    });
+}
+/** The build's part of `ascribe diff --format json`'s output. */
+export function parseDiff(json, build) {
+    const report = JSON.parse(json);
+    if (report.base === undefined || !Array.isArray(report.builds)) {
+        throw new Error("not a diff report");
+    }
+    const pages = report.builds.find((b) => b.build === build)?.pages ?? [];
+    const errors = typeof report.working_tree_errors === "number" ? report.working_tree_errors : 0;
+    return { base: report.base, pages, errors };
+}
+//# sourceMappingURL=diff.js.map

package/dist/review/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.js","sourceRoot":"","sources":["../../src/review/diff.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAW9C;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,OAMvB;IACC,MAAM,IAAI,GAAG;QACX,MAAM;QACN,UAAU;QACV,MAAM;QACN,SAAS;QACT,OAAO,CAAC,KAAK;QACb,UAAU;QACV,OAAO,CAAC,UAAU;QAClB,SAAS;QACT,OAAO;KACR,CAAC;IACF,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,QAAQ,CACN,OAAO,CAAC,MAAM,EACd,IAAI,EACJ,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,EACrE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;YACxB,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;gBAC7B,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;gBAC5E,OAAO;YACT,CAAC;YACD,IAAI,CAAC;gBACH,OAAO,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;YAC5C,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,CAAC,IAAI,KAAK,CAAC,kDAAkD,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;YACnF,CAAC;QACH,CAAC,CACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,KAAa;IACnD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAI7B,CAAC;IACF,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;QAC/D,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;IACvC,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,EAAE,KAAK,IAAI,EAAE,CAAC;IACxE,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,mBAAmB,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/F,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AAC9C,CAAC"}

package/dist/review/github.d.ts

@@ -0,0 +1,19 @@
+import type { ReviewSession } from "@ascribed/review/github";
+import type { LocalState, ThreadsState } from "./protocol.js";
+/** A project's connection to its pull request: a session, or why there's none. */
+export type Connection = {
+    state: "on";
+    session: ReviewSession;
+    /** The git revision for the pull request's base: `origin/main`. */
+    base: string;
+    local: {
+        state: LocalState;
+        behind: number;
+        ahead: number;
+    };
+} | Exclude<ThreadsState, {
+    state: "on";
+}>;
+/** Finds the checkout's pull request and opens a review of it with the GitHub CLI's sign-in. */
+export declare function connect(projectDir: string): Promise<Connection>;
+export declare function messageOf(error: unknown): string;

package/dist/review/github.js

@@ -0,0 +1,73 @@
+// The pull request's review, through the GitHub CLI: `@ascribed/review`'s
+// session with `ghTransport`, found for the project's checkout. Loaded only
+// when review starts, so `astro build` never reads it.
+import { execFile } from "node:child_process";
+const CHANGES_ONLY = "Showing changes only.";
+/** Finds the checkout's pull request and opens a review of it with the GitHub CLI's sign-in. */
+export async function connect(projectDir) {
+    const github = await import("@ascribed/review/github");
+    let checkout;
+    try {
+        checkout = await github.readCheckout(projectDir);
+    }
+    catch {
+        return {
+            state: "no-pull-request",
+            message: `${CHANGES_ONLY} Comments need a git checkout with a pull request on GitHub.`,
+        };
+    }
+    const host = checkout.bases[0]?.host;
+    if (host === undefined) {
+        return {
+            state: "no-pull-request",
+            message: `${CHANGES_ONLY} Comments need the branch pushed to GitHub, with a pull request.`,
+        };
+    }
+    let session;
+    try {
+        session = await github.openReview({ projectDir });
+    }
+    catch (error) {
+        const code = error instanceof github.ReviewError ? error.code : undefined;
+        if (code === "gh-missing" || code === "gh-too-old") {
+            return {
+                state: "gh-missing",
+                message: `${CHANGES_ONLY} Comments need the GitHub CLI: install gh, run \`gh auth login\`, then Refresh.`,
+            };
+        }
+        if (code === "not-signed-in") {
+            return {
+                state: "signed-out",
+                message: `${CHANGES_ONLY} Comments need GitHub: run \`gh auth login --hostname ${host}\`, then Refresh.`,
+            };
+        }
+        // The first line: what `gh` or GitHub said, without any trace after it.
+        return { state: "error", message: messageOf(error).split("\n")[0] ?? "" };
+    }
+    if (session === undefined) {
+        return {
+            state: "no-pull-request",
+            message: `${CHANGES_ONLY} This branch has no open pull request: open one to comment here, then Refresh.`,
+        };
+    }
+    const pr = session.pullRequest;
+    return {
+        state: "on",
+        session,
+        base: await github.baseRevision(checkout.root, pr),
+        local: { state: pr.local, ...(await aheadBehind(checkout.root, pr.headOid)) },
+    };
+}
+/** How many commits `HEAD` is ahead of and behind the pull request's head. */
+function aheadBehind(root, head) {
+    return new Promise((resolve) => {
+        execFile("git", ["rev-list", "--left-right", "--count", `HEAD...${head}`], { cwd: root, timeout: 15_000, windowsHide: true, encoding: "utf8" }, (error, stdout) => {
+            const [ahead, behind] = (error ? "" : stdout).trim().split(/\s+/).map(Number);
+            resolve({ ahead: ahead || 0, behind: behind || 0 });
+        });
+    });
+}
+export function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=github.js.map

package/dist/review/github.js.map

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

package/dist/review/protocol.d.ts

@@ -0,0 +1,98 @@
+import type { Change } from "@ascribed/review/marks";
+/** A block change, as `ascribe diff --format json` reports it and the marks take it. */
+export type { Change };
+/** The toolbar app's id, also the prefix of its events. */
+export declare const APP_ID = "ascribe:review";
+export declare const REQUEST_EVENT = "ascribe:review:request";
+export declare const RESULT_EVENT = "ascribe:review:result";
+export declare const CHANGED_EVENT = "ascribe:review:changed";
+/** What the page asks for, besides the overlay's own requests (`OverlayMethod`). */
+export type AppMethod = "status" | "start" | "stop" | "page" | "refresh";
+export interface Request {
+    /** The page's own id, made when it loads. */
+    tab: string;
+    id: number;
+    method: string;
+    params: Record<string, unknown>;
+}
+export interface Result {
+    tab: string;
+    id: number;
+    result?: unknown;
+    error?: {
+        message: string;
+        code?: string;
+    };
+}
+export interface Counts {
+    changed: number;
+    added: number;
+    removed: number;
+    moved: number;
+}
+/** A changed page, as `ascribe diff --format json` lists it. */
+export interface DiffPage {
+    path: string;
+    route: string;
+    status: "added" | "removed" | "changed";
+    own_file_changed: boolean;
+    because: string[];
+    page_changed: string[];
+    counts: Counts;
+    changes: Change[];
+}
+/** A changed page in the list: without its changes, and with its title when the build has it. */
+export type ChangedPage = Omit<DiffPage, "changes"> & {
+    title: string | null;
+};
+/** The base compared with, as `ascribe diff` reports it. */
+export interface DiffBase {
+    requested: string;
+    commit: string;
+    merge_base: string | null;
+}
+/** How the checkout's `HEAD` relates to the pull request's head commit. */
+export type LocalState = "same" | "behind" | "ahead" | "diverged" | "missing";
+/** The review threads: on, or why not, with a sentence to show. */
+export type ThreadsState = {
+    state: "on";
+    pullRequest: {
+        number: number;
+        url: string;
+        baseRefName: string;
+    };
+    local: {
+        state: LocalState;
+        behind: number;
+        ahead: number;
+    };
+}
+/** No pull request, no GitHub CLI, no sign-in, a channel other pages could use, or a failure. */
+ | {
+    state: "no-pull-request" | "gh-missing" | "signed-out" | "unprotected" | "error";
+    message: string;
+};
+/** `status`'s answer. */
+export interface Status {
+    on: boolean;
+}
+/** `page`'s answer: what the app shows for the page at a route. */
+export interface PageView {
+    /** `"page"` for a page of the Ascribe build, `"not-page"` for the site's own routes. */
+    kind: "page" | "not-page";
+    /** The page's content path; `null` for a route that isn't one. */
+    path: string | null;
+    /** The page's changes; `null` when it didn't change. */
+    page: DiffPage | null;
+    base: DiffBase | null;
+    /** Why the changes couldn't be read, when they couldn't. */
+    problem: string | null;
+    /** How many errors `ascribe check` finds in the working tree for the build. */
+    errors: number;
+    threads: ThreadsState;
+    /** The build's changed pages, in path order. */
+    changedPages: ChangedPage[];
+    /** The content root, absolute, and the platform's path separator: for opening a source file. */
+    contentRoot: string;
+    separator: string;
+}

package/dist/review/protocol.js

@@ -0,0 +1,14 @@
+// The messages between the toolbar app (in the page) and the dev server,
+// over Astro's dev toolbar channel. Types only: both sides import them.
+//
+// The page sends `ascribe:review:request` with `{ tab, id, method, params }`;
+// the server answers that page with `ascribe:review:result` and the same
+// `tab` and `id`. When a page's request changes the threads, or review stops,
+// the server tells every page with `ascribe:review:changed`, naming the
+// `from` tab, which already knows.
+/** The toolbar app's id, also the prefix of its events. */
+export const APP_ID = "ascribe:review";
+export const REQUEST_EVENT = "ascribe:review:request";
+export const RESULT_EVENT = "ascribe:review:result";
+export const CHANGED_EVENT = "ascribe:review:changed";
+//# sourceMappingURL=protocol.js.map

package/dist/review/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/review/protocol.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,wEAAwE;AACxE,EAAE;AACF,8EAA8E;AAC9E,yEAAyE;AACzE,8EAA8E;AAC9E,wEAAwE;AACxE,mCAAmC;AAOnC,2DAA2D;AAC3D,MAAM,CAAC,MAAM,MAAM,GAAG,gBAAgB,CAAC;AACvC,MAAM,CAAC,MAAM,aAAa,GAAG,wBAAwB,CAAC;AACtD,MAAM,CAAC,MAAM,YAAY,GAAG,uBAAuB,CAAC;AACpD,MAAM,CAAC,MAAM,aAAa,GAAG,wBAAwB,CAAC"}

package/dist/review/routes.d.ts

@@ -0,0 +1,13 @@
+/** A route as compared: decoded, without a trailing `/` (except the root's). */
+export declare function normalizeRoute(route: string): string;
+/** A page of the build, as its JSON output names it. */
+export interface RoutedPage {
+    /** The content path. */
+    path: string;
+    title: string | null;
+}
+/**
+ * Every page of the build's JSON output (`<output-dir>/<build>/json/`), by
+ * normalized route. Empty when there's no JSON output.
+ */
+export declare function readRoutes(jsonRoot: string): Promise<Map<string, RoutedPage>>;

package/dist/review/routes.js

@@ -0,0 +1,92 @@
+// Which page of the build is at a route, and its title: read from the JSON
+// output, which the dev server writes while review is on, since the site
+// output doesn't say.
+import { open, readFile } from "node:fs/promises";
+import path from "node:path";
+/** A route as compared: decoded, without a trailing `/` (except the root's). */
+export function normalizeRoute(route) {
+    let decoded;
+    try {
+        decoded = decodeURI(route);
+    }
+    catch {
+        decoded = route;
+    }
+    const trimmed = (decoded.split(/[?#]/)[0] ?? "").replace(/\/+$/, "");
+    return trimmed === "" ? "/" : trimmed;
+}
+/** How much of a page's JSON to read: its `path`, `route`, and `title` come first. */
+const HEAD_BYTES = 4096;
+/**
+ * Every page of the build's JSON output (`<output-dir>/<build>/json/`), by
+ * normalized route. Empty when there's no JSON output.
+ */
+export async function readRoutes(jsonRoot) {
+    const routes = new Map();
+    let files;
+    try {
+        const manifest = JSON.parse(await readFile(path.join(path.dirname(jsonRoot), "json.manifest.json"), "utf8"));
+        files = Array.isArray(manifest.files) ? manifest.files : [];
+    }
+    catch {
+        return routes;
+    }
+    await Promise.all(files.map(async (entry) => {
+        if (entry.kind !== "page" || typeof entry.path !== "string")
+            return;
+        const page = await readHead(path.join(jsonRoot, ...entry.path.split("/")));
+        if (page)
+            routes.set(normalizeRoute(page.route), { path: page.path, title: page.title });
+    }));
+    return routes;
+}
+/** A page's `path`, `route`, and `title`, from the start of its JSON, or the whole of it if need be. */
+async function readHead(file) {
+    let head = "";
+    try {
+        const handle = await open(file, "r");
+        try {
+            const buffer = Buffer.alloc(HEAD_BYTES);
+            const { bytesRead } = await handle.read(buffer, 0, HEAD_BYTES, 0);
+            head = buffer.subarray(0, bytesRead).toString("utf8");
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return undefined;
+    }
+    const field = (name) => {
+        const match = new RegExp(`"${name}"\\s*:\\s*("(?:[^"\\\\]|\\\\.)*")`).exec(head);
+        if (!match?.[1])
+            return undefined;
+        try {
+            return JSON.parse(match[1]);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    // The page's own keys come before `frontmatter`, so the first of each is the page's.
+    const pagePath = field("path");
+    const route = field("route");
+    const title = field("title");
+    if (pagePath !== undefined && route !== undefined && title !== undefined) {
+        return { path: pagePath, route, title };
+    }
+    try {
+        const page = JSON.parse(await readFile(file, "utf8"));
+        return typeof page.path === "string" && typeof page.route === "string"
+            ? {
+                path: page.path,
+                route: page.route,
+                title: typeof page.title === "string" ? page.title : null,
+            }
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=routes.js.map

package/dist/review/routes.js.map

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

package/dist/review/server.d.ts

@@ -0,0 +1,100 @@
+import type { DiffResult } from "./diff.js";
+import { type Connection } from "./github.js";
+import { type RoutedPage } from "./routes.js";
+/** A page's end of the channel: the server answers it alone. */
+export interface ChannelClient {
+    send(event: string, payload?: unknown): void;
+}
+/**
+ * The toolbar's channel, as `astro:server:setup`'s `toolbar` has it. Its
+ * listeners get the sending page's client too (it is Vite's `server.hot`);
+ * without one, an answer goes to every page, which tell theirs by `tab`.
+ */
+export interface ToolbarChannel {
+    on(event: string, callback: (data: unknown, client?: ChannelClient) => void): void;
+    send(event: string, payload: unknown): void;
+}
+export interface ReviewServerOptions {
+    channel: ToolbarChannel;
+    logger: {
+        info(message: string): void;
+        warn(message: string): void;
+    };
+    build: string;
+    /** The content root, absolute. */
+    contentRoot: string;
+    /** Why someone else could use the channel, if they could: then GitHub stays off. */
+    channelProblem: string | undefined;
+    /** Compares the build with `base` (the default branch when `undefined`). */
+    diff(base: string | undefined): Promise<DiffResult>;
+    /** Opens the pull request's review. */
+    connect(): Promise<Connection>;
+    /** Writes the build's JSON output, in turn with the dev server's builds: it has the routes. */
+    writeRoutes(): Promise<void>;
+    /** Every page of the build, by normalized route. */
+    readRoutes(): Promise<Map<string, RoutedPage>>;
+    /** How long to wait after a rebuild before comparing again. Default 150 ms. */
+    debounceMs?: number;
+}
+export declare class ReviewServer {
+    private readonly options;
+    private on;
+    private problem;
+    private connection;
+    private connecting;
+    private diffed;
+    private diffing;
+    private stale;
+    private timer;
+    private routes;
+    /** The page each overlay last read, by content path: comments are made on it. */
+    private readonly pages;
+    /** How long the last comparison took, in milliseconds. */
+    lastDiffMs: number | undefined;
+    constructor(options: ReviewServerOptions);
+    /**
+     * The address the dev server listens on, once it does: one other machines
+     * can reach turns comments off, as `server.host` does.
+     */
+    listening(address: string): void;
+    /** Whether review is on: then the dev server's builds write JSON output too. */
+    get active(): boolean;
+    /** The dev server rebuilt: compare again soon, and read the routes again when asked. */
+    rebuilt(): void;
+    /** The dev server stopped. */
+    dispose(): void;
+    private receive;
+    /** Answers one request. Rejects with a sentence to show. */
+    handle(method: string, params: Record<string, unknown>, tab?: string): Promise<unknown>;
+    private start;
+    private stop;
+    private refresh;
+    /** The pull request's review, opened once while review is on. */
+    private connected;
+    /** The build's changes, compared again first if a rebuild made them stale. */
+    private changes;
+    private compare;
+    private pageView;
+    /** Tells every page the threads or the changes changed; `from` is the page that did it. */
+    private changed;
+}
+/**
+ * Why someone other than the developer could use the dev server's toolbar
+ * channel, or `undefined` when they can't. Vite takes a browser's connection
+ * only with the token in its client script, which the page's own origin can
+ * read and, by default, only localhost origins can fetch. These settings undo
+ * that, and a server listening on the network gives its pages, token and all,
+ * to anyone who can reach it.
+ */
+export declare function channelProblem(config: {
+    server: {
+        cors?: unknown;
+        allowedHosts?: unknown;
+        host?: unknown;
+    };
+    legacy?: {
+        skipWebSocketTokenCheck?: unknown;
+    } | undefined;
+}): string | undefined;
+/** Whether Vite's `server.host`, or the address the server listens on, keeps the server on this machine: unset, `false`, or a loopback name. */
+export declare function isLoopback(host: unknown): boolean;