@forgespace/branding-mcp 0.4.0

package/src/__tests__/unit/ai-interpreter.test.ts

@@ -0,0 +1,172 @@
+import { interpretWithKeywords } from '../../lib/branding-core/ai/keyword-interpreter.js';
+import { applyIntent } from '../../lib/branding-core/ai/intent-applier.js';
+import { interpretFeedback } from '../../lib/branding-core/ai/brand-interpreter.js';
+import { generateColorPalette } from '../../lib/branding-core/generators/color-palette.js';
+import { generateTypographySystem } from '../../lib/branding-core/generators/typography-system.js';
+import { generateSpacingScale } from '../../lib/branding-core/generators/spacing-scale.js';
+
+function createTestBrand() {
+  return {
+    id: 'test_brand',
+    name: 'Test',
+    industry: 'tech',
+    style: 'tech' as const,
+    colors: generateColorPalette('#6B4CE6'),
+    typography: generateTypographySystem(),
+    spacing: generateSpacingScale(),
+    createdAt: '2026-01-01T00:00:00Z',
+  };
+}
+
+describe('interpretWithKeywords', () => {
+  it('interprets "warm" as analogous with positive hue shift', () => {
+    const intent = interpretWithKeywords('make it warmer', 'colors');
+    expect(intent.color?.harmony).toBe('analogous');
+    expect(intent.color?.hueShift).toBeGreaterThan(0);
+  });
+
+  it('interprets "vibrant" as triadic with saturation boost', () => {
+    const intent = interpretWithKeywords('more vibrant colors', 'colors');
+    expect(intent.color?.harmony).toBe('triadic');
+    expect(intent.color?.saturationShift).toBeGreaterThan(0);
+  });
+
+  it('interprets "muted" as monochromatic with reduced saturation', () => {
+    const intent = interpretWithKeywords('make it muted', 'colors');
+    expect(intent.color?.harmony).toBe('monochromatic');
+    expect(intent.color?.saturationShift).toBeLessThan(0);
+  });
+
+  it('interprets "premium" as analogous with lower saturation and lightness', () => {
+    const intent = interpretWithKeywords('premium feel', 'colors');
+    expect(intent.color?.harmony).toBe('analogous');
+    expect(intent.color?.saturationShift).toBeLessThan(0);
+  });
+
+  it('interprets "dark" theme', () => {
+    const intent = interpretWithKeywords('make it darker', 'colors');
+    expect(intent.color?.theme).toBe('dark');
+    expect(intent.color?.lightnessShift).toBeLessThan(0);
+  });
+
+  it('falls back to complementary with no matching keywords', () => {
+    const intent = interpretWithKeywords('xyzzy', 'colors');
+    expect(intent.color?.harmony).toBe('complementary');
+  });
+
+  it('interprets "serif" for typography', () => {
+    const intent = interpretWithKeywords('use serif headings', 'typography');
+    expect(intent.typography?.headingCategory).toBe('serif');
+  });
+
+  it('interprets "monospace" for typography body', () => {
+    const intent = interpretWithKeywords('monospace body text', 'typography');
+    expect(intent.typography?.bodyCategory).toBe('monospace');
+  });
+
+  it('interprets "dramatic" scale for typography', () => {
+    const intent = interpretWithKeywords('dramatic type scale', 'typography');
+    expect(intent.typography?.scaleRatio).toBe('golden-ratio');
+  });
+
+  it('interprets "editorial" as serif + perfect-fourth', () => {
+    const intent = interpretWithKeywords('editorial style', 'typography');
+    expect(intent.typography?.headingCategory).toBe('serif');
+    expect(intent.typography?.scaleRatio).toBe('perfect-fourth');
+  });
+
+  it('interprets "modern" as sans-serif heading and body', () => {
+    const intent = interpretWithKeywords('modern look', 'typography');
+    expect(intent.typography?.headingCategory).toBe('sans-serif');
+    expect(intent.typography?.bodyCategory).toBe('sans-serif');
+  });
+
+  it('falls back for typography with no matching keywords', () => {
+    const intent = interpretWithKeywords('xyzzy', 'typography');
+    expect(intent.typography?.headingCategory).toBe('sans-serif');
+  });
+
+  it('returns reasoning for spacing with no actions', () => {
+    const intent = interpretWithKeywords('more space', 'spacing');
+    expect(intent.reasoning).toBeDefined();
+  });
+
+  it('includes reasoning string', () => {
+    const intent = interpretWithKeywords('warm and vibrant', 'colors');
+    expect(intent.reasoning).toContain('Keyword match');
+  });
+
+  it('merges multiple color keywords', () => {
+    const intent = interpretWithKeywords('warm and bold', 'colors');
+    expect(intent.color?.saturationShift).toBeGreaterThan(0);
+    expect(intent.color?.hueShift).toBeGreaterThan(0);
+  });
+});
+
+describe('applyIntent', () => {
+  it('applies color intent to generate new palette', () => {
+    const brand = createTestBrand();
+    const updated = applyIntent(brand, {
+      color: { harmony: 'triadic', saturationShift: 10 },
+    });
+    expect(updated.colors).toBeDefined();
+    expect(updated.colors.primary.hex).not.toBe(brand.colors.primary.hex);
+  });
+
+  it('applies typography intent', () => {
+    const brand = createTestBrand();
+    const updated = applyIntent(brand, {
+      typography: { headingCategory: 'serif', scaleRatio: 'perfect-fourth' },
+    });
+    expect(updated.typography.scaleRatio).toBe(1.333);
+  });
+
+  it('applies style change', () => {
+    const brand = createTestBrand();
+    const updated = applyIntent(brand, { style: 'elegant' });
+    expect(updated.style).toBe('elegant');
+  });
+
+  it('applies hue shift to base color', () => {
+    const brand = createTestBrand();
+    const updated = applyIntent(brand, {
+      color: { hueShift: 30 },
+    });
+    expect(updated.colors.primary.hex).toBeDefined();
+  });
+
+  it('preserves unchanged elements', () => {
+    const brand = createTestBrand();
+    const updated = applyIntent(brand, { color: { harmony: 'analogous' } });
+    expect(updated.typography).toEqual(brand.typography);
+    expect(updated.spacing).toEqual(brand.spacing);
+  });
+
+  it('returns brand unchanged with empty intent', () => {
+    const brand = createTestBrand();
+    const updated = applyIntent(brand, {});
+    expect(updated.colors).toEqual(brand.colors);
+    expect(updated.typography).toEqual(brand.typography);
+  });
+});
+
+describe('interpretFeedback (strategy selection)', () => {
+  it('uses keyword strategy when no API key', async () => {
+    const brand = createTestBrand();
+    const intent = await interpretFeedback('warm colors', 'colors', brand, 'auto');
+    expect(intent.color?.harmony).toBe('analogous');
+    expect(intent.reasoning).toContain('Keyword');
+  });
+
+  it('uses keyword strategy when explicitly set', async () => {
+    const brand = createTestBrand();
+    const intent = await interpretFeedback('warm colors', 'colors', brand, 'keyword');
+    expect(intent.color?.harmony).toBe('analogous');
+  });
+
+  it('falls back to keywords when ai strategy has no key', async () => {
+    const brand = createTestBrand();
+    const intent = await interpretFeedback('warm', 'colors', brand, 'ai', {});
+    expect(intent.reasoning).toContain('Keyword');
+  });
+});

package/src/__tests__/unit/border-system.test.ts

@@ -0,0 +1,77 @@
+import { generateBorderSystem } from '../../lib/branding-core/generators/border-system.js';
+import type { BrandStyle } from '../../lib/types.js';
+
+describe('generateBorderSystem', () => {
+  it('generates all radius levels', () => {
+    const system = generateBorderSystem();
+    const names = Object.keys(system.radii);
+    expect(names).toEqual(['none', 'sm', 'md', 'lg', 'xl', 'full', 'circle']);
+  });
+
+  it('none radius is always 0px', () => {
+    const system = generateBorderSystem('playful');
+    expect(system.radii.none).toBe('0px');
+  });
+
+  it('full and circle are always 9999px', () => {
+    const styles: BrandStyle[] = ['minimal', 'bold', 'elegant', 'playful'];
+    for (const style of styles) {
+      const system = generateBorderSystem(style);
+      expect(system.radii.full).toBe('9999px');
+      expect(system.radii.circle).toBe('9999px');
+    }
+  });
+
+  it('playful has larger radii than corporate', () => {
+    const playful = generateBorderSystem('playful');
+    const corporate = generateBorderSystem('corporate');
+    expect(parseInt(playful.radii.md)).toBeGreaterThan(parseInt(corporate.radii.md));
+  });
+
+  it('generates three border widths', () => {
+    const system = generateBorderSystem();
+    expect(system.widths.thin).toBeDefined();
+    expect(system.widths.medium).toBeDefined();
+    expect(system.widths.thick).toBeDefined();
+  });
+
+  it('border widths increase thin < medium < thick', () => {
+    const system = generateBorderSystem('bold');
+    const thin = parseInt(system.widths.thin);
+    const medium = parseInt(system.widths.medium);
+    const thick = parseInt(system.widths.thick);
+    expect(thin).toBeLessThanOrEqual(medium);
+    expect(medium).toBeLessThanOrEqual(thick);
+  });
+
+  it('bold style has thicker borders', () => {
+    const bold = generateBorderSystem('bold');
+    const minimal = generateBorderSystem('minimal');
+    expect(parseInt(bold.widths.thick)).toBeGreaterThanOrEqual(parseInt(minimal.widths.thick));
+  });
+
+  it('radii values are formatted as px strings', () => {
+    const system = generateBorderSystem();
+    for (const value of Object.values(system.radii)) {
+      expect(value).toMatch(/^\d+px$/);
+    }
+  });
+
+  it('works for all brand styles', () => {
+    const styles: BrandStyle[] = [
+      'minimal',
+      'bold',
+      'elegant',
+      'playful',
+      'corporate',
+      'tech',
+      'organic',
+      'retro',
+    ];
+    for (const style of styles) {
+      const system = generateBorderSystem(style);
+      expect(Object.keys(system.radii)).toHaveLength(7);
+      expect(Object.keys(system.widths)).toHaveLength(3);
+    }
+  });
+});

package/src/__tests__/unit/color-palette.test.ts

@@ -0,0 +1,161 @@
+import {
+  generateColorPalette,
+  checkContrast,
+  hslToHex,
+  hexToHsl,
+} from '../../lib/branding-core/generators/color-palette.js';
+
+describe('hslToHex', () => {
+  it('converts pure red', () => {
+    expect(hslToHex(0, 100, 50)).toBe('#ff0000');
+  });
+
+  it('converts pure green', () => {
+    expect(hslToHex(120, 100, 50)).toBe('#00ff00');
+  });
+
+  it('converts pure blue', () => {
+    expect(hslToHex(240, 100, 50)).toBe('#0000ff');
+  });
+
+  it('converts white', () => {
+    expect(hslToHex(0, 0, 100)).toBe('#ffffff');
+  });
+
+  it('converts black', () => {
+    expect(hslToHex(0, 0, 0)).toBe('#000000');
+  });
+
+  it('handles negative hue via wrapping', () => {
+    const result = hslToHex(-60, 100, 50);
+    expect(result).toMatch(/^#[0-9a-f]{6}$/);
+  });
+});
+
+describe('hexToHsl', () => {
+  it('converts red hex to HSL', () => {
+    const hsl = hexToHsl('#ff0000');
+    expect(hsl.h).toBe(0);
+    expect(hsl.s).toBe(100);
+    expect(hsl.l).toBe(50);
+  });
+
+  it('converts white hex to HSL', () => {
+    const hsl = hexToHsl('#ffffff');
+    expect(hsl.l).toBe(100);
+  });
+
+  it('handles invalid hex gracefully', () => {
+    const hsl = hexToHsl('invalid');
+    expect(hsl).toEqual({ h: 0, s: 0, l: 0 });
+  });
+
+  it('handles hex without hash', () => {
+    const hsl = hexToHsl('ff0000');
+    expect(hsl.h).toBe(0);
+    expect(hsl.s).toBe(100);
+  });
+});
+
+describe('checkContrast', () => {
+  it('returns maximum contrast for black on white', () => {
+    const result = checkContrast('#000000', '#ffffff');
+    expect(result.ratio).toBeGreaterThan(20);
+    expect(result.aa).toBe(true);
+    expect(result.aaa).toBe(true);
+  });
+
+  it('returns minimum contrast for same color', () => {
+    const result = checkContrast('#808080', '#808080');
+    expect(result.ratio).toBe(1);
+    expect(result.aa).toBe(false);
+  });
+
+  it('correctly identifies AA pass for dark blue on white', () => {
+    const result = checkContrast('#003366', '#ffffff');
+    expect(result.aa).toBe(true);
+  });
+
+  it('correctly identifies AA failure for light gray on white', () => {
+    const result = checkContrast('#cccccc', '#ffffff');
+    expect(result.aa).toBe(false);
+  });
+});
+
+describe('generateColorPalette', () => {
+  it('generates a complete palette with defaults', () => {
+    const palette = generateColorPalette();
+    expect(palette.primary).toBeDefined();
+    expect(palette.secondary).toBeDefined();
+    expect(palette.accent).toBeDefined();
+    expect(palette.neutral.length).toBeGreaterThanOrEqual(4);
+    expect(palette.semantic.success).toBeDefined();
+    expect(palette.semantic.warning).toBeDefined();
+    expect(palette.semantic.error).toBeDefined();
+    expect(palette.semantic.info).toBeDefined();
+    expect(palette.contrast).toBeDefined();
+  });
+
+  it('generates palette from a base color', () => {
+    const palette = generateColorPalette('#6B4CE6');
+    expect(palette.primary.hex).toMatch(/^#[0-9a-f]{6}$/);
+  });
+
+  it('generates complementary palette', () => {
+    const palette = generateColorPalette('#0000ff', 'complementary');
+    expect(palette.primary).toBeDefined();
+    expect(palette.secondary).toBeDefined();
+  });
+
+  it('generates analogous palette', () => {
+    const palette = generateColorPalette('#0000ff', 'analogous');
+    expect(palette.primary).toBeDefined();
+  });
+
+  it('generates triadic palette', () => {
+    const palette = generateColorPalette('#0000ff', 'triadic');
+    expect(palette.primary).toBeDefined();
+  });
+
+  it('generates monochromatic palette', () => {
+    const palette = generateColorPalette('#6B4CE6', 'monochromatic');
+    expect(palette.primary).toBeDefined();
+  });
+
+  it('generates dark theme neutrals', () => {
+    const palette = generateColorPalette('#6B4CE6', 'complementary', 'dark');
+    expect(palette.neutral.length).toBeGreaterThanOrEqual(4);
+  });
+
+  it('includes contrast data', () => {
+    const palette = generateColorPalette();
+    expect(palette.contrast['primary-on-white']).toBeDefined();
+    expect(palette.contrast['primary-on-white'].ratio).toBeGreaterThan(0);
+  });
+
+  it('generates split-complementary palette', () => {
+    const palette = generateColorPalette('#0000ff', 'split-complementary');
+    expect(palette.primary).toBeDefined();
+  });
+
+  it('generates tetradic palette', () => {
+    const palette = generateColorPalette('#0000ff', 'tetradic');
+    expect(palette.primary).toBeDefined();
+  });
+
+  it('generates light theme neutrals', () => {
+    const palette = generateColorPalette('#6B4CE6', 'complementary', 'light');
+    expect(palette.neutral.length).toBeGreaterThanOrEqual(4);
+  });
+
+  it('produces valid hex colors for all swatches', () => {
+    const palette = generateColorPalette('#FF6B35', 'triadic');
+    const hexRegex = /^#[0-9a-f]{6}$/;
+    expect(palette.primary.hex).toMatch(hexRegex);
+    expect(palette.secondary.hex).toMatch(hexRegex);
+    expect(palette.accent.hex).toMatch(hexRegex);
+    for (const n of palette.neutral) {
+      expect(n.hex).toMatch(hexRegex);
+    }
+  });
+});

package/src/__tests__/unit/contrast-checker.test.ts

@@ -0,0 +1,124 @@
+import { validateContrast } from '../../lib/branding-core/validators/contrast-checker.js';
+import { validateBrandConsistency } from '../../lib/branding-core/validators/brand-consistency.js';
+import { generateColorPalette } from '../../lib/branding-core/generators/color-palette.js';
+import { generateTypographySystem } from '../../lib/branding-core/generators/typography-system.js';
+import { generateSpacingScale } from '../../lib/branding-core/generators/spacing-scale.js';
+import type { BrandIdentity } from '../../lib/types.js';
+
+function createTestBrand(overrides?: Partial<BrandIdentity>): BrandIdentity {
+  return {
+    id: 'test_brand',
+    name: 'Test',
+    industry: 'tech',
+    style: 'tech',
+    colors: generateColorPalette('#003366'),
+    typography: generateTypographySystem(),
+    spacing: generateSpacingScale(),
+    createdAt: '2026-01-01T00:00:00Z',
+    ...overrides,
+  };
+}
+
+describe('validateContrast', () => {
+  it('returns no issues for high-contrast colors', () => {
+    const brand = createTestBrand({ colors: generateColorPalette('#003366') });
+    const issues = validateContrast(brand);
+    const errors = issues.filter((i) => i.severity === 'error');
+    expect(errors.length).toBe(0);
+  });
+
+  it('flags low-contrast colors', () => {
+    const brand = createTestBrand({ colors: generateColorPalette('#cccccc') });
+    const issues = validateContrast(brand);
+    expect(issues.length).toBeGreaterThan(0);
+  });
+});
+
+describe('validateBrandConsistency', () => {
+  it('validates a complete brand as valid', () => {
+    const brand = createTestBrand();
+    const result = validateBrandConsistency(brand);
+    expect(result.score).toBeGreaterThan(0);
+    expect(typeof result.valid).toBe('boolean');
+    expect(Array.isArray(result.issues)).toBe(true);
+  });
+
+  it('includes contrast issues in overall validation', () => {
+    const brand = createTestBrand({ colors: generateColorPalette('#cccccc') });
+    const result = validateBrandConsistency(brand);
+    expect(result.issues.length).toBeGreaterThan(0);
+  });
+
+  it('validates typography properties', () => {
+    const brand = createTestBrand();
+    const result = validateBrandConsistency(brand);
+    const typographyIssues = result.issues.filter((i) => i.element.startsWith('typography'));
+    expect(typographyIssues.every((i) => i.severity !== 'error')).toBe(true);
+  });
+
+  it('returns score between 0 and 100', () => {
+    const brand = createTestBrand();
+    const result = validateBrandConsistency(brand);
+    expect(result.score).toBeGreaterThanOrEqual(0);
+    expect(result.score).toBeLessThanOrEqual(100);
+  });
+
+  it('flags missing primary color', () => {
+    const brand = createTestBrand();
+    brand.colors.primary.hex = '';
+    const result = validateBrandConsistency(brand);
+    expect(result.issues.some((i) => i.element === 'color.primary')).toBe(true);
+    expect(result.valid).toBe(false);
+  });
+
+  it('flags missing secondary color', () => {
+    const brand = createTestBrand();
+    brand.colors.secondary.hex = '';
+    const result = validateBrandConsistency(brand);
+    expect(result.issues.some((i) => i.element === 'color.secondary')).toBe(true);
+  });
+
+  it('flags too few neutral shades', () => {
+    const brand = createTestBrand();
+    brand.colors.neutral = brand.colors.neutral.slice(0, 2);
+    const result = validateBrandConsistency(brand);
+    expect(result.issues.some((i) => i.element === 'color.neutral')).toBe(true);
+  });
+
+  it('flags missing heading font', () => {
+    const brand = createTestBrand();
+    brand.typography.headingFont = '';
+    const result = validateBrandConsistency(brand);
+    expect(result.issues.some((i) => i.element === 'typography.headingFont')).toBe(true);
+    expect(result.valid).toBe(false);
+  });
+
+  it('flags missing body font', () => {
+    const brand = createTestBrand();
+    brand.typography.bodyFont = '';
+    const result = validateBrandConsistency(brand);
+    expect(result.issues.some((i) => i.element === 'typography.bodyFont')).toBe(true);
+  });
+
+  it('flags base size outside recommended range', () => {
+    const brand = createTestBrand();
+    brand.typography.baseSize = 10;
+    const result = validateBrandConsistency(brand);
+    expect(result.issues.some((i) => i.element === 'typography.baseSize')).toBe(true);
+  });
+
+  it('flags base size above recommended range', () => {
+    const brand = createTestBrand();
+    brand.typography.baseSize = 24;
+    const result = validateBrandConsistency(brand);
+    expect(result.issues.some((i) => i.element === 'typography.baseSize')).toBe(true);
+  });
+
+  it('reduces score for errors more than warnings', () => {
+    const brand = createTestBrand();
+    brand.colors.primary.hex = '';
+    brand.colors.secondary.hex = '';
+    const result = validateBrandConsistency(brand);
+    expect(result.score).toBeLessThan(70);
+  });
+});