@gravitykit/block-mcp 2.0.0-beta

package/src/__tests__/unit/preferences/enrich-block-list.test.ts

@@ -0,0 +1,175 @@
+/**
+ * Unit tests for enrichBlockList().
+ *
+ * The function is purely synchronous and side-effect-free: feed it a Block
+ * array, get back { blocks, warnings, summary }. No HTTP, no client.
+ *
+ * Key invariants tested:
+ *   - Only blocks with server-attached `preference` field generate warnings
+ *   - Any tier (legacy OR avoid) generates a warning
+ *   - Nested innerBlocks are walked (legacy blocks inside groups surface)
+ *   - Empty input returns clean state
+ *   - Summary text varies by warning count
+ */
+
+import { describe, it, expect } from 'vitest';
+import { enrichBlockList } from '../../../preferences.js';
+import type { Block } from '../../../types.js';
+import {
+  paragraphBlock,
+  headingBlock,
+  legacyHeadingBlock,
+  avoidBlock,
+  groupBlock,
+} from '../../fixtures/block-trees.js';
+import { assertPreferenceWarning } from '../../helpers/schema-asserts.js';
+
+// ── Empty input ───────────────────────────────────────────────────────────────
+
+describe('enrichBlockList — empty input', () => {
+  it('returns empty warnings array', () => {
+    const result = enrichBlockList([]);
+    expect(result.warnings).toHaveLength(0);
+  });
+
+  it('returns empty blocks array', () => {
+    expect(enrichBlockList([]).blocks).toHaveLength(0);
+  });
+
+  it('returns clean summary when no blocks', () => {
+    const result = enrichBlockList([]);
+    expect(result.summary).toMatch(/preferred or acceptable/);
+  });
+});
+
+// ── Preferred/acceptable blocks (no preference field attached) ─────────────
+
+describe('enrichBlockList — clean blocks', () => {
+  it('returns no warnings for core blocks', () => {
+    const blocks = [paragraphBlock, headingBlock] as unknown as Block[];
+    const result = enrichBlockList(blocks);
+    expect(result.warnings).toHaveLength(0);
+  });
+
+  it('returns the original blocks array reference', () => {
+    const blocks = [paragraphBlock] as unknown as Block[];
+    const result = enrichBlockList(blocks);
+    expect(result.blocks).toBe(blocks);
+  });
+
+  it('summary says preferred/acceptable', () => {
+    const blocks = [paragraphBlock] as unknown as Block[];
+    expect(enrichBlockList(blocks).summary).toMatch(/preferred or acceptable/);
+  });
+
+  it('does not invent warnings for unrecognised namespaces without preference field', () => {
+    const customBlock: Block = {
+      index: 0, name: 'customplugin/widget', attributes: {},
+    };
+    expect(enrichBlockList([customBlock]).warnings).toHaveLength(0);
+  });
+});
+
+// ── Non-preferred blocks (server attaches preference field) ───────────────
+
+describe('enrichBlockList — non-preferred blocks', () => {
+  it('warns about a legacy-tier block', () => {
+    const blocks = [legacyHeadingBlock] as unknown as Block[];
+    const result = enrichBlockList(blocks);
+    expect(result.warnings).toHaveLength(1);
+    assertPreferenceWarning(result.warnings[0]);
+    expect(result.warnings[0].block).toBe('ugb/heading');
+  });
+
+  it('warns about an avoid-tier block', () => {
+    const blocks = [avoidBlock] as unknown as Block[];
+    const result = enrichBlockList(blocks);
+    expect(result.warnings).toHaveLength(1);
+    expect(result.warnings[0].block).toBe('stackable/heading');
+  });
+
+  it('warns about multiple non-preferred blocks', () => {
+    const blocks = [legacyHeadingBlock, avoidBlock] as unknown as Block[];
+    const result = enrichBlockList(blocks);
+    expect(result.warnings).toHaveLength(2);
+    const names = result.warnings.map((w) => w.block);
+    expect(names).toContain('ugb/heading');
+    expect(names).toContain('stackable/heading');
+  });
+
+  it('includes suggested_replacement when provided', () => {
+    const blocks = [legacyHeadingBlock] as unknown as Block[];
+    const result = enrichBlockList(blocks);
+    expect(result.warnings[0].suggested_replacement).toBe('core/heading');
+  });
+
+  it('summary mentions block names', () => {
+    const blocks = [legacyHeadingBlock] as unknown as Block[];
+    const result = enrichBlockList(blocks);
+    expect(result.summary).toContain('ugb/heading');
+    expect(result.summary).toMatch(/1 non-preferred/);
+  });
+
+  it('summary mentions count when multiple warnings', () => {
+    const blocks = [legacyHeadingBlock, avoidBlock] as unknown as Block[];
+    const result = enrichBlockList(blocks);
+    expect(result.summary).toMatch(/2 non-preferred/);
+  });
+});
+
+// ── Nested innerBlocks walk ───────────────────────────────────────────────
+
+describe('enrichBlockList — nested innerBlocks', () => {
+  it('finds legacy block inside a core/group', () => {
+    // groupBlock has two preferred innerBlocks — no warnings expected
+    const clean = enrichBlockList([groupBlock as unknown as Block]);
+    expect(clean.warnings).toHaveLength(0);
+  });
+
+  it('surfaces legacy block nested inside a container', () => {
+    const containerWithLegacy: Block = {
+      index: 0,
+      name: 'core/group',
+      attributes: {},
+      innerBlocks: [
+        legacyHeadingBlock as unknown as Block,
+        { index: 2, name: 'core/paragraph', attributes: {} },
+      ],
+    };
+    const result = enrichBlockList([containerWithLegacy]);
+    expect(result.warnings).toHaveLength(1);
+    expect(result.warnings[0].block).toBe('ugb/heading');
+  });
+
+  it('surfaces avoid block two levels deep', () => {
+    const deeplyNested: Block = {
+      index: 0,
+      name: 'core/columns',
+      attributes: {},
+      innerBlocks: [
+        {
+          index: 1,
+          name: 'core/column',
+          attributes: {},
+          innerBlocks: [avoidBlock as unknown as Block],
+        },
+      ],
+    };
+    const result = enrichBlockList([deeplyNested]);
+    expect(result.warnings).toHaveLength(1);
+    expect(result.warnings[0].block).toBe('stackable/heading');
+  });
+});
+
+// ── Mixed pages ───────────────────────────────────────────────────────────
+
+describe('enrichBlockList — mixed preferred + non-preferred', () => {
+  it('only warns about non-preferred blocks', () => {
+    const blocks = [paragraphBlock, legacyHeadingBlock, headingBlock, avoidBlock] as unknown as Block[];
+    const result = enrichBlockList(blocks);
+    expect(result.warnings).toHaveLength(2);
+    const warnedNames = result.warnings.map((w) => w.block);
+    expect(warnedNames).not.toContain('core/paragraph');
+    expect(warnedNames).not.toContain('core/heading');
+  });
+});

package/src/__tests__/unit/preferences/enrich-pattern-list.test.ts

@@ -0,0 +1,227 @@
+/**
+ * Unit tests for enrichPatternList() and enrichBlockTypes().
+ *
+ * Both functions transform API arrays into { items, summary/guidance } objects.
+ * No HTTP, no client, no mocks needed.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { enrichPatternList, enrichBlockTypes } from '../../../preferences.js';
+import type { Pattern, BlockType } from '../../../types.js';
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function makePattern(overrides: Partial<Pattern> & { id: number; name: string }): Pattern {
+  return {
+    type: 'synced',
+    created: '2026-01-01',
+    modified: '2026-01-01',
+    reference_count: 0,
+    preference: { score: 80, tier: 'recommended', reasons: [] },
+    contains_blocks: [],
+    has_legacy_blocks: false,
+    ...overrides,
+  };
+}
+
+function makeBlockType(
+  name: string,
+  tier: BlockType['preference']['tier'],
+  score = 80
+): BlockType {
+  return {
+    name,
+    title: name.split('/')[1] ?? name,
+    category: 'text',
+    preference: { score, tier },
+  };
+}
+
+// ── enrichPatternList ─────────────────────────────────────────────────────────
+
+describe('enrichPatternList — empty input', () => {
+  it('returns empty patterns array', () => {
+    expect(enrichPatternList([]).patterns).toHaveLength(0);
+  });
+
+  it('returns "No patterns found" summary', () => {
+    expect(enrichPatternList([]).summary).toMatch(/No patterns found/);
+  });
+});
+
+describe('enrichPatternList — sorting', () => {
+  it('sorts by score descending', () => {
+    const patterns = [
+      makePattern({ id: 1, name: 'Low',  preference: { score: 10, tier: 'avoid',       reasons: [] } }),
+      makePattern({ id: 2, name: 'High', preference: { score: 95, tier: 'recommended', reasons: [] } }),
+      makePattern({ id: 3, name: 'Mid',  preference: { score: 50, tier: 'recommended', reasons: [] } }),
+    ];
+    const result = enrichPatternList(patterns);
+    expect(result.patterns[0].name).toBe('High');
+    expect(result.patterns[1].name).toBe('Mid');
+    expect(result.patterns[2].name).toBe('Low');
+  });
+
+  it('preserves equal-score order (stable sort is not required, just non-crash)', () => {
+    const patterns = [
+      makePattern({ id: 1, name: 'A', preference: { score: 80, tier: 'recommended', reasons: [] } }),
+      makePattern({ id: 2, name: 'B', preference: { score: 80, tier: 'recommended', reasons: [] } }),
+    ];
+    const result = enrichPatternList(patterns);
+    expect(result.patterns).toHaveLength(2);
+  });
+
+  it('does not mutate the input array', () => {
+    const patterns = [
+      makePattern({ id: 1, name: 'A', preference: { score: 10, tier: 'avoid',       reasons: [] } }),
+      makePattern({ id: 2, name: 'B', preference: { score: 95, tier: 'recommended', reasons: [] } }),
+    ];
+    const original = [...patterns];
+    enrichPatternList(patterns);
+    expect(patterns[0].name).toBe(original[0].name);
+  });
+});
+
+describe('enrichPatternList — summary generation', () => {
+  it('includes RECOMMENDED label for recommended patterns', () => {
+    const patterns = [
+      makePattern({ id: 1, name: 'Hero', preference: { score: 85, tier: 'recommended', reasons: [] } }),
+    ];
+    const result = enrichPatternList(patterns);
+    expect(result.summary).toMatch(/RECOMMENDED/);
+    expect(result.summary).toContain('Hero');
+  });
+
+  it('includes AVOID label for avoid-tier patterns', () => {
+    const patterns = [
+      makePattern({
+        id: 2, name: 'Old Legacy',
+        preference: { score: -80, tier: 'legacy', reasons: ['has_legacy_blocks'] },
+        has_legacy_blocks: true,
+        legacy_blocks: ['ugb/text'],
+      }),
+    ];
+    const result = enrichPatternList(patterns);
+    expect(result.summary).toMatch(/AVOID/);
+    expect(result.summary).toContain('Old Legacy');
+  });
+
+  it('includes legacy block names in the avoid section', () => {
+    const patterns = [
+      makePattern({
+        id: 3, name: 'Old Pattern',
+        preference: { score: -80, tier: 'legacy', reasons: [] },
+        has_legacy_blocks: true,
+        legacy_blocks: ['ugb/text', 'ugb/heading'],
+      }),
+    ];
+    const result = enrichPatternList(patterns);
+    expect(result.summary).toContain('ugb/text');
+  });
+
+  it('does not include AVOID label when all patterns are recommended', () => {
+    const patterns = [
+      makePattern({ id: 1, name: 'Good', preference: { score: 80, tier: 'recommended', reasons: [] } }),
+    ];
+    expect(enrichPatternList(patterns).summary).not.toMatch(/AVOID/);
+  });
+
+  it('shows both sections when mixed tiers', () => {
+    const patterns = [
+      makePattern({ id: 1, name: 'Good',  preference: { score: 80, tier: 'recommended', reasons: [] } }),
+      makePattern({ id: 2, name: 'Bad',   preference: { score: 0,  tier: 'legacy',      reasons: [] }, has_legacy_blocks: true }),
+    ];
+    const { summary } = enrichPatternList(patterns);
+    expect(summary).toMatch(/RECOMMENDED/);
+    expect(summary).toMatch(/AVOID/);
+  });
+
+  it('includes block namespace info for recommended patterns with contains_blocks', () => {
+    const patterns = [
+      makePattern({
+        id: 1, name: 'Hero',
+        preference: { score: 80, tier: 'recommended', reasons: [] },
+        contains_blocks: ['core/heading', 'core/paragraph', 'core/image'],
+      }),
+    ];
+    const { summary } = enrichPatternList(patterns);
+    // Should mention "core" namespace
+    expect(summary).toContain('core');
+  });
+});
+
+// ── enrichBlockTypes ──────────────────────────────────────────────────────────
+
+describe('enrichBlockTypes — empty input', () => {
+  it('returns empty block_types array', () => {
+    expect(enrichBlockTypes([]).block_types).toHaveLength(0);
+  });
+
+  it('returns guidance string (may be minimal)', () => {
+    const result = enrichBlockTypes([]);
+    expect(typeof result.guidance).toBe('string');
+  });
+});
+
+describe('enrichBlockTypes — tier grouping', () => {
+  it('all preferred types appear in guidance', () => {
+    const types = [makeBlockType('core/paragraph', 'preferred', 90)];
+    const result = enrichBlockTypes(types);
+    expect(result.guidance).toMatch(/PREFERRED|preferred/i);
+    expect(result.block_types).toContain(types[0]);
+  });
+
+  it('avoid-tier blocks appear in guidance with warning', () => {
+    const types = [makeBlockType('stackable/heading', 'avoid', 10)];
+    const result = enrichBlockTypes(types);
+    expect(result.guidance).toMatch(/avoid|AVOID/i);
+  });
+
+  it('legacy-tier blocks appear in guidance', () => {
+    const types = [makeBlockType('ugb/text', 'legacy', 0)];
+    const result = enrichBlockTypes(types);
+    expect(result.guidance).toMatch(/legacy|LEGACY/i);
+  });
+
+  it('groups all four tiers when all are present', () => {
+    const types = [
+      makeBlockType('core/paragraph',      'preferred',   90),
+      makeBlockType('outermost/icon',       'acceptable',  60),
+      makeBlockType('stackable/heading',    'avoid',       10),
+      makeBlockType('ugb/text',             'legacy',       0),
+    ];
+    const result = enrichBlockTypes(types);
+    expect(result.block_types).toHaveLength(4);
+    const guidance = result.guidance;
+    // All four tiers should have some representation in the guidance text
+    expect(guidance.length).toBeGreaterThan(20);
+  });
+
+  it('returns original types in block_types (not copies)', () => {
+    const types = [makeBlockType('core/heading', 'preferred', 90)];
+    const result = enrichBlockTypes(types);
+    expect(result.block_types).toContain(types[0]);
+  });
+
+  it('unknown tier falls through to acceptable bucket without crashing', () => {
+    const weirdType = {
+      ...makeBlockType('unknown/block', 'acceptable', 30),
+      preference: { score: 30, tier: 'unknown-tier' as any },
+    };
+    expect(() => enrichBlockTypes([weirdType])).not.toThrow();
+  });
+});
+
+describe('enrichBlockTypes — inline snapshot for stable guidance format', () => {
+  it('single preferred block produces expected guidance shape', () => {
+    const types = [makeBlockType('core/paragraph', 'preferred', 90)];
+    const { guidance } = enrichBlockTypes(types);
+    expect(guidance).toMatchInlineSnapshot(`"PREFERRED (core/): paragraph"`);
+  });
+
+  it('single legacy block produces expected guidance shape', () => {
+    const types = [makeBlockType('ugb/text', 'legacy', 0)];
+    const { guidance } = enrichBlockTypes(types);
+    expect(guidance).toMatchInlineSnapshot(`"LEGACY — DO NOT USE (ugb/): text"`);
+  });
+});