@lchase/kiln 0.12.0 → 0.14.0

package/dist/jobs.js

@@ -102,6 +102,15 @@ export function writeJob(config, input) {
     });
     return { job, jsonPath };
 }
+/** Record a cancel on the job file. A second call leaves the file as it is. */
+export function markJobCancelled(config, job, now = new Date()) {
+    if (job.cancelledAt)
+        return job;
+    const next = JobSchema.parse({ ...job, cancelledAt: now.toISOString() });
+    const jsonPath = jobFilePath(config.jobsDir, job.id);
+    writeFileSync(jsonPath, `${JSON.stringify(next, null, 2)}\n`);
+    return next;
+}
 export function renderAddedJob(job, jsonPath) {
     const lines = [`added ${job.id}`, `repo ${job.repo}`, `workflow ${job.workflow}`, `spec ${job.spec}`];
     if (job.issue)

package/dist/markdown.js

@@ -0,0 +1,91 @@
+/**
+ * A small markdown subset for the board. Text is escaped before any tag is
+ * added, so a draft cannot inject HTML or a script. Links are http(s) only.
+ */
+export function renderMarkdown(src) {
+    const lines = src.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+    let index = 0;
+    let html = "";
+    while (index < lines.length) {
+        const line = lines[index] ?? "";
+        if (!line.trim()) {
+            index += 1;
+            continue;
+        }
+        if (line.startsWith("```")) {
+            const fence = [];
+            index += 1;
+            while (index < lines.length && !(lines[index] ?? "").startsWith("```")) {
+                fence.push(lines[index] ?? "");
+                index += 1;
+            }
+            index += 1;
+            html += `<pre><code>${escapeHtml(fence.join("\n"))}</code></pre>`;
+            continue;
+        }
+        const heading = /^(#{1,6})\s+(.*)$/.exec(line);
+        if (heading?.[1] && heading[2] !== undefined) {
+            const level = Math.min(heading[1].length, 3);
+            html += `<h${level}>${inline(heading[2])}</h${level}>`;
+            index += 1;
+            continue;
+        }
+        if (line.startsWith(">")) {
+            const quote = [];
+            while (index < lines.length && (lines[index] ?? "").startsWith(">")) {
+                quote.push((lines[index] ?? "").replace(/^>\s?/, ""));
+                index += 1;
+            }
+            html += `<blockquote>${inline(quote.join(" "))}</blockquote>`;
+            continue;
+        }
+        if (isList(line)) {
+            const ordered = /^\s*\d+\./.test(line);
+            const items = [];
+            while (index < lines.length && (isList(lines[index] ?? "") || (/^\s{2,}\S/.test(lines[index] ?? "") && items.length > 0))) {
+                const item = lines[index] ?? "";
+                index += 1;
+                if (isList(item))
+                    items.push(item.replace(/^\s*(?:[-*+]|\d+\.)\s+/, ""));
+                else
+                    items[items.length - 1] = `${items[items.length - 1]} ${item.trim()}`;
+            }
+            const tag = ordered ? "ol" : "ul";
+            html += `<${tag}>${items.map((item) => `<li>${inline(item)}</li>`).join("")}</${tag}>`;
+            continue;
+        }
+        const paragraph = [];
+        while (index < lines.length && (lines[index] ?? "").trim() && !isBlock(lines[index] ?? "")) {
+            paragraph.push(lines[index] ?? "");
+            index += 1;
+        }
+        html += `<p>${inline(paragraph.join(" "))}</p>`;
+    }
+    return html;
+}
+function isList(line) {
+    return /^\s*(?:[-*+]|\d+\.)\s+/.test(line);
+}
+function isBlock(line) {
+    return /^(?:#{1,6}\s|```|>)/.test(line) || isList(line);
+}
+function inline(raw) {
+    const codes = [];
+    const slotted = raw.replace(/`([^`]+)`/g, (_match, code) => {
+        codes.push(escapeHtml(code));
+        return `\u0000${codes.length - 1}\u0000`;
+    });
+    let html = escapeHtml(slotted);
+    html = html.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>");
+    html = html.replace(/(^|[^*])\*([^*\n]+)\*/g, "$1<em>$2</em>");
+    html = html.replace(/\[([^\]]+)\]\((https?:\/\/[^)\s]+)\)/g, '<a href="$2" rel="noopener noreferrer">$1</a>');
+    return html.replace(/\u0000(\d+)\u0000/g, (_match, slot) => `<code>${codes[Number(slot)] ?? ""}</code>`);
+}
+export function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}

package/dist/project.js

@@ -1,7 +1,8 @@
 import { createHash } from "node:crypto";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
-import { basename, join, relative, sep } from "node:path";
+import { basename, dirname, join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
 import { appendEvent } from "./events.js";
 import { costFromJournal, decideFailure } from "./failure.js";
 import { jobBasename, packageRoot } from "./paths.js";
@@ -24,7 +25,31 @@ export function projectRunJournal(input) {
         console.error(`kiln: event log: ${message}`);
     }
 }
+/**
+ * Version of the `@lchase/kiln` package that contains this file.
+ * Walks up from the running module so a parent package.json (the workspace
+ * root has none) cannot supply a stale or missing version.
+ */
 export function kilnVersion() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 8; i += 1) {
+        const pkgPath = join(dir, "package.json");
+        if (existsSync(pkgPath)) {
+            try {
+                const parsed = JSON.parse(readFileSync(pkgPath, "utf8"));
+                if (parsed.name === "@lchase/kiln" && typeof parsed.version === "string" && parsed.version) {
+                    return parsed.version;
+                }
+            }
+            catch {
+                // An unreadable file is not the running package. Keep walking.
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
     return packageVersion(join(packageRoot(), "package.json"));
 }
 export function yakVersion() {

package/dist/reconcile.js

@@ -35,6 +35,7 @@ function inFlight(job, observation) {
  * | launching breadcrumb | running |
  * | dependencies unmet | blocked |
  * | launch error | failed |
+ * | cancelled before start | cancelled |
  * | otherwise | queued |
  *
  * `deliver=local`: `done` is a finished run whose gate says approve.
@@ -51,6 +52,8 @@ export function jobState(job, observation) {
         return "in-review";
     if (job.launching && (!job.run || job.runRetired || job.fixInProgress))
         return "running";
+    if (job.cancelled && !job.run && !job.launching)
+        return "cancelled";
     if ((job.feedbackExhausted || job.feedbackAmbiguous) && isLanded(job) && !job.fixInProgress) {
         if (job.delivery?.merged || job.delivery?.prState === "MERGED")
             return "done";
@@ -165,7 +168,7 @@ function needsDelivery(job) {
     return true;
 }
 function canLaunch(job, observation) {
-    if (job.error || job.run || job.launching || job.launchFailed || job.fixInProgress)
+    if (job.cancelled || job.error || job.run || job.launching || job.launchFailed || job.fixInProgress)
         return false;
     return dependenciesMet(job, observation);
 }
@@ -177,7 +180,7 @@ function canStartFix(job) {
 }
 /** A recorded transient failure whose backoff has elapsed. One retry per tick, ahead of a new job. */
 function canRetry(job, observation, now) {
-    if (job.error || job.launching || job.retriesExhausted || job.stopReason || job.ledgerError)
+    if (job.cancelled || job.error || job.launching || job.retriesExhausted || job.stopReason || job.ledgerError)
         return false;
     if (job.run && !job.runRetired)
         return false;

package/dist/report.js

@@ -132,6 +132,10 @@ export function statusDetails(job) {
         lines.push(`findings ${job.findingsPath}`);
     else if (job.workflow === INVESTIGATION_WORKFLOW && job.state === "done")
         lines.push("findings missing");
+    if (job.reviewUrl)
+        lines.push(`review ${job.reviewUrl}`);
+    if (job.reviewPostError)
+        lines.push(job.reviewPostError);
     if (job.prPending)
         lines.push("pull request not opened yet");
     if (job.state === "failed" && job.deliveryError)
@@ -222,6 +226,8 @@ function toStatusJob(job, observation) {
             ...(job.specPath ? { specPath: job.specPath } : {}),
             ...(job.logPath ? { logPath: job.logPath } : {}),
             ...(job.findingsPath ? { findingsPath: job.findingsPath } : {}),
+            ...(job.reviewPostError ? { reviewPostError: job.reviewPostError } : {}),
+            ...(job.reviewUrl ? { reviewUrl: job.reviewUrl } : {}),
             launchFailed: job.launchFailed,
             attemptCount: job.attemptCount ?? 0,
             maxAttempts: job.attemptCap ?? observation.maxAttempts,
@@ -270,6 +276,8 @@ function toStatusJob(job, observation) {
         ...(job.logPath ? { logPath: job.logPath } : {}),
         ...(job.specPath ? { specPath: job.specPath } : {}),
         ...(job.findingsPath ? { findingsPath: job.findingsPath } : {}),
+        ...(job.reviewPostError ? { reviewPostError: job.reviewPostError } : {}),
+        ...(job.reviewUrl ? { reviewUrl: job.reviewUrl } : {}),
         launchFailed: job.launchFailed,
         attemptCount: job.attemptCount ?? 0,
         maxAttempts: job.attemptCap ?? observation.maxAttempts,

package/dist/review-post.js

@@ -0,0 +1,269 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { appendEvent, readEvents } from "./events.js";
+import { classifyFailureText } from "./failure.js";
+import { realGitHub } from "./host.js";
+import { redact } from "./redact.js";
+import { parseReviewSource } from "./triggers.js";
+/**
+ * A review draft the human has not posted yet, and the COMMENT review Kiln
+ * writes after they approve the Inbox gate.
+ *
+ * The review event is always COMMENT. Kiln does not approve, request
+ * changes, or merge. A second approve at the same `review:<repo>:<number>:<sha>`
+ * does not post again.
+ */
+export const REVIEW_SEVERITIES = ["note", "nit", "warning", "blocking"];
+const NEEDS_HUMAN_REASON = "review-post";
+/** Target of a review-request job, or undefined when the draft is not tied to a pull request. */
+export function reviewTargetFrom(repo, sourceRef) {
+    if (!sourceRef)
+        return undefined;
+    const parsed = parseReviewSource(sourceRef);
+    if (!parsed || parsed.repo !== repo)
+        return undefined;
+    return {
+        repo: parsed.repo,
+        number: parsed.number,
+        sha: parsed.sha,
+        dedupe: `review:${parsed.repo}:${parsed.number}:${parsed.sha}`,
+    };
+}
+export function reviewAlreadyPosted(events, dedupe) {
+    return events.some((event) => event.event === "review.posted" && event.properties.dedupe === dedupe);
+}
+/**
+ * Latest post for this job. A `review.posted` for the same dedupe, including
+ * one recorded on another job, counts as posted.
+ */
+export function reviewPostForJob(events, job) {
+    const dedupe = job.source?.kind === "trigger" ? reviewTargetFrom(job.repo, job.source.ref)?.dedupe : undefined;
+    let url;
+    let error;
+    for (const event of events) {
+        const posted = event.event === "review.posted" &&
+            (event.job_id === job.jobId || (dedupe !== undefined && event.properties.dedupe === dedupe));
+        if (posted) {
+            url = event.properties.url;
+            error = undefined;
+            continue;
+        }
+        if (event.event === "review.failed" && event.job_id === job.jobId) {
+            url = undefined;
+            error = `Could not post the review (${event.properties.class}). ${event.properties.detail}`;
+        }
+    }
+    return { ...(url ? { url } : {}), ...(error ? { error } : {}) };
+}
+/** The draft step's artifact. Missing or unreadable is undefined. Extra fields are ignored. */
+export function readReviewDraft(checkout, runId) {
+    const path = join(checkout, ".runs", runId, "artifacts", "draft.json");
+    if (!existsSync(path))
+        return undefined;
+    try {
+        return parseReviewDraft(JSON.parse(readFileSync(path, "utf8")));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function parseReviewDraft(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const markdown = value.markdown;
+    if (typeof markdown !== "string" || !markdown.trim())
+        return undefined;
+    const raw = value.findings;
+    const findings = [];
+    if (Array.isArray(raw)) {
+        for (const item of raw) {
+            const finding = parseFinding(item);
+            if (finding)
+                findings.push(finding);
+        }
+    }
+    return { markdown: markdown.trim(), findings };
+}
+/**
+ * Body is the draft markdown. Findings with a real file and line become
+ * inline comments. Anything else is folded into the body when the markdown
+ * does not already contain it. Line numbers are never invented.
+ */
+export function buildCommentReview(draft) {
+    const comments = [];
+    const skipped = [];
+    for (const finding of draft.findings) {
+        const path = commentPath(finding.file);
+        const line = commentLine(finding.line);
+        if (!path || line === undefined) {
+            skipped.push(finding);
+            continue;
+        }
+        comments.push({ path, line, body: commentText(finding) });
+    }
+    return {
+        body: redact(foldSkipped(draft.markdown, skipped)),
+        comments: comments.map((comment) => ({ ...comment, body: redact(comment.body) })),
+        findings: draft.findings.length,
+        inline: comments.length,
+        skipped: skipped.length,
+    };
+}
+/**
+ * Post the approved draft, or do nothing when that head SHA was already
+ * posted. Throws without calling gh when the factory is paused, the daily
+ * cap is blocking, or the post fails. The caller leaves the gate open on throw.
+ */
+export function postApprovedReview(input) {
+    const target = reviewTargetFrom(input.repo, input.sourceRef);
+    if (!target) {
+        recordNeedsHuman(input);
+        throw new Error("This review draft is not tied to a pull request, so Kiln will not post it.");
+    }
+    const events = readEvents(input.kilnDir, { warn: () => { } });
+    if (reviewAlreadyPosted(events, target.dedupe))
+        return;
+    if (input.paused) {
+        throw new Error("Paused. Kiln will not post this review until kiln resume.");
+    }
+    if (input.spendBlocked) {
+        throw new Error("Daily cap reached. Kiln will not post this review until the local day rolls over.");
+    }
+    const draft = readReviewDraft(input.checkout, input.runId);
+    if (!draft) {
+        failPost(input, target, "deterministic", "The draft artifact is missing or unreadable.");
+    }
+    const review = buildCommentReview(draft);
+    const poster = input.host.github.postCommentReview ?? realGitHub.postCommentReview;
+    if (!poster) {
+        failPost(input, target, "deterministic", "gh cannot post a review from this host.");
+    }
+    let posted;
+    try {
+        posted = poster.call(input.host.github, {
+            checkout: input.checkout,
+            number: target.number,
+            commitId: target.sha,
+            body: review.body,
+            comments: review.comments,
+        });
+    }
+    catch (error) {
+        const detail = publicDetail(error);
+        failPost(input, target, classifyFailureText(detail), detail);
+    }
+    appendEvent(input.kilnDir, {
+        job_id: input.jobId,
+        run_id: input.runId,
+        event: "review.posted",
+        step: "approve",
+        properties: {
+            repo: target.repo,
+            number: target.number,
+            sha: target.sha,
+            review_id: posted.id,
+            url: posted.url,
+            findings: review.findings,
+            inline: review.inline,
+            skipped: review.skipped,
+            dedupe: target.dedupe,
+            once: `posted:${target.dedupe}`,
+        },
+    });
+}
+function failPost(input, target, failureClass, detail) {
+    const clipped = detail.trim() || "The review was not posted.";
+    appendEvent(input.kilnDir, {
+        job_id: input.jobId,
+        run_id: input.runId,
+        event: "review.failed",
+        step: "approve",
+        properties: {
+            repo: target.repo,
+            number: target.number,
+            sha: target.sha,
+            class: failureClass,
+            detail: clipped,
+            dedupe: target.dedupe,
+        },
+    });
+    recordNeedsHuman(input);
+    throw new Error(`Could not post the review (${failureClass}). ${clipped}`);
+}
+function recordNeedsHuman(input) {
+    appendEvent(input.kilnDir, {
+        job_id: input.jobId,
+        run_id: input.runId,
+        event: "needs-human",
+        step: "approve",
+        properties: { reason: NEEDS_HUMAN_REASON, once: `needs-human:${NEEDS_HUMAN_REASON}` },
+    });
+}
+function publicDetail(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const cleaned = redact(message).replace(/\s+/g, " ").trim();
+    if (cleaned.length > 500)
+        return `${cleaned.slice(0, 499)}…`;
+    return cleaned || "The review was not posted.";
+}
+function parseFinding(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const record = value;
+    if (typeof record.comment !== "string" || !record.comment.trim())
+        return undefined;
+    const severity = REVIEW_SEVERITIES.find((item) => item === record.severity) ?? "note";
+    const file = typeof record.file === "string" ? record.file : undefined;
+    const line = commentLine(record.line);
+    return {
+        severity,
+        comment: record.comment.trim(),
+        ...(file !== undefined ? { file } : {}),
+        ...(line !== undefined ? { line } : {}),
+    };
+}
+/** A relative path inside the repo. Absolute paths and `..` are not locations. A leading `./` is a normal relative path. */
+export function commentPath(file) {
+    if (!file)
+        return undefined;
+    const raw = file.trim().replace(/\\/g, "/");
+    if (!raw || raw.startsWith("/") || raw.startsWith("~") || /^[A-Za-z]:/.test(raw))
+        return undefined;
+    if (/[\0\r\n]/.test(raw))
+        return undefined;
+    const parts = raw.split("/");
+    if (parts.some((part) => part === "" || part === ".."))
+        return undefined;
+    const cleaned = parts.filter((part) => part !== ".");
+    if (cleaned.length === 0)
+        return undefined;
+    return cleaned.join("/");
+}
+function commentLine(line) {
+    if (typeof line !== "number" || !Number.isInteger(line) || line < 1)
+        return undefined;
+    return line;
+}
+function commentText(finding) {
+    const text = finding.comment.trim();
+    if (finding.severity === "nit")
+        return `**nit** (not blocking)\n\n${text}`;
+    return `**${finding.severity}**\n\n${text}`;
+}
+function foldSkipped(markdown, skipped) {
+    const base = markdown.trim();
+    const extra = skipped.filter((finding) => !base.includes(finding.comment.trim()));
+    if (extra.length === 0)
+        return `${base}\n`;
+    const lines = [
+        base,
+        "",
+        "## Not posted on a line",
+        "",
+        "These findings had no file and line Kiln could check, so they are only in this review.",
+        "",
+    ];
+    for (const finding of extra)
+        lines.push(`- **${finding.severity}** ${finding.comment.trim()}`);
+    return `${lines.join("\n")}\n`;
+}

package/dist/schemas.js

@@ -48,6 +48,11 @@ export const RepoEntrySchema = z.object({
         .int("Max fix rounds must be a whole number.")
         .min(1, "Max fix rounds must be at least 1.")
         .optional(),
+    /**
+     * GitHub label `review-requests` searches for in this checkout.
+     * Overrides the trigger `label`. Omitted uses that label, which defaults to `kiln-review`.
+     */
+    reviewLabel: z.string().min(1).optional(),
 });
 /** Repo map shared by the config file and the settings API. */
 export const KilnReposSchema = z.record(z.string().regex(REPO_NAME, "must start with a letter or digit and contain only letters, digits, dots, underscores, and hyphens"), RepoEntrySchema);
@@ -135,6 +140,10 @@ const TRIGGER_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
  * `schedule` uses `cron` (5 fields, local time). `jira` uses `jql` or
  * `label` / `status` (compiled to JQL) and `every` (default `5m`).
  * `pr` is the built-in Kiln-owned pull request source.
+ * On `review-requests`, `label` is the GitHub label a pull request must
+ * carry (default `kiln-review`). `maxNew` is how many new review jobs one
+ * fire may create (default 3). `maxQueued` is how many review jobs may be
+ * queued or running at once (default 5).
  */
 export const TriggerConfigSchema = z
     .object({
@@ -147,6 +156,10 @@ export const TriggerConfigSchema = z
     jql: z.string().min(1).optional(),
     label: z.string().min(1).optional(),
     status: z.string().min(1).optional(),
+    /** Review jobs created on one fire of `review-requests`. Default 3. */
+    maxNew: z.number().int().min(1).optional(),
+    /** Queued or running review jobs at once. Default 5. */
+    maxQueued: z.number().int().min(1).optional(),
 })
     .strict();
 /** Maps a trigger id to create a job or attach to one. Hot-reloaded with the config. */
@@ -240,6 +253,11 @@ export const JobSchema = z.object({
     issue: z.string().regex(ISSUE_KEY).optional(),
     source: JobSourceSchema.optional(),
     createdAt: z.string().min(1),
+    /**
+     * Set when a person cancels the job before it starts.
+     * Tick does not launch it. Cancelling does not delete a branch.
+     */
+    cancelledAt: z.string().min(1).optional(),
 });
 /**
  * Derived from the yak journal, gate files, and (for `deliver=pr`) the
@@ -255,7 +273,8 @@ export const JobSchema = z.object({
  * after-merged dependent. A stacked job unblocks when its one upstream has
  * landed, which includes `in-review`. A job that has used its attempt cap,
  * fix-round cap, or fingerprint breaker is `needs-human`. `dead` is a run
- * whose process died and has not been recorded yet. Attempts live under
+ * whose process died and has not been recorded yet. `cancelled` is a job
+ * cancelled before it started. Attempts live under
  * the kiln directory, not in this file.
  */
 export const JOB_STATES = [
@@ -269,4 +288,5 @@ export const JOB_STATES = [
     "dead",
     "in-review",
     "done",
+    "cancelled",
 ];