@astrosheep/keiyaku 4.5.5 → 4.5.7

package/build/src/task/compose-language.js

@@ -0,0 +1,328 @@
+import { serializeTaskDocument } from "./document.js";
+import { allocateLocalId, deriveLocalStem, formatTaskId, parseTaskId, sameNamespace } from "./identity.js";
+import { parseTaskComposition } from "./compose-parser.js";
+import { advanceTaskTimestamp } from "./operations.js";
+export function taskCompositionNamespaceHeader(markdown) {
+    const parsed = parseTaskComposition(markdown);
+    return {
+        specified: parsed.namespaceSpecified,
+        ...(parsed.namespace === undefined ? {} : { namespace: parsed.namespace }),
+    };
+}
+function diagnostic(line, reason, token) {
+    return { line, reason, token };
+}
+function occupied(board, namespace) {
+    return new Set([...board.tasks.values()].flatMap((task) => {
+        const coordinate = parseTaskId(task.id);
+        return sameNamespace(coordinate.namespace, namespace) ? [coordinate.localId] : [];
+    }));
+}
+function createdTask(id, title, at, actor) {
+    return {
+        id,
+        title,
+        state: "open",
+        priority: 2,
+        needs: [],
+        parent: null,
+        supersedes: [],
+        relates: [],
+        note: "",
+        ...(actor === undefined ? {} : { createdBy: actor }),
+        createdAt: at,
+        updatedAt: at,
+        body: "",
+    };
+}
+function aliasFor(node) {
+    return node.assignments.find((item) => item.field === "as");
+}
+function allocateNodes(input, diagnostics) {
+    const ids = occupied(input.board, input.namespace);
+    const allocations = new Map();
+    for (const node of input.parsed.nodes) {
+        if (node.kind !== "new")
+            continue;
+        try {
+            const localId = allocateLocalId(deriveLocalStem(node.title), ids);
+            ids.add(localId);
+            const id = formatTaskId({ namespace: input.namespace, localId });
+            allocations.set(node.index, createdTask(id, node.title, input.at, input.actor));
+        }
+        catch (error) {
+            diagnostics.push(diagnostic(node.line, error instanceof Error ? error.message : String(error), node.title));
+        }
+    }
+    return allocations;
+}
+function collectAliases(nodes, allocations, diagnostics) {
+    const aliases = new Map();
+    for (const node of nodes) {
+        const declarations = node.assignments.filter((item) => item.field === "as");
+        for (const duplicate of declarations.slice(1)) {
+            diagnostics.push(diagnostic(duplicate.line, "alias is assigned more than once", duplicate.token));
+        }
+        const declaration = declarations[0];
+        if (declaration === undefined)
+            continue;
+        if (node.kind !== "new") {
+            diagnostics.push(diagnostic(declaration.line, "only a new task may declare an alias", declaration.token));
+            continue;
+        }
+        if (declaration.operator !== "=" || !/^[a-z0-9-]+$/u.test(declaration.value)) {
+            diagnostics.push(diagnostic(declaration.line, "alias must use as = [a-z0-9-]+", declaration.token));
+            continue;
+        }
+        if (aliases.has(declaration.value)) {
+            diagnostics.push(diagnostic(declaration.line, "alias must be unique in the composition", declaration.value));
+            continue;
+        }
+        const allocated = allocations.get(node.index);
+        if (allocated !== undefined)
+            aliases.set(declaration.value, allocated.id);
+    }
+    return aliases;
+}
+function resolveReference(raw, line, board, aliases, diagnostics) {
+    if (raw.startsWith("^")) {
+        const alias = raw.slice(1);
+        const resolved = aliases.get(alias);
+        if (resolved === undefined)
+            diagnostics.push(diagnostic(line, "new-task alias is not declared", raw));
+        return resolved;
+    }
+    if (!raw.startsWith("@task/")) {
+        diagnostics.push(diagnostic(line, "reference must be @task/... or ^alias", raw));
+        return undefined;
+    }
+    try {
+        const id = raw.slice(1);
+        parseTaskId(id);
+        if (!board.tasks.has(id))
+            diagnostics.push(diagnostic(line, "@ reference must name a pre-existing task", raw));
+        return board.tasks.has(id) ? id : undefined;
+    }
+    catch (error) {
+        diagnostics.push(diagnostic(line, error instanceof Error ? error.message : String(error), raw));
+        return undefined;
+    }
+}
+function referenceList(assignment, board, aliases, diagnostics) {
+    if (assignment.value === "")
+        return [];
+    const raw = assignment.value.split(",").map((item) => item.trim());
+    if (raw.some((item) => item.length === 0)) {
+        diagnostics.push(diagnostic(assignment.line, "reference list contains an empty item", assignment.token));
+        return undefined;
+    }
+    const resolved = raw.map((item) => resolveReference(item, assignment.line, board, aliases, diagnostics));
+    if (resolved.some((item) => item === undefined))
+        return undefined;
+    const ids = resolved;
+    if (new Set(ids).size !== ids.length) {
+        diagnostics.push(diagnostic(assignment.line, "reference list contains a duplicate", assignment.token));
+        return undefined;
+    }
+    return ids;
+}
+function patchRelation(current, assignment, values, diagnostics) {
+    if (assignment.operator === "=")
+        return values;
+    if (assignment.operator === "+=")
+        return [...current, ...values.filter((id) => !current.includes(id))];
+    const missing = values.filter((id) => !current.includes(id));
+    for (const id of missing)
+        diagnostics.push(diagnostic(assignment.line, "cannot remove an absent relation", `@${id}`));
+    return missing.length === 0 ? current.filter((id) => !values.includes(id)) : current;
+}
+function applyAssignments(node, base, board, aliases, diagnostics) {
+    let next = base;
+    const scalar = new Set();
+    for (const assignment of node.assignments) {
+        if (assignment.field === "as")
+            continue;
+        if (assignment.field === "pri" || assignment.field === "parent") {
+            if (scalar.has(assignment.field)) {
+                diagnostics.push(diagnostic(assignment.line, `${assignment.field} is assigned more than once`, assignment.token));
+            }
+            scalar.add(assignment.field);
+        }
+        if (assignment.field === "pri") {
+            if (assignment.operator !== "=" || !/^[0-3]$/u.test(assignment.value)) {
+                diagnostics.push(diagnostic(assignment.line, "pri must use = with a value from 0 through 3", assignment.token));
+            }
+            else
+                next = { ...next, priority: Number(assignment.value) };
+            continue;
+        }
+        if (assignment.field === "parent") {
+            if (assignment.operator !== "=") {
+                diagnostics.push(diagnostic(assignment.line, "parent accepts only =", assignment.token));
+            }
+            else if (assignment.value === "")
+                next = { ...next, parent: null };
+            else {
+                const id = resolveReference(assignment.value.trim(), assignment.line, board, aliases, diagnostics);
+                if (id !== undefined)
+                    next = { ...next, parent: id };
+            }
+            continue;
+        }
+        const values = referenceList(assignment, board, aliases, diagnostics);
+        if (values === undefined)
+            continue;
+        if (assignment.operator !== "=" && values.length === 0) {
+            diagnostics.push(diagnostic(assignment.line, `${assignment.operator} requires at least one reference`, assignment.token));
+            continue;
+        }
+        next = { ...next, [assignment.field]: patchRelation(next[assignment.field], assignment, values, diagnostics) };
+    }
+    if (node.body !== undefined)
+        next = { ...next, body: node.body.value };
+    for (const field of ["needs", "supersedes", "relates"]) {
+        if (next[field].includes(next.id))
+            diagnostics.push(diagnostic(node.line, `${field} cannot reference the task itself`, next.id));
+    }
+    if (next.parent === next.id)
+        diagnostics.push(diagnostic(node.line, "parent cannot reference the task itself", next.id));
+    return next;
+}
+function relationTargets(document, relation) {
+    return relation === "needs" ? document.needs : document.parent === null ? [] : [document.parent];
+}
+function pathExists(board, start, goal, relation) {
+    const seen = new Set();
+    const pending = [start];
+    while (pending.length > 0) {
+        const id = pending.pop();
+        if (id === goal)
+            return true;
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        const task = board.tasks.get(id);
+        if (task !== undefined)
+            pending.push(...relationTargets(task, relation));
+    }
+    return false;
+}
+function diagnoseIntroducedCycles(after, tasks, diagnostics) {
+    for (const task of tasks) {
+        for (const relation of ["needs", "parent"]) {
+            const old = task.before === null ? [] : relationTargets(task.before, relation);
+            for (const target of relationTargets(task.after, relation)) {
+                if (!old.includes(target) && pathExists(after, target, task.after.id, relation)) {
+                    diagnostics.push(diagnostic(task.line, `${relation} edge creates a cycle`, `${task.after.id} -> ${target}`));
+                }
+            }
+        }
+    }
+}
+function changed(task) {
+    return (task.before === null ||
+        !Buffer.from(serializeTaskDocument(task.before)).equals(Buffer.from(serializeTaskDocument(task.after))));
+}
+function stableAdmissionOrder(tasks, diagnostics) {
+    const candidates = tasks.filter(changed);
+    const byId = new Map(candidates.map((task) => [task.after.id, task]));
+    const dependencies = new Map(candidates.map((task) => [task.after.id, new Set()]));
+    for (const task of candidates) {
+        const targets = [...task.after.needs, ...(task.after.parent === null ? [] : [task.after.parent])];
+        for (const target of targets) {
+            const plannedTarget = byId.get(target);
+            if (plannedTarget?.before === null)
+                dependencies.get(task.after.id).add(target);
+        }
+    }
+    const remaining = new Set(candidates.map((task) => task.after.id));
+    const ordered = [];
+    while (remaining.size > 0) {
+        const ready = candidates.find((task) => remaining.has(task.after.id) && [...dependencies.get(task.after.id)].every((id) => !remaining.has(id)));
+        if (ready === undefined) {
+            const first = candidates.find((task) => remaining.has(task.after.id));
+            diagnostics.push(diagnostic(first.line, "needs and parent references create an admission cycle", first.after.id));
+            return [];
+        }
+        remaining.delete(ready.after.id);
+        ordered.push(ready);
+    }
+    return ordered;
+}
+function bodyPreview(node, id) {
+    if (node.body?.kind !== "replace")
+        return null;
+    const lines = node.body.value.split(/\r\n|\n|\r/u);
+    return {
+        taskId: id,
+        bytes: Buffer.byteLength(node.body.value),
+        firstLine: lines[0] ?? "",
+        lastLine: lines.at(-1) ?? "",
+    };
+}
+export function planTaskComposition(input) {
+    const parsed = parseTaskComposition(input.markdown);
+    const diagnostics = [...parsed.diagnostics];
+    const namespace = parsed.namespace ?? input.namespace;
+    const allocationInput = {
+        parsed,
+        board: input.board,
+        namespace,
+        at: input.at,
+        ...(input.actor === undefined ? {} : { actor: input.actor }),
+    };
+    const allocations = allocateNodes(allocationInput, diagnostics);
+    const aliases = collectAliases(parsed.nodes, allocations, diagnostics);
+    const addressed = new Set();
+    const tasks = [];
+    for (const node of parsed.nodes) {
+        const before = node.kind === "new" ? null : (input.board.tasks.get(node.id) ?? null);
+        const base = node.kind === "new" ? allocations.get(node.index) : before;
+        if (base === null || base === undefined) {
+            diagnostics.push(diagnostic(node.line, "existing task does not exist before composition", `@${node.id}`));
+            continue;
+        }
+        if (addressed.has(base.id)) {
+            diagnostics.push(diagnostic(node.line, "task is addressed more than once", base.id));
+            continue;
+        }
+        addressed.add(base.id);
+        let after = applyAssignments(node, base, input.board, aliases, diagnostics);
+        if (before !== null && changed({ index: node.index, line: node.line, kind: node.kind, before, after })) {
+            after = { ...after, updatedAt: advanceTaskTimestamp(before.updatedAt, input.at) };
+        }
+        tasks.push({
+            index: node.index,
+            line: node.line,
+            kind: node.kind,
+            ...(aliasFor(node) === undefined ? {} : { alias: aliasFor(node).value }),
+            before,
+            after,
+        });
+    }
+    const post = new Map(input.board.tasks);
+    for (const task of tasks)
+        post.set(task.after.id, task.after);
+    diagnoseIntroducedCycles({ tasks: post }, tasks, diagnostics);
+    const ordered = stableAdmissionOrder(tasks, diagnostics);
+    if (diagnostics.length > 0)
+        return { kind: "refused", diagnostics };
+    const aliasBindings = [...aliases].map(([alias, taskId]) => ({ alias, taskId }));
+    const bodies = parsed.nodes.flatMap((node) => {
+        const task = tasks.find((candidate) => candidate.index === node.index);
+        if (task === undefined)
+            return [];
+        const preview = bodyPreview(node, task.after.id);
+        return preview === null ? [] : [preview];
+    });
+    return {
+        kind: "planned",
+        plan: {
+            namespace,
+            aliases: aliasBindings,
+            admissionOrder: ordered.map((task) => task.after.id),
+            bodies,
+            tasks: ordered,
+        },
+    };
+}

package/build/src/task/compose-parser.d.ts

@@ -0,0 +1,32 @@
+import { type TaskId } from "./identity.js";
+import type { TaskCompositionDiagnostic } from "./operations.js";
+export type RelationField = "needs" | "supersedes" | "relates";
+export type Assignment = Readonly<{
+    field: "as" | "parent" | "pri" | RelationField;
+    operator: "=" | "+=" | "-=";
+    value: string;
+    line: number;
+    token: string;
+}>;
+export type BodyAssignment = Readonly<{
+    kind: "clear" | "replace";
+    value: string;
+    line: number;
+    token: string;
+}>;
+export type ParsedNode = Readonly<{
+    index: number;
+    line: number;
+    kind: "new" | "existing";
+    title?: string;
+    id?: TaskId;
+    assignments: readonly Assignment[];
+    body?: BodyAssignment;
+}>;
+export type ParsedComposition = Readonly<{
+    namespace?: readonly string[];
+    namespaceSpecified: boolean;
+    nodes: readonly ParsedNode[];
+    diagnostics: readonly TaskCompositionDiagnostic[];
+}>;
+export declare function parseTaskComposition(source: string): ParsedComposition;

package/build/src/task/compose-parser.js

@@ -0,0 +1,180 @@
+import { parseTaskId } from "./identity.js";
+function diagnostic(line, reason, token) {
+    return { line, reason, token };
+}
+function sourceLines(source) {
+    const lines = [];
+    let start = 0;
+    let number = 1;
+    while (start < source.length) {
+        let cursor = start;
+        while (cursor < source.length && source[cursor] !== "\n" && source[cursor] !== "\r")
+            cursor += 1;
+        let end = cursor;
+        if (source[cursor] === "\r" && source[cursor + 1] === "\n")
+            end += 2;
+        else if (cursor < source.length)
+            end += 1;
+        lines.push({ number, start, end, text: source.slice(start, cursor) });
+        start = end;
+        number += 1;
+    }
+    if (source.length === 0 || source.endsWith("\n") || source.endsWith("\r")) {
+        lines.push({ number, start: source.length, end: source.length, text: "" });
+    }
+    return lines;
+}
+function withoutFenceSeparator(value) {
+    if (value.endsWith("\r\n"))
+        return value.slice(0, -2);
+    if (value.endsWith("\n") || value.endsWith("\r"))
+        return value.slice(0, -1);
+    return value;
+}
+function parseNamespace(value) {
+    if (value === "/")
+        return [];
+    if (value === "")
+        throw new Error("empty compose namespace; use ns=/ for root");
+    return parseTaskId(`task/${value}/placeholder`).namespace;
+}
+function parseAssignment(text, line) {
+    const matched = /^(as|parent|pri|needs|supersedes|relates)\s*(=|\+=|-=)\s*(.*)$/u.exec(text);
+    if (matched === null)
+        return null;
+    return {
+        field: matched[1],
+        operator: matched[2],
+        value: matched[3],
+        line,
+        token: text,
+    };
+}
+function parseNode(text, line, index) {
+    if (text.startsWith("+ ")) {
+        const title = text.slice(2);
+        return title.trim().length === 0
+            ? diagnostic(line, "new task title must be nonblank", text)
+            : { index, line, kind: "new", title, assignments: [] };
+    }
+    if (!text.startsWith("@task/"))
+        return diagnostic(line, "node must begin with + or @task/", text);
+    try {
+        const id = text.slice(1);
+        parseTaskId(id);
+        return { index, line, kind: "existing", id, assignments: [] };
+    }
+    catch (error) {
+        return diagnostic(line, error instanceof Error ? error.message : String(error), text);
+    }
+}
+function withAssignment(node, assignment) {
+    return { ...node, assignments: [...node.assignments, assignment] };
+}
+function withBody(node, body) {
+    return { ...node, body };
+}
+function replaceNode(nodes, node) {
+    nodes[node.index] = node;
+}
+function parseBodyAssignment(input, diagnostics) {
+    const fence = /^body\s+<<(.+)$/u.exec(input.text);
+    if (fence !== null) {
+        const token = fence[1];
+        if (!/^[A-Z][A-Z0-9_]{2,31}$/u.test(token)) {
+            diagnostics.push(diagnostic(input.line.number, "body token must match [A-Z][A-Z0-9_]* with length 3..32", token));
+            return { handled: true };
+        }
+        const close = input.lines.findIndex((candidate, candidateIndex) => candidateIndex > input.index && candidate.text === token);
+        if (close < 0) {
+            diagnostics.push(diagnostic(input.line.number, "body fence is not closed", token));
+            return { handled: true, stop: true };
+        }
+        const body = withoutFenceSeparator(input.source.slice(input.line.end, input.lines[close].start));
+        if (input.current.body !== undefined) {
+            diagnostics.push(diagnostic(input.line.number, "body is assigned more than once", input.text));
+            return { handled: true, close };
+        }
+        return {
+            handled: true,
+            node: withBody(input.current, { kind: "replace", value: body, line: input.line.number, token }),
+            close,
+        };
+    }
+    if (!/^body\s*=\s*$/u.test(input.text))
+        return { handled: false };
+    if (input.current.body !== undefined) {
+        diagnostics.push(diagnostic(input.line.number, "body is assigned more than once", input.text));
+        return { handled: true };
+    }
+    return {
+        handled: true,
+        node: withBody(input.current, { kind: "clear", value: "", line: input.line.number, token: input.text }),
+    };
+}
+export function parseTaskComposition(source) {
+    const lines = sourceLines(source);
+    const diagnostics = [];
+    const nodes = [];
+    let namespace;
+    let current;
+    let sawNode = false;
+    let sawNamespace = false;
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        const text = line.text.trimStart();
+        if (text.trim().length === 0)
+            continue;
+        if (text.startsWith("ns=")) {
+            if (sawNode || sawNamespace)
+                diagnostics.push(diagnostic(line.number, "namespace must be the first nonblank line", text));
+            else {
+                try {
+                    namespace = parseNamespace(text.slice(3));
+                }
+                catch (error) {
+                    diagnostics.push(diagnostic(line.number, error instanceof Error ? error.message : String(error), text));
+                }
+            }
+            sawNamespace = true;
+            continue;
+        }
+        if (text.startsWith("+ ") || text.startsWith("@task/")) {
+            const parsed = parseNode(text, line.number, nodes.length);
+            if ("reason" in parsed) {
+                diagnostics.push(parsed);
+                current = undefined;
+            }
+            else {
+                nodes.push(parsed);
+                current = parsed;
+            }
+            sawNode = true;
+            continue;
+        }
+        if (current === undefined) {
+            diagnostics.push(diagnostic(line.number, "property must follow a task node", text));
+            continue;
+        }
+        const body = parseBodyAssignment({ text, line, index, lines, source, current }, diagnostics);
+        if (body.handled) {
+            if (body.node !== undefined) {
+                current = body.node;
+                replaceNode(nodes, current);
+            }
+            if (body.close !== undefined)
+                index = body.close;
+            if (body.stop === true)
+                break;
+            continue;
+        }
+        const assignment = parseAssignment(text, line.number);
+        if (assignment === null)
+            diagnostics.push(diagnostic(line.number, "unknown compose property", text));
+        else {
+            current = withAssignment(current, assignment);
+            replaceNode(nodes, current);
+        }
+    }
+    return { ...(namespace === undefined ? {} : { namespace }), namespaceSpecified: sawNamespace, nodes, diagnostics };
+}

package/build/src/task/compose.d.ts

@@ -1,18 +1,32 @@
-import { type TaskId } from "./identity.js";
 import type { WorldRoot } from "../world.js";
-import { type TaskRefusal, type TaskRetry } from "./operations.js";
-type TaskDocumentChange = Readonly<{
+import { type TaskCompositionAlias, type TaskCompositionBodyPreview } from "./compose-language.js";
+import type { TaskId } from "./identity.js";
+import type { TaskRefusal, TaskRetry } from "./operations.js";
+export type { TaskCompositionAlias, TaskCompositionBodyPreview } from "./compose-language.js";
+export { taskCompositionNamespaceHeader } from "./compose-language.js";
+export type TaskDocumentChange = Readonly<{
     taskId: TaskId;
     kind: "created" | "updated";
     documentDiff: string;
 }>;
+export type TaskCompositionFacts = Readonly<{
+    aliases: readonly TaskCompositionAlias[];
+    admissionOrder: readonly TaskId[];
+}>;
 export type TaskCompositionResult = Readonly<{
+    kind: "planned";
+    aliases: readonly TaskCompositionAlias[];
+    admissionOrder: readonly TaskId[];
+    bodies: readonly TaskCompositionBodyPreview[];
+}> | Readonly<{
     kind: "accepted";
     documentChanges: readonly TaskDocumentChange[];
-}> | Readonly<{
+} & TaskCompositionFacts> | Readonly<{
     kind: "refused";
-    refusal: TaskRefusal;
-}> | Readonly<{
+    refusal: Extract<TaskRefusal, {
+        kind: "invalid-composition";
+    }>;
+}> | (Readonly<{
     kind: "incomplete";
     documentChanges: readonly TaskDocumentChange[];
     stopped: TaskRefusal | Readonly<{
@@ -20,6 +34,12 @@ export type TaskCompositionResult = Readonly<{
         reason: TaskRetry;
     }>;
     draft: string;
-}>;
-export declare function composeTasks(world: WorldRoot, markdown: string, signal?: AbortSignal, actor?: string, defaultNamespace?: readonly string[]): Promise<TaskCompositionResult>;
-export {};
+}> & TaskCompositionFacts);
+export declare function composeTasks(input: Readonly<{
+    world: WorldRoot;
+    markdown: string;
+    signal?: AbortSignal;
+    actor?: string;
+    defaultNamespace?: readonly string[];
+    planOnly?: boolean;
+}>): Promise<TaskCompositionResult>;