0
# Configuration Management
1

2
Advanced configuration system supporting multiple sources, validation, and flexible option processing for both CLI and programmatic usage.
3

4
## Capabilities
5

6
### Options Processing from CLI
7

8
Converts Commander.js CLI instance to validated IOptions configuration object.
9

10
```typescript { .api }
11
/**
12
 * Converts CLI arguments to IOptions configuration with validation
13
 * @param cli - Commander.js instance with parsed CLI arguments
14
 * @returns Fully processed and validated options object
15
 */
16
function initOptionsFromCli(cli: Command): IOptions;
17
```
18

19
**Usage Example:**
20

21
```typescript
22
import { initCli, initOptionsFromCli } from "jscpd";
23
import { readJSONSync } from "fs-extra";
24

25
const packageJson = readJSONSync("./package.json");
26
const cli = initCli(packageJson, process.argv);
27
const options = initOptionsFromCli(cli);
28

29
console.log("Processed options:", options);
30
console.log("Supported formats:", options.format);
31
console.log("Final paths:", options.path);
32
```
33

34
### Options Preparation and Merging
35

36
Merges options from multiple sources (CLI, config files, package.json) with proper priority handling.
37

38
```typescript { .api }
39
/**
40
 * Merges CLI, config file, and package.json options with proper precedence
41
 * @param cli - Commander.js instance with CLI arguments
42
 * @returns Final merged options with all sources combined
43
 */
44
function prepareOptions(cli: Command): IOptions;
45
```
46

47
**Usage Example:**
48

49
```typescript
50
import { initCli, prepareOptions } from "jscpd";
51

52
const cli = initCli(packageJson, [
53
  "node", "jscpd", "./src",
54
  "--config", "./custom-config.json",
55
  "--min-lines", "3"
56
]);
57

58
const options = prepareOptions(cli);
59
// Result combines: default options + package.json config + config file + CLI args
60
```
61

62
### Ignore Pattern Processing
63

64
Processes ignore patterns including .gitignore integration.
65

66
```typescript { .api }
67
/**
68
 * Processes ignore patterns including .gitignore file integration
69
 * @param options - Options object containing ignore and gitignore settings
70
 * @returns Array of processed ignore patterns
71
 */
72
function initIgnore(options: IOptions): string[];
73
```
74

75
**Usage Example:**
76

77
```typescript
78
import { initIgnore } from "jscpd";
79

80
const options = {
81
  ignore: ["**/*.test.js", "**/dist/**"],
82
  gitignore: true
83
};
84

85
const ignorePatterns = initIgnore(options);
86
console.log("Final ignore patterns:", ignorePatterns);
87
// Includes both explicit ignore patterns and .gitignore patterns
88
```
89

90
### Print and Debug Functions
91

92
Utility functions for displaying configuration and file information during debugging.
93

94
```typescript { .api }
95
/**
96
 * Prints the complete options configuration to console
97
 * @param options - Options object to display
98
 */
99
function printOptions(options: IOptions): void;
100

101
/**
102
 * Prints list of files that will be analyzed
103
 * @param files - Array of file entries with content
104
 */
105
function printFiles(files: EntryWithContent[]): void;
106

107
// External types from @jscpd/finder
108
interface EntryWithContent {
109
  path: string;
110
  // Additional properties from finder package
111
}
112

113
/**
114
 * Prints supported file formats and exits
115
 */
116
function printSupportedFormat(): void;
117
```
118

119
**Usage Examples:**
120

121
```typescript
122
import { printOptions, printFiles, printSupportedFormat } from "jscpd";
123
import { getFilesToDetect } from "@jscpd/finder";
124

125
// Debug current configuration
126
printOptions(options);
127

128
// Show files that will be analyzed
129
const files = getFilesToDetect(options);
130
printFiles(files);
131

132
// List all supported formats
133
printSupportedFormat();
134
```
135

136
## Configuration Sources and Priority
137

138
Configuration options are merged from multiple sources with the following priority (highest to lowest):
139

140
### 1. CLI Arguments (Highest Priority)
141

142
Direct command-line arguments override all other sources:
143

144
```bash
145
jscpd ./src --min-lines 5 --reporters console,html
146
```
147

148
### 2. Config File
149

150
Specified via `--config` option or default `.jscpd.json`:
151

152
```json
153
{
154
  "minLines": 3,
155
  "minTokens": 40,  
156
  "threshold": 8,
157
  "reporters": ["console", "json"],
158
  "ignore": ["**/*.test.js"],
159
  "output": "./reports",
160
  "gitignore": true
161
}
162
```
163

164
### 3. Package.json Configuration
165

166
Configuration in the `jscpd` property of package.json:
167

168
```json
169
{
170
  "name": "my-project",
171
  "jscpd": {
172
    "minLines": 4,
173
    "reporters": ["html"],
174
    "threshold": 10
175
  }
176
}
177
```
178

179
### 4. Default Values (Lowest Priority)
180

181
Built-in defaults from `@jscpd/core`:
182

183
```typescript
184
// Example default values
185
{
186
  minLines: 5,
187
  minTokens: 50,
188
  maxLines: 1000,
189
  mode: "mild",
190
  reporters: ["time", "console"],
191
  output: "./report/",
192
  pattern: "**/*"
193
}
194
```
195

196
## Configuration File Formats
197

198
### Standard .jscpd.json Format
199

200
```json
201
{
202
  "minLines": 5,
203
  "minTokens": 50,
204
  "maxLines": 1000,
205
  "maxSize": "1mb",
206
  "threshold": 10,
207
  "mode": "strict",
208
  "format": [
209
    "javascript",
210
    "typescript",
211
    "python"
212
  ],
213
  "ignore": [
214
    "**/*.test.js",
215
    "**/*.spec.ts", 
216
    "**/node_modules/**",
217
    "**/dist/**"
218
  ],
219
  "ignorePattern": [
220
    "DEBUG",
221
    "TODO",
222
    "FIXME"
223
  ],
224
  "reporters": [
225
    "console",
226
    "html",
227
    "json"
228
  ],
229
  "output": "./reports/jscpd",
230
  "absolute": true,
231
  "gitignore": true,
232
  "blame": true,
233
  "verbose": false,
234
  "silent": false,
235
  "noSymlinks": true,
236
  "skipLocal": false,
237
  "ignoreCase": false,
238
  "cache": true,
239
  "store": "memory",
240
  "formatsExts": {
241
    "javascript": ["js", "jsx", "es6"],
242
    "typescript": ["ts", "tsx"]
243
  }
244
}
245
```
246

247
### Package.json Integration
248

249
```json
250
{
251
  "name": "my-project",
252
  "version": "1.0.0",
253
  "scripts": {
254
    "jscpd": "jscpd",
255
    "jscpd:check": "jscpd --threshold 5"
256
  },
257
  "jscpd": {
258
    "minLines": 3,
259
    "threshold": 5,
260
    "reporters": ["console", "badge"],
261
    "ignore": [
262
      "**/*.test.js"
263
    ],
264
    "path": [
265
      "./src",
266
      "./lib"
267
    ]
268
  }
269
}
270
```
271

272
## Configuration Validation and Processing
273

274
### Path Resolution
275

276
Paths in configuration files are resolved relative to the config file location:
277

278
```json
279
{
280
  "path": ["./src", "../shared"],
281
  "ignore": ["./tests/**"]
282
}
283
```
284

285
### Array Option Processing
286

287
Comma-separated CLI values are automatically split into arrays:
288

289
```bash
290
# CLI input
291
jscpd --format "javascript,typescript,python" --ignore "**/*.test.js,**/dist/**"
292

293
# Processed as
294
{
295
  "format": ["javascript", "typescript", "python"],
296
  "ignore": ["**/*.test.js", "**/dist/**"]
297
}
298
```
299

300
### Type Conversion
301

302
Numeric and boolean options are automatically converted:
303

304
```bash
305
# CLI input
306
jscpd --min-lines "5" --threshold "10" --gitignore
307

308
# Processed as  
309
{
310
  "minLines": 5,
311
  "threshold": 10,
312
  "gitignore": true
313
}
314
```
315

316
### Reporter Configuration
317

318
Reporters are automatically configured based on options:
319

320
```typescript
321
// Silent mode filters out console reporters
322
{
323
  "silent": true,
324
  "reporters": ["console", "html"] // Becomes ["silent", "html"]
325
}
326

327
// Threshold automatically adds threshold reporter
328
{
329
  "threshold": 10,
330
  "reporters": ["console"] // Becomes ["console", "threshold"]
331
}
332
```
333

334
## Environment-Specific Configuration
335

336
### Development Configuration
337

338
```json
339
{
340
  "minLines": 3,
341
  "verbose": true,
342
  "reporters": ["console"],
343
  "format": ["javascript", "typescript"]
344
}
345
```
346

347
### CI/CD Configuration
348

349
```json
350
{
351
  "threshold": 5,
352
  "silent": true,
353
  "reporters": ["json", "threshold"],
354
  "output": "./reports",
355
  "exitCode": 1
356
}
357
```
358

359
### Pre-commit Hook Configuration
360

361
```json
362
{
363
  "minLines": 5,
364
  "threshold": 0,
365
  "reporters": ["console"],
366
  "gitignore": true,
367
  "skipLocal": true
368
}
369
```
370

371
## Configuration Debugging
372

373
Use the debug option to inspect final configuration:
374

375
```bash
376
jscpd --debug ./src
377
```
378

379
This will output:
380
- Final merged configuration
381
- List of files that will be analyzed
382
- Skip the actual detection process
383

384
```typescript
385
// Programmatic debugging
386
import { printOptions, printFiles } from "jscpd";
387
import { getFilesToDetect } from "@jscpd/finder";
388

389
const options = prepareOptions(cli);
390
printOptions(options);
391

392
const files = getFilesToDetect(options);
393
printFiles(files);
394
```