jscpd Code Migration Tracker

code-migration

jscpd --compare SOURCE TARGET pairs every function of one folder with the function of the other folder that does the same job, in any pair of languages, and lists the functions that have no counterpart. This skill uses it to measure a port: what is ported, what is left, and whether the port you just wrote was recognized.

A port runs in two phases: the tests first, then the code they check. A coverage report of the source's tests tells which tests exercise which function, so each function is ported together with the tests that prove it works. See Plan: tests first, then code.

Two words are used throughout:

• source: the implementation you port from, such as the iOS app, the Python library, or the JavaScript package;
• target: the implementation you port to, such as the Android app, the Rust crate, or the TypeScript rewrite.

Neither has to be old or new. The source may stay in production and keep changing, and the target may already hold features the source lacks. For two implementations that both live on (ios/ and android/), the same report shows parity; see Parity.

jscpd finds functions in JavaScript, TypeScript, JSX, TSX, Vue, Svelte, Astro, Python, Rust, Go, Java, Kotlin, C#, C, C++, PHP, Ruby, Scala and Swift. The compare-codebases skill explains how the comparison pairs functions and how to check its result; the jscpd skill covers the rest of the tool.

Setup

--compare pairs functions with a code embedding model that runs inside jscpd. Download it once (548 MB, CodeRankEmbed). Ask the user before you start the download:

npx jscpd --semantic-download

jscpd caches the vectors, so a repeat run embeds only the functions whose code changed and takes seconds.

Pick the two paths and keep them fixed for the whole port: the source first, the target second. Two paths are required, and they must not overlap (app/ and app/android/ is refused). The target may be empty at the start.

One run measures both phases: the report has a Code block and a Tests block (a code and a tests section in JSON), and a test pairs only with a test. jscpd tells a test by the conventions of its language: test files such as *_test.go, test_*.py, *.test.ts or *Test.java, folders such as tests/, __tests__/ or src/test/, Rust tests in #[cfg(test)] modules, and JavaScript test cases such as it('rounds cents', () => …). Phase 1 reads the Tests block, phase 2 the Code block.

Keep vendored and generated code out

--compare counts and embeds every function in both paths. Vendored dependencies (vendor/ from cargo vendor or go mod vendor, third_party/), installed packages (node_modules/, .venv/), build output (target/, build/, dist/) and generated code are not part of the port, yet a vendored crate tree alone holds thousands of functions. With them in a path, the first run embeds all of them and takes tens of minutes instead of seconds, and the percentages describe the dependencies instead of the port.

jscpd skips what .gitignore excludes, but only inside a git repository. Before the first run:

1. Check both paths for such folders. A target you create for the port gets them as soon as you build it or vendor its dependencies, so check again after the first build.

2. Suggest a .gitignore to the user that lists the folders the target's language and tools produce, plus the report folder. For a Rust addon built with napi-rs:

   /target/
   /vendor/
   node_modules/
   *.node
   .jscpd-compare/

   If the target is not in a git repository, tell the user that jscpd reads the .gitignore only after git init.

3. Until the .gitignore works, pass the same folders with --ignore, and keep the globs the same for every run:

   npx jscpd --compare node-lib/ rust-lib/ --ignore "**/vendor/**,**/target/**,**/node_modules/**"

The totals line shows when something slipped through. Suspect vendored or generated code in a path when the target has far more functions than the source, or when a run embeds hundreds of functions after a small change.

Measure

Run the console report for yourself and for the user. Here a Python billing library is being ported to TypeScript:

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

• The first line is the port's progress: the share of the source's functions that have a counterpart in the target. "Only in" the source is the work left.
• The second line and "Only in" the target describe the target's own code: helpers the port needed, features the source never had, or a port jscpd did not recognize (see Misses).
• Each file row gives its paired functions, the mean similarity of their pairs (with the number of low pairs, if any), and the counterpart file: the file on the other side that holds most of its counterparts. Use the counterpart to decide where a missing function goes.
• "Paired under other names" lists the pairs whose names differ even once case and underscores are ignored: renamed ports, constructors, platform names. Each has its similarity and level (see Reading pairs). These are ported already, even though a search by name would not find them.
• With an empty target the report is one line of totals plus billing-ts/ has no functions yet.

For work you plan and track, read the JSON report instead of the console:

npx jscpd --compare billing-py/ billing-ts/ -r json -o .jscpd-compare --silent

jscpd measures tests and code apart and pairs a test only with a test, so .jscpd-compare/jscpd-compare.json has a code and a tests section of the same shape. Each section has sides[0] (the source) and sides[1] (the target), each with path, functions, matched, percentage, files (file, functions, matched, counterpart, similarity, lowPairs) unmatched (file, name, start, end) and readyToPort (the unmatched functions whose callees all have a counterpart, with their number of callers, most called first), and pairs, each with a (source), b (target), similarity, level (high, medium, low), renamed (the names differ) and matchedBy (code or name). Paths are relative to each side's folder. Add .jscpd-compare/ to .gitignore or write the report outside the repository.

-r console-full also prints every pair with its similarity, -r markdown writes jscpd-compare.md, a table you can paste into a PR description or a tracking issue, and -r html writes jscpd-compare.html, a migration map the user can open to see the two dependency graphs side by side, or the same pairs as a table.

Plan: tests first, then code

Port the tests before the code. Ported tests define, before any target code exists, what it means for each function to be ported: when the function lands, its tests pass or show what still differs. A port written before its tests can only be checked against your reading of the source.

Bind tests to functions with coverage

A test's name does not say which functions it runs: a test of checkout also runs apply_discount and tax_for_region. Coverage does. Before porting anything, build a map from each source function to the tests that exercise it.

1. Get a coverage report of the source's tests that says which test ran which lines: recorded per test, or per test file when the project's tooling has no per-test mode.
2. Take the source's functions and their lines from the code section of the JSON report. Every counted function is either in the source's unmatched list or the a side of a pair, each with file, name, start and end. Functions under --min-tokens or --min-lines are not listed there; take those from the coverage report's own function list, which most formats have.
3. A test covers a function when it runs a line from the function's start to its end. Write the map both ways, function to tests and test to functions, to a file next to the report (for example .jscpd-compare/test-map.json), and rebuild it when the source's tests change.

Use the map for three things:

• which tests to port with a function, and which functions a ported test needs before it can pass;
• the source functions no test covers. Before porting such a function, write a test for it on the source side that records what it does today (a characterization test), and port that test with the others. A port with no test has nothing to check it;
• the order of work: tests that need few functions come first, since they turn green soonest.

Coverage says which code a test runs, not what it checks. A function that a test only passes through on the way to another is weakly bound to that test; prefer the tests whose names or assertions are about the function.

Phase 1: port the tests

1. Take the source's unmatched tests from the tests section of the JSON report. A JavaScript or TypeScript test case written as a callback, it('rounds cents', () => …), goes by its title, so it pairs with test_rounds_cents in pytest or rounds_cents in Rust like any named test.
2. Port the tests file by file, into the target's test layout, against the API the target will have. Keep inputs and expected values exactly as they are. Where the target must behave differently (a platform limit, a language's number types), write the difference into the test with a comment and tell the user.
3. A ported test calls functions that do not exist yet, so it fails. In a compiled language it stops the whole test build. Keep such tests out of the build until their functions land, for example a module declaration left commented out, a cfg feature or an excluded source set, and turn them on one by one in phase 2. Do not write empty functions to make the tests compile: a stub under a source name can pair by name and count as ported.
4. Run the target's tests. The ported tests that pass already cover what the target has; the failing or disabled ones, read against the test map, are the work list for phase 2.