toolroll 0.9.103 → 0.9.105

package/dist/remote.js

@@ -1,32 +1,7 @@
-/**
- * The half of "in flight" that is not on this machine.
- *
- * Branches come off the local filesystem in milliseconds. Pull requests and
- * issues are a network round trip per repository, and that difference is the
- * whole reason this is a separate module with a budget attached rather than
- * three more lines inside discovery.
- *
- * An earlier draft kept these behind their own command precisely because of
- * the cost, and the milestone still asks for one command that shows every
- * branch, pull request, and issue in flight. Both concerns are real, so this
- * follows the rule the rest of the tool already uses for expensive reads:
- * price it, bound it, and **say what you withheld**. Twenty-four repositories
- * on hotel wifi will not hang; they will come back with what fitted in the
- * budget and a line naming what did not.
- *
- * The budget is for the whole phase, not per repository. A per-call timeout
- * bounds the worst case at repos × timeout, which for a machine full of work
- * is not a bound anybody would recognise as one.
- */
 import { readPulls } from "./pulls.js";
 import { githubIssues } from "./issues.js";
 import {} from "./backend.js";
-/**
- * Long enough for a dozen repositories on an ordinary connection, short enough
- * that somebody who typed a command still feels like it answered.
- */
 export const DEFAULT_BUDGET_MS = 15_000;
-/** GitHub is the bottleneck here, not the local machine. */
 export const DEFAULT_REMOTE_CONCURRENCY = 6;
 export const EMPTY = {
     pulls: [],
@@ -36,13 +11,6 @@ export const EMPTY = {
     problems: [],
     skipped: false,
 };
-/**
- * Read pull requests and issues for each repository, within one budget.
- *
- * Only repositories that look like they are on a remote are asked; a local-only
- * repo has no pull requests by definition, and spending part of a shared budget
- * to be told so would come out of the repositories that do.
- */
 export async function readRemote(repos, options = {}) {
     const { runner, budgetMs = DEFAULT_BUDGET_MS, concurrency = DEFAULT_REMOTE_CONCURRENCY, now = () => Date.now(), issueLimit, } = options;
     const state = new Map();
@@ -58,24 +26,15 @@ export async function readRemote(repos, options = {}) {
             const repo = wanted[next++];
             if (repo === undefined)
                 return;
-            // Checked before each repository rather than after: once the budget is
-            // spent, every remaining repository is marked and none of them waits.
             const remaining = deadline - now();
             if (remaining <= 0) {
                 state.set(repo.path, { ...EMPTY, skipped: true });
                 continue;
             }
             try {
-                // The per-call timeout is clamped to what is left of the budget. A
-                // deadline checked only before starting is not a bound: with six lanes
-                // and a twenty-second call timeout, six repositories begun a moment
-                // before the budget expires run twenty seconds past it. Handing each
-                // call the remaining time makes the budget mean what it says.
                 state.set(repo.path, await readOne(repo.path, runner, issueLimit, remaining));
             }
             catch (error) {
-                // A runner that throws rather than returning a failure must not end a
-                // report covering everything else — the same rule discovery follows.
                 state.set(repo.path, {
                     ...EMPTY,
                     problems: [`could not read ${repo.path}: ${describe(error)}`],
@@ -93,19 +52,11 @@ async function readOne(path, runner, issueLimit, timeoutMs) {
         ...(runner === undefined ? {} : { runner }),
         ...(issueLimit === undefined ? {} : { limit: issueLimit }),
     });
-    // Both round trips at once: they are independent, and doing them in sequence
-    // would double the time this repository costs the shared budget.
     const [pulls, listed] = await Promise.all([
         readPulls(path, { timeoutMs, ...(runner === undefined ? {} : { runner }) }),
         issues.listReady(),
     ]);
     const problems = [...pulls.problems];
-    // Every failed read is said out loud. An earlier version swallowed the
-    // `unreachable` ones as though they meant "issues are switched off here",
-    // but that bucket also holds an expired token, a rate limit, and a dropped
-    // connection — and reporting any of those as `issues: []` turns "we could
-    // not look" into "there is nothing there", which is the one thing this
-    // report must never do.
     if (!listed.ok)
         problems.push(`could not read issues: ${listed.message}`);
     return {

package/dist/render.js

@@ -1,10 +1,3 @@
-/**
- * Turning snapshots into something worth reading.
- *
- * Pure string building. The clock is a parameter rather than a call, so the
- * output is deterministic under test and the same report can be re-rendered
- * later against the time it was taken.
- */
 import { chooseBackend, setupOptions, LABELS as GRAPH_LABELS, } from "./graph.js";
 import { classify, describe as describePull, idleDays, DEFAULT_STALE_DAYS, } from "./pulls.js";
 export const DEFAULT_MAX_BRANCHES = 6;
@@ -15,12 +8,6 @@ const MONTH = 30 * DAY;
 const YEAR = 365 * DAY;
 const INDENT = "  ";
 const GUTTER = 2;
-/**
- * Columns size themselves to the content, within bounds. Fixed widths either
- * waste half the terminal on short names or let one long branch name shove
- * every other column out of alignment — and truncating is not an option when
- * the name is the thing you are about to type.
- */
 const MIN_NAME_WIDTH = 20;
 const MAX_NAME_WIDTH = 44;
 const MIN_STATE_WIDTH = 12;
@@ -29,7 +16,6 @@ export function formatAge(iso, now) {
     const then = Date.parse(iso);
     if (Number.isNaN(then))
         return "unknown";
-    // Clocks disagree across machines; a branch from the future is just recent.
     const elapsed = Math.max(0, now.getTime() - then);
     if (elapsed < MINUTE)
         return "just now";
@@ -53,7 +39,6 @@ export function formatTrack(track) {
         parts.push(`behind ${track.behind}`);
     return parts.join(", ");
 }
-/** A branch is in flight when it has diverged from its upstream or lost it. */
 function isInFlight(branch) {
     return branch.track.ahead > 0 || branch.track.behind > 0 || branch.track.gone;
 }
@@ -67,10 +52,6 @@ export function renderReport(snapshots, options) {
         .filter(rows => rows.length > 0);
     const totals = countInFlight(snapshots, remote);
     const withheld = renderWithheld(snapshots, remote);
-    // "Nothing in flight" is a claim about what was looked at. If the budget ran
-    // out before some repositories were asked, saying it flatly would be the
-    // silence this tool exists to break — so the withheld line goes here too,
-    // and it is the whole point of this branch rather than a footnote.
     if (sections.length === 0) {
         return [...renderNothingInFlight(snapshots.length, remote, withheld.length > 0), ...withheld]
             .join("\n")
@@ -85,22 +66,12 @@ export function renderReport(snapshots, options) {
         .join("\n")
         .trimEnd();
 }
-/**
- * One repository's block, from both halves.
- *
- * The local rows already end in a blank separator, so remote rows are spliced
- * in ahead of it rather than appended after — otherwise a repository's pull
- * requests would appear under the gap, reading as though they belonged to the
- * repository below.
- */
 function composeSection(snapshot, now, maxBranches, remote) {
     const local = collectRows(snapshot, now, maxBranches);
     const fromRemote = collectRemoteRows(snapshot, remote, now);
     if (fromRemote.length === 0)
         return local;
     if (local.length === 0) {
-        // Nothing local to say, but a pull request waiting is still news, and the
-        // repository needs a heading of its own to be attributed to.
         return [
             { indent: "", name: snapshot.name, state: snapshot.head ?? "detached", tail: "" },
             ...fromRemote,
@@ -122,15 +93,6 @@ function countInFlight(snapshots, remote) {
     }
     return { branches, pulls, issues, remoteRead: remote !== undefined };
 }
-/**
- * Pull requests waiting on somebody, and a count of open issues.
- *
- * Pull requests get a row each because a pull request that nobody has looked at
- * is the single most actionable thing this report can surface — the case that
- * motivated the tool was two of them sitting green and ignored for two months.
- * Issues get a count: a hundred open issues is context, not a to-do list, and
- * printing all of them would bury everything above.
- */
 function collectRemoteRows(snapshot, remote, now) {
     const state = remote?.get(snapshot.path);
     if (state === undefined || state.skipped)
@@ -161,18 +123,12 @@ function collectRemoteRows(snapshot, remote, now) {
     }
     return rows;
 }
-/** What the budget did not reach, named rather than silently missing. */
 function renderWithheld(snapshots, remote) {
     if (remote === undefined)
         return [];
     const skipped = snapshots.filter(snapshot => remote.get(snapshot.path)?.skipped === true);
     if (skipped.length === 0)
         return [];
-    // Named, not counted. "3 repositories were not checked" leaves an operator
-    // to work out which three, and the whole reason this line exists is that a
-    // repository nobody looked at must not be mistaken for one with nothing in
-    // it. Long lists are truncated, because at that point the budget is the
-    // story rather than the names.
     const shown = skipped.slice(0, MAX_SKIPPED_NAMED).map(snapshot => snapshot.name);
     const rest = skipped.length - shown.length;
     const names = rest > 0 ? `${shown.join(", ")} and ${rest} more` : shown.join(", ");
@@ -186,27 +142,12 @@ function renderRow(row, nameWidth, stateWidth) {
     const name = pad(`${row.indent}${row.name}`, nameWidth);
     return `${name}${pad(row.state, stateWidth)}${row.tail}`.trimEnd();
 }
-/**
- * Only rows that carry a later column get a vote on how wide the earlier ones
- * are. A free-text problem line has nothing to its right, so letting it size
- * the table would push every real column off to the horizon.
- */
 function widthOf(rows, measure, min, max) {
     const widest = rows
         .filter(row => row.state !== "" || row.tail !== "")
         .reduce((longest, row) => Math.max(longest, measure(row)), 0);
     return Math.min(max, Math.max(min, widest + GUTTER));
 }
-/**
- * The one line the milestone is actually about: every branch, pull request and
- * issue in flight, counted together.
- *
- * Zeroes are dropped rather than printed. "3 branches, 0 pull requests, 0
- * issues" reads as a system reporting on itself; "3 branches" reads as an
- * answer. But a zero that was never *looked* for is different from one that
- * was, which is why the remote counts only appear when the remote read
- * actually happened.
- */
 function renderHeader(totals, repoCount, unmeasured) {
     const parts = [plural(totals.branches, "branch", "branches")];
     if (totals.remoteRead && totals.pulls > 0) {
@@ -217,9 +158,6 @@ function renderHeader(totals, repoCount, unmeasured) {
     }
     const repos = plural(repoCount, "repository", "repositories");
     const headline = `${joinWords(parts)} in flight across ${repos}`;
-    // A count that quietly excludes repositories it could not measure is a lie
-    // of omission. The remedy is named once here rather than on every repo — and
-    // it is printed, never run, because it writes to someone else's .git.
     if (unmeasured === 0)
         return headline;
     const which = unmeasured === 1 ? "1 repository is" : `${unmeasured} repositories are`;
@@ -230,7 +168,6 @@ function renderHeader(totals, repoCount, unmeasured) {
         "it writes to .git, so run it yourself.",
     ].join("\n");
 }
-/** Repositories were found and read; none of them had anything outstanding. */
 function renderNothingInFlight(repoCount, remote, anyWithheld) {
     return [
         anyWithheld
@@ -241,15 +178,11 @@ function renderNothingInFlight(repoCount, remote, anyWithheld) {
             : "Every branch is level with its upstream, and nothing is waiting on a person.",
         "",
         "Uncommitted work is not counted here — add --dirty to read working trees.",
-        // Said in addition to, not instead of: an operator who ran --local has two
-        // things missing from this answer, and hearing about one of them would
-        // leave them believing the other was checked.
         ...(remote === undefined
             ? ["Pull requests and issues were not read — drop --local to include them."]
             : []),
     ];
 }
-/** "a, b and c" — the report is prose at this point, not a field list. */
 function joinWords(parts) {
     if (parts.length <= 1)
         return parts[0] ?? "";
@@ -264,17 +197,8 @@ function renderEmpty(roots) {
         "`toolroll --depth 8`. Nothing has been written or configured.",
     ].join("\n");
 }
-/** Past this, the budget is the story rather than which repositories missed out. */
 const MAX_SKIPPED_NAMED = 6;
-/** Long enough to catch work you have put down, short enough to exclude archaeology. */
 const RECENT_WINDOW = 30 * DAY;
-/**
- * Which branches to show. With tracking, the ones that have diverged. Without
- * it, recency is the only signal left — filtering on ahead/behind that was
- * never computed would discard every branch and leave the repository
- * represented by a complaint, and listing all of them buries the report under
- * whichever repo happens to have the most abandoned branches.
- */
 function selectBranches(snapshot, now) {
     const byRecent = [...snapshot.branches].sort(byCommittedAtDesc);
     if (snapshot.hasTracking)
@@ -291,7 +215,6 @@ function isWithinWindow(iso, now) {
 }
 function collectRows(snapshot, now, maxBranches) {
     const { shown: selected, note } = selectBranches(snapshot, now);
-    // A quiet, clean repo with nothing outstanding is not worth a line.
     if (selected.length === 0 &&
         note === null &&
         !snapshot.dirtyFiles &&
@@ -325,11 +248,9 @@ function collectRows(snapshot, now, maxBranches) {
     rows.push({ indent: "", name: "", state: "", tail: "" });
     return rows;
 }
-/** null means the working tree was not read, which is silence rather than "clean". */
 function renderDirty(count) {
     return count === null || count === 0 ? "" : `${count} uncommitted`;
 }
-/** Most recently touched repository first — recency is what "in flight" means. */
 function byRecency(a, b) {
     const difference = latestCommit(b) - latestCommit(a);
     return difference !== 0 ? difference : a.name.localeCompare(b.name);
@@ -349,11 +270,6 @@ function pad(text, width) {
 function plural(count, one, many) {
     return `${count} ${count === 1 ? one : many}`;
 }
-/**
- * How long since anything happened. Phrased as idleness rather than age
- * because a pull request opened in May and discussed yesterday is not old in
- * any sense the operator cares about.
- */
 export function formatIdle(iso, now) {
     const age = formatAge(iso, now);
     if (age === "unknown")
@@ -362,12 +278,6 @@ export function formatIdle(iso, now) {
         return "just now";
     return `${age.replace(" ago", "")} idle`;
 }
-/**
- * Grouped by whose move it is, because that is the only question being asked.
- * Drafts and running builds are counted but not listed — nobody is blocked on
- * them, and a report that lists everything is the attention problem it was
- * written to solve.
- */
 export function renderPulls(groups, options) {
     const { now, staleDays = DEFAULT_STALE_DAYS } = options;
     const entries = groups.flatMap(group => group.pulls.map(pull => ({ repo: group.repo, pull, attention: classify(pull) })));
@@ -399,10 +309,6 @@ const ATTENTION_HEADINGS = {
     machine: "Waiting on CI",
     none: "In progress",
 };
-/**
- * Longest-idle first. The one that has been ignored the longest is the one
- * most likely to have been forgotten rather than deferred.
- */
 function renderAttention(attention, entries, now) {
     const mine = entries
         .filter(entry => entry.attention === attention)
@@ -430,18 +336,12 @@ function renderPullsHeader(waiting, stalled, staleDays) {
     const which = stalled === 1 ? "1 has" : `${stalled} have`;
     return `${headline} ${which} been waiting more than ${plural(staleDays, "day", "days")}.`;
 }
-/**
- * Nothing waiting is only good news if we managed to look. A repository whose
- * pull requests could not be read has told us nothing, and saying "nothing is
- * waiting" about it would be the silence this tool exists to break.
- */
 function renderNothingWaiting(entries, problems) {
     if (problems.length > 0 && entries.length === 0)
         return "No pull requests were read.";
     const quiet = renderQuiet(entries);
     return ["Nothing is waiting on you.", ...quiet].join("\n");
 }
-/** Drafts and running builds: counted, so their absence above is not a mystery. */
 function renderQuiet(entries) {
     const drafts = entries.filter(entry => entry.attention === "none").length;
     const running = entries.filter(entry => entry.attention === "machine").length;
@@ -454,15 +354,6 @@ function renderQuiet(entries) {
 function renderProblems(problems) {
     return problems.length === 0 ? [] : ["", ...problems.map(problem => `! ${problem}`)];
 }
-/**
- * What work graph is already here.
- *
- * The recommended backend is marked with a pointer and nothing else is, because
- * the one thing this report must not read as is a menu of things already
- * switched on. Every line ends by saying what is *not* authorized, since
- * detection is not authorization and a report that omitted that would be
- * inviting exactly the wrong conclusion.
- */
 export function renderGraph(detections, options = {}) {
     if (detections.length === 0) {
         return [
@@ -493,18 +384,6 @@ export function renderGraph(detections, options = {}) {
         .join("\n")
         .trimEnd();
 }
-/**
- * The way forward when nothing is set up.
- *
- * Without this the empty case is a dead end — "no tracker found, and the
- * fallback does not exist yet" — which tells an operator nothing they can act
- * on. §4 requires the opposite: print the upstream command *and* what it will
- * do, and let them run it.
- *
- * The side effects are not a footnote. `bd init` rewrites AGENTS.md and
- * installs agent integrations, and somebody who ran it because a tool
- * suggested it and only found that out afterwards would be right to be angry.
- */
 function renderSetup() {
     const lines = ["", "Setting one up — commands to run yourself, in your own shell:"];
     for (const option of setupOptions()) {
@@ -521,14 +400,11 @@ function renderSetup() {
     lines.push("Toolroll runs none of these. Re-run `toolroll graph` afterwards.");
     return lines;
 }
-/** The middle column: where it is, how much is in it, and whether it could run. */
 function describeDetection(detection) {
     const parts = [];
     if (detection.repos.length > 0) {
         parts.push(`${plural(detection.repos.length, "repo", "repos")}`);
     }
-    // A row with no number at all reads as zero. Absence of a count is its own
-    // fact and has to be said out loud.
     parts.push(detection.count === null
         ? "count unknown"
         : `${detection.count.value} ${detection.count.of}`);
@@ -553,15 +429,9 @@ function describeRuntime(detection) {
         return "runtime would not answer";
     return runtime.version === null ? "runtime ok" : `runtime ok (${runtime.version})`;
 }
-/**
- * The closing line always says nothing is enrolled, including when a backend
- * is recommended. A recommendation that read as an activation would be the one
- * misunderstanding this whole module is written to prevent.
- */
 function describeChoice(choice) {
     const lines = [];
     if (choice.action === "recommend" && choice.why === "already enrolled") {
-        // An enrolled backend is not a suggestion, and must not read like one.
         lines.push(`Enrolled: ${GRAPH_LABELS[choice.kind]}. Write access has been granted.`);
         lines.push("`toolroll grants` shows exactly what, and `revoke` takes it back.");
         return lines;
@@ -569,9 +439,6 @@ function describeChoice(choice) {
     if (choice.action === "recommend") {
         lines.push(`Suggested: ${GRAPH_LABELS[choice.kind]} — ${choice.why}.`);
         if (!choice.dispatchable) {
-            // Deliberately not "it can be read, but…": when the runtime is missing
-            // it cannot be read either, and the sentence would contradict the row
-            // directly above it.
             lines.push("Nothing here could be scheduled from it as it stands.");
         }
     }