@pathmx/completion 0.5.0

package/targets.ts

@@ -0,0 +1,240 @@
+import type { MarkdownTask, PathMXDataSchema } from "@pathmx/core"
+import { COMPLETION_KEY, type CompletionRef } from "./model.ts"
+
+type CompletionNode = Readonly<{
+  id: string
+  data: Readonly<Record<string, unknown>>
+}>
+
+type CompletionBlock = CompletionNode &
+  Readonly<{
+    body: string
+    tasks: readonly MarkdownTask[]
+  }>
+
+type CompletionSource = CompletionNode &
+  Readonly<{
+    blocks: readonly CompletionBlock[]
+  }>
+
+type ManualCompletion = Readonly<{
+  target: true
+  label?: string
+  optional: boolean
+}>
+
+type TargetBase = Readonly<{
+  ref: CompletionRef
+  label: string
+  optional: boolean
+}>
+
+export type CompletionTarget =
+  | (TargetBase & Readonly<{ type: "source" }>)
+  | (TargetBase & Readonly<{ type: "block"; block: string }>)
+  | (TargetBase & Readonly<{ type: "task"; block: string; line: number }>)
+
+type TargetCandidate = Readonly<{
+  target: CompletionTarget
+  valid: boolean
+}>
+
+function issue(message: string, path?: string) {
+  return {
+    issues: [{ message, ...(path ? { path: [path] } : {}) }],
+  }
+}
+
+function parseManualCompletion(value: unknown) {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) {
+    return issue("Expected an object")
+  }
+  const input = value as Record<string, unknown>
+  const extra = Object.keys(input).find(
+    (key) => key !== "target" && key !== "label" && key !== "optional",
+  )
+  if (extra) return issue("Unknown completion field", extra)
+  if (input.target !== true) return issue("Expected true", "target")
+  if (
+    input.label !== undefined &&
+    (typeof input.label !== "string" || !input.label.trim())
+  ) {
+    return issue("Expected a non-empty string", "label")
+  }
+  if (input.optional !== undefined && typeof input.optional !== "boolean") {
+    return issue("Expected a boolean", "optional")
+  }
+  return {
+    value: Object.freeze({
+      target: true as const,
+      ...(typeof input.label === "string" ? { label: input.label.trim() } : {}),
+      optional: input.optional === true,
+    }),
+  }
+}
+
+const CompletionPropInputJson = Object.freeze({
+  type: "object",
+  additionalProperties: false,
+  required: ["target"],
+  properties: {
+    target: { const: true },
+    label: { type: "string", minLength: 1 },
+    optional: { type: "boolean" },
+  },
+})
+
+const CompletionPropOutputJson = Object.freeze({
+  ...CompletionPropInputJson,
+  required: ["target", "optional"],
+})
+
+export const CompletionPropSchema: PathMXDataSchema<unknown, ManualCompletion> =
+  {
+    "~standard": {
+      version: 1,
+      vendor: "pathmx",
+      validate: parseManualCompletion,
+      jsonSchema: {
+        input: () => CompletionPropInputJson,
+        output: () => CompletionPropOutputJson,
+      },
+    },
+  }
+
+function manualCompletion(node: CompletionNode) {
+  if (!Object.hasOwn(node.data, "completion")) return
+  const result = parseManualCompletion(node.data.completion)
+  return "value" in result ? result.value : undefined
+}
+
+function targetRef(source: CompletionSource, key: string) {
+  return Object.freeze({ source: source.id, key })
+}
+
+function validKey(key: string) {
+  return key.length <= 256 && COMPLETION_KEY.test(key)
+}
+
+function authoredBlockId(block: CompletionBlock) {
+  return typeof block.data.id === "string" && block.data.id.trim() === block.id
+}
+
+function sourceTarget(source: CompletionSource): TargetCandidate[] {
+  const completion = manualCompletion(source)
+  if (!completion) return []
+  return [
+    {
+      target: Object.freeze({
+        type: "source",
+        ref: targetRef(source, "source/self"),
+        label: completion.label ?? "Complete this source",
+        optional: completion.optional,
+      }),
+      valid: true,
+    },
+  ]
+}
+
+function blockTarget(
+  source: CompletionSource,
+  block: CompletionBlock,
+  issues: string[],
+): TargetCandidate[] {
+  const completion = manualCompletion(block)
+  if (!completion) return []
+  const key = `block/${block.id}`
+  const authored = authoredBlockId(block)
+  if (!authored) {
+    issues.push(
+      `Completion Block ${source.id}#${block.id} must author a stable id.`,
+    )
+  }
+  if (!validKey(key)) {
+    issues.push(`Invalid Completion target key ${key} on ${source.id}.`)
+  }
+  return [
+    {
+      target: Object.freeze({
+        type: "block",
+        ref: targetRef(source, key),
+        label: completion.label ?? "Complete this section",
+        optional: completion.optional,
+        block: block.id,
+      }),
+      valid: authored && validKey(key),
+    },
+  ]
+}
+
+function taskTarget(
+  source: CompletionSource,
+  block: CompletionBlock,
+  task: MarkdownTask,
+  issues: string[],
+): TargetCandidate[] {
+  if (!task.id) return []
+  const key = `task/${task.id}`
+  const label = task.text.trim()
+  if (task.checked) {
+    issues.push(
+      `Completion task ${key} on ${source.id}:${task.line} must be unchecked; [x] is shared document state.`,
+    )
+  }
+  if (!label) {
+    issues.push(
+      `Completion task ${key} on ${source.id}:${task.line} needs text.`,
+    )
+  }
+  if (!validKey(key)) {
+    issues.push(`Invalid Completion target key ${key} on ${source.id}.`)
+  }
+  return [
+    {
+      target: Object.freeze({
+        type: "task",
+        ref: targetRef(source, key),
+        label,
+        optional: task.tags.includes("optional"),
+        block: block.id,
+        line: task.line,
+      }),
+      valid: !task.checked && Boolean(label) && validKey(key),
+    },
+  ]
+}
+
+export function inspectCompletionTargets(source: CompletionSource) {
+  const issues: string[] = []
+  const candidates = [
+    ...sourceTarget(source),
+    ...source.blocks.flatMap((block) => [
+      ...blockTarget(source, block, issues),
+      ...(block.body.includes("{#")
+        ? block.tasks.flatMap((task) => taskTarget(source, block, task, issues))
+        : []),
+    ]),
+  ]
+  const counts = new Map<string, number>()
+  for (const { target } of candidates) {
+    counts.set(target.ref.key, (counts.get(target.ref.key) ?? 0) + 1)
+  }
+  for (const [key, count] of counts) {
+    if (count > 1) {
+      issues.push(`Duplicate Completion target ${key} on ${source.id}.`)
+    }
+  }
+  return Object.freeze({
+    targets: Object.freeze(
+      candidates.flatMap(({ target, valid }) =>
+        valid && counts.get(target.ref.key) === 1 ? [target] : [],
+      ),
+    ),
+    issues: Object.freeze(issues),
+  })
+}
+
+/** Project valid manual and Markdown-task targets in authored order. */
+export function completionTargets(source: CompletionSource) {
+  return inspectCompletionTargets(source).targets
+}