@supersoniks/concorde 5.1.1 → 5.1.3-immutable.1

package/src/core/utils/immutableValue.ts

@@ -0,0 +1,102 @@
+/**
+ * Ownership helpers for the immutable DataProvider store (REDMINE-79567).
+ * External values are cloned then deep-frozen; internal updates rebuild via spread.
+ */
+
+const warnedUnclonable = new WeakSet<object>();
+
+export function isFrozenValue(value: unknown): boolean {
+  return value != null && typeof value === "object" && Object.isFrozen(value);
+}
+
+/** Deep freeze (in place). Safe to call on already-frozen graphs. */
+export function deepFreeze<T>(value: T): T {
+  if (value == null || typeof value !== "object" || Object.isFrozen(value)) {
+    return value;
+  }
+  Object.freeze(value);
+  if (Array.isArray(value)) {
+    for (const item of value) deepFreeze(item);
+  } else {
+    for (const key of Reflect.ownKeys(value as object)) {
+      deepFreeze((value as Record<string | symbol, unknown>)[key]);
+    }
+  }
+  return value;
+}
+
+/**
+ * Clone so the publisher owns the data, then freeze.
+ * Non-cloneable values (EventSource, etc.): kept as-is, not frozen (warned once).
+ */
+export function takeOwnership<T>(value: T): T {
+  if (value == null || typeof value !== "object") return value;
+  if (isFrozenValue(value)) return value;
+  try {
+    return deepFreeze(structuredClone(value));
+  } catch {
+    if (!warnedUnclonable.has(value as object)) {
+      warnedUnclonable.add(value as object);
+      console.warn(
+        "[Concorde] takeOwnership: value is not structuredClone-able; stored without freeze.",
+      );
+    }
+    return value;
+  }
+}
+
+/** Drop `undefined` own keys on plain objects (before freeze). Arrays unchanged. */
+export function stripUndefinedKeys<T>(value: T): T {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) {
+    return value;
+  }
+  if (Object.prototype.hasOwnProperty.call(value, "__value")) return value;
+  // Keep frozen / already-owned graphs intact (set(get()) identity).
+  if (Object.isFrozen(value)) return value;
+  let needsStrip = false;
+  for (const key of Object.keys(value as object)) {
+    if ((value as Record<string, unknown>)[key] === undefined) {
+      needsStrip = true;
+      break;
+    }
+  }
+  if (!needsStrip) return value;
+  const out: Record<string, unknown> = { ...(value as object) };
+  for (const key of Object.keys(out)) {
+    if (out[key] === undefined) delete out[key];
+  }
+  return out as T;
+}
+
+/** Shallow rebuild with one key set — result is deep-frozen. Nested `value` should already be owned. */
+export function setAtKey<T extends object>(
+  root: T | null | undefined,
+  key: string | number,
+  value: unknown,
+): T {
+  let next: any;
+  if (root == null) {
+    next = typeof key === "number" || !isNaN(Number(key)) ? [] : {};
+  } else if (Array.isArray(root)) {
+    next = [...root];
+  } else {
+    next = { ...(root as object) };
+  }
+  next[key as any] = value;
+  return deepFreeze(next) as T;
+}
+
+/** Shallow rebuild without one key — result is deep-frozen. */
+export function deleteAtKey<T extends object>(
+  root: T,
+  key: string | number,
+): T {
+  if (Array.isArray(root)) {
+    const next = [...root];
+    delete next[key as any];
+    return deepFreeze(next) as T;
+  }
+  const next = { ...(root as object) } as Record<string, unknown>;
+  delete next[String(key)];
+  return deepFreeze(next) as T;
+}

package/src/core/utils/nestedDotForm.spec.ts

@@ -0,0 +1,88 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { PublisherManager, get, set } from "./PublisherProxy";
+import { traverseDotNotation } from "./Objects";
+
+afterEach(() => {
+  PublisherManager.getInstance().delete("nested-dot-form");
+});
+
+describe("nested dot form publishers (immutable)", () => {
+  it("set via traverseDotNotation builds nested object", () => {
+    const form = PublisherManager.get("nested-dot-form");
+    form.set({});
+    traverseDotNotation(form as any, "passenger.seat").set("window");
+    expect(get("nested-dot-form")).toEqual({ passenger: { seat: "window" } });
+  });
+
+  it("successive nested sets keep siblings", () => {
+    const form = PublisherManager.get("nested-dot-form");
+    form.set({});
+    traverseDotNotation(form as any, "passenger.name").set("Ada");
+    traverseDotNotation(form as any, "passenger.seat").set("aisle");
+    expect(get("nested-dot-form")).toEqual({
+      passenger: { name: "Ada", seat: "aisle" },
+    });
+  });
+
+  it("nested get after set is readable", () => {
+    set("nested-dot-form", { passenger: { seat: "window" } });
+    const form = PublisherManager.get("nested-dot-form");
+    expect(traverseDotNotation(form as any, "passenger.seat").get()).toBe(
+      "window",
+    );
+  });
+
+  it("deep leaf set from empty root creates intermediates (frozen)", () => {
+    const form = PublisherManager.get("nested-dot-form");
+    traverseDotNotation(form as any, "passenger.seat").set("window");
+    const data = get("nested-dot-form") as { passenger: { seat: string } };
+    expect(data).toEqual({ passenger: { seat: "window" } });
+    expect(Object.isFrozen(data)).toBe(true);
+    expect(Object.isFrozen(data.passenger)).toBe(true);
+  });
+
+  it("switching nested radio leaf replaces value", () => {
+    const form = PublisherManager.get("nested-dot-form");
+    traverseDotNotation(form as any, "passenger.seat").set("window");
+    traverseDotNotation(form as any, "passenger.seat").set("aisle");
+    expect(get("nested-dot-form")).toEqual({ passenger: { seat: "aisle" } });
+  });
+
+  it("onAssign on nested path receives scalar", () => {
+    const form = PublisherManager.get("nested-dot-form");
+    const seen: unknown[] = [];
+    traverseDotNotation(form as any, "passenger.seat").onAssign((v: unknown) => {
+      seen.push(v);
+    });
+    traverseDotNotation(form as any, "passenger.seat").set("window");
+    expect(seen).toContain("window");
+  });
+
+  it("reading nested before set returns null", () => {
+    const form = PublisherManager.get("nested-dot-form");
+    expect(traverseDotNotation(form as any, "passenger.seat").get()).toBeNull();
+  });
+
+  it("updating leaf after frozen parent set keeps siblings", () => {
+    set("nested-dot-form", { passenger: { name: "Ada", seat: "window" } });
+    const form = PublisherManager.get("nested-dot-form");
+    traverseDotNotation(form as any, "passenger.seat").set("aisle");
+    expect(get("nested-dot-form")).toEqual({
+      passenger: { name: "Ada", seat: "aisle" },
+    });
+  });
+
+  it("checkbox-like array replace via slice keeps frozen parent", () => {
+    const form = PublisherManager.get("nested-dot-form");
+    traverseDotNotation(form as any, "passenger.tags").set(["a"]);
+    const current = traverseDotNotation(form as any, "passenger.tags").get() as
+      | string[]
+      | null;
+    const next = (current ?? []).slice(0);
+    next.push("b");
+    traverseDotNotation(form as any, "passenger.tags").set(next);
+    expect(get("nested-dot-form")).toEqual({
+      passenger: { tags: ["a", "b"] },
+    });
+  });
+});

package/src/core/utils/publisherImmutable.spec.ts

@@ -0,0 +1,76 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { DataProviderKey } from "./dataProviderKey";
+import { dp, get, PublisherManager, set } from "./PublisherProxy";
+
+type Cart = { items: { id: number }[]; total: number };
+type Row = { id: number; _metadata_?: { key: string; even: boolean } };
+
+describe("immutable DataProvider store (79567)", () => {
+  const cartKey = new DataProviderKey<Cart>("publisherImmutableCart");
+
+  afterEach(() => {
+    PublisherManager.getInstance().delete(cartKey.path);
+    PublisherManager.getInstance().delete("publisherImmutableListLoop");
+  });
+
+  it("set takes ownership — mutating the input does not change the store", () => {
+    const input: Cart = { items: [{ id: 1 }], total: 1 };
+    set(cartKey, input);
+    input.total = 99;
+    input.items.push({ id: 2 });
+    expect(get(cartKey).total).toBe(1);
+    expect(get(cartKey).items).toHaveLength(1);
+  });
+
+  it("get returns a frozen value (same ref until next set)", () => {
+    set(cartKey, { items: [], total: 0 });
+    const a = get(cartKey);
+    const b = get(cartKey);
+    expect(a).toBe(b);
+    expect(Object.isFrozen(a)).toBe(true);
+    expect(() => {
+      (a as Cart).total = 5;
+    }).toThrow();
+    expect(get(cartKey).total).toBe(0);
+  });
+
+  it("nested dp().set updates parent immutably", () => {
+    set(cartKey, { items: [{ id: 1 }], total: 0 });
+    dp(cartKey.total).set(10);
+    expect(get(cartKey).total).toBe(10);
+    expect(Object.isFrozen(get(cartKey))).toBe(true);
+  });
+
+  it("publisher property assign goes through immutable set", () => {
+    set(cartKey, { items: [], total: 0 });
+    const pub = dp(cartKey);
+    (pub as any).total = 4;
+    expect(get(cartKey).total).toBe(4);
+  });
+
+  it("set(get()) is a no-op identity keep", () => {
+    set(cartKey, { items: [{ id: 1 }], total: 1 });
+    const snap = get(cartKey);
+    set(cartKey, snap);
+    expect(get(cartKey)).toBe(snap);
+  });
+
+  it("re-assigning the same nested value does not re-publish the parent", () => {
+    const listKey = new DataProviderKey<Row[]>("publisherImmutableListLoop");
+    set(listKey, [{ id: 1 }]);
+    const row = dp(listKey)[0];
+    const meta = { key: "0", even: true };
+    row._metadata_ = meta as any;
+
+    const parentAssign = vi.fn();
+    dp(listKey).onAssign(parentAssign, false);
+    parentAssign.mockClear();
+
+    // Same logical metadata again (new object) would rebuild without the list guard;
+    // engine must still skip parent sync when the child commits a value already at parent[key].
+    expect(row._metadata_).toBeDefined();
+    const ownedMeta = row._metadata_!.get();
+    row._metadata_!.set(ownedMeta as any);
+    expect(parentAssign).not.toHaveBeenCalled();
+  });
+});

package/src/core/utils/strictGet.spec.ts

@@ -0,0 +1,61 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { DataProviderKey } from "./dataProviderKey";
+import {
+  clearStrictGetWarnings,
+  PublisherManager,
+  dp,
+  get,
+  set,
+} from "./PublisherProxy";
+
+type Cart = { items: { id: number }[]; total: number };
+
+describe("strictGet runtime guard (79567)", () => {
+  const cartKey = new DataProviderKey<Cart>("strictGetSpecCart");
+
+  afterEach(() => {
+    PublisherManager.strictGet = "off";
+    clearStrictGetWarnings();
+    vi.restoreAllMocks();
+  });
+
+  it("off: store is frozen — assignment via get() throws", () => {
+    PublisherManager.strictGet = "off";
+    set(cartKey, { items: [{ id: 1 }], total: 1 });
+    const cart = get(cartKey) as Cart;
+    expect(() => {
+      cart.total = 7;
+    }).toThrow();
+    expect(get(cartKey).total).toBe(1);
+  });
+
+  it("warn: logs once per path; mutation still blocked by freeze", () => {
+    PublisherManager.strictGet = "warn";
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    set(cartKey, { items: [{ id: 1 }], total: 1 });
+    const cart = get(cartKey) as Cart;
+    expect(() => {
+      cart.total = 2;
+    }).toThrow();
+    expect(warn).toHaveBeenCalled();
+    expect(String(warn.mock.calls[0]?.[0])).toContain("strictGet=warn");
+    expect(get(cartKey).total).toBe(1);
+  });
+
+  it("throw: TypeError from strictGet before freeze", () => {
+    PublisherManager.strictGet = "throw";
+    set(cartKey, { items: [{ id: 1 }], total: 1 });
+    const cart = get(cartKey) as Cart;
+    expect(() => {
+      cart.total = 9;
+    }).toThrow(/strictGet=throw/);
+    expect(dp(cartKey).get().total).toBe(1);
+  });
+
+  it("set() still works while strictGet=throw", () => {
+    PublisherManager.strictGet = "throw";
+    set(cartKey, { items: [], total: 0 });
+    set(cartKey, { items: [{ id: 1 }], total: 1 });
+    expect(get(cartKey).total).toBe(1);
+  });
+});

package/src/core/utils/strictGet.ts

@@ -0,0 +1,102 @@
+/**
+ * Runtime guard for values returned by publisher `get()` (REDMINE-79567).
+ * Wraps objects/arrays in a Proxy — does **not** freeze live `_value_`.
+ * Engine writes that touch the target directly still work.
+ *
+ * - `off`   — no wrap (same ref as today)
+ * - `warn`  — log once per path, mutation still applied (discovery)
+ * - `throw` — TypeError, mutation blocked (CI / hardening)
+ */
+
+export type StrictGetMode = "off" | "warn" | "throw";
+
+let strictGetMode: StrictGetMode = "off";
+const warnedKeys = new Set<string>();
+const proxyCache = new WeakMap<object, object>();
+
+export function getStrictGetMode(): StrictGetMode {
+  return strictGetMode;
+}
+
+export function setStrictGetMode(mode: StrictGetMode): void {
+  strictGetMode = mode;
+}
+
+/** Test helper — clears once-only warn dedupe. */
+export function clearStrictGetWarnings(): void {
+  warnedKeys.clear();
+}
+
+function report(mode: "warn" | "throw", path: string): void {
+  const message = `[Concorde strictGet=${mode}] Mutation via get() at "${path || "(root)"}". Use set() / dp(…).set(…) instead.`;
+  if (mode === "throw") {
+    throw new TypeError(message);
+  }
+  if (warnedKeys.has(path)) return;
+  warnedKeys.add(path);
+  console.warn(message);
+}
+
+function wrapDeep<T extends object>(target: T, path: string): T {
+  const cached = proxyCache.get(target);
+  if (cached) return cached as T;
+
+  const proxy = new Proxy(target, {
+    get(obj, prop, receiver) {
+      if (prop === "__strictGetTarget__") return target;
+      const value = Reflect.get(obj, prop, receiver);
+      if (value == null || typeof value !== "object") return value;
+      if (getStrictGetMode() === "off") return value;
+      const childPath =
+        path === "" ? String(prop) : `${path}.${String(prop)}`;
+      return wrapDeep(value as object, childPath);
+    },
+    set(obj, prop, value, receiver) {
+      const mode = getStrictGetMode();
+      if (mode === "off") {
+        return Reflect.set(obj, prop, value, receiver);
+      }
+      const childPath =
+        path === "" ? String(prop) : `${path}.${String(prop)}`;
+      report(mode, childPath);
+      if (mode === "throw") return false;
+      return Reflect.set(obj, prop, value, receiver);
+    },
+    deleteProperty(obj, prop) {
+      const mode = getStrictGetMode();
+      if (mode === "off") {
+        return Reflect.deleteProperty(obj, prop);
+      }
+      const childPath =
+        path === "" ? String(prop) : `${path}.${String(prop)}`;
+      report(mode, childPath);
+      if (mode === "throw") return false;
+      return Reflect.deleteProperty(obj, prop);
+    },
+    defineProperty(obj, prop, desc) {
+      const mode = getStrictGetMode();
+      if (mode === "off") {
+        return Reflect.defineProperty(obj, prop, desc);
+      }
+      const childPath =
+        path === "" ? String(prop) : `${path}.${String(prop)}`;
+      report(mode, childPath);
+      if (mode === "throw") return false;
+      return Reflect.defineProperty(obj, prop, desc);
+    },
+  });
+
+  proxyCache.set(target, proxy);
+  return proxy;
+}
+
+/**
+ * When mode is off or value is not an object, returns value as-is (same ref).
+ * Otherwise returns a deep Proxy over the **same** target (no clone).
+ */
+export function wrapStrictGet<T>(value: T): T {
+  if (getStrictGetMode() === "off" || value == null || typeof value !== "object") {
+    return value;
+  }
+  return wrapDeep(value as object, "") as T;
+}

package/src/css.d.ts

@@ -0,0 +1,19 @@
+declare module "*.css" {
+  const css: import("lit").CSSResult;
+  export default css;
+}
+
+declare module "*.css?inline" {
+  const css: string;
+  export default css;
+}
+
+declare module "*.scss" {
+  const css: import("lit").CSSResult;
+  export default css;
+}
+
+declare module "*.scss?inline" {
+  const css: string;
+  export default css;
+}