@adecore/plan 0.23.1 → 0.24.1

package/dist/apply.js

@@ -3,9 +3,19 @@ import { z } from 'zod';
 import { canApply } from './permissions.js';
 import { allItems, allSteps, effectiveChecks, locateItem, missingItem, refuse, structureProblem } from './tree.js';
 const ID_ALPHABET = 'abcdefghijklmnopqrstuvwxyz0123456789';
+const ID_LENGTH = 6;
+/* 256 is no multiple of the alphabet, so a byte at or above this would favor its first characters. */
+const ID_BYTE_LIMIT = 256 - (256 % ID_ALPHABET.length);
 export function randomItemId() {
-    const bytes = crypto.getRandomValues(new Uint8Array(6));
-    return Array.from(bytes, (byte) => ID_ALPHABET[byte % ID_ALPHABET.length]).join('');
+    let id = '';
+    while (id.length < ID_LENGTH) {
+        for (const byte of crypto.getRandomValues(new Uint8Array(ID_LENGTH))) {
+            if (byte < ID_BYTE_LIMIT && id.length < ID_LENGTH) {
+                id += ID_ALPHABET[byte % ID_ALPHABET.length];
+            }
+        }
+    }
+    return id;
 }
 function issueMessage(error) {
     const issue = error.issues[0];
@@ -15,9 +25,10 @@ function issueMessage(error) {
     const path = issue.path.map((part) => (typeof part === 'number' ? `[${part}]` : `.${String(part)}`)).join('');
     return `${path ? `${path.replace(/^\./, '')}: ` : ''}${issue.message}`;
 }
+const MINT_ATTEMPTS = 1000;
 function idMinter(taken, mintId, minted) {
     return () => {
-        for (let attempt = 0; attempt < 1000; attempt++) {
+        for (let attempt = 0; attempt < MINT_ATTEMPTS; attempt++) {
             const id = mintId();
             if (!taken.has(id)) {
                 taken.add(id);
@@ -25,7 +36,7 @@ function idMinter(taken, mintId, minted) {
                 return id;
             }
         }
-        throw new Error('Could not mint a free plan item id');
+        return refuse('duplicate-id', `mintId gave no id the plan does not already have in ${MINT_ATTEMPTS} tries`);
     };
 }
 function setState(step, state, actor, now) {
@@ -160,6 +171,9 @@ function applyOne(plan, op, options, mint, dropped) {
         }
         case 'add': {
             const id = op.id ?? mint();
+            if (typeof id !== 'string') {
+                return id;
+            }
             if (op.id !== undefined && locateItem(plan, op.id)) {
                 return refuse('duplicate-id', `The plan already has an item "${op.id}"`);
             }
@@ -339,6 +353,18 @@ export function createPlan(draft, options) {
         }
     }
     const mint = idMinter(taken, options.mintId ?? randomItemId, minted);
+    // Minted up front so a refusal stops here; the tree below takes them in the same order, parents first.
+    const fresh = [];
+    for (const item of allDraftItems(source.items)) {
+        if (item.id === undefined) {
+            const id = mint();
+            if (typeof id !== 'string') {
+                return id;
+            }
+            fresh.push(id);
+        }
+    }
+    const nextId = () => fresh.shift();
     const described = (value) => {
         if (value.description === '') {
             delete value.description;
@@ -347,7 +373,7 @@ export function createPlan(draft, options) {
     };
     const toStep = (step) => {
         const { steps, state, note, ...rest } = step;
-        const result = described({ ...rest, id: step.id ?? mint() });
+        const result = described({ ...rest, id: step.id ?? nextId() });
         if (steps && steps.length > 0) {
             result.steps = steps.map(toStep);
         }
@@ -359,10 +385,10 @@ export function createPlan(draft, options) {
         }
         return result;
     };
-    const toText = (text) => described({ ...text, id: text.id ?? mint() });
+    const toText = (text) => described({ ...text, id: text.id ?? nextId() });
     const items = source.items.map((item) => {
         if (item.type === 'section') {
-            return described({ ...item, id: item.id ?? mint(), items: item.items.map((child) => (child.type === 'text' ? toText(child) : toStep(child))) });
+            return described({ ...item, id: item.id ?? nextId(), items: item.items.map((child) => (child.type === 'text' ? toText(child) : toStep(child))) });
         }
         return item.type === 'text' ? toText(item) : toStep(item);
     });

package/dist/index.d.ts

@@ -2,4 +2,4 @@ export { type PlanApplyOptions, type PlanApplied, randomItemId, applyPlanOps, va
 export { planToMarkdown, parsePlanMarkdown } from './markdown.ts';
 export { type PlanVerdict, canApply, canDeletePlan } from './permissions.ts';
 export { PLAN_STATE_MARKERS, PLAN_LEGEND, type PlanTextOptions, progressText, renderPlanText } from './text.ts';
-export { type PlanRefusalCode, type PlanRefusal, refuse, type PlanLocation, locateItem, findItem, allItems, allSteps, isParentStep, effectiveChecks, isFinishedOutcome, deriveState, stepState, type PlanProgress, planProgress, leafSteps, activeStepIds, holdsPersonState, structureProblem } from './tree.ts';
+export { type PlanRefusalCode, type PlanRefusal, refuse, findItem, allItems, allSteps, isParentStep, effectiveChecks, isFinishedOutcome, stepState, type PlanProgress, planProgress, leafSteps, activeStepIds } from './tree.ts';

package/dist/index.js

@@ -2,4 +2,4 @@ export { randomItemId, applyPlanOps, validatePlan, PlanDraftStepSchema, PlanDraf
 export { planToMarkdown, parsePlanMarkdown } from './markdown.js';
 export { canApply, canDeletePlan } from './permissions.js';
 export { PLAN_STATE_MARKERS, PLAN_LEGEND, progressText, renderPlanText } from './text.js';
-export { refuse, locateItem, findItem, allItems, allSteps, isParentStep, effectiveChecks, isFinishedOutcome, deriveState, stepState, planProgress, leafSteps, activeStepIds, holdsPersonState, structureProblem } from './tree.js';
+export { refuse, findItem, allItems, allSteps, isParentStep, effectiveChecks, isFinishedOutcome, stepState, planProgress, leafSteps, activeStepIds } from './tree.js';

package/dist/permissions.js

@@ -28,14 +28,20 @@ function mayState(plan, step, state, actor) {
     }
     return ALLOWED;
 }
-/* Adding under a leaf takes its state away, which may not happen to a state a person set. */
-function mayHoldChildren(plan, under) {
-    if (under === undefined) {
+/*
+ * Adding under a leaf takes its state away, which may not happen to a state a person set. Its state
+ * then follows from the sub-steps, so a step only a person checks takes only sub-steps a person checks.
+ */
+function mayHoldChildren(plan, under, after, added) {
+    const parent = under !== undefined ? locateItem(plan, under)?.item : after !== undefined ? locateItem(plan, after)?.parent : null;
+    if (parent?.type !== 'step') {
         return ALLOWED;
     }
-    const location = locateItem(plan, under);
-    if (location?.item.type === 'step' && !isParentStep(location.item) && holdsPersonState(location.item)) {
-        return refuse('set-by-person', `A person set "${under}" to ${location.item.state}; a sub-step would take that state away`);
+    if (!isParentStep(parent) && holdsPersonState(parent)) {
+        return refuse('set-by-person', `A person set "${parent.id}" to ${parent.state}; a sub-step would take that state away`);
+    }
+    if (effectiveChecks(plan, parent) === 'person' && added.some((checks) => checks !== 'person')) {
+        return refuse('person-only', `Only a person checks "${parent.id}", so a sub-step under it is one a person checks too`);
     }
     return ALLOWED;
 }
@@ -86,7 +92,7 @@ export function canApply(op, actor, plan) {
             return ALLOWED;
         }
         case 'add':
-            return mayHoldChildren(plan, op.under);
+            return mayHoldChildren(plan, op.under, op.after, op.type === 'step' ? [op.checks ?? plan.meta.checks] : []);
         case 'edit': {
             const location = locateItem(plan, op.id);
             if (!location) {
@@ -117,10 +123,11 @@ export function canApply(op, actor, plan) {
             return ALLOWED;
         }
         case 'move': {
-            if (!locateItem(plan, op.id)) {
+            const location = locateItem(plan, op.id);
+            if (!location) {
                 return missingItem(op.id);
             }
-            return mayHoldChildren(plan, op.under);
+            return mayHoldChildren(plan, op.under, op.after, allSteps([location.item]).map((step) => effectiveChecks(plan, step)));
         }
         case 'remove': {
             const location = locateItem(plan, op.id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/plan",
-  "version": "0.23.1",
+  "version": "0.24.1",
   "description": "Plan schemas, atomic tree operations, actor permissions and Markdown.",
   "license": "FSL-1.1-MIT",
   "author": "Bas Milius",
@@ -19,6 +19,7 @@
     "dist",
     "src",
     "!src/**/*.test.ts",
+    "!src/**/__snapshots__",
     "!src/fixtures"
   ],
   "exports": {

package/src/apply.ts

@@ -27,7 +27,7 @@ export interface PlanApplyOptions {
     actor: PlanActor;
     /* ISO time written into `at`; injected so a test never reads the clock. */
     now: string;
-    /* Mints an id for an item that comes without one; retried until it is not taken. */
+    /* Mints an id for an item that comes without one; retried until it is not taken, and refused when it never is. */
     mintId?: () => string;
 }
 
@@ -41,10 +41,20 @@ export interface PlanApplied {
 }
 
 const ID_ALPHABET = 'abcdefghijklmnopqrstuvwxyz0123456789';
+const ID_LENGTH = 6;
+/* 256 is no multiple of the alphabet, so a byte at or above this would favor its first characters. */
+const ID_BYTE_LIMIT = 256 - (256 % ID_ALPHABET.length);
 
 export function randomItemId(): string {
-    const bytes = crypto.getRandomValues(new Uint8Array(6));
-    return Array.from(bytes, (byte) => ID_ALPHABET[byte % ID_ALPHABET.length]).join('');
+    let id = '';
+    while (id.length < ID_LENGTH) {
+        for (const byte of crypto.getRandomValues(new Uint8Array(ID_LENGTH))) {
+            if (byte < ID_BYTE_LIMIT && id.length < ID_LENGTH) {
+                id += ID_ALPHABET[byte % ID_ALPHABET.length];
+            }
+        }
+    }
+    return id;
 }
 
 function issueMessage(error: z.ZodError): string {
@@ -56,9 +66,11 @@ function issueMessage(error: z.ZodError): string {
     return `${path ? `${path.replace(/^\./, '')}: ` : ''}${issue.message}`;
 }
 
+const MINT_ATTEMPTS = 1000;
+
 function idMinter(taken: Set<string>, mintId: () => string, minted: string[]) {
-    return (): string => {
-        for (let attempt = 0; attempt < 1000; attempt++) {
+    return (): string | PlanRefusal => {
+        for (let attempt = 0; attempt < MINT_ATTEMPTS; attempt++) {
             const id = mintId();
             if (!taken.has(id)) {
                 taken.add(id);
@@ -66,7 +78,7 @@ function idMinter(taken: Set<string>, mintId: () => string, minted: string[]) {
                 return id;
             }
         }
-        throw new Error('Could not mint a free plan item id');
+        return refuse('duplicate-id', `mintId gave no id the plan does not already have in ${MINT_ATTEMPTS} tries`);
     };
 }
 
@@ -176,7 +188,7 @@ function newItem(op: Extract<PlanOp, { op: 'add' }>, id: string): PlanItem {
     return { type: 'step', ...base, ...(op.checks ? { checks: op.checks } : {}) };
 }
 
-function applyOne(plan: Plan, op: PlanOp, options: PlanApplyOptions, mint: () => string, dropped: string[]): PlanRefusal | null {
+function applyOne(plan: Plan, op: PlanOp, options: PlanApplyOptions, mint: () => string | PlanRefusal, dropped: string[]): PlanRefusal | null {
     const verdict = canApply(op, options.actor, plan);
     if (!verdict.ok) {
         return verdict;
@@ -210,6 +222,9 @@ function applyOne(plan: Plan, op: PlanOp, options: PlanApplyOptions, mint: () =>
         }
         case 'add': {
             const id = op.id ?? mint();
+            if (typeof id !== 'string') {
+                return id;
+            }
             if (op.id !== undefined && locateItem(plan, op.id)) {
                 return refuse('duplicate-id', `The plan already has an item "${op.id}"`);
             }
@@ -411,6 +426,18 @@ export function createPlan(draft: PlanDraft, options: PlanCreateOptions): PlanAp
         }
     }
     const mint = idMinter(taken, options.mintId ?? randomItemId, minted);
+    // Minted up front so a refusal stops here; the tree below takes them in the same order, parents first.
+    const fresh: string[] = [];
+    for (const item of allDraftItems(source.items)) {
+        if (item.id === undefined) {
+            const id = mint();
+            if (typeof id !== 'string') {
+                return id;
+            }
+            fresh.push(id);
+        }
+    }
+    const nextId = (): string => fresh.shift()!;
     const described = <T extends { description?: string }>(value: T): T => {
         if (value.description === '') {
             delete value.description;
@@ -419,7 +446,7 @@ export function createPlan(draft: PlanDraft, options: PlanCreateOptions): PlanAp
     };
     const toStep = (step: PlanDraftStep): PlanStep => {
         const { steps, state, note, ...rest } = step;
-        const result: PlanStep = described({ ...rest, id: step.id ?? mint() });
+        const result: PlanStep = described({ ...rest, id: step.id ?? nextId() });
         if (steps && steps.length > 0) {
             result.steps = steps.map(toStep);
         }
@@ -431,10 +458,10 @@ export function createPlan(draft: PlanDraft, options: PlanCreateOptions): PlanAp
         }
         return result;
     };
-    const toText = (text: PlanDraftText): PlanText => described({ ...text, id: text.id ?? mint() });
+    const toText = (text: PlanDraftText): PlanText => described({ ...text, id: text.id ?? nextId() });
     const items = source.items.map((item): PlanItem => {
         if (item.type === 'section') {
-            return described({ ...item, id: item.id ?? mint(), items: item.items.map((child) => (child.type === 'text' ? toText(child) : toStep(child))) });
+            return described({ ...item, id: item.id ?? nextId(), items: item.items.map((child) => (child.type === 'text' ? toText(child) : toStep(child))) });
         }
         return item.type === 'text' ? toText(item) : toStep(item);
     });

package/src/index.ts

@@ -27,20 +27,15 @@ export {
     type PlanRefusalCode,
     type PlanRefusal,
     refuse,
-    type PlanLocation,
-    locateItem,
     findItem,
     allItems,
     allSteps,
     isParentStep,
     effectiveChecks,
     isFinishedOutcome,
-    deriveState,
     stepState,
     type PlanProgress,
     planProgress,
     leafSteps,
-    activeStepIds,
-    holdsPersonState,
-    structureProblem
+    activeStepIds
 } from './tree.ts';

package/src/permissions.ts

@@ -1,4 +1,4 @@
-import type { Plan, PlanActor, PlanOp, PlanStep, PlanStepState } from './protocol.ts';
+import type { Plan, PlanActor, PlanChecks, PlanOp, PlanStep, PlanStepState } from './protocol.ts';
 import { allSteps, effectiveChecks, holdsPersonState, isParentStep, locateItem, missingItem, refuse, type PlanRefusal } from './tree.ts';
 
 export type PlanVerdict = { ok: true } | PlanRefusal;
@@ -36,14 +36,20 @@ function mayState(plan: Plan, step: PlanStep, state: PlanStepState, actor: PlanA
     return ALLOWED;
 }
 
-/* Adding under a leaf takes its state away, which may not happen to a state a person set. */
-function mayHoldChildren(plan: Plan, under: string | undefined): PlanVerdict {
-    if (under === undefined) {
+/*
+ * Adding under a leaf takes its state away, which may not happen to a state a person set. Its state
+ * then follows from the sub-steps, so a step only a person checks takes only sub-steps a person checks.
+ */
+function mayHoldChildren(plan: Plan, under: string | undefined, after: string | undefined, added: readonly PlanChecks[]): PlanVerdict {
+    const parent = under !== undefined ? locateItem(plan, under)?.item : after !== undefined ? locateItem(plan, after)?.parent : null;
+    if (parent?.type !== 'step') {
         return ALLOWED;
     }
-    const location = locateItem(plan, under);
-    if (location?.item.type === 'step' && !isParentStep(location.item) && holdsPersonState(location.item)) {
-        return refuse('set-by-person', `A person set "${under}" to ${location.item.state}; a sub-step would take that state away`);
+    if (!isParentStep(parent) && holdsPersonState(parent)) {
+        return refuse('set-by-person', `A person set "${parent.id}" to ${parent.state}; a sub-step would take that state away`);
+    }
+    if (effectiveChecks(plan, parent) === 'person' && added.some((checks) => checks !== 'person')) {
+        return refuse('person-only', `Only a person checks "${parent.id}", so a sub-step under it is one a person checks too`);
     }
     return ALLOWED;
 }
@@ -95,7 +101,7 @@ export function canApply(op: PlanOp, actor: PlanActor, plan: Plan): PlanVerdict
             return ALLOWED;
         }
         case 'add':
-            return mayHoldChildren(plan, op.under);
+            return mayHoldChildren(plan, op.under, op.after, op.type === 'step' ? [op.checks ?? plan.meta.checks] : []);
         case 'edit': {
             const location = locateItem(plan, op.id);
             if (!location) {
@@ -126,10 +132,16 @@ export function canApply(op: PlanOp, actor: PlanActor, plan: Plan): PlanVerdict
             return ALLOWED;
         }
         case 'move': {
-            if (!locateItem(plan, op.id)) {
+            const location = locateItem(plan, op.id);
+            if (!location) {
                 return missingItem(op.id);
             }
-            return mayHoldChildren(plan, op.under);
+            return mayHoldChildren(
+                plan,
+                op.under,
+                op.after,
+                allSteps([location.item]).map((step) => effectiveChecks(plan, step))
+            );
         }
         case 'remove': {
             const location = locateItem(plan, op.id);