@adecore/plan 0.0.1 → 0.17.0-beta.1

package/src/text.ts

@@ -0,0 +1,159 @@
+import type { Plan, PlanItem, PlanStep, PlanStepState } from './protocol.ts';
+import { effectiveChecks, isParentStep, leafSteps, planProgress, stepState, type PlanProgress } from './tree.ts';
+
+export const PLAN_STATE_MARKERS: Record<PlanStepState, string> = {
+    open: '[ ]',
+    active: '[~]',
+    done: '[x]',
+    failed: '[!]',
+    skipped: '[-]',
+    blocked: '[?]',
+    warning: '[w]',
+    info: '[i]'
+};
+
+export const PLAN_LEGEND = '[ ] open, [~] active, [x] done, [!] failed, [-] skipped, [?] blocked, [w] warning, [i] info';
+
+export interface PlanTextOptions {
+    /* The chat's other plans, named on the second line. */
+    others?: readonly Plan[];
+    /* How `at` reads; the default is the local hour and minute. */
+    formatTime?: (at: string) => string;
+}
+
+function localTime(at: string): string {
+    const date = new Date(at);
+    if (Number.isNaN(date.getTime())) {
+        return '';
+    }
+    return `${String(date.getHours()).padStart(2, '0')}:${String(date.getMinutes()).padStart(2, '0')}`;
+}
+
+function oneLine(text: string): string {
+    return text.replace(/\s*\n\s*/g, ' ');
+}
+
+function descriptionLines(description: string | undefined, indent: string): string[] {
+    return description ? [`${indent}${oneLine(description)}`] : [];
+}
+
+function counter(progress: PlanProgress): string {
+    return `${progress.finished}/${progress.total}`;
+}
+
+export function progressText(plan: Pick<Plan, 'meta' | 'items'>): string {
+    const progress = planProgress(plan.items);
+    const extra = (count: number, label: string): string[] => (count > 0 ? [`${count} ${label}`] : []);
+    const warnings = progress.warning === 1 ? 'warning' : 'warnings';
+    if (plan.meta.kind === 'test') {
+        return [
+            `${progress.finished} of ${progress.total} run`,
+            `${progress.done} passed`,
+            ...extra(progress.warning, warnings),
+            ...extra(progress.info, 'info'),
+            ...extra(progress.failed, 'failed'),
+            ...extra(progress.skipped, 'skipped'),
+            ...extra(progress.blocked, 'blocked')
+        ].join(', ');
+    }
+    // In a steps plan a warning or info is still done; the extras say which of the done steps to read.
+    return [
+        `${progress.done + progress.warning + progress.info} of ${progress.total} done`,
+        ...extra(progress.warning, `with ${progress.warning === 1 ? 'a warning' : 'warnings'}`),
+        ...extra(progress.info, 'with info'),
+        ...extra(progress.failed, 'failed'),
+        ...extra(progress.skipped, 'skipped'),
+        ...extra(progress.blocked, 'blocked')
+    ].join(', ');
+}
+
+function sentences(parts: string[]): string {
+    return parts.map((part, index) => (index < parts.length - 1 && !/[.!?]$/.test(part) ? `${part}.` : part)).join(' ');
+}
+
+/*
+ * The compact text `plan read` prints for an agent: one line per item with its id in brackets, so
+ * the ids survive a compacted conversation, and a step's or a section's description on the line
+ * under it, the way the Markdown of a plan has it. The markers are `PLAN_LEGEND`.
+ */
+export function renderPlanText(plan: Plan, options: PlanTextOptions = {}): string {
+    const formatTime = options.formatTime ?? localTime;
+    const lines = [`Plan "${plan.meta.title}" (${plan.id}, ${plan.meta.kind}, rev ${plan.rev}): ${progressText(plan)}`];
+    const second: string[] = [];
+    if (plan.meta.summary) {
+        second.push(`Summary: ${oneLine(plan.meta.summary)}`);
+    }
+    if (plan.meta.status) {
+        second.push(`Status: ${plan.meta.status}`);
+    }
+    const active = leafSteps(plan.items).filter((step) => step.state === 'active');
+    if (active.length > 0) {
+        second.push(`Now: ${active.map((step) => `"${step.title}" [${step.id}]`).join(', ')}`);
+    }
+    if (options.others && options.others.length > 0) {
+        const others = options.others.map((other) => `${other.id} "${other.meta.title}" (${other.meta.kind}, ${counter(planProgress(other.items))})`);
+        second.push(`Also in this chat: ${others.join(', ')}`);
+    }
+    if (second.length > 0) {
+        lines.push(sentences(second));
+    }
+
+    const stepLine = (step: PlanStep, number: string, indent: string): void => {
+        let line = `${indent}${PLAN_STATE_MARKERS[stepState(step)]} ${number} ${step.title} [${step.id}]`;
+        if (isParentStep(step)) {
+            line += ` ${counter(planProgress(step.steps!))}`;
+        } else {
+            const notes: string[] = [];
+            const checks = effectiveChecks(plan, step);
+            if (checks !== 'anyone') {
+                notes.push(`${checks}-only`);
+            } else if (step.unlocked) {
+                notes.push('unlocked');
+            }
+            if (step.by === 'person' && step.state !== undefined) {
+                const time = step.at ? formatTime(step.at) : '';
+                notes.push(time ? `set by a person ${time}` : 'set by a person');
+            }
+            if (notes.length > 0) {
+                line += ` ${notes.join(', ')}`;
+            }
+        }
+        if (step.note) {
+            line += `: "${oneLine(step.note)}"`;
+        }
+        lines.push(line, ...descriptionLines(step.description, `${indent}  `));
+        step.steps?.forEach((child, index) => stepLine(child, `${number}.${index + 1}`, `${indent}  `));
+    };
+    const itemLines = (items: readonly PlanItem[], indent: string): void => {
+        let number = 0;
+        for (const item of items) {
+            if (item.type === 'text') {
+                lines.push(`${indent}${item.title} [${item.id}]${item.description ? `: ${oneLine(item.description)}` : ''}`);
+            } else if (item.type === 'step') {
+                number++;
+                stepLine(item, String(number), indent);
+            }
+        }
+    };
+
+    let loose: PlanItem[] = [];
+    const flushLoose = (): void => {
+        if (loose.length > 0) {
+            lines.push('');
+            itemLines(loose, '');
+            loose = [];
+        }
+    };
+    for (const item of plan.items) {
+        if (item.type !== 'section') {
+            loose.push(item);
+            continue;
+        }
+        flushLoose();
+        const progress = planProgress(item.items);
+        lines.push('', `## ${item.title} [${item.id}]${progress.total > 0 ? ` ${counter(progress)}` : ''}`, ...descriptionLines(item.description, '  '));
+        itemLines(item.items, '  ');
+    }
+    flushLoose();
+    return lines.join('\n');
+}

package/src/tree.ts

@@ -0,0 +1,206 @@
+import { PLAN_LIMITS, type Plan, type PlanChecks, type PlanItem, type PlanSection, type PlanStep, type PlanStepState } from './protocol.ts';
+
+export type PlanRefusalCode =
+    | 'person-only'
+    | 'set-by-person'
+    | 'unlocked-by-person'
+    | 'step-locked'
+    | 'plan-missing-item'
+    | 'plan-not-found'
+    | 'op-not-allowed'
+    | 'plan-not-a-step'
+    | 'plan-parent-state'
+    | 'plan-bad-position'
+    | 'duplicate-id'
+    | 'plan-too-deep'
+    | 'plan-too-large'
+    | 'plan-invalid'
+    | 'too-many-plans';
+
+export interface PlanRefusal {
+    ok: false;
+    code: PlanRefusalCode;
+    message: string;
+}
+
+export function refuse(code: PlanRefusalCode, message: string): PlanRefusal {
+    return { ok: false, code, message };
+}
+
+/* Where an item stands: the array that holds it, so an operation can splice it, and the step or section around it. */
+export interface PlanLocation {
+    item: PlanItem;
+    siblings: PlanItem[];
+    index: number;
+    parent: PlanSection | PlanStep | null;
+    /* How deep a step is among steps, 1 at the top or in a section; 0 for a section or a text block. */
+    depth: number;
+}
+
+function childrenOf(item: PlanItem): PlanItem[] {
+    if (item.type === 'section') {
+        return item.items;
+    }
+    if (item.type === 'step') {
+        return item.steps ?? [];
+    }
+    return [];
+}
+
+export function locateItem(plan: Pick<Plan, 'items'>, id: string): PlanLocation | null {
+    const search = (siblings: PlanItem[], parent: PlanSection | PlanStep | null, depth: number): PlanLocation | null => {
+        for (let index = 0; index < siblings.length; index++) {
+            const item = siblings[index]!;
+            const itemDepth = item.type === 'step' ? depth + 1 : 0;
+            if (item.id === id) {
+                return { item, siblings, index, parent, depth: itemDepth };
+            }
+            const found = search(childrenOf(item), item.type === 'text' ? null : item, item.type === 'step' ? itemDepth : depth);
+            if (found) {
+                return found;
+            }
+        }
+        return null;
+    };
+    return search(plan.items, null, 0);
+}
+
+export function findItem(plan: Pick<Plan, 'items'>, id: string): PlanItem | null {
+    return locateItem(plan, id)?.item ?? null;
+}
+
+/* Every item in document order, parents before their children. */
+export function allItems(items: readonly PlanItem[]): PlanItem[] {
+    return items.flatMap((item) => [item, ...allItems(childrenOf(item))]);
+}
+
+export function allSteps(items: readonly PlanItem[]): PlanStep[] {
+    return allItems(items).filter((item): item is PlanStep => item.type === 'step');
+}
+
+export function isParentStep(step: PlanStep): boolean {
+    return (step.steps?.length ?? 0) > 0;
+}
+
+/* Unlocked wins over everything: a person lifted the lock and no one puts it back. */
+export function effectiveChecks(plan: Pick<Plan, 'meta'>, step: PlanStep): PlanChecks {
+    return step.unlocked ? 'anyone' : (step.checks ?? plan.meta.checks);
+}
+
+export function isFinishedOutcome(state: PlanStepState): boolean {
+    return state === 'done' || state === 'skipped' || state === 'warning' || state === 'info';
+}
+
+/* A warning bubbles up so a parent does not look clean; info is only worth reading on the step itself. */
+export function deriveState(states: readonly PlanStepState[]): PlanStepState {
+    if (states.includes('failed')) {
+        return 'failed';
+    }
+    if (states.includes('blocked')) {
+        return 'blocked';
+    }
+    if (states.every(isFinishedOutcome)) {
+        return states.includes('warning') ? 'warning' : 'done';
+    }
+    // A skipped step did not run, so next to open steps alone it moves nothing forward.
+    if (states.some((state) => state === 'active' || state === 'done' || state === 'warning' || state === 'info')) {
+        return 'active';
+    }
+    return 'open';
+}
+
+/* A leaf's own state, or for a parent the state its children add up to. */
+export function stepState(step: PlanStep): PlanStepState {
+    return isParentStep(step) ? deriveState(step.steps!.map(stepState)) : (step.state ?? 'open');
+}
+
+export interface PlanProgress {
+    /* Leaf steps only: a parent is its children. */
+    total: number;
+    open: number;
+    active: number;
+    done: number;
+    failed: number;
+    skipped: number;
+    blocked: number;
+    warning: number;
+    info: number;
+    /* Steps with an outcome: done, failed, skipped, warning or info. */
+    finished: number;
+}
+
+export function planProgress(items: readonly PlanItem[]): PlanProgress {
+    const progress: PlanProgress = { total: 0, open: 0, active: 0, done: 0, failed: 0, skipped: 0, blocked: 0, warning: 0, info: 0, finished: 0 };
+    for (const step of leafSteps(items)) {
+        const state = step.state ?? 'open';
+        progress.total++;
+        progress[state]++;
+        if (state === 'failed' || isFinishedOutcome(state)) {
+            progress.finished++;
+        }
+    }
+    return progress;
+}
+
+/*
+ * The steps that carry a state, in document order. A step with steps under it has no state of its
+ * own: it is a heading, and what it says about progress is whatever its leaves say.
+ */
+export function leafSteps(items: readonly PlanItem[]): PlanStep[] {
+    return allSteps(items).filter((step) => !isParentStep(step));
+}
+
+export function activeStepIds(plan: Pick<Plan, 'items'>): string[] {
+    return leafSteps(plan.items)
+        .filter((step) => step.state === 'active')
+        .map((step) => step.id);
+}
+
+/* True when the item, or any step under it, carries a state a person set. */
+export function holdsPersonState(item: PlanItem): boolean {
+    return allItems([item]).some((entry) => entry.type === 'step' && !isParentStep(entry) && entry.by === 'person' && entry.state !== undefined);
+}
+
+/* The rules of a plan the schema cannot say, because they need the whole tree. */
+export function structureProblem(plan: Pick<Plan, 'items'>): PlanRefusal | null {
+    const ids = new Set<string>();
+    let count = 0;
+    const walk = (items: readonly PlanItem[], depth: number, inside: 'top' | 'section' | 'step'): PlanRefusal | null => {
+        for (const item of items) {
+            count++;
+            if (count > PLAN_LIMITS.items) {
+                return refuse('plan-too-large', `A plan holds at most ${PLAN_LIMITS.items} items`);
+            }
+            if (ids.has(item.id)) {
+                return refuse('duplicate-id', `Two items share the id "${item.id}"`);
+            }
+            ids.add(item.id);
+            if (item.type === 'section' && inside !== 'top') {
+                return refuse('plan-bad-position', `The section "${item.id}" is not at the top of the plan; sections do not nest`);
+            }
+            if (item.type === 'text' && inside === 'step') {
+                return refuse('plan-bad-position', `The text block "${item.id}" is under a step; a step only holds steps`);
+            }
+            if (item.type === 'step') {
+                if (depth + 1 > PLAN_LIMITS.depth) {
+                    return refuse('plan-too-deep', `The step "${item.id}" is ${depth + 1} levels deep; steps go at most ${PLAN_LIMITS.depth} levels deep`);
+                }
+                if (isParentStep(item) && (item.state !== undefined || item.by !== undefined || item.at !== undefined)) {
+                    return refuse('plan-parent-state', `The step "${item.id}" has sub-steps, so its state follows from them`);
+                }
+                const problem = walk(item.steps ?? [], depth + 1, 'step');
+                if (problem) {
+                    return problem;
+                }
+            }
+            if (item.type === 'section') {
+                const problem = walk(item.items, depth, 'section');
+                if (problem) {
+                    return problem;
+                }
+            }
+        }
+        return null;
+    };
+    return walk(plan.items, 0, 'top');
+}