@3fn/core 14.1.0 → 15.0.0

package/src/__tests__/browser-distribution/mcp-queryability.test.ts

@@ -1,342 +0,0 @@
-/**
- * @jest-environment node
- * @category evergreen
- * @purpose Verify Browser Distribution Guide is indexed and queryable via MCP server
- */
-
-/**
- * MCP Queryability Test
- *
- * Verifies that the Browser Distribution Guide steering document is properly
- * structured for MCP server indexing and can be queried. This test validates:
- * - Document exists in the correct location
- * - Document has required MCP metadata
- * - Document structure supports MCP queries (sections, cross-references)
- * - MCP server is built and available
- *
- * Note: Direct MCP server integration tests are in mcp-server/src/__tests__/
- * This test focuses on verifying the document is properly structured for MCP.
- *
- * @see .kiro/specs/028-web-component-browser-distribution/design.md
- * @see Requirements: 9.5
- * @validates Requirements 9.5
- */
-
-import { execSync } from 'child_process';
-import * as path from 'path';
-import * as fs from 'fs';
-
-describe('MCP Queryability: Browser Distribution Guide', () => {
-  const MCP_SERVER_DIR = path.join(process.cwd(), 'mcp-server');
-  const BROWSER_DISTRIBUTION_GUIDE_PATH = 'governance/browser-distribution-guide.md';
-
-  describe('Document Indexing Prerequisites', () => {
-    /**
-     * Verify the Browser Distribution Guide file exists.
-     * This is a prerequisite for MCP indexing.
-     */
-    it('Browser Distribution Guide file should exist', () => {
-      const fullPath = path.join(process.cwd(), BROWSER_DISTRIBUTION_GUIDE_PATH);
-      expect(fs.existsSync(fullPath)).toBe(true);
-    });
-
-    /**
-     * Verify the document has required MCP metadata for indexing.
-     * The MCP server indexes documents based on metadata fields.
-     */
-    it('should have required metadata fields for MCP indexing', () => {
-      const fullPath = path.join(process.cwd(), BROWSER_DISTRIBUTION_GUIDE_PATH);
-      const content = fs.readFileSync(fullPath, 'utf-8');
-
-      // Required metadata fields for MCP indexing
-      const requiredFields = ['Date', 'Purpose', 'Organization', 'Scope', 'Layer'];
-
-      for (const field of requiredFields) {
-        const regex = new RegExp(`\\*\\*${field}\\*\\*:\\s*.+`, 'i');
-        expect(content).toMatch(regex);
-      }
-    });
-
-    /**
-     * Verify the document is in the served governance directory (indexed by MCP).
-     * MCP server indexes documents from governance/ directory (Spec 119-A).
-     */
-    it('should be in the served governance directory for MCP indexing', () => {
-      expect(BROWSER_DISTRIBUTION_GUIDE_PATH).toMatch(/^governance\//);
-    });
-  });
-
-  describe('Document Structure for Queryability', () => {
-    let documentContent: string;
-
-    beforeAll(() => {
-      const fullPath = path.join(process.cwd(), BROWSER_DISTRIBUTION_GUIDE_PATH);
-      documentContent = fs.readFileSync(fullPath, 'utf-8');
-    });
-
-    /**
-     * Verify the document has section headings for section-based queries.
-     * MCP server allows querying specific sections by heading.
-     */
-    it('should have queryable section headings', () => {
-      // Expected sections that should be queryable
-      const expectedSections = [
-        'Overview',
-        'Quick Start',
-        'ESM Loading Pattern',
-        'UMD Loading Pattern',
-        'Token Loading',
-        'Troubleshooting',
-      ];
-
-      for (const section of expectedSections) {
-        const regex = new RegExp(`^##\\s+${section}`, 'm');
-        expect(documentContent).toMatch(regex);
-      }
-    });
-
-    /**
-     * Verify the document has AI Agent Reading Priorities section.
-     * This section helps AI agents navigate the document efficiently.
-     */
-    it('should have AI Agent Reading Priorities section', () => {
-      expect(documentContent).toMatch(/^##\s+AI Agent Reading Priorities/m);
-    });
-
-    /**
-     * Verify the document has Related Documentation section.
-     * This enables cross-reference queries via MCP.
-     */
-    it('should have Related Documentation section with cross-references', () => {
-      expect(documentContent).toMatch(/^##\s+Related Documentation/m);
-
-      // Should have at least one markdown link
-      expect(documentContent).toMatch(/\[.+\]\(.+\.md\)/);
-    });
-
-    /**
-     * Verify the document has loading frontmatter.
-     * The inclusion field controls how the document is loaded by the context system.
-     */
-    it('should have loading frontmatter', () => {
-      // Check for frontmatter
-      expect(documentContent).toMatch(/^---\n/);
-
-      // Check for inclusion type
-      expect(documentContent).toMatch(/inclusion:\s*(conditional|always|manual)/);
-    });
-  });
-
-  describe('MCP Server Availability', () => {
-    /**
-     * Verify MCP server dist exists (server is built).
-     * This is required for MCP queryability.
-     */
-    it('MCP server should be built', () => {
-      const distPath = path.join(MCP_SERVER_DIR, 'dist', 'index.js');
-      expect(fs.existsSync(distPath)).toBe(true);
-    });
-
-    /**
-     * Verify MCP server package.json exists.
-     */
-    it('MCP server package.json should exist', () => {
-      const packagePath = path.join(MCP_SERVER_DIR, 'package.json');
-      expect(fs.existsSync(packagePath)).toBe(true);
-    });
-
-    /**
-     * Verify MCP server has required dependencies.
-     */
-    it('MCP server should have required dependencies', () => {
-      const packagePath = path.join(MCP_SERVER_DIR, 'package.json');
-      const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf-8'));
-
-      expect(packageJson.dependencies).toBeDefined();
-      expect(packageJson.dependencies['@modelcontextprotocol/sdk']).toBeDefined();
-    });
-  });
-
-  describe('MCP Server Integration via Subprocess', () => {
-    /**
-     * Verify the MCP server can be invoked and returns valid JSON.
-     * This tests actual MCP queryability through subprocess execution.
-     */
-    it('should be queryable via MCP server subprocess', () => {
-      const distPath = path.join(MCP_SERVER_DIR, 'dist', 'index.js');
-
-      if (!fs.existsSync(distPath)) {
-        console.log('Skipping: MCP server not built');
-        return;
-      }
-
-      // Test that the MCP server's DocumentIndexer can be instantiated
-      // by running a simple Node.js script that imports just the indexer
-      try {
-        const result = execSync(
-          `node -e "
-            const path = require('path');
-            const fs = require('fs');
-            
-            // Read the steering document directly
-            const docPath = path.join(process.cwd(), 'governance/browser-distribution-guide.md');
-            const content = fs.readFileSync(docPath, 'utf-8');
-            
-            // Parse metadata
-            const metadata = {};
-            const metadataRegex = /\\*\\*([^*]+)\\*\\*:\\s*(.+)/g;
-            let match;
-            while ((match = metadataRegex.exec(content)) !== null) {
-              metadata[match[1].trim()] = match[2].trim();
-            }
-            
-            // Parse sections
-            const sections = [];
-            const sectionRegex = /^##\\s+(.+)$/gm;
-            while ((match = sectionRegex.exec(content)) !== null) {
-              sections.push(match[1].trim());
-            }
-            
-            // Output result
-            console.log(JSON.stringify({
-              path: 'governance/browser-distribution-guide.md',
-              metadata: metadata,
-              sections: sections,
-              hasContent: content.length > 0
-            }));
-          "`,
-          { encoding: 'utf-8', timeout: 10000, cwd: process.cwd() }
-        );
-
-        const parsed = JSON.parse(result.trim());
-
-        // Verify the document was parsed correctly
-        expect(parsed.path).toBe('governance/browser-distribution-guide.md');
-        expect(parsed.hasContent).toBe(true);
-        expect(parsed.metadata.Purpose).toBeDefined();
-        expect(parsed.metadata.Layer).toBeDefined();
-        expect(parsed.sections.length).toBeGreaterThan(0);
-        expect(parsed.sections).toContain('Overview');
-        expect(parsed.sections).toContain('Troubleshooting');
-
-        console.log('MCP queryability verified via subprocess');
-        console.log(`  - Metadata fields: ${Object.keys(parsed.metadata).length}`);
-        console.log(`  - Sections: ${parsed.sections.length}`);
-      } catch (error) {
-        // If subprocess fails, log the error but don't fail the test
-        // as this might be due to environment issues
-        console.log('Subprocess test skipped due to environment issue');
-        console.log(error);
-      }
-    });
-
-    /**
-     * Verify the document can be found by the MCP server's file scanning.
-     * This simulates how the MCP server discovers documents.
-     */
-    it('should be discoverable by MCP server file scanning', () => {
-      const steeringDir = path.join(process.cwd(), 'governance');
-
-      // Verify served governance directory exists
-      expect(fs.existsSync(steeringDir)).toBe(true);
-
-      // Get all markdown files in the served governance directory
-      const files = fs.readdirSync(steeringDir).filter((f) => f.endsWith('.md'));
-
-      // Verify Browser Distribution Guide is in the list
-      expect(files).toContain('browser-distribution-guide.md');
-
-      console.log(`Found ${files.length} steering documents`);
-      console.log(`Browser Distribution Guide is discoverable: ✓`);
-    });
-  });
-
-  describe('Query Response Quality', () => {
-    /**
-     * Verify document content is comprehensive enough for AI agents.
-     * The document should provide actionable guidance.
-     */
-    it('should have comprehensive content for AI agent queries', () => {
-      const fullPath = path.join(process.cwd(), BROWSER_DISTRIBUTION_GUIDE_PATH);
-      const content = fs.readFileSync(fullPath, 'utf-8');
-
-      // Should have code examples
-      expect(content).toMatch(/```html/);
-      expect(content).toMatch(/```javascript/);
-
-      // Should have ESM and UMD patterns
-      expect(content).toContain('ESM');
-      expect(content).toContain('UMD');
-
-      // Should have troubleshooting guidance
-      expect(content).toContain('Troubleshooting');
-      expect(content).toContain('Components Not Rendering');
-      expect(content).toContain('Components Unstyled');
-
-      // Should have component reference
-      // Note: Stemma System migration - components now use *-base suffix pattern
-      expect(content).toContain('button-cta');
-      expect(content).toContain('input-text-base');
-      expect(content).toContain('icon-base');
-      expect(content).toContain('container-base');
-    });
-
-    /**
-     * Verify the document has appropriate token count for efficient queries.
-     * Documents should be comprehensive but not excessively large.
-     */
-    it('should have reasonable token count for efficient queries', () => {
-      const fullPath = path.join(process.cwd(), BROWSER_DISTRIBUTION_GUIDE_PATH);
-      const content = fs.readFileSync(fullPath, 'utf-8');
-
-      // Rough token estimate (words / 0.75)
-      const wordCount = content.split(/\s+/).length;
-      const estimatedTokens = Math.ceil(wordCount / 0.75);
-
-      // Should be comprehensive (at least 2000 tokens)
-      expect(estimatedTokens).toBeGreaterThan(2000);
-
-      // Should not be excessively large (under 15000 tokens)
-      expect(estimatedTokens).toBeLessThan(15000);
-
-      console.log(`Estimated token count: ${estimatedTokens}`);
-    });
-  });
-
-  describe('Cross-Reference Integrity', () => {
-    /**
-     * Verify cross-references point to existing documents.
-     */
-    it('should have valid cross-references to existing documents', () => {
-      const fullPath = path.join(process.cwd(), BROWSER_DISTRIBUTION_GUIDE_PATH);
-      const content = fs.readFileSync(fullPath, 'utf-8');
-      const docDir = path.dirname(fullPath);
-
-      // Extract markdown links
-      const linkRegex = /\[([^\]]+)\]\(([^)]+\.md)\)/g;
-      const links: Array<{ text: string; target: string }> = [];
-      let match;
-
-      while ((match = linkRegex.exec(content)) !== null) {
-        links.push({ text: match[1], target: match[2] });
-      }
-
-      // Verify each link points to an existing file
-      for (const link of links) {
-        const targetPath = path.resolve(docDir, link.target);
-        const exists = fs.existsSync(targetPath);
-
-        if (!exists) {
-          console.log(`Warning: Cross-reference "${link.text}" points to non-existent file: ${link.target}`);
-        }
-
-        // We expect at least some cross-references to exist
-        // Not all may exist if they're to external docs
-      }
-
-      // Should have at least one cross-reference
-      expect(links.length).toBeGreaterThan(0);
-      console.log(`Found ${links.length} cross-references`);
-    });
-  });
-});

package/src/__tests__/browser-distribution/minification-effectiveness.property.test.ts

@@ -1,188 +0,0 @@
-/**
- * @jest-environment node
- * @category evergreen
- * @purpose Property test for minification effectiveness
- */
-
-/**
- * Minification Effectiveness Property Test
- *
- * Property 3: Minification Effectiveness
- * Verifies that minified bundles are at least 50% smaller than non-minified versions.
- *
- * This property ensures that the minification process is working correctly and
- * providing meaningful size reduction for production deployments.
- *
- * @see .kiro/specs/028-web-component-browser-distribution/design.md
- * @see Requirements: 5.3
- * @validates Requirements 5.3
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import * as zlib from 'zlib';
-
-describe('Property 3: Minification Effectiveness', () => {
-  const BROWSER_DIST_DIR = path.join(process.cwd(), 'dist', 'browser');
-
-  /**
-   * Bundle configuration for testing
-   */
-  const BUNDLES = [
-    {
-      name: 'ESM',
-      devFile: 'designerpunk.esm.js',
-      minFile: 'designerpunk.esm.min.js',
-    },
-    {
-      name: 'UMD',
-      devFile: 'designerpunk.umd.js',
-      minFile: 'designerpunk.umd.min.js',
-    },
-  ];
-
-  /**
-   * Minimum expected size reduction (30%)
-   * Minified bundle should be at most 70% of the original size
-   * Note: esbuild's minification achieves ~35-40% reduction typically
-   */
-  const MAX_SIZE_RATIO = 0.7;
-
-  beforeAll(() => {
-    // Ensure bundles exist before running tests
-    if (!fs.existsSync(BROWSER_DIST_DIR)) {
-      throw new Error(
-        'Browser bundles not found. Run "npm run build:browser" first.'
-      );
-    }
-  });
-
-  describe('Raw Size Reduction', () => {
-    /**
-     * Property: For all bundle types, minified size <= 70% of development size
-     *
-     * This property validates that minification achieves meaningful size reduction.
-     * A 30% reduction is a reasonable minimum expectation for JavaScript minification
-     * with esbuild, which typically achieves 35-40% reduction.
-     */
-    test.each(BUNDLES)(
-      '$name bundle: minified should be at most 70% of development size',
-      ({ name, devFile, minFile }) => {
-        const devPath = path.join(BROWSER_DIST_DIR, devFile);
-        const minPath = path.join(BROWSER_DIST_DIR, minFile);
-
-        const devSize = fs.statSync(devPath).size;
-        const minSize = fs.statSync(minPath).size;
-
-        const ratio = minSize / devSize;
-        const reductionPercent = ((1 - ratio) * 100).toFixed(1);
-
-        // Log sizes for visibility
-        console.log(
-          `${name}: Dev=${devSize} bytes, Min=${minSize} bytes, Reduction=${reductionPercent}%`
-        );
-
-        // Property assertion: minified size should be at most 70% of dev size
-        expect(ratio).toBeLessThanOrEqual(MAX_SIZE_RATIO);
-      }
-    );
-  });
-
-  describe('Gzipped Size Reduction', () => {
-    /**
-     * Helper to get gzipped size of a file
-     */
-    function getGzippedSize(filePath: string): number {
-      const content = fs.readFileSync(filePath);
-      const gzipped = zlib.gzipSync(content);
-      return gzipped.length;
-    }
-
-    /**
-     * Property: For all bundle types, gzipped minified size < gzipped development size
-     *
-     * Even after gzip compression, minified bundles should be smaller.
-     * This validates that minification provides value beyond what gzip alone provides.
-     */
-    test.each(BUNDLES)(
-      '$name bundle: gzipped minified should be smaller than gzipped development',
-      ({ name, devFile, minFile }) => {
-        const devPath = path.join(BROWSER_DIST_DIR, devFile);
-        const minPath = path.join(BROWSER_DIST_DIR, minFile);
-
-        const devGzipSize = getGzippedSize(devPath);
-        const minGzipSize = getGzippedSize(minPath);
-
-        const reductionPercent = (
-          ((devGzipSize - minGzipSize) / devGzipSize) *
-          100
-        ).toFixed(1);
-
-        // Log gzipped sizes for visibility
-        console.log(
-          `${name} (gzip): Dev=${devGzipSize} bytes, Min=${minGzipSize} bytes, Reduction=${reductionPercent}%`
-        );
-
-        // Property assertion: gzipped minified should be smaller
-        expect(minGzipSize).toBeLessThan(devGzipSize);
-      }
-    );
-  });
-
-  describe('Source Map Integrity', () => {
-    /**
-     * Property: For all minified bundles, source maps should exist and be valid JSON
-     *
-     * Source maps are essential for debugging production issues.
-     * This property ensures they are generated correctly.
-     */
-    test.each(BUNDLES)(
-      '$name bundle: minified source map should be valid JSON',
-      ({ name, minFile }) => {
-        const mapPath = path.join(BROWSER_DIST_DIR, `${minFile}.map`);
-
-        expect(fs.existsSync(mapPath)).toBe(true);
-
-        const mapContent = fs.readFileSync(mapPath, 'utf-8');
-
-        // Property assertion: source map should be valid JSON
-        expect(() => JSON.parse(mapContent)).not.toThrow();
-
-        const sourceMap = JSON.parse(mapContent);
-
-        // Property assertion: source map should have required fields
-        expect(sourceMap).toHaveProperty('version');
-        expect(sourceMap).toHaveProperty('sources');
-        expect(sourceMap).toHaveProperty('mappings');
-      }
-    );
-  });
-
-  describe('Bundle Content Preservation', () => {
-    /**
-     * Property: For all bundle types, minified bundle should contain all component names
-     *
-     * Minification should not remove essential exports.
-     * This property ensures component names are preserved.
-     */
-    const REQUIRED_COMPONENTS = [
-      'TextInputField',
-      'ButtonCTA',
-      'IconBaseElement',
-      'ContainerBaseWeb',
-    ];
-
-    test.each(BUNDLES)(
-      '$name bundle: minified should contain all component names',
-      ({ name, minFile }) => {
-        const minPath = path.join(BROWSER_DIST_DIR, minFile);
-        const content = fs.readFileSync(minPath, 'utf-8');
-
-        // Property assertion: all component names should be present
-        for (const component of REQUIRED_COMPONENTS) {
-          expect(content).toContain(component);
-        }
-      }
-    );
-  });
-});