jackherd 1.24.0 → 1.25.0

package/src/vocabulary/index.ts

@@ -2,6 +2,12 @@ export const PLAN_LANGUAGE = { de: 'de', en: 'en' } as const
 
 export type PlanLanguage = (typeof PLAN_LANGUAGE)[keyof typeof PLAN_LANGUAGE]
 
+/** The languages to try when reading: `language` first, then every other known one. */
+export const languagesFrom = (language: PlanLanguage): PlanLanguage[] => [
+  language,
+  ...Object.values(PLAN_LANGUAGE).filter((other) => other !== language),
+]
+
 /** The language's name as a reply or a question says it. */
 export const LANGUAGE_NAME: Record<PlanLanguage, string> = {
   [PLAN_LANGUAGE.en]: 'English',
@@ -175,6 +181,111 @@ export const WAITING_VOCABULARY: Record<
   },
 }
 
+/**
+ * The closed set of keys a section carries in a marker, `<!-- jh: <key> -->` on the line directly under its heading.
+ * The marker names the section whatever language the heading is written in.
+ */
+export const SECTION_KEY = {
+  waiting: 'waiting',
+  appointments: 'appointments',
+  lanes: 'lanes',
+  goal: 'goal',
+  history: 'history',
+  plans: 'plans',
+  decisions: 'decisions',
+  implementation: 'implementation',
+  model: 'model',
+  dependencies: 'dependencies',
+  documentation: 'documentation',
+  forYou: 'for-you',
+  next: 'next',
+} as const
+
+export type SectionKey = (typeof SECTION_KEY)[keyof typeof SECTION_KEY]
+
+export const isSectionKey = (value: string): value is SectionKey =>
+  (Object.values(SECTION_KEY) as string[]).includes(value)
+
+/**
+ * The marker key of each line of the head section (`- **Stand:** <!-- jh: head-status --> …`). The marker names the
+ * line whatever language its label is written in.
+ */
+export const HEAD_KEY: Record<HeadLine, string> = {
+  changes: 'head-changes',
+  status: 'head-status',
+  decisions: 'head-decisions',
+  tryNow: 'head-try-now',
+  next: 'head-next',
+}
+
+/**
+ * The closed set of keys a line that opens with bold words carries in a marker
+ * (`**Kein Review-Gate** <!-- jh: no-review-gate --> reason`). The marker names the line whatever language it is in.
+ */
+export const LINE_KEY = { noReviewGate: 'no-review-gate', purpose: 'purpose' } as const
+
+/**
+ * The closed set of keys a table column carries in a marker in its header cell (`Hängt ab von <!-- jh: depends-on -->`).
+ * The marker names the column whatever language the header is written in.
+ */
+export const COLUMN_KEY = {
+  since: 'since',
+  item: 'item',
+  origin: 'origin',
+  unblocks: 'unblocks',
+  status: 'status',
+  when: 'when',
+  action: 'action',
+  dependsOn: 'depends-on',
+  writes: 'writes',
+  serialMarker: 'serial-marker',
+} as const
+
+export type ColumnKey = (typeof COLUMN_KEY)[keyof typeof COLUMN_KEY]
+
+/** The header names the column `key` goes by in `language`: its name first, then the names that count as the same column. */
+export const columnWords = (key: ColumnKey, language: PlanLanguage): readonly string[] => {
+  const waiting = WAITING_VOCABULARY[language]
+  const appointments = APPOINTMENT_VOCABULARY[language]
+  const { columns } = PLAN_VOCABULARY[language]
+  const words: Record<ColumnKey, readonly string[]> = {
+    [COLUMN_KEY.since]: [waiting.columns.since],
+    [COLUMN_KEY.item]: [waiting.columns.item],
+    [COLUMN_KEY.origin]: [waiting.columns.origin],
+    [COLUMN_KEY.unblocks]: [waiting.columns.unblocks],
+    [COLUMN_KEY.status]: [
+      waiting.columns.status,
+      ...waiting.statusAlso,
+      appointments.columns.status,
+      ...appointments.statusAlso,
+    ],
+    [COLUMN_KEY.when]: [appointments.columns.when],
+    [COLUMN_KEY.action]: [appointments.columns.action],
+    [COLUMN_KEY.dependsOn]: [columns.dependsOn],
+    [COLUMN_KEY.writes]: [columns.writes],
+    [COLUMN_KEY.serialMarker]: [columns.serialMarker],
+  }
+  return words[key]
+}
+
+/**
+ * The closed set of keys a status carries in a marker in its cell (`erledigt <!-- jh: status-done -->`): `open` for a
+ * board row that still waits, the others for the status of a plan. The marker names the status whatever language the
+ * cell is written in.
+ */
+export const STATUS_KEY = {
+  open: 'status-open',
+  done: 'status-done',
+  abandoned: 'status-abandoned',
+  inProgress: 'status-in-progress',
+  draft: 'status-draft',
+} as const
+
+export type StatusKey = (typeof STATUS_KEY)[keyof typeof STATUS_KEY]
+
+export const isStatusKey = (value: string): value is StatusKey =>
+  (Object.values(STATUS_KEY) as string[]).includes(value)
+
 export const isPlanLanguage = (value: string): value is PlanLanguage =>
   (Object.values(PLAN_LANGUAGE) as string[]).includes(value)
 
@@ -248,6 +359,8 @@ export type PlanVocabulary = {
   phase: string
   /** Opens the line by which a phase says it has no review gate on purpose: `**Kein Review-Gate:** <reason>`. */
   noReviewGate: string
+  /** Opens the line directly under a phase heading that says in one sentence what is different afterwards, for whom: `**Worum es geht:** <sentence>`. */
+  phasePurpose: string
   /** Marks a lane as closed when its name cell contains it. */
   laneClosed: string
   /** Stands in a board row's phases cell when that pull request builds only part of the phase. */
@@ -296,6 +409,7 @@ export const PLAN_VOCABULARY: Record<PlanLanguage, PlanVocabulary> = {
     columns: { dependsOn: 'Hängt ab von', writes: 'Schreibt', serialMarker: 'Seriell-Marker' },
     phase: 'Phase',
     noReviewGate: 'Kein Review-Gate',
+    phasePurpose: 'Worum es geht',
     laneClosed: 'abgeräumt',
     partialPhase: '(Teil)',
     openSubagents: 'offene Sub-Agenten',
@@ -339,6 +453,7 @@ export const PLAN_VOCABULARY: Record<PlanLanguage, PlanVocabulary> = {
     columns: { dependsOn: 'Depends on', writes: 'Writes', serialMarker: 'Serial marker' },
     phase: 'Phase',
     noReviewGate: 'No review gate',
+    phasePurpose: 'What it is about',
     laneClosed: 'cleaned up',
     partialPhase: '(part)',
     openSubagents: 'open subagents',
@@ -362,20 +477,93 @@ export const PLAN_VOCABULARY: Record<PlanLanguage, PlanVocabulary> = {
 
 const STATUS_PRECEDENCE = [PLAN_STATUS.done, PLAN_STATUS.abandoned, PLAN_STATUS.inProgress, PLAN_STATUS.draft] as const
 
-/** Classifies a free-text `Status:` line; the first matching status in precedence order wins. */
-export const classifyStatus = (language: PlanLanguage, statusText: string): PlanStatus => {
+const STATUS_OF_KEY: Partial<Record<StatusKey, PlanStatus>> = {
+  [STATUS_KEY.done]: PLAN_STATUS.done,
+  [STATUS_KEY.abandoned]: PLAN_STATUS.abandoned,
+  [STATUS_KEY.inProgress]: PLAN_STATUS.inProgress,
+  [STATUS_KEY.draft]: PLAN_STATUS.draft,
+}
+
+/** A `<!-- jh: <key> -->` marker anywhere in a text; the key is group 1. */
+export const MARKER_IN_TEXT = /<!--\s*jh:\s*([a-z-]+)\s*-->/
+
+const statusOfMarker = (statusText: string): PlanStatus | undefined => {
+  const key = MARKER_IN_TEXT.exec(statusText)?.[1]
+  return key !== undefined && isStatusKey(key) ? STATUS_OF_KEY[key] : undefined
+}
+
+const statusOfWords = (language: PlanLanguage, statusText: string): PlanStatus | undefined => {
   const { statusWords } = PLAN_VOCABULARY[language]
   const lowerStatus = statusText.toLowerCase()
   const matches = ({ leading, anywhere }: StatusWord) =>
     leading.some((word) => lowerStatus.startsWith(word)) || anywhere.some((fragment) => lowerStatus.includes(fragment))
-  const matched = STATUS_PRECEDENCE.find((status) => matches(statusWords[status]))
+  return STATUS_PRECEDENCE.find((status) => matches(statusWords[status]))
+}
+
+/**
+ * Classifies a free-text `Status:` line. A status marker (`<!-- jh: status-done -->`) decides, any language; else the
+ * first matching status in precedence order of the words of `language`, then of any other known language.
+ */
+export const classifyStatus = (language: PlanLanguage, statusText: string): PlanStatus => {
+  const marked = statusOfMarker(statusText)
+  if (marked) return marked
+  const text = statusText.replace(MARKER_IN_TEXT, '')
+  const matched = languagesFrom(language)
+    .map((candidate) => statusOfWords(candidate, text))
+    .find((status) => status !== undefined)
   if (matched) return matched
-  return statusText.trim() ? PLAN_STATUS.other : PLAN_STATUS.none
+  return text.trim() ? PLAN_STATUS.other : PLAN_STATUS.none
 }
 
 /** `### Phase 3: Title` as the plan spells it in `language`. */
 export const phaseHeading = (language: PlanLanguage, id: string, title: string): string =>
   `### ${PLAN_VOCABULARY[language].phase} ${id}: ${title}`
 
+/** The heading text of the section `key` names, as `language` writes it. */
+export const headingOfSection = (key: SectionKey, language: PlanLanguage): string => {
+  const { sections } = PLAN_VOCABULARY[language]
+  const headings: Record<SectionKey, string> = {
+    [SECTION_KEY.waiting]: WAITING_VOCABULARY[language].heading,
+    [SECTION_KEY.appointments]: APPOINTMENT_VOCABULARY[language].heading,
+    [SECTION_KEY.lanes]: sections.lanes,
+    [SECTION_KEY.goal]: sections.goal,
+    [SECTION_KEY.history]: sections.history,
+    [SECTION_KEY.plans]: sections.plans,
+    [SECTION_KEY.decisions]: sections.decisions,
+    [SECTION_KEY.implementation]: sections.implementation,
+    [SECTION_KEY.model]: sections.modelRecommendations,
+    [SECTION_KEY.dependencies]: sections.dependencies,
+    [SECTION_KEY.documentation]: sections.documentation,
+    [SECTION_KEY.forYou]: sections.forYou,
+    [SECTION_KEY.next]: NEXT_VOCABULARY[language].heading,
+  }
+  return headings[key]
+}
+
+/** The key and language of the section a heading text names, read the way a caller spells it; `null` when no language does. */
+export const sectionOfHeading = (headingText: string): { key: SectionKey; language: PlanLanguage } | null => {
+  for (const language of Object.values(PLAN_LANGUAGE)) {
+    const key = Object.values(SECTION_KEY).find((candidate) => headingOfSection(candidate, language) === headingText)
+    if (key !== undefined) return { key, language }
+  }
+  return null
+}
+
+/**
+ * The closed set of keys a lanes-table cell carries in a marker: `lane-closed` in the name cell of a lane that was
+ * cleaned up, `partial-phase` in the phases cell of a row that builds only part of a phase.
+ */
+export const CELL_KEY = { laneClosed: 'lane-closed', partialPhase: 'partial-phase' } as const
+
+export type CellKey = (typeof CELL_KEY)[keyof typeof CELL_KEY]
+
+/** The words of every known language that mark a lane as cleaned up. */
+export const LANE_CLOSED_WORDS: readonly string[] = Object.values(PLAN_VOCABULARY).map(({ laneClosed }) => laneClosed)
+
+/** The words of every known language that mark a row as building only part of a phase. */
+export const PARTIAL_PHASE_WORDS: readonly string[] = Object.values(PLAN_VOCABULARY).map(
+  ({ partialPhase }) => partialPhase,
+)
+
 export const sectionHeading = (language: PlanLanguage, section: keyof PlanVocabulary['sections']): string =>
   `## ${PLAN_VOCABULARY[language].sections[section]}`

package/src/watch/appointments.ts

@@ -1,7 +1,8 @@
 import { DAY_MS, twoDigits } from '../plan-format/clock'
-import { firstTableWithHeader, sectionLines } from '../plan-format/markdown'
+import { columnIndex, firstTableWithHeader, sectionLines } from '../plan-format/markdown'
+import { isOpenStatus } from '../plan-format/open-status'
 import { isRecord } from '../shared/is-record'
-import { APPOINTMENT_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { APPOINTMENT_VOCABULARY, COLUMN_KEY, type PlanLanguage } from '../vocabulary'
 
 export const APPOINTMENT_EVENT = { due: 'due', unreadable: 'appointment unreadable' } as const
 
@@ -98,22 +99,15 @@ const unreadableKey = ({ whenText, action }: UnreadableAppointment): string => `
 
 const oneLine = (text: string): string => text.replace(/\s+/g, ' ').trim()
 
-/** An empty status counts as open: a row nobody closed is not dropped in silence. */
-const isOpen = (status: string, language: PlanLanguage): boolean => {
-  const lower = status.toLowerCase()
-  return lower === '' || APPOINTMENT_VOCABULARY[language].open.some((word) => lower.startsWith(word))
-}
+const OPEN_WORDS = Object.values(APPOINTMENT_VOCABULARY).flatMap(({ open }) => open)
+
+const isOpen = (status: string): boolean => isOpenStatus(status, OPEN_WORDS)
 
 /** The row as an appointment, as an unreadable row when it is open and its time cannot be read, else as nothing. */
-const tableOfRow = (
-  cells: string[],
-  [when, action, status]: number[],
-  language: PlanLanguage,
-  now: Date,
-): AppointmentTable => {
+const tableOfRow = (cells: string[], [when, action, status]: number[], now: Date): AppointmentTable => {
   const whenText = cells[when] ?? ''
   const actionText = oneLine(cells[action] ?? '')
-  const open = isOpen(cells[status] ?? '', language)
+  const open = isOpen(cells[status] ?? '')
   const time = parseAppointmentTime(whenText, now)
   if (time)
     return {
@@ -130,19 +124,18 @@ const tableOfRow = (
  * listed as unreadable as a whole, with its header and the missing names; a section without a table has no rows.
  */
 export const readAppointmentTable = (board: string, language: PlanLanguage, now: Date): AppointmentTable => {
-  const { heading, columns, statusAlso } = APPOINTMENT_VOCABULARY[language]
+  const { heading, columns } = APPOINTMENT_VOCABULARY[language]
   const { header, rows } = firstTableWithHeader(sectionLines(board, heading))
   if (header.length === 0) return { appointments: [], unreadable: [] }
-  const statusName = [columns.status, ...statusAlso].find((name) => header.includes(name)) ?? columns.status
-  const needed = [columns.when, columns.action, statusName]
-  const missing = needed.filter((name) => !header.includes(name))
+  const needed = [COLUMN_KEY.when, COLUMN_KEY.action, COLUMN_KEY.status] as const
+  const positions = needed.map((key) => columnIndex(header, key, language))
+  const missing = needed.filter((_, index) => positions[index] === -1).map((key) => columns[key])
   if (missing.length > 0)
     return {
       appointments: [],
       unreadable: [{ whenText: header.join(' | '), action: `missing columns: ${missing.join(', ')}` }],
     }
-  const positions = needed.map((name) => header.indexOf(name))
-  const tables = rows.map((cells) => tableOfRow(cells, positions, language, now))
+  const tables = rows.map((cells) => tableOfRow(cells, positions, now))
   return {
     appointments: tables.flatMap(({ appointments }) => appointments),
     unreadable: tables.flatMap(({ unreadable }) => unreadable),

package/src/watch/command.ts

@@ -609,7 +609,7 @@ const boardReadOf = async (
   pullRequests: readonly WatchedPullRequest[],
 ): Promise<{ progress: Record<string, LaneProgress>; checkoutRows: number }> => {
   const text = await Bun.file(watch.sprintFile).text()
-  const sprintLanes = parseSprintLanes(text, watch.settings.planLanguage)
+  const sprintLanes = parseSprintLanes(text, watch.settings.boardLanguage)
   const watched = sprintLanes.filter((lane) => lanes.includes(lane.name))
   const planPulls = watchedPlanPullRequests(pullRequests, watch.settings)
   const headReaderOf = readerOncePerRef((ref) => baseReaderOf(watch.root, ref))
@@ -1108,13 +1108,13 @@ const readBoardText = (watch: Watch): string | null => {
 const readAppointments = (watch: Watch, now: number): Watching['appointments'] => {
   const board = readBoardText(watch)
   if (board === null) return null
-  return { table: readAppointmentTable(board, watch.settings.planLanguage, new Date(now)), readAt: now }
+  return { table: readAppointmentTable(board, watch.settings.boardLanguage, new Date(now)), readAt: now }
 }
 
 /** The line of what waits on the user's answer, from the board's own section; null when nothing is open or the board cannot be read. */
 const waitingLineOf = (watch: Watch, hint = ''): string | null => {
   return waitingLine(
-    waitingItemsOf(readBoardText(watch), watch.settings.planLanguage, readWaitingRecords(watch.root), Date.now()),
+    waitingItemsOf(readBoardText(watch), watch.settings.boardLanguage, readWaitingRecords(watch.root), Date.now()),
     hint,
   )
 }
@@ -1122,7 +1122,7 @@ const waitingLineOf = (watch: Watch, hint = ''): string | null => {
 /** The board's lanes, null when the board cannot be read. */
 const readSprintLanes = (watch: Watch): SprintLane[] | null => {
   const board = readBoardText(watch)
-  return board === null ? null : parseSprintLanes(board, watch.settings.planLanguage)
+  return board === null ? null : parseSprintLanes(board, watch.settings.boardLanguage)
 }
 
 /** The sprint's lane names; the previous ones when the sprint cannot be read, so no lane drops out over it. */
@@ -1449,7 +1449,7 @@ const selfMergesOf = (watch: Watch, watching: Watching, now: number): number[] =
   const open = Object.entries(watching.state.pullRequests).flatMap(([number, { state }]) =>
     state === PULL_REQUEST_STATE.open ? [Number(number)] : [],
   )
-  return selfMergePullRequests(board, watch.settings.planLanguage, open, now, watch.selfMergeMinutes)
+  return selfMergePullRequests(board, watch.settings.boardLanguage, open, now, watch.selfMergeMinutes)
 }
 
 const clearInputOf = (

package/src/watch/lane-progress.ts

@@ -224,5 +224,5 @@ export const boardCheckoutRows = (
   checkoutText: string,
 ): number => {
   const atBase = textAtBase(baseReaderOf(root, baseRefOf(settings)), boardRepoPathOf(root, settings, boardFile))
-  return atBase === null ? 0 : boardRowsOf(atBase, checkoutText, settings.planLanguage).rowsFromCheckout
+  return atBase === null ? 0 : boardRowsOf(atBase, checkoutText, settings.boardLanguage).rowsFromCheckout
 }

package/src/watch/merge-overlap-read.ts

@@ -1,7 +1,7 @@
 import { STACKS } from '../config/detect'
 import { isObjectId } from '../lane/close-survey'
 import { parseSprintLanes } from '../plan-format'
-import type { PlansSettings } from '../plans/settings'
+import { type PlansSettings } from '../plans/settings'
 import { lanePlanPath, watchedLanePlanText } from './lane-progress'
 import type { OverlapOf } from './lane-report'
 import { type LaneScope, type MergeOverlap, overlapOf } from './merge-duties'
@@ -39,7 +39,7 @@ const scopeOf = (
   boardText: string,
   name: string,
 ): LaneScope | null => {
-  const lane = parseSprintLanes(boardText, settings.planLanguage).find((candidate) => candidate.name === name)
+  const lane = parseSprintLanes(boardText, settings.boardLanguage).find((candidate) => candidate.name === name)
   if (lane === undefined) return null
   const text = watchedLanePlanText(root, settings, boardFile, lane)
   if (text === null) return null

package/src/watch/plan-missing-read.ts

@@ -19,7 +19,9 @@ import {
 const worktreePlanOf = (root: string, settings: PlansSettings, boardFile: string, laneName: string): string | null => {
   const file = join(worktreeOf(root, settings, laneName), boardRepoPathOf(root, settings, boardFile))
   if (!existsSync(file)) return null
-  const lane = parseSprintLanes(readFileSync(file, 'utf8'), settings.planLanguage).find(({ name }) => name === laneName)
+  const lane = parseSprintLanes(readFileSync(file, 'utf8'), settings.boardLanguage).find(
+    ({ name }) => name === laneName,
+  )
   const path = lane === undefined ? null : lanePlanPath(root, settings, boardFile, lane)
   return path === null || isOutsideRepository(path) ? null : path
 }