0
# Programmatic Analysis API
1

2
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.
3

4
## Capabilities
5

6
### Main Analysis Function
7

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

10
```javascript { .api }
11
/**
12
 * Analyze JavaScript files and generate complexity reports
13
 * @param {Array|String} files - File paths or glob patterns to analyze
14
 * @param {String} outputDir - Directory to write HTML reports (optional)
15
 * @param {Object} options - Analysis configuration options (optional)
16
 * @param {Function} done - Callback function receiving reports array
17
 */
18
function inspect(files, outputDir, options, done);
19
```
20

21
**Parameters:**
22

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

28
**Options Object:**
29

30
```javascript { .api }
31
interface AnalysisOptions {
32
  /** Recursively search directories */
33
  recurse?: boolean;
34
  /** Quiet mode - reduce output to errors only */
35
  q?: boolean;
36
  /** Custom title for generated reports */
37
  title?: string;
38
  /** Regular expression for excluding files */
39
  exclude?: RegExp;
40
  /** Custom date for report timestamp */
41
  date?: Date;
42
  /** JSHint configuration object */
43
  jshint?: Object;
44
  /** ESLint configuration object */
45
  eslint?: Object;
46
  /** Skip empty lines from line count calculations */
47
  noempty?: boolean;
48
}
49
```
50

51
**Usage Examples:**
52

53
```javascript
54
const plato = require('plato');
55

56
// Basic analysis with callback
57
plato.inspect(['src/**/*.js'], 'reports', {
58
  title: 'Project Analysis',
59
  recurse: true
60
}, function(reports) {
61
  console.log(`Analyzed ${reports.length} files`);
62
  reports.forEach(report => {
63
    console.log(`${report.info.file}: ${report.complexity.cyclomatic} complexity`);
64
  });
65
});
66

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

76
// Analysis with custom exclusions
77
plato.inspect(['**/*.js'], 'reports', {
78
  exclude: /node_modules|test/,
79
  eslint: {
80
    env: { browser: true, es6: true }
81
  }
82
}, function(reports) {
83
  console.log('Analysis complete');
84
});
85
```
86

87
### Overview Report Generation
88

89
Generates a summary overview from individual file analysis reports.
90

91
```javascript { .api }
92
/**
93
 * Generate overview summary from individual file reports
94
 * @param {Array} reports - Array of individual file analysis reports
95
 * @returns {Object} Overview report with summary and reports properties
96
 */
97
function getOverviewReport(reports);
98
```
99

100
**Parameters:**
101

102
- `reports` (Array): Array of individual file analysis reports from `inspect()`
103

104
**Returns:**
105

106
```javascript { .api }
107
interface OverviewReport {
108
  /** Summary statistics across all analyzed files */
109
  summary: {
110
    total: {
111
      sloc: number;
112
      maintainability: number;
113
      // ... other aggregated metrics
114
    };
115
    average: {
116
      sloc: number;
117
      maintainability: number;
118
      // ... other averaged metrics
119
    };
120
  };
121
  /** Original reports array */
122
  reports: Array;
123
}
124
```
125

126
**Usage Examples:**
127

128
```javascript
129
const plato = require('plato');
130

131
plato.inspect(['src/**/*.js'], null, {}, function(reports) {
132
  // Generate overview summary
133
  const overview = plato.getOverviewReport(reports);
134
  
135
  console.log('Project Overview:');
136
  console.log(`Total SLOC: ${overview.summary.total.sloc}`);
137
  console.log(`Average Maintainability: ${overview.summary.average.maintainability}`);
138
  console.log(`Total Files: ${overview.reports.length}`);
139
  
140
  // Find files with low maintainability
141
  const problematicFiles = overview.reports.filter(
142
    report => report.complexity.maintainability < 70
143
  );
144
  
145
  console.log(`Files needing attention: ${problematicFiles.length}`);
146
});
147
```
148

149
## Report Structure
150

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

153
```javascript { .api }
154
interface FileReport {
155
  /** File information */
156
  info: {
157
    file: string;        // File path
158
    fileShort: string;   // Short file name
159
    fileSafe: string;    // URL-safe file name
160
    link: string;        // Report link
161
  };
162
  
163
  /** Complexity metrics */
164
  complexity: {
165
    cyclomatic: number;           // Cyclomatic complexity
166
    sloc: {
167
      physical: number;           // Physical lines of code
168
      logical: number;            // Logical lines of code
169
    };
170
    halstead: {
171
      operators: {
172
        distinct: number;
173
        total: number;
174
        identifiers: string[];
175
      };
176
      operands: {
177
        distinct: number;
178
        total: number;
179
        identifiers: string[];
180
      };
181
      length: number;
182
      vocabulary: number;
183
      difficulty: number;
184
      volume: number;
185
      effort: number;
186
      bugs: number;
187
      time: number;
188
    };
189
    maintainability: number;      // Maintainability index
190
    params: number;               // Function parameters
191
    // ... other complexity metrics
192
  };
193
  
194
  /** JSHint results (if enabled) */
195
  jshint?: {
196
    messages: Array<{
197
      severity: string;
198
      line: number;
199
      column: number;
200
      message: string;
201
      evidence: string;
202
    }>;
203
  };
204
  
205
  /** ESLint results (if enabled) */
206
  eslint?: {
207
    messages: Array<{
208
      severity: string;
209
      line: number;
210
      column: number;
211
      message: string;
212
      // ... other ESLint properties
213
    }>;
214
  };
215
}
216
```
217

218
## Error Handling
219

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

222
```javascript
223
plato.inspect(['nonexistent/*.js'], 'reports', {}, function(err, reports) {
224
  if (err) {
225
    console.error('Analysis failed:', err.message);
226
    return;
227
  }
228
  
229
  console.log('Analysis completed successfully');
230
});
231
```
232

233
Common error scenarios:
234
- Invalid file paths or glob patterns
235
- Insufficient permissions for output directory
236
- Malformed configuration options
237
- JavaScript parsing errors in analyzed files