kennel 0.2.3 → 0.2.5

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

@@ -1,544 +0,0 @@
-/**
- * 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

@@ -1,56 +0,0 @@
-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
-}