kennel 0.2.1 → 0.2.2

package/kernel/plugins/calendar/src/parse.ts

@@ -0,0 +1,610 @@
+import {
+  addDays,
+  addMonths,
+  addWeeks,
+  differenceInCalendarDays,
+  differenceInCalendarMonths,
+  endOfDay,
+  isSameDay,
+} from "date-fns"
+
+import type { ContentIssue } from "@raggle-ai/folder-plugin/validation"
+import {
+  issueSummary,
+  parseJsonSource,
+} from "@raggle-ai/folder-plugin/validation"
+
+export type CalendarColor =
+  "blue" | "green" | "red" | "yellow" | "purple" | "orange"
+
+export type CalendarRepeating = "daily" | "weekly" | "monthly"
+export type CalendarStatus = "confirmed" | "tentative" | "cancelled"
+
+export interface CalendarEvent {
+  id: string
+  title: string
+  start: Date
+  end: Date
+  /**
+   * Absolute owning folder of the `calendar.json` that declared this event,
+   * stamped by the server at merge time (not part of the source document).
+   */
+  folder?: string
+  description?: string
+  group?: string
+  groupColor?: CalendarColor
+  color?: CalendarColor
+  repeating?: CalendarRepeating
+  allDay?: boolean
+  attendees?: string[]
+  excludeDates?: Date[]
+  location?: string
+  organizer?: string
+  reminders?: number[]
+  repeatUntil?: Date
+  status?: CalendarStatus
+  tags?: string[]
+  url?: string
+}
+
+export interface CalendarDocument {
+  color?: CalendarColor
+  group?: string
+  title?: string
+  /** Optional anchor date: the calendar view opens here instead of today. */
+  startDate?: string
+  events: CalendarEvent[]
+}
+
+export interface CalendarSource {
+  calendar: CalendarDocument
+  /** Absolute directory that owns the `calendar.json` file. */
+  folder: string
+  group: string
+  path: string
+}
+
+type RawEvent = Record<string, unknown>
+
+type RawCalendar = {
+  color?: unknown
+  events?: RawEvent[]
+  group?: unknown
+  startDate?: unknown
+  title?: unknown
+}
+
+const colors = new Set<CalendarColor>([
+  "blue",
+  "green",
+  "red",
+  "yellow",
+  "purple",
+  "orange",
+])
+
+const repeats = new Set<CalendarRepeating>(["daily", "weekly", "monthly"])
+const statuses = new Set<CalendarStatus>([
+  "confirmed",
+  "tentative",
+  "cancelled",
+])
+
+function valueAt(record: RawEvent, keys: string[]) {
+  for (const key of keys) {
+    const value = record[key]
+    if (value !== undefined && value !== null && value !== "") return value
+  }
+  return undefined
+}
+
+function text(record: RawEvent, keys: string[]) {
+  const value = valueAt(record, keys)
+  return typeof value === "string" && value.trim() ? value.trim() : undefined
+}
+
+function texts(value: unknown) {
+  if (!Array.isArray(value)) return undefined
+  const values = [
+    ...new Set(
+      value
+        .filter((item): item is string => typeof item === "string")
+        .map((item) => item.trim())
+        .filter(Boolean),
+    ),
+  ]
+  return values.length ? values : undefined
+}
+
+function numbers(value: unknown) {
+  if (!Array.isArray(value)) return undefined
+  const values = [
+    ...new Set(
+      value.filter(
+        (item): item is number =>
+          typeof item === "number" && Number.isInteger(item) && item >= 0,
+      ),
+    ),
+  ].sort((left, right) => left - right)
+  return values.length ? values : undefined
+}
+
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/
+
+function localDateOnly(value: string): Date | undefined {
+  const trimmed = value.trim()
+  if (!DATE_ONLY.test(trimmed)) return undefined
+  const [year, month, day] = trimmed.split("-").map(Number)
+  return new Date(year ?? 0, (month ?? 1) - 1, day ?? 1)
+}
+
+function date(value: unknown, fallback: Date) {
+  if (value instanceof Date && !Number.isNaN(value.getTime())) return value
+  if (typeof value === "number" && Number.isFinite(value))
+    return new Date(value)
+  if (typeof value === "string" && value.trim()) {
+    const parsed = localDateOnly(value) ?? new Date(value)
+    if (!Number.isNaN(parsed.getTime())) return parsed
+  }
+  return fallback
+}
+
+function color(value: unknown): CalendarColor | undefined {
+  if (typeof value !== "string") return undefined
+  const candidate = value.toLowerCase()
+  return colors.has(candidate as CalendarColor)
+    ? (candidate as CalendarColor)
+    : undefined
+}
+
+function repeating(value: unknown): CalendarRepeating | undefined {
+  if (typeof value !== "string") return undefined
+  const candidate = value.toLowerCase()
+  return repeats.has(candidate as CalendarRepeating)
+    ? (candidate as CalendarRepeating)
+    : undefined
+}
+
+function status(value: unknown): CalendarStatus | undefined {
+  if (typeof value !== "string") return undefined
+  const candidate = value.toLowerCase()
+  return statuses.has(candidate as CalendarStatus)
+    ? (candidate as CalendarStatus)
+    : undefined
+}
+
+function url(value: unknown) {
+  if (typeof value !== "string" || !value.trim()) return undefined
+  const candidate = value.trim()
+  return /^https?:\/\/[^\s]+$/i.test(candidate) ? candidate : undefined
+}
+
+function dates(value: unknown) {
+  if (!Array.isArray(value)) return undefined
+  const values = value
+    .map((item) => date(item, new Date(Number.NaN)))
+    .filter((item) => !Number.isNaN(item.getTime()))
+  return values.length ? values : undefined
+}
+
+function until(value: unknown) {
+  if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    const parsed = date(value, new Date(Number.NaN))
+    return Number.isNaN(parsed.getTime()) ? undefined : endOfDay(parsed)
+  }
+  const parsed = date(value, new Date(Number.NaN))
+  return Number.isNaN(parsed.getTime()) ? undefined : parsed
+}
+
+export function parseCalendar(calendar: unknown): CalendarDocument | undefined {
+  if (Array.isArray(calendar)) return { events: parseEvents(calendar) }
+  if (!calendar || typeof calendar !== "object") return undefined
+
+  const record = calendar as RawCalendar
+  if (!Array.isArray(record.events)) return undefined
+
+  return {
+    color: color(record.color),
+    startDate:
+      typeof record.startDate === "string" && record.startDate.trim()
+        ? record.startDate.trim()
+        : undefined,
+    group:
+      typeof record.group === "string" && record.group.trim()
+        ? record.group.trim()
+        : undefined,
+    title:
+      typeof record.title === "string" && record.title.trim()
+        ? record.title.trim()
+        : undefined,
+    events: parseEvents(record.events),
+  }
+}
+
+export function parseCalendarJson(
+  source: string,
+): CalendarDocument | undefined {
+  try {
+    return parseCalendar(JSON.parse(source))
+  } catch {
+    return undefined
+  }
+}
+
+export function parseEvents(events: RawEvent[]): CalendarEvent[] {
+  return events.map((record, index) => normalizeEvent(record, index))
+}
+
+export function normalizeEvent(record: RawEvent, index: number): CalendarEvent {
+  const id = valueAt(record, ["id", "uid", "key"])?.toString() ?? String(index)
+
+  const startValue = date(
+    valueAt(record, ["start", "startDate", "start_date", "date", "begin"]),
+    new Date(0),
+  )
+  const endValue = date(
+    valueAt(record, ["end", "endDate", "end_date", "due", "finish"]),
+    startValue,
+  )
+
+  const allDay = typeof record.allDay === "boolean" ? record.allDay : undefined
+  const start = startValue
+  const end =
+    endValue > start
+      ? endValue
+      : new Date(start.getTime() + (allDay ? 86_400_000 : 3_600_000))
+
+  const rawColor =
+    valueAt(record, [
+      "color",
+      "colour",
+      "calendarId",
+      "calendar",
+      "category",
+    ]) ?? valueAt(record, ["calendars"])
+  const eventColor =
+    color(rawColor) ?? color(Array.isArray(rawColor) ? rawColor[0] : undefined)
+
+  return {
+    id,
+    start,
+    end,
+    color: eventColor,
+    folder: typeof record.folder === "string" ? record.folder : undefined,
+    group: text(record, ["group"]),
+    groupColor: color(record.groupColor),
+    repeating: repeating(record.repeating),
+    allDay,
+    attendees: texts(record.attendees),
+    excludeDates: dates(record.excludeDates),
+    location: text(record, ["location"]),
+    organizer: text(record, ["organizer"]),
+    reminders: numbers(record.reminders),
+    repeatUntil: until(record.repeatUntil),
+    status: status(record.status),
+    tags: texts(record.tags),
+    url: url(record.url),
+    description: text(record, [
+      "description",
+      "detail",
+      "notes",
+      "summary",
+      "body",
+    ]),
+    title:
+      text(record, ["title", "name", "subject", "summary", "label"]) ??
+      "Untitled",
+  }
+}
+
+const AUTO_PALETTE: CalendarColor[] = [
+  "green",
+  "orange",
+  "purple",
+  "red",
+  "yellow",
+  "blue",
+]
+
+/**
+ * Resolve render colors for a merged event list. Precedence per event:
+ * explicit event color, then folder/group color, then an auto-assigned color
+ * for the event's group. Groups without any declared color get distinct
+ * palette colors in deterministic first-seen order, so filter chips and
+ * events for the same group always match without any configuration.
+ */
+export function resolveColors(events: CalendarEvent[]): CalendarEvent[] {
+  const groupColor = new Map<string, CalendarColor | undefined>()
+  const used = new Set<CalendarColor>()
+  for (const event of events) {
+    if (!event.group || groupColor.has(event.group)) continue
+    const resolved = event.color ?? event.groupColor
+    groupColor.set(event.group, resolved)
+    if (resolved) used.add(resolved)
+  }
+
+  let next = 0
+  for (const [group, resolved] of groupColor) {
+    if (resolved !== undefined) continue
+    let chosen: CalendarColor | undefined
+    for (let attempt = 0; attempt < AUTO_PALETTE.length; attempt++) {
+      const candidate = AUTO_PALETTE[(next + attempt) % AUTO_PALETTE.length]!
+      if (!used.has(candidate)) {
+        chosen = candidate
+        next += attempt + 1
+        break
+      }
+    }
+    if (!chosen) {
+      chosen = AUTO_PALETTE[next % AUTO_PALETTE.length]!
+      next += 1
+    }
+    used.add(chosen)
+    groupColor.set(group, chosen)
+  }
+
+  return events.map((event) => ({
+    ...event,
+    color:
+      event.color ??
+      event.groupColor ??
+      groupColor.get(event.group ?? "") ??
+      "blue",
+  }))
+}
+
+export function mergeCalendars(sources: CalendarSource[]): CalendarDocument {
+  const root = sources.find((source) => source.path === "calendar.json")
+
+  return {
+    title: root?.calendar.title ?? sources[0]?.calendar.title,
+    startDate: root?.calendar.startDate ?? sources[0]?.calendar.startDate,
+    events: sources.flatMap((source) => {
+      const group = source.calendar.group ?? source.group
+      return source.calendar.events.map((event) => ({
+        ...event,
+        folder: source.folder,
+        group: event.group ?? group,
+        groupColor: event.groupColor ?? source.calendar.color,
+        id: `${source.path}:${event.id}`,
+      }))
+    }),
+  }
+}
+
+function repeatStart(event: CalendarEvent, index: number) {
+  if (event.repeating === "daily") return addDays(event.start, index)
+  if (event.repeating === "weekly") return addWeeks(event.start, index)
+  return addMonths(event.start, index)
+}
+
+function repeatIndex(event: CalendarEvent, date: Date) {
+  if (event.repeating === "daily") {
+    return Math.max(0, differenceInCalendarDays(date, event.start) - 1)
+  }
+  if (event.repeating === "weekly") {
+    return Math.max(
+      0,
+      Math.floor(differenceInCalendarDays(date, event.start) / 7) - 1,
+    )
+  }
+  return Math.max(0, differenceInCalendarMonths(date, event.start) - 1)
+}
+
+export function eventsInRange(events: CalendarEvent[], start: Date, end: Date) {
+  if (
+    Number.isNaN(start.getTime()) ||
+    Number.isNaN(end.getTime()) ||
+    end <= start
+  )
+    return []
+
+  const occurrences: CalendarEvent[] = []
+  for (const event of events) {
+    if (!event.repeating) {
+      if (event.end > start && event.start < end) occurrences.push(event)
+      continue
+    }
+
+    const duration = event.end.getTime() - event.start.getTime()
+    const earliest = new Date(start.getTime() - duration)
+    for (let index = repeatIndex(event, earliest); ; index += 1) {
+      const occurrenceStart = repeatStart(event, index)
+      if (Number.isNaN(occurrenceStart.getTime()) || occurrenceStart >= end)
+        break
+      if (event.repeatUntil && occurrenceStart > event.repeatUntil) break
+      const occurrenceEnd = new Date(occurrenceStart.getTime() + duration)
+      if (occurrenceEnd <= start) continue
+      if (
+        event.excludeDates?.some((excluded) =>
+          isSameDay(excluded, occurrenceStart),
+        )
+      )
+        continue
+      occurrences.push({
+        ...event,
+        id: `${event.id}:${occurrenceStart.toISOString()}`,
+        start: occurrenceStart,
+        end: occurrenceEnd,
+      })
+    }
+  }
+  return occurrences.sort(
+    (left, right) => left.start.getTime() - right.start.getTime(),
+  )
+}
+
+export function eventCount(calendar: CalendarDocument | undefined) {
+  return calendar?.events.length ?? 0
+}
+
+const EVENT_TITLE_KEYS = [
+  "title",
+  "name",
+  "subject",
+  "summary",
+  "label",
+] as const
+const EVENT_START_KEYS = [
+  "start",
+  "startDate",
+  "start_date",
+  "date",
+  "begin",
+] as const
+const EVENT_END_KEYS = ["end", "endDate", "end_date", "due", "finish"] as const
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value)
+}
+
+function strictDate(value: unknown): Date | undefined {
+  if (value instanceof Date && !Number.isNaN(value.getTime())) return value
+  if (typeof value === "number" && Number.isFinite(value))
+    return new Date(value)
+  if (typeof value === "string" && value.trim()) {
+    const parsed = localDateOnly(value) ?? new Date(value)
+    if (!Number.isNaN(parsed.getTime())) return parsed
+  }
+  return undefined
+}
+
+/**
+ * Validate a parsed `calendar.json` value before tolerant rendering. Covers
+ * what the tolerant parser would silently drop or default (missing events
+ * array, events without any title, unparseable dates that would fall back to
+ * epoch, bad enums). Returns `{ path, message }` issues; empty means valid.
+ */
+export function validateCalendarFile(value: unknown): ContentIssue[] {
+  if (Array.isArray(value)) {
+    return value.flatMap((event, index) =>
+      validateEvent(event, `events[${index}]`),
+    )
+  }
+  if (!isRecord(value)) {
+    return [
+      {
+        path: "#",
+        message: "calendar.json must contain an object or an array of events",
+      },
+    ]
+  }
+
+  const issues: ContentIssue[] = []
+  if (!Array.isArray(value.events)) {
+    issues.push({ path: "events", message: "must be an array of events" })
+  } else {
+    value.events.forEach((event, index) => {
+      issues.push(...validateEvent(event, `events[${index}]`))
+    })
+  }
+  return issues
+}
+
+function validateEvent(event: unknown, path: string): ContentIssue[] {
+  if (!isRecord(event)) {
+    return [{ path, message: "must be an event object" }]
+  }
+  const issues: ContentIssue[] = []
+
+  const hasTitle = EVENT_TITLE_KEYS.some(
+    (key) => typeof event[key] === "string" && event[key].trim().length > 0,
+  )
+  if (!hasTitle) {
+    issues.push({
+      path,
+      message:
+        "has no title (expected one of title, name, subject, summary, label)",
+    })
+  }
+
+  const startValue = EVENT_START_KEYS.find((key) => event[key] !== undefined)
+  if (startValue !== undefined && !strictDate(event[startValue])) {
+    issues.push({
+      path: `${path}.${startValue}`,
+      message: "could not be parsed as a date",
+    })
+  }
+
+  const endValue = EVENT_END_KEYS.find((key) => event[key] !== undefined)
+  if (
+    endValue !== undefined &&
+    event[endValue] !== null &&
+    !strictDate(event[endValue])
+  ) {
+    issues.push({
+      path: `${path}.${endValue}`,
+      message: "could not be parsed as a date",
+    })
+  }
+
+  if (event.allDay !== undefined && typeof event.allDay !== "boolean") {
+    issues.push({ path: `${path}.allDay`, message: "must be a boolean" })
+  }
+  if (
+    event.repeating !== undefined &&
+    !["daily", "weekly", "monthly"].includes(String(event.repeating))
+  ) {
+    issues.push({
+      path: `${path}.repeating`,
+      message: "must be one of daily, weekly, monthly",
+    })
+  }
+  if (
+    event.status !== undefined &&
+    !["confirmed", "tentative", "cancelled"].includes(String(event.status))
+  ) {
+    issues.push({
+      path: `${path}.status`,
+      message: "must be one of confirmed, tentative, cancelled",
+    })
+  }
+  if (event.excludeDates !== undefined && !Array.isArray(event.excludeDates)) {
+    issues.push({
+      path: `${path}.excludeDates`,
+      message: "must be an array of dates",
+    })
+  }
+  return issues
+}
+
+/**
+ * Parse a `calendar.json` source string and validate it. Never throws:
+ * invalid JSON and structural mistakes come back as issues with paths.
+ */
+export function parseCalendarSource(source: string) {
+  return parseJsonSource<unknown>(source, validateCalendarFile)
+}
+
+/**
+ * Compact validation summary for nav badges and error headers.
+ */
+export function calendarIssueSummary(issues: ContentIssue[]): string {
+  return issueSummary(issues, "calendar.json")
+}
+
+/**
+ * Starter `calendar.json` for `kennel init`: one sample event in the shape
+ * the tolerant parser reads directly.
+ */
+export function starterCalendarSource(): string {
+  return `${JSON.stringify(
+    {
+      color: "blue",
+      events: [
+        {
+          id: "1",
+          title: "First event",
+          description: "Describe what happens.",
+          start: "2030-01-01T09:00:00",
+          end: "2030-01-01T10:00:00",
+          allDay: false,
+          status: "confirmed",
+          attendees: [],
+        },
+      ],
+    },
+    null,
+    2,
+  )}\n`
+}