@taskmark/ui 0.3.0 → 0.3.1

package/lib/taskmark/board-index.ts

@@ -0,0 +1,101 @@
+import fs from "node:fs"
+import path from "node:path"
+
+import { asString, extractFrontmatter } from "@/lib/taskmark/frontmatter"
+import { readActualTimingFromWorkLog } from "@/lib/taskmark/timing"
+
+export type IndexedLeaf = {
+  filePath: string
+  raw: string
+  frontmatter: Record<string, unknown>
+  actualMinutes: number | null
+  actualMs: number | null
+}
+
+export type BoardIndex = {
+  boardPath: string
+  leaves: IndexedLeaf[]
+  leavesByEpic: ReadonlyMap<string, IndexedLeaf[]>
+  leavesByParent: ReadonlyMap<string, IndexedLeaf[]>
+}
+
+function addToMap(
+  map: Map<string, IndexedLeaf[]>,
+  key: string,
+  leaf: IndexedLeaf
+): void {
+  if (!key) return
+  const current = map.get(key)
+  if (current) current.push(leaf)
+  else map.set(key, [leaf])
+}
+
+function itemMarkdownFiles(dir: string): string[] {
+  let entries: fs.Dirent[]
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return []
+  }
+
+  const files: string[] = []
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) continue
+    const filePath = path.join(dir, entry.name)
+    if (entry.isDirectory()) {
+      if (entry.name === "items") {
+        let itemEntries: fs.Dirent[]
+        try {
+          itemEntries = fs.readdirSync(filePath, { withFileTypes: true })
+        } catch {
+          continue
+        }
+        for (const item of itemEntries) {
+          if (
+            item.isFile() &&
+            !item.name.startsWith(".") &&
+            item.name.endsWith(".md")
+          ) {
+            files.push(path.join(filePath, item.name))
+          }
+        }
+      } else {
+        files.push(...itemMarkdownFiles(filePath))
+      }
+    }
+  }
+  return files
+}
+
+/** Read every task/bug once and group leaves for reuse during one render. */
+export function buildBoardIndex(boardPath: string): BoardIndex {
+  const leaves: IndexedLeaf[] = []
+  const leavesByEpic = new Map<string, IndexedLeaf[]>()
+  const leavesByParent = new Map<string, IndexedLeaf[]>()
+
+  for (const filePath of itemMarkdownFiles(path.join(boardPath, "epics"))) {
+    try {
+      const raw = fs.readFileSync(filePath, "utf8")
+      const frontmatter = extractFrontmatter(raw)
+      if (!frontmatter) continue
+      const type = asString(frontmatter.type).toLowerCase()
+      const id = asString(frontmatter.id)
+      if ((type !== "task" && type !== "bug") || !id) continue
+
+      const leaf = {
+        filePath,
+        raw,
+        frontmatter,
+        ...readActualTimingFromWorkLog(raw),
+      }
+      leaves.push(leaf)
+      addToMap(leavesByEpic, asString(frontmatter.epic), leaf)
+      addToMap(leavesByParent, asString(frontmatter.parent), leaf)
+    } catch {
+      // Existing parsers surface malformed files in their own result objects.
+    }
+  }
+
+  leaves.sort((a, b) => a.filePath.localeCompare(b.filePath))
+  return { boardPath, leaves, leavesByEpic, leavesByParent }
+}

package/lib/taskmark/build-snapshot.ts

@@ -2,6 +2,7 @@ import fs from "node:fs"
 import path from "node:path"
 
 import { loadWorkItemDetailSync } from "@/lib/taskmark/detail-load"
+import { buildBoardIndex } from "@/lib/taskmark/board-index"
 import type { WorkItemRef } from "@/lib/taskmark/detail-types"
 import { parseEpicsForProject } from "@/lib/taskmark/parse-epics"
 import { parseWorkItemsForEpic, parseWorkItemsViewForProject } from "@/lib/taskmark/parse-flat-lists"
@@ -16,6 +17,7 @@ import {
   storyKey,
 } from "@/lib/taskmark/snapshot-types"
 import type { DiscoveredProject } from "@/lib/taskmark/types"
+import { loadBoardChangelogMarkdown } from "@/lib/taskmark/load-changelog"
 import { loadWorkspace } from "@/lib/taskmark/workspace"
 import { asString, extractFrontmatter } from "@/lib/taskmark/frontmatter"
 
@@ -127,19 +129,26 @@ export function buildBoardSnapshot(
   projects: DiscoveredProject[],
   active: DiscoveredProject
 ): BoardSnapshot {
-  const epics = parseEpicsForProject(active)
+  const boardIndex = buildBoardIndex(active.boardPath)
+  const epics = parseEpicsForProject(active, boardIndex)
   const workItemsByEpic: BoardSnapshot["workItemsByEpic"] = {}
   const itemsByStory: BoardSnapshot["itemsByStory"] = {}
 
   for (const epic of epics.epics) {
-    const epicList = parseWorkItemsForEpic(active, epic.id, epic.title)
+    const epicList = parseWorkItemsForEpic(
+      active,
+      epic.id,
+      epic.title,
+      boardIndex
+    )
     workItemsByEpic[epic.id] = epicList
     for (const row of epicList.rows) {
       if (row.kind !== "story") continue
       itemsByStory[storyKey(epic.id, row.id)] = parseItemsForStory(
         active,
         epic.id,
-        row.id
+        row.id,
+        boardIndex
       )
     }
   }
@@ -152,7 +161,12 @@ export function buildBoardSnapshot(
     refsById[ref.id] = ref
     const hint =
       ref.kind === "epic" ? "epic" : ref.kind === "story" ? "story" : "item"
-    const detail = loadWorkItemDetailSync(projects, ref.filePath, hint)
+    const detail = loadWorkItemDetailSync(
+      projects,
+      ref.filePath,
+      hint,
+      boardIndex
+    )
     if (detail.ok) {
       detailsByPath[ref.filePath] = detail.detail
     }
@@ -166,19 +180,26 @@ export function buildBoardSnapshot(
     workItems: false,
   } as const
 
+  const metricLeaves = collectMetricLeaves(active, boardIndex)
+
   return {
     version: 1,
     builtAt: new Date().toISOString(),
     project: active,
     projects,
     epics,
-    workItemsView: parseWorkItemsViewForProject(active),
+    workItemsView: parseWorkItemsViewForProject(active, boardIndex),
     workItemsByEpic,
     itemsByStory,
-    statusMetrics: computeProjectStatusMetrics(active),
+    statusMetrics: computeProjectStatusMetrics(
+      active,
+      boardIndex,
+      metricLeaves
+    ),
     countableCompletions: collectCompletedLeafPointSamples(
-      collectMetricLeaves(active)
+      metricLeaves
     ),
+    changelogMarkdown: loadBoardChangelogMarkdown(active.boardPath),
     hideCompletedDefaults: { ...hideCompletedDefaults },
     detailsByPath,
     refsById,

package/lib/taskmark/derive-parents.test.ts

@@ -0,0 +1,23 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+
+import { deriveParentStatus } from "./derive-parents"
+
+test("rolls all shelved descendants up to shelved", () => {
+  assert.equal(deriveParentStatus(["shelved", "shelved"]), "shelved")
+})
+
+test("rolls a terminal mix containing done up to done", () => {
+  assert.equal(
+    deriveParentStatus(["shelved", "cancelled", "done"]),
+    "done"
+  )
+})
+
+test("rolls shelved and cancelled without done up to shelved", () => {
+  assert.equal(deriveParentStatus(["shelved", "cancelled"]), "shelved")
+})
+
+test("keeps a parent in progress while any descendant is open", () => {
+  assert.equal(deriveParentStatus(["shelved", "backlog"]), "in_progress")
+})

package/lib/taskmark/derive-parents.ts

@@ -0,0 +1,323 @@
+import {
+  asNumberOrNull,
+  asString,
+} from "@/lib/taskmark/frontmatter"
+import {
+  buildBoardIndex,
+  type BoardIndex,
+  type IndexedLeaf,
+} from "@/lib/taskmark/board-index"
+import type { ContributorIdentity } from "@/lib/taskmark/identity"
+import { asContributorList } from "@/lib/taskmark/identity"
+import { parseWorkItemDetailFromRaw } from "@/lib/taskmark/parse-detail"
+import type {
+  CommitRow,
+  PromptFeedbackRow,
+  RowWorkItemRef,
+  WorkLogRow,
+} from "@/lib/taskmark/detail-types"
+
+export const STATIC_SIZE_POINTS = {
+  XS: 1,
+  S: 3,
+  M: 5,
+  L: 8,
+  XL: 13,
+  XXL: 21,
+} as const
+
+type ParentKind = "epic" | "story"
+
+type LeafRecord = {
+  id: string
+  title: string
+  parent: string
+  epic: string
+  status: string
+  points: number
+  reporters: ContributorIdentity[]
+  resolvers: ContributorIdentity[]
+  updated: string
+  startedAt: string
+  completedAt: string
+  actualMinutes: number | null
+  actualMs: number | null
+  promptFeedback: PromptFeedbackRow[]
+  commits: CommitRow[]
+  workLog: WorkLogRow[]
+}
+
+export type ParentRollup = {
+  status: string
+  size: string
+  points: number
+  actualMinutes: number
+  actualMs: number
+  resolvers: ContributorIdentity[]
+  updated: string
+  startedAt: string
+  completedAt: string
+  promptFeedback: PromptFeedbackRow[]
+  commits: CommitRow[]
+  workLog: WorkLogRow[]
+  leafCount: number
+  doneLeafCount: number
+}
+
+function leafPoints(frontmatter: Record<string, unknown>): number {
+  const explicit = asNumberOrNull(frontmatter.points)
+  if (explicit != null) return Math.max(0, explicit)
+  const size = asString(frontmatter.size).trim().toUpperCase()
+  return STATIC_SIZE_POINTS[size as keyof typeof STATIC_SIZE_POINTS] ?? 0
+}
+
+function readLeaf(indexed: IndexedLeaf, includeDetails: boolean): LeafRecord | null {
+  try {
+    const { filePath, raw, frontmatter } = indexed
+    const type = asString(frontmatter.type).toLowerCase()
+    if (type !== "task" && type !== "bug") return null
+    const id = asString(frontmatter.id)
+    if (!id) return null
+    const timing = {
+      actualMinutes: indexed.actualMinutes,
+      actualMs: indexed.actualMs,
+    }
+    const parsed = includeDetails
+      ? parseWorkItemDetailFromRaw(raw, filePath, "item")
+      : null
+    const itemDetail =
+      parsed?.ok &&
+      parsed.detail.type !== "epic" &&
+      parsed.detail.type !== "story"
+        ? parsed.detail
+        : null
+    return {
+      id,
+      title: asString(frontmatter.title, id),
+      parent: asString(frontmatter.parent),
+      epic: asString(frontmatter.epic),
+      status: asString(frontmatter.status, "backlog"),
+      points: leafPoints(frontmatter),
+      reporters: asContributorList(frontmatter.reporters),
+      resolvers: asContributorList(frontmatter.resolvers),
+      updated: asString(frontmatter.updated),
+      startedAt: asString(frontmatter.started_at),
+      completedAt: asString(frontmatter.completed_at),
+      ...timing,
+      promptFeedback: itemDetail?.promptFeedback ?? [],
+      commits: itemDetail?.commits ?? [],
+      workLog: itemDetail?.workLog ?? [],
+    }
+  } catch {
+    return null
+  }
+}
+
+function leavesForParent(
+  parentId: string,
+  kind: ParentKind,
+  index: BoardIndex,
+  includeDetails: boolean
+): LeafRecord[] {
+  const indexed =
+    kind === "story"
+      ? index.leavesByParent.get(parentId) ?? []
+      : [
+          ...(index.leavesByEpic.get(parentId) ?? []),
+          ...(index.leavesByParent.get(parentId) ?? []),
+        ].filter(
+          (leaf, position, all) =>
+            all.findIndex((candidate) => candidate.filePath === leaf.filePath) ===
+            position
+        )
+  return indexed
+    .map((leaf) => readLeaf(leaf, includeDetails))
+    .filter((leaf): leaf is LeafRecord => leaf != null)
+}
+
+export function deriveParentStatus(statusesInput: readonly string[]): string {
+  if (statusesInput.length === 0) return "backlog"
+  const statuses = statusesInput.map((status) => status.trim().toLowerCase())
+  const terminal = statuses.every(
+    (status) =>
+      status === "done" || status === "shelved" || status === "cancelled"
+  )
+  if (terminal && statuses.some((status) => status === "done")) return "done"
+  if (terminal && statuses.some((status) => status === "shelved")) {
+    return "shelved"
+  }
+  if (terminal) return "cancelled"
+  if (statuses.every((status) => status === "backlog")) return "backlog"
+  return "in_progress"
+}
+
+function parentSize(points: number, leafCount: number): string {
+  if (leafCount === 0) return "—"
+  if (points <= 1) return "XS"
+  if (points <= 3) return "S"
+  if (points <= 5) return "M"
+  if (points <= 8) return "L"
+  if (points <= 13) return "XL"
+  return "XXL"
+}
+
+function dateValue(value: string): number | null {
+  if (!value.trim()) return null
+  const parsed = Date.parse(value)
+  return Number.isFinite(parsed) ? parsed : null
+}
+
+function selectDate(
+  values: readonly string[],
+  direction: "min" | "max"
+): string {
+  return values
+    .map((value) => ({ value, time: dateValue(value) }))
+    .filter((entry): entry is { value: string; time: number } => entry.time != null)
+    .sort((a, b) => direction === "min" ? a.time - b.time : b.time - a.time)[0]
+    ?.value ?? ""
+}
+
+function identityKey(identity: ContributorIdentity): string {
+  return identity.email.trim().toLowerCase() ||
+    identity.name.trim().toLowerCase()
+}
+
+function uniqueResolvers(leaves: readonly LeafRecord[]): ContributorIdentity[] {
+  const identities = new Map<string, ContributorIdentity>()
+  for (const leaf of leaves) {
+    for (const identity of leaf.resolvers) {
+      const key = identityKey(identity)
+      if (key && !identities.has(key)) identities.set(key, identity)
+    }
+  }
+  return [...identities.values()]
+}
+
+/**
+ * Collapse rows that leaves repeat verbatim into one row carrying every
+ * contributing work item.
+ */
+function groupRowsByContent<T extends object>(
+  leaves: readonly LeafRecord[],
+  rowsOf: (leaf: LeafRecord) => readonly T[],
+  contentKey: (row: T) => string,
+  merge?: (existing: T, incoming: T) => T
+): (T & { workItems: RowWorkItemRef[] })[] {
+  const grouped = new Map<string, T & { workItems: RowWorkItemRef[] }>()
+
+  for (const leaf of leaves) {
+    for (const row of rowsOf(leaf)) {
+      const key = contentKey(row)
+      const existing = grouped.get(key)
+      const workItem = { id: leaf.id, title: leaf.title }
+      if (existing) {
+        if (merge) Object.assign(existing, merge(existing, row))
+        if (!existing.workItems.some((item) => item.id === leaf.id)) {
+          existing.workItems.push(workItem)
+        }
+        continue
+      }
+      grouped.set(key, {
+        ...row,
+        workItems: [workItem],
+      })
+    }
+  }
+
+  return [...grouped.values()]
+}
+
+function normalizeLogText(value: string): string {
+  return value.trim().replace(/\s+/g, " ").toLowerCase()
+}
+
+function workLogContentKey(row: WorkLogRow): string {
+  const actor = normalizeLogText(row.actor)
+  const summary = normalizeLogText(row.summary)
+  if (!summary) {
+    return [actor, row.started, row.ended, ""].join("\u0000")
+  }
+  return [actor, summary].join("\u0000")
+}
+
+function mergeWorkLogSpan(existing: WorkLogRow, incoming: WorkLogRow): WorkLogRow {
+  const started = selectDate([existing.started, incoming.started], "min")
+  const ended = selectDate([existing.ended, incoming.ended], "max")
+  return { ...existing, started, ended }
+}
+
+function sortByDate<T>(rows: T[], date: (row: T) => string): T[] {
+  return rows.sort((a, b) => {
+    const left = dateValue(date(a)) ?? Number.MAX_SAFE_INTEGER
+    const right = dateValue(date(b)) ?? Number.MAX_SAFE_INTEGER
+    return left - right
+  })
+}
+
+/** Derive every mutable parent field exclusively from task/bug leaves. */
+export function deriveParentRollup(
+  boardPath: string,
+  parentId: string,
+  kind: ParentKind,
+  index: BoardIndex = buildBoardIndex(boardPath),
+  includeDetails = false
+): ParentRollup {
+  const leaves = leavesForParent(parentId, kind, index, includeDetails)
+  const status = deriveParentStatus(leaves.map((leaf) => leaf.status))
+  const points = leaves.reduce((sum, leaf) => sum + leaf.points, 0)
+  const actualMs = leaves.reduce(
+    (sum, leaf) =>
+      sum + (leaf.actualMs ?? (leaf.actualMinutes ?? 0) * 60_000),
+    0
+  )
+  const completedLeaves = leaves.filter(
+    (leaf) =>
+      leaf.status.trim().toLowerCase() === "done" ||
+      leaf.status.trim().toLowerCase() === "shelved" ||
+      leaf.status.trim().toLowerCase() === "cancelled"
+  )
+
+  return {
+    status,
+    size: parentSize(points, leaves.length),
+    points,
+    actualMinutes: Math.floor(actualMs / 60_000),
+    actualMs,
+    resolvers: uniqueResolvers(leaves),
+    updated: selectDate(leaves.map((leaf) => leaf.updated), "max"),
+    startedAt: selectDate(leaves.map((leaf) => leaf.startedAt), "min"),
+    completedAt:
+      completedLeaves.length === leaves.length
+        ? selectDate(completedLeaves.map((leaf) => leaf.completedAt), "max")
+        : "",
+    promptFeedback: sortByDate(
+      groupRowsByContent(
+        leaves,
+        (leaf) => leaf.promptFeedback,
+        (row) => [row.when, row.kind, row.author, row.summary].join("\u0000")
+      ),
+      (row) => row.when
+    ).map((row, position) => ({ ...row, index: String(position + 1) })),
+    commits: sortByDate(
+      groupRowsByContent(
+        leaves,
+        (leaf) => leaf.commits,
+        (row) =>
+          [row.sha, row.repo, row.date, row.author, row.message].join("\u0000")
+      ),
+      (row) => row.date
+    ),
+    workLog: sortByDate(
+      groupRowsByContent(
+        leaves,
+        (leaf) => leaf.workLog,
+        workLogContentKey,
+        mergeWorkLogSpan
+      ),
+      (row) => row.started
+    ).map((row, position) => ({ ...row, session: String(position + 1) })),
+    leafCount: leaves.length,
+    doneLeafCount: completedLeaves.length,
+  }
+}

package/lib/taskmark/detail-load.ts

@@ -18,6 +18,11 @@ import {
   findWorkItemOnBoard,
 } from "@/lib/taskmark/resolve-work-item"
 import type { WorkItemRef } from "@/lib/taskmark/detail-types"
+import { deriveParentRollup } from "@/lib/taskmark/derive-parents"
+import {
+  buildBoardIndex,
+  type BoardIndex,
+} from "@/lib/taskmark/board-index"
 
 function isPathInside(parent: string, child: string): boolean {
   const rel = path.relative(parent, child)
@@ -37,11 +42,12 @@ export function findProjectForFile(
 
 export function attachChildren(
   detail: WorkItemDetail,
-  project: DiscoveredProject
+  project: DiscoveredProject,
+  index?: BoardIndex
 ): WorkItemDetail {
   if (detail.type === "epic") {
     const children: DetailChildItem[] = []
-    const stories = parseStoriesForEpic(project, detail.id)
+    const stories = parseStoriesForEpic(project, detail.id, index)
     for (const story of stories.stories) {
       children.push({
         id: story.id,
@@ -52,7 +58,7 @@ export function attachChildren(
         filePath: story.filePath,
       })
     }
-    const epicItems = parseItemsForEpic(project, detail.id)
+    const epicItems = parseItemsForEpic(project, detail.id, index)
     for (const item of epicItems.items) {
       children.push({
         id: item.id,
@@ -70,7 +76,7 @@ export function attachChildren(
     const epicId = detail.epic || detail.parent
     if (!epicId) return detail
     const children: DetailChildItem[] = []
-    const items = parseItemsForStory(project, epicId, detail.id)
+    const items = parseItemsForStory(project, epicId, detail.id, index)
     for (const item of items.items) {
       children.push({
         id: item.id,
@@ -87,10 +93,41 @@ export function attachChildren(
   return detail
 }
 
+function attachDerivedParentFields(
+  detail: WorkItemDetail,
+  project: DiscoveredProject,
+  index?: BoardIndex
+): WorkItemDetail {
+  if (detail.type !== "epic" && detail.type !== "story") return detail
+  const derived = deriveParentRollup(
+    project.boardPath,
+    detail.id,
+    detail.type,
+    index,
+    true
+  )
+  return {
+    ...detail,
+    status: derived.status,
+    size: derived.size,
+    points: derived.points,
+    actualMinutes: derived.actualMinutes,
+    actualMs: derived.actualMs,
+    resolvers: derived.resolvers,
+    updated: derived.updated,
+    startedAt: derived.startedAt,
+    completedAt: derived.completedAt,
+    promptFeedback: derived.promptFeedback,
+    commits: derived.commits,
+    workLog: derived.workLog,
+  }
+}
+
 export function loadWorkItemDetailSync(
   projects: DiscoveredProject[],
   filePath: string,
-  hint?: "epic" | "story" | "item"
+  hint?: "epic" | "story" | "item",
+  index?: BoardIndex
 ): WorkItemDetailResult {
   if (!filePath || typeof filePath !== "string") {
     return { ok: false, filePath: filePath ?? "", message: "Missing file path" }
@@ -123,8 +160,13 @@ export function loadWorkItemDetailSync(
 
   const result = parseWorkItemDetailFromRaw(raw, resolved, hint)
   if (!result.ok) return result
+  if (result.detail.type !== "epic" && result.detail.type !== "story") {
+    return result
+  }
 
-  return { ok: true, detail: attachChildren(result.detail, project) }
+  const boardIndex = index ?? buildBoardIndex(project.boardPath)
+  const derived = attachDerivedParentFields(result.detail, project, boardIndex)
+  return { ok: true, detail: attachChildren(derived, project, boardIndex) }
 }
 
 export function resolveWorkItemByIdSync(
@@ -175,6 +217,12 @@ export function resolveWorkItemByIdSync(
     }
   }
 
-  const { boardPath: _b, projectId: _p, ...ref } = resolved
+  const ref: WorkItemRef = {
+    kind: resolved.kind,
+    id: resolved.id,
+    title: resolved.title,
+    filePath: resolved.filePath,
+    ...(resolved.itemType ? { itemType: resolved.itemType } : {}),
+  }
   return { ok: true, ref }
 }

package/lib/taskmark/detail-types.ts

@@ -13,12 +13,19 @@ export type MarkdownTable = {
   rows: string[][]
 }
 
+/** Descendant task/bug that contributed a row to a derived parent view. */
+export type RowWorkItemRef = {
+  id: string
+  title: string
+}
+
 export type PromptFeedbackRow = {
   index: string
   when: string
   kind: string
   author: string
   summary: string
+  workItems?: RowWorkItemRef[]
 }
 
 export type CommitRow = {
@@ -27,6 +34,7 @@ export type CommitRow = {
   date: string
   author: string
   message: string
+  workItems?: RowWorkItemRef[]
 }
 
 export type WorkLogRow = {
@@ -35,6 +43,7 @@ export type WorkLogRow = {
   started: string
   ended: string
   summary: string
+  workItems?: RowWorkItemRef[]
 }
 
 export type WorkItemMeta = {
@@ -45,11 +54,9 @@ export type WorkItemMeta = {
   priority: string
   size: string
   points: number | null
-  estimateMinutes: number | null
   actualMinutes: number | null
   actualMs: number | null
   tags: string[]
-  owner: string
   reporters: ContributorIdentity[]
   resolvers: ContributorIdentity[]
   blocked: boolean
@@ -82,6 +89,7 @@ export type EpicDetail = WorkItemMeta & {
   storiesMarkdown: string
   /** Stories + epic-direct tasks/bugs under this epic. */
   children: DetailChildItem[]
+  promptFeedback: PromptFeedbackRow[]
   commits: CommitRow[]
   workLog: WorkLogRow[]
 }