or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

index.mddocs/

Grunt Plato

Grunt Plato is a Grunt plugin that generates static analysis reports using the plato library. It provides comprehensive code complexity analysis and visualization for JavaScript projects by integrating with JSHint for code quality checks and complexity-report for cyclomatic complexity metrics.

Package Information

  • Package Name: grunt-plato
  • Package Type: npm (Grunt plugin)
  • Language: JavaScript
  • Installation: npm install grunt-plato --save-dev

Core Imports

As a Grunt plugin, grunt-plato is loaded and used within a Gruntfile:

grunt.loadNpmTasks('grunt-plato');

Basic Usage

module.exports = function(grunt) {
  grunt.initConfig({
    plato: {
      your_target: {
        files: {
          'output/directory': ['src/**/*.js', 'test/**/*.js']
        }
      }
    }
  });

  grunt.loadNpmTasks('grunt-plato');
  grunt.registerTask('analyze', ['plato']);
};

Architecture

Grunt Plato is a wrapper around the plato library that integrates static analysis capabilities into the Grunt build system. The plugin:

  • Grunt Integration: Registers as a multi-task that fits into standard Grunt workflows
  • Plato Wrapper: Delegates analysis to the plato library while providing Grunt-style configuration
  • Options Processing: Normalizes and processes configuration options before passing to plato
  • File Handling: Uses Grunt's file system abstraction for source file discovery and output management

The plugin serves as a bridge between Grunt's task-based build system and plato's code analysis engine, allowing developers to integrate complexity analysis into their automated build processes.

Capabilities

Plato Task Registration

The plugin registers a multi-task named 'plato' that generates static analysis charts.

grunt.registerMultiTask('plato', 'Generate static analysis charts with plato', function() {
  // Task implementation
});

Configuration Options

Configuration options that can be passed to the plato task.

interface PlatoOptions {
  /** JSHint configuration options for code linting */
  jshint?: JSHintOptions | false;
  /** Path to .jshintrc file for JSHint configuration */
  jshintrc?: string;
  /** Path to .eslintrc file for ESLint configuration */
  eslintrc?: string;
  /** Complexity analysis options passed to complexity-report */
  complexity?: ComplexityOptions;
  /** Regular expression to exclude files from analysis */
  exclude?: RegExp;
  /** Path to file containing list of files to exclude */
  excludeFromFile?: string;
}

interface JSHintOptions {
  options?: any;
  globals?: { [key: string]: boolean };
}

interface ComplexityOptions {
  /** Use new maintainability index calculation */
  newmi?: boolean;
  /** Include logical OR operators in complexity calculation */
  logicalor?: boolean;
  /** Include switch case statements in complexity calculation */
  switchcase?: boolean;
  /** Include for-in loops in complexity calculation */
  forin?: boolean;
  /** Include try-catch blocks in complexity calculation */
  trycatch?: boolean;
}

// Default options applied by the plugin
interface DefaultPlatoOptions {
  jshint: {};
  jshintrc: '';
  complexity: {
    newmi: true;
  };
}

Usage Examples:

// Basic configuration
grunt.initConfig({
  plato: {
    analysis: {
      files: {
        'reports': ['src/**/*.js']
      }
    }
  }
});

// With custom options
grunt.initConfig({
  plato: {
    analysis: {
      options: {
        jshint: {
          options: {
            strict: true,
            unused: true
          },
          globals: {
            jQuery: false,
            console: false
          }
        },
        complexity: {
          logicalor: false,
          switchcase: false,
          forin: true,
          trycatch: true
        },
        exclude: /\.min\.js$/
      },
      files: {
        'reports': ['src/**/*.js']
      }
    }
  }
});

// Using external configuration files
grunt.initConfig({
  plato: {
    analysis: {
      options: {
        jshintrc: '.jshintrc',
        eslintrc: '.eslintrc',
        excludeFromFile: '.platoignore'
      },
      files: {
        'reports': ['src/**/*.js']
      }
    }
  }
});

// Disabling JSHint
grunt.initConfig({
  plato: {
    analysis: {
      options: {
        jshint: false
      },
      files: {
        'reports': ['src/**/*.js']
      }
    }
  }
});

// JSHint options normalization example
// Input: { jshint: { strict: true, globals: { jQuery: false } } }
// Normalized to: { jshint: { options: { strict: true }, globals: { jQuery: false } } }
grunt.initConfig({
  plato: {
    analysis: {
      options: {
        jshint: {
          strict: true,
          unused: true,
          globals: {
            jQuery: false,
            console: false
          }
        }
      },
      files: {
        'reports': ['src/**/*.js']
      }
    }
  }
});

Task Execution Flow

The plato task follows this execution pattern:

  1. Options Processing:

    • Merges default options { jshint: {}, jshintrc: '', complexity: { newmi: true } } with user-provided options
    • Processes external configuration files (jshintrc, eslintrc) by reading and parsing JSON
    • Normalizes JSHint options structure: if JSHint options don't contain an options property, wraps them in { options: userOptions, globals: userGlobals || {} }
    • Removes globals from the options object to prevent duplication

  2. Exclusion Processing:

    • If excludeFromFile is specified, reads the file line by line
    • Converts each line to a regex pattern by escaping special characters (/, ., *)
    • Combines all patterns into a single RegExp for filtering

  3. Plato Inspection: Calls plato.inspect() with processed options using source files from this.filesSrc and destination directory from this.files[0].dest

File Configuration

The task uses standard Grunt file configuration:

interface FileConfiguration {
  files: {
    [destinationDirectory: string]: string[] | string;
  };
}

Examples:

// Single destination with multiple sources
plato: {
  analysis: {
    files: {
      'reports/complexity': ['src/**/*.js', 'lib/**/*.js']
    }
  }
}

// Multiple targets
plato: {
  src_analysis: {
    files: {
      'reports/src': ['src/**/*.js']
    }
  },
  test_analysis: {
    files: {
      'reports/test': ['test/**/*.js']
    }
  }
}

Output Structure

The plato task generates the following output structure in the destination directory:

  • index.html - Main report page with overview and navigation
  • report.js - JavaScript data for interactive features
  • report.json - Raw analysis data in JSON format
  • files/ - Directory containing detailed reports for individual files
  • assets/ - Static assets (CSS, JavaScript, images) for report styling

Each analyzed file gets a corresponding report in the files/ directory with complexity metrics, maintainability index, and code quality analysis.