kennel 0.2.1 → 0.2.2

package/kernel/plugins/tasks/src/data/parse.ts

@@ -0,0 +1,544 @@
+/**
+ * Validation functions for the raw `todo.json` source document.
+ *
+ * This module is the tasks plugin's "validate" seam: it turns a source file
+ * into either a typed document or a list of precise, human-readable issues
+ * (`path` + `message`). It is deliberately dependency-free and shared by the
+ * server entry (detection + data loading), the client error panel, and the
+ * plugin's node tests.
+ *
+ * Parsing never throws: invalid JSON and structural mistakes are reported as
+ * issues so the host and viewer can show exactly what is wrong instead of a
+ * 404 or a generic "could not parse" message.
+ */
+
+import type { ContentIssue } from "@raggle-ai/folder-plugin/validation"
+import {
+  issueSummary,
+  parseJsonSource,
+} from "@raggle-ai/folder-plugin/validation"
+
+export const TASK_TYPES = [
+  "task",
+  "bug",
+  "feature",
+  "chore",
+  "spike",
+  "epic",
+  "milestone",
+] as const
+
+export const TASK_STATUSES = [
+  "todo",
+  "in_progress",
+  "blocked",
+  "review",
+  "done",
+  "canceled",
+] as const
+
+export const RELATION_TYPES = [
+  "blocks",
+  "blocked_by",
+  "related_to",
+  "duplicates",
+  "duplicated_by",
+  "parent_of",
+  "child_of",
+] as const
+
+export const LINK_PROVIDERS = ["github", "linear", "jira", "web"] as const
+
+export const LINK_KINDS = [
+  "issue",
+  "pull_request",
+  "commit",
+  "repository",
+  "project",
+  "document",
+  "design",
+  "discussion",
+  "external",
+] as const
+
+export const LINK_RELATIONS = [
+  "references",
+  "implemented_by",
+  "fixes",
+  "reported_by",
+  "spec",
+  "design",
+  "review",
+  "deployment",
+  "blocked_by",
+] as const
+
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/
+
+/** One precise problem found in a task document. `path` is JSON-pointer-ish. */
+export type TodoIssue = ContentIssue
+
+/** The source document after validation; tasks keep their raw shapes. */
+export type TodoFile = {
+  $schema?: string
+  id?: string
+  tasks: Array<Record<string, unknown>>
+  title?: string
+  version?: number
+}
+
+export type ParsedTodo =
+  { ok: true; document: TodoFile } | { ok: false; issues: TodoIssue[] }
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value)
+}
+
+function nonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0
+}
+
+/** Compact summary for nav badges and error headers. */
+export function todoIssueSummary(issues: TodoIssue[]): string {
+  return issueSummary(issues, "todo.json")
+}
+
+/**
+ * Validate an already-parsed JSON value. Returns every problem found; an
+ * empty array means the document is structurally valid. Enums below mirror
+ * the published schema (`https://raggle.co/schemas/tasks.json`) and the
+ * client decoder in `./ui` (this plugin's vendored todo UI).
+ */
+export function validateTodoFile(value: unknown): TodoIssue[] {
+  if (!isRecord(value)) {
+    return [{ path: "#", message: "todo.json must contain a JSON object" }]
+  }
+
+  const issues: TodoIssue[] = []
+
+  if (
+    value.version !== undefined &&
+    value.version !== 1 &&
+    value.version !== 2
+  ) {
+    issues.push({
+      path: "version",
+      message: `must be 1 or 2; got ${JSON.stringify(value.version)}`,
+    })
+  }
+
+  if (value.$schema !== undefined && !nonEmptyString(value.$schema)) {
+    issues.push({ path: "$schema", message: "must be a non-empty string" })
+  }
+
+  if (value.id !== undefined && !nonEmptyString(value.id)) {
+    issues.push({ path: "id", message: "must be a non-empty string" })
+  }
+
+  if (value.title !== undefined && !nonEmptyString(value.title)) {
+    issues.push({ path: "title", message: "must be a non-empty string" })
+  }
+
+  if (!Array.isArray(value.tasks)) {
+    issues.push({ path: "tasks", message: "must be an array of tasks" })
+    return issues
+  }
+
+  const ids = new Set<string>()
+  const keys = new Set<string>()
+  value.tasks.forEach((task, index) => {
+    validateTask(task, `tasks[${index}]`, issues, ids, keys)
+  })
+
+  // Cross-task integrity: relation targets must point at a known task id.
+  value.tasks.forEach((task, index) => {
+    if (!isRecord(task) || !Array.isArray(task.relations)) return
+    task.relations.forEach((relation, relIndex) => {
+      if (!isRecord(relation)) return
+      const target = relation.targetTaskId
+      if (typeof target === "string" && !ids.has(target)) {
+        issues.push({
+          path: `tasks[${index}].relations[${relIndex}].targetTaskId`,
+          message: `references unknown task id ${JSON.stringify(target)}`,
+        })
+      }
+    })
+  })
+
+  return issues
+}
+
+function validateTask(
+  task: unknown,
+  path: string,
+  issues: TodoIssue[],
+  ids: Set<string>,
+  keys: Set<string>,
+) {
+  if (!isRecord(task)) {
+    issues.push({ path, message: "must be a task object" })
+    return
+  }
+
+  if (!nonEmptyString(task.name)) {
+    issues.push({
+      path: `${path}.name`,
+      message: "required; a task needs a non-empty name",
+    })
+  }
+
+  if (task.id !== undefined) {
+    if (!nonEmptyString(task.id)) {
+      issues.push({ path: `${path}.id`, message: "must be a non-empty string" })
+    } else if (ids.has(task.id)) {
+      issues.push({
+        path: `${path}.id`,
+        message: `duplicate task id ${JSON.stringify(task.id)}`,
+      })
+    } else {
+      ids.add(task.id)
+    }
+  }
+
+  if (task.key !== undefined) {
+    if (!nonEmptyString(task.key)) {
+      issues.push({
+        path: `${path}.key`,
+        message: "must be a non-empty string",
+      })
+    } else if (keys.has(task.key)) {
+      issues.push({
+        path: `${path}.key`,
+        message: `duplicate task key ${JSON.stringify(task.key)}`,
+      })
+    } else {
+      keys.add(task.key)
+    }
+  }
+
+  if (task.type !== undefined && !inEnum(task.type, TASK_TYPES)) {
+    issues.push({
+      path: `${path}.type`,
+      message: `must be one of ${TASK_TYPES.join(", ")}; got ${JSON.stringify(task.type)}`,
+    })
+  }
+
+  if (task.status !== undefined && !inEnum(task.status, TASK_STATUSES)) {
+    issues.push({
+      path: `${path}.status`,
+      message: `must be one of ${TASK_STATUSES.join(", ")}; got ${JSON.stringify(task.status)}`,
+    })
+  }
+
+  if (task.done !== undefined && typeof task.done !== "boolean") {
+    issues.push({ path: `${path}.done`, message: "must be a boolean" })
+  }
+
+  if (task.priority !== undefined && task.priority !== null) {
+    const priority = task.priority
+    if (
+      typeof priority !== "number" ||
+      !Number.isInteger(priority) ||
+      priority < 1 ||
+      priority > 5
+    ) {
+      issues.push({
+        path: `${path}.priority`,
+        message: "must be an integer between 1 and 5",
+      })
+    }
+  }
+
+  if (
+    task.deadline !== undefined &&
+    task.deadline !== null &&
+    (typeof task.deadline !== "string" || !DATE_PATTERN.test(task.deadline))
+  ) {
+    issues.push({
+      path: `${path}.deadline`,
+      message: "must be an ISO date (YYYY-MM-DD)",
+    })
+  }
+
+  for (const section of ["acceptanceCriteria", "steps"]) {
+    const items = task[section]
+    if (items === undefined) continue
+    if (!Array.isArray(items)) {
+      issues.push({
+        path: `${path}.${section}`,
+        message: "must be an array of check items",
+      })
+      continue
+    }
+    items.forEach((item, index) => {
+      validateCheckItem(item, `${path}.${section}[${index}]`, issues)
+    })
+  }
+
+  if (task.links !== undefined) {
+    if (!Array.isArray(task.links)) {
+      issues.push({
+        path: `${path}.links`,
+        message: "must be an array of links",
+      })
+    } else {
+      task.links.forEach((link, index) => {
+        validateLink(link, `${path}.links[${index}]`, issues)
+      })
+    }
+  }
+
+  if (task.notes !== undefined) {
+    if (!Array.isArray(task.notes)) {
+      issues.push({
+        path: `${path}.notes`,
+        message: "must be an array of note references",
+      })
+    } else {
+      task.notes.forEach((note, index) => {
+        validateNoteRef(note, `${path}.notes[${index}]`, issues)
+      })
+    }
+  }
+}
+
+const UNSAFE_NOTE_REFERENCE = /^(?:\/|\\\\|[a-z][a-z0-9+.-]*:|~)/i
+
+/**
+ * One `notes` entry: an https URL, or a folder-relative note path with an
+ * optional `#section` heading (for example "notes/spec.md#Plan").
+ */
+function validateNoteRef(note: unknown, path: string, issues: TodoIssue[]) {
+  if (!nonEmptyString(note)) {
+    issues.push({ path, message: "must be a non-empty string" })
+    return
+  }
+  if (/^https?:\/\//i.test(note)) {
+    let url: URL
+    try {
+      url = new URL(note)
+    } catch {
+      issues.push({ path, message: "is not a valid absolute URL" })
+      return
+    }
+    if (url.username || url.password) {
+      issues.push({ path, message: "must not contain embedded credentials" })
+      return
+    }
+    const isLocalhost =
+      url.hostname === "localhost" ||
+      url.hostname === "127.0.0.1" ||
+      url.hostname === "::1"
+    if (
+      url.protocol !== "https:" &&
+      !(url.protocol === "http:" && isLocalhost)
+    ) {
+      issues.push({
+        path,
+        message: "must use https, except localhost development links",
+      })
+    }
+    return
+  }
+  if (UNSAFE_NOTE_REFERENCE.test(note) || note.split(/[\\/]/).includes("..")) {
+    issues.push({
+      path,
+      message: "must be a folder-relative path (or an https URL)",
+    })
+  }
+}
+
+function validateCheckItem(item: unknown, path: string, issues: TodoIssue[]) {
+  if (!isRecord(item)) {
+    issues.push({
+      path,
+      message: "must be an object with id, text and done",
+    })
+    return
+  }
+  if (!nonEmptyString(item.id)) {
+    issues.push({ path: `${path}.id`, message: "required non-empty string" })
+  }
+  if (!nonEmptyString(item.text)) {
+    issues.push({ path: `${path}.text`, message: "required non-empty string" })
+  }
+  if (typeof item.done !== "boolean") {
+    issues.push({ path: `${path}.done`, message: "required boolean" })
+  }
+}
+
+function validateLink(link: unknown, path: string, issues: TodoIssue[]) {
+  if (!isRecord(link)) {
+    issues.push({ path, message: "must be a link object" })
+    return
+  }
+  for (const field of ["id", "provider", "kind", "relation", "url"]) {
+    if (!nonEmptyString(link[field])) {
+      issues.push({
+        path: `${path}.${field}`,
+        message: "required non-empty string",
+      })
+    }
+  }
+  if (link.provider !== undefined && !inEnum(link.provider, LINK_PROVIDERS)) {
+    issues.push({
+      path: `${path}.provider`,
+      message: `must be one of ${LINK_PROVIDERS.join(", ")}; got ${JSON.stringify(link.provider)}`,
+    })
+  }
+  if (link.kind !== undefined && !inEnum(link.kind, LINK_KINDS)) {
+    issues.push({
+      path: `${path}.kind`,
+      message: `must be one of ${LINK_KINDS.join(", ")}; got ${JSON.stringify(link.kind)}`,
+    })
+  }
+  if (link.relation !== undefined && !inEnum(link.relation, LINK_RELATIONS)) {
+    issues.push({
+      path: `${path}.relation`,
+      message: `must be one of ${LINK_RELATIONS.join(", ")}; got ${JSON.stringify(link.relation)}`,
+    })
+  }
+
+  const urlValue = link.url
+  if (typeof urlValue === "string") {
+    let url: URL
+    try {
+      url = new URL(urlValue)
+    } catch {
+      issues.push({
+        path: `${path}.url`,
+        message: "is not a valid absolute URL",
+      })
+      return
+    }
+    if (url.username || url.password) {
+      issues.push({
+        path: `${path}.url`,
+        message: "must not contain embedded credentials",
+      })
+    }
+    const isLocalhost =
+      url.hostname === "localhost" ||
+      url.hostname === "127.0.0.1" ||
+      url.hostname === "::1"
+    if (
+      url.protocol !== "https:" &&
+      !(url.protocol === "http:" && isLocalhost)
+    ) {
+      issues.push({
+        path: `${path}.url`,
+        message: "must use https, except localhost development links",
+      })
+    }
+    if (link.provider === "github" && url.hostname !== "github.com") {
+      issues.push({
+        path: `${path}.url`,
+        message: "github links must use github.com",
+      })
+    }
+    if (
+      link.provider === "linear" &&
+      url.hostname !== "linear.app" &&
+      !url.hostname.endsWith(".linear.app")
+    ) {
+      issues.push({
+        path: `${path}.url`,
+        message: "linear links must use linear.app",
+      })
+    }
+    if (
+      link.provider === "jira" &&
+      !url.hostname.endsWith(".atlassian.net") &&
+      url.hostname !== "jira.atlassian.com"
+    ) {
+      issues.push({
+        path: `${path}.url`,
+        message: "jira links must use an Atlassian Jira host",
+      })
+    }
+  }
+}
+
+function inEnum(value: unknown, allowed: readonly string[]) {
+  return allowed.includes(String(value))
+}
+
+/**
+ * Advisory checks that do not invalidate the file. Today there is one: a
+ * task with no `notes` entries warns, because todos are meant to be
+ * accompanied by notes — link a note file or an https reference. Paths use
+ * the same `tasks[i]` convention as `validateTodoFile` issues, relative to
+ * the file the task lives in.
+ */
+export function todoFileWarnings(value: unknown): TodoIssue[] {
+  if (!isRecord(value) || !Array.isArray(value.tasks)) return []
+  return value.tasks.flatMap((task, index) =>
+    isRecord(task) &&
+    Array.isArray(task.notes) &&
+    task.notes.some((note) => nonEmptyString(note))
+      ? []
+      : [
+          {
+            message:
+              "no notes; link the accompanying note file or https reference",
+            path: `tasks[${index}].notes`,
+            severity: "warning" as const,
+          },
+        ],
+  )
+}
+
+/**
+ * Parse a `todo.json` source string into a validated document. Never throws:
+ * invalid JSON and structural mistakes come back as issues with paths, so the
+ * caller can render "what is wrong and where" directly.
+ */
+export function parseTodoSource(source: string): ParsedTodo {
+  return parseJsonSource<TodoFile>(source, validateTodoFile)
+}
+
+/**
+ * Starter `todo.json` for `kennel init`: a valid v2 document with one sample
+ * task showing the common fields. The folder name becomes the project title.
+ */
+export function starterTodoSource(folder: string): string {
+  const title = folder.trim().split(/[\\/]/).filter(Boolean).at(-1) ?? "Tasks"
+  return `${JSON.stringify(
+    {
+      $schema: "https://raggle.co/schemas/tasks.json",
+      version: 2,
+      id: "todo",
+      title,
+      people: [],
+      projects: [],
+      cycles: [],
+      milestones: [],
+      components: [],
+      areas: [],
+      integrations: [],
+      customFields: [],
+      automations: [],
+      tasks: [
+        {
+          id: "todo:0",
+          key: "TODO-1",
+          index: 0,
+          rank: "0001",
+          name: "First task",
+          description: "Describe what needs to happen.",
+          type: "task",
+          status: "todo",
+          done: false,
+          priority: 3,
+          deadline: null,
+          assigneeIds: [],
+          acceptanceCriteria: [
+            { id: "ac-1", text: "Acceptance check", done: false },
+          ],
+        },
+      ],
+    },
+    null,
+    2,
+  )}\n`
+}

package/kernel/plugins/tasks/src/data/task-id.ts

@@ -0,0 +1,56 @@
+import { folderPathId } from "@raggle-ai/folder-plugin/client"
+
+/**
+ * Tasks from several `todo.json` sources merge into one workspace list, and
+ * file-local ids such as `todo:1` repeat across sources. Task addresses
+ * therefore qualify the task id with its owning folder:
+ *
+ *   `<folderPathId(source folder)>@<task id|key>`
+ *
+ * `folderPathId` is the viewer's stable base64url folder id, so the address
+ * stays one URL-safe path segment and survives the single-segment
+ * `/folder/<id>/views/tasks/<subpath>` route. A bare `<taskId|key>` remains
+ * valid as a legacy address and resolves to the first matching source (the
+ * previous behavior), but every address the plugin builds is qualified.
+ */
+
+const QUALIFIER = "@"
+
+/** Base64url output of `folderPathId`; a task id ref must look like one. */
+const REF_PATTERN = /^[A-Za-z0-9_-]+$/
+
+/**
+ * Qualified task address for a task inside `sourceFolder`, or undefined when
+ * the task has neither id nor key (or the source folder is unknown).
+ */
+export function qualifiedTaskId(
+  sourceFolder: unknown,
+  task: { id?: unknown; key?: unknown },
+): string | undefined {
+  if (typeof sourceFolder !== "string" || !sourceFolder) return undefined
+  const target =
+    typeof task.id === "string" && task.id.trim()
+      ? task.id.trim()
+      : typeof task.key === "string" && task.key.trim()
+        ? task.key.trim()
+        : undefined
+  if (!target) return undefined
+  return `${folderPathId(sourceFolder)}${QUALIFIER}${target}`
+}
+
+/** Splits a qualified address; undefined for a plain task id/key string. */
+export function parseQualifiedTaskId(
+  value: string,
+): { id: string; ref: string } | undefined {
+  const at = value.indexOf(QUALIFIER)
+  if (at < 1) return undefined
+  const ref = value.slice(0, at)
+  const id = value.slice(at + 1)
+  if (!id || !REF_PATTERN.test(ref)) return undefined
+  return { id, ref }
+}
+
+/** True when `ref` is the view-stable id of `sourceFolder`. */
+export function refMatchesFolder(ref: string, sourceFolder: unknown): boolean {
+  return typeof sourceFolder === "string" && folderPathId(sourceFolder) === ref
+}