0
# JSCPD
1

2
JSCPD is a comprehensive copy/paste detector for programming source code that supports over 150 programming languages and document formats. It implements the Rabin-Karp algorithm for efficient duplication detection and provides both CLI and programmatic APIs for integration into development workflows.
3

4
## Package Information
5

6
- **Package Name**: jscpd
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install -g jscpd` (global) or `npm install jscpd` (local)
10

11
## Core Imports
12

13
```typescript
14
import { detectClones, jscpd } from "jscpd";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { detectClones, jscpd } = require("jscpd");
21
```
22

23
## Basic Usage
24

25
### CLI Usage
26

27
```bash
28
# Global installation
29
npm install -g jscpd
30
jscpd /path/to/source
31

32
# Or using npx
33
npx jscpd /path/to/source
34

35
# With pattern matching
36
jscpd --pattern "src/**/*.js"
37

38
# With configuration options
39
jscpd --min-lines 5 --min-tokens 50 --reporters console,html --output ./reports
40
```
41

42
### Programmatic Usage
43

44
```typescript
45
import { detectClones, jscpd } from "jscpd";
46

47
// Direct clone detection
48
const clones = await detectClones({
49
  path: ["./src"],
50
  minLines: 5,
51
  minTokens: 50,
52
  format: ["javascript", "typescript"],
53
  reporters: ["console"]
54
});
55

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

63
// CLI-style programmatic usage
64
const clones2 = await jscpd([
65
  "node", "jscpd", "./src", 
66
  "--min-lines", "5", 
67
  "--format", "javascript,typescript"
68
]);
69
```
70

71
## Architecture
72

73
JSCPD is built as a modular system with several key components:
74

75
- **Core Detection Engine**: Implements Rabin-Karp algorithm for efficient pattern matching
76
- **Tokenizer**: Language-specific tokenization supporting 150+ formats
77
- **File Finder**: Glob-based file discovery with ignore patterns
78
- **Reporter System**: Multiple output formats (console, HTML, JSON, SARIF, XML)
79
- **Configuration System**: CLI args, config files, and package.json integration
80
- **Store System**: Pluggable storage backends for large codebases
81

82
## Capabilities
83

84
### Programmatic Clone Detection
85

86
Core API for detecting code duplications programmatically. Ideal for CI/CD integration and custom tooling.
87

88
```typescript { .api }
89
function detectClones(
90
  opts: IOptions, 
91
  store?: IStore<IMapFrame>
92
): Promise<IClone[]>;
93

94
interface IOptions {
95
  path?: string[];
96
  minLines?: number;
97
  minTokens?: number;
98
  maxLines?: number;
99
  maxSize?: string;
100
  threshold?: number;
101
  format?: string[];
102
  pattern?: string;
103
  ignore?: string[];
104
  ignorePattern?: string[];
105
  reporters?: string[];
106
  output?: string;
107
  mode?: string;
108
  silent?: boolean;
109
  debug?: boolean;
110
  verbose?: boolean;
111
  // ... additional options
112
}
113

114
interface IClone {
115
  format: string;
116
  isNew?: boolean;
117
  foundDate?: number;
118
  duplicationA: IDuplication;
119
  duplicationB: IDuplication;
120
}
121
```
122

123
[Clone Detection API](./clone-detection.md)
124

125
### CLI Integration
126

127
Command-line interface with full argument processing and configuration file support.
128

129
```typescript { .api }
130
function jscpd(
131
  argv: string[], 
132
  exitCallback?: (code: number) => {}
133
): Promise<IClone[]>;
134
```
135

136
[CLI Integration](./cli-integration.md)
137

138
### Configuration Management
139

140
Advanced configuration system supporting multiple sources and validation.
141

142
```typescript { .api }
143
function initOptionsFromCli(cli: Command): IOptions;
144
function prepareOptions(cli: Command): IOptions;
145
```
146

147
[Configuration](./configuration.md)
148

149
## Types
150

151
```typescript { .api }
152
// External types from dependencies
153
interface Command {
154
  // Commander.js Command interface from 'commander' package
155
  // Full Command interface available at: https://github.com/tj/commander.js/
156
}
157

158
interface IBlamedLines {
159
  // Git blame information for duplicated lines
160
  // From @jscpd/core package
161
}
162

163
interface IDuplication {
164
  sourceId: string;
165
  start: ITokenLocation;
166
  end: ITokenLocation;
167
  range: [number, number];
168
  fragment?: string;
169
  blame?: IBlamedLines;
170
}
171

172
interface ITokenLocation {
173
  line: number;
174
  column?: number;
175
  position?: number;
176
}
177

178
interface IMapFrame {
179
  // Internal type for duplicate detection
180
}
181

182
interface IStore<T> {
183
  namespace(name: string): void;
184
  get(key: string): Promise<T>;
185
  set(key: string, value: T): Promise<T>;
186
  close(): void;
187
}
188
```