kennel 0.2.1 → 0.2.2

package/kernel/plugins/tasks/src/data/todo-model.ts

@@ -0,0 +1,795 @@
+import { Array, Effect, Order, pipe, Schema } from "effect"
+
+/** Normalized task status shown in the viewer. */
+export type TodoItemStatus = "open" | "blocked" | "done"
+
+/** One normalized task, shared by the task list rows and the task page. */
+export type TodoItemData = {
+  id: string
+  key?: string
+  title: string
+  description?: string
+  type?: string
+  steps?: ReadonlyArray<TodoItemStep>
+  acceptanceCriteria?: ReadonlyArray<TodoItemStep>
+  links?: ReadonlyArray<TodoItemLink>
+  /** Folder-relative note paths and https references that accompany the task. */
+  notes?: ReadonlyArray<string>
+  relations?: ReadonlyArray<TodoItemRelation>
+  status: TodoItemStatus
+  priority: 1 | 2 | 3 | 4 | 5
+  dueDate?: string
+  overdue?: boolean
+  source: string
+  tags: string[]
+}
+
+export type TodoItemStep = {
+  id: string
+  text: string
+  done: boolean
+}
+
+export type TodoItemLink = {
+  id: string
+  provider: "github" | "linear" | "jira" | "web"
+  kind:
+    | "issue"
+    | "pull_request"
+    | "commit"
+    | "repository"
+    | "project"
+    | "document"
+    | "design"
+    | "discussion"
+    | "external"
+  relation: string
+  url: string
+  repository?: string | null
+  number?: number | null
+  title?: string | null
+}
+
+export type TodoItemRelation = {
+  type: string
+  targetTaskId: string
+  description?: string | null
+}
+
+export type TodoFilter = "all" | TodoItemStatus | "overdue"
+
+/** Multi-value filter selection; an empty array means "no filter". */
+export type TodoFilterSelection = readonly string[]
+
+export type TodoSource = Schema.Schema.Type<typeof TodoSourceSchema>
+export type JsonTodo = Schema.Schema.Type<typeof JsonTodoSchema>
+export type TodoDataset = Schema.Schema.Type<typeof TodoDatasetSchema>
+
+export type TodoState = {
+  readonly dataset: TodoDataset | null
+  readonly selectedSource: string
+  readonly filter: TodoFilter
+  /** Selected tag chips; empty shows tasks with any tags. */
+  readonly tag: TodoFilterSelection
+  /** Selected assignee ids; empty shows tasks for any agent. */
+  readonly assignee: TodoFilterSelection
+  readonly query: string
+}
+
+export type UiTodoItem = TodoItemData & {
+  readonly jsonTodo: JsonTodo
+  readonly overdue: boolean
+}
+
+export type TodoDatasetOptions = {
+  readonly dataUrl?: string
+  readonly schemaUrl?: string
+  readonly path?: string
+}
+
+const DATASET_URL = "/data/todos.json"
+const LOCAL_SCHEMA_URL = "https://raggle.co/schemas/tasks.json"
+
+const TaskTypeSchema = Schema.Literal(
+  "task",
+  "bug",
+  "feature",
+  "chore",
+  "spike",
+  "epic",
+  "milestone",
+)
+const TaskStatusSchema = Schema.Literal(
+  "todo",
+  "in_progress",
+  "blocked",
+  "review",
+  "done",
+  "canceled",
+)
+const TaskResolutionSchema = Schema.Literal(
+  "completed",
+  "duplicate",
+  "wont_do",
+  "not_reproducible",
+  "moved",
+)
+const TaskRelationTypeSchema = Schema.Literal(
+  "blocks",
+  "blocked_by",
+  "related_to",
+  "duplicates",
+  "duplicated_by",
+  "parent_of",
+  "child_of",
+)
+const TaskLinkProviderSchema = Schema.Literal("github", "linear", "jira", "web")
+const TaskLinkKindSchema = Schema.Literal(
+  "issue",
+  "pull_request",
+  "commit",
+  "repository",
+  "project",
+  "document",
+  "design",
+  "discussion",
+  "external",
+)
+const TaskLinkRelationSchema = Schema.Literal(
+  "references",
+  "implemented_by",
+  "fixes",
+  "reported_by",
+  "spec",
+  "design",
+  "review",
+  "deployment",
+  "blocked_by",
+)
+
+const JsonTodoSourceSchema = Schema.Struct({
+  id: Schema.String,
+  title: Schema.String,
+})
+
+const JsonTodoStepSchema = Schema.Struct({
+  id: Schema.String,
+  text: Schema.String,
+  done: Schema.Boolean,
+})
+
+const AcceptanceCriterionSchema = Schema.Struct({
+  id: Schema.String,
+  text: Schema.String,
+  done: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+})
+
+const TaskEstimateSchema = Schema.Struct({
+  points: Schema.optionalWith(Schema.NullOr(Schema.Number), {
+    default: () => null,
+  }),
+  minutes: Schema.optionalWith(Schema.NullOr(Schema.Number), {
+    default: () => null,
+  }),
+  confidence: Schema.optionalWith(
+    Schema.NullOr(Schema.Literal("low", "medium", "high")),
+    { default: () => null },
+  ),
+})
+
+const TaskRelationSchema = Schema.Struct({
+  type: TaskRelationTypeSchema,
+  targetTaskId: Schema.String,
+  description: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+})
+
+const TaskLinkSnapshotSchema = Schema.Struct({
+  state: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+  draft: Schema.optionalWith(Schema.NullOr(Schema.Boolean), {
+    default: () => null,
+  }),
+  checks: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+  updatedAt: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+})
+
+const TaskLinkSyncSchema = Schema.Struct({
+  mode: Schema.optionalWith(Schema.Literal("manual", "read", "write"), {
+    default: () => "manual" as const,
+  }),
+  checkedAt: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+})
+
+const TaskLinkSchema = Schema.Struct({
+  id: Schema.String,
+  provider: TaskLinkProviderSchema,
+  kind: TaskLinkKindSchema,
+  relation: TaskLinkRelationSchema,
+  url: Schema.String,
+  repository: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+  number: Schema.optionalWith(Schema.NullOr(Schema.Number), {
+    default: () => null,
+  }),
+  title: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+  snapshot: Schema.optionalWith(Schema.NullOr(TaskLinkSnapshotSchema), {
+    default: () => null,
+  }),
+  sync: Schema.optionalWith(Schema.NullOr(TaskLinkSyncSchema), {
+    default: () => null,
+  }),
+})
+
+const TaskCommentSchema = Schema.Struct({
+  id: Schema.String,
+  authorId: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+  body: Schema.String,
+  createdAt: Schema.String,
+})
+
+const TaskDecisionSchema = Schema.Struct({
+  id: Schema.String,
+  title: Schema.String,
+  outcome: Schema.String,
+  decidedAt: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+})
+
+const TaskCustomFieldSchema = Schema.Struct({
+  id: Schema.String,
+  value: Schema.Unknown,
+})
+
+const TodoSourceSchema = Schema.Struct({
+  id: Schema.String,
+  title: Schema.String,
+  total: Schema.Number,
+  open: Schema.Number,
+})
+
+const JsonTodoSchema = Schema.Struct({
+  id: Schema.optionalWith(Schema.String, { default: () => "" }),
+  key: Schema.optionalWith(Schema.String, { default: () => "" }),
+  index: Schema.optionalWith(Schema.Number, { default: () => 0 }),
+  rank: Schema.optionalWith(Schema.String, { default: () => "" }),
+  name: Schema.String,
+  description: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => "",
+  }),
+  type: Schema.optionalWith(TaskTypeSchema, { default: () => "task" as const }),
+  status: Schema.optionalWith(TaskStatusSchema, {
+    default: () => "todo" as const,
+  }),
+  resolution: Schema.optionalWith(Schema.NullOr(TaskResolutionSchema), {
+    default: () => null,
+  }),
+  done: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+  priority: Schema.optionalWith(Schema.NullOr(Schema.Number), {
+    default: () => 5,
+  }),
+  deadline: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+  overdue: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+  reporterId: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+  assigneeIds: Schema.optionalWith(Schema.Array(Schema.String), {
+    default: () => [],
+  }),
+  estimate: Schema.optionalWith(Schema.NullOr(TaskEstimateSchema), {
+    default: () => null,
+  }),
+  projectIds: Schema.optionalWith(Schema.Array(Schema.String), {
+    default: () => [],
+  }),
+  cycleId: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+  milestoneIds: Schema.optionalWith(Schema.Array(Schema.String), {
+    default: () => [],
+  }),
+  componentIds: Schema.optionalWith(Schema.Array(Schema.String), {
+    default: () => [],
+  }),
+  areaIds: Schema.optionalWith(Schema.Array(Schema.String), {
+    default: () => [],
+  }),
+  parentId: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+  relations: Schema.optionalWith(Schema.Array(TaskRelationSchema), {
+    default: () => [],
+  }),
+  links: Schema.optionalWith(Schema.Array(TaskLinkSchema), {
+    default: () => [],
+  }),
+  notes: Schema.optionalWith(Schema.Array(Schema.String), {
+    default: () => [],
+  }),
+  acceptanceCriteria: Schema.optionalWith(
+    Schema.Array(AcceptanceCriterionSchema),
+    { default: () => [] },
+  ),
+  steps: Schema.optionalWith(Schema.Array(JsonTodoStepSchema), {
+    default: () => [],
+  }),
+  comments: Schema.optionalWith(Schema.Array(TaskCommentSchema), {
+    default: () => [],
+  }),
+  decisions: Schema.optionalWith(Schema.Array(TaskDecisionSchema), {
+    default: () => [],
+  }),
+  createdAt: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+  updatedAt: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+  startedAt: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+  completedAt: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+  canceledAt: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+  tags: Schema.optionalWith(Schema.Array(Schema.String), { default: () => [] }),
+  customFields: Schema.optionalWith(Schema.Array(TaskCustomFieldSchema), {
+    default: () => [],
+  }),
+  reminder: Schema.optionalWith(Schema.Unknown, { default: () => null }),
+  source: Schema.optionalWith(JsonTodoSourceSchema, {
+    default: () => ({ id: "todos", title: "Todos" }),
+  }),
+})
+
+const PersonSchema = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  email: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+  url: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+})
+
+const ProjectRefSchema = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  description: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+})
+
+const CycleSchema = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  startsAt: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+  endsAt: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+})
+
+const NamedCatalogSchema = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+})
+
+const MilestoneSchema = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  dueAt: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+})
+
+const ComponentSchema = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  ownerId: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+})
+
+const IntegrationSchema = Schema.Struct({
+  id: Schema.String,
+  provider: TaskLinkProviderSchema,
+  name: Schema.String,
+  repository: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+  baseUrl: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+  syncMode: Schema.optionalWith(Schema.Literal("manual", "read", "write"), {
+    default: () => "manual" as const,
+  }),
+})
+
+const CustomFieldDefinitionSchema = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  type: Schema.Literal(
+    "text",
+    "number",
+    "date",
+    "select",
+    "multi_select",
+    "boolean",
+    "url",
+  ),
+  options: Schema.optionalWith(Schema.Array(Schema.String), {
+    default: () => [],
+  }),
+})
+
+const AutomationSchema = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  trigger: Schema.Literal(
+    "status_changed",
+    "link_changed",
+    "deadline_overdue",
+    "task_created",
+    "task_updated",
+  ),
+  enabled: Schema.optionalWith(Schema.Boolean, { default: () => true }),
+  description: Schema.optionalWith(Schema.NullOr(Schema.String), {
+    default: () => null,
+  }),
+})
+
+export const TodoDatasetSchema = Schema.Struct({
+  $schema: Schema.String,
+  version: Schema.Literal(1, 2),
+  project: Schema.Struct({
+    name: Schema.String,
+  }),
+  sources: Schema.Array(TodoSourceSchema),
+  people: Schema.optionalWith(Schema.Array(PersonSchema), {
+    default: () => [],
+  }),
+  projects: Schema.optionalWith(Schema.Array(ProjectRefSchema), {
+    default: () => [],
+  }),
+  cycles: Schema.optionalWith(Schema.Array(CycleSchema), { default: () => [] }),
+  milestones: Schema.optionalWith(Schema.Array(MilestoneSchema), {
+    default: () => [],
+  }),
+  components: Schema.optionalWith(Schema.Array(ComponentSchema), {
+    default: () => [],
+  }),
+  areas: Schema.optionalWith(Schema.Array(NamedCatalogSchema), {
+    default: () => [],
+  }),
+  integrations: Schema.optionalWith(Schema.Array(IntegrationSchema), {
+    default: () => [],
+  }),
+  customFields: Schema.optionalWith(Schema.Array(CustomFieldDefinitionSchema), {
+    default: () => [],
+  }),
+  automations: Schema.optionalWith(Schema.Array(AutomationSchema), {
+    default: () => [],
+  }),
+  tasks: Schema.Array(JsonTodoSchema),
+  summary: Schema.Struct({
+    open: Schema.Number,
+    completed: Schema.Number,
+    sources: Schema.Number,
+  }),
+})
+
+/** Overdue tasks first; overdue is the most urgent state. */
+const overdueOrder = Order.mapInput(
+  Order.boolean,
+  (item: UiTodoItem) => !item.overdue,
+)
+const priorityOrder = Order.mapInput(
+  Order.number,
+  (item: UiTodoItem) => item.priority,
+)
+const rankOrder = Order.mapInput(
+  Order.string,
+  (item: UiTodoItem) => item.jsonTodo.rank || "9999",
+)
+const deadlineOrder = Order.mapInput(
+  Order.string,
+  (item: UiTodoItem) => item.dueDate ?? "9999",
+)
+const titleOrder = Order.mapInput(Order.string, (item: UiTodoItem) =>
+  item.title.toLowerCase(),
+)
+
+export const initialState: TodoState = {
+  dataset: null,
+  selectedSource: "*",
+  filter: "open",
+  tag: [],
+  assignee: [],
+  query: "",
+}
+
+export const decodeTodoDataset = (value: unknown) =>
+  Schema.decodeUnknownSync(TodoDatasetSchema)(value)
+
+export const fetchTodoDataset = (options: TodoDatasetOptions = {}) =>
+  Effect.tryPromise({
+    try: async () => {
+      const datasetUrl = datasetUrlFromOptions(options)
+      const datasetResponse = await fetch(datasetUrl)
+      if (!datasetResponse.ok) {
+        throw new Error(`Could not load ${datasetUrl}.`)
+      }
+      const rawDataset: unknown = await datasetResponse.json()
+      const dataset = Schema.decodeUnknownSync(TodoDatasetSchema)(rawDataset)
+      validateDatasetLinks(dataset)
+
+      const schemaUrl =
+        options.schemaUrl ?? dataset["$schema"] ?? LOCAL_SCHEMA_URL
+      const schemaResponse = await fetch(schemaUrl)
+      if (!schemaResponse.ok) {
+        throw new Error(`Could not load todo schema at ${schemaUrl}.`)
+      }
+      const jsonSchema = (await schemaResponse.json()) as {
+        readonly $id?: string
+      }
+      if (
+        jsonSchema["$id"] &&
+        isRemoteUrl(schemaUrl) &&
+        jsonSchema["$id"] !== schemaUrl
+      ) {
+        throw new Error(
+          `Todo schema id mismatch: expected ${schemaUrl}, got ${jsonSchema["$id"]}.`,
+        )
+      }
+
+      return dataset
+    },
+    catch: (error) =>
+      error instanceof Error ? error : new Error(String(error)),
+  })
+
+const datasetUrlFromOptions = (options: TodoDatasetOptions) => {
+  const url = new URL(options.dataUrl ?? DATASET_URL, window.location.origin)
+  if (options.path) {
+    url.searchParams.set("path", options.path)
+  }
+  return `${url.pathname}${url.search}`
+}
+
+export const visibleTodos = (state: TodoState) =>
+  Effect.succeed(
+    pipe(
+      todosForDataset(state.dataset),
+      Array.filter(
+        (item) =>
+          state.selectedSource === "*" ||
+          item.jsonTodo.source.id === state.selectedSource,
+      ),
+      Array.filter((item) => {
+        if (state.filter === "all") return true
+        if (state.filter === "overdue")
+          return item.overdue && item.status !== "done"
+        return item.status === state.filter
+      }),
+      Array.filter((item) =>
+        state.tag.length
+          ? item.tags.some((tag) => state.tag.includes(tag))
+          : true,
+      ),
+      Array.filter((item) =>
+        state.assignee.length
+          ? item.jsonTodo.assigneeIds.some((id) => state.assignee.includes(id))
+          : true,
+      ),
+      Array.filter((item) => {
+        const query = state.query.trim().toLowerCase()
+        if (!query) return true
+        return [
+          item.key,
+          item.title,
+          item.description,
+          item.source,
+          item.type,
+          item.status,
+          ...item.tags,
+          ...(item.steps ?? []).map((step) => step.text),
+          ...(item.acceptanceCriteria ?? []).map((criterion) => criterion.text),
+          ...(item.links ?? []).flatMap(
+            (link) =>
+              [link.title, link.url, link.repository].filter(
+                Boolean,
+              ) as Array<string>,
+          ),
+          ...(item.notes ?? []),
+        ]
+          .filter(Boolean)
+          .join(" ")
+          .toLowerCase()
+          .includes(query)
+      }),
+      Array.sort(
+        Order.combineMany(overdueOrder, [
+          priorityOrder,
+          rankOrder,
+          deadlineOrder,
+          titleOrder,
+        ]),
+      ),
+    ),
+  )
+
+export const allTodos = (state: TodoState) =>
+  Effect.succeed(todosForDataset(state.dataset))
+
+export type TodoAgent = {
+  readonly id: string
+  readonly name: string
+}
+
+/** Agents (assignees) used by a dataset's tasks, sorted by name. People
+ * never assigned keep their name; ids without a person entry show raw. */
+export const datasetAgents = (dataset: TodoDataset | null): TodoAgent[] => {
+  const tasks = dataset?.tasks ?? []
+  const used = (id: string) =>
+    tasks.some((task) => task.assigneeIds.includes(id))
+  const names = new Map<string, string>()
+  for (const person of dataset?.people ?? []) {
+    if (used(person.id)) names.set(person.id, person.name)
+  }
+  for (const task of tasks) {
+    for (const id of task.assigneeIds) {
+      if (!names.has(id)) names.set(id, id)
+    }
+  }
+  return [...names]
+    .map(([id, name]) => ({ id, name }))
+    .sort((a, b) => a.name.localeCompare(b.name))
+}
+
+/** UI-ready task items for a dataset, without filtering or sorting. */
+export const todoItems = (dataset: TodoDataset | null): UiTodoItem[] =>
+  todosForDataset(dataset)
+
+export const datasetSummary = (dataset: TodoDataset | null) =>
+  Effect.succeed({
+    open: dataset?.tasks.filter(isOpenTask).length ?? 0,
+    completed: dataset?.tasks.filter(isDone).length ?? 0,
+    sources: dataset?.summary.sources ?? 0,
+    overdue:
+      dataset?.tasks.filter((task) => !isDone(task) && task.overdue).length ??
+      0,
+    blocked:
+      dataset?.tasks.filter((task) => !isDone(task) && isBlocked(task))
+        .length ?? 0,
+  })
+
+const toUiTodo = (task: JsonTodo): UiTodoItem => {
+  const status: TodoItemStatus = isDone(task)
+    ? "done"
+    : isBlocked(task)
+      ? "blocked"
+      : "open"
+  return {
+    id: task.id,
+    key: task.key || task.id,
+    title: task.name,
+    description: task.description ?? undefined,
+    type: task.type,
+    steps: [...(task.steps ?? [])],
+    acceptanceCriteria: [...(task.acceptanceCriteria ?? [])],
+    links: [...(task.links ?? [])],
+    notes: [...(task.notes ?? [])],
+    relations: [...(task.relations ?? [])],
+    status,
+    priority: normalizePriority(task.priority),
+    dueDate: task.deadline ?? undefined,
+    source: task.source.id,
+    tags: [...task.tags],
+    jsonTodo: task,
+    overdue: !isDone(task) && (task.overdue || isOverdue(task.deadline)),
+  }
+}
+
+const todosForDataset = (dataset: TodoDataset | null) =>
+  pipe(dataset?.tasks ?? [], Array.map(toUiTodo))
+
+const isDone = (task: JsonTodo) => task.status === "done"
+const isOpenTask = (task: JsonTodo) =>
+  !isDone(task) && task.status !== "canceled"
+const isBlocked = (task: JsonTodo) =>
+  task.status === "blocked" ||
+  task.relations.some((relation) => relation.type === "blocked_by")
+
+const isRemoteUrl = (value: string) => /^https?:\/\//i.test(value)
+
+const normalizePriority = (value: number | null): TodoItemData["priority"] => {
+  if (value === 1 || value === 2 || value === 3 || value === 4 || value === 5) {
+    return value
+  }
+  return 5
+}
+
+const isOverdue = (deadline: string | null) => {
+  if (!deadline) return false
+  const date = new Date(`${deadline}T12:00:00`)
+  if (Number.isNaN(date.valueOf())) return false
+  const today = new Date()
+  today.setHours(0, 0, 0, 0)
+  date.setHours(0, 0, 0, 0)
+  return date < today
+}
+
+const validateDatasetLinks = (dataset: TodoDataset) => {
+  const errors: Array<string> = []
+  for (const task of dataset.tasks) {
+    for (const link of task.links) {
+      const error = validateLink(link)
+      if (error) {
+        errors.push(`${task.key || task.id} ${link.id}: ${error}`)
+      }
+    }
+  }
+  if (errors.length) {
+    throw new Error(
+      `Invalid todo links:\n${errors.map((error) => `- ${error}`).join("\n")}`,
+    )
+  }
+}
+
+const validateLink = (link: JsonTodo["links"][number]) => {
+  let url: URL
+  try {
+    url = new URL(link.url)
+  } catch {
+    return "url is not a valid absolute URL"
+  }
+
+  const isLocalhost =
+    url.hostname === "localhost" ||
+    url.hostname === "127.0.0.1" ||
+    url.hostname === "::1"
+  if (url.username || url.password)
+    return "url must not contain embedded credentials"
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && isLocalhost)) {
+    return "url must use https, except localhost development links"
+  }
+  if (link.provider === "github" && url.hostname !== "github.com") {
+    return "github links must use github.com"
+  }
+  if (
+    link.provider === "linear" &&
+    url.hostname !== "linear.app" &&
+    !url.hostname.endsWith(".linear.app")
+  ) {
+    return "linear links must use linear.app"
+  }
+  if (
+    link.provider === "jira" &&
+    !url.hostname.endsWith(".atlassian.net") &&
+    url.hostname !== "jira.atlassian.com"
+  ) {
+    return "jira links must use an Atlassian Jira host"
+  }
+  return null
+}