tessl/npm-plato

JavaScript source analysis and visualizer that generates detailed complexity reports

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Programmatic Analysis API

Name: tessl/npm-plato
Author: tessl

Core analysis functions for integrating Plato into custom workflows and applications. The programmatic API provides the main functionality for analyzing JavaScript source code and generating complexity reports.

Capabilities

Main Analysis Function

Analyzes JavaScript files and generates comprehensive complexity reports with optional HTML output.

/**
 * Analyze JavaScript files and generate complexity reports
 * @param {Array|String} files - File paths or glob patterns to analyze
 * @param {String} outputDir - Directory to write HTML reports (optional)
 * @param {Object} options - Analysis configuration options (optional)
 * @param {Function} done - Callback function receiving reports array
 */
function inspect(files, outputDir, options, done);

Parameters:

files (Array|String): File paths or glob patterns to analyze
outputDir (String, optional): Directory to write HTML reports to
options (Object, optional): Analysis configuration options
done (Function): Callback function that receives the analysis reports array

Options Object:

interface AnalysisOptions {
  /** Recursively search directories */
  recurse?: boolean;
  /** Quiet mode - reduce output to errors only */
  q?: boolean;
  /** Custom title for generated reports */
  title?: string;
  /** Regular expression for excluding files */
  exclude?: RegExp;
  /** Custom date for report timestamp */
  date?: Date;
  /** JSHint configuration object */
  jshint?: Object;
  /** ESLint configuration object */
  eslint?: Object;
  /** Skip empty lines from line count calculations */
  noempty?: boolean;
}

Usage Examples:

const plato = require('plato');

// Basic analysis with callback
plato.inspect(['src/**/*.js'], 'reports', {
  title: 'Project Analysis',
  recurse: true
}, function(reports) {
  console.log(`Analyzed ${reports.length} files`);
  reports.forEach(report => {
    console.log(`${report.info.file}: ${report.complexity.cyclomatic} complexity`);
  });
});

// Analysis without HTML output
plato.inspect(['lib/*.js'], null, {
  jshint: { node: true }
}, function(reports) {
  // Process reports programmatically
  const complexFiles = reports.filter(r => r.complexity.cyclomatic > 10);
  console.log(`${complexFiles.length} files have high complexity`);
});

// Analysis with custom exclusions
plato.inspect(['**/*.js'], 'reports', {
  exclude: /node_modules|test/,
  eslint: {
    env: { browser: true, es6: true }
  }
}, function(reports) {
  console.log('Analysis complete');
});

Overview Report Generation

Generates a summary overview from individual file analysis reports.

/**
 * Generate overview summary from individual file reports
 * @param {Array} reports - Array of individual file analysis reports
 * @returns {Object} Overview report with summary and reports properties
 */
function getOverviewReport(reports);

Parameters:

reports (Array): Array of individual file analysis reports from inspect()

Returns:

interface OverviewReport {
  /** Summary statistics across all analyzed files */
  summary: {
    total: {
      sloc: number;
      maintainability: number;
      // ... other aggregated metrics
    };
    average: {
      sloc: number;
      maintainability: number;
      // ... other averaged metrics
    };
  };
  /** Original reports array */
  reports: Array;
}

Usage Examples:

const plato = require('plato');

plato.inspect(['src/**/*.js'], null, {}, function(reports) {
  // Generate overview summary
  const overview = plato.getOverviewReport(reports);
  
  console.log('Project Overview:');
  console.log(`Total SLOC: ${overview.summary.total.sloc}`);
  console.log(`Average Maintainability: ${overview.summary.average.maintainability}`);
  console.log(`Total Files: ${overview.reports.length}`);
  
  // Find files with low maintainability
  const problematicFiles = overview.reports.filter(
    report => report.complexity.maintainability < 70
  );
  
  console.log(`Files needing attention: ${problematicFiles.length}`);
});

Report Structure

Individual file reports returned by inspect() have the following structure:

interface FileReport {
  /** File information */
  info: {
    file: string;        // File path
    fileShort: string;   // Short file name
    fileSafe: string;    // URL-safe file name
    link: string;        // Report link
  };
  
  /** Complexity metrics */
  complexity: {
    cyclomatic: number;           // Cyclomatic complexity
    sloc: {
      physical: number;           // Physical lines of code
      logical: number;            // Logical lines of code
    };
    halstead: {
      operators: {
        distinct: number;
        total: number;
        identifiers: string[];
      };
      operands: {
        distinct: number;
        total: number;
        identifiers: string[];
      };
      length: number;
      vocabulary: number;
      difficulty: number;
      volume: number;
      effort: number;
      bugs: number;
      time: number;
    };
    maintainability: number;      // Maintainability index
    params: number;               // Function parameters
    // ... other complexity metrics
  };
  
  /** JSHint results (if enabled) */
  jshint?: {
    messages: Array<{
      severity: string;
      line: number;
      column: number;
      message: string;
      evidence: string;
    }>;
  };
  
  /** ESLint results (if enabled) */
  eslint?: {
    messages: Array<{
      severity: string;
      line: number;
      column: number;
      message: string;
      // ... other ESLint properties
    }>;
  };
}

Error Handling

The programmatic API uses Node.js callback conventions. Errors are passed as the first argument to callback functions:

plato.inspect(['nonexistent/*.js'], 'reports', {}, function(err, reports) {
  if (err) {
    console.error('Analysis failed:', err.message);
    return;
  }
  
  console.log('Analysis completed successfully');
});

Common error scenarios: