Codebase Comparison with jscpd

compare-codebases

jscpd --compare A B pairs every function of folder A with the function of folder B that does the same job, and lists the functions of each folder that have no counterpart. The two folders may be in one language or in two (Python and TypeScript, Kotlin and Swift, Java and Rust). This skill explains how the comparison works and how to run one well. For porting code with the comparison as the progress measure, use the code-migration skill; for the rest of jscpd, the jscpd skill.

How the comparison works

jscpd finds the functions of JavaScript, TypeScript, JSX, TSX, Vue, Svelte, Astro, Python, Rust, Go, Java, Kotlin, C#, C, C++, PHP, Ruby, Scala and Swift files in both folders. It turns the code of each function into a vector with a code embedding model that runs inside jscpd (CodeRankEmbed by default), so two functions that do the same job point the same way even when their languages, names and structure differ. Functions of one folder are never compared with each other.

Functions pair in two steps:

1. By code. Two functions pair when each is the other's closest match in the other folder, their cosine similarity reaches the model's threshold (0.4125 across languages and 0.6375 within one language, with CodeRankEmbed), and the similarity stands out from the function's other matches. A function close to the best one also pairs when it reaches a higher bar, so a feature written twice on one side gets two pairs. Functions shorter than --min-tokens (30 with --compare) or --min-lines (5) stay out of this step, because a short function resembles too many others.
2. By name. A function left over pairs with a function of the other folder under the same name, once case, underscores, spaces and punctuation are ignored (encodeBinary, encode_binary, _encode_binary; the test title rounds cents and rounds_cents), when their similarity reaches the medium level (0.5625 across languages with CodeRankEmbed). A name pair skips the closest-match and stand-out checks of the first step, so it needs more than that step's threshold; otherwise every load and init of two codebases would pair. Size does not matter here, so a short port is found. A name pair has to stay within modules the first step linked. A module is the folder right under the deepest folder all files of a side share (notification in android/notification/…), and a file that sits higher than the rest, such as a build script, does not move that folder up. Two modules link when one holds the most of the other's pairs, counted for code and for tests separately. So checkPermissions of one plugin does not pair with its namesake in another.

Each pair gets a level on the scale of the model, because a cosine that is high for one model is low for another:

jscpd measures tests and code apart, in two blocks of the report, and pairs a test only with a test. It tells a test by the conventions of its language:

• a test file such as *_test.go, test_*.py, *.test.ts, *.spec.js, *Tests.swift or *_spec.rb;
• a test folder such as tests/, __tests__/, spec/, src/test/ (where Java, Kotlin and Scala keep their tests) or MyAppTests/, the compared folder's own name included;
• a Rust function in a #[cfg(test)] module or under #[test];
• a JavaScript or TypeScript test case such as it('rounds cents', () => …).

When neither side has a test that counts (see below), the report has one block and no headings.

Totals count the functions of at least --min-tokens tokens and --min-lines lines; smaller ones appear only as partners. Declarations without a body (TypeScript overloads, the functions of a .d.ts file, interface and abstract methods) take no part. Anonymous functions (callbacks, closures) take no part either, except JavaScript and TypeScript test cases. A test case such as it('rounds cents', () => …) goes by its title, and so do those written with test, specify, fit, xit, xtest or bench, with .only, .skip or .each(table) after them. Suites and hooks stay anonymous. jscpd does not compare types, constants, SQL or UI markup.

A way to compare two folders

1. Pick the folders

• Point at the code, not the repositories: app/src/main/java and ios/Sources, not the two repository roots. Build output, vendored code, installed packages and generated files dilute the result, and a vendored dependency tree can turn a run of seconds into one of tens of minutes, since every function in it is embedded. Inside a git repository jscpd skips what .gitignore excludes; outside one, or for folders the .gitignore misses, pass them with --ignore (--ignore "**/vendor/**,**/target/**,**/node_modules/**"). When a side has no .gitignore entries for such folders, suggest them to the user.
• Two folders are required, and they must not overlap: app/ and app/android/ is refused.
• Keep parallel structures when you can (ios/<module> and android/<module>). Modules steer the name step, so matching folder names help.
• For a port, put the source first and the target second, so the first line of the report is the port's progress. For two implementations that both live on, the order does not matter.
• One run covers tests and code, since the report measures the tests in a block of their own. When the user asks about the code alone, leave the tests out with --ignore "**/__tests__/**,**/*.test.*,**/test/**". When they ask about the tests alone, pass the two test folders as the paths, or pick the test files with --pattern.

2. Get the model

The first run needs the model (548 MB). Ask the user before downloading it:

npx jscpd --semantic-download

jscpd caches the vectors per pair of folders, so later runs embed only the functions whose code changed.

3. Read the overview

npx jscpd --compare billing-py/ billing-ts/

 71% 5 of 7 functions in billing-py/ have a counterpart in billing-ts/
 80% 4 of 5 functions in billing-ts/ have a counterpart in billing-py/

billing-py/
  file         paired  similarity  counterpart
  billing.py   4 / 5   0.89        billing.ts
  shipping.py  1 / 2   0.91        shipping.ts

billing-ts/
  file         paired  similarity  counterpart
  billing.ts   3 / 4   0.89        billing.py
  shipping.ts  1 / 1   0.91        shipping.py

Paired under other names (1):
  billing-py/                   billing-ts/             similarity
  billing.py:28 tax_for_region  billing.ts:27 salesTax  0.87 high

Only in billing-py/ (2):
  billing.py (1)
    46  due_date                6 lines
  shipping.py (1)
    18  estimate_delivery_days  8 lines

Only in billing-ts/ (1):
  billing.ts (1)
    39  toCurrency  8 lines

• When both folders hold tests, the report has a Code block and a Tests block, each with everything below. The two top lines of a block give the share of each folder's functions (or tests) that have a counterpart in the other.
• The file tables give each file's paired functions, the mean similarity of its pairs (with the number of low pairs, as in 0.62, 1 low), and the file on the other side that holds most of its counterparts.
• "Paired under other names" lists the pairs whose names differ even once case and underscores are ignored. A search by name never finds these.
• "Only in" lists the functions with no counterpart, per folder, grouped by file with the number of each file's functions, then each function's first line, name and length.
• In colour, levels are green (high), yellow (medium) and red (low), and the shares are green when complete, yellow when partial and red when nothing is paired. Pass --no-colors when you parse the console output, or read the JSON report instead.
• If one folder has no functions, the report is one line of totals and <folder> has no functions yet. Check the path and the languages before concluding anything else.