0
# Plato
1

2
Plato is a JavaScript source analysis and visualizer that generates detailed complexity reports for JavaScript projects. It analyzes JavaScript files to calculate cyclomatic complexity, Halstead metrics, maintainability indices, and other code quality measurements, then produces interactive HTML reports with visualizations including charts and graphs.
3

4
## Package Information
5

6
- **Package Name**: plato
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install plato`
10

11
## Core Imports
12

13
```javascript
14
const plato = require('plato');
15
```
16

17
For individual functions:
18

19
```javascript
20
const { inspect, getOverviewReport } = require('plato');
21
```
22

23
## Basic Usage
24

25
```javascript
26
const plato = require('plato');
27

28
// Analyze JavaScript files and generate HTML reports
29
plato.inspect(['src/**/*.js'], 'reports', {
30
  title: 'My Project Analysis',
31
  recurse: true,
32
  jshint: {
33
    node: true,
34
    browser: true
35
  }
36
}, function(reports) {
37
  console.log('Analysis complete!');
38
  console.log(`Analyzed ${reports.length} files`);
39
  
40
  // Generate overview report
41
  const overview = plato.getOverviewReport(reports);
42
  console.log('Overall maintainability:', overview.summary.average.maintainability);
43
});
44
```
45

46
## Architecture
47

48
Plato is built around several key components:
49

50
- **Core Analysis Engine**: Main `inspect()` function orchestrates file analysis and report generation
51
- **Reporters**: Pluggable analysis modules for complexity, JSHint, and ESLint integration
52
- **History Tracking**: Models for tracking code quality metrics over time
53
- **CLI Interface**: Command-line tool for CI/CD integration and batch processing
54
- **Utility Functions**: Common operations for file handling, JSON processing, and output formatting
55

56
## Capabilities
57

58
### Programmatic Analysis API
59

60
Core analysis functions for integrating Plato into custom workflows and applications.
61

62
```javascript { .api }
63
function inspect(files, outputDir, options, done);
64
function getOverviewReport(reports);
65
```
66

67
[Programmatic API](./programmatic-api.md)
68

69
### Command Line Interface
70

71
Complete CLI for batch analysis, CI/CD integration, and automated reporting workflows.
72

73
```javascript { .api }
74
function exec(options, done);
75
```
76

77
[CLI API](./cli-api.md)
78

79
### Utility Functions
80

81
Helper functions for file operations, JSON processing, and output formatting.
82

83
```javascript { .api }
84
function findCommonBase(files);
85
function formatJSON(report);
86
function readJSON(file, options);
87
function stripComments(str);
88
function escapeHTML(html);
89
```
90

91
[Utilities](./utilities.md)
92

93
### History and Models
94

95
Data models for tracking code quality metrics over time and maintaining historical analysis data.
96

97
```javascript { .api }
98
class History
99
class OverviewHistory extends History
100
class FileHistory extends History
101
```
102

103
[Models](./models.md)
104

105
### Analysis Reporters
106

107
Specialized analysis modules for different code quality metrics and linting integration.
108

109
```javascript { .api }
110
// Complexity Reporter
111
function process(source, options, reportInfo);
112

113
// JSHint Reporter  
114
function process(source, options);
115

116
// ESLint Reporter
117
function process(source, options);
118
```
119

120
[Reporters](./reporters.md)
121

122
## Configuration Options
123

124
### Analysis Options
125

126
```javascript { .api }
127
interface AnalysisOptions {
128
  /** Recursively search directories */
129
  recurse?: boolean;
130
  /** Quiet mode (errors only) */
131
  q?: boolean;
132
  /** Report title */
133
  title?: string;
134
  /** File exclusion regex */
135
  exclude?: RegExp;
136
  /** Custom report date */
137
  date?: Date;
138
  /** JSHint configuration */
139
  jshint?: Object;
140
  /** ESLint configuration */
141
  eslint?: Object;
142
  /** Skip empty lines from line count */
143
  noempty?: boolean;
144
}
145
```
146

147
### Logger Configuration
148

149
```javascript { .api }
150
class Logger {
151
  constructor(level: number);
152
  
153
  static TRACE: 0;
154
  static DEBUG: 1;
155
  static INFO: 2;
156
  static WARNING: 3;
157
  static ERROR: 4;
158
  
159
  trace(...args: any[]): void;
160
  debug(...args: any[]): void;
161
  info(...args: any[]): void;
162
  warning(...args: any[]): void;
163
  error(...args: any[]): void;
164
}
165
```