@dscodotco/theme-cli/docs/tutorials/analysis.md

A CLI tool for developing Shopify themes

# Theme Analysis Tutorial

This tutorial shows you how to analyze your Shopify theme's structure, dependencies, and performance using Theme CLI.

## Getting Started

First, let's set up our theme analysis tools:

```typescript
import { ThemeAPI } from '@dscodotco/theme-cli';
import { Shopify } from 'shopify-api-node';
import { ThemeManager } from './theme-manager';

// Initialize ThemeAPI
const shopify = new Shopify({
  shopName: process.env.SHOPIFY_STORE_NAME,
  accessToken: process.env.SHOPIFY_ACCESS_TOKEN
});

const themeManager = new ThemeManager({
  credentials: {
    storeName: process.env.SHOPIFY_STORE_NAME,
    apiKey: process.env.SHOPIFY_API_KEY,
    password: process.env.SHOPIFY_API_PASSWORD
  },
  themeId: parseInt(process.env.SHOPIFY_THEME_ID)
});

const themeAPI = new ThemeAPI(shopify, themeManager, './my-theme');
```

## Analyzing Theme Structure

### 1. Get Theme Metadata

Let's start by examining the theme's overall structure:

```typescript
async function analyzeThemeStructure() {
  const metadata = await themeAPI.getMetadata();
  
  console.log('Theme Structure:');
  console.log('----------------');
  console.log(`Sections: ${metadata.sections.length}`);
  console.log(`Templates: ${Object.keys(metadata.templates).length}`);
  console.log(`Assets: ${metadata.assets.length}`);
  
  // Analyze template types
  const templateTypes = new Set(
    Object.values(metadata.templates).map(t => t.type)
  );
  console.log('\nTemplate Types:', Array.from(templateTypes));
}
```

### 2. Analyze Page Types

Examine the different types of pages in your theme:

```typescript
async function analyzePageTypes() {
  const pages = await themeAPI.getPages();
  
  // Group pages by type
  const pagesByType = pages.reduce((acc, page) => {
    acc[page.type] = acc[page.type] || [];
    acc[page.type].push(page.path);
    return acc;
  }, {});
  
  console.log('Page Types:');
  console.log('-----------');
  for (const [type, paths] of Object.entries(pagesByType)) {
    console.log(`${type}: ${paths.length} pages`);
    console.log('Examples:', paths.slice(0, 3));
  }
}
```

## Dependency Analysis

### 1. Build Dependency Graph

Create a visual representation of theme dependencies:

```typescript
async function buildDependencyGraph() {
  const graph = await themeAPI.buildDependencyGraph();
  
  console.log('Template Dependencies:');
  console.log('--------------------');
  for (const [template, deps] of Object.entries(graph)) {
    console.log(`\n${template}:`);
    console.log('  Sections:', deps.sections);
    console.log('  Snippets:', deps.snippets);
    console.log('  Assets:', deps.assets);
  }
}
```

### 2. Find Unused Components

Identify unused sections and snippets:

```typescript
async function findUnusedComponents() {
  const unused = await themeAPI.findUnusedSections();
  
  console.log('Unused Components:');
  console.log('-----------------');
  console.log('Sections:', unused.sections);
  console.log('Snippets:', unused.snippets);
  
  // Suggest cleanup
  if (unused.sections.length > 0 || unused.snippets.length > 0) {
    console.log('\nCleanup Suggestions:');
    console.log('1. Review unused components for potential reuse');
    console.log('2. Remove confirmed unused components');
    console.log('3. Update theme documentation');
  }
}
```

## Performance Analysis

### 1. Analyze Asset Usage

Track how assets are used across templates:

```typescript
async function analyzeAssetUsage() {
  const metadata = await themeAPI.getMetadata();
  const assetUsage = {};
  
  // Track asset usage across templates
  for (const [template, data] of Object.entries(metadata.templates)) {
    for (const asset of data.assets || []) {
      assetUsage[asset] = assetUsage[asset] || [];
      assetUsage[asset].push(template);
    }
  }
  
  console.log('Asset Usage:');
  console.log('------------');
  for (const [asset, templates] of Object.entries(assetUsage)) {
    console.log(`${asset}: Used in ${templates.length} templates`);
    console.log('  Templates:', templates);
  }
}
```

### 2. Check Template Complexity

Analyze template complexity and suggest optimizations:

```typescript
async function analyzeTemplateComplexity() {
  const templates = await themeAPI.getTemplates();
  
  for (const template of templates) {
    const analysis = await themeAPI.analyzeTemplate(template, {
      includeSections: true,
      includeSnippets: true,
      includeAssets: true
    });
    
    console.log(`\nTemplate: ${template}`);
    console.log('----------------');
    console.log(`Sections: ${analysis.sections.length}`);
    console.log(`Snippets: ${analysis.snippets.length}`);
    console.log(`Assets: ${analysis.assets.length}`);
    
    // Check for potential issues
    if (analysis.sections.length > 10) {
      console.log('Warning: High number of sections may impact performance');
    }
    if (analysis.snippets.length > 15) {
      console.log('Warning: Consider consolidating snippets');
    }
  }
}
```

## Generating Reports

### 1. Theme Health Report

Create a comprehensive theme health report:

```typescript
async function generateHealthReport() {
  const report = await themeAPI.generateThemeReport();
  
  console.log('Theme Health Report');
  console.log('==================');
  
  // Structure
  console.log('\nStructure:');
  console.log(`Total Templates: ${report.templateCount}`);
  console.log(`Total Sections: ${report.sectionCount}`);
  console.log(`Total Snippets: ${report.snippetCount}`);
  
  // Performance
  console.log('\nPerformance Metrics:');
  console.log(`Average Template Size: ${report.averageTemplateSize}KB`);
  console.log(`Total Asset Size: ${report.totalAssetSize}MB`);
  
  // Issues
  if (report.issues.length > 0) {
    console.log('\nPotential Issues:');
    report.issues.forEach(issue => {
      console.log(`- ${issue.description} (${issue.severity})`);
    });
  }
}
```

### 2. Dependency Report

Generate a detailed dependency report:

```typescript
async function generateDependencyReport() {
  const graph = await themeAPI.buildDependencyGraph();
  
  // Find circular dependencies
  const circular = findCircularDependencies(graph);
  
  // Find shared dependencies
  const shared = findSharedDependencies(graph);
  
  console.log('Dependency Report');
  console.log('================');
  
  if (circular.length > 0) {
    console.log('\nCircular Dependencies:');
    circular.forEach(cycle => {
      console.log(`- ${cycle.join(' -> ')}`);
    });
  }
  
  console.log('\nMost Shared Components:');
  Object.entries(shared)
    .sort((a, b) => b[1].length - a[1].length)
    .slice(0, 5)
    .forEach(([component, templates]) => {
      console.log(`${component}: Used in ${templates.length} templates`);
    });
}
```

## Best Practices

### 1. Regular Analysis

Schedule regular theme analysis:

```typescript
async function scheduleAnalysis() {
  // Run daily analysis
  const schedule = require('node-schedule');
  
  schedule.scheduleJob('0 0 * * *', async () => {
    console.log('Running daily theme analysis...');
    
    await analyzeThemeStructure();
    await findUnusedComponents();
    await analyzeTemplateComplexity();
    
    // Generate reports
    await generateHealthReport();
    await generateDependencyReport();
  });
}
```

### 2. Monitoring Changes

Track changes over time:

```typescript
async function monitorThemeChanges() {
  // Watch for file changes
  themeAPI.watchTheme(async (event, path) => {
    console.log(`File changed: ${path}`);
    
    // Analyze impact
    const impact = await analyzeChangeImpact(path);
    
    if (impact.affectedTemplates.length > 0) {
      console.log('Affected templates:', impact.affectedTemplates);
      console.log('Suggestion:', impact.suggestion);
    }
  });
}
```

## Next Steps

1. Set up automated analysis in your CI/CD pipeline
2. Create custom reports for your specific needs
3. Implement monitoring for key metrics
4. Schedule regular theme audits

For more information, check out:
- [API Reference](../api/README.md)
- [Best Practices](../development/best-practices.md)
- [Performance Guide](../development/performance.md)