jackherd 1.6.1 → 1.7.1

package/src/plan-format/plan-structure.ts

@@ -1,12 +1,13 @@
 import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
-import { laneNameOf, parseSprintLanes, phaseIdsOfCell } from './lanes'
-import { escapeRegExp, firstTableRows, sectionLines, sectionStart } from './markdown'
+import { changedOpenLaneRows, type OpenLaneRow, phaseIdsOfCell } from './lanes'
+import { escapeRegExp, sectionLines } from './markdown'
 import {
   deferralTarget,
   endsPhase,
   isCheckboxLine,
   isOpenCheckboxLine,
   isReviewGateLine,
+  type PhaseHeading,
   type PlanPhase,
   parsePlanPhases,
   phaseHeadingPattern,
@@ -14,10 +15,10 @@ import {
 import { terminalSafe } from './terminal-text'
 
 /** A `### Phase` heading (1-based line) whose section has tasks and neither a review gate nor the line saying why not. */
-export type PhaseWithoutGate = { line: number; id: string; title: string }
+export type PhaseWithoutGate = PhaseHeading
 
 /** A row of the lanes table (1-based line) whose phases cell names no phase id. */
-export type RowWithoutPhase = { line: number; lane: string; phases: string }
+export type RowWithoutPhase = OpenLaneRow
 
 /**
  * A `### Phase` heading (1-based line) whose tasks are all ticked on the base branch while its own section still
@@ -118,33 +119,14 @@ export const mergedPhasesWithOpenBoxes = (
 }
 
 /**
- * The rows of the lanes table (`## Spuren`) that are not in `previousLines` word for word and whose phases cell
- * names no phase id (`P10c`), so neither the view nor the watcher can tie that step to a phase. The table is read
- * as `parseSprintLanes` reads it (its first table, a lane closed when any of its rows says so); rows of a closed
- * lane are history and stay out.
+ * The changed rows of open lanes whose phases cell names no phase id (`P10c`), so neither the view nor the watcher
+ * can tie that step to a phase.
  */
 export const boardRowsWithoutPhase = (
   markdown: string,
   language: PlanLanguage,
   previousLines: ReadonlySet<string>,
-): RowWithoutPhase[] => {
-  const start = sectionStart(markdown, PLAN_VOCABULARY[language].sections.lanes)
-  if (start === -1) return []
-  const closed = new Set(
-    parseSprintLanes(markdown, language)
-      .filter((lane) => lane.closed)
-      .map((lane) => lane.name),
+): RowWithoutPhase[] =>
+  changedOpenLaneRows(markdown, language, previousLines).filter(
+    ({ phases }) => phaseIdsOfCell(phases, language).length === 0,
   )
-  const rows: RowWithoutPhase[] = []
-  let previous: string | null = null
-  for (const { index, line, cells } of firstTableRows(
-    sectionLines(markdown, PLAN_VOCABULARY[language].sections.lanes),
-  )) {
-    const [name = '', , , phases = ''] = cells
-    const lane = laneNameOf(name, previous)
-    previous = lane ?? previous
-    const counts = lane !== null && !closed.has(lane) && !previousLines.has(line)
-    if (counts && phaseIdsOfCell(phases, language).length === 0) rows.push({ line: start + index + 1, lane, phases })
-  }
-  return rows
-}

package/src/plan-format/progress.ts

@@ -33,30 +33,12 @@ export const sumPhases = (phases: readonly PhaseProgress[]): { done: number; tot
   total: phases.reduce((sum, phase) => sum + phase.total, 0),
 })
 
-const baseId = (id: string): string => id.replace(/[a-z]$/, '')
-
-const findPhase = (phases: PlanPhase[], id: string): PlanPhase | undefined =>
-  phases.find((phase) => phase.id === id) ?? phases.find((phase) => phase.id === baseId(id))
-
-/**
- * The ids of a step that show a phase of their own. An id the plan lacks (`5b`) falls back to its
- * base phase (`5`); when the step already names that phase by its own id, or an earlier id fell
- * back to it, the fallback would list the same tasks twice, so it is dropped. A lone fallback
- * stays: the sprint line `P4a` finds phase 4 in the plans that have no `4a`.
- */
-export const keptPhaseIds = (phases: PlanPhase[], ids: readonly string[]): string[] => {
-  const shown = new Set(ids.flatMap((id) => phases.filter((phase) => phase.id === id)))
-  return ids.filter((id) => {
-    const phase = findPhase(phases, id)
-    if (!phase || phase.id === id) return true
-    if (shown.has(phase)) return false
-    shown.add(phase)
-    return true
-  })
-}
+/** The phase with exactly this id: a board row's `3c` never falls back to phase 3. */
+const phaseById = <T extends { id: string }>(phases: readonly T[], id: string): T | undefined =>
+  phases.find((phase) => phase.id === id)
 
 const phaseProgress = (phases: PlanPhase[], id: string): PhaseProgress => {
-  const phase = findPhase(phases, id)
+  const phase = phaseById(phases, id)
   const items = phase?.items ?? []
   return {
     id,
@@ -102,16 +84,12 @@ const newestStepWith = (
 
 type LocatedPhase = { phase: PhaseProgress; current: NonNullable<LaneProgress['current']> }
 
-/** The phase a step shows for `id`: by that id, else by its base id, as `keptPhaseIds` keeps a lone fallback. */
-const shownPhase = (phases: readonly PhaseProgress[], id: string): PhaseProgress | undefined =>
-  phases.find((phase) => phase.id === id) ?? phases.find((phase) => phase.id === baseId(id))
-
 /** The phase `id` as the newest step before `before` that shows it from the same plan has it. */
 const earlierPhase = (steps: readonly StepProgress[], before: number, id: string): LocatedPhase | null => {
   const planHref = steps[before].step.planHref
   for (let stepIndex = before - 1; stepIndex >= 0; stepIndex--) {
     if (steps[stepIndex].step.planHref !== planHref) continue
-    const phase = shownPhase(steps[stepIndex].phases, id)
+    const phase = phaseById(steps[stepIndex].phases, id)
     if (phase) return { phase, current: { stepIndex, phaseId: phase.id } }
   }
   return null
@@ -179,7 +157,7 @@ export const currentPhaseOf = (steps: readonly StepProgress[]): LaneProgress['cu
 export const laneProgress = (lane: SprintLane, plans: PlansByHref): LaneProgress => {
   const steps = lane.steps.map((step) => {
     const phases = step.planHref ? plans[step.planHref] : undefined
-    return { step, phases: phases ? keptPhaseIds(phases, step.phaseIds).map((id) => phaseProgress(phases, id)) : [] }
+    return { step, phases: phases ? step.phaseIds.map((id) => phaseProgress(phases, id)) : [] }
   })
   return { lane, steps, current: currentPhaseOf(steps), ...sumPhases(steps.flatMap((step) => step.phases)) }
 }
@@ -187,7 +165,7 @@ export const laneProgress = (lane: SprintLane, plans: PlansByHref): LaneProgress
 export const currentPhase = (progress: LaneProgress): PhaseProgress | null => {
   if (!progress.current) return null
   const { stepIndex, phaseId } = progress.current
-  return progress.steps[stepIndex].phases.find((phase) => phase.id === phaseId) ?? null
+  return phaseById(progress.steps[stepIndex].phases, phaseId) ?? null
 }
 
 /** The item being worked on: the first open checkbox of a phase in plan order, a review-gate item included; null when none is open. */

package/src/plans/command.ts

@@ -27,8 +27,8 @@ const printOnce = async (source: Source): Promise<void> => {
 }
 
 /**
- * `jh plans [<board.md>] [--lane <name>] [--once | --ensure]`: a live view of a board's lanes and their plan
- * progress; `--ensure` instead brings back the missing views beside the coordinator and each lane.
+ * `jh herd [<board.md>] [--lane <name>] [--once | --ensure]`: a live view of a board's lanes and their plan
+ * progress; `--ensure` instead brings back the missing herd panes beside the coordinator and each lane.
  * `home` is where the global config is looked up when the project has none.
  */
 export const run = async (args: string[], home: string = homedir()): Promise<number> => {
@@ -45,7 +45,7 @@ export const run = async (args: string[], home: string = homedir()): Promise<num
         settings.adapter === TERMINAL_ADAPTER.herdr
           ? ensurePlanPanes(root, settings, picked.file)
           : ['the terminal adapter is not herdr: no panes to bring back']
-      for (const line of lines.length > 0 ? lines : ['every plans view is running']) console.log(line)
+      for (const line of lines.length > 0 ? lines : ['every herd pane is running']) console.log(line)
       return 0
     }
     const source = { root, sprintFile: picked.file, options, settings, terminal, boardNotice: picked.notice }

package/src/plans/current-phase.ts

@@ -0,0 +1,71 @@
+import { isTickedUnmerged, type LaneProgress, type PhaseProgress, type PlansByHref } from '../plan-format'
+
+/** A phase of a plan, as the sprint table spells the plan's link. */
+export type PhaseRef = { planHref: string; phaseId: string }
+
+/** Per plan link and phase id, the state of its checkboxes as `1` (ticked) and `0` (open) in plan order. */
+export type TickSnapshot = Record<string, Record<string, string>>
+
+/**
+ * What the herd remembers of a lane between two reads: the ticks it saw, the phase whose ticks moved last and the
+ * identity of the newest board row (`newestRowIdentity`), which a new row changes.
+ */
+export type LaneMemory = { ticks: TickSnapshot; moved: PhaseRef | null; row: string }
+
+export const tickSnapshotOf = (plans: PlansByHref): TickSnapshot =>
+  Object.fromEntries(
+    Object.entries(plans).map(([href, phases]) => [
+      href,
+      Object.fromEntries(
+        phases.map((phase) => [phase.id, phase.items.map((item) => (item.done ? '1' : '0')).join('')]),
+      ),
+    ]),
+  )
+
+/**
+ * The phases both reads have whose ticks differ, in plan order; a plan or phase new in `next` has no state to move
+ * from. A task added to or removed from a phase changes its tick string and counts as movement.
+ */
+export const movedPhases = (previous: TickSnapshot, next: TickSnapshot): PhaseRef[] =>
+  Object.entries(next).flatMap(([planHref, phases]) =>
+    Object.entries(phases).flatMap(([phaseId, ticks]) => {
+      const before = previous[planHref]?.[phaseId]
+      return before !== undefined && before !== ticks ? [{ planHref, phaseId }] : []
+    }),
+  )
+
+/** The newest board row of a lane as its step index and the phase ids it shows, a step `withWorkedPhases` added not counted. */
+export const newestRowIdentity = ({ steps }: LaneProgress): string => {
+  const index = steps.reduce((last, { step }, stepIndex) => (step.withoutRow ? last : stepIndex), -1)
+  return `${index}:${(steps[index]?.phases ?? []).map((phase) => phase.id).join(',')}`
+}
+
+/**
+ * The memory after a read of the lane's plans. The first read has no earlier ticks and no moved phase; exactly one
+ * moved phase becomes the remembered one; none keeps the one moved last; several at once decide nothing, so the
+ * newest board row rules again until a single phase moves. A changed newest board row (`row`) is an explicit
+ * signal and clears the memory.
+ */
+export const nextMemory = (previous: LaneMemory | undefined, plans: PlansByHref, row: string): LaneMemory => {
+  const ticks = tickSnapshotOf(plans)
+  if (!previous || previous.row !== row) return { ticks, moved: null, row }
+  const moved = movedPhases(previous.ticks, ticks)
+  if (moved.length === 0) return { ticks, moved: previous.moved, row }
+  return { ticks, moved: moved.length === 1 ? moved[0] : null, row }
+}
+
+/**
+ * The progress with `moved` as the current phase, in the newest step that shows it with checkboxes; unchanged
+ * when there is no moved phase, the lane does not show it or it is done and merged, so the newest board row decides
+ * as before.
+ */
+export const withMovedPhase = (progress: LaneProgress, moved: PhaseRef | null): LaneProgress => {
+  if (!moved) return progress
+  const isCurrentWork = (phase: PhaseProgress): boolean =>
+    phase.id === moved.phaseId && phase.total > 0 && (phase.done < phase.total || isTickedUnmerged(phase))
+  const showsIt = progress.steps.map(
+    ({ step, phases }) => step.planHref === moved.planHref && phases.some(isCurrentWork),
+  )
+  const stepIndex = showsIt.lastIndexOf(true)
+  return stepIndex < 0 ? progress : { ...progress, current: { stepIndex, phaseId: moved.phaseId } }
+}

package/src/plans/ensure-panes.ts

@@ -40,14 +40,14 @@ const apply = (action: PaneAction): string => {
         ? splitPaneOf(runHerdr(['pane', 'split', action.pane, '--direction', 'right', '--no-focus']))
         : action.pane
     runHerdr(['pane', 'run', target, action.command])
-    return `${action.kind === 'split' ? `split ${action.pane}, ` : ''}started the plans view in ${target}`
+    return `${action.kind === 'split' ? `split ${action.pane}, ` : ''}started the herd in ${target}`
   } catch (error) {
     return `${action.pane}: ${errorText(error)}`
   }
 }
 
 /**
- * `plans --ensure`: brings back every missing plans view beside the coordinator and each lane of the board, and
+ * `herd --ensure`: brings back every missing herd pane beside the coordinator and each lane of the board, and
  * leaves running ones alone, so it can run after every start. A lane gets its view once its agent runs. One line per
  * action or skipped target, none when every view runs.
  */

package/src/plans/herd-command.ts

@@ -0,0 +1,4 @@
+/** The CLI word of the herd and the alias it had up to 1.6, which running panes of that version still carry. */
+export const HERD_COMMAND = { name: 'herd', alias: 'plans' } as const
+
+export const HERD_COMMAND_WORDS: readonly string[] = Object.values(HERD_COMMAND)

package/src/plans/lane-discovery.ts

@@ -9,14 +9,26 @@ export type LaneSources = {
 
 export type LaneSetChange = { added: string[]; removed: string[] }
 
+/**
+ * The helper agents of the lanes: an agent named `<lane>-<purpose>` that a lane started in a pane of its own, such as
+ * for a measurement. A name that is a worktree of its own is that lane, not a helper. The prefix only decides whether
+ * the agent is watched, not whose it is: under lanes `a` and `a-b` the agent `a-b-c` matches both and is watched once,
+ * and any agent named after a lane with a suffix is watched, whoever started it.
+ */
+const helpersOf = (lanes: readonly string[], worktrees: readonly string[], agentNames: readonly string[]): string[] =>
+  [...new Set(agentNames)].filter(
+    (name) => !worktrees.includes(name) && lanes.some((lane) => name.startsWith(`${lane}-`)),
+  )
+
 /**
  * The lanes to watch when none are named: a worktree directory whose name a herdr agent carries or
  * the board's lanes table lists. A worktree with neither (a branch parked in its own checkout) is no
- * lane, and an agent or a row without a worktree is none either.
+ * lane, and an agent or a row without a worktree is none either, except a lane's helper agent (`helpersOf`).
  */
 export const discoverLanes = ({ worktrees, agentNames, sprintLanes }: LaneSources): string[] => {
   const claimed = new Set([...agentNames, ...sprintLanes])
-  return [...new Set(worktrees)].filter((worktree) => claimed.has(worktree)).sort()
+  const lanes = [...new Set(worktrees)].filter((worktree) => claimed.has(worktree))
+  return [...lanes, ...helpersOf(lanes, worktrees, agentNames)].sort()
 }
 
 /** The lanes that joined and left between two discoveries, each sorted. */

package/src/plans/lane-tickets.ts

@@ -0,0 +1,69 @@
+import type { SprintLane } from '../plan-format'
+import type { SourceTicket, TicketBadge } from '../watch/plan-badges'
+import type { LinkChip } from './link-chips'
+import { shownWithMore } from './shown-with-more'
+
+/** The tickets of one lane as drawn: the first `SHOWN_TICKETS`, how many more, and how many of all are new. */
+export type LaneTickets = { shown: TicketBadge[]; more: number; newCount: number }
+
+export const SHOWN_TICKETS = 3
+
+const WORD_CHARACTER = /[\p{L}\p{N}_]/u
+
+const isWordCharacter = (character: string | undefined): boolean =>
+  character !== undefined && WORD_CHARACTER.test(character)
+
+/**
+ * Whether `text` names `id` as a whole word: no letter, digit or `_` right before or after it, so `T-12` is not
+ * found in `T-123`. A plain search per occurrence, no regular expression: a lookbehind over a long plan cost
+ * seconds per refresh. An empty id is found nowhere.
+ */
+const namesWord = (text: string, id: string): boolean => {
+  if (id === '') return false
+  for (let at = text.indexOf(id); at !== -1; at = text.indexOf(id, at + 1)) {
+    if (!isWordCharacter(text[at - 1]) && !isWordCharacter(text[at + id.length])) return true
+  }
+  return false
+}
+
+const belongsTo = (ticket: SourceTicket, lane: string, texts: readonly string[]): boolean =>
+  ticket.lane === lane || [lane, ...texts].some((text) => namesWord(text, ticket.id))
+
+const onceById = (tickets: readonly SourceTicket[]): SourceTicket[] =>
+  tickets.filter((ticket, index) => tickets.findIndex(({ id }) => id === ticket.id) === index)
+
+const badgeOf = ({ lane: _lane, ...badge }: SourceTicket): TicketBadge => badge
+
+/** What the lane's board rows say of it beside its name, for finding ticket ids: the text of each row. */
+export const boardRowTexts = (lane: SprintLane): string[] => lane.steps.map(({ label }) => label)
+
+/**
+ * The tickets of `lane`: those of a source that names it, and those whose id the lane's name or `texts` (its board
+ * rows and its plans) name as a whole word, as written. A ticket listed twice counts once, from its first source.
+ * New tickets come first, the rest keep their order; null when the lane has none, so the view draws nothing.
+ */
+export const laneTicketsOf = (
+  tickets: readonly SourceTicket[],
+  lane: string,
+  texts: readonly string[],
+): LaneTickets | null => {
+  const own = onceById(tickets.filter((ticket) => belongsTo(ticket, lane, texts))).map(badgeOf)
+  if (own.length === 0) return null
+  const fresh = own.filter(({ isNew }) => isNew)
+  const ordered = [...fresh, ...own.filter(({ isNew }) => !isNew)]
+  return {
+    ...shownWithMore(ordered, SHOWN_TICKETS),
+    newCount: fresh.length,
+  }
+}
+
+/** The lane's link chips without those whose URL a shown ticket badge opens: the badge takes the chip's place. */
+export const withoutTicketLinks = (
+  chips: Record<string, LinkChip[]>,
+  tickets: LaneTickets,
+): Record<string, LinkChip[]> => {
+  const shown = new Set(tickets.shown.flatMap(({ url }) => (url ? [url] : [])))
+  return Object.fromEntries(
+    Object.entries(chips).map(([href, list]) => [href, list.filter(({ url }) => !shown.has(url))]),
+  )
+}