@milehimikey/em 1.17.0 → 1.18.1

package/dist/model/validate.js

@@ -4,7 +4,10 @@ import { AUTOMATION_KINDS } from "../parser/ast.js";
 import { collectModelInvariants, collectTags, MODEL_INVARIANT_ID_RE, PUBLIC_SCALAR_TYPE_NAMES, normalizeName, resolvePublicType, resolveTypeRef, } from "./model.js";
 import { pushDiag } from "./rules.js";
 import { viewSourceNames } from "./continuation.js";
-import { connectionKind, resolveLoopsToTarget } from "./edges.js";
+import { connectionKind, resolveLoopsToTarget, semanticEdges } from "./edges.js";
+import { composedButRenderedBackward, findStoryline, isEarlierOnTimeline, isLaterOnTimeline, latestOnTimeline, } from "./storylines.js";
+import { classifySlicePattern } from "../catalog/classify.js";
+import { shapeDiagnostics } from "./shapeLint.js";
 import { kebabSlug } from "../util/slug.js";
 /** A GitHub user (`@alice`) or team (`@org/team`) — the shape CODEOWNERS accepts. */
 export const OWNER_HANDLE_RE = /^@[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?(?:\/[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?)?$/;
@@ -19,9 +22,13 @@ export function validate(model, grid, refs) {
     const refOf = (id) => refs.refById.get(id);
     // Grid collisions: two elements of the same band landed in one slice cell.
     for (const c of grid.collisions) {
+        const bothEvents = c.dropped.kind === "event" && c.kept.kind === "event";
         pushDiag(diags, "grid-collision", {
             message: `"${c.dropped.name}" collides with "${c.kept.name}" in the same ` +
-                `slice/lane (${c.rowKey}); split them into separate slices`,
+                `slice/lane (${c.rowKey}); split them into separate slices` +
+                (bothEvents
+                    ? ` — or, if they are two outcomes of one command on one context, write \`event A | B @Context\``
+                    : ""),
             line: c.dropped.line,
             refs: [refOf(c.dropped.id), refOf(c.kept.id)],
         });
@@ -47,13 +54,29 @@ export function validate(model, grid, refs) {
             for (const ui of slice.elements.filter((e) => e.kind === "ui")) {
                 pushDiag(diags, "ui-shares-slice-with-automation", {
                     message: `ui "${ui.name}" shares slice "${slice.name}" with ${auto.kind} "${auto.name}"; ` +
-                        `a \`ui\` only wires to a \`command\` a person issues and renders disconnected here — ` +
-                        `move it to the slice that displays the read model, or drop it`,
+                        `a \`ui\` only wires to a \`command\` a person issues and renders disconnected here` +
+                        ((auto.from ?? []).length > 0
+                            ? ` (and it sits between the ${auto.kind} and the row below it, so the ${auto.kind}'s ` +
+                                `inbound edge has to be routed around it)`
+                            : ``) +
+                        ` — move it to the slice that displays the read model, or drop it`,
                     line: ui.line,
                     refs: [refOf(ui.id), refOf(auto.id)],
                 });
             }
         }
+        // GH #278: `event A | B @Ctx` alternatives are the outcomes of ONE command's decision.
+        if (!command) {
+            const alt = events.find((e) => e.alternativeGroup !== undefined);
+            if (alt) {
+                pushDiag(diags, "alternative-events-no-command", {
+                    message: `alternative events ${events.filter((e) => e.alternativeGroup === alt.alternativeGroup).map((e) => `"${e.name}"`).join(" | ")} share no command in slice "${slice.name}"; ` +
+                        `alternatives are the possible outcomes of one command — add the command that records one of them`,
+                    line: alt.line,
+                    refs: events.filter((e) => e.alternativeGroup === alt.alternativeGroup).map((e) => refOf(e.id)),
+                });
+            }
+        }
         // A command should record at least one event.
         if (command && events.length === 0) {
             pushDiag(diags, "both-ends-of-a-flow/command-no-event", {
@@ -89,7 +112,9 @@ export function validate(model, grid, refs) {
                         refs: other ? [refOf(view.id), refOf(other.id)] : [refOf(view.id)],
                     });
                 }
-                else if (evt.sliceIndex > view.sliceIndex) {
+                else if (isLaterOnTimeline(model, evt.sliceIndex, view.sliceIndex) &&
+                    // GH #279: any recording site of the logical event on or before the view suffices.
+                    !(bucket ?? []).some((e) => e.kind === "event" && e.logicalId === evt.logicalId && !isLaterOnTimeline(model, e.sliceIndex, view.sliceIndex))) {
                     pushDiag(diags, "view-from-future-event", {
                         message: `time flows left to right: event "${evt.name}" (slice ${evt.sliceIndex + 1}) happens ` +
                             `after read model "${view.name}" (slice ${view.sliceIndex + 1}); move this source to a ` +
@@ -163,6 +188,41 @@ export function validate(model, grid, refs) {
                         }
                     }
                 }
+                // Collection fields (GH #288): `values: AttributeValue[] derived from "E1", "E2"` embeds a
+                // child entity in the view. The field itself is exempt (derived), but each field of the
+                // element type must trace to a field on at least one NAMED child event. Only checked when
+                // every resolvable named event declares `{ fields }` (a fieldless one may be the provider),
+                // and unresolved names are left to `derived-from-unresolved` above.
+                for (const f of view.fields) {
+                    if (!f.derived || !f.derivedFrom || f.derivedFrom.length === 0)
+                        continue;
+                    const resolved = resolveTypeRef(f.type, model.typesByName);
+                    if (!resolved || !resolved.array)
+                        continue;
+                    const named = [];
+                    for (const name of f.derivedFrom) {
+                        const evt = (model.byName.get(normalizeName(name)) ?? []).find((e) => e.kind === "event");
+                        if (evt)
+                            named.push(evt);
+                    }
+                    if (named.length === 0 || !named.every((e) => (e.fields ?? []).length > 0))
+                        continue;
+                    const union = new Set();
+                    for (const e of named)
+                        for (const ef of e.fields ?? [])
+                            union.add(normalizeName(ef.name));
+                    const list = named.map((e) => `"${e.name}"`).join(", ");
+                    for (const tf of resolved.typeDecl.fields) {
+                        if (union.has(normalizeName(tf.name)))
+                            continue;
+                        pushDiag(diags, "fields-completeness/view-field-no-source", {
+                            message: `view "${view.name}" collection field "${f.name}" (${f.type}) element field ` +
+                                `"${tf.name}" of type "${resolved.typeDecl.name}" has no source in ${list}`,
+                            line: view.line,
+                            refs: [refOf(view.id), ...named.map((e) => refOf(e.id))],
+                        });
+                    }
+                }
             }
         }
         // Fields completeness: every event field in a slice should trace to a field on
@@ -226,7 +286,7 @@ export function validate(model, grid, refs) {
                     refs: asEvent ? [refOf(el.id), refOf(asEvent.id)] : [refOf(el.id)],
                 });
             }
-            else if (!views.some((v) => v.sliceIndex <= el.sliceIndex)) {
+            else if (!views.some((v) => !isLaterOnTimeline(model, v.sliceIndex, el.sliceIndex))) {
                 pushDiag(diags, "reaction-from-future-view", {
                     message: `time flows left to right: ${el.kind} "${el.name}" (slice ${el.sliceIndex + 1}) reads ` +
                         `"${src}" before any instance of it exists; declare the view in or before that slice`,
@@ -263,7 +323,7 @@ export function validate(model, grid, refs) {
             const target = resolveLoopsToTarget(model, el, name);
             if (!target) {
                 const nearest = views
-                    .filter((v) => v.sliceIndex >= el.sliceIndex)
+                    .filter((v) => !isEarlierOnTimeline(model, v.sliceIndex, el.sliceIndex))
                     .sort((a, b) => a.sliceIndex - b.sliceIndex)[0];
                 pushDiag(diags, "loops-to-forward", {
                     message: `time flows left to right: event "${el.name}" (slice ${el.sliceIndex + 1}) loops-to ` +
@@ -455,13 +515,26 @@ export function validate(model, grid, refs) {
     for (const el of model.elements) {
         if (el.kind !== "event")
             continue;
-        if (readEvents.has(normalizeName(el.name)))
+        if (readEvents.has(normalizeName(el.name)) && !isSharedEventSite(model, el))
             continue;
         // A `public` event is part of the published integration surface — its reader is
         // outside this model, possibly outside this system entirely, so there's nothing local
         // to project it into.
         if (el.public)
             continue;
+        if (isSharedEventSite(model, el) && readEvents.has(normalizeName(el.name))) {
+            // GH #279: every recording site of a shared event needs a reader at or after it.
+            if (sharedSiteHasReader(model, el))
+                continue;
+            const slice = model.slices[el.sliceIndex];
+            pushDiag(diags, "both-ends-of-a-flow/event-unread", {
+                message: `this recording of "${el.name}" (slice "${slice?.name ?? el.sliceIndex + 1}") has no reader after it; ` +
+                    `add \`view V again from "${el.name}"\` after it`,
+                line: el.line,
+                refs: [refOf(el.id)],
+            });
+            continue;
+        }
         pushDiag(diags, "both-ends-of-a-flow/event-unread", {
             message: `event "${el.name}" is not read by any read model; project it into a view ` +
                 `(\`view X from "${el.name}"\`), or reconsider recording it`,
@@ -474,7 +547,7 @@ export function validate(model, grid, refs) {
         if (a.fromId && a.toId) {
             const fromEl = model.byId.get(a.fromId);
             const toEl = model.byId.get(a.toId);
-            if (fromEl && toEl && toEl.sliceIndex < fromEl.sliceIndex) {
+            if (fromEl && toEl && isEarlierOnTimeline(model, toEl.sliceIndex, fromEl.sliceIndex)) {
                 pushDiag(diags, "arrow-backward", {
                     message: `time flows left to right: arrow "${a.from}" -> "${a.to}" points backward ` +
                         `(slice ${fromEl.sliceIndex + 1} -> ${toEl.sliceIndex + 1}); restructure so the target comes later`,
@@ -506,6 +579,78 @@ export function validate(model, grid, refs) {
                 ...(a.fromId ? { refs: [refOf(a.fromId)] } : {}),
             });
     }
+    // Storylines (GH #277). Advisory grouping, plus the `after "<storyline>"` clause that composes
+    // the timeline (model/storylines.ts) — whose misuse (unknown/cyclic reference, or a reference
+    // that would draw right-to-left in the full-model render) is an error.
+    const storylines = model.storylines ?? [];
+    if (storylines.length > 0) {
+        for (const slice of model.slices) {
+            if (slice.storyline !== undefined)
+                continue;
+            pushDiag(diags, "slice-outside-storyline", {
+                message: `slice "${slice.name}" belongs to no storyline, but this model declares ` +
+                    `${storylines.length} (${storylines.map((s) => `"${s.name}"`).join(", ")}); move it inside one`,
+                line: slice.line,
+                refs: [refs.sliceKeys[slice.index]],
+            });
+        }
+        for (const st of storylines) {
+            if (st.after === undefined)
+                continue;
+            const target = findStoryline(model, st.after);
+            if (!target) {
+                pushDiag(diags, "storyline-after-unknown", {
+                    message: `storyline "${st.name}" is declared \`after\` unknown storyline "${st.after}"`,
+                    line: st.line,
+                });
+                continue;
+            }
+            // A cycle (including `after` itself) leaves the storyline with no usable chain.
+            let cur = target;
+            const seen = new Set();
+            let cyclic = target === st;
+            while (!cyclic && cur && cur.after !== undefined && !seen.has(cur)) {
+                seen.add(cur);
+                cur = findStoryline(model, cur.after);
+                if (cur === st)
+                    cyclic = true;
+            }
+            if (cyclic) {
+                pushDiag(diags, "storyline-after-cycle", {
+                    message: `storyline "${st.name}" is declared \`after\` "${st.after}", which (transitively) comes after ` +
+                        `"${st.name}" — a story cannot follow itself; remove one \`after\` clause`,
+                    line: st.line,
+                });
+            }
+        }
+        // The composed timeline may read a flow forward that the full-model render (file order)
+        // draws right-to-left; that is an error, never a special render.
+        for (const edge of semanticEdges(model)) {
+            if (edge.source === "loops-to")
+                continue;
+            const from = model.byId.get(edge.from);
+            const to = model.byId.get(edge.to);
+            if (!from || !to || from.sliceIndex === to.sliceIndex)
+                continue;
+            if (!composedButRenderedBackward(model, from.sliceIndex, to.sliceIndex))
+                continue;
+            const fromStory = model.slices[from.sliceIndex].storyline;
+            const toStory = model.slices[to.sliceIndex].storyline;
+            const toAfter = findStoryline(model, toStory ?? "")?.after;
+            const fromSlice = model.slices[from.sliceIndex].name;
+            pushDiag(diags, "storyline-after-out-of-order", {
+                message: `time flows left to right: "${from.name}" (slice "${fromSlice}", storyline "${fromStory}") feeds ` +
+                    `"${to.name}" (slice "${model.slices[to.sliceIndex].name}", storyline "${toStory}"), but ` +
+                    (toAfter !== undefined ? `\`after "${toAfter}"\` ` : "the storyline's `after` clause ") +
+                    `places "${toStory}" later on the composed timeline than slice "${fromSlice}", while the file declares it above, ` +
+                    `so the full-model render would draw this arrow right-to-left; move this storyline block below slice "${fromSlice}"`,
+                line: to.line,
+                refs: [refOf(from.id), refOf(to.id)],
+            });
+        }
+    }
+    // Advisory shape lints (GH #292): outcome-split reactions, retry slices.
+    shapeDiagnostics(model, refs, diags);
     // Open issues (`issue "text"`) are always surfaced as a warning — the red-note
     // device for a question that hasn't been resolved yet.
     for (const el of model.elements) {
@@ -609,11 +754,65 @@ export function validate(model, grid, refs) {
             });
         }
     }
+    // GH #279: a logical event recorded at several sites must agree on its declaration. Later
+    // sites with no fields / tags / `public` inherited the first's (model.ts); one that declares
+    // a different one is an error.
+    const tagSig = (t) => JSON.stringify((t ?? []).map((x) => [x.key, x.kind, x.fields ?? null, x.description ?? null]));
+    for (const el of model.elements) {
+        if (el.kind !== "event" || el.logicalId === el.id)
+            continue;
+        const first = model.byId.get(el.logicalId);
+        if (!first)
+            continue;
+        const differs = [];
+        if (el.fields !== first.fields && JSON.stringify(el.fields ?? []) !== JSON.stringify(first.fields ?? []))
+            differs.push("different fields");
+        if (el.tags !== first.tags && tagSig(el.tags) !== tagSig(first.tags))
+            differs.push("different tags");
+        if ((el.public === true) !== (first.public === true))
+            differs.push("a different public marker");
+        if (differs.length === 0)
+            continue;
+        pushDiag(diags, "shared-event-field-mismatch", {
+            message: `event "${el.name}" is recorded again in slice ${el.sliceIndex + 1} with ${differs.join(" and ")} ` +
+                `than its first declaration (slice ${first.sliceIndex + 1}); repeat the event bare ` +
+                `to inherit its fields, tags and public, or make them identical`,
+            line: el.line,
+            refs: [refOf(el.id), refOf(first.id)],
+        });
+    }
+    // GH #278: one command repeated across slices — a column per outcome. Continuation slices
+    // (every non-`ui` element an `again` view) declare no command, so none can contribute here.
+    const commandSlices = new Map();
+    for (const el of model.elements) {
+        if (el.kind !== "command")
+            continue;
+        const k = normalizeName(el.name);
+        const bucket = commandSlices.get(k);
+        if (bucket)
+            bucket.push(el);
+        else
+            commandSlices.set(k, [el]);
+    }
+    for (const els of commandSlices.values()) {
+        const slices = [...new Set(els.map((e) => e.sliceIndex))];
+        if (slices.length < 2)
+            continue;
+        pushDiag(diags, "command-repeated-across-slices", {
+            message: `command "${els[0].name}" is declared in ${slices.length} slices (${slices.map((i) => `"${model.slices[i].name}"`).join(", ")}); ` +
+                `one command with several possible outcomes is ONE slice — record them as ` +
+                `\`event A | B @Context\` alternatives instead of one column per event`,
+            line: els[1].line,
+            refs: els.map((e) => refOf(e.id)),
+        });
+    }
     // Ambiguous names (used by arrows / view sources) get a heads-up.
     for (const [key, els] of model.byName) {
         // Later \`again\` instances of a view are the SAME logical read model reappearing on the
         // timeline — deliberate, not an ambiguity. Only warn when a duplicate is NOT an instance.
-        const nonInstances = els.filter((e, i) => i === 0 || !(e.kind === "view" && e.again));
+        // Likewise an event recorded again in the same context is one logical event (GH #279), so
+        // only a same-name event in a DIFFERENT context (or a non-event) counts as a collision.
+        const nonInstances = els.filter((e, i) => i === 0 || !((e.kind === "view" && e.again) || (e.kind === "event" && e.logicalId !== e.id)));
         if (nonInstances.length > 1 && isReferenced(model, key)) {
             pushDiag(diags, "duplicate-name", {
                 message: `name "${els[0].name}" is defined ${nonInstances.length} times; ` +
@@ -743,6 +942,82 @@ export function validate(model, grid, refs) {
             refs: [...new Set(decls.map((d) => refOf(d.element.id)))],
         });
     }
+    diags.push(...timelineEntityClustered(model, refs.sliceKeys));
+    return diags;
+}
+/** Minimum run length for `timeline-entity-clustered` (GH #281). A future config knob; the
+ *  value is set by measurement (see the PR): no shipped example, skill em block or real model
+ *  has a qualifying run even at 2, so 3 is conservative. */
+export const TIMELINE_ENTITY_CLUSTER_MIN_RUN = 3;
+/** `timeline-entity-clustered` (GH #281): a run of >= N consecutive State Change slices whose
+ *  events all sit on ONE context, where the first view-bearing slice from the run onward reads
+ *  only that context and no view fed by another context sits inside the run — the
+ *  lifecycle-per-entity (CRUD-on-a-timeline) shape. Exempt below 2 distinct write contexts. A trailing
+ *  `again` view is judged by the logical view's union of sources. Fires once per maximal run, with `refs`
+ *  naming every slice key in the run. */
+function timelineEntityClustered(model, sliceKeys) {
+    const diags = [];
+    // Interleaving contexts is the fix, so a model with fewer than 2 distinct write contexts
+    // (no `@Context` at all, or every event on one) has nothing to interleave: exempt.
+    const writeContexts = new Set();
+    for (const slice of model.slices)
+        for (const e of slice.elements)
+            if (e.kind === "event")
+                writeContexts.add(e.context);
+    if (writeContexts.size < 2)
+        return diags;
+    const sliceInfo = model.slices.map((slice) => {
+        const events = slice.elements.filter((e) => e.kind === "event");
+        const views = slice.elements.filter((e) => e.kind === "view");
+        const eventContexts = new Set(events.map((e) => e.context));
+        const viewCtx = new Set();
+        for (const v of views) {
+            const names = viewSourceNames(model, v);
+            if (names.length === 0)
+                for (const c of eventContexts)
+                    viewCtx.add(c);
+            for (const n of names)
+                viewCtx.add(model.byName.get(normalizeName(n))?.find((e) => e.kind === "event")?.context);
+        }
+        const isStateChange = classifySlicePattern(slice) === "state-change" && events.length > 0;
+        return {
+            slice,
+            views: views.length,
+            viewCtx,
+            // The single context this slice writes, or null when it is not a single-context State Change slice.
+            context: isStateChange && eventContexts.size === 1 ? ([...eventContexts][0] ?? null) : null,
+        };
+    });
+    let i = 0;
+    while (i < sliceInfo.length) {
+        const ctx = sliceInfo[i].context;
+        if (ctx === null || ![...sliceInfo[i].viewCtx].every((c) => c === ctx)) {
+            i++;
+            continue;
+        }
+        let j = i;
+        // Extend while the slice writes ctx and any view it carries reads only ctx.
+        while (j < sliceInfo.length && sliceInfo[j].context === ctx && [...sliceInfo[j].viewCtx].every((c) => c === ctx))
+            j++;
+        const run = sliceInfo.slice(i, j);
+        if (run.length >= TIMELINE_ENTITY_CLUSTER_MIN_RUN) {
+            const trailing = sliceInfo.slice(i).find((s) => s.views > 0);
+            if (trailing && [...trailing.viewCtx].every((c) => c === ctx)) {
+                const first = run[0].slice;
+                const last = run[run.length - 1].slice;
+                pushDiag(diags, "timeline-entity-clustered", {
+                    message: `${run.length} consecutive State Change slices ("${first.name}" through "${last.name}") all write ` +
+                        `context "${ctx}" and only that context is read next. If these are create/update/archive operations ` +
+                        `on one entity, order the slices by the business journey, interleaving contexts as the story does ` +
+                        `(see docs/storyline.md); if they are consecutive steps of one journey, show the screen the user ` +
+                        `sees between them (a view after each step)`,
+                    line: first.line,
+                    refs: run.map((s) => sliceKeys[s.slice.index]),
+                });
+            }
+        }
+        i = j;
+    }
     return diags;
 }
 const PUBLIC_TYPE_TABLE_TEXT = PUBLIC_SCALAR_TYPE_NAMES.join(", ");
@@ -825,9 +1100,7 @@ function computeViewReaders(model) {
             if (!bucket)
                 continue;
             const views = bucket.filter((x) => x.kind === "view");
-            const atOrBefore = views
-                .filter((x) => x.sliceIndex <= el.sliceIndex)
-                .sort((a, b) => b.sliceIndex - a.sliceIndex);
+            const atOrBefore = views.filter((x) => !isLaterOnTimeline(model, x.sliceIndex, el.sliceIndex));
             if (atOrBefore.length === 0) {
                 if (views[0])
                     readByArrowOrFrom.add(views[0].id);
@@ -837,7 +1110,7 @@ function computeViewReaders(model) {
                     readByArrowOrFrom.add(v.id);
             }
             else {
-                readByArrowOrFrom.add(atOrBefore[0].id);
+                readByArrowOrFrom.add(latestOnTimeline(model, atOrBefore, el.sliceIndex).id);
             }
         }
     }
@@ -974,6 +1247,36 @@ function withArticle(kind) {
     const label = kindLabel(kind);
     return `${/^[aeiou]/.test(label) ? "an" : "a"} ${label}`;
 }
+/** True when the event is one of several recording sites of one logical event (GH #279). */
+function isSharedEventSite(model, el) {
+    if (el.kind !== "event")
+        return false;
+    return (model.byName.get(normalizeName(el.name)) ?? []).some((x) => x.id !== el.id && x.kind === "event" && x.logicalId === el.logicalId);
+}
+/** A recording site is read when a view at or after its slice names the event (`from`, or a
+ *  `from`-less view in the same slice), a resolved `loops-to` leaves it, or an explicit arrow
+ *  leads from the event to a view at or after it. */
+function sharedSiteHasReader(model, site) {
+    const key = normalizeName(site.name);
+    for (const v of model.elements) {
+        if (v.kind !== "view" || isEarlierOnTimeline(model, v.sliceIndex, site.sliceIndex))
+            continue;
+        const from = v.from ?? [];
+        if (from.length ? from.some((n) => normalizeName(n) === key) : v.sliceIndex === site.sliceIndex)
+            return true;
+    }
+    for (const name of site.loopsTo ?? [])
+        if (resolveLoopsToTarget(model, site, name))
+            return true;
+    for (const a of model.arrows) {
+        if (normalizeName(a.from) !== key)
+            continue;
+        const to = a.toId ? model.byId.get(a.toId) : undefined;
+        if (to?.kind === "view" && !isEarlierOnTimeline(model, to.sliceIndex, site.sliceIndex))
+            return true;
+    }
+    return false;
+}
 function isReferenced(model, key) {
     for (const a of model.arrows) {
         if (normalizeName(a.from) === key || normalizeName(a.to) === key)