@beehexa/hexasync-template-worker-flow 2608.20.18 → 2608.20.31

package/dist/render.js

@@ -0,0 +1,157 @@
+/**
+ * `renderMermaid` / `renderMarkdown` for a worker flow — Story 4.3, `PACKAGE-CONTRACT.md` §5.
+ *
+ * Thin by design. The emission rules live in `hexasync-template-model`'s `flowRender`, because AD-21 forbids the two
+ * flow packages importing each other and the shared half has to live somewhere neither owns. This file's whole job is
+ * to say what a WORKER node looks like: which shape it takes, what its label reads, and how stages become subgraphs.
+ */
+import { renderFlowMermaid, composeNodeLabel, renderFlowMarkdown, } from '@beehexa/hexasync-template-model';
+/**
+ * A node's label.
+ *
+ * A synthesised node reads as its own `label` — the condition, the expression, the unresolved target — which is why
+ * `FlowNode` carries one at all (Story 4.1 review, HIGH-3).
+ *
+ * ⚠️ A step reads as its **`name`**, falling back to its key. The first version used the key alone and defended it by
+ * citing a FRONTEND node that shows a name, so the evidence argued the other way. All three baselines draw the name:
+ * the CLI report `["Get Sales Return Detail"]`, the extension `{"GET_…<br/>Get Sales Return Detail"}`.
+ *
+ * The extension's `<br/>` form cannot be produced through this renderer, deliberately: `escapeLabel` escapes `<` and
+ * `>`, so a literal `<br/>` would render as text. A two-line label is a RENDERER capability, not a model one, and
+ * belongs in whatever option the extension needs rather than smuggled through a label string.
+ */
+function labelOf(node) {
+    // COMPOSED, not a fallback chain (2026-08-20). This was
+    // `node.label ?? node.name ?? node.stepKey ?? node.address`, so a step with a name drew its name and
+    // dropped the key and the type — both already on the node. A reader beside the YAML could not tell which
+    // `key:` a box was, and `next:`/`outputs:` reference steps BY KEY. One composer for both runtimes, in
+    // `template-model`, so the two diagrams cannot start labelling differently.
+    return composeNodeLabel(node);
+}
+/** Stages become subgraphs, in the order the model reports them. */
+/**
+ * Stages become subgraphs — and a stage that drew NOTHING is omitted entirely (Story 4.3 review, HIGH-1).
+ *
+ * `stagesPresent` counts a stage present when its array is non-empty, but `stepOf` can drop every element (no `key`, or
+ * the composer's `!` removal). The stage then had zero nodes and was still emitted: an empty `subgraph … / direction TB
+ * / end`, and — because `firstOf` never got an entry — **every stage arrow touching it disappeared**, so the chart
+ * asserted the surviving stages were unrelated. Both authorities remove empty stages so their chain collapses instead.
+ */
+function groupsOf(flow) {
+    return flow.stages
+        .map((stage) => ({
+        key: `${flow.address}:${stage.key}`,
+        title: stage.label,
+        nodes: flow.nodes
+            .filter((node) => node.stage === stage.key)
+            .map((node) => ({
+            address: node.address,
+            label: labelOf(node),
+            decides: node.decides,
+            // A dead end and a cycle marker are terminals; a condition or an expression is a diamond.
+            terminal: node.junction === 'unknown',
+        })),
+    }))
+        .filter((group) => group.nodes.length > 0);
+}
+/**
+ * Stage-to-stage arrows: **every terminal of the source stage → every ENTRY of the target**, which is the CLI's
+ * geometry and therefore the one the composition report must reproduce (Story 4.6).
+ *
+ * ⛔ The first version drew ONE arrow, from each stage's first document-order step. That was a **fourth** geometry
+ * where `epic-4-ground-truth.md` records three and says one must be chosen — and it was semantically wrong: an
+ * `on error` arrow leaving only the first step reads as *"only that step can fail"*. The extension's own docblock
+ * argues exactly against it: *"picking one of them would draw a claim about ordering that the YAML does not make."*
+ * Worse, the file's comment cited *"node→node (CLI, terminal to entry)"* and then implemented entry→entry.
+ *
+ * A **terminal** is a step no route leaves — the honest source of "what happens after this stage". An **entry** is a
+ * step marked `rootStep`, falling back to the first, which is how dashboard chooses its target. Both facts now exist in
+ * the model; neither did before.
+ */
+function stageEdgesOf(flow) {
+    const stepsOf = (stage) => flow.nodes.filter((node) => node.stage === stage && node.stepKey !== undefined);
+    /** Steps with no outgoing route edge — where a stage actually finishes. */
+    const terminalsOf = (stage) => {
+        const steps = stepsOf(stage);
+        const leaves = new Set(flow.edges.filter((e) => e.stage === stage).map((e) => e.from));
+        const terminals = steps.filter((node) => !leaves.has(node.address));
+        // A stage whose every step routes onward (a loop) has no terminal; its last step is the honest stand-in.
+        return terminals.length > 0 ? terminals : steps.slice(-1);
+    };
+    const entriesOf = (stage) => {
+        const steps = stepsOf(stage);
+        const declared = steps.filter((node) => node.isEntry === true);
+        return declared.length > 0 ? declared : steps.slice(0, 1);
+    };
+    /**
+     * A stage that drew NOTHING is collapsed THROUGH, not merely omitted (Story 4.4 review, MED-6).
+     *
+     * ⛔ Story 4.3's fix omitted the empty subgraph and stopped there — so every stage arrow touching it still vanished,
+     * and the chart went on asserting that the stages either side were unrelated. Half a fix reads exactly like the whole
+     * one until something builds the case: no real corpus component has a stage whose every step is dropped, so only a
+     * hand-built one can falsify it.
+     *
+     * Both authorities collapse: dashboard's `pusherPhases` and the extension's `drawable` filter both REMOVE an empty
+     * stage, so `beforePull → afterPull` survives. The stage order is the model's, so following it forward is the same
+     * walk either of them does.
+     */
+    const order = flow.stages.map((stage) => stage.key);
+    const drawn = (stage) => stepsOf(stage).length > 0;
+    /** The next stage at or after `stage` that actually drew something. */
+    const forwardTo = (stage) => {
+        for (let index = order.indexOf(stage); index < order.length; index += 1) {
+            const candidate = order[index];
+            if (drawn(candidate))
+                return candidate;
+        }
+        return undefined;
+    };
+    const seen = new Set();
+    return flow.stageEdges.flatMap((edge) => {
+        if (!drawn(edge.from))
+            return [];
+        const to = forwardTo(edge.to);
+        if (to === undefined || to === edge.from)
+            return [];
+        // Two collapsed hops can arrive at the same pair; one arrow is enough.
+        const key = `${edge.from} ${to} ${edge.label ?? ''}`;
+        if (seen.has(key))
+            return [];
+        seen.add(key);
+        return terminalsOf(edge.from).flatMap((from) => entriesOf(to).map((entry) => ({
+            from: from.address,
+            to: entry.address,
+            ...(edge.label !== undefined ? { label: edge.label } : {}),
+        })));
+    });
+}
+export function renderMermaid(flow, opts = {}) {
+    return renderFlowMermaid(groupsOf(flow), [...flow.edges, ...stageEdgesOf(flow)], opts);
+}
+/**
+ * Markdown for one component — `(flow, opts)`, matching the frontend twin and `PACKAGE-CONTRACT.md` §5.
+ *
+ * ⛔ This took `(flow, title, opts)` (Story 4.3 review, MEDIUM-1). §5 declares `renderMarkdown(model, opts?)`
+ * *"exported from both flow packages"*, so a caller written to the contract passed the options object into the `title`
+ * slot and it reached `escapeLabel`: **`TypeError: value.replace is not a function`**. TypeScript caught it for TS
+ * consumers; JS consumers and the "one renderer set, callable uniformly" premise did not.
+ *
+ * The title now comes from the model, which has everything needed: the collection and the component's authored id. A
+ * caller wanting its own wording passes `title`.
+ */
+export function renderMarkdown(flow, opts = {}) {
+    const title = opts.title ?? titleOf(flow);
+    return renderFlowMarkdown(title, groupsOf(flow), [...flow.edges, ...stageEdgesOf(flow)], opts);
+}
+/**
+ * A default title from the model.
+ *
+ * The authored id rather than a composed GUID, for AD-33's reason: it is the form that is identical across
+ * environments. `pullers:id_**XPullerId**` reads as `**XPullerId**`, which is what an author typed.
+ */
+function titleOf(flow) {
+    const identity = flow.address.split(':').at(-1) ?? flow.address;
+    const singular = flow.collection === 'pullers' ? 'Puller' : 'Pusher';
+    return `${singular} ${identity.replace(/^id_/, '')}`;
+}
+//# sourceMappingURL=render.js.map

package/dist/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,GAInB,MAAM,kCAAkC,CAAC;AAG1C;;;;;;;;;;;;;GAaG;AACH,SAAS,OAAO,CAAC,IAAiC;IAChD,wDAAwD;IACxD,qGAAqG;IACrG,yGAAyG;IACzG,sGAAsG;IACtG,4EAA4E;IAC5E,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC;AAChC,CAAC;AAED,oEAAoE;AACpE;;;;;;;GAOG;AACH,SAAS,QAAQ,CAAC,IAAgB;IAChC,OAAO,IAAI,CAAC,MAAM;SACf,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACf,GAAG,EAAE,GAAG,IAAI,CAAC,OAAO,IAAI,KAAK,CAAC,GAAG,EAAE;QACnC,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,KAAK,EAAE,IAAI,CAAC,KAAK;aACd,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC,GAAG,CAAC;aAC1C,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACd,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC;YACpB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,0FAA0F;YAC1F,QAAQ,EAAE,IAAI,CAAC,QAAQ,KAAK,SAAS;SACtC,CAAC,CAAC;KACN,CAAC,CAAC;SACF,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAS,YAAY,CAAC,IAAgB;IACpC,MAAM,OAAO,GAAG,CAAC,KAAa,EAAE,EAAE,CAChC,IAAI,CAAC,KAAK,CAAC,MAAM,CACf,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,KAAK,KAAK,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,CAC7D,CAAC;IAEJ,2EAA2E;IAC3E,MAAM,WAAW,GAAG,CAAC,KAAa,EAAE,EAAE;QACpC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;QAC7B,MAAM,MAAM,GAAG,IAAI,GAAG,CACpB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAC/D,CAAC;QACF,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QACpE,yGAAyG;QACzG,OAAO,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5D,CAAC,CAAC;IAEF,MAAM,SAAS,GAAG,CAAC,KAAa,EAAE,EAAE;QAClC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;QAC7B,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC;QAC/D,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5D,CAAC,CAAC;IAEF;;;;;;;;;;;OAWG;IACH,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpD,MAAM,KAAK,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;IAC3D,uEAAuE;IACvE,MAAM,SAAS,GAAG,CAAC,KAAa,EAAsB,EAAE;QACtD,KAAK,IAAI,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;YACxE,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAE,CAAC;YAChC,IAAI,KAAK,CAAC,SAAS,CAAC;gBAAE,OAAO,SAAS,CAAC;QACzC,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC;IAEF,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;QACtC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,EAAE,CAAC;QACjC,MAAM,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC9B,IAAI,EAAE,KAAK,SAAS,IAAI,EAAE,KAAK,IAAI,CAAC,IAAI;YAAE,OAAO,EAAE,CAAC;QACpD,uEAAuE;QACvE,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,IAAI,IAAI,EAAE,IAAI,IAAI,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;QACrD,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,EAAE,CAAC;QAC7B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,OAAO,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAC7C,SAAS,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YAC5B,IAAI,EAAE,IAAI,CAAC,OAAO;YAClB,EAAE,EAAE,KAAK,CAAC,OAAO;YACjB,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC3D,CAAC,CAAC,CACJ,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,IAAgB,EAChB,IAAI,GAAkB,EAAE;IAExB,OAAO,iBAAiB,CACtB,QAAQ,CAAC,IAAI,CAAC,EACd,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC,EACtC,IAAI,CACL,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAgB,EAChB,IAAI,GAAgD,EAAE;IAEtD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,OAAO,kBAAkB,CACvB,KAAK,EACL,QAAQ,CAAC,IAAI,CAAC,EACd,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC,EACtC,IAAI,CACL,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,OAAO,CAAC,IAAgB;IAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC;IAChE,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;IACrE,OAAO,GAAG,QAAQ,IAAI,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC;AACvD,CAAC"}

package/dist/routeGraph.d.ts

@@ -0,0 +1,41 @@
+import { type RoutableStep } from './routes.js';
+/** What a synthesised node is, so a renderer picks a shape without inspecting the label. */
+export type JunctionKind = 'if' | 'expression' | 'unknown';
+/** A node the document does not declare, produced because a route needs somewhere to branch. */
+export interface Junction {
+    /** Relative path from the owning step, e.g. `['next', 'if']`. The caller prefixes the step's address. */
+    readonly path: readonly string[];
+    readonly kind: JunctionKind;
+    /** The text a renderer draws in it: the condition, the expression, or the unresolved target. */
+    readonly label: string;
+    /** The step key that produced it. */
+    readonly owner: string;
+}
+/** An edge in the route graph. Ends are either a step key or a junction path, tagged so the caller can address it. */
+export interface GraphEdge {
+    readonly from: EdgeEnd;
+    readonly to: EdgeEnd;
+    readonly label?: string;
+}
+export type EdgeEnd = {
+    readonly kind: 'step';
+    readonly key: string;
+} | {
+    readonly kind: 'junction';
+    readonly owner: string;
+    readonly path: readonly string[];
+};
+export interface RouteGraph {
+    readonly junctions: readonly Junction[];
+    readonly edges: readonly GraphEdge[];
+}
+/**
+ * Every junction and every edge for the steps of ONE stage.
+ *
+ * Iterative over an explicit work list, never recursive — `then`/`else` nest without bound and a document is
+ * untrusted input. The work list carries the PATH, which is what makes the addressing positional-free.
+ */
+export declare function routeGraph(steps: readonly RoutableStep[]): RouteGraph;
+/** The address of a junction, given its owning step's address. AD-33 rule 4 / rule 5. */
+export declare function junctionAddress(ownerAddress: string, path: readonly string[]): string;
+//# sourceMappingURL=routeGraph.d.ts.map

package/dist/routeGraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routeGraph.d.ts","sourceRoot":"","sources":["../src/routeGraph.ts"],"names":[],"mappings":"AAqCA,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AAErB,4FAA4F;AAC5F,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,YAAY,GAAG,SAAS,CAAC;AAE3D,gGAAgG;AAChG,MAAM,WAAW,QAAQ;IACvB,yGAAyG;IACzG,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,gGAAgG;IAChG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,sHAAsH;AACtH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,OAAO,GACf;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC/C;IACE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC,CAAC;AAEN,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;CACtC;AAID;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,UAAU,CAsMrE;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAC7B,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,MAAM,CAOR"}

package/dist/routeGraph.js

@@ -0,0 +1,214 @@
+/**
+ * The route GRAPH — edges that pass THROUGH the nodes a branch synthesises.
+ *
+ * ### Why this exists alongside `routeEdges`, which is flat
+ *
+ * ⛔ The first version of this package had `routeEdges` only, and `flow.ts` synthesised a decision node beside it
+ * without connecting the two. The Story 4.1 review measured what that produced: a diamond with **zero** edges
+ * touching it, while the YES/NO arms left the step — so the diamond was unreachable and undrawable, and the step
+ * carried arms it does not have. Worse, it synthesised for the ~22 corpus steps with an object-valued `next` and
+ * produced **no** node for the **3,480** with an expression-valued one, which is exactly where both shipped
+ * surfaces DO synthesise (`_EXPR_<n>` in `flowChart.ts:145-155`, in the golden baseline for fixture 01).
+ *
+ * `routeEdges` is kept because it answers a genuinely different question — *"what routes where"*, flat, which is
+ * what `flowEdges` answers and what `routeParity.spec.ts` compares. This answers *"how is it drawn"*, and
+ * `routeGraph.spec.ts` asserts the two agree about reachability so they cannot drift.
+ *
+ * ### The three synthesised kinds, from the shipped baseline
+ *
+ * | kind | when | drawn as | label |
+ * | --- | --- | --- | --- |
+ * | `if` | an object route `{ if, then, else }` | diamond | the `if` text, or `?` |
+ * | `expression` | a Scriban route naming ≥1 real step | diamond | the expression |
+ * | `unknown` | a route naming no step at all | stadium | the route text |
+ *
+ * ### Addressed by PATH, per AD-33 rule 4
+ *
+ * A structural node is *"named by the keys that reach it"*. So the junction for a step's object `next` is
+ * `<step>:next:if` — AD-33's own example — a nested arm is `<step>:next:then:if`, an `IF` branching through `data`
+ * is `<step>:data:if`, and an expression is `<step>:next:expression`. No counter anywhere, so inserting a step above
+ * renumbers nothing. The path also disambiguates naturally: two dead ends leaving one step reach it by different
+ * keys (`:next:unknown` and `:onError:unknown`), so neither needs an index.
+ */
+import { keySegment, entrySegment, nodeAddress, } from '@beehexa/hexasync-template-model';
+import { looksLikeExpression, quotedKeys, } from './routes.js';
+const step_ = (key) => ({ kind: 'step', key });
+/**
+ * Every junction and every edge for the steps of ONE stage.
+ *
+ * Iterative over an explicit work list, never recursive — `then`/`else` nest without bound and a document is
+ * untrusted input. The work list carries the PATH, which is what makes the addressing positional-free.
+ */
+export function routeGraph(steps) {
+    const known = new Set(steps.map((s) => String(s.key)));
+    const junctions = [];
+    const edges = [];
+    /** Junctions already created, so two routes reaching the same path share one node. */
+    const seen = new Set();
+    const junction = (owner, path, kind, label) => {
+        const id = `${owner} ${path.join(' ')}`;
+        if (!seen.has(id)) {
+            seen.add(id);
+            junctions.push({ owner, path, kind, label });
+        }
+        return { kind: 'junction', owner, path };
+    };
+    for (const step of steps) {
+        const owner = String(step.key);
+        const type = String(step.stepType ?? '').toUpperCase();
+        const isBranchObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+        /**
+         * Branch objects already entered on THIS step's walk — the cycle guard.
+         *
+         * ⛔ Without it a cyclic branch does not merely loop, it **kills the process**. Found by the Story 4.2 review and
+         * confirmed here: `const a = {}; a.then = a; routeGraph([{ key: 'A', next: a }])` exits **134**, `FATAL ERROR:
+         * heap out of memory`, in a few seconds. The `path` grows by two segments per iteration, `seen` is keyed by that
+         * path so it never repeats, and both `junctions` and the work list grow without bound.
+         *
+         * This module's own docblock argued *"iterative, never recursive — a document is untrusted input"*. Iteration was
+         * the right call and it removed the only thing that had been bounding this: the reference implementation recurses
+         * and throws a **catchable** `RangeError`. An uncatchable V8 fatal is strictly worse, and this package is bundled
+         * into the VS Code extension host, so the blast radius is the editor process.
+         *
+         * REACHABLE FROM YAML with the parser the CLI already uses — a recursive anchor is all it takes:
+         *
+         * ```yaml
+         * next: &loop
+         *   if: "x"
+         *   then: *loop
+         * ```
+         *
+         * Identity, not path: the same object reached twice is the cycle, however long the path to it.
+         */
+        const entered = new WeakSet();
+        /** Work list of routes still to place: where the arrow leaves, the value, the path, the label. */
+        const pending = [];
+        // ── Which route(s) this step declares, and under which key ──
+        //
+        // An IF whose `data` is an object but declares NEITHER `then` NOR `else` falls back to `next`. Without the
+        // fallback a partly-written IF loses its only edge and its target is orphaned in the diagram — `data:
+        // { expression: '…' }` with `next: 'DONE'` drew `CHECK → <diamond>` and nothing else, leaving `DONE` floating.
+        //
+        // This mirrors `routes.ts`, the flat twin, which has always had the fallback and says why in the same words. The
+        // two disagreed until Story 4.7's review measured it; this module's own docblock claimed the case "routed
+        // correctly through its `next`", which was aspiration rather than behaviour. `type` comes from `displayType`
+        // first, and every UI-served step carries one, so the divergence was reachable from a real surface.
+        const branching = (type === 'IF' || type === 'SWITCH') && isBranchObject(step.data);
+        const ifWithoutBranch = type === 'IF' &&
+            branching &&
+            step.data.then == null &&
+            step.data.else == null;
+        if (branching && !ifWithoutBranch) {
+            pending.push({ from: step_(owner), value: step.data, path: ['data'] });
+        }
+        else {
+            pending.push({ from: step_(owner), value: step.next, path: ['next'] });
+        }
+        if (step.onError !== null && step.onError !== undefined) {
+            pending.push({
+                from: step_(owner),
+                value: step.onError,
+                path: ['onError'],
+                label: 'onError',
+            });
+        }
+        while (pending.length > 0) {
+            const { from, value, path, label } = pending.pop();
+            if (value === null || value === undefined || value === '')
+                continue;
+            const labelled = label !== undefined ? { label } : {};
+            // ── An object route: a diamond, and its arms leave the DIAMOND, not the step ──
+            if (isBranchObject(value)) {
+                const branch = value;
+                if (entered.has(branch)) {
+                    /**
+                     * A cycle. Reported as a dead end labelled for what it is, rather than dropped: a route that loops back on
+                     * itself is a real document defect, and a diagram that simply stops there tells the reader nothing.
+                     */
+                    const point = junction(owner, [...path, 'cycle'], 'unknown', 'cycle: this branch refers to itself');
+                    edges.push({ from, to: point, ...labelled });
+                    continue;
+                }
+                entered.add(branch);
+                const isSwitch = type === 'SWITCH' && path.length === 1 && path[0] === 'data';
+                if (isSwitch) {
+                    // A SWITCH's arms are its data KEYS. The junction is the switch point itself.
+                    const point = junction(owner, [...path, 'switch'], 'if', 'SWITCH');
+                    edges.push({ from, to: point, ...labelled });
+                    for (const arm of Object.keys(branch)) {
+                        pending.push({
+                            from: point,
+                            value: arm,
+                            path: [...path, arm],
+                            label: arm,
+                        });
+                    }
+                    continue;
+                }
+                const condition = branch.if === null || branch.if === undefined
+                    ? '?'
+                    : String(branch.if);
+                const point = junction(owner, [...path, 'if'], 'if', condition);
+                edges.push({ from, to: point, ...labelled });
+                // `else` first so `then` is placed first — a reader expects YES before NO.
+                pending.push({
+                    from: point,
+                    value: branch.else,
+                    path: [...path, 'else'],
+                    label: 'NO',
+                });
+                pending.push({
+                    from: point,
+                    value: branch.then,
+                    path: [...path, 'then'],
+                    label: 'YES',
+                });
+                continue;
+            }
+            const text = String(value);
+            // ── A direct step key: a plain edge, no synthesis ──
+            if (known.has(text)) {
+                edges.push({ from, to: step_(text), ...labelled });
+                continue;
+            }
+            // ── An expression naming real steps: a diamond, then one arrow per target ──
+            if (looksLikeExpression(text)) {
+                const targets = quotedKeys(text).filter((k) => known.has(k));
+                if (targets.length > 0) {
+                    const point = junction(owner, [...path, 'expression'], 'expression', text);
+                    edges.push({ from, to: point, ...labelled });
+                    // Unlabelled, as the baseline draws them: which target it takes is a run-time fact.
+                    for (const target of targets) {
+                        edges.push({ from: point, to: step_(target) });
+                    }
+                    continue;
+                }
+            }
+            // ── Naming nothing: a terminal, kept so the reader sees the dead end ──
+            const point = junction(owner, [...path, 'unknown'], 'unknown', text);
+            edges.push({ from, to: point, ...labelled });
+        }
+        /**
+         * The exception BACK-REFERENCE, which is reversed: an edge INTO this step from the one that threw. No junction —
+         * it is a direct edge between two authored steps.
+         */
+        if (step.fromStep && known.has(step.fromStep)) {
+            edges.push({
+                from: step_(step.fromStep),
+                to: step_(owner),
+                label: 'Exception',
+            });
+        }
+    }
+    return { junctions, edges };
+}
+/** The address of a junction, given its owning step's address. AD-33 rule 4 / rule 5. */
+export function junctionAddress(ownerAddress, path) {
+    return nodeAddress([
+        keySegment(ownerAddress),
+        // A path element is a document key where it is one (`next`, `then`, `if`) and a dictionary tail where it is a
+        // SWITCH arm — `entrySegment` normalises both and refuses a `!`-prefixed one.
+        ...path.map((element) => entrySegment(element) ?? keySegment(element)),
+    ]);
+}
+//# sourceMappingURL=routeGraph.js.map

package/dist/routeGraph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routeGraph.js","sourceRoot":"","sources":["../src/routeGraph.ts"],"names":[],"mappings":"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"}

package/dist/routes.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Where a step goes next — Story 4.1 AC-2, all five kinds, in the MODEL rather than in a renderer.
+ *
+ * The semantics are the runtime's: `core.api/hexasync.steps/Execution/NextStepBuilder.cs` and `IfStepExecutor`.
+ * This package does not invent them; NFR-1 says the editor invents no semantics the runtime lacks.
+ *
+ * | kind | where it is declared | who drew it before |
+ * | --- | --- | --- |
+ * | by step TYPE | `IF` / `SWITCH` read their `data` | CLI only — dashboard reads only `step.next` |
+ * | by step DATA | `{ if, then, else }` on `next` or `data` | CLI |
+ * | an EXPRESSION | a Scriban `next` naming keys in quotes | CLI |
+ * | an ERROR route | `onError` | CLI |
+ * | an exception BACK-REFERENCE | `fromStep` → this step | **nobody** — see below |
+ *
+ * ### The back-reference is why routing has to live here
+ *
+ * `fromStep` produces an edge *into* the exception step from the step that threw. It exists **only in the CLI's
+ * drawing path** (`flowChart.ts:199-201` emits `fromStep --|"Exception"|-> this`) and **not** in the shared
+ * `flowEdges`. The VS Code extension imports `flowEdges`, so it has never drawn that edge at all — a whole route
+ * kind missing from one surface because the renderer, not the model, owned it. Moving routing into the model is what
+ * makes AC-2's last clause true everywhere, and it is the concrete argument for this package existing.
+ *
+ * ### An unresolvable route is REPORTED, not dropped
+ *
+ * A route naming no step in the stage yields an edge with `raw` and no `to`. A reader needs to see the dead end:
+ * silently dropping it draws a flow that terminates where the document does not say it terminates, which is the
+ * more expensive error. Same for an expression whose quoted keys match nothing.
+ */
+/** A step as routing needs to see it. Deliberately structural — this package reads no schema and no file. */
+export interface RoutableStep {
+    readonly key: string;
+    /** Raw `next`: a step key, a `{ if, then, else }` branch, a Scriban expression, or absent. */
+    readonly next?: unknown;
+    /** The step's declared type, e.g. `IF`, `SWITCH`. Compared case-insensitively. */
+    readonly stepType?: string;
+    /** For `IF`/`SWITCH`, the runtime passes `data` to the route builder. */
+    readonly data?: unknown;
+    /** A recovery target. */
+    readonly onError?: unknown;
+    /** An Exception step's back-reference: the step whose failure reaches this one. */
+    readonly fromStep?: string;
+}
+/** One arrow between two steps. */
+export interface RouteEdge {
+    /** The step the arrow leaves. */
+    readonly from: string;
+    /** The step it reaches, when that step exists in this stage. */
+    readonly to?: string;
+    /** `YES`, `NO`, a SWITCH branch name, `onError`, `Exception`. */
+    readonly label?: string;
+    /**
+     * The route text when it does not name a known step — an expression, or a dead end.
+     *
+     * Carried alongside `to` for an expression that DOES resolve, because which branch it takes at run time is a fact
+     * a static view cannot know, and showing the expression is how the reader learns that.
+     */
+    readonly raw?: string;
+}
+/** Every `"QUOTED_KEY"` in an expression. */
+export declare function quotedKeys(expression: string): readonly string[];
+/** Is this route text an expression rather than a step key? */
+export declare function looksLikeExpression(text: string): boolean;
+/**
+ * Every edge the steps of ONE stage declare.
+ *
+ * Iterative, never recursive: `then`/`else` nest without bound and a document is untrusted input, so a deep branch
+ * must not be able to exhaust the stack. (The same rule the puller step standards state: *no recursion — stack or
+ * loop*.)
+ */
+export declare function routeEdges(steps: readonly RoutableStep[]): readonly RouteEdge[];
+//# sourceMappingURL=routes.d.ts.map

package/dist/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,6GAA6G;AAC7G,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8FAA8F;IAC9F,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,yBAAyB;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,mCAAmC;AACnC,MAAM,WAAW,SAAS;IACxB,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,6CAA6C;AAC7C,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAEhE;AAED,+DAA+D;AAC/D,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIzD;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,SAAS,YAAY,EAAE,GAC7B,SAAS,SAAS,EAAE,CAmHtB"}