clava 0.4.1 → 0.4.2

package/src/index.ts

@@ -1,4 +1,12 @@
 import clsx, { type ClassValue as ClsxClassValue } from "clsx";
+import {
+  REFINE_UNSTABLE_TRACKING_WINDOW,
+  type RefineRunState,
+  type VariantChange,
+  accumulateUnstableVariantChanges,
+  captureCreationFrame,
+  warnRefineLimit,
+} from "./refine-warning.ts";
 import type {
   AnyComponent,
   CVComponent,
@@ -57,11 +65,6 @@ type ResolveRefineFn = (
   protectedVariantKeys?: Set<string> | null,
 ) => Record<string, unknown>;
 
-interface RefineRunState {
-  remaining: number;
-  warned?: boolean;
-}
-
 // Internal metadata stored on components but hidden from public types.
 interface ComponentMeta {
   baseClass: string;
@@ -105,13 +108,6 @@ const EMPTY_DEFAULTS: Record<string, unknown> = Object.freeze({}) as Record<
 
 const MAX_REFINE_RUNS = 50;
 
-// Once a refine loop is within this many iterations of the cap, start tracking
-// every variant key that changes between iterations so the warning can report
-// every key that contributed to the oscillation, not just the keys that
-// happened to flip on the final step. Convergent loops (the common case) exit
-// well before this threshold and pay no per-iteration tracking cost.
-const REFINE_UNSTABLE_TRACKING_WINDOW = 10;
-
 function areVariantsEqual(
   a: Record<string, unknown>,
   b: Record<string, unknown>,
@@ -127,96 +123,6 @@ function areVariantsEqual(
   return true;
 }
 
-interface CreationFrame {
-  stack?: string;
-}
-
-// Captures the call site of the function passed in `skipFn` so refine-limit
-// warnings can point developers at the originating `cv()` call. Returns
-// `undefined` in production so bundlers that replace `process.env.NODE_ENV` at
-// build time can drop the entire warning machinery. The underlying `.stack`
-// string is formatted lazily on first access in every major engine (V8,
-// SpiderMonkey, JavaScriptCore), so holding the captured frame for the
-// lifetime of the component is cheap when no warning fires.
-function captureCreationFrame(skipFn: Function): CreationFrame | undefined {
-  if (process.env.NODE_ENV === "production") return undefined;
-  if (typeof Error.captureStackTrace === "function") {
-    const holder: CreationFrame = {};
-    Error.captureStackTrace(holder, skipFn);
-    return holder;
-  }
-  // Engines without `Error.captureStackTrace` (SpiderMonkey, JavaScriptCore)
-  // can't strip internal frames, but their `Error.stack` getter is still
-  // lazy, so returning the Error instance defers the format cost. The
-  // resulting trace includes 1–2 extra frames at the top from this helper and
-  // `cv` itself.
-  return new Error();
-}
-
-function formatCreationStack(frame: CreationFrame): string | undefined {
-  let stack = frame.stack;
-  if (!stack) return undefined;
-  // V8 prefixes the stack with a leading "Error" / "Error: message" line that
-  // isn't meaningful for a captured location — drop it.
-  const newlineIdx = stack.indexOf("\n");
-  if (newlineIdx > 0) {
-    const firstLine = stack.slice(0, newlineIdx);
-    if (firstLine === "Error" || firstLine.startsWith("Error:")) {
-      stack = stack.slice(newlineIdx + 1);
-    }
-  }
-  return stack;
-}
-
-// Accumulates the union of variant keys that differ between `prev` and `next`
-// into `into`. Called on every non-converging iteration of the refine loop so
-// the refine-limit warning can report any key that ever changed across runs,
-// not just the keys that changed on the final iteration (two keys flipping at
-// different cadences could otherwise hide each other on the last step).
-function accumulateUnstableVariantKeys(
-  into: Set<string>,
-  prev: Record<string, unknown>,
-  next: Record<string, unknown>,
-): void {
-  for (const key in next) {
-    if (!Object.hasOwn(next, key)) continue;
-    if (!Object.is(prev[key], next[key])) {
-      into.add(key);
-    }
-  }
-  for (const key in prev) {
-    if (!Object.hasOwn(prev, key)) continue;
-    if (Object.hasOwn(next, key)) continue;
-    into.add(key);
-  }
-}
-
-function warnRefineLimit(
-  runState: RefineRunState,
-  creationFrame: CreationFrame | undefined,
-  unstableKeys: Set<string> | null,
-): void {
-  // Bundlers are expected to replace this branch with a production literal,
-  // allowing warning-only code below to be removed from consumer bundles.
-  if (process.env.NODE_ENV === "production") return;
-  if (runState.warned) return;
-  runState.warned = true;
-  let message =
-    "Clava: Maximum refine iterations exceeded. This can happen when a " +
-    "refine callback calls setVariants or setDefaultVariants, but one " +
-    "of the variants changes on every run.";
-  if (unstableKeys && unstableKeys.size > 0) {
-    message += `\nVariant(s) that did not stabilize: ${Array.from(unstableKeys).join(", ")}.`;
-  }
-  if (creationFrame) {
-    const creationStack = formatCreationStack(creationFrame);
-    if (creationStack) {
-      message += `\nComponent created at:\n${creationStack}`;
-    }
-  }
-  console.warn(message);
-}
-
 function getExtUserVariantProps(
   userVariantProps: Record<string, unknown>,
   protectedVariants: Record<string, unknown> | null,
@@ -1120,7 +1026,7 @@ export function create({
                 if (!Object.hasOwn(newVariants, key)) continue;
                 const value = (newVariants as Record<string, unknown>)[key];
                 setChangedVariant(key, value, true);
-                if (getCurrentVariantValue(key) === value) continue;
+                if (Object.is(getCurrentVariantValue(key), value)) continue;
                 ensureUpdated()[key] = value;
               }
               return;
@@ -1139,7 +1045,7 @@ export function create({
                 }
               }
               setChangedVariant(key, value, true);
-              if (getCurrentVariantValue(key) === value) continue;
+              if (Object.is(getCurrentVariantValue(key), value)) continue;
               ensureUpdated()[key] = value;
             }
           },
@@ -1161,11 +1067,11 @@ export function create({
                   continue;
                 }
               }
+              if (Object.is(getCurrentVariantValue(key), value)) continue;
               setChangedVariant(key, value);
               if (pendingProtectedVariants) {
                 pendingProtectedVariants[key] = value;
               }
-              if (getCurrentVariantValue(key) === value) continue;
               ensureUpdated()[key] = value;
             }
           },
@@ -1474,11 +1380,9 @@ export function create({
             protectedVariants ??= {};
             protectedVariantKeys ??= new Set<string>();
             let workingResolved = resolved;
-            // Union of variant keys that differed on non-converging iterations
-            // inside the tracking window, so the refine-limit warning can name
-            // every variant that contributed to the late-stage oscillation.
-            // Lazy-init keeps convergent loops allocation-free.
-            let unstableKeys: Set<string> | null = null;
+            // Latest variant changes from non-converging iterations inside the
+            // tracking window. Lazy-init keeps convergent loops allocation-free.
+            let unstableChanges: Map<string, VariantChange> | null = null;
             let lastClasses: ClsxClassValue[] = [];
             let lastStyle: StyleValue = {};
             let isFirstRun = true;
@@ -1546,11 +1450,11 @@ export function create({
                 process.env.NODE_ENV !== "production" &&
                 runState.remaining < REFINE_UNSTABLE_TRACKING_WINDOW
               ) {
-                if (!unstableKeys) {
-                  unstableKeys = new Set<string>();
+                if (!unstableChanges) {
+                  unstableChanges = new Map<string, VariantChange>();
                 }
-                accumulateUnstableVariantKeys(
-                  unstableKeys,
+                accumulateUnstableVariantChanges(
+                  unstableChanges,
                   workingResolved,
                   nextResolved,
                 );
@@ -1559,7 +1463,11 @@ export function create({
               if (useDirectOutput && runState.remaining === 0) {
                 // Keep the direct output from the last allowed run. Rolling
                 // back here would drop it before the fallback copy below.
-                warnRefineLimit(runState, creationFrame, unstableKeys);
+                warnRefineLimit({
+                  runState,
+                  creationFrame,
+                  unstableChanges,
+                });
                 return nextResolved;
               }
 
@@ -1579,7 +1487,11 @@ export function create({
               isFirstRun = false;
             }
 
-            warnRefineLimit(runState, creationFrame, unstableKeys);
+            warnRefineLimit({
+              runState,
+              creationFrame,
+              unstableChanges,
+            });
 
             for (let i = 0; i < lastClasses.length; i++) {
               classesOut.push(lastClasses[i]);
@@ -1656,11 +1568,10 @@ export function create({
             protectedVariants ??= {};
             protectedVariantKeys ??= new Set<string>();
             let workingResolved = resolved;
-            // Union of variant keys that differed on non-converging iterations
-            // inside the tracking window — see the compute loop above for the
-            // shared rationale. Lazy-init keeps convergent loops
-            // allocation-free.
-            let unstableKeys: Set<string> | null = null;
+            // Latest variant changes from non-converging iterations inside the
+            // tracking window. See the compute loop above for the shared
+            // rationale.
+            let unstableChanges: Map<string, VariantChange> | null = null;
             let reachedLimit = true;
 
             while (runState.remaining > 0) {
@@ -1704,11 +1615,11 @@ export function create({
                 process.env.NODE_ENV !== "production" &&
                 runState.remaining < REFINE_UNSTABLE_TRACKING_WINDOW
               ) {
-                if (!unstableKeys) {
-                  unstableKeys = new Set<string>();
+                if (!unstableChanges) {
+                  unstableChanges = new Map<string, VariantChange>();
                 }
-                accumulateUnstableVariantKeys(
-                  unstableKeys,
+                accumulateUnstableVariantChanges(
+                  unstableChanges,
                   workingResolved,
                   nextResolved,
                 );
@@ -1717,7 +1628,11 @@ export function create({
             }
 
             if (reachedLimit) {
-              warnRefineLimit(runState, creationFrame, unstableKeys);
+              warnRefineLimit({
+                runState,
+                creationFrame,
+                unstableChanges,
+              });
             }
 
             return workingResolved;

package/src/refine-warning.ts

@@ -0,0 +1,161 @@
+export interface RefineRunState {
+  remaining: number;
+  warned?: boolean;
+}
+
+export interface CreationFrame {
+  stack?: string;
+}
+
+export interface VariantChange {
+  from: unknown;
+  to: unknown;
+}
+
+// Once a refine loop is within this many iterations of the cap, start tracking
+// the latest value transition for every variant key that changes between
+// iterations so the warning can report every key that contributed to the
+// oscillation, not just the keys that happened to flip on the final step.
+// Convergent loops (the common case) exit well before this threshold and pay no
+// per-iteration tracking cost.
+export const REFINE_UNSTABLE_TRACKING_WINDOW = 10;
+
+// Captures the call site of the function passed in `skipFn` so refine-limit
+// warnings can point developers at the originating `cv()` call. Returns
+// `undefined` in production so bundlers that replace `process.env.NODE_ENV` at
+// build time can drop the entire warning machinery. The underlying `.stack`
+// string is formatted lazily on first access in every major engine (V8,
+// SpiderMonkey, JavaScriptCore), so holding the captured frame for the
+// lifetime of the component is cheap when no warning fires.
+export function captureCreationFrame(
+  skipFn: Function,
+): CreationFrame | undefined {
+  if (process.env.NODE_ENV === "production") return undefined;
+  if (typeof Error.captureStackTrace === "function") {
+    const holder: CreationFrame = {};
+    Error.captureStackTrace(holder, skipFn);
+    return holder;
+  }
+  // Engines without `Error.captureStackTrace` (SpiderMonkey, JavaScriptCore)
+  // can't strip internal frames, but their `Error.stack` getter is still
+  // lazy, so returning the Error instance defers the format cost. The
+  // resulting trace includes 1–2 extra frames at the top from this helper and
+  // `cv` itself.
+  return new Error();
+}
+
+export function formatCreationStack(frame: CreationFrame): string | undefined {
+  let stack = frame.stack;
+  if (!stack) return undefined;
+  // V8 prefixes the stack with a leading "Error" / "Error: message" line that
+  // isn't meaningful for a captured location — drop it.
+  const newlineIdx = stack.indexOf("\n");
+  if (newlineIdx > 0) {
+    const firstLine = stack.slice(0, newlineIdx);
+    if (firstLine === "Error" || firstLine.startsWith("Error:")) {
+      stack = stack.slice(newlineIdx + 1);
+    }
+  }
+  const frames = stack.split("\n");
+  for (let i = 0; i < frames.length; i++) {
+    const line = frames[i]?.trim();
+    if (!line) continue;
+    if (isInternalCreationFrame(line)) continue;
+    if (line.includes("/node_modules/")) continue;
+    if (line.includes("\\node_modules\\")) continue;
+    if (line.includes("node:internal")) continue;
+    return `    ${line}`;
+  }
+  return undefined;
+}
+
+function isInternalCreationFrame(line: string): boolean {
+  if (line.includes("captureCreationFrame")) return true;
+  if (line.startsWith("at cv ")) return true;
+  if (line.startsWith("at cv(")) return true;
+  if (line.startsWith("cv@")) return true;
+  return false;
+}
+
+function formatVariantValue(value: unknown): string {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number") {
+    if (Number.isNaN(value)) return "NaN";
+    return String(value);
+  }
+  if (typeof value === "bigint") return `${value}n`;
+  if (value === undefined) return "undefined";
+  if (value === null) return "null";
+  if (typeof value === "boolean") return String(value);
+  if (typeof value === "symbol") return String(value);
+  if (typeof value === "function") return "[function]";
+  return "[object]";
+}
+
+function setVariantChange(
+  into: Map<string, VariantChange>,
+  key: string,
+  from: unknown,
+  to: unknown,
+): void {
+  into.set(key, { from, to });
+}
+
+export function accumulateUnstableVariantChanges(
+  into: Map<string, VariantChange>,
+  prev: Record<string, unknown>,
+  next: Record<string, unknown>,
+): void {
+  for (const key in next) {
+    if (!Object.hasOwn(next, key)) continue;
+    if (!Object.is(prev[key], next[key])) {
+      setVariantChange(into, key, prev[key], next[key]);
+    }
+  }
+  for (const key in prev) {
+    if (!Object.hasOwn(prev, key)) continue;
+    if (Object.hasOwn(next, key)) continue;
+    setVariantChange(into, key, prev[key], undefined);
+  }
+}
+
+function formatVariantChanges(changes: Map<string, VariantChange>): string {
+  return Array.from(changes)
+    .map(([key, { from, to }]) => {
+      return `${key}: ${formatVariantValue(from)} -> ${formatVariantValue(to)}`;
+    })
+    .join(", ");
+}
+
+interface WarnRefineLimitParams {
+  runState: RefineRunState;
+  creationFrame: CreationFrame | undefined;
+  unstableChanges: Map<string, VariantChange> | null;
+}
+
+export function warnRefineLimit({
+  runState,
+  creationFrame,
+  unstableChanges,
+}: WarnRefineLimitParams): void {
+  // Bundlers are expected to replace this branch with a production literal,
+  // allowing warning-only code below to be removed from consumer bundles.
+  if (process.env.NODE_ENV === "production") return;
+  if (runState.warned) return;
+  runState.warned = true;
+  let message =
+    "Clava: Maximum refine iterations exceeded. This can happen when a " +
+    "refine callback calls setVariants or setDefaultVariants, but one " +
+    "of the variants changes on every run.";
+  if (unstableChanges && unstableChanges.size > 0) {
+    message += `\nVariant(s) that did not stabilize: ${Array.from(unstableChanges.keys()).join(", ")}.`;
+    message += `\nLatest variant changes before warning: ${formatVariantChanges(unstableChanges)}.`;
+  }
+  if (creationFrame) {
+    const creationStack = formatCreationStack(creationFrame);
+    if (creationStack) {
+      message += `\nComponent created at:\n${creationStack}`;
+    }
+  }
+  console.warn(message);
+}

package/tests/build.test.ts

@@ -82,6 +82,7 @@ test("vite removes warning logic from the production bundle", async () => {
       expect(code).not.toContain("console.warn");
       expect(code).not.toContain("Clava: Maximum refine iterations exceeded");
       expect(code).not.toContain("Variant(s) that did not stabilize");
+      expect(code).not.toContain("Latest variant changes before warning");
       expect(code).not.toContain("Component created at");
       expect(code).not.toContain("captureStackTrace");
       expect(code).not.toMatch(/\.warned\b|["']warned["']/);

package/tests/refine-warning.test.ts

@@ -0,0 +1,28 @@
+import { expect, test } from "vitest";
+import { formatCreationStack } from "../src/refine-warning.ts";
+
+test("formatCreationStack returns the first app frame", () => {
+  const stack = [
+    "Error",
+    "    at captureCreationFrame (/repo/packages/clava/src/refine-warning.ts:31:10)",
+    "    at cv (/repo/packages/clava/src/index.ts:734:9)",
+    "    at eval (/repo/app/src/button.ts:12:21)",
+    "    at ModuleJob.run (node:internal/modules/esm/module_job:343:25)",
+  ].join("\n");
+
+  expect(formatCreationStack({ stack })).toBe(
+    "    at eval (/repo/app/src/button.ts:12:21)",
+  );
+});
+
+test("formatCreationStack omits dependency and runtime frames", () => {
+  const stack = [
+    "Error",
+    "    at captureCreationFrame (/repo/packages/clava/src/refine-warning.ts:31:10)",
+    "    at cv(/repo/packages/clava/src/index.ts:734:9)",
+    "    at eval (/repo/node_modules/package/index.js:1:1)",
+    "    at ModuleJob.run (node:internal/modules/esm/module_job:343:25)",
+  ].join("\n");
+
+  expect(formatCreationStack({ stack })).toBeUndefined();
+});

package/tests/refine.test.ts

@@ -125,6 +125,125 @@ for (const config of Object.values(CONFIGS)) {
       }
     });
 
+    test("refine converges with undefined setDefaultVariants", () => {
+      const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+      const base = cv({
+        variants: {
+          invert: { true: "invert" },
+          offset: (value: boolean | undefined) =>
+            value ? "offset" : undefined,
+          push: (value: number | undefined) =>
+            value === undefined ? undefined : `push-${value}`,
+        },
+        refine: ({ variants, setDefaultVariants }) => {
+          setDefaultVariants({
+            offset: !variants.invert,
+            push: variants.invert ? 20 : undefined,
+          });
+        },
+      });
+      const component = getModeComponent(mode, cv({ extend: [base] }));
+
+      try {
+        const props = component();
+        expect(getStyleClass(props)).toEqual({
+          class: cls("offset"),
+        });
+        expect(component.getVariants()).toEqual({
+          offset: true,
+          push: undefined,
+        });
+        expect(warn).not.toHaveBeenCalled();
+      } finally {
+        warn.mockRestore();
+      }
+    });
+
+    test("refine converges with undefined setDefaultVariants in nested extends", () => {
+      const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+      const calls = {
+        layer: 0,
+        frame: 0,
+        control: 0,
+      };
+      const layer = cv({
+        variants: {
+          layer: { true: "layer" },
+          invert: { true: "invert" },
+          offset: (value: boolean | undefined) =>
+            value ? "offset" : undefined,
+          push: (value: number | undefined) =>
+            value === undefined ? undefined : `push-${value}`,
+        },
+        defaultVariants: {
+          layer: true,
+        },
+        refine: ({ variants, setDefaultVariants }) => {
+          calls.layer += 1;
+          setDefaultVariants({
+            offset: !variants.invert,
+            push: variants.invert ? 20 : undefined,
+          });
+        },
+      });
+      const frame = cv({
+        extend: [layer],
+        variants: {
+          frame: { true: "frame" },
+        },
+        defaultVariants: {
+          frame: true,
+        },
+        refine: () => {
+          calls.frame += 1;
+        },
+      });
+      const control = cv({
+        extend: [frame],
+        variants: {
+          control: { true: "control" },
+        },
+        defaultVariants: {
+          control: true,
+          offset: true,
+        },
+        refine: () => {
+          calls.control += 1;
+        },
+      });
+      const component = getModeComponent(mode, cv({ extend: [control] }));
+
+      try {
+        const props = component();
+        expect(getStyleClass(props)).toEqual({
+          class: cls("layer offset frame control"),
+        });
+        expect(calls).toEqual({
+          layer: 2,
+          frame: 2,
+          control: 2,
+        });
+        calls.layer = 0;
+        calls.frame = 0;
+        calls.control = 0;
+        expect(component.getVariants()).toEqual({
+          layer: true,
+          offset: true,
+          push: undefined,
+          frame: true,
+          control: true,
+        });
+        expect(calls).toEqual({
+          layer: 2,
+          frame: 2,
+          control: 2,
+        });
+        expect(warn).not.toHaveBeenCalled();
+      } finally {
+        warn.mockRestore();
+      }
+    });
+
     test("refine with setDefaultVariants", () => {
       const component = getModeComponent(
         mode,
@@ -719,6 +838,11 @@ for (const config of Object.values(CONFIGS)) {
             /Variant\(s\) that did not stabilize: [^\n]*\bsize\b/,
           ),
         );
+        expect(warn).toHaveBeenCalledWith(
+          expect.stringMatching(
+            /Latest variant changes before warning: [^\n]*\bsize: "(sm|lg)" -> "(sm|lg)"/,
+          ),
+        );
         expect(warn).toHaveBeenCalledWith(
           expect.stringContaining("Component created at:"),
         );
@@ -750,6 +874,11 @@ for (const config of Object.values(CONFIGS)) {
             /Variant\(s\) that did not stabilize: [^\n]*\bsize\b/,
           ),
         );
+        expect(warn).toHaveBeenCalledWith(
+          expect.stringMatching(
+            /Latest variant changes before warning: [^\n]*\bsize: "(sm|lg)" -> "(sm|lg)"/,
+          ),
+        );
         expect(warn).toHaveBeenCalledWith(
           expect.stringContaining("Component created at:"),
         );
@@ -853,6 +982,11 @@ for (const config of Object.values(CONFIGS)) {
             /Variant\(s\) that did not stabilize: [^\n]*\bcolor\b/,
           ),
         );
+        expect(warn).toHaveBeenCalledWith(
+          expect.stringMatching(
+            /Latest variant changes before warning: [^\n]*\bsize\b[^\n]*\bcolor\b/,
+          ),
+        );
       } finally {
         warn.mockRestore();
       }
@@ -879,7 +1013,50 @@ for (const config of Object.values(CONFIGS)) {
         expect(warn).toHaveBeenCalledWith(
           expect.stringContaining("refine.test.ts"),
         );
+        expect(warn).toHaveBeenCalledWith(
+          expect.not.stringContaining("node_modules"),
+        );
+      } finally {
+        warn.mockRestore();
+      }
+    });
+
+    test("refine warning fallback stack skips internal creation frames", () => {
+      const ErrorWithCaptureStackTrace = Error as ErrorConstructor & {
+        captureStackTrace?: (
+          targetObject: object,
+          constructorOpt?: Function,
+        ) => void;
+      };
+      const captureStackTrace = ErrorWithCaptureStackTrace.captureStackTrace;
+      Reflect.deleteProperty(ErrorWithCaptureStackTrace, "captureStackTrace");
+      const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+      const component = getModeComponent(
+        mode,
+        cv({
+          variants: { size: { sm: "sm", lg: "lg" } },
+          defaultVariants: { size: "sm" },
+          refine: ({ variants, setVariants }) => {
+            setVariants({ size: variants.size === "sm" ? "lg" : "sm" });
+          },
+        }),
+      );
+
+      try {
+        component();
+        expect(warn).toHaveBeenCalledWith(
+          expect.stringContaining("Component created at:"),
+        );
+        expect(warn).toHaveBeenCalledWith(
+          expect.stringContaining("refine.test.ts"),
+        );
+        expect(warn).toHaveBeenCalledWith(
+          expect.not.stringContaining("captureCreationFrame"),
+        );
       } finally {
+        if (captureStackTrace) {
+          ErrorWithCaptureStackTrace.captureStackTrace = captureStackTrace;
+        }
         warn.mockRestore();
       }
     });