@nowline/layout 0.8.5 → 0.9.0

package/src/schedule.ts

@@ -1,40 +1,63 @@
 // scheduleRoadmap — compute the floating calendar start/end date for every
 // named entity (items, milestones, anchors) without running the full layout.
 //
-// The sequencing rules exactly mirror `computeContentEndDay` in `layout.ts`
-// plus the roadmap-start resolution in `RoadmapNode.place`:
-//   - date: / start:  — absolute pin (date: wins over start:)
-//   - after:[id|DATE]  — start after the maximum predecessor end
+// This is the only day-level scheduler (specs/scheduler-unification.md): the
+// date window reads its content day from `extent`, and the exporters read the
+// dates. The pixel layout keeps its own placement and differs from it in the
+// catalogued ways of `test/engine-divergences.json`. The rules, with the
+// roadmap-start resolution of the date-window phase (`resolveDateWindow` in
+// `phases/date-window.ts`):
 //   - sequential default — start where the previous item in the lane ended
+//   - after:[id|DATE]  — start no earlier than the maximum predecessor end
+//     (work has no fixed start pin: `date:` / `start:` on an item are
+//     unknown keys, specs/dsl.md § Item Properties); a parallel ends at its
+//     latest track end, a group at its last child's end
+//   - wave barriers (roadmaps with waves only) — every start is floored by
+//     its wave's start S_k, iterated to a fixpoint by `solveWaveBarriers`
+//     (specs/waves.md §8.5)
 //
-// Used by the XLSX exporter to populate the "Start" / "End" date columns and
-// the milestone "Date" cell when no explicit `date:` is set. Keeping it
-// separate from `computeContentEndDay` avoids mutating the byte-stable snapshot
-// pipeline.
+// Offsets are working-day indices from the start (specs/working-calendar.md
+// §5): dates convert with `workingIndexOf`, so an `after:` date on a
+// non-working day starts on the next working day. A start (and an after-only milestone) is a
+// point, `dateAtWorkingIndex`; an exclusive end is `spanEndDate`, so a
+// Mon–Fri item ends on Saturday. Anchors and dated milestones keep their own
+// dates. A calendar with no non-working day keeps calendar-day arithmetic.
+//
+// The schedule is every exporter's source for the chart's calendar and
+// durations (handoff m2p decision 16): `calendar` is the file's resolved
+// calendar and `ScheduledItem.days` the duration engine C placed. The XLSX
+// exporter also reads the Start / End dates, the milestone dates and the
+// wave spans; the Mermaid exporter reads the wave spans.
 
 import type {
     GroupBlock,
     ItemDeclaration,
     MilestoneDeclaration,
     NowlineFile,
-    ParallelBlock,
+    ResolvedContent,
     ResolveResult,
     SwimlaneDeclaration,
+    WavePlan,
 } from '@nowline/core';
-import { isGroupBlock, isItemDeclaration, isParallelBlock } from '@nowline/core';
-import {
-    addDays,
-    daysBetween,
-    deriveItemDurationDays,
-    resolveCalendar,
-    resolveSizes,
-} from './calendar.js';
-import { parseDate, propValue, propValues } from './dsl-utils.js';
+import { buildWavePlan, isGroupBlock, isItemDeclaration, isParallelBlock } from '@nowline/core';
+import { type TrackNode, trackChildren } from '@nowline/core/internal';
+import { deriveItemDurationDays, resolveSizes } from './calendar.js';
+import { type ResolvedCalendar, resolveWorkingCalendar } from './calendar-resolver.js';
+import { parseIsoDate, propValue } from './dsl-utils.js';
+import { type AfterTerm, startTermsOf } from './start-terms.js';
+import { solveWaveBarriers, summarizeWaves, WavePass, waveFloorDays } from './wave-barrier.js';
+import { spanEndDate } from './working-calendar.js';
 
 /** Per-item scheduled interval, keyed by item id (name). */
 export interface ScheduledItem {
     start: Date;
     end: Date;
+    /**
+     * Duration in working days: the `duration:` literal, or the size's effort
+     * divided by `capacity:`, under the file's calendar. 0 when the item has
+     * neither, or names an undeclared size.
+     */
+    days: number;
 }
 
 /**
@@ -48,6 +71,8 @@ export interface ScheduledItem {
 export interface RoadmapSchedule {
     /** Resolved roadmap start date (UTC midnight). */
     startDate: Date;
+    /** The file's calendar, which every date and `days` here uses. */
+    calendar: ResolvedCalendar;
     /** Named items keyed by their DSL id (`name`). */
     items: Map<string, ScheduledItem>;
     /** Every item keyed by AST node identity (named and anonymous). */
@@ -58,11 +83,67 @@ export interface RoadmapSchedule {
     milestoneByNode: WeakMap<MilestoneDeclaration, Date>;
     /** Named anchors: their declared or computed date. */
     anchors: Map<string, Date>;
+    /**
+     * Waves by id, in declaration order (specs/waves.md §8.5). Present only
+     * when the roadmap declares waves.
+     */
+    waves?: Map<string, ScheduledWave>;
+    /** The wave plan the schedule ran with; undefined without waves. */
+    plan?: WavePlan;
+    /** The `ResolveResult` this schedule was built from. */
+    resolved: ResolveResult;
+    /** What the date window needs (specs/scheduler-unification.md §3.3). */
+    extent: ScheduleExtent;
+}
+
+/**
+ * True when some wave has a member (specs/waves.md §9.1). With none, the
+ * roadmap draws no waves: no strip, no hatch, no legend. The barrier still
+ * runs, so wave floors and `after:<wave>` keep their dates.
+ */
+export function hasVisibleWaves(schedule: Pick<RoadmapSchedule, 'waves'>): boolean {
+    for (const wave of schedule.waves?.values() ?? []) {
+        if (wave.memberCount > 0) return true;
+    }
+    return false;
+}
+
+/** A wave's solved span (specs/waves.md §5.1). */
+export interface ScheduledWave {
+    /** 1-based declaration order. */
+    index: number;
+    /** `S_k` (UTC midnight). */
+    start: Date;
+    /** `E_k`, exclusive (UTC midnight); equals `start` for an empty wave. */
+    end: Date;
+    /** Members placed in the main lanes and first-level isolated regions. */
+    memberCount: number;
+    /** The member that sets `E_k` (id ?? title); omitted when none ends past `S_k`. */
+    heldBy?: string;
+    /** The wave's `after:` element that set `S_k`, when it beat the previous wave's end. */
+    floorRef?: string;
 }
 
 export interface ScheduleOptions {
     /** Passed as the reference date when the roadmap omits `start:`. */
     today?: Date;
+    /**
+     * The roadmap's wave plan from `buildWavePlan(resolved)`, when the caller
+     * already built it; `null` means "built, no waves". Omitted: built here.
+     */
+    plan?: WavePlan | null;
+}
+
+/** What the date window needs from the schedule (specs/scheduler-unification.md §3.2). */
+export interface ScheduleExtent {
+    /**
+     * Latest working-day offset from `startDate` reached by any lane cursor
+     * (item ends and container starts), any dated anchor, any milestone, and,
+     * with waves, every `S_k` and `E_n`. Isolated regions count too: without
+     * waves every region at any depth with its anchors and milestones, with
+     * waves the first-level regions' lanes. `today` is not included.
+     */
+    contentEndDay: number;
 }
 
 /**
@@ -74,144 +155,311 @@ export function scheduleRoadmap(
     resolved: ResolveResult,
     options: ScheduleOptions = {},
 ): RoadmapSchedule {
-    const cal = resolveCalendar(file, resolved.config.calendar);
+    const resolvedCalendar = resolveWorkingCalendar(file, resolved);
+    const { config: cal, working: calendar } = resolvedCalendar;
     const sizes = resolveSizes(resolved.content.sizes, cal);
 
-    // Resolve roadmap start date — same precedence as RoadmapNode.place.
+    // Resolve roadmap start date — same precedence as the date-window phase.
     const startRaw = propValue(file.roadmapDecl?.properties ?? [], 'start');
-    const startDate = parseDate(startRaw) ?? utcMidnight(options.today ?? new Date());
+    const startDate = parseIsoDate(startRaw) ?? utcMidnight(options.today ?? new Date());
+    // Working-day index of a date, and back: a point and an exclusive end.
+    const dayOf = (date: Date): number => calendar.workingIndexOf(startDate, date);
+    const pointAt = (day: number): Date => calendar.dateAtWorkingIndex(startDate, day);
+    const endAt = (start: number, end: number): Date =>
+        spanEndDate(calendar, startDate, start, end);
+
+    // The latest day any lane cursor, anchor, milestone or wave edge reaches.
+    let contentEndDay = 0;
+    const reachMax = (day: number): void => {
+        contentEndDay = Math.max(contentEndDay, day);
+    };
 
     // These maps accumulate end-day offsets (from startDate) for cross-entity
-    // `after:` resolution, matching computeContentEndDay exactly.
-    const itemEnd = new Map<string, number>(); // id → end day
+    // `after:` resolution. In a roadmap with waves the item maps are rebuilt on
+    // every barrier pass.
+    let itemEnd = new Map<string, number>(); // item, group, parallel or wave id → end day
     const anchorEnd = new Map<string, number>(); // id → date day
     const milestoneEnd = new Map<string, number>(); // id → date day
 
     // Result maps (Date objects).
-    const itemResults = new Map<string, ScheduledItem>();
-    const itemByNode = new WeakMap<ItemDeclaration, ScheduledItem>();
+    let itemResults = new Map<string, ScheduledItem>();
+    let itemByNode = new WeakMap<ItemDeclaration, ScheduledItem>();
     const milestoneResults = new Map<string, Date>();
     const milestoneByNode = new WeakMap<MilestoneDeclaration, Date>();
     const anchorResults = new Map<string, Date>();
 
-    // Resolve a single `after:` element to a day-offset.
-    const resolveAfterDay = (ref: string): number => {
-        const inlineDate = parseDate(ref);
-        if (inlineDate) return daysBetween(startDate, inlineDate);
-        if (itemEnd.has(ref)) return itemEnd.get(ref)!;
-        if (anchorEnd.has(ref)) return anchorEnd.get(ref)!;
-        if (milestoneEnd.has(ref)) return milestoneEnd.get(ref)!;
-        return 0;
-    };
-
     // Pre-seed named anchors (they may be referenced by item after: before we
     // walk the lanes).
     for (const [id, anchor] of resolved.content.anchors) {
-        const d = parseDate(propValue(anchor.properties, 'date'));
+        const d = parseIsoDate(propValue(anchor.properties, 'date'));
         if (d) {
-            const day = daysBetween(startDate, d);
+            const day = dayOf(d);
             anchorEnd.set(id, day);
-            anchorResults.set(id, addDays(startDate, day));
+            anchorResults.set(id, d);
+            reachMax(day);
         }
     }
 
-    // Walk a sequential lane, returning the end-day of the last child.
-    const walkLane = (children: SwimlaneDeclaration['content'], baselineEnd: number): number => {
-        let prevEnd = baselineEnd;
-        for (const child of children) {
-            if (child.$type === 'DescriptionDirective') continue;
-            prevEnd = walkNode(child as ItemDeclaration | GroupBlock | ParallelBlock, prevEnd);
-        }
-        return prevEnd;
-    };
+    // The id maps one walk resolves `after:` against: the main lanes share
+    // the maps above; an isolated region gets fresh maps.
+    interface WalkScope {
+        itemEnd: Map<string, number>;
+        anchorEnd: ReadonlyMap<string, number>;
+        milestoneEnd: ReadonlyMap<string, number>;
+        sizes: typeof sizes;
+        /** Id-keyed results; omitted for a region, whose ids stay invisible. */
+        itemResults?: Map<string, ScheduledItem>;
+        /** False for a nested region: its items count in the extent only. */
+        inByNode: boolean;
+    }
+    const mainScope = (): WalkScope => ({
+        itemEnd,
+        anchorEnd,
+        milestoneEnd,
+        sizes,
+        itemResults,
+        inByNode: true,
+    });
 
-    const walkNode = (
-        node: ItemDeclaration | GroupBlock | ParallelBlock,
-        prevEnd: number,
-    ): number => {
-        if (isItemDeclaration(node)) {
-            const dur = deriveItemDurationDays(node.properties, sizes, cal);
-            const dateProp = parseDate(propValue(node.properties, 'date'));
-            const startProp = parseDate(propValue(node.properties, 'start'));
-            const afterRefs = propValues(node.properties, 'after');
-            let start = prevEnd;
-            if (dateProp) {
-                start = daysBetween(startDate, dateProp);
-            } else if (startProp) {
-                start = daysBetween(startDate, startProp);
-            } else if (afterRefs.length > 0) {
-                start = Math.max(prevEnd, ...afterRefs.map(resolveAfterDay));
+    // `wave` is the current barrier pass, undefined when there are no waves;
+    // `reach` receives every lane cursor, so a container start that passes
+    // every child (an empty `group after:x`) still counts in the extent.
+    const makeWalker = (
+        scope: WalkScope,
+        wave: WavePass | undefined,
+        reach: (day: number) => void,
+    ) => {
+        // Resolve a single `after:` element to a day-offset.
+        const resolveAfterDay = (term: AfterTerm): number => {
+            if ('date' in term) return dayOf(term.date);
+            const ref = term.ref;
+            if (scope.itemEnd.has(ref)) return scope.itemEnd.get(ref)!;
+            if (scope.anchorEnd.has(ref)) return scope.anchorEnd.get(ref)!;
+            if (scope.milestoneEnd.has(ref)) return scope.milestoneEnd.get(ref)!;
+            return 0;
+        };
+
+        // Walk a sequential lane or group, returning the end-day of the last
+        // child. Core's `trackChildren` says what a child is; the recursion
+        // stays here because it carries the cursor and the wave pass.
+        const walkLane = (
+            container: SwimlaneDeclaration | GroupBlock,
+            baselineEnd: number,
+        ): number => {
+            let prevEnd = baselineEnd;
+            for (const child of trackChildren(container)) {
+                prevEnd = walkNode(child, prevEnd);
+                reach(prevEnd);
             }
-            const end = start + dur;
-            const scheduled: ScheduledItem = {
-                start: addDays(startDate, start),
-                end: addDays(startDate, end),
-            };
-            itemByNode.set(node, scheduled);
-            if (node.name) {
-                itemEnd.set(node.name, end);
-                itemResults.set(node.name, scheduled);
+            return prevEnd;
+        };
+
+        const walkNode = (node: TrackNode, prevEnd: number): number => {
+            if (isItemDeclaration(node)) {
+                const dur = deriveItemDurationDays(node.properties, scope.sizes, cal);
+                const { after } = startTermsOf(node.properties);
+                let start =
+                    after.length > 0 ? Math.max(prevEnd, ...after.map(resolveAfterDay)) : prevEnd;
+                // The barrier floor is one more term in the max.
+                if (wave) start = wave.apply(node, start);
+                const end = start + dur;
+                const scheduled: ScheduledItem = {
+                    start: pointAt(start),
+                    end: endAt(start, end),
+                    days: dur,
+                };
+                if (scope.inByNode) itemByNode.set(node, scheduled);
+                if (node.name) {
+                    scope.itemEnd.set(node.name, end);
+                    scope.itemResults?.set(node.name, scheduled);
+                }
+                wave?.accumulate(node, end);
+                return end;
             }
-            return end;
-        }
-        if (isParallelBlock(node)) {
-            const afterRefs = propValues(node.properties, 'after');
-            const containerStart =
-                afterRefs.length > 0
-                    ? Math.max(prevEnd, ...afterRefs.map(resolveAfterDay))
-                    : prevEnd;
-            let parallelEnd = containerStart;
-            for (const child of node.content) {
-                if (child.$type === 'DescriptionDirective') continue;
-                const childEnd = walkNode(child as ItemDeclaration | GroupBlock, containerStart);
-                parallelEnd = Math.max(parallelEnd, childEnd);
+            if (isParallelBlock(node)) {
+                const { after } = startTermsOf(node.properties);
+                let containerStart =
+                    after.length > 0 ? Math.max(prevEnd, ...after.map(resolveAfterDay)) : prevEnd;
+                if (wave) containerStart = wave.apply(node, containerStart);
+                let parallelEnd = containerStart;
+                for (const child of trackChildren(node)) {
+                    parallelEnd = Math.max(parallelEnd, walkNode(child, containerStart));
+                }
+                // `after:` a parallel waits for its latest track end.
+                if (node.name) scope.itemEnd.set(node.name, parallelEnd);
+                return parallelEnd;
+            }
+            if (isGroupBlock(node)) {
+                const { after } = startTermsOf(node.properties);
+                let containerStart =
+                    after.length > 0 ? Math.max(prevEnd, ...after.map(resolveAfterDay)) : prevEnd;
+                if (wave) containerStart = wave.apply(node, containerStart);
+                // `after:` a group waits for its last child's end.
+                const groupEnd = walkLane(node, containerStart);
+                if (node.name) scope.itemEnd.set(node.name, groupEnd);
+                return groupEnd;
+            }
+            return prevEnd;
+        };
+
+        return { walkLane, resolveAfterDay };
+    };
+
+    // A milestone is a point: its `date:`, else its latest predecessor end.
+    // Returns the day, or undefined when it has neither.
+    const milestoneDay = (
+        ms: MilestoneDeclaration,
+        resolveAfterDay: (term: AfterTerm) => number,
+    ): number | undefined => {
+        const d = parseIsoDate(propValue(ms.properties, 'date'));
+        if (d) return dayOf(d);
+        const { after } = startTermsOf(ms.properties);
+        return after.length > 0 ? Math.max(0, ...after.map(resolveAfterDay)) : undefined;
+    };
+
+    // An isolated region in a roadmap without waves: fresh id maps, its own
+    // sizes (specs/scheduler-unification.md §8, decision 2), its anchors and
+    // milestones (resolved inside the region and counted in the extent, never
+    // in the results) and its nested regions.
+    // First-level region items join `byNode`; their ids stay out of `items`.
+    const scheduleRegion = (content: ResolvedContent, firstLevel: boolean): void => {
+        const regionItemEnd = new Map<string, number>();
+        const regionAnchorEnd = new Map<string, number>();
+        const regionMilestoneEnd = new Map<string, number>();
+        for (const [id, anchor] of content.anchors) {
+            const d = parseIsoDate(propValue(anchor.properties, 'date'));
+            if (d) {
+                const day = dayOf(d);
+                regionAnchorEnd.set(id, day);
+                reachMax(day);
             }
-            return parallelEnd;
         }
-        if (isGroupBlock(node)) {
-            const afterRefs = propValues(node.properties, 'after');
-            const containerStart =
-                afterRefs.length > 0
-                    ? Math.max(prevEnd, ...afterRefs.map(resolveAfterDay))
-                    : prevEnd;
-            return walkLane(node.content as SwimlaneDeclaration['content'], containerStart);
+        const { walkLane, resolveAfterDay } = makeWalker(
+            {
+                itemEnd: regionItemEnd,
+                anchorEnd: regionAnchorEnd,
+                milestoneEnd: regionMilestoneEnd,
+                sizes: resolveSizes(content.sizes, cal),
+                inByNode: firstLevel,
+            },
+            undefined,
+            reachMax,
+        );
+        for (const lane of content.swimlanes.values()) walkLane(lane, 0);
+        for (const [id, ms] of content.milestones) {
+            const day = milestoneDay(ms, resolveAfterDay);
+            if (day === undefined) continue;
+            regionMilestoneEnd.set(id, day);
+            reachMax(day);
         }
-        return prevEnd;
+        for (const nested of content.isolatedRegions) scheduleRegion(nested.content, false);
     };
 
-    for (const lane of resolved.content.swimlanes.values()) {
-        walkLane(lane.content, 0);
+    const plan = options.plan !== undefined ? (options.plan ?? undefined) : buildWavePlan(resolved);
+    let waves: Map<string, ScheduledWave> | undefined;
+    if (!plan) {
+        const { walkLane } = makeWalker(mainScope(), undefined, reachMax);
+        for (const lane of resolved.content.swimlanes.values()) {
+            walkLane(lane, 0);
+        }
+    } else {
+        // Wave barriers (specs/waves.md §8.5): iterate the lane walk to the
+        // least fixpoint. The final pass's results are the schedule.
+        const ids = plan.waves.map((w) => w.name as string);
+        const floors = waveFloorDays(plan, startDate, calendar);
+        let finalPass: WavePass | undefined;
+        // The extent of the latest pass; the final one ran with the solved S/E.
+        let passMax = 0;
+        const reachPass = (day: number): void => {
+            passMax = Math.max(passMax, day);
+        };
+        const result = solveWaveBarriers(ids.length, 0, floors, (S, E) => {
+            // Reset the item maps, keep the anchors, and seed each wave id
+            // with E_k so `after:<wave>` resolves to the wave's end.
+            const seeds = ids.map((id, i): [string, number] => [id, E[i]]);
+            itemEnd = new Map(seeds);
+            itemResults = new Map();
+            itemByNode = new WeakMap();
+            passMax = 0;
+            const pass = new WavePass(plan, S);
+            const { walkLane } = makeWalker(mainScope(), pass, reachPass);
+            for (const lane of resolved.content.swimlanes.values()) {
+                walkLane(lane, 0);
+            }
+            // Exactly one level of isolated regions, each with fresh id maps
+            // seeded only with the wave edges. Region items join the barrier
+            // and `byNode`; their ids stay out of `items`. Region anchors,
+            // region milestones and nested regions are not walked: engine A
+            // draws none of them.
+            for (const region of resolved.content.isolatedRegions) {
+                const regionWalker = makeWalker(
+                    {
+                        itemEnd: new Map(seeds),
+                        anchorEnd: new Map(),
+                        milestoneEnd: new Map(),
+                        sizes: resolveSizes(region.content.sizes, cal),
+                        inByNode: true,
+                    },
+                    pass,
+                    reachPass,
+                );
+                for (const lane of region.content.swimlanes.values()) {
+                    regionWalker.walkLane(lane, 0);
+                }
+            }
+            finalPass = pass;
+            return pass;
+        });
+        // The content end covers the last wave's end and every wave start,
+        // so floors and empty trailing waves stay inside the window.
+        reachMax(Math.max(passMax, ...result.S, ...result.E.slice(-1)));
+        waves = new Map();
+        for (const span of summarizeWaves(plan, result, finalPass!, 0, floors)) {
+            waves.set(span.id, {
+                index: span.index,
+                start: pointAt(span.start),
+                end: endAt(span.start, span.end),
+                memberCount: span.memberCount,
+                ...(span.heldBy !== undefined ? { heldBy: span.heldBy } : {}),
+                ...(span.floorRef !== undefined ? { floorRef: span.floorRef } : {}),
+            });
+        }
     }
 
-    // Milestones — same pass order as computeContentEndDay (after items so
-    // after: can resolve item end-days).
+    // Milestones, after the items so after: can resolve item end-days, and
+    // wave ids their E_k.
+    const { resolveAfterDay } = makeWalker(mainScope(), undefined, reachMax);
     for (const [id, ms] of resolved.content.milestones) {
-        const d = parseDate(propValue(ms.properties, 'date'));
-        if (d) {
-            const day = daysBetween(startDate, d);
-            const resolved2 = addDays(startDate, day);
-            milestoneEnd.set(id, day);
-            milestoneResults.set(id, resolved2);
-            milestoneByNode.set(ms, resolved2);
-            continue;
-        }
-        const after = propValues(ms.properties, 'after');
-        if (after.length > 0) {
-            const day = Math.max(0, ...after.map(resolveAfterDay));
-            const resolved2 = addDays(startDate, day);
-            milestoneEnd.set(id, day);
-            milestoneResults.set(id, resolved2);
-            milestoneByNode.set(ms, resolved2);
+        const day = milestoneDay(ms, resolveAfterDay);
+        if (day === undefined) continue;
+        // A dated milestone keeps its own date; an after-only one is a point
+        // at the latest predecessor end: the next working day.
+        const date = parseIsoDate(propValue(ms.properties, 'date')) ?? pointAt(day);
+        milestoneEnd.set(id, day);
+        milestoneResults.set(id, date);
+        milestoneByNode.set(ms, date);
+        reachMax(day);
+    }
+
+    // Isolated regions without waves (with waves they joined the passes).
+    if (!plan) {
+        for (const region of resolved.content.isolatedRegions) {
+            scheduleRegion(region.content, true);
         }
     }
 
     return {
         startDate,
+        calendar: resolvedCalendar,
         items: itemResults,
         byNode: itemByNode,
         milestones: milestoneResults,
         milestoneByNode,
         anchors: anchorResults,
+        ...(waves ? { waves } : {}),
+        ...(plan ? { plan } : {}),
+        resolved,
+        extent: { contentEndDay },
     };
 }