omp-conductor 0.17.0 → 0.18.0

package/src/decisions.ts

@@ -161,6 +161,16 @@ export async function probeRateLimitReset(runGh: RateLimitGh = ghRateLimit): Pro
  * pass. A condition that could not be checked is simply not met this time, and
  * the next tick asks again for free.
  *
+ * A watch (#459) whose PR condition can no longer be observed — the PR merged
+ * or closed before the requested condition was seen — is withdrawn in this same
+ * pass rather than left rendering `condition:pending` forever: the mediated
+ * surfaces for checks and mergeability do not answer for a settled PR, so the
+ * row could only ever stay unmet, and a watch has deliberately no seven-day
+ * expiry to close it. The withdrawal is the same durable `state=withdrawn`
+ * resolution an operator's `watch withdraw` writes, so the audit trail of what
+ * was waiting and why it stopped survives. Operator questions are untouched:
+ * they answer to a human and expire on the seven-day clock.
+ *
  * Returns the rows that just became met, so the caller can log what changed
  * rather than a count.
  */
@@ -179,12 +189,29 @@ export async function evaluateDecisionConditions(
     let satisfied = false;
     try {
       if (condition.kind === "pr-merged") {
-        satisfied = (await tracker.prState(condition.url)) === "merged";
+        const state = await tracker.prState(condition.url);
+        if (state === "merged") {
+          satisfied = true;
+        } else if (decision.kind === "watch" && state === "closed") {
+          // The PR closed without merging: `pr-merged` can never be observed.
+          store.resolveDecision(decision.id, "withdrawn", "PR closed without merging", now());
+          continue;
+        }
       } else if (condition.kind === "issue-closed") {
         satisfied = (await tracker.issueState(condition.issue)) === "closed";
       } else if (condition.kind === "npm-version") {
         satisfied = await probes.npm(condition.spec);
       } else if (condition.kind === "pr-checks-green") {
+        // A watch whose PR settled before its checks were seen green cannot
+        // ever be met: the checks surface does not answer for a merged or
+        // closed PR, so the row would render `pending` forever (#664).
+        if (decision.kind === "watch") {
+          const state = await tracker.prState(condition.url);
+          if (state === "merged" || state === "closed") {
+            store.resolveDecision(decision.id, "withdrawn", `PR ${state} before its checks were seen`, now());
+            continue;
+          }
+        }
         // The same conclusion values the daemon's failure classifier treats as
         // a green verdict (`success` / `neutral`, lowercased): a non-empty list
         // in which every check is terminally successful and none is failing or
@@ -193,6 +220,16 @@ export async function evaluateDecisionConditions(
         satisfied =
           checks.length > 0 && checks.every((c) => GREEN_CHECK_STATES[c.state.trim().toLowerCase()] === true);
       } else if (condition.kind === "pr-mergeable") {
+        // A watch whose PR settled before it was seen mergeable is the same
+        // unobservable case as checks: the mergeability literal exists only
+        // while the PR is open (#664).
+        if (decision.kind === "watch") {
+          const state = await tracker.prState(condition.url);
+          if (state === "merged" || state === "closed") {
+            store.resolveDecision(decision.id, "withdrawn", `PR ${state} before it was seen mergeable`, now());
+            continue;
+          }
+        }
         // `clean` is the tracker's "this PR can merge" literal; `unknown` and a
         // conflict are both unsatisfied (#189).
         satisfied = (await tracker.mergeable(condition.url)) === "clean";
@@ -242,7 +279,9 @@ function age(since: number, now: number): string {
  * watch heading with no instruction to resolve it, so a fleet at rest behind
  * GitHub's checks is never mistaken for a fleet that is waiting on its
  * operator. A met watch still surfaces to the orchestrator with its note and
- * the same `[CONDITION MET]` flag a met question gets.
+ * the same `[CONDITION MET]` flag a met question gets. Every watch line also
+ * names the command that closes it (`watch withdraw <id>`), because the
+ * surface that shows a watch is where the reader learns how to end one (#664).
  */
 export function formatDecisionDigest(open: readonly DecisionRecord[], now = Date.now()): string {
   const questions = open.filter((d) => d.kind !== "watch");
@@ -261,14 +300,20 @@ export function formatDecisionDigest(open: readonly DecisionRecord[], now = Date
       `Watches (${watches.length}) — conditions the orchestrator set for itself; no operator action needed:`,
     );
     for (const d of watches) {
-      lines.push(decisionLine(d, now));
+      // Each line names the verb that closes it, so the orchestrator reading a
+      // digest does not have to know the decisions vocabulary (#664).
+      lines.push(decisionLine(d, now, `watch withdraw ${d.id}`));
     }
   }
   return lines.join("\n");
 }
 
-/** One digest row: id, age, what it blocks, the met flag, and the note. */
-function decisionLine(d: DecisionRecord, now: number): string {
+/**
+ * One digest row: id, age, what it blocks, the met flag, and the note.
+ * `closing` names the command that ends the row, rendered after the note.
+ */
+function decisionLine(d: DecisionRecord, now: number, closing?: string): string {
   const flag = d.conditionMetAt === undefined ? "" : " [CONDITION MET — act on this now]";
-  return `- ${d.id} (${age(d.askedAt, now)}, blocks ${d.blocks ?? "nothing"})${flag}: ${d.question}`;
+  const end = closing === undefined ? "" : ` — end with: omp-conductor ${closing}`;
+  return `- ${d.id} (${age(d.askedAt, now)}, blocks ${d.blocks ?? "nothing"})${flag}: ${d.question}${end}`;
 }

package/src/depends-on.ts

@@ -18,9 +18,70 @@
  * usable prerequisite, so it is reported as `malformed` for the grooming flag
  * rather than guessed at, and the declaration it belongs to is ignored.
  *
- * Graph cycles are a later slice (#421) and stay out of scope here.
+ * The module also owns the dependency-graph cycle pass (#421): {@link
+ * buildDependencyCycles} closes the graph over a pass's candidates and their
+ * reachable `Depends-on:` targets, and names every cycle so admission can hold
+ * the whole group rather than have an open first edge mask the cycle.
  */
 
+import type { IssueState } from "./types.ts";
+
+/** Canonical identity of one dependency-graph node: `owner/repo#n`. */
+export interface DependencyNode {
+  readonly repo: string;
+  readonly issue: number;
+}
+
+/** Stable string key for {@link DependencyNode} — `owner/repo#n`. */
+export function dependencyNodeKey(repo: string, issue: number): string {
+  return `${repo}#${issue}`;
+}
+
+/** One issue's live facts, enough to follow a dependency edge from it. */
+export interface DependencyRead {
+  readonly state: IssueState;
+  readonly body: string;
+}
+
+/**
+ * Reads one issue's state + body in either the tracker repo or a routed repo,
+ * or undefined when the repo is not a resolvable dependency target or the read
+ * could not be completed. Both cases fail closed — no edge is added — rather
+ * than ever synthesising a false cycle (#421).
+ */
+export type DependencyNodeReader = (
+  repo: string,
+  issue: number,
+) => Promise<DependencyRead | undefined>;
+
+/** Where a cross-repo `owner/repo#n` target resolves: the tracker repo, a
+ *  routed repo, or nowhere (bounds traversal to the fleet's own repos). */
+export type DependencyRepoResolver = (ownerRepo: string) => "tracker" | "routed" | undefined;
+
+/** A detected dependency cycle, canonicalised so rotation or queue order cannot
+ *  change its identity (and therefore cannot emit a new material event). */
+export interface DependencyCycle {
+  /** Member node keys (`owner/repo#n`), for membership checks. */
+  readonly members: readonly string[];
+  /** The cycle as an ordered path from the canonical start, closing on itself.
+   *  The display is stable under rotation and queue order. */
+  readonly path: readonly DependencyNode[];
+  /** {@link path} rendered: same-repo nodes as `#n`, others as `owner/repo#n`. */
+  readonly display: string;
+  /** The tracker-repo issue this cycle is reported against: the lowest global
+   *  tracker issue among the members. A cycle reachable only through routed
+   *  nodes falls back to its lowest member issue. */
+  readonly anchorIssue: number;
+}
+
+/** The output of one cycle pass over a set of candidates. */
+export interface DependencyGraphResult {
+  /** Node keys of every node on at least one detected cycle. */
+  readonly cycleNodes: ReadonlySet<string>;
+  /** The distinct cycles found, canonicalised and deduplicated. */
+  readonly cycles: readonly DependencyCycle[];
+}
+
 export interface DependsOnDecl {
   /** Referenced same-repo prerequisite issue numbers, deduplicated,
    *  first-seen order. */
@@ -120,3 +181,202 @@ export function parseDependsOn(body: string): DependsOnDecl {
   }
   return { refs, crossRefs, malformed };
 }
+
+/**
+ * Enumerate every dependency cycle reachable from an admission pass's
+ * candidates. Built once per pass, before any per-candidate open-prerequisite
+ * hold, so a candidate sitting on a cycle is held as `dependency-cycle` rather
+ * than having its status masked by the first open edge (#421).
+ *
+ * The graph nodes are the candidates (bodies already parsed from `routed`,
+ * never a network read) plus every issue they reach through `Depends-on:`
+ * references — a bare `#n` resolves in the declaring node's own repo
+ * (tracker or routed), a cross-repo `owner/repo#n` in the tracker or a
+ * routed repo. Traversal is bounded in three ways:
+ *   - references to a repo that is neither the tracker nor a routed repo are
+ *     dropped before any read (they are the existing unroutable hold's job);
+ *   - every node is expanded once, so each body/state read happens at most
+ *     once per pass regardless of how many candidates reach it;
+ *   - a closed node is terminal: it never propagates a cycle, because a
+ *     dependency that is already done cannot hold anyone open.
+ * A node whose state or body cannot be read fails closed — it adds no edge and
+ * is never mistaken for a cycle; the per-candidate path then holds its
+ * originator on the existing dependency-unreadable route.
+ *
+ * Cycle membership is the graph's strongly connected components (Tarjan): a
+ * node sits on some directed cycle exactly when its component has more than
+ * one node or a self-edge, so overlapping cycles cannot hide a member behind
+ * an already-explored subtree. Each cyclic component is one cycle identity,
+ * with a deterministic simple path for status/digest.
+ */
+export async function buildDependencyCycles(
+  candidates: ReadonlyArray<{ repo: string; issue: number; body: string }>,
+  trackerRepo: string,
+  resolveRepo: DependencyRepoResolver,
+  read: DependencyNodeReader,
+): Promise<DependencyGraphResult> {
+  const candidateBody = new Map<string, string>();
+  for (const c of candidates) {
+    candidateBody.set(dependencyNodeKey(c.repo, c.issue), c.body);
+  }
+
+  // Materialise the reachable graph once: node key -> outgoing targets. A key
+  // present in `adj` is expanded — a candidate carries its body, a
+  // non-candidate is read at most once, and an unreadable or closed node is
+  // terminal (present, with no edges), so it is never read or re-expanded.
+  const adj = new Map<string, DependencyNode[]>();
+  const nodeOf = new Map<string, DependencyNode>();
+
+  const expand = async (node: DependencyNode): Promise<void> => {
+    const key = dependencyNodeKey(node.repo, node.issue);
+    if (adj.has(key)) return;
+    let body = candidateBody.get(key);
+    if (body === undefined) {
+      // Non-candidate node: read it fresh (once), fail closed on any doubt.
+      const r = await read(node.repo, node.issue);
+      if (r === undefined || r.state === "closed") {
+        // Unreadable never synthesises a cycle; a closed dependency is terminal.
+        adj.set(key, []);
+        nodeOf.set(key, { repo: node.repo, issue: node.issue });
+        return;
+      }
+      body = r.body;
+    }
+
+    const decl = parseDependsOn(body);
+    const targets: DependencyNode[] = [];
+    // A bare `#n` resolves in the declaring node's OWN repo: a body read from
+    // `acme/web#7` declares `acme/web#n`, never the tracker repo's #n.
+    for (const ref of decl.refs) {
+      targets.push({ repo: node.repo, issue: ref });
+    }
+    for (const cref of decl.crossRefs) {
+      const where = resolveRepo(cref.repo);
+      if (where === "tracker") targets.push({ repo: trackerRepo, issue: cref.issue });
+      else if (where === "routed") targets.push({ repo: cref.repo, issue: cref.issue });
+      // unresolved repos are dropped before any read: bounds traversal to the
+      // fleet's own tracker/routed repos (#421).
+    }
+    adj.set(key, targets);
+    nodeOf.set(key, { repo: node.repo, issue: node.issue });
+    for (const t of targets) {
+      await expand(t);
+    }
+  };
+
+  for (const c of candidates) {
+    await expand({ repo: c.repo, issue: c.issue });
+  }
+
+  // Tarjan's strongly connected components over the materialised graph. Every
+  // node on some directed cycle is in a cyclic component, so membership is
+  // complete where a single DFS path would miss a member behind an
+  // already-explored subtree (1 -> {2,3}, 3 -> 2, 2 -> 1: 3 is on the cycle
+  // 1 -> 3 -> 2 -> 1 even though the direct 1 <-> 2 pair is found first).
+  let nextIndex = 0;
+  const index = new Map<string, number>();
+  const low = new Map<string, number>();
+  const onStack = new Set<string>();
+  const stack: string[] = [];
+  const components: string[][] = [];
+
+  const strongConnect = (key: string): void => {
+    index.set(key, nextIndex);
+    low.set(key, nextIndex);
+    nextIndex += 1;
+    stack.push(key);
+    onStack.add(key);
+    for (const t of adj.get(key) ?? []) {
+      const targetKey = dependencyNodeKey(t.repo, t.issue);
+      if (!index.has(targetKey)) {
+        strongConnect(targetKey);
+        low.set(key, Math.min(low.get(key)!, low.get(targetKey)!));
+      } else if (onStack.has(targetKey)) {
+        low.set(key, Math.min(low.get(key)!, index.get(targetKey)!));
+      }
+    }
+    if (low.get(key) === index.get(key)) {
+      const component: string[] = [];
+      let w: string;
+      do {
+        w = stack.pop()!;
+        onStack.delete(w);
+        component.push(w);
+      } while (w !== key);
+      components.push(component);
+    }
+  };
+  for (const key of adj.keys()) {
+    if (!index.has(key)) strongConnect(key);
+  }
+
+  /** A deterministic simple directed cycle inside one cyclic component: DFS
+   *  from the smallest member with children in key order; the first back edge
+   *  closes a path. A true cyclic component always yields one — every member
+   *  reaches every other, so the search cannot finish without crossing an
+   *  ancestor. */
+  const findCyclePath = (
+    start: DependencyNode,
+    inComponent: ReadonlySet<string>,
+  ): readonly DependencyNode[] | undefined => {
+    const path: DependencyNode[] = [start];
+    const position = new Map<string, number>([
+      [dependencyNodeKey(start.repo, start.issue), 0],
+    ]);
+    const descend = (cur: DependencyNode): readonly DependencyNode[] | undefined => {
+      const children = (adj.get(dependencyNodeKey(cur.repo, cur.issue)) ?? [])
+        .filter((t) => inComponent.has(dependencyNodeKey(t.repo, t.issue)))
+        .sort((a, b) => {
+          const ka = dependencyNodeKey(a.repo, a.issue);
+          const kb = dependencyNodeKey(b.repo, b.issue);
+          return ka < kb ? -1 : ka > kb ? 1 : 0;
+        });
+      for (const child of children) {
+        const childKey = dependencyNodeKey(child.repo, child.issue);
+        const at = position.get(childKey);
+        if (at !== undefined) {
+          // Back edge: the path from the ancestor to here, closed on `child`.
+          return [...path.slice(at), child];
+        }
+        position.set(childKey, path.length);
+        path.push(child);
+        const found = descend(child);
+        if (found !== undefined) return found;
+        path.pop();
+        position.delete(childKey);
+      }
+      return undefined;
+    };
+    return descend(start);
+  };
+
+  const cycles: DependencyCycle[] = [];
+  for (const component of components) {
+    const members = [...component].sort();
+    const hasSelfEdge = members.some((k) =>
+      (adj.get(k) ?? []).some((t) => dependencyNodeKey(t.repo, t.issue) === k),
+    );
+    if (members.length === 1 && !hasSelfEdge) continue; // terminal or acyclic
+    // Canonical start: the smallest member by owner/repo#n spelling, so
+    // rotation and queue order never produce a different identity.
+    const path = findCyclePath(nodeOf.get(members[0]!)!, new Set(component));
+    if (path === undefined) continue; // unreachable for a cyclic component; never fabricate
+    const display = path
+      .map((n) => (n.repo === trackerRepo ? `#${n.issue}` : `${n.repo}#${n.issue}`))
+      .join(" -> ");
+    const trackerMembers = members
+      .map((k) => k.split("#") as [string, string])
+      .filter(([repo]) => repo === trackerRepo)
+      .map(([, issue]) => Number(issue));
+    const anchorIssue =
+      trackerMembers.length > 0
+        ? Math.min(...trackerMembers)
+        : Math.min(...members.map((k) => Number(k.split("#")[1])));
+
+    cycles.push({ members, path, display, anchorIssue });
+  }
+
+  const cycleNodes = new Set<string>();
+  for (const cyc of cycles) for (const m of cyc.members) cycleNodes.add(m);
+  return { cycleNodes, cycles };
+}