0
# Clone Detection API
1

2
Core programmatic API for detecting code duplications with extensive configuration options and type safety.
3

4
## Capabilities
5

6
### Primary Detection Function
7

8
Detects code clones in the specified paths with comprehensive configuration options.
9

10
```typescript { .api }
11
/**
12
 * Detects code clones in the provided paths using the specified options
13
 * @param opts - Configuration options for detection behavior
14
 * @param store - Optional custom store implementation for large codebases
15
 * @returns Promise resolving to array of detected clones
16
 */
17
function detectClones(
18
  opts: IOptions, 
19
  store?: IStore<IMapFrame>
20
): Promise<IClone[]>;
21
```
22

23
**Usage Examples:**
24

25
```typescript
26
import { detectClones } from "jscpd";
27

28
// Basic detection
29
const clones = await detectClones({
30
  path: ["./src"],
31
  minLines: 5,
32
  minTokens: 50
33
});
34

35
// Advanced detection with custom options
36
const clones = await detectClones({
37
  path: ["./src", "./lib"],
38
  minLines: 3,
39
  minTokens: 30,
40
  maxLines: 1000,
41
  format: ["javascript", "typescript"],
42
  ignore: ["**/*.test.js", "**/node_modules/**"],
43
  ignorePattern: ["DEBUG", "TODO"],
44
  reporters: ["console", "json"],
45
  output: "./reports",
46
  threshold: 10,
47
  mode: "strict",
48
  gitignore: true,
49
  blame: true
50
});
51

52
console.log(`Found ${clones.length} duplications`);
53
clones.forEach(clone => {
54
  console.log(`Format: ${clone.format}`);
55
  console.log(`Duplication A: ${clone.duplicationA.sourceId}:${clone.duplicationA.start.line}-${clone.duplicationA.end.line}`);
56
  console.log(`Duplication B: ${clone.duplicationB.sourceId}:${clone.duplicationB.start.line}-${clone.duplicationB.end.line}`);
57
});
58
```
59

60
### Configuration Options
61

62
Complete configuration interface for clone detection behavior.
63

64
```typescript { .api }
65
interface IOptions {
66
  /** Paths to analyze for duplications */
67
  path?: string[];
68
  
69
  /** Minimum lines for duplication detection (default varies by mode) */
70
  minLines?: number;
71
  
72
  /** Minimum tokens for duplication detection (default: 50) */
73
  minTokens?: number;
74
  
75
  /** Maximum source lines to analyze (default varies) */
76
  maxLines?: number;
77
  
78
  /** Maximum source size in bytes (examples: "1kb", "1mb", "120kb") */
79
  maxSize?: string;
80
  
81
  /** Duplication threshold for error exit */
82
  threshold?: number;
83
  
84
  /** Formats to analyze (default: all supported formats) */
85
  format?: string[];
86
  
87
  /** Glob pattern for file search (default: "**/*") */
88
  pattern?: string;
89
  
90
  /** Glob patterns for files to exclude */
91
  ignore?: string[];
92
  
93
  /** Regexp patterns for code blocks to ignore */
94
  ignorePattern?: string[];
95
  
96
  /** Reporter names to use (default: ["time", "console"]) */
97
  reporters?: string[];
98
  
99
  /** Output directory path (default: "./report/") */
100
  output?: string;
101
  
102
  /** Quality mode: "strict", "mild", or "weak" */
103
  mode?: string;
104
  
105
  /** Suppress console output */
106
  silent?: boolean;
107
  
108
  /** Show debug information */
109
  debug?: boolean;
110
  
111
  /** Show verbose output during detection */
112
  verbose?: boolean;
113
  
114
  /** Use absolute paths in reports */
115
  absolute?: boolean;
116
  
117
  /** Respect .gitignore file */
118
  gitignore?: boolean;
119
  
120
  /** Avoid following symlinks */
121
  noSymlinks?: boolean;
122
  
123
  /** Get git blame information for duplications */
124
  blame?: boolean;
125
  
126
  /** Skip duplicates in local folders */
127
  skipLocal?: boolean;
128
  
129
  /** Case-insensitive matching (experimental) */
130
  ignoreCase?: boolean;
131
  
132
  /** Enable caching */
133
  cache?: boolean;
134
  
135
  /** Custom store type (e.g., "leveldb") */
136
  store?: string;
137
  
138
  /** Execution identifier */
139
  executionId?: string;
140
  
141
  /** Custom format extensions mapping */
142
  formatsExts?: Record<string, string[]>;
143
  
144
  /** Custom exit code when duplications found */
145
  exitCode?: number;
146
  
147
  /** Path to configuration file */
148
  config?: string;
149
  
150
  /** Custom hash function for token hashing */
151
  hashFunction?: (value: string) => string;
152
  
153
  /** Event listeners array */
154
  listeners?: any[];
155
  
156
  /** Configuration options for specific reporters */
157
  reportersOptions?: Record<string, any>;
158
  
159
  /** Tokens to skip during analysis */
160
  tokensToSkip?: string[];
161
}
162
```
163

164
### Detection Results
165

166
Interface representing detected code clones.
167

168
```typescript { .api }
169
interface IClone {
170
  /** Programming language/format of the clone */
171
  format: string;
172
  
173
  /** Whether this is a newly detected clone */
174
  isNew?: boolean;
175
  
176
  /** Timestamp when clone was found */
177
  foundDate?: number;
178
  
179
  /** First instance of the duplication */
180
  duplicationA: IDuplication;
181
  
182
  /** Second instance of the duplication */
183
  duplicationB: IDuplication;
184
}
185

186
interface IDuplication {
187
  /** Source file identifier/path */
188
  sourceId: string;
189
  
190
  /** Starting location of the duplication */
191
  start: ITokenLocation;
192
  
193
  /** Ending location of the duplication */
194
  end: ITokenLocation;
195
  
196
  /** Token range [start, end] */
197
  range: [number, number];
198
  
199
  /** Source code fragment (optional) */
200
  fragment?: string;
201
  
202
  /** Git blame information (optional) */
203
  blame?: IBlamedLines;
204
}
205

206
interface ITokenLocation {
207
  /** Line number (1-based) */
208
  line: number;
209
  
210
  /** Column number (1-based, optional) */
211
  column?: number;
212
  
213
  /** Character position in file (optional) */
214
  position?: number;
215
}
216
```
217

218
### Custom Store Interface
219

220
Interface for implementing custom storage backends for large codebases.
221

222
```typescript { .api }
223
interface IStore<T> {
224
  /** Set namespace for key isolation */
225
  namespace(name: string): void;
226
  
227
  /** Store a value with the given key */
228
  set(key: string, value: T): Promise<T>;
229
  
230
  /** Retrieve a value by key */
231
  get(key: string): Promise<T>;
232
  
233
  /** Close/cleanup the store */
234
  close(): void;
235
}
236

237
interface IMapFrame {
238
  // Internal type used by the detection algorithm
239
  // Specific structure is implementation detail
240
}
241

242
interface IBlamedLines {
243
  // Git blame information for duplicated lines
244
  // From @jscpd/core package
245
}
246
```
247

248
### Error Handling
249

250
The `detectClones` function may throw errors in the following scenarios:
251

252
- **Invalid Configuration**: When required options are missing or invalid
253
- **File System Errors**: When specified paths don't exist or aren't accessible  
254
- **Format Errors**: When unsupported file formats are specified
255
- **Store Errors**: When custom store implementation fails
256
- **Memory Errors**: When processing very large codebases without appropriate store
257

258
```typescript
259
try {
260
  const clones = await detectClones(options);
261
} catch (error) {
262
  console.error("Detection failed:", error.message);
263
}
264
```