diffninja 0.1.0

package/dist/review/connected.d.ts

@@ -0,0 +1,23 @@
+import { type Server } from "node:http";
+import { ConnectedReview } from "./github.js";
+import type { ConnectedAnalysisView } from "./connected-analysis.js";
+export interface ConnectedSession {
+    server: Server;
+    url: string;
+}
+/** Read-only extras a connected session can serve beside the review itself. */
+export interface ConnectedOptions {
+    /**
+     * The local analysis of the loaded snapshot, for `GET /api/analysis`. It must
+     * describe the snapshot the review currently holds, or say it is unavailable.
+     */
+    readonly analysis?: () => Promise<ConnectedAnalysisView>;
+    /**
+     * The call-flow page of the analysis of snapshot `snapshotId`, for one changed
+     * file or all of them, for `GET /flow`. Undefined when that snapshot is not
+     * the one analyzed or it has no call flows there.
+     */
+    readonly flow?: (snapshotId: string, file: string | undefined) => Promise<string | undefined>;
+}
+/** A single ephemeral session; never exposes a general GitHub API proxy. */
+export declare function serveConnected(review?: ConnectedReview, options?: ConnectedOptions): Promise<ConnectedSession>;

package/dist/review/connected.js

@@ -0,0 +1,141 @@
+import { createServer } from "node:http";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { z } from "zod";
+import { ConnectedReview } from "./github.js";
+import { renderConnectedPage } from "./connected-html.js";
+import { reportPolicy } from "./report-pages.js";
+const MAX_BODY = 256 * 1024;
+const loadSchema = z.object({ url: z.string() }).strict();
+const reviewSchema = z.object({
+    snapshotId: z.string(), event: z.enum(["COMMENT", "APPROVE", "REQUEST_CHANGES"]), body: z.string(),
+    comments: z.array(z.object({ path: z.string(), line: z.number().int().positive(), side: z.enum(["LEFT", "RIGHT"]), body: z.string() }).strict()),
+}).strict();
+const emptySchema = z.object({}).strict();
+const tokenSchema = z.string().regex(/^[a-f0-9]{64}$/);
+const NO_ANALYSIS = {
+    available: false,
+    reason: "No local analysis is attached to this session.",
+};
+async function readBody(req) {
+    if (req.headers["content-type"] !== "application/json")
+        throw new Error("Expected application/json.");
+    const chunks = [];
+    let length = 0;
+    for await (const chunk of req) {
+        length += chunk.length;
+        if (length > MAX_BODY)
+            throw new Error("Request exceeds 256 KiB.");
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+/**
+ * Loopback-only guard. The request must name this session's exact host, must
+ * not carry a foreign `Origin`, and must not announce a cross-site fetch. A
+ * browser page on another origin can produce none of these headers honestly.
+ */
+function requestIsTrusted(req, origin) {
+    if (req.headers.host !== new URL(origin).host)
+        return false;
+    if (req.headers.origin !== undefined && req.headers.origin !== origin)
+        return false;
+    const site = req.headers["sec-fetch-site"];
+    return !site || ["same-origin", "none"].includes(String(site));
+}
+/** A single ephemeral session; never exposes a general GitHub API proxy. */
+export async function serveConnected(review = new ConnectedReview(), options = {}) {
+    const csrf = randomBytes(32).toString("hex");
+    let origin = "";
+    const server = createServer(async (req, res) => {
+        res.setHeader("Cache-Control", "no-store");
+        res.setHeader("X-Content-Type-Options", "nosniff");
+        res.setHeader("X-Frame-Options", "DENY");
+        res.setHeader("Referrer-Policy", "no-referrer");
+        res.setHeader("Content-Security-Policy", `default-src 'none'; script-src 'nonce-${csrf}'; style-src 'nonce-${csrf}'; connect-src 'self'; frame-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'`);
+        const json = (code, value) => { res.writeHead(code, { "Content-Type": "application/json" }); res.end(JSON.stringify(value)); };
+        if (!requestIsTrusted(req, origin)) {
+            json(403, { error: "Untrusted Host or Origin." });
+            return;
+        }
+        if (req.method === "GET" && req.url === "/") {
+            res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+            res.end(renderConnectedPage(csrf));
+            return;
+        }
+        if (req.method === "GET" && req.url === "/api/state") {
+            json(200, review.getState());
+            return;
+        }
+        if (req.method === "GET" && req.url === "/api/analysis") {
+            try {
+                json(200, options.analysis === undefined ? NO_ANALYSIS : await options.analysis());
+            }
+            catch (error) {
+                json(200, { available: false, reason: `Local analysis failed: ${error instanceof Error ? error.message : "unknown error"}` });
+            }
+            return;
+        }
+        if (req.method === "GET" && (req.url ?? "").startsWith("/flow?")) {
+            const query = new URL(req.url ?? "", origin).searchParams;
+            const snapshotId = query.get("snapshot") ?? "";
+            const file = query.get("file") ?? undefined;
+            let html;
+            try {
+                html = options.flow === undefined ? undefined : await options.flow(snapshotId, file);
+            }
+            catch {
+                html = undefined;
+            }
+            if (html === undefined) {
+                json(404, { error: "No call flow for that revision and file." });
+                return;
+            }
+            // Only this page may frame it: the drawer beside the diff.
+            res.setHeader("Content-Security-Policy", reportPolicy(html).replace("frame-ancestors 'none'", "frame-ancestors 'self'"));
+            res.setHeader("X-Frame-Options", "SAMEORIGIN");
+            res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+            res.end(html);
+            return;
+        }
+        const routes = ["/api/load", "/api/preview", "/api/submit", "/api/reconcile"];
+        if (req.method !== "POST" || !routes.includes(req.url ?? "")) {
+            json(404, { error: "Not found." });
+            return;
+        }
+        const token = tokenSchema.safeParse(req.headers["x-diffninja-csrf"]);
+        if (req.headers.origin !== origin || !token.success || !timingSafeEqual(Buffer.from(token.data), Buffer.from(csrf))) {
+            json(403, { error: "Invalid session or CSRF token." });
+            return;
+        }
+        try {
+            const text = await readBody(req);
+            let result;
+            switch (req.url) {
+                case "/api/load":
+                    result = await review.load(loadSchema.parse(JSON.parse(text)).url);
+                    break;
+                case "/api/preview":
+                    result = await review.preview(reviewSchema.parse(JSON.parse(text)));
+                    break;
+                case "/api/submit":
+                    result = await review.submit(reviewSchema.parse(JSON.parse(text)));
+                    break;
+                default:
+                    emptySchema.parse(JSON.parse(text));
+                    result = await review.reconcile();
+                    break;
+            }
+            json(200, result);
+        }
+        catch (error) {
+            const message = error instanceof z.ZodError ? "Invalid request fields: " + error.issues.map(issue => issue.path.join(".") || "input").join(", ") : error instanceof Error ? error.message : "Request failed.";
+            json(400, { error: message, state: review.getState() });
+        }
+    });
+    server.requestTimeout = 15_000;
+    server.headersTimeout = 10_000;
+    await new Promise((resolve, reject) => { server.once("error", reject); server.listen(0, "127.0.0.1", () => { server.removeListener("error", reject); resolve(); }); });
+    const address = z.object({ port: z.number().int().positive() }).parse(server.address());
+    origin = `http://127.0.0.1:${address.port}`;
+    return { server, url: origin + "/" };
+}

package/dist/review/escape-html.d.ts

@@ -0,0 +1,2 @@
+/** Escape untrusted text for HTML element and attribute contexts. */
+export declare function escapeHtml(text: string): string;

package/dist/review/escape-html.js

@@ -0,0 +1,9 @@
+/** Escape untrusted text for HTML element and attribute contexts. */
+export function escapeHtml(text) {
+    return text
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}

package/dist/review/evidence-html.d.ts

@@ -0,0 +1,21 @@
+import type { ReviewReport } from "./types.js";
+/**
+ * The opening view of a review report: what the pull request says it does, what
+ * the gathered evidence actually established, the short reading agenda, and the
+ * automatic findings with the source behind them.
+ *
+ * Every string is a fixed template or escaped report data. The pull request
+ * title, description and evidence text are untrusted input: they are escaped
+ * into text nodes and never reach the page script. No numeric priority, model
+ * probability or judgment value is printed here, and no check is described as
+ * passing: a check states the scope it ran over and where its certainty ends,
+ * and a finding carries its own limitation.
+ *
+ * The order is the reading order: outcome first, then the checks that ran and
+ * what they did not cover, then the agenda, then the findings the agenda points
+ * at. One piece of evidence is rendered once — an excerpt a finding already
+ * carries is linked from the agenda instead of repeated, and a definition cited
+ * by two agenda entries is shown in the first and linked from the second.
+ */
+export declare function renderBrief(report: ReviewReport): string;
+export declare const BRIEF_STYLES = "\n.brief { display: flex; flex-direction: column; gap: 7px; }\n.brief > h2 { font-size: 13.5px; text-transform: uppercase; letter-spacing: 0.1em; color: var(--accent); margin-top: 7px; }\n.brief > h2:first-child { margin-top: 0; }\n.brief h3 { font-size: 13px; color: var(--ink-soft); font-weight: 600; }\n.pr-facts { display: grid; grid-template-columns: max-content minmax(0, 1fr); gap: 4px 12px; margin: 0; }\n.pr-facts dt { font-size: 12px; color: var(--ink-soft); }\n.pr-facts dd { margin: 0; min-width: 0; overflow-wrap: anywhere; }\n.pr-title { font-size: 17px; font-weight: 700; }\n.pr-body > summary { cursor: pointer; font-size: 12.5px; color: var(--ink-soft); }\n.pr-text {\n  margin: 6px 0 0;\n  padding: 9px 11px;\n  border: 1px solid var(--line);\n  border-radius: 6px;\n  background: var(--sunken);\n  font-family: var(--mono);\n  font-size: 12.5px;\n  line-height: 1.5;\n  white-space: pre-wrap;\n  overflow-wrap: anywhere;\n  max-height: 40vh;\n  overflow: auto;\n}\n.intent { border: 1px solid var(--line); border-left: 5px solid var(--line-strong); border-radius: 6px; padding: 10px 14px; background: var(--panel); }\n.intent-done { border-left-color: var(--teal); }\n.intent-warn { border-left-color: var(--warn); }\n.intent-summary { font-size: 14.5px; overflow-wrap: anywhere; }\n.intent-verdict { margin-bottom: 4px; }\n.ev-badge {\n  display: inline-flex;\n  align-items: center;\n  gap: 6px;\n  border: 1px solid var(--line-strong);\n  border-radius: 999px;\n  padding: 2px 10px;\n  font-size: 11.5px;\n  font-weight: 600;\n  white-space: nowrap;\n}\n.ev-badge-done { border-color: var(--teal); color: var(--teal); background: var(--teal-bg); }\n.ev-badge-warn { border-color: var(--warn); color: var(--warn); background: var(--warn-bg); }\n.claims, .checks, .findings, .evidence { list-style: none; margin: 5px 0 0; padding: 0; display: flex; flex-direction: column; gap: 6px; }\n.claim, .check, .finding, .ev-card { border: 1px solid var(--line); border-radius: 6px; padding: 6px 9px; background: var(--panel); }\n.claim-head, .check-head, .finding-head, .ev-head, .ag-head { display: flex; align-items: center; flex-wrap: wrap; gap: 8px; }\nsummary.ev-head, summary.check-head { cursor: pointer; }\nsummary.ev-head::before, summary.check-head::before { content: \"+\"; font-family: var(--mono); }\ndetails[open] > summary.ev-head::before, details[open] > summary.check-head::before { content: \"-\"; font-family: var(--mono); }\n.claim-origin, .ev-role, .finding-kind, .check-kind { font-size: 11.5px; font-weight: 700; letter-spacing: 0.06em; text-transform: uppercase; color: var(--ink-soft); }\n.claim-text, .ag-title, .finding-title { font-size: 14.5px; font-weight: 600; overflow-wrap: anywhere; }\n.claim-note, .ag-reason { font-size: 13px; color: var(--ink-soft); overflow-wrap: anywhere; }\n.check-detail, .finding-scope, .finding-limit, .ev-label, .ev-note, .ag-links, .finding-hunks, .claim-links {\n  font-size: 12.5px;\n  color: var(--ink-soft);\n  overflow-wrap: anywhere;\n  margin-top: 3px;\n}\n.finding-label { font-weight: 700; text-transform: uppercase; letter-spacing: 0.06em; font-size: 11px; }\n.ev-where, .ev-ref { font-size: 12px; color: var(--ink-soft); overflow-wrap: anywhere; }\n.ev-card { background: var(--sunken); }\n.ev-code {\n  margin: 6px 0 0;\n  padding: 7px 9px;\n  border: 1px solid var(--line);\n  border-radius: 6px;\n  background: var(--panel);\n  font-family: var(--mono);\n  font-size: 12px;\n  line-height: 1.5;\n  max-height: 26vh;\n  overflow: auto;\n  tab-size: 4;\n}\n.ev-hunk { font-size: 12px; white-space: nowrap; }\n.agenda { list-style: none; counter-reset: agenda; margin: 6px 0 0; padding: 0; display: flex; flex-direction: column; gap: 8px; }\n.ag-card { border: 1px solid var(--line); border-left: 5px solid var(--line-strong); border-radius: 6px; padding: 9px 12px; background: var(--panel); }\n.ag-rank {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  min-width: 20px;\n  height: 20px;\n  border-radius: 999px;\n  background: var(--sunken);\n  border: 1px solid var(--line);\n  font-size: 11.5px;\n  font-weight: 700;\n  color: var(--ink-soft);\n}\n.ag-ctx-list { display: flex; flex-direction: column; gap: 4px; margin-top: 6px; }\n.ag-ctx > summary { cursor: pointer; font-size: 12.5px; color: var(--ink-soft); overflow-wrap: anywhere; }\n.ag-ctx { border: 1px dashed var(--line-strong); border-radius: 6px; padding: 6px 9px; }\n.ag-ctx-again { font-size: 12.5px; }\n.obligations { margin-top: 8px; }\n.obligations > summary { cursor: pointer; font-size: 12.5px; color: var(--ink-soft); }\n.obligations ul { margin: 6px 0 0; padding-left: 20px; font-size: 13px; }\n.obligations li { overflow-wrap: anywhere; }\n@media (max-width: 680px) {\n  .pr-facts { grid-template-columns: minmax(0, 1fr); gap: 0 0; }\n  .pr-facts dd { margin-bottom: 6px; }\n}\n";