jscpd Duplicate Code Detector

jscpd

Copy-paste detector for programming source code, supports 220+ languages. Use this skill to run jscpd and understand its output.

Quick Start

# Run with ai reporter (compact output optimized for agents)
npx jscpd --reporters ai <path>

# With ignore patterns
npx jscpd --reporters ai --ignore "**/node_modules/**,**/dist/**" <path>

# Scope to specific formats
npx jscpd --reporters ai --format "javascript,typescript" <path>

# Second pass, noisier: copies that only differ in names and values (Type-2, "renamed").
# Review each hit before acting on it.
npx jscpd --reporters ai --ignore-identifiers --min-tokens 70 <path>

# Third pass, noisier still: copies with a few edited lines or the same function
# structure (Type-3, "similar"). Keep the settings tight.
npx jscpd --reporters ai --max-gap-lines 1 --similarity <path>

# Where to refactor first: clone list plus a hotspot summary
npx jscpd --reporters ai --summary <path>

# Most complex files only, without clone detection
npx jscpd --complexity --reporters ai <path>

AI Reporter Output Format

The ai reporter produces compact, token-efficient output designed for agent consumption:

Clones:
src/ foo.ts:10-25 ~ bar.ts:42-57
src/utils/helpers.ts:100-120 ~ src/utils/other.ts:5-25
src/cart/ basket.js:1-9 ~ cart.js:1-9 (renamed)
src/api/ save-account.js:1-12 ~ save-user.js:1-11 [~0.91 gap]
src/billing/ orders.ts:1-14 ~ refunds.ts:1-15 [~0.85 ast]
---
5 clones · 4.2% duplication

Each line represents one clone pair:

• Same file: path/file.ts 10-25 ~ 45-60 (shared path shown once)
• Same directory: shared/prefix/ file-a.ts:10-25 ~ file-b.ts:42-57 (common prefix factored out)
• Different paths: path/a.ts:10-25 ~ path/b.ts:42-57

A suffix tells the kind of clone; no suffix means an exact copy:

• (renamed): the two blocks differ only in identifier names, literal values or annotations (Type-2). Only appears with --ignore-identifiers, --ignore-literals or --ignore-annotations.
• [~0.91 gap]: two exact clones merged across up to --max-gap-lines unmatched lines (Type-3). The number is matched tokens over the merged span.
• [~0.85 ast]: two functions whose normalized syntax trees share at least --similarity of their subtrees (Type-3). The number is that share. The names of called functions and methods and the operators count, local names and literal values do not, so a renamed copy with other constants scores 1 and a copy that calls other methods scores lower.

Options

Clone Kinds: Exact, Renamed, Similar

By default jscpd reports exact clones only: the token sequences are identical (whitespace, layout and, depending on the mode, comments do not count). Two opt-in families widen the net. Run them as separate passes after the default scan, because they find more and longer clones and change what a "clone" means.

These passes are noisy by design. An exact clone is almost always a real copy. A renamed or similar clone is a candidate: the flags deliberately ignore the very things (names, values, a statement or two) that often make two blocks different in meaning. Expect false positives from:

• boilerplate that is supposed to look alike: DTOs and models, config tables, enum-like maps, route or handler registrations, builders
• test files: describe/it blocks, fixtures and setup code repeat the same shape on purpose
• generated code, migrations, serializers, protocol bindings
• language idioms: two reduce loops or two switch statements that share structure but not logic
• small blocks: with --ignore-identifiers a 50-token block is mostly placeholders, so raise --min-tokens

Rules that keep the noise manageable:

• Run them after the exact clones are handled, one family at a time, so every hit is attributable to one flag.
• Start conservative: --ignore-identifiers alone (add --ignore-literals only when constants are the known problem), --max-gap-lines 1 or 2, --similarity 0.85 or higher, and --min-tokens 70 or more for the identifier pass. Widen only when the tight run comes back empty.
• Treat every (renamed) or [~…] line as a lead to read, not a defect to fix. Do not gate CI (--threshold, --fail-on-new-clones) on these passes unless the team has reviewed what they report on the codebase.
• Never claim "N duplicates found" from a normalized run without saying which flags produced them.

Type-2: renamed clones (--ignore-identifiers, --ignore-literals, --ignore-annotations)

Copies where someone renamed the variables or changed the constants:

npx jscpd --reporters ai --ignore-identifiers <path>                      # function a(x) {…} matches function b(y) {…}
npx jscpd --reporters ai --ignore-identifiers --ignore-literals <path>    # …and 10 matches 25, 'dev' matches 'prod'
npx jscpd --reporters ai --ignore-annotations <path>                      # @Override / @Deprecated no longer split a clone

Clones:
basket.js:1-9 ~ cart.js:1-9 (renamed)
limits-dev.js:1-13 ~ limits-prod.js:1-13 (renamed)
---

• Keywords keep their meaning (return never matches retry), so structure still has to match.
• --ignore-annotations only acts in Java, Kotlin, Scala, Groovy, Python, Dart, Swift, JavaScript and TypeScript; in Ruby, Perl, T-SQL, Razor and CSS @ means something else and is left alone.
• Positions in the report still point at the original source.
• Config keys: ignoreIdentifiers, ignoreLiterals, ignoreAnnotations.

Type-3: near-miss clones (--max-gap-lines, --similarity)

Copies with a few edited lines, or functions rewritten with the same shape:

npx jscpd --reporters ai --max-gap-lines 2 <path>      # a copy with up to 2 inserted/changed lines becomes one clone
npx jscpd --reporters ai --similarity <path>           # functions whose normalized syntax trees share ≥82% of their subtrees

Clones:
save-account.js:1-12 ~ save-user.js:1-11 [~0.91 gap]
orders.ts:1-14 ~ refunds.ts:1-15 [~0.85 ast]
---

• --max-gap-lines N only joins clones the exact run already found, so it removes fragmentation rather than inventing matches; it works in every language. A merge is refused when the gap holds more tokens than the halves share (similarity would drop under 0.5).
• --similarity normalizes the syntax tree of every function (local names and literals become markers, called names and operators stay) and scores the share of subtrees two trees have in common, so a renamed copy scores 1.0, one inserted statement in a function of ten about 0.85, a copy that calls other methods less. It applies to JavaScript, TypeScript, Python, Java, Kotlin, Scala, C#, Go, Rust, C, C++, PHP, Ruby, Swift and Clojure, and to their code blocks in Markdown and in Vue, Svelte and Astro files; other formats are a silent no-op. A function nested in another is part of it, and test files are left out. Start at the default 0.8 and lower to 0.7 only when looking for leads; read both functions before believing a low score.
• similar takes precedence over renamed when both apply (a merged clone is no longer identical even after normalization).
• Config keys: maxGapLines, similarity, minNodes.