@nickmeriano/task 0.7.1 → 0.9.0

package/src/check.ts

@@ -0,0 +1,497 @@
+/**
+ * `task check` — lint the board files.
+ *
+ * A database enforced its constraints at write time; a text store has two
+ * extra write paths no CLI code ever sees — git merges and hand-edits — so
+ * validation has to be a lint you can run. This strictly parses every ticket
+ * comment and goal file on every board at or below the check root (the same
+ * walk `task serve` does) and reports what would degrade or throw at read
+ * time: files that don't parse, invalid timestamps, dangling `blocked_by`
+ * references (one branch deleted a ticket another branch linked to), `goal:`
+ * refs naming a goal that doesn't exist, tickets duplicated between the board
+ * and the archive, unknown frontmatter keys, and formatting drift from the
+ * canonical serialization. Retired pre-0.8 spellings (`milestone:`,
+ * `claimPrefix`) are refused by the parsers with the rename in the error —
+ * this lint just surfaces those messages; there is no migration machinery.
+ *
+ * The mechanical repairs — pruning dangling or self references, deduping and
+ * sorting `blocked_by`, rewriting a file into canonical form — are applied by
+ * `--fix`. Anything that needs a decision (a status that isn't a status, a
+ * missing title) is reported and left alone. Cheap enough for pre-commit and
+ * CI, which is where merge-introduced drift gets caught.
+ */
+
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import {
+  ARCHIVE_DIR,
+  ASKS_DIR,
+  COMMENTS_DIR,
+  GOALS_ARCHIVE_DIR,
+  GOALS_DIR,
+  TICKETS_DIR,
+  TICKET_FILE,
+} from "./file-store.ts"
+import {
+  ASK_FIELDS,
+  COMMENT_FIELDS,
+  TicketParseError,
+  frontmatterKeys,
+  isGoalSlug,
+  parseAsk,
+  parseComment,
+  parseGoal,
+  parseTicket,
+  serializeAsk,
+  serializeComment,
+  serializeGoal,
+  serializeTicket,
+  type TicketDoc,
+} from "./ticket-doc.ts"
+import {
+  CONFIG_FILE,
+  TASK_DIR,
+  boardConfig,
+  findBoards,
+  findRoot,
+  findScopeRoot,
+  type BoardRef,
+} from "./store.ts"
+import { claimNamespace } from "./claim.ts"
+import { isTicketKey } from "./id.ts"
+import type { ProjectConfig } from "./types.ts"
+
+export interface CheckIssue {
+  /** Board id relative to the check root — "." for the root board. */
+  board: string
+  /** File (or directory) the problem is in, relative to the check root. */
+  file: string
+  message: string
+  /** `task check --fix` repairs this mechanically. */
+  fixable: boolean
+}
+
+export interface CheckResult {
+  boards: number
+  /** Ticket and comment files inspected. */
+  files: number
+  issues: CheckIssue[]
+  /** Files rewritten, relative to the check root. Empty unless fixing. */
+  fixed: string[]
+}
+
+/** The boards `task check` covers from `cwd` — the same set `task serve` has. */
+export function checkRoot(cwd: string): string {
+  return findRoot(cwd) ?? cwd
+}
+
+interface TicketEntry {
+  key: string
+  /** Path relative to the check root, for reporting. */
+  file: string
+  /** Absolute path, for fixing. */
+  absolute: string
+  archived: boolean
+  text: string
+  doc: TicketDoc | null
+}
+
+function posixJoin(...parts: string[]): string {
+  return parts.filter((p) => p !== "" && p !== ".").join("/")
+}
+
+/** Strip the `where: ` prefix strict parsers put in messages — we report the file. */
+function reason(error: unknown, where: string): string {
+  const message = error instanceof Error ? error.message : String(error)
+  return message.startsWith(`${where}: `) ? message.slice(where.length + 2) : message
+}
+
+function isValidTimestamp(value: string): boolean {
+  return value !== "" && !Number.isNaN(Date.parse(value))
+}
+
+export function checkBoards(root: string, fix: boolean): CheckResult {
+  const boards = findBoards(root)
+  // The repo's root board is the reference for everything repo-scoped: the
+  // `boards` key may live only there, and every board's claim namespace must
+  // match its. It can sit *above* the check root (check run inside a nested
+  // board), so it's resolved by walking up, not taken from the walk down.
+  const scopeRoot = findScopeRoot(root)
+  // Normalized through claimNamespace so "claude/task" and "claude/task/"
+  // compare equal; an unreadable or malformed root config means "no
+  // reference" (the root board's own check reports the problem).
+  let rootBranchPrefix: string | null = null
+  try {
+    rootBranchPrefix = claimNamespace(boardConfig(scopeRoot))
+  } catch {
+    rootBranchPrefix = null
+  }
+  const issues: CheckIssue[] = []
+  const fixed: string[] = []
+  let files = 0
+
+  for (const board of boards) {
+    files += checkBoard(board, scopeRoot, rootBranchPrefix, fix, issues, fixed)
+  }
+  return { boards: boards.length, files, issues, fixed }
+}
+
+/**
+ * Config lints (TAS-27): a `boards` list on a non-root board (root-only by
+ * design, so vendored boards can't opt into a repo's automation), a malformed
+ * one, an unusable branch prefix, a branch prefix that disagrees with the
+ * root board's (workflows match claim branches by pattern — one repo, one
+ * namespace), and a leftover pre-0.8 `claimPrefix` key. The retired spelling
+ * is not migrated anymore (TAS-41: no compat) — with no `claims.branchPrefix`
+ * beside it, `claimNamespace` refuses by name and that error surfaces here;
+ * with one, the stray key is inert and gets its own line.
+ */
+function checkConfig(
+  board: BoardRef,
+  scopeRoot: string,
+  rootBranchPrefix: string | null,
+  push: (file: string, message: string, fixable?: boolean) => void,
+): ProjectConfig | null {
+  const absolute = join(board.root, TASK_DIR, CONFIG_FILE)
+  const file = posixJoin(board.id, TASK_DIR, CONFIG_FILE)
+  let raw: Record<string, unknown>
+  try {
+    raw = JSON.parse(readFileSync(absolute, "utf8")) as Record<string, unknown>
+  } catch (error) {
+    push(file, reason(error, ""))
+    return null
+  }
+  const config = raw as unknown as ProjectConfig
+
+  if (raw.claimPrefix !== undefined && config.claims?.branchPrefix !== undefined) {
+    push(
+      file,
+      "`claimPrefix` is the pre-0.8 spelling and is no longer read — `claims.branchPrefix` wins; delete the leftover key",
+    )
+  }
+
+  if (raw.boards !== undefined) {
+    if (board.root !== scopeRoot) {
+      push(
+        file,
+        '"boards" is root-only — automation reads it from the repo\'s root board; remove it here',
+      )
+    } else if (
+      !Array.isArray(raw.boards) ||
+      raw.boards.length === 0 ||
+      raw.boards.some((b) => typeof b !== "string")
+    ) {
+      push(file, '"boards" must be a non-empty array of board prefixes, e.g. ["NIC", "TAS"]')
+    }
+  }
+
+  let branchPrefix: string | null = null
+  try {
+    branchPrefix = claimNamespace(config)
+  } catch (error) {
+    push(file, reason(error, ""))
+  }
+  if (
+    branchPrefix !== null &&
+    rootBranchPrefix !== null &&
+    board.root !== scopeRoot &&
+    branchPrefix !== rootBranchPrefix
+  ) {
+    push(
+      file,
+      `claims.branchPrefix ${JSON.stringify(branchPrefix)} disagrees with the root board's ${JSON.stringify(rootBranchPrefix)} — workflows match claim branches by pattern, keep one namespace per repo`,
+    )
+  }
+
+  return config
+}
+
+function checkBoard(
+  board: BoardRef,
+  scopeRoot: string,
+  rootBranchPrefix: string | null,
+  fix: boolean,
+  issues: CheckIssue[],
+  fixed: string[],
+): number {
+  const taskDir = join(board.root, TASK_DIR)
+  const relTaskDir = posixJoin(board.id, TASK_DIR)
+  const push = (file: string, message: string, fixable = false) =>
+    issues.push({ board: board.id, file, message, fixable })
+
+  const config = checkConfig(board, scopeRoot, rootBranchPrefix, push)
+  const prefix = config?.prefix ?? "TASK"
+  const displayId = (k: string) => `${prefix}-${k}`
+
+  // ── Collect every ticket, live and archived ────────────────────────────────
+  const tickets: TicketEntry[] = []
+  let files = 0
+  for (const [dir, archived] of [
+    [TICKETS_DIR, false],
+    [ARCHIVE_DIR, true],
+  ] as const) {
+    const home = join(taskDir, dir)
+    if (!existsSync(home)) continue
+    for (const entry of readdirSync(home, { withFileTypes: true })) {
+      if (entry.name.startsWith(".")) continue
+      const relEntry = posixJoin(relTaskDir, dir, entry.name)
+      // A purely numeric directory is a pre-TAS-42 ticket — the old
+      // sequential-id format, which nothing reads anymore. The likely way one
+      // appears post-migration is merging a branch cut before the cutover;
+      // the fix is mechanical and named here.
+      if (entry.isDirectory() && /^\d+$/.test(entry.name)) {
+        push(
+          relEntry,
+          "numeric ticket directory — the pre-TAS-42 sequential-id format, which is no longer read; migrate it with `node tools/migrate-ids/migrate.mjs --ticket <board-dir> " +
+            entry.name +
+            "`",
+        )
+        continue
+      }
+      if (!entry.isDirectory() || !isTicketKey(entry.name)) {
+        push(relEntry, "unexpected entry — ticket directories are named by their key (e.g. x7k4m)")
+        continue
+      }
+      const absolute = join(home, entry.name, TICKET_FILE)
+      const file = posixJoin(relEntry, TICKET_FILE)
+      if (!existsSync(absolute)) {
+        push(file, "ticket directory without a ticket.md")
+        continue
+      }
+      files++
+      const text = readFileSync(absolute, "utf8")
+      let doc: TicketDoc | null = null
+      try {
+        doc = parseTicket(text, file)
+      } catch (error) {
+        if (!(error instanceof TicketParseError)) throw error
+        push(file, reason(error, file))
+      }
+      tickets.push({ key: entry.name, file, absolute, archived, text, doc })
+    }
+  }
+
+  // A ticket present in both tickets/ and archive/ is a merge artifact: one
+  // branch archived it while another kept editing it. Which copy wins is a
+  // human call, so it's reported, never auto-fixed. (This doubles as the
+  // duplicate-key lint: within either directory git itself makes duplicates
+  // impossible, so board-and-archive is the only place one can exist.)
+  const live = new Set(tickets.filter((t) => !t.archived).map((t) => t.key))
+  const valid = new Set(tickets.map((t) => t.key))
+  for (const ticket of tickets) {
+    if (ticket.archived && live.has(ticket.key)) {
+      push(
+        ticket.file,
+        `${displayId(ticket.key)} also exists in ${TICKETS_DIR}/ — a merge kept both copies; delete one`,
+      )
+    }
+  }
+
+  // ── Goals ──────────────────────────────────────────────────────────────────
+  // Same strict pass as tickets: parse, timestamps, unknown keys, canonical
+  // form. `goalSlugs` (live and archived together) is what ticket refs are
+  // checked against below — an archived goal still resolves.
+  const goalSlugs = new Set<string>()
+  const liveGoalSlugs = new Set<string>()
+  for (const [dir, goalArchived] of [
+    [GOALS_DIR, false],
+    [`${GOALS_DIR}/${GOALS_ARCHIVE_DIR}`, true],
+  ] as const) {
+    const home = join(taskDir, dir)
+    if (!existsSync(home)) continue
+    for (const entry of readdirSync(home, { withFileTypes: true })) {
+      if (entry.name.startsWith(".")) continue
+      if (entry.isDirectory() && !goalArchived && entry.name === GOALS_ARCHIVE_DIR) continue
+      const file = posixJoin(relTaskDir, dir, entry.name)
+      if (entry.isDirectory() || !entry.name.endsWith(".md")) {
+        push(file, "unexpected entry — goals/ holds one <slug>.md per goal")
+        continue
+      }
+      files++
+      const slug = entry.name.slice(0, -3)
+      const text = readFileSync(join(home, entry.name), "utf8")
+      let doc
+      try {
+        doc = parseGoal(text, file)
+      } catch (error) {
+        if (!(error instanceof TicketParseError)) throw error
+        push(file, reason(error, file))
+        continue
+      }
+      if (goalArchived && liveGoalSlugs.has(slug)) {
+        push(file, `goal "${slug}" also exists in ${GOALS_DIR}/ — a merge kept both copies; delete one`)
+      }
+      goalSlugs.add(slug)
+      if (!goalArchived) liveGoalSlugs.add(slug)
+      if (!isGoalSlug(slug)) {
+        push(file, `"${slug}" is not a valid goal slug — lowercase letters, digits and dashes`)
+      }
+      for (const [key, at] of [
+        [doc.createdAt, "created"],
+        [doc.updatedAt, "updated"],
+      ] as const) {
+        if (!isValidTimestamp(key)) push(file, `${at} is not a valid timestamp`)
+      }
+      for (const [key] of doc.extras ?? []) {
+        push(file, `unknown frontmatter key "${key}" — preserved on rewrite, but nothing reads it`)
+      }
+      const canonical = serializeGoal(doc)
+      if (canonical !== text) {
+        push(file, "not in canonical form — `task check --fix` rewrites it", true)
+        if (fix) {
+          writeFileSync(join(home, entry.name), canonical)
+          fixed.push(file)
+        }
+      }
+    }
+  }
+
+  // ── Per-ticket content checks ──────────────────────────────────────────────
+  for (const ticket of tickets) {
+    const { doc, file, key } = ticket
+    if (!doc) continue
+
+    for (const [key, at] of [
+      [doc.createdAt, "created"],
+      [doc.updatedAt, "updated"],
+    ] as const) {
+      if (!isValidTimestamp(key)) push(file, `${at} is not a valid timestamp`)
+    }
+    for (const [key] of doc.extras ?? []) {
+      push(file, `unknown frontmatter key "${key}" — preserved on rewrite, but nothing reads it`)
+    }
+    if (ticket.archived && doc.status !== "done" && doc.status !== "canceled") {
+      push(
+        file,
+        `archived but still ${doc.status} — only done or canceled tickets belong in the archive`,
+      )
+    }
+
+    // A dangling goal ref is deliberately NOT fixable: unlike a blocked_by
+    // pointing at a deleted ticket (pure mechanics), a goal ref is
+    // organization — whether to create the missing goal or clear the ref is a
+    // human call, so the lint states both options and touches nothing.
+    if (doc.goal && !goalSlugs.has(doc.goal)) {
+      push(
+        file,
+        `goal "${doc.goal}" doesn't exist — create it with \`task goal add\`, or clear the ref with \`--goal ""\``,
+      )
+    }
+
+    // The repaired relation list: no self references, no dangling targets, no
+    // duplicates, sorted. Each divergence is its own issue; all are mechanical.
+    const pruned = [...new Set(doc.blockedBy)]
+      .filter((k) => k !== key && valid.has(k))
+      .sort((a, b) => a.localeCompare(b))
+    if (doc.blockedBy.includes(key)) {
+      push(file, `${displayId(key)} is blocked by itself`, true)
+    }
+    for (const target of new Set(doc.blockedBy)) {
+      if (target !== key && !valid.has(target)) {
+        push(file, `blocked_by references ${displayId(target)}, which doesn't exist`, true)
+      }
+    }
+
+    // Everything else — duplicate or unsorted blocked_by, hand-edited field
+    // order or quoting, stray whitespace — is formatting drift: the parse is
+    // fine, the bytes just aren't what the CLI would write. `normalized` keeps
+    // the dangling refs so drift isn't double-reported on top of them. (The
+    // pre-0.8 `milestone:` key never reaches here — the strict parse refuses
+    // it by name, and that error is the whole report.)
+    const normalized = serializeTicket({
+      ...doc,
+      blockedBy: [...new Set(doc.blockedBy)].sort((a, b) => a.localeCompare(b)),
+    })
+    if (normalized !== ticket.text) {
+      push(file, "not in canonical form — `task check --fix` rewrites it", true)
+    }
+    const canonical = serializeTicket({ ...doc, blockedBy: pruned })
+    if (fix && canonical !== ticket.text) {
+      writeFileSync(ticket.absolute, canonical)
+      fixed.push(file)
+    }
+  }
+
+  // ── Asks ───────────────────────────────────────────────────────────────────
+  // Same pass as comments: strict parse, timestamps, unknown keys, canonical
+  // drift. An empty ask body gets its own line — an ask that doesn't say what's
+  // owed is the old boolean wearing a new file.
+  const knownAskKeys = new Set<string>(ASK_FIELDS)
+  for (const ticket of tickets) {
+    const dir = join(ticket.absolute, "..", ASKS_DIR)
+    if (!existsSync(dir)) continue
+    for (const entry of readdirSync(dir)) {
+      if (!entry.endsWith(".md") || entry.startsWith(".")) continue
+      files++
+      const file = posixJoin(ticket.file.slice(0, -TICKET_FILE.length - 1), ASKS_DIR, entry)
+      const text = readFileSync(join(dir, entry), "utf8")
+      let parsed
+      try {
+        parsed = parseAsk(text, file)
+      } catch (error) {
+        if (!(error instanceof TicketParseError)) throw error
+        push(file, reason(error, file))
+        continue
+      }
+      if (!isValidTimestamp(parsed.createdAt)) push(file, "created is not a valid timestamp")
+      if (parsed.resolvedAt !== null && !isValidTimestamp(parsed.resolvedAt)) {
+        push(file, "resolved is not a valid timestamp")
+      }
+      if (!parsed.body.trim()) push(file, "empty ask — say what a person owes, or delete it")
+      let unknownKeys = false
+      for (const key of frontmatterKeys(text) ?? []) {
+        if (knownAskKeys.has(key)) continue
+        unknownKeys = true
+        push(file, `unknown frontmatter key "${key}"`)
+      }
+      const canonical = serializeAsk(parsed)
+      if (canonical !== text && !unknownKeys) {
+        push(file, "not in canonical form — `task check --fix` rewrites it", true)
+        if (fix) {
+          writeFileSync(join(dir, entry), canonical)
+          fixed.push(file)
+        }
+      }
+    }
+  }
+
+  // ── Comments ───────────────────────────────────────────────────────────────
+  const knownCommentKeys = new Set<string>(COMMENT_FIELDS)
+  for (const ticket of tickets) {
+    const dir = join(ticket.absolute, "..", COMMENTS_DIR)
+    if (!existsSync(dir)) continue
+    for (const entry of readdirSync(dir)) {
+      if (!entry.endsWith(".md") || entry.startsWith(".")) continue
+      files++
+      const file = posixJoin(ticket.file.slice(0, -TICKET_FILE.length - 1), COMMENTS_DIR, entry)
+      const text = readFileSync(join(dir, entry), "utf8")
+      let parsed
+      try {
+        parsed = parseComment(text, file)
+      } catch (error) {
+        if (!(error instanceof TicketParseError)) throw error
+        push(file, reason(error, file))
+        continue
+      }
+      if (!isValidTimestamp(parsed.createdAt)) push(file, "created is not a valid timestamp")
+      let unknownKeys = false
+      for (const key of frontmatterKeys(text) ?? []) {
+        if (knownCommentKeys.has(key)) continue
+        unknownKeys = true
+        push(file, `unknown frontmatter key "${key}"`)
+      }
+      // A comment's serialization carries only the known fields, so rewriting
+      // one with unknown keys would delete them — skip the drift fix there.
+      const canonical = serializeComment(parsed)
+      if (canonical !== text && !unknownKeys) {
+        push(file, "not in canonical form — `task check --fix` rewrites it", true)
+        if (fix) {
+          writeFileSync(join(dir, entry), canonical)
+          fixed.push(file)
+        }
+      }
+    }
+  }
+
+  return files
+}