@arcote.tech/arc-process 0.7.28

package/src/state/store.ts

@@ -0,0 +1,55 @@
+/**
+ * Persystencja stanu widoku diagramu.
+ *
+ * `ProcessViewStore` to wspólny interfejs — fragment dostarcza:
+ *  - {@link localStorageStore} — fallback bez scope (klucz `arc-process:<docId>`),
+ *  - {@link functionStore} — adapter dla persystencji aplikacyjnej (np. agregat
+ *    z {@link createProcessViewAggregate} — aplikacja wiąże load/save ze swoim
+ *    scope w jednej linii),
+ *  - {@link memoryStore} — ulotny (testy, SSR).
+ */
+
+import type { ProcessViewState } from "./view-state";
+
+export interface ProcessViewStore {
+  load(docId: string): ProcessViewState | null;
+  save(docId: string, state: ProcessViewState): void;
+}
+
+/** Persystencja w localStorage — działa wszędzie, bez backendu i scope. */
+export function localStorageStore(prefix = "arc-process"): ProcessViewStore {
+  return {
+    load(docId) {
+      try {
+        const raw = globalThis.localStorage?.getItem(`${prefix}:${docId}`);
+        return raw ? (JSON.parse(raw) as ProcessViewState) : null;
+      } catch {
+        return null;
+      }
+    },
+    save(docId, state) {
+      try {
+        globalThis.localStorage?.setItem(`${prefix}:${docId}`, JSON.stringify(state));
+      } catch {
+        // localStorage niedostępny (SSR / private mode) — stan pozostaje ulotny.
+      }
+    },
+  };
+}
+
+/** Adapter funkcyjny — spina store z dowolną persystencją (agregat, API). */
+export function functionStore(
+  load: (docId: string) => ProcessViewState | null,
+  save: (docId: string, state: ProcessViewState) => void,
+): ProcessViewStore {
+  return { load, save };
+}
+
+/** Store w pamięci — do testów i renderu bez persystencji. */
+export function memoryStore(): ProcessViewStore {
+  const mem = new Map<string, ProcessViewState>();
+  return {
+    load: (docId) => mem.get(docId) ?? null,
+    save: (docId, state) => void mem.set(docId, state),
+  };
+}

package/src/state/view-state.ts

@@ -0,0 +1,88 @@
+/**
+ * Stan widoku diagramu procesu — otwarcia rozwinięć i zwinięcia kontekstów.
+ *
+ * Rozwinięcia adresowane są ŚCIEŻKĄ rozwinięcia ({@link ExpansionKey}):
+ * korzeń to occId kroku ("occ:o12"), dzieci doklejają segment
+ * "grupa:nodId" ("occ:o12/mutates:orderPaid") — dzięki temu każda
+ * doczepiona karteczka może rekurencyjnie otwierać własne relacje.
+ *
+ * React-free — reducer + budowa stanu startowego z MDX; persystencję
+ * zapewnia {@link ProcessViewStore} (localStorage / agregat).
+ */
+
+import type { ProcessModel } from "../model/types";
+
+/** Ścieżka rozwinięcia: "occ:<occId>" lub "<parentKey>/<grupa>:<nodId>". */
+export type ExpansionKey = string;
+
+export function rootKey(occId: string): ExpansionKey {
+  return `occ:${occId}`;
+}
+
+export function childKey(
+  parent: ExpansionKey,
+  group: string,
+  nodeId: string,
+): ExpansionKey {
+  return `${parent}/${group}:${nodeId}`;
+}
+
+export interface ProcessViewState {
+  /** Klucz rozwinięcia → otwarte grupy relacji. */
+  expanded: Record<ExpansionKey, string[]>;
+  /** Id kontekstu → zwinięty (override nad domyślnym trybem). */
+  collapsedContexts: Record<string, boolean>;
+}
+
+export const EMPTY_VIEW_STATE: ProcessViewState = {
+  expanded: {},
+  collapsedContexts: {},
+};
+
+/**
+ * Stan startowy z modelu: `<Arc expand={["mutates"]}>` otwiera grupy na
+ * korzeniu kroku. Deterministyczny — pierwszy render zawsze taki sam.
+ */
+export function initialViewState(model: ProcessModel): ProcessViewState {
+  const expanded: Record<ExpansionKey, string[]> = {};
+  for (const s of model.steps) {
+    if (s.expand?.length) expanded[rootKey(s.occId)] = [...s.expand];
+  }
+  return { expanded, collapsedContexts: {} };
+}
+
+/** Przełącz grupę rozwinięcia pod danym kluczem. */
+export function toggleGroup(
+  state: ProcessViewState,
+  key: ExpansionKey,
+  group: string,
+): ProcessViewState {
+  const current = state.expanded[key] ?? [];
+  const next = current.includes(group)
+    ? current.filter((g) => g !== group)
+    : [...current, group];
+  const expanded = { ...state.expanded };
+  if (next.length) expanded[key] = next;
+  else delete expanded[key];
+  // Zamknięcie grupy zamyka też rozwinięcia-dzieci pod tym kluczem.
+  if (!next.includes(group)) {
+    const prefix = `${key}/${group}:`;
+    for (const k of Object.keys(expanded)) {
+      if (k.startsWith(prefix)) delete expanded[k];
+    }
+  }
+  return { ...state, expanded };
+}
+
+/** Przełącz zwinięcie kontekstu (klik w box). */
+export function toggleContext(
+  state: ProcessViewState,
+  contextId: string,
+  defaultCollapsed: boolean,
+): ProcessViewState {
+  const current = state.collapsedContexts[contextId] ?? defaultCollapsed;
+  return {
+    ...state,
+    collapsedContexts: { ...state.collapsedContexts, [contextId]: !current },
+  };
+}

package/tests/arc-profile.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "bun:test";
+import { resolveArcRef, normalizePagePath } from "../src/profiles/arc";
+
+describe("normalizePagePath", () => {
+  test("strips query, hash and trailing slash; keeps root", () => {
+    expect(normalizePagePath("/checkout/success?orderId=1")).toBe("/checkout/success");
+    expect(normalizePagePath("/credits#top")).toBe("/credits");
+    expect(normalizePagePath("/checkout/")).toBe("/checkout");
+    expect(normalizePagePath("/")).toBe("/");
+  });
+});
+
+describe("resolveArcRef", () => {
+  test("page → identified by normalized path (not module key)", () => {
+    expect(resolveArcRef({ page: "/checkout/success?orderId=1" })).toMatchObject({
+      nodeId: "/checkout/success",
+      kind: "page",
+      key: "page:/checkout/success",
+    });
+  });
+
+
+  test("command / view / listener / route / event", () => {
+    expect(resolveArcRef({ command: "signIn" })).toMatchObject({ nodeId: "signIn", kind: "command", key: "command:signIn" });
+    expect(resolveArcRef({ view: "orders" })).toMatchObject({ nodeId: "orders", kind: "view" });
+    expect(resolveArcRef({ listener: "onX" })).toMatchObject({ nodeId: "onX", kind: "listener" });
+    expect(resolveArcRef({ route: "webhook" })).toMatchObject({ nodeId: "webhook", kind: "route" });
+    expect(resolveArcRef({ event: "taskCreated" })).toMatchObject({ nodeId: "taskCreated", kind: "event" });
+  });
+
+  test("aggregate alone → aggregate node", () => {
+    expect(resolveArcRef({ aggregate: "tasks" })).toMatchObject({ nodeId: "tasks", kind: "aggregate", key: "aggregate:tasks" });
+  });
+
+  test("aggregate + mutationMethod → aggregate node + method", () => {
+    const r = resolveArcRef({ aggregate: "userAccounts", mutationMethod: "checkEmail" });
+    expect(r).toMatchObject({
+      nodeId: "userAccounts",
+      kind: "aggregate",
+      method: { name: "checkEmail", kind: "mutation" },
+      key: "aggregate:userAccounts#mutate:checkEmail",
+    });
+  });
+
+  test("aggregate + queryMethod → query method", () => {
+    expect(resolveArcRef({ aggregate: "tasks", queryMethod: "getAll" })?.method).toEqual({ name: "getAll", kind: "query" });
+  });
+
+  test("aggregate + event → the event node", () => {
+    expect(resolveArcRef({ aggregate: "tasks", event: "taskCreated" })).toMatchObject({ nodeId: "taskCreated", kind: "event" });
+  });
+
+  test("no recognised prop → null", () => {
+    expect(resolveArcRef({})).toBeNull();
+  });
+});

package/tests/build.test.ts

@@ -0,0 +1,345 @@
+import { describe, expect, test } from "bun:test";
+import { buildProcessModel } from "../src/model/build";
+import {
+  arcProfile,
+  resolveArcRef,
+  toProcessGraph,
+  type ArcGraphEdge,
+  type ArcGraphInput,
+} from "../src/profiles/arc";
+import type {
+  Occurrence,
+  PathSeg,
+  StepOccurrence,
+} from "../src/model/types";
+
+function el(id: string, kind: string, extra: Record<string, unknown> = {}) {
+  return { id, name: id, kind, ...extra };
+}
+function edge(source: string, target: string, kind: string): ArcGraphEdge {
+  return { source, target, kind };
+}
+
+// cmd czyta v, zapisuje e; listener l też zapisuje e; v,x widoki; e event.
+const input: ArcGraphInput = {
+  elements: [
+    el("cmd", "command", { queryDeps: ["v"], mutationDeps: ["e"] }),
+    el("l", "listener", { mutationDeps: ["e"] }),
+    el("v", "view"),
+    el("e", "event"),
+    el("x", "view"),
+  ],
+  edges: [edge("cmd", "v", "queries"), edge("cmd", "e", "mutates"), edge("l", "e", "mutates")],
+  components: [],
+  componentEdges: [],
+};
+const graph = toProcessGraph(input);
+
+function occ(
+  occId: string,
+  props: Record<string, string>,
+  label = occId,
+  path?: PathSeg[],
+): StepOccurrence {
+  return { type: "step", occId, ref: resolveArcRef(props), label, path };
+}
+
+describe("buildProcessModel — parytet z buildUseCaseModel", () => {
+  test("one step per occurrence (duplicates kept)", () => {
+    const m = buildProcessModel({
+      graph,
+      profile: arcProfile,
+      occurrences: [occ("o1", { command: "cmd" }), occ("o2", { command: "cmd" })],
+    });
+    expect(m.steps.map((s) => s.occId)).toEqual(["o1", "o2"]);
+    expect(m.steps.map((s) => s.seq)).toEqual([1, 2]);
+    expect(m.steps.every((s) => s.exists)).toBe(true);
+  });
+
+  test("missing reference → step with exists=false", () => {
+    const m = buildProcessModel({
+      graph,
+      profile: arcProfile,
+      occurrences: [occ("o1", { command: "ghost" })],
+    });
+    expect(m.steps[0].exists).toBe(false);
+    expect(m.steps[0].node).toBeUndefined();
+  });
+
+  test("forward attachments exclude visible; query dep becomes attachment", () => {
+    const m = buildProcessModel({
+      graph,
+      profile: arcProfile,
+      occurrences: [occ("o1", { command: "cmd" }), occ("o2", { event: "e" })],
+    });
+    const cmd = m.steps.find((s) => s.occId === "o1")!;
+    expect(cmd.attachments.queries).toEqual(["v"]);
+    expect(cmd.attachments.mutates).toBeUndefined();
+  });
+
+  test("reverse mutatedBy attachment (e pisane przez cmd[widoczny] i l[ukryty])", () => {
+    const m = buildProcessModel({
+      graph,
+      profile: arcProfile,
+      occurrences: [occ("o1", { command: "cmd" }), occ("o2", { event: "e" })],
+    });
+    const e = m.steps.find((s) => s.occId === "o2")!;
+    expect(e.attachments.mutatedBy).toEqual(["l"]);
+  });
+
+  test("connector leży na SKIEROWANEJ ścieżce przepływu między krokami", () => {
+    const chain = toProcessGraph({
+      elements: [
+        el("cmd", "command", { mutationDeps: ["e"] }),
+        el("e", "event"),
+        el("l", "listener"),
+      ],
+      edges: [edge("cmd", "e", "emits"), edge("l", "e", "handles")],
+    });
+    const m = buildProcessModel({
+      graph: chain,
+      profile: arcProfile,
+      occurrences: [occ("o1", { command: "cmd" }), occ("o2", { listener: "l" })],
+    });
+    expect(m.connectors.map((c) => c.id)).toEqual(["e"]);
+    expect(m.connectors[0].between).toEqual([1, 2]);
+    expect(m.connectors[0].order).toBe(1);
+    expect(m.connectors[0].count).toBe(1);
+    expect(m.visible.has("e")).toBe(true);
+    expect(m.steps.find((s) => s.occId === "o1")!.attachments.mutates).toBeUndefined();
+  });
+
+  test("wspólny downstream NIE jest connectorem", () => {
+    const m = buildProcessModel({
+      graph,
+      profile: arcProfile,
+      occurrences: [occ("o1", { command: "cmd" }), occ("o2", { listener: "l" })],
+    });
+    expect(m.connectors.length).toBe(0);
+    expect(m.visible.has("e")).toBe(false);
+  });
+
+  test("usedByUI z componentEdges + referencje component", () => {
+    const ui = toProcessGraph({
+      elements: [el("acc", "aggregate")],
+      edges: [],
+      components: [
+        { id: "pkg/login.tsx", file: "pkg/login.tsx", name: "login" },
+        { id: "pkg/other.tsx", file: "pkg/other.tsx", name: "other" },
+      ],
+      componentEdges: [{ source: "pkg/login.tsx", target: "acc", usage: "query" }],
+    });
+    const m = buildProcessModel({
+      graph: ui,
+      profile: arcProfile,
+      occurrences: [occ("o1", { aggregate: "acc" })],
+    });
+    expect(m.steps[0].attachments.usedByUI).toEqual(["pkg/login.tsx"]);
+
+    const m2 = buildProcessModel({
+      graph: ui,
+      profile: arcProfile,
+      occurrences: [occ("o1", { component: "pkg/login.tsx" })],
+    });
+    expect(m2.steps[0].exists).toBe(true);
+    expect(m2.steps[0].node?.kind).toBe("page");
+  });
+
+  test("depth/lane: zwykła sekwencja inkrementuje depth, lane 0", () => {
+    const m = buildProcessModel({
+      graph,
+      profile: arcProfile,
+      occurrences: [occ("o1", { command: "cmd" }), occ("o2", { event: "e" })],
+    });
+    expect(m.steps.map((s) => [s.depth, s.lane])).toEqual([
+      [0, 0],
+      [1, 0],
+    ]);
+  });
+
+  test("depth/lane: <Parallel> dzieli lane'y na tej samej głębokości", () => {
+    const p = (occId: string, props: Record<string, string>, lane: number) =>
+      occ(occId, props, occId, [{ type: "parallel", id: "p1", laneIndex: lane }]);
+    const m = buildProcessModel({
+      graph,
+      profile: arcProfile,
+      occurrences: [
+        p("a", { command: "cmd" }, 0),
+        p("b", { view: "v" }, 1),
+        occ("c", { event: "e" }),
+      ],
+    });
+    const by = new Map(m.steps.map((s) => [s.occId, s]));
+    expect([by.get("a")!.depth, by.get("a")!.lane]).toEqual([0, 0]);
+    expect([by.get("b")!.depth, by.get("b")!.lane]).toEqual([0, 1]);
+    expect([by.get("c")!.depth, by.get("c")!.lane]).toEqual([1, 0]);
+  });
+
+  test("depth/lane: <Branch>/<Lane> ustawia alt i lane'y", () => {
+    const b = (occId: string, props: Record<string, string>, lane: number, title: string) =>
+      occ(occId, props, occId, [
+        { type: "branch", id: "br1", laneIndex: lane },
+        { type: "lane", id: `l${lane}`, title, alt: true },
+      ]);
+    const m = buildProcessModel({
+      graph,
+      profile: arcProfile,
+      occurrences: [b("ok", { view: "v" }, 0, "Sukces"), b("err", { event: "e" }, 1, "Błąd")],
+    });
+    const by = new Map(m.steps.map((s) => [s.occId, s]));
+    expect(by.get("ok")!.alt).toBe(true);
+    expect([by.get("ok")!.depth, by.get("ok")!.lane]).toEqual([0, 0]);
+    expect([by.get("err")!.depth, by.get("err")!.lane]).toEqual([0, 1]);
+    expect(by.get("ok")!.laneTitle).toBe("Sukces");
+  });
+
+  test("aggregate mutationMethod używa per-metodowych zależności", () => {
+    const agg = toProcessGraph({
+      elements: [
+        el("acc", "aggregate", {
+          methods: [
+            { name: "check", kind: "mutate", queryDeps: ["dirA"], mutationDeps: ["dirB"] },
+            { name: "other", kind: "mutate", queryDeps: ["zzz"], mutationDeps: [] },
+          ],
+        }),
+        el("dirA", "view"),
+        el("dirB", "event"),
+        el("zzz", "view"),
+      ],
+      edges: [],
+    });
+    const m = buildProcessModel({
+      graph: agg,
+      profile: arcProfile,
+      occurrences: [occ("o1", { aggregate: "acc", mutationMethod: "check" })],
+    });
+    expect(m.steps[0].attachments.queries).toEqual(["dirA"]);
+    expect(m.steps[0].attachments.mutates).toEqual(["dirB"]);
+  });
+});
+
+describe("buildProcessModel — fazy, Entry/Continue, notatki, konteksty", () => {
+  const entryPath = (id: string, title: string): PathSeg[] => [
+    { type: "entry", id, title },
+  ];
+  const phasePath = (phaseId: string, title?: string): PathSeg[] => [
+    { type: "step", id: `s-${phaseId}`, phaseId, title },
+  ];
+
+  test("Entry z Continue wpina się przed fazę docelową (depth) na osobnym torze", () => {
+    const occurrences: Occurrence[] = [
+      // Entry: dwa kroki → Continue do fazy "kwalifikacja".
+      occ("e1", { command: "cmd" }, "e1", entryPath("en1", "Formularz")),
+      occ("e2", { event: "e" }, "e2", entryPath("en1", "Formularz")),
+      { type: "continue", to: "kwalifikacja", path: entryPath("en1", "Formularz") },
+      // Oś główna: faza kwalifikacja o dwóch krokach.
+      occ("m1", { view: "v" }, "m1", phasePath("kwalifikacja")),
+      occ("m2", { view: "x" }, "m2", phasePath("kwalifikacja")),
+    ];
+    const m = buildProcessModel({ graph, profile: arcProfile, occurrences });
+    const by = new Map(m.steps.map((s) => [s.occId, s]));
+
+    // Oś główna zaczyna od depth 0.
+    expect([by.get("m1")!.depth, by.get("m1")!.lane]).toEqual([0, 0]);
+    expect([by.get("m2")!.depth, by.get("m2")!.lane]).toEqual([1, 0]);
+    // Entry (łańcuch L=2, cel depth 0) → start = max(0, 0-2) = 0, tor nad osią.
+    expect(by.get("e1")!.lane).toBeLessThan(0);
+    expect(by.get("e2")!.lane).toBe(by.get("e1")!.lane);
+    expect(by.get("e1")!.entryTitle).toBe("Formularz");
+    // Krawędź continues: ostatni krok Entry → pierwszy krok fazy.
+    expect(m.continueEdges).toEqual([
+      { fromOcc: "e2", toOcc: "m1", phaseId: "kwalifikacja" },
+    ]);
+  });
+
+  test("Entry wpinające się w ŚRODEK procesu dostaje depth przed fazą", () => {
+    const occurrences: Occurrence[] = [
+      occ("m1", { view: "v" }, "m1", phasePath("start")),
+      occ("m2", { view: "x" }, "m2", phasePath("wywiad")),
+      occ("m3", { event: "e" }, "m3", phasePath("wywiad")),
+      occ("a1", { command: "cmd" }, "a1", entryPath("en-admin", "Link admina")),
+      { type: "continue", to: "wywiad", path: entryPath("en-admin", "Link admina") },
+    ];
+    const m = buildProcessModel({ graph, profile: arcProfile, occurrences });
+    const by = new Map(m.steps.map((s) => [s.occId, s]));
+    // Faza "wywiad" zaczyna się na depth 1 → Entry (L=1) na depth 0.
+    expect(by.get("a1")!.depth).toBe(0);
+    expect(by.get("a1")!.lane).not.toBe(0);
+    expect(m.continueEdges).toEqual([
+      { fromOcc: "a1", toOcc: "m2", phaseId: "wywiad" },
+    ]);
+  });
+
+  test("dwa Entry rozkładają się naprzemiennie nad i pod osią", () => {
+    const occurrences: Occurrence[] = [
+      occ("f1", { command: "cmd" }, "f1", entryPath("en-a", "A")),
+      { type: "continue", to: "p", path: entryPath("en-a", "A") },
+      occ("g1", { listener: "l" }, "g1", entryPath("en-b", "B")),
+      { type: "continue", to: "p", path: entryPath("en-b", "B") },
+      occ("m1", { view: "v" }, "m1", phasePath("p")),
+    ];
+    const m = buildProcessModel({ graph, profile: arcProfile, occurrences });
+    const by = new Map(m.steps.map((s) => [s.occId, s]));
+    expect(by.get("f1")!.lane).toBeLessThan(0); // pierwsze nad osią
+    expect(by.get("g1")!.lane).toBeGreaterThan(0); // drugie pod osią
+    expect(m.continueEdges.length).toBe(2);
+  });
+
+  test("Entry bez Continue wpina się w pierwszą fazę dokumentu", () => {
+    const occurrences: Occurrence[] = [
+      occ("f1", { command: "cmd" }, "f1", entryPath("en-x", "X")),
+      occ("m1", { view: "v" }, "m1"),
+    ];
+    const m = buildProcessModel({ graph, profile: arcProfile, occurrences });
+    expect(m.continueEdges).toEqual([{ fromOcc: "f1", toOcc: "m1", phaseId: "" }]);
+  });
+
+  test("notatka dokleja się do poprzedzającego kroku", () => {
+    const occurrences: Occurrence[] = [
+      occ("m1", { view: "v" }, "m1"),
+      { type: "note", occId: "n1", text: "Ten widok admin wysyła linkiem.", side: "N" },
+      occ("m2", { event: "e" }, "m2"),
+    ];
+    const m = buildProcessModel({ graph, profile: arcProfile, occurrences });
+    expect(m.steps[0].notes).toEqual([
+      { occId: "n1", side: "N", title: undefined, text: "Ten widok admin wysyła linkiem." },
+    ]);
+    expect(m.steps[1].notes).toEqual([]);
+  });
+
+  test("<Arc context> rozwiązuje po kropkowanej ścieżce nazw", () => {
+    const g = toProcessGraph({
+      elements: [],
+      edges: [],
+      contexts: [
+        { id: "ctx_ai", path: ["ctx_ai"], name: "ai" },
+        { id: "ctx_chat", path: ["ctx_ai", "ctx_chat"], name: "chat", title: "Czat AI" },
+      ],
+    });
+    const occurrences: Occurrence[] = [
+      {
+        type: "step",
+        occId: "c1",
+        ref: { nodeId: "ai.chat", kind: "context", key: "context:ai.chat" },
+        label: "agent AI dopytuje",
+      },
+    ];
+    const m = buildProcessModel({ graph: g, profile: arcProfile, occurrences });
+    expect(m.steps[0].exists).toBe(true);
+    expect(m.steps[0].node?.kind).toBe("context");
+    expect(m.steps[0].node?.id).toBe("ctx:ctx_chat");
+    expect(m.steps[0].node?.label).toBe("Czat AI");
+    expect(m.steps[0].node?.contextPath).toEqual(["ctx_ai", "ctx_chat"]);
+  });
+
+  test("sides/expand z wystąpienia przechodzą na krok", () => {
+    const o: StepOccurrence = {
+      ...occ("o1", { command: "cmd" }),
+      sides: { mutates: "SE" },
+      expand: ["mutates"],
+    };
+    const m = buildProcessModel({ graph, profile: arcProfile, occurrences: [o] });
+    expect(m.steps[0].sides).toEqual({ mutates: "SE" });
+    expect(m.steps[0].expand).toEqual(["mutates"]);
+  });
+});