@pathmx/completion 0.5.0

package/index.ts

@@ -0,0 +1,251 @@
+import {
+  defineAction,
+  type AppContext,
+  type PathMXDataSchema,
+  type Plugin,
+  type Source,
+} from "@pathmx/core"
+import type { CompletionOutcome } from "./model.ts"
+import { COMPLETION_KEY } from "./model.ts"
+import { createCompletionState } from "./state.ts"
+import {
+  CompletionPropSchema,
+  completionTargets,
+  inspectCompletionTargets,
+} from "./targets.ts"
+import {
+  completionDeclarations,
+  inspectConfiguredCompletionDeclarations,
+  type CompletionContributor,
+  type CompletionEvidence,
+} from "./contributors.ts"
+import { completionReader } from "./evidence.ts"
+
+export type {
+  CompletionFact,
+  CompletionOutcome,
+  CompletionReader,
+  CompletionRef,
+  CompletionStatus,
+  CompletionSummary,
+} from "./model.ts"
+export { completionTargets, type CompletionTarget } from "./targets.ts"
+export type {
+  CompletionContributor,
+  CompletionEvidence,
+} from "./contributors.ts"
+
+type CompletionChange = CompletionOutcome | "pending"
+type CompletionInput = Readonly<{
+  source: string
+  key: string
+  outcome: CompletionChange
+}>
+type CompletionOptions = Readonly<{
+  contributors?: readonly CompletionContributor[]
+  evidence?: readonly CompletionEvidence[]
+}>
+
+function issue(message: string, path?: string) {
+  return {
+    issues: [{ message, ...(path ? { path: [path] } : {}) }],
+  }
+}
+
+const CompletionInputJson = Object.freeze({
+  type: "object",
+  additionalProperties: false,
+  required: ["source", "key", "outcome"],
+  properties: {
+    source: { type: "string", pattern: "^/", maxLength: 2_048 },
+    key: { type: "string", pattern: COMPLETION_KEY.source, maxLength: 256 },
+    outcome: { enum: ["complete", "skipped", "pending"] },
+  },
+})
+
+const CompletionInput: PathMXDataSchema<unknown, CompletionInput> = {
+  "~standard": {
+    version: 1,
+    vendor: "pathmx",
+    validate(value) {
+      if (value == null || typeof value !== "object" || Array.isArray(value)) {
+        return issue("Expected an object")
+      }
+      const input = value as Record<string, unknown>
+      const source = input.source
+      if (
+        typeof source !== "string" ||
+        !source.startsWith("/") ||
+        source.length > 2_048
+      ) {
+        return issue("Expected a canonical Source id", "source")
+      }
+      const key = input.key
+      if (
+        typeof key !== "string" ||
+        !COMPLETION_KEY.test(key) ||
+        key.length > 256
+      ) {
+        return issue("Expected a provider-namespaced completion key", "key")
+      }
+      const outcome = input.outcome
+      if (
+        outcome !== "complete" &&
+        outcome !== "skipped" &&
+        outcome !== "pending"
+      ) {
+        return issue("Expected complete, skipped, or pending", "outcome")
+      }
+      return { value: { source, key, outcome } }
+    },
+    jsonSchema: {
+      input: () => CompletionInputJson,
+      output: () => CompletionInputJson,
+    },
+  },
+}
+
+function completionPlugin(
+  state: ReturnType<typeof createCompletionState>,
+  contributors: readonly CompletionContributor[],
+  evidence: readonly CompletionEvidence[],
+): Plugin {
+  const setCompletion = defineAction({
+    title: "Update completion",
+    description: "Set or clear one Actor-owned completion outcome.",
+    input: CompletionInput,
+    affordance: ({ target }) =>
+      completionDeclarations(target, contributors, evidence).length
+        ? { boundInput: { source: target.id } }
+        : false,
+    authorize: ({ target }) =>
+      target != null || "Completion requires a target Source.",
+    async execute(input, { actor, target, tx, yaml }) {
+      if (!target || input.source !== target.id) {
+        throw new Error("Completion Source does not match the target Source.")
+      }
+      const declaration = completionDeclarations(
+        target,
+        contributors,
+        evidence,
+      ).find(({ key }) => key === input.key)
+      if (!declaration) {
+        throw new Error(
+          `Completion target ${input.key} is not declared on ${target.id}.`,
+        )
+      }
+      if (input.outcome === "skipped" && !declaration.optional) {
+        throw new Error(
+          `Completion target ${input.key} is not optional and cannot be skipped.`,
+        )
+      }
+      return state.write(
+        tx,
+        actor,
+        { source: input.source, key: input.key },
+        input.outcome === "pending" ? undefined : input.outcome,
+        yaml,
+      )
+    },
+  })
+
+  return {
+    id: "completion",
+    name: "CompletionPlugin",
+    schema: {
+      props: { completion: CompletionPropSchema },
+      actions: { set: setCompletion },
+    },
+    lint(report, app) {
+      lintCompletion(report, app, state.records(), contributors, evidence)
+    },
+    index(source, app) {
+      state.index(source, app)
+    },
+    unindex(sourcePath) {
+      state.unindex(sourcePath)
+    },
+  }
+}
+
+function lintCompletion(
+  report: (source: Source, message: string) => void,
+  app: AppContext,
+  states: ReturnType<ReturnType<typeof createCompletionState>["records"]>,
+  contributors: readonly CompletionContributor[],
+  evidence: readonly CompletionEvidence[],
+) {
+  for (const source of app.sources.all()) {
+    const content = inspectCompletionTargets(source)
+    const issues = [
+      ...content.issues,
+      ...inspectConfiguredCompletionDeclarations(
+        source,
+        contributors,
+        evidence,
+        content.targets,
+      ).issues,
+    ]
+    for (const message of issues) {
+      report(source, message)
+    }
+  }
+  for (const state of states) {
+    const origin = app.sources.get(state.originId)
+    if (!origin) {
+      report(
+        state.source,
+        `Completion State ${state.source.id} targets missing Source ${state.originId}.`,
+      )
+      continue
+    }
+    const configured = inspectConfiguredCompletionDeclarations(
+      origin,
+      contributors,
+      evidence,
+    )
+    const targets = new Map(
+      configured.manual.map((target) => [target.key, target]),
+    )
+    const derived = new Set(configured.derived.map(({ key }) => key))
+    for (const [key, fact] of Object.entries(state.items)) {
+      const target = targets.get(key)
+      if (derived.has(key)) {
+        report(
+          state.source,
+          `Completion fact ${key} duplicates provider-owned evidence on ${origin.id}.`,
+        )
+      } else if (!target) {
+        report(
+          state.source,
+          `Completion fact ${key} does not resolve on ${origin.id}.`,
+        )
+      } else if (fact.outcome === "skipped" && !target.optional) {
+        report(
+          state.source,
+          `Completion fact ${key} is skipped but its target is not optional.`,
+        )
+      }
+    }
+  }
+}
+
+/** A standalone Completion plugin instance for ordinary preset composition. */
+export function CompletionPlugin(options: CompletionOptions = {}): Plugin {
+  return completionPlugin(
+    createCompletionState(),
+    Object.freeze([...(options.contributors ?? [])]),
+    Object.freeze([...(options.evidence ?? [])]),
+  )
+}
+
+/** Compose Completion with its immutable reader for domain and UI plugins. */
+export function createCompletionPlugin(options: CompletionOptions = {}) {
+  const state = createCompletionState()
+  const contributors = Object.freeze([...(options.contributors ?? [])])
+  const evidence = Object.freeze([...(options.evidence ?? [])])
+  return Object.freeze({
+    reader: completionReader(state.reader, evidence),
+    plugin: () => completionPlugin(state, contributors, evidence),
+  })
+}

package/model.ts

@@ -0,0 +1,50 @@
+export type CompletionRef = Readonly<{
+  source: string
+  key: string
+}>
+
+export type CompletionOutcome = "complete" | "skipped"
+export type CompletionFact = Readonly<{
+  outcome: CompletionOutcome
+  occurredAt: string
+}>
+export type CompletionStatus = "not-started" | "in-progress" | "complete"
+
+export type CompletionSummary = Readonly<{
+  status: CompletionStatus
+  complete: number
+  skipped: number
+  total: number
+}>
+
+export type CompletionReader = Readonly<{
+  read(actorId: string, ref: CompletionRef): CompletionFact | undefined
+  summary(actorId: string, refs: readonly CompletionRef[]): CompletionSummary
+}>
+
+export function completionSummary<T>(
+  refs: readonly T[],
+  read: (ref: T) => CompletionFact | undefined,
+): CompletionSummary {
+  let complete = 0
+  let skipped = 0
+  for (const ref of refs) {
+    const value = read(ref)?.outcome
+    if (value === "complete") complete++
+    if (value === "skipped") skipped++
+  }
+  return Object.freeze({
+    status:
+      refs.length > 0 && complete + skipped === refs.length
+        ? "complete"
+        : complete + skipped > 0
+          ? "in-progress"
+          : "not-started",
+    complete,
+    skipped,
+    total: refs.length,
+  })
+}
+
+/** Provider namespace plus one stable provider-local leaf id. */
+export const COMPLETION_KEY = /^[a-z][a-z0-9-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@pathmx/completion",
+  "description": "Actor-relative completion tracking for PathMX.",
+  "version": "0.5.0",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pathmx/pathmx-beta.git",
+    "directory": "pathmx/completion"
+  },
+  "homepage": "https://github.com/pathmx/pathmx-beta#readme",
+  "bugs": "https://github.com/pathmx/pathmx-beta/issues",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "beta"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./react": "./react.tsx"
+  },
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "peerDependencies": {
+    "@pathmx/react": "*",
+    "@pathmx/core": "^0.5.0",
+    "react": ">=19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@pathmx/react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  }
+}

package/react.tsx

@@ -0,0 +1,116 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from "react"
+import { useAction } from "@pathmx/react"
+import {
+  completionSummary,
+  type CompletionFact,
+  type CompletionOutcome,
+  type CompletionSummary,
+} from "./model.ts"
+
+export type CompletionSnapshot = Readonly<
+  Record<string, CompletionFact | undefined>
+>
+
+type CompletionReactValue = Readonly<{
+  facts: CompletionSnapshot
+  setFact(key: string, fact: CompletionFact | undefined): void
+}>
+
+const CompletionContext = createContext<CompletionReactValue | undefined>(
+  undefined,
+)
+
+export function CompletionProvider(
+  props: Readonly<{
+    initial?: CompletionSnapshot
+    children: ReactNode
+  }>,
+) {
+  const [facts, setFacts] = useState<CompletionSnapshot>(props.initial ?? {})
+  useEffect(() => setFacts(props.initial ?? {}), [props.initial])
+  const setFact = useCallback(
+    (key: string, fact: CompletionFact | undefined) => {
+      setFacts((current) => Object.freeze({ ...current, [key]: fact }))
+    },
+    [],
+  )
+  const value = useMemo(() => ({ facts, setFact }), [facts, setFact])
+  return (
+    <CompletionContext.Provider value={value}>
+      {props.children}
+    </CompletionContext.Provider>
+  )
+}
+
+function useCompletionContext() {
+  const value = useContext(CompletionContext)
+  if (!value) {
+    throw new Error("Completion hooks must be used inside CompletionProvider.")
+  }
+  return value
+}
+
+function actionFact(value: unknown, outcome: CompletionOutcome) {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Completion Action returned an invalid fact.")
+  }
+  const fact = value as Record<string, unknown>
+  if (
+    fact.outcome !== outcome ||
+    typeof fact.occurredAt !== "string" ||
+    !Number.isFinite(Date.parse(fact.occurredAt))
+  ) {
+    throw new Error("Completion Action returned an invalid fact.")
+  }
+  return Object.freeze({ outcome, occurredAt: fact.occurredAt })
+}
+
+/** Read one current-Source Completion fact from a server-projected snapshot. */
+export function useCompletion(key: string) {
+  return useCompletionContext().facts[key]
+}
+
+/** Summarize current-Source keys without introducing a second status model. */
+export function useCompletionSummary(
+  keys: readonly string[],
+): CompletionSummary {
+  const { facts } = useCompletionContext()
+  return useMemo(
+    () => completionSummary(keys, (key) => facts[key]),
+    [facts, keys],
+  )
+}
+
+/** Invoke the canonical manual Completion Action and update local app state. */
+export function useCompletionAction(key: string) {
+  const { facts, setFact } = useCompletionContext()
+  const { action, invoke } = useAction("completion:set")
+  const [pending, setPending] = useState(false)
+  const set = useCallback(
+    async (outcome: CompletionOutcome | "pending") => {
+      setPending(true)
+      try {
+        const response = await invoke({ key, outcome })
+        const result = (await response.json()) as { output?: unknown }
+        setFact(
+          key,
+          outcome === "pending"
+            ? undefined
+            : actionFact(result.output, outcome),
+        )
+      } finally {
+        setPending(false)
+      }
+    },
+    [invoke, key, setFact],
+  )
+  return Object.freeze({ fact: facts[key], action, pending, set })
+}

package/state.ts

@@ -0,0 +1,220 @@
+import {
+  formatFrontmatter,
+  type AppContext,
+  type PathMXEnvironment,
+  type Source,
+  type SourceTransaction,
+  type UserActor,
+} from "@pathmx/core"
+import {
+  COMPLETION_KEY,
+  completionSummary,
+  type CompletionFact,
+  type CompletionOutcome,
+  type CompletionReader,
+  type CompletionRef,
+} from "./model.ts"
+
+type CompletionStateRecord = Readonly<{
+  actorId: string
+  originId: string
+  source: Source
+  items: Readonly<Record<string, CompletionFact>>
+}>
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value != null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined
+}
+
+function occurredAt(value: unknown) {
+  if (value instanceof Date && Number.isFinite(value.getTime())) {
+    return value.toISOString()
+  }
+  if (typeof value !== "string" || !value.trim()) return
+  const time = Date.parse(value)
+  return Number.isFinite(time) ? new Date(time).toISOString() : undefined
+}
+
+function invalidState(app: AppContext, source: Source, message: string): never {
+  return app.diagnostics.invalid(
+    source,
+    `Invalid Completion state in ${source.path}: ${message}`,
+  )
+}
+
+function stateItems(source: Source, app: AppContext) {
+  const rawItems = source.data.items
+  if (rawItems == null) return Object.freeze({})
+  if (typeof rawItems !== "object" || Array.isArray(rawItems)) {
+    invalidState(app, source, "items must be a map.")
+  }
+  const items: Array<[string, CompletionFact]> = []
+  for (const [key, value] of Object.entries(rawItems)) {
+    if (!COMPLETION_KEY.test(key) || key.length > 256) {
+      invalidState(app, source, `invalid item key ${key}.`)
+    }
+    const data = asRecord(value)
+    if (!data || (data.outcome !== "complete" && data.outcome !== "skipped")) {
+      invalidState(app, source, `${key}.outcome must be complete or skipped.`)
+    }
+    const timestamp = occurredAt(data.occurred_at)
+    if (!timestamp) {
+      invalidState(
+        app,
+        source,
+        `${key}.occurred_at must be an ISO 8601 timestamp.`,
+      )
+    }
+    const extra = Object.keys(data).find(
+      (name) => name !== "outcome" && name !== "occurred_at",
+    )
+    if (extra) {
+      invalidState(app, source, `${key}.${extra} is not supported.`)
+    }
+    items.push([
+      key,
+      Object.freeze({
+        outcome: data.outcome,
+        occurredAt: timestamp,
+      }),
+    ])
+  }
+  return Object.freeze(Object.fromEntries(items))
+}
+
+function stateRecord(
+  source: Source,
+  actorId: string | undefined,
+  app: AppContext,
+): CompletionStateRecord | undefined {
+  if (source.type !== "state" || source.data.plugin !== "completion") return
+  if (!actorId) {
+    invalidState(app, source, "state must be stored in an Actor Home.")
+  }
+  const originId =
+    typeof source.data.for === "string" ? source.data.for.trim() : ""
+  if (!originId.startsWith("/") || originId.length > 2_048) {
+    invalidState(app, source, "frontmatter for must be a canonical Source id.")
+  }
+  return Object.freeze({
+    actorId,
+    originId,
+    source,
+    items: stateItems(source, app),
+  })
+}
+
+function stateContent(
+  originId: string,
+  items: Readonly<Record<string, CompletionFact>>,
+  previous: CompletionStateRecord | undefined,
+  yaml: PathMXEnvironment["yaml"],
+) {
+  return `${formatFrontmatter(
+    {
+      ...previous?.source.data,
+      type: "state",
+      plugin: "completion",
+      for: originId,
+      items: Object.fromEntries(
+        Object.entries(items).map(([key, fact]) => [
+          key,
+          { outcome: fact.outcome, occurred_at: fact.occurredAt },
+        ]),
+      ),
+    },
+    yaml,
+  )}\n`
+}
+
+function stateId(actor: UserActor, originId: string) {
+  return `${actor.home}/completion${originId}.state`
+}
+
+export function createCompletionState() {
+  const bySourcePath = new Map<string, CompletionStateRecord>()
+  const byActorOrigin = new Map<string, CompletionStateRecord>()
+  const key = (actorId: string, originId: string) => `${actorId}\0${originId}`
+  const stateFor = (actorId: string, originId: string) =>
+    byActorOrigin.get(key(actorId, originId))
+
+  const reader: CompletionReader = Object.freeze({
+    read(actorId, ref) {
+      return stateFor(actorId, ref.source)?.items[ref.key]
+    },
+    summary(actorId, refs) {
+      return completionSummary(
+        refs,
+        (ref) => stateFor(actorId, ref.source)?.items[ref.key],
+      )
+    },
+  })
+
+  return Object.freeze({
+    reader,
+    records() {
+      return Object.freeze([...bySourcePath.values()])
+    },
+    index(source: Source, app: AppContext) {
+      const completion = stateRecord(
+        source,
+        app.actors.homeActorId(source.id),
+        app,
+      )
+      if (!completion) return
+      const recordKey = key(completion.actorId, completion.originId)
+      const existing = byActorOrigin.get(recordKey)
+      if (existing && existing.source.path !== source.path) {
+        invalidState(
+          app,
+          source,
+          `duplicate State for ${completion.actorId} and ${completion.originId}: ${existing.source.path} and ${source.path}.`,
+        )
+      }
+      bySourcePath.set(source.path, completion)
+      byActorOrigin.set(recordKey, completion)
+    },
+    unindex(sourcePath: string) {
+      const completion = bySourcePath.get(sourcePath)
+      if (!completion) return
+      bySourcePath.delete(sourcePath)
+      byActorOrigin.delete(key(completion.actorId, completion.originId))
+    },
+    async write(
+      tx: SourceTransaction,
+      actor: UserActor,
+      ref: CompletionRef,
+      outcome: CompletionOutcome | undefined,
+      yaml: PathMXEnvironment["yaml"],
+    ) {
+      const current = stateFor(actor.id, ref.source)
+      if (!current && outcome == null) return
+      const items = new Map(Object.entries(current?.items ?? {}))
+      let fact: CompletionFact | undefined
+      if (outcome) {
+        const previous = items.get(ref.key)
+        if (previous?.outcome === outcome) return previous
+        fact = Object.freeze({
+          outcome,
+          occurredAt: new Date().toISOString(),
+        })
+        items.set(ref.key, fact)
+      } else items.delete(ref.key)
+      if (!items.size) {
+        if (current) await tx.delete(current.source.id)
+        return
+      }
+      const content = stateContent(
+        ref.source,
+        Object.fromEntries(items),
+        current,
+        yaml,
+      )
+      if (current) await tx.update(current.source.id, content)
+      else await tx.create(stateId(actor, ref.source), content)
+      return fact
+    },
+  })
+}