meno-core 1.0.53 → 1.1.0

package/lib/shared/utilityClassMapper.durability.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Serialization-durability characterization for the class<->style round-trip.
+ *
+ * The class-string styling migration (docs/meno-class-styling-migration.md)
+ * wants the utility-class string to become the on-disk source of truth. That
+ * only works if `classToStyle(class)` can recover the value from the class name
+ * ALONE — without the in-memory `styleValueRegistry`, which is populated by the
+ * forward pass (`stylesToClasses`) and does NOT live in the `.astro` source.
+ *
+ * These tests pin where the round-trip is durable (value lives in the class
+ * name) vs. ephemeral (value lives only in the registry, lost on reload). The
+ * ephemeral cases are the Phase-1 GATE: they MUST become lossless — or be moved
+ * to a structured remainder — before class strings can be the source of truth.
+ */
+import { describe, test, expect } from 'bun:test';
+import { stylesToClasses, responsiveStylesToClasses, classToStyle, classesToStyles } from './utilityClassMapper';
+import { clearRegistry } from './styleValueRegistry';
+
+describe('class<->style serialization durability', () => {
+  describe('durable: value lives in the class name (survives a registry wipe)', () => {
+    test('scale-step length value', () => {
+      const cls = stylesToClasses({ padding: '24px' });
+      expect(cls).toEqual(['p-6']); // exact scale step → named token
+      clearRegistry(); // simulate a fresh process that loaded the class from disk
+      // The scale table is static, so `p-6` recovers 24px without the registry.
+      expect(classToStyle('p-6')).toEqual({ prop: 'padding', value: '24px' });
+    });
+
+    test('off-scale length value (arbitrary form)', () => {
+      const cls = stylesToClasses({ padding: '13px' });
+      expect(cls).toEqual(['p-[13px]']);
+      clearRegistry();
+      expect(classToStyle('p-[13px]')).toEqual({ prop: 'padding', value: '13px' });
+    });
+
+    test('arbitrary value with spaces (underscore-encoded)', () => {
+      const cls = stylesToClasses({ padding: '92px 0' });
+      expect(cls).toEqual(['p-[92px_0]']);
+      clearRegistry();
+      expect(classToStyle('p-[92px_0]')).toEqual({ prop: 'padding', value: '92px 0' });
+    });
+
+    test('color token: bare form is durable WITHIN the project token set', () => {
+      const cls = stylesToClasses({ color: 'primary' });
+      expect(cls).toEqual(['text-primary']); // bare Meno token form
+      clearRegistry();
+      // The bare token resolves against the project's defined tokens (colors.json /
+      // variables.json), not the ephemeral registry — durable, but project-scoped.
+      expect(classToStyle('text-primary', new Set(['primary']))).toEqual({ prop: 'color', value: 'primary' });
+      // Without the token set it is (intentionally) NOT recognized — foreign-safe.
+      expect(classToStyle('text-primary')).toBeNull();
+    });
+
+    test('color token: the var() shorthand stays self-describing (no token set needed)', () => {
+      clearRegistry();
+      expect(classToStyle('text-(--primary)')).toEqual({ prop: 'color', value: 'primary' });
+    });
+
+    test('static utility', () => {
+      const cls = stylesToClasses({ display: 'flex' });
+      expect(cls).toEqual(['flex']);
+      clearRegistry();
+      expect(classToStyle('flex')).toEqual({ prop: 'display', value: 'flex' });
+    });
+
+    test('responsive round-trip, same process', () => {
+      const cls = responsiveStylesToClasses({ base: { padding: '24px' }, tablet: { padding: '16px' } });
+      expect(cls).toEqual(['p-6', 'max-lg:p-4']);
+      expect(classesToStyles(cls)).toEqual({ base: { padding: '24px' }, tablet: { padding: '16px' } });
+    });
+  });
+
+  describe('now-durable: literal underscores (Phase 1 encoding extension)', () => {
+    // Previously these hash-fell-back into the ephemeral registry. The `\_`
+    // escape now encodes them reversibly into the class name itself.
+    test('underscore value survives a registry wipe', () => {
+      const cls = stylesToClasses({ animationName: 'slide_in' });
+      expect(cls).toHaveLength(1);
+      clearRegistry(); // fresh process: registry never warmed
+      expect(classToStyle(cls[0]!)?.value).toBe('slide_in');
+    });
+
+    test('underscore + spaces round-trip after a wipe', () => {
+      const cls = stylesToClasses({ animation: 'fade_in 2s ease' });
+      expect(cls).toHaveLength(1);
+      clearRegistry();
+      expect(classToStyle(cls[0]!)?.value).toBe('fade_in 2s ease');
+    });
+  });
+
+  describe('PHASE 1 GATE — ephemeral: value lives only in the registry (lost on reload)', () => {
+    // A value that `encodeArbitraryValue` cannot encode reversibly (literal
+    // quotes) falls back to a `*-h<hash>` class whose real value is stashed in
+    // the ephemeral style-value registry — e.g. grid-template-areas, which
+    // legitimately needs quotes.
+    const STYLE = { gridTemplateAreas: '"a a" "b c"' };
+
+    test('warm registry recovers the value (same-process round-trip holds)', () => {
+      clearRegistry();
+      const cls = stylesToClasses(STYLE);
+      expect(cls).toHaveLength(1);
+      // Forward pass registered the value, so the reverse recovers it.
+      expect(classToStyle(cls[0]!)?.value).toBe('"a a" "b c"');
+    });
+
+    test('after a registry wipe the value is LOST from the class name alone (codec side-channels it)', () => {
+      clearRegistry();
+      const cls = stylesToClasses(STYLE);
+      const onDiskClass = cls[0]!; // this is all the class NAME carries
+      clearRegistry(); // fresh process: parse from disk, registry never warmed
+      // The class name alone can't recover the value — which is WHY the codec emits the durable
+      // `const __styleValues` side-channel (meno-astro `dialect/styleValues.ts` + its tests),
+      // restoring the value into this registry on parse so `classToStyle` recovers it.
+      expect(classToStyle(onDiskClass)).toBeNull();
+    });
+  });
+});