All files / core/blong-gogo/src checkpoint.ts

67.66% Statements 90/133
100% Branches 21/21
83.33% Functions 5/6
67.66% Lines 90/133

Press n or j to go to the next uncovered block, b, p or k for the previous block.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 1341x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 57x 57x 48x 48x 9x 9x 9x 9x 9x 9x 1x 1x 1x 1x 1x 1x 1x 1x 1x 27x 27x 27x 27x 27x 27x 27x 27x 27x 27x 27x 27x 27x 27x 27x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 1x 30x 30x 30x 30x 30x 30x 30x 30x 30x 30x 30x 55x 55x 29x 29x                                                                                       76x 76x 76x 76x 3783x 3783x 335x 335x 3783x 76x  
import type {
    CheckpointFn,
    DecideFn,
    IMeta,
    IProgressPoint,
    IProgressRegion,
    IRegionMark,
} from '@feasibleone/blong/types';
import {vocabulary} from '@feasibleone/lukaot/context';
 
/**
 * The branches the calling scope is running inside, named the way `$meta` names them.
 *
 * Names only, and never the log's own mark: the mark carries the position it was minted at,
 * which describes a place in *this* process' execution. An entry that travelled here from
 * another process over a call would bring a position that means nothing here, while the three
 * names still say exactly which branches it sat in — which is all a report groups by.
 */
const regionMarks = (): IRegionMark[] | undefined => {
    const chain = vocabulary.currentRegions();
    if (chain === undefined || chain.length === 0) {
        return undefined;
    }
    return chain.map(region => ({
        discriminator: region.discriminator,
        candidates: region.candidates,
        chosen: region.chosen,
    }));
};
 
/**
 * Reports a checkpoint into `$meta.progress`, and announces it as a progress point
 * (PRD R26).
 *
 * Uses `this` binding — works correctly when called as
 * $meta.checkpoint?.('name', data) with optional chaining.
 */
const checkpoint: CheckpointFn = function (this: IMeta, name: string, data?: unknown): void {
    const regions = regionMarks();
    const entry: IProgressPoint = {
        kind: 'point',
        name,
        ...(data === undefined ? {} : {data}),
        timestamp: Date.now(),
        ...(regions === undefined ? {} : {regions}),
    };
    (this.progress ??= []).push(entry);
    // The same moment is announced to the log, so a checkpoint reaches the record the
    // sequence diagram is drawn from rather than only the list a test asserts on. The
    // vocabulary degrades to nothing where no emitter is attached, so this is one call
    // and never a way for a dispatch path to import the emitter's ambient scope (F-197).
    vocabulary.point(name, data);
};
 
/**
 * Takes a branch, and keeps what it was and which one was taken on the invocation that took
 * it (PRD R11/R26).
 *
 * `this`-bound like {@link checkpoint}. The branch's `run` is *wrapped* rather than the
 * predicates re-evaluated: a predicate with a side effect must run exactly once, and the
 * decision recorded has to be the one the code actually took. A branch whose `run` throws
 * records nothing — the entry is withdrawn before the throw propagates, because a decision
 * that never completed is not a decision.
 */
const decide: DecideFn = function <T>(
    this: IMeta,
    discriminator: string,
    values: Record<string, unknown>,
    branches: ReadonlyArray<{
        name: string;
        when: (values: Record<string, unknown>) => boolean;
        run: () => T;
    }>,
): T | undefined {
    let chosen: string | undefined;
    const wrapped = branches.map(branch => ({
        ...branch,
        run: () => {
            chosen = branch.name;
            return branch.run();
        },
    }));
    // The entry is pushed *before* the branch runs, which is what puts it where the
    // announcement order wants it: the points the branch announces come after it in the
    // array, and a report that groups by those points therefore draws them inside the
    // branch. Nothing else in the entry is known yet, so `chosen` is filled in below.
    const outer = regionMarks();
    const entry: IProgressRegion = {
        kind: 'region',
        discriminator,
        candidates: branches.map(branch => branch.name),
        chosen: '',
        values,
        ...(outer === undefined ? {} : {regions: outer}),
    };
    const held = this.progress;
    const progress = (this.progress ??= []);
    progress.push(entry);
    try {
        const result = vocabulary.decide<T>(discriminator, values, wrapped);
        entry.chosen = chosen ?? 'none';
        return result;
    } catch (error) {
        // A branch whose `run` throws records nothing, which is the rule this recorder has
        // always kept: a decision that never completed is not a decision. The entry was
        // pushed early, so it is withdrawn again — and, where the array was this call's own,
        // the slot goes with it, so a throwing branch leaves `$meta.progress` exactly as
        // absent as it found it. The throw still propagates.
        const at = progress.lastIndexOf(entry);
        if (at !== -1) progress.splice(at, 1);
        if (held === undefined && progress.length === 0) delete this.progress;
        throw error;
    }
};

/**
 * Attach the framework's progress-point handles to a dispatch's `$meta`.
 *
 * `decide` is attached in **every** mode: it selects a branch, so a missing one would skip
 * the work rather than cost a note. `checkpoint` is attached only where points are
 * recorded, which is what keeps its `?.` call free in production.
 */
export function createAttachCheckpoint(
    mode: 'test' | 'debug' | 'production',
): (meta: IMeta) => void {
    const recording = mode !== 'production';
    return (meta: IMeta): void => {
        meta.decide ??= decide;
        if (recording) {
            meta.checkpoint ??= checkpoint;
        }
    };
}