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

Command Line Interface API

Name: tessl/npm-plato
Author: tessl

Complete CLI for batch analysis, CI/CD integration, and automated reporting workflows. The CLI provides programmatic access to command-line functionality and configuration.

Capabilities

CLI Execution Function

Execute CLI analysis with programmatic override options.

/**
 * Execute CLI analysis with programmatic override options
 * @param {Object} options - Override CLI options (optional)
 * @param {Function} done - Completion callback (optional)
 */
function exec(options, done);

Parameters:

options (Object, optional): Override CLI options
done (Function, optional): Completion callback

Usage Examples:

const cli = require('plato/lib/cli');

// Execute with default CLI options
cli.exec();

// Execute with custom options
cli.exec({
  title: 'Custom Analysis',
  recurse: true,
  quiet: false
}, function() {
  console.log('CLI analysis completed');
});

// Access parsed CLI arguments
console.log('CLI args:', cli.args);
console.log('CLI options:', cli.options);

CLI Configuration Access

Access to CLI options configuration and parsed command-line arguments.

/** CLI options configuration object */
const options: Object;

/** Parsed command-line arguments object */
const args: Object;

Properties:

options (Object): CLI options configuration object
args (Object): Parsed command-line arguments object

Command Line Options

The CLI supports the following command-line options:

Help and Version

plato -h, --help        # Display help text
plato -v, --version     # Print version information

Analysis Configuration

plato -d, --dir <String>          # Output directory for reports (required)
plato -t, --title <String>        # Custom report title
plato -r, --recurse               # Recursively search directories
plato -q, --quiet                 # Reduce output to errors only
plato -n, --noempty               # Skip empty lines from line count

File Filtering

plato -x, --exclude <String>      # File exclusion regex pattern

Linting Integration

plato -l, --jshint <String>       # JSHint configuration file path
plato -e, --eslint <String>       # ESLint configuration file path

Report Customization

plato -D, --date <String>         # Custom report date

CLI Usage Examples

Basic Analysis

# Analyze all JavaScript files in src directory
plato -r -d reports src

# Analyze specific files with custom title
plato -d reports -t "My Project Analysis" src/app.js src/utils.js

Advanced Configuration

# Exclude test files and node_modules
plato -r -d reports -x "test|spec|node_modules" src

# Use custom JSHint configuration
plato -r -d reports -l .jshintrc src

# Quiet mode for CI/CD
plato -r -d reports -q src

Integration Examples

# CI/CD pipeline usage
plato -r -d build/reports -q -t "Build $BUILD_NUMBER" src
if [ $? -eq 0 ]; then
  echo "Code analysis passed"
else
  echo "Code analysis failed"
  exit 1
fi

# Generate reports with timestamp
plato -r -d "reports-$(date +%Y%m%d)" -t "Daily Analysis" src

Programmatic CLI Options

When using the exec() function programmatically, you can override CLI options:

interface CLIOptions {
  /** Output directory path */
  dir?: string;
  /** Report title */
  title?: string;
  /** Recursively search directories */
  recurse?: boolean;
  /** Quiet mode */
  quiet?: boolean;
  /** Skip empty lines */
  noempty?: boolean;
  /** File exclusion regex */
  exclude?: string;
  /** JSHint config file path */
  jshint?: string;
  /** ESLint config file path */
  eslint?: string;
  /** Custom report date */
  date?: string;
  /** File paths to analyze */
  files?: string[];
}

Usage Examples:

const cli = require('plato/lib/cli');

// Override CLI options programmatically
cli.exec({
  dir: 'custom-reports',
  title: 'Automated Analysis',
  recurse: true,
  quiet: true,
  files: ['src/**/*.js']
}, function() {
  console.log('Analysis complete');
});

Binary Entry Point

The main executable is located at bin/plato and provides the command-line interface:

/** Main CLI executable that delegates to lib/cli.js */
// Handles version (-v) and help (-h) flags
// Calls cli.exec() for main functionality

Direct Execution:

# Using global installation
plato -r -d reports src

# Using npx
npx plato -r -d reports src

# Using local installation
./node_modules/.bin/plato -r -d reports src

Info Module Integration

The CLI integrates with the info module for version and help display:

/** Package name constant */
const name: string;

/** Print version to console */
function version(): void;

/** Print help text to console */
function help(): void;

Usage in CLI context:

plato --version    # Calls info.version()
plato --help       # Calls info.help()

Exit Codes

The CLI uses standard exit codes for automation and CI/CD integration:

0: Analysis completed successfully
1: Analysis failed due to errors
2: Invalid command-line arguments

CI/CD Integration:

# Bash script example
plato -r -d reports -q src
exit_code=$?

if [ $exit_code -eq 0 ]; then
  echo "✓ Code analysis passed"
  # Continue with deployment
else
  echo "✗ Code analysis failed (exit code: $exit_code)"
  exit $exit_code
fi

Install with Tessl CLI