jackherd 1.24.0 → 1.26.0

package/src/plan-format/markdown.ts

@@ -1,3 +1,15 @@
+import {
+  type CellKey,
+  type ColumnKey,
+  columnWords,
+  headingOfSection,
+  isSectionKey,
+  languagesFrom,
+  MARKER_IN_TEXT,
+  type PlanLanguage,
+  type SectionKey,
+  sectionOfHeading,
+} from '../vocabulary'
 import { terminalSafe } from './terminal-text'
 
 const SECTION_END = /^##\s/
@@ -5,20 +17,120 @@ const TABLE_SEPARATOR = /^\|[\s|:-]+\|$/
 
 export const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 
-/** The index of the line after a level-2 heading with exactly this text; -1 when there is none. */
-export const sectionStart = (markdown: string, headingText: string): number => {
-  const heading = new RegExp(`^##\\s+${escapeRegExp(headingText)}\\s*$`)
+const MARKER = /^<!--\s*jh:\s*([a-z-]+)\s*-->\s*$/
+
+/** The key of the `<!-- jh: <key> -->` marker in `text`, wherever it stands; null when there is none. The key is not checked against any vocabulary. */
+export const markedKeyOf = (text: string): string | null => MARKER_IN_TEXT.exec(text)?.[1] ?? null
+
+/** `text` without its marker, trimmed: what a cell or a line says in words. */
+export const withoutMarker = (text: string): string => text.replace(MARKER_IN_TEXT, '').trim()
+
+/**
+ * What a reader looked for when it found no section `key`: `(looked for "### A", "### B" or <!-- jh: key -->)`, the
+ * heading of `language` first. `level` is the heading marks the reader accepts (`##` or `###`).
+ */
+export const lookedForSection = (key: SectionKey, level: '##' | '###', language: PlanLanguage): string => {
+  const headings = languagesFrom(language).map((candidate) => `"${level} ${headingOfSection(key, candidate)}"`)
+  return `(looked for ${headings.join(', ')} or <!-- jh: ${key} -->)`
+}
+
+/** Whether `text` carries the marker `key` or contains one of `words`: a state a cell names in any language. */
+export const namesState = (text: string, key: CellKey, words: readonly string[]): boolean =>
+  markedKeyOf(text) === key || words.some((word) => text.includes(word))
+
+export const SECTION_HEADING = /^##\s+(.*?)\s*$/
+
+const markerKey = (line: string | undefined): SectionKey | null => {
+  const key = line === undefined ? undefined : MARKER.exec(line)?.[1]
+  return key !== undefined && isSectionKey(key) ? key : null
+}
+
+type HeadingMatch = { pattern: RegExp; matches: (text: string, heading: string) => boolean }
+
+const SECTION_MATCH: HeadingMatch = { pattern: SECTION_HEADING, matches: (text, heading) => text === heading }
+const SUBSECTION_MATCH: HeadingMatch = {
+  pattern: /^(#{2,4})\s+(.*?)\s*$/,
+  matches: (text, heading) => text.startsWith(heading),
+}
+
+const headingText = (line: string, { pattern }: HeadingMatch): string | undefined => pattern.exec(line)?.at(-1)
+
+const headingIndexOf = (lines: string[], key: SectionKey, language: PlanLanguage, match: HeadingMatch): number => {
+  const marked = lines.findIndex((line, index) => match.pattern.test(line) && markerKey(lines[index + 1]) === key)
+  if (marked !== -1) return marked
+  for (const candidate of languagesFrom(language)) {
+    const heading = headingOfSection(key, candidate)
+    const found = lines.findIndex((line) => {
+      const text = headingText(line, match)
+      return text !== undefined && match.matches(text, heading)
+    })
+    if (found !== -1) return found
+  }
+  return -1
+}
+
+/**
+ * The index of the line after the level-2 heading that names the section `key`; -1 when none does. A heading names it by the
+ * marker `<!-- jh: <key> -->` on the line directly under it (any language), else by the text of `language`, else by the
+ * text of any other known language. The marker line itself is not part of the section.
+ */
+export const findSectionStart = (markdown: string, key: SectionKey, language: PlanLanguage): number => {
+  const lines = markdown.split('\n')
+  const heading = headingIndexOf(lines, key, language, SECTION_MATCH)
+  if (heading === -1) return -1
+  return heading + (markerKey(lines[heading + 1]) === key ? 2 : 1)
+}
+
+/** The 0-based index of the level-2 heading that names the section `key`, found as `findSectionStart` finds it; -1 when none does. */
+export const findSectionHeading = (markdown: string, key: SectionKey, language: PlanLanguage): number =>
+  headingIndexOf(markdown.split('\n'), key, language, SECTION_MATCH)
+
+const untilNextSection = (rest: string[]): string[] => {
+  const end = rest.findIndex((line) => SECTION_END.test(line))
+  return end === -1 ? rest : rest.slice(0, end)
+}
+
+/** The lines of the section `key` names (see `findSectionStart`), up to the next level-2 heading; empty when none does. */
+export const findSection = (markdown: string, key: SectionKey, language: PlanLanguage): string[] => {
+  const start = findSectionStart(markdown, key, language)
+  return start === -1 ? [] : untilNextSection(markdown.split('\n').slice(start))
+}
+
+/**
+ * The position of the column `key` names among the header cells; -1 when none does. A cell names it by the marker
+ * `<!-- jh: <key> -->` (any language), else by a header name of `language`, else by one of any other known language.
+ */
+export const columnIndex = (header: string[], key: ColumnKey, language: PlanLanguage): number => {
+  const marked = header.findIndex((cell) => markedKeyOf(cell) === key)
+  if (marked !== -1) return marked
+  const names = header.map(withoutMarker)
+  for (const candidate of languagesFrom(language)) {
+    for (const word of columnWords(key, candidate)) {
+      const found = names.indexOf(word)
+      if (found !== -1) return found
+    }
+  }
+  return -1
+}
+
+const exactSectionStart = (markdown: string, headingTextValue: string): number => {
+  const heading = new RegExp(`^##\\s+${escapeRegExp(headingTextValue)}\\s*$`)
   const start = markdown.split('\n').findIndex((line) => heading.test(line))
   return start === -1 ? -1 : start + 1
 }
 
-/** The lines under a level-2 heading with exactly this text, up to the next level-2 heading. */
+/** The index of the line after a level-2 heading with exactly this text, or after the one that names the same section in another language or by marker; -1 when there is none. */
+export const sectionStart = (markdown: string, headingText: string): number => {
+  const section = sectionOfHeading(headingText)
+  return section === null
+    ? exactSectionStart(markdown, headingText)
+    : findSectionStart(markdown, section.key, section.language)
+}
+
+/** The lines under that heading (see `sectionStart`), up to the next level-2 heading. */
 export const sectionLines = (markdown: string, headingText: string): string[] => {
   const start = sectionStart(markdown, headingText)
-  if (start === -1) return []
-  const rest = markdown.split('\n').slice(start)
-  const end = rest.findIndex((line) => SECTION_END.test(line))
-  return end === -1 ? rest : rest.slice(0, end)
+  return start === -1 ? [] : untilNextSection(markdown.split('\n').slice(start))
 }
 
 const tableCells = (line: string): string[] =>
@@ -57,8 +169,11 @@ export const firstHeading = (markdown: string, fallback: string): string =>
 const HEADING = /^(#{2,4})\s+(.*?)\s*$/
 
 /** The 0-based line index of the first level 2 to 4 heading whose text starts with `headingText` (a suffix such as `(PFLICHT ab 3 Phasen)` is allowed); -1 when there is none. */
-export const subsectionStart = (markdown: string, headingText: string): number =>
-  markdown.split('\n').findIndex((line) => HEADING.exec(line)?.[2].startsWith(headingText))
+export const subsectionStart = (markdown: string, headingText: string): number => {
+  const section = sectionOfHeading(headingText)
+  if (section !== null) return headingIndexOf(markdown.split('\n'), section.key, section.language, SUBSECTION_MATCH)
+  return markdown.split('\n').findIndex((line) => HEADING.exec(line)?.[2].startsWith(headingText))
+}
 
 /** The lines under that heading (see `subsectionStart`), up to the next heading of the same or a higher level. */
 export const subsectionLines = (markdown: string, headingText: string): string[] => {

package/src/plan-format/open-status.ts

@@ -0,0 +1,15 @@
+import { isStatusKey, STATUS_KEY } from '../vocabulary'
+import { markedKeyOf, withoutMarker } from './markdown'
+
+/**
+ * Whether a status cell of a board row says the row is still open. A status marker decides (`<!-- jh: status-open -->`
+ * is open, any other status marker is not); else an empty cell is open (a row nobody closed is not dropped in
+ * silence), and so is a cell that starts with one of the lower-case `openWords`. The words come from every known
+ * language, so a board need not match the configured one.
+ */
+export const isOpenStatus = (status: string, openWords: readonly string[]): boolean => {
+  const marked = markedKeyOf(status)
+  if (marked !== null && isStatusKey(marked)) return marked === STATUS_KEY.open
+  const lower = withoutMarker(status).toLowerCase()
+  return lower === '' || openWords.some((word) => lower.startsWith(word))
+}

package/src/plan-format/phases.ts

@@ -1,6 +1,6 @@
-import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { LINE_KEY, languagesFrom, PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
 import { PHASE_ID_PREFIX } from './lanes'
-import { escapeRegExp } from './markdown'
+import { escapeRegExp, markedKeyOf, withoutMarker } from './markdown'
 import { terminalSafe } from './terminal-text'
 
 /** A checkbox of a plan. `gate` is set on the ones listed under the phase's review gate, and only on those. */
@@ -29,11 +29,13 @@ export type PhaseWorkFields = {
 /**
  * `work` is set by the phase source and says nothing for a phase the worktree left as the base has it; a merged phase
  * is touched as well. `deferred` holds the checkboxes moved to another phase; they are not among `items`, so they
- * count neither as open nor as done.
+ * count neither as open nor as done. `purpose` is the sentence of the purpose line directly under a `### Phase`
+ * heading (`phasePurposeOf`); absent when the phase has none.
  */
 export type PlanPhase = {
   id: string
   title: string
+  purpose?: string
   items: ChecklistItem[]
   deferred?: DeferredItem[]
 } & Partial<PhaseWorkFields>
@@ -72,6 +74,30 @@ export const isOpenCheckboxLine = (line: string): boolean => line.match(CHECKBOX
 export const phaseHeadingPattern = (language: PlanLanguage): RegExp =>
   new RegExp(`^###\\s+${escapeRegExp(PLAN_VOCABULARY[language].phase)}\\s+(\\d+[a-z]?)\\b\\s*[:—–-]?\\s*(.*)$`, 'i')
 
+/** The bold opening of a line (`**Label:**` or `**Label**:`): the label and the text after it. */
+export const BOLD_OPENING = /^\s*\*\*([^*]+?)\s*:?\*\*\s*:?\s*(.*)$/
+
+/** Whether the bold `label` of `line` names the purpose line: by the marker on the line, else by the word of `language`, else by that of any other known language. */
+const namesPurpose = (line: string, label: string, language: PlanLanguage): boolean => {
+  if (markedKeyOf(line) === LINE_KEY.purpose) return true
+  const written = label.trim().toLowerCase()
+  return languagesFrom(language).some((candidate) => PLAN_VOCABULARY[candidate].phasePurpose.toLowerCase() === written)
+}
+
+/**
+ * The sentence of a purpose line, `**Worum es geht:** <sentence>`, the colon inside or outside the bold; null for any
+ * other line and for a purpose line without text after the colon.
+ */
+export const phasePurposeOf = (line: string, language: PlanLanguage): string | null => {
+  const opening = BOLD_OPENING.exec(line)
+  if (!opening || !namesPurpose(line, opening[1], language)) return null
+  const text = terminalSafe(withoutMarker(opening[2])).trim()
+  return text === '' ? null : text
+}
+
+/** The first non-empty line under a heading decides whether a phase has its purpose line; once `decided`, later lines never do. */
+export const decidesPurpose = (decided: boolean, line: string): boolean => !decided && line.trim() !== ''
+
 const tableCells = (line: string): string[] | null => {
   const trimmed = line.trim()
   if (!trimmed.startsWith('|')) return null
@@ -220,6 +246,14 @@ const notePointer = (pointers: Map<PlanPhase, string>, phase: PlanPhase | null,
   if (phase && pointer) pointers.set(phase, pointer)
 }
 
+/** Reads the first non-empty line under a `### Phase` heading as the phase's purpose; later lines and `## N —` sections never are. */
+const notePurpose = (read: Set<PlanPhase>, phase: PlanPhase | null, line: string, language: PlanLanguage): void => {
+  if (!phase || !decidesPurpose(read.has(phase), line)) return
+  read.add(phase)
+  const purpose = phasePurposeOf(line, language)
+  if (purpose !== null) phase.purpose = purpose
+}
+
 const headingOf = (line: string, phaseHeading: RegExp): RegExpMatchArray | null =>
   line.match(phaseHeading) ?? line.match(NUMBERED_SECTION)
 
@@ -244,15 +278,22 @@ export const phaseHeadings = (markdown: string, language: PlanLanguage): PhaseHe
 export const parsePlanPhases = (markdown: string, language: PlanLanguage): PlanPhase[] => {
   const phaseHeading = phaseHeadingPattern(language)
   const pointers = new Map<PlanPhase, string>()
+  const purposeRead = new Set<PlanPhase>()
   const { phases } = markdown.split('\n').reduce<{ phases: PlanPhase[]; open: PlanPhase | null; gate: boolean }>(
     ({ phases, open, gate }, line) => {
       const heading = headingOf(line, phaseHeading)
       if (heading) {
-        const phase = { id: (heading[1] ?? '').toLowerCase(), title: terminalSafe(heading[2] ?? '').trim(), items: [] }
+        const phase: PlanPhase = {
+          id: (heading[1] ?? '').toLowerCase(),
+          title: terminalSafe(heading[2] ?? '').trim(),
+          items: [],
+        }
+        if (!phaseHeading.test(line)) purposeRead.add(phase)
         return { phases: [...phases, phase], open: phase, gate: false }
       }
       if (PHASE_END.test(line)) return { phases, open: null, gate: false }
       const inGate = gate || REVIEW_GATE.test(line)
+      notePurpose(purposeRead, open, line, language)
       if (open) fileLine(open, line, inGate)
       notePointer(pointers, open, line)
       return { phases, open, gate: inGate }

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

@@ -1,5 +1,13 @@
-import { HEAD_LINE, type HeadLine, PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
-import { escapeRegExp } from './markdown'
+import {
+  HEAD_KEY,
+  HEAD_LINE,
+  type HeadLine,
+  languagesFrom,
+  PLAN_VOCABULARY,
+  type PlanLanguage,
+  SECTION_KEY,
+} from '../vocabulary'
+import { escapeRegExp, findSectionHeading, lookedForSection, markedKeyOf, withoutMarker } from './markdown'
 import { parsePlanPhases } from './phases'
 
 /** What a plan holds of its head: all of it and current, none of it, or something that no longer matches the plan. */
@@ -38,12 +46,21 @@ const HEAD_LINES = Object.values(HEAD_LINE)
 
 const labelOf = (language: PlanLanguage, line: HeadLine): string => PLAN_VOCABULARY[language].head[line].toLowerCase()
 
+/** The head line a label names: by the marker on the line, else by the label of `language`, else by that of any other known language. */
+const labelNamed = (text: string, written: string, language: PlanLanguage): HeadLine | undefined => {
+  const marked = markedKeyOf(text)
+  const byMarker = HEAD_LINES.find((each) => HEAD_KEY[each] === marked)
+  if (byMarker) return byMarker
+  return languagesFrom(language)
+    .map((candidate) => HEAD_LINES.find((each) => labelOf(candidate, each) === written))
+    .find((each) => each !== undefined)
+}
+
 const entryOf = (text: string, language: PlanLanguage): { label: HeadLine; text: string } | null => {
   const match = text.match(HEAD_ENTRY)
   if (!match) return null
-  const written = match[1].trim().toLowerCase()
-  const label = HEAD_LINES.find((each) => labelOf(language, each) === written)
-  return label ? { label, text: match[2].trim() } : null
+  const label = labelNamed(text, match[1].trim().toLowerCase(), language)
+  return label ? { label, text: withoutMarker(match[2]) } : null
 }
 
 const phaseOf = (statusText: string | undefined, language: PlanLanguage): HeadPhase | null => {
@@ -59,8 +76,7 @@ const phaseOf = (statusText: string | undefined, language: PlanLanguage): HeadPh
  */
 export const parsePlanHead = (markdown: string, language: PlanLanguage): PlanHead | null => {
   const lines = markdown.split('\n')
-  const heading = new RegExp(`^##\\s+${escapeRegExp(PLAN_VOCABULARY[language].sections.forYou)}\\s*$`)
-  const start = lines.findIndex((text) => heading.test(text))
+  const start = findSectionHeading(markdown, SECTION_KEY.forYou, language)
   if (start === -1) return null
   const rest = lines.slice(start + 1)
   const end = rest.findIndex((text) => SECTION_HEADING.test(text))
@@ -107,8 +123,14 @@ const phaseMismatch = ({ current, total }: HeadPhase, states: readonly PhaseStat
  */
 export const checkPlanHead = (markdown: string, language: PlanLanguage): HeadVerdict => {
   const head = parsePlanHead(markdown, language)
-  const { sections } = PLAN_VOCABULARY[language]
-  if (head === null) return verdict(HEAD_STATUS.missing, null, `no \`## ${sections.forYou}\` section`)
+  if (head === null) {
+    const looked = lookedForSection(SECTION_KEY.forYou, '##', language)
+    return verdict(
+      HEAD_STATUS.missing,
+      null,
+      `no \`## ${PLAN_VOCABULARY[language].sections.forYou}\` section ${looked}`,
+    )
+  }
   if (head.misplaced)
     return verdict(
       HEAD_STATUS.stale,

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

@@ -1,7 +1,9 @@
-import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { LINE_KEY, PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
 import { changedOpenLaneRows, type OpenLaneRow, phaseIdsOfCell } from './lanes'
-import { escapeRegExp, sectionLines } from './markdown'
+import { escapeRegExp, markedKeyOf, sectionLines } from './markdown'
 import {
+  BOLD_OPENING,
+  decidesPurpose,
   deferralTarget,
   endsPhase,
   isCheckboxLine,
@@ -11,6 +13,7 @@ import {
   type PlanPhase,
   parsePlanPhases,
   phaseHeadingPattern,
+  phasePurposeOf,
 } from './phases'
 import { terminalSafe } from './terminal-text'
 
@@ -26,10 +29,21 @@ export type PhaseWithOpenBoxes = PhaseWithoutGate & { openLines: number[] }
 /** A `PhaseWithOpenBoxes` whose tasks are all ticked on the base branch. */
 export type MergedPhaseWithOpenBoxes = PhaseWithOpenBoxes
 
-type PhaseSection = PhaseWithoutGate & { tasks: boolean; gate: boolean; openLines: number[] }
+/** A `### Phase` heading (1-based line) whose section has tasks and no purpose line directly under the heading. */
+export type PhaseWithoutPurpose = PhaseHeading
 
-const noGatePattern = (language: PlanLanguage): RegExp =>
-  new RegExp(`^\\s*\\*\\*${escapeRegExp(PLAN_VOCABULARY[language].noReviewGate)}\\b`, 'i')
+type PhaseSection = PhaseWithoutGate & { tasks: boolean; gate: boolean; purpose: boolean | null; openLines: number[] }
+
+const NO_GATE_WORDS = new RegExp(
+  `^\\s*\\*\\*(?:${Object.values(PLAN_VOCABULARY)
+    .map(({ noReviewGate }) => escapeRegExp(noReviewGate))
+    .join('|')})\\b`,
+  'i',
+)
+
+/** The line by which a phase says it has no review gate on purpose: a bold opening with the words of any known language, or with the marker. */
+const isNoGateLine = (line: string): boolean =>
+  NO_GATE_WORDS.test(line) || (BOLD_OPENING.test(line) && markedKeyOf(line) === LINE_KEY.noReviewGate)
 
 const tickCount = (phase: PlanPhase): number => phase.items.filter((item) => item.done).length
 
@@ -39,10 +53,13 @@ const tasksDone = (phase: PlanPhase): boolean => {
   return tasks.length > 0 && tasks.every((item) => item.done)
 }
 
+const settlePurpose = (section: PhaseSection, line: string, language: PlanLanguage): void => {
+  if (decidesPurpose(section.purpose !== null, line)) section.purpose = phasePurposeOf(line, language) !== null
+}
+
 /** Every `### Phase` section with whether it has tasks and whether it has a gate or says why it has none. */
 const phaseSections = (markdown: string, language: PlanLanguage): PhaseSection[] => {
   const heading = phaseHeadingPattern(language)
-  const noGate = noGatePattern(language)
   const sections: PhaseSection[] = []
   let open: PhaseSection | null = null
   for (const [index, line] of markdown.split('\n').entries()) {
@@ -54,14 +71,16 @@ const phaseSections = (markdown: string, language: PlanLanguage): PhaseSection[]
         title: terminalSafe(match[2]).trim(),
         tasks: false,
         gate: false,
+        purpose: null,
         openLines: [],
       }
       sections.push(open)
     } else if (endsPhase(line)) {
       open = null
     } else if (open) {
+      settlePurpose(open, line, language)
       open.tasks ||= isCheckboxLine(line)
-      open.gate ||= isReviewGateLine(line) || noGate.test(line)
+      open.gate ||= isReviewGateLine(line) || isNoGateLine(line)
       if (isOpenCheckboxLine(line) && deferralTarget(line, open.id) === null) open.openLines.push(index + 1)
     }
   }
@@ -87,6 +106,23 @@ export const newPhasesWithoutReviewGate = (
     .filter(({ id, tasks, gate }) => tasks && !gate && !previousIds.has(id))
     .map(({ line, id, title }) => ({ line, id, title }))
 
+/**
+ * The phases a plan gained against `previousIds` that have checkboxes and no purpose line as the first non-empty line
+ * under the heading (`phasePurposeOf`). Phases the plan already had are not read, like in `newPhasesWithoutReviewGate`.
+ */
+export const newPhasesWithoutPurpose = (
+  markdown: string,
+  language: PlanLanguage,
+  previousIds: ReadonlySet<string>,
+): PhaseWithoutPurpose[] =>
+  phaseSections(markdown, language)
+    .filter(({ id, tasks, purpose }) => tasks && !purpose && !previousIds.has(id))
+    .map(({ line, id, title }) => ({ line, id, title }))
+
+/** Every phase of the plan with tasks and without a purpose line: for a plan read whole, where no phase is older than the change. */
+export const phasesWithoutPurpose = (markdown: string, language: PlanLanguage): PhaseWithoutPurpose[] =>
+  newPhasesWithoutPurpose(markdown, language, new Set())
+
 /** Whether the document has a lanes table (`## Spuren`): a board, not a plan. */
 export const hasLanesTable = (markdown: string, language: PlanLanguage): boolean =>
   sectionLines(markdown, PLAN_VOCABULARY[language].sections.lanes).some((line) => line.startsWith('|'))

package/src/plan-format/progress.ts

@@ -8,6 +8,8 @@ import { type ChecklistItem, type DeferredItem, type PhaseWorkFields, type PlanP
 export type PhaseProgress = {
   id: string
   title: string | null
+  /** The phase's purpose sentence; absent when the plan has none or lacks the phase. */
+  purpose?: string
   done: number
   total: number
   items: ChecklistItem[]
@@ -46,6 +48,7 @@ export const phaseProgress = (phases: readonly PlanPhase[], id: string): PhasePr
     done: items.filter((item) => item.done).length,
     total: items.length,
     items,
+    ...(phase?.purpose ? { purpose: phase.purpose } : {}),
     ...(phase?.deferred ? { deferred: phase.deferred } : {}),
     ...(phase?.work ? phaseWorkFields(phase.work) : {}),
   }

package/src/plan-format/sprint-document.ts

@@ -1,5 +1,5 @@
-import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
-import { allTables, firstTableWithHeader, sectionLines, subsectionLines } from './markdown'
+import { COLUMN_KEY, PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { allTables, columnIndex, firstTableWithHeader, sectionLines, subsectionLines } from './markdown'
 
 const PHASE_ID_IN_CELL = /^(\d+[a-z]?)\b/
 
@@ -57,9 +57,9 @@ export const readSprintDocument = (markdown: string, language: PlanLanguage): Sp
  * first cell of a row starts with the id (`3 — Sync-Engine`); a plan without the table gives an empty map.
  */
 export const readPhaseDependencies = (planMarkdown: string, language: PlanLanguage): Record<string, string> => {
-  const { sections, columns } = PLAN_VOCABULARY[language]
+  const { sections } = PLAN_VOCABULARY[language]
   const { header, rows } = firstTableWithHeader(subsectionLines(planMarkdown, sections.dependencies))
-  const column = header.indexOf(columns.dependsOn)
+  const column = columnIndex(header, COLUMN_KEY.dependsOn, language)
   if (column === -1) return {}
   const entries = rows.flatMap((cells) => {
     const id = PHASE_ID_IN_CELL.exec(cells[0] ?? '')?.[1]

package/src/plan-format/unrecognized-sections.ts

@@ -0,0 +1,21 @@
+import { isSectionKey, sectionOfHeading } from '../vocabulary'
+import { markedKeyOf, SECTION_HEADING } from './markdown'
+
+const isRecognized = (lines: readonly string[], index: number): boolean => {
+  const text = SECTION_HEADING.exec(lines[index])?.[1] ?? ''
+  const marked = markedKeyOf(lines[index + 1] ?? '')
+  return sectionOfHeading(text) !== null || (marked !== null && isSectionKey(marked))
+}
+
+/**
+ * The 1-based line of the first `##` heading of a board or plan when it has such headings and jh reads none of them,
+ * neither by the heading of a known language nor by a marker `<!-- jh: <key> -->` directly under it: a document in a
+ * language without vocabulary and without markers, which every reader would take for empty. Null when the document has
+ * no `##` heading or reads at least one.
+ */
+export const firstUnrecognizedSectionLine = (markdown: string): number | null => {
+  const lines = markdown.split('\n')
+  const headings = lines.flatMap((line, index) => (SECTION_HEADING.test(line) ? [index] : []))
+  if (headings.length === 0 || headings.some((index) => isRecognized(lines, index))) return null
+  return headings[0] + 1
+}

package/src/plan-format/waiting.ts

@@ -1,5 +1,6 @@
-import { type PlanLanguage, WAITING_VOCABULARY } from '../vocabulary'
-import { firstTableWithHeader, sectionLines } from './markdown'
+import { COLUMN_KEY, type PlanLanguage, WAITING_VOCABULARY } from '../vocabulary'
+import { columnIndex, firstTableWithHeader, sectionLines } from './markdown'
+import { isOpenStatus } from './open-status'
 import { terminalSafe } from './terminal-text'
 
 /** `file` for a file or an Artifact that was sent, `question` for a dialog that ended unanswered. */
@@ -35,11 +36,9 @@ const namesOf = (cell: string): string[] =>
     .map((name) => name.replaceAll('`', '').trim())
     .filter(Boolean)
 
-/** 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 === '' || WAITING_VOCABULARY[language].open.some((word) => lower.startsWith(word))
-}
+const OPEN_WORDS = Object.values(WAITING_VOCABULARY).flatMap(({ open }) => open)
+
+const isOpen = (status: string): boolean => isOpenStatus(status, OPEN_WORDS)
 
 /**
  * The rows of the board's waiting section in `language` (`## Wartet auf dich`, `## Waiting for you`), its columns
@@ -47,14 +46,15 @@ const isOpen = (status: string, language: PlanLanguage): boolean => {
  * column, a section without a table and a row without an item give nothing.
  */
 export const readWaitingItems = (board: string, language: PlanLanguage): WaitingItem[] => {
-  const { heading, columns, statusAlso } = WAITING_VOCABULARY[language]
+  const { heading } = WAITING_VOCABULARY[language]
   const { header, rows } = firstTableWithHeader(sectionLines(board, heading))
-  const statusName = [columns.status, ...statusAlso].find((name) => header.includes(name)) ?? columns.status
-  const positions = [columns.since, columns.item, statusName].map((name) => header.indexOf(name))
+  const positions = [COLUMN_KEY.since, COLUMN_KEY.item, COLUMN_KEY.status].map((key) =>
+    columnIndex(header, key, language),
+  )
   if (positions.includes(-1)) return []
   const [since, item, status] = positions
-  const originPosition = header.indexOf(columns.origin)
-  const unblocksPosition = header.indexOf(columns.unblocks)
+  const originPosition = columnIndex(header, COLUMN_KEY.origin, language)
+  const unblocksPosition = columnIndex(header, COLUMN_KEY.unblocks, language)
   return rows.flatMap((cells) => {
     const text = oneLine(cells[item] ?? '')
     const origin = oneLine(cells[originPosition] ?? '')
@@ -65,7 +65,7 @@ export const readWaitingItems = (board: string, language: PlanLanguage): Waiting
           {
             since: oneLine(cells[since] ?? ''),
             item: text,
-            open: isOpen(cells[status] ?? '', language),
+            open: isOpen(cells[status] ?? ''),
             ...(origin === '' ? {} : { origin }),
             ...(unblocks.length === 0 ? {} : { unblocks }),
           },

package/src/plans/board-close.ts

@@ -1,12 +1,19 @@
 import { twoDigits } from '../plan-format/clock'
-import { firstTableRows, sectionLines, sectionStart } from '../plan-format/markdown'
-import { APPOINTMENT_VOCABULARY, PLAN_LANGUAGE, type PlanLanguage, WAITING_VOCABULARY } from '../vocabulary'
+import { columnIndex, firstTableRows, sectionLines, sectionStart } from '../plan-format/markdown'
+import {
+  APPOINTMENT_VOCABULARY,
+  COLUMN_KEY,
+  type ColumnKey,
+  PLAN_LANGUAGE,
+  type PlanLanguage,
+  WAITING_VOCABULARY,
+} from '../vocabulary'
 
 type SectionColumns = {
   heading: string
-  /** The header names of the two cells that identify a row, then the names that count as the status column. */
-  keys: readonly [string, string]
-  status: readonly string[]
+  /** The columns of the two cells that identify a row; the status column is found beside them. */
+  keys: readonly [ColumnKey, ColumnKey]
+  language: PlanLanguage
 }
 
 const DONE_WORD: Record<PlanLanguage, string> = { [PLAN_LANGUAGE.de]: 'erledigt', [PLAN_LANGUAGE.en]: 'done' }
@@ -17,15 +24,17 @@ export const doneStatus = (language: PlanLanguage, now: Date): string =>
 
 const squeezed = (text: string): string => text.replace(/\s+/g, ' ').trim()
 
-const waitingColumns = (language: PlanLanguage): SectionColumns => {
-  const { heading, columns, statusAlso } = WAITING_VOCABULARY[language]
-  return { heading, keys: [columns.since, columns.item], status: [columns.status, ...statusAlso] }
-}
+const waitingColumns = (language: PlanLanguage): SectionColumns => ({
+  heading: WAITING_VOCABULARY[language].heading,
+  keys: [COLUMN_KEY.since, COLUMN_KEY.item],
+  language,
+})
 
-const appointmentColumns = (language: PlanLanguage): SectionColumns => {
-  const { heading, columns, statusAlso } = APPOINTMENT_VOCABULARY[language]
-  return { heading, keys: [columns.when, columns.action], status: [columns.status, ...statusAlso] }
-}
+const appointmentColumns = (language: PlanLanguage): SectionColumns => ({
+  heading: APPOINTMENT_VOCABULARY[language].heading,
+  keys: [COLUMN_KEY.when, COLUMN_KEY.action],
+  language,
+})
 
 /** The line with the status cell (the `index`th between the bars) replaced; the other cells keep their text as written. */
 const withStatus = (line: string, index: number, status: string): string => {
@@ -42,7 +51,7 @@ const withStatus = (line: string, index: number, status: string): string => {
  */
 const closeRow = (
   board: string,
-  { heading, keys: keyNames, status: statusNames }: SectionColumns,
+  { heading, keys: keyColumns, language }: SectionColumns,
   keys: readonly [string, string],
   status: string,
 ): string | null => {
@@ -55,8 +64,8 @@ const closeRow = (
     .slice(1, header.endsWith('|') ? -1 : undefined)
     .split('|')
     .map((cell) => cell.trim())
-  const positions = keyNames.map((name) => names.indexOf(name))
-  const statusAt = names.findIndex((name) => statusNames.includes(name))
+  const positions = keyColumns.map((key) => columnIndex(names, key, language))
+  const statusAt = columnIndex(names, COLUMN_KEY.status, language)
   if (positions.includes(-1) || statusAt === -1) return null
   const row = firstTableRows(lines).find(({ cells }) =>
     positions.every((position, index) => squeezed(cells[position] ?? '') === squeezed(keys[index])),

package/src/plans/board-pick.ts

@@ -20,7 +20,7 @@ const changedAtOf = (root: string, settings: PlansSettings, file: string): numbe
 
 const candidateOf = (root: string, settings: PlansSettings, file: string): BoardCandidate => ({
   path: relative(root, file),
-  lanes: parseSprintLanes(readFileSync(file, 'utf8'), settings.planLanguage).map((lane) => lane.name),
+  lanes: parseSprintLanes(readFileSync(file, 'utf8'), settings.boardLanguage).map((lane) => lane.name),
   changedAt: changedAtOf(root, settings, file),
 })