Bridge: Automatically Mining Ecosystem-Scale API Update Mappings and Client Update Instances

Bridge: Automatically Mining Ecosystem-Scale API Update Mappings and Client Update Instances

arXiv:2608.30497v1 [cs.SE] 31 Aug 2026

KAI GAO, University of Science and Technology Beijing, China YU SUN, University of Science and Technology Beijing, China CHANG-AI SUN, University of Science and Technology Beijing, China Library updates are essential for incorporating bug fixes, security patches, and new features, but they often require adapting client code to API changes. API update mappings that identify relations between legacy and replacement APIs, version transitions that these mappings apply, and client update instances that capture concrete API call changes are essential for developing and evaluating automated library update techniques. Existing library evolution datasets capture different subsets of this information, but none simultaneously provides all three. Moreover, these datasets typically cover a small number of third-party libraries, limiting the diversity of API updates they capture. Constructing a dataset that provides all three types of information at ecosystem scale is challenging because it requires reliably connecting API update mappings, version transitions, and client update instances across large numbers of library releases and client projects. To address this challenge, we present Bridge, a client-driven framework that starts from observed client dependency updates, which naturally connect library version transitions with client code changes. Built on the World of Code (WoC) infrastructure, Bridge mines candidate update instances from client dependency update commits at scale, validates them using library-side evidence, and then derives API update mappings from validated instances. This design grounds each retained mapping in at least one client update instance. On a manually annotated ground truth dataset, Bridge achieves 91.6% precision and 88.7% recall for Java and 90.1% precision and 64.0% recall for Python. Applied to WoC V3, Bridge mines 381,661 Java and 277,259 Python client update instances, representing 18,900 and 4,456 API update mappings across 2,557 and 999 libraries, respectively. The mined mappings exhibit a pronounced long-tail distribution, with most appearing in only a few client update instances. As one application of the dataset, we evaluate four large language models on replacement API recommendation, a key step in library updates. The best recommendation accuracy reaches only 37.1% for Java and 44.4% for Python, and all evaluated models perform substantially better on frequently observed mappings than on mappings observed in only a few client update instances, highlighting the difficulty current LLMs face in recommending replacements for mappings in the long tail. Overall, Bridge provides an automated approach to constructing ecosystem-scale library update datasets that connect what APIs are replaced, between which versions, and how clients perform the updates. CCS Concepts: • Software and its engineering → Software evolution; Software libraries and repositories. Additional Key Words and Phrases: Library Update, Mining Software Repositories, API analysis, Library Ecosystems, Large Language Models Authors’ Contact Information: Kai Gao, University of Science and Technology Beijing, Beijing, China, kai.gao@ustb.edu.cn; Yu Sun, University of Science and Technology Beijing, Beijing, China, yusun@xs.ustb.edu.cn; Chang-ai Sun, University of Science and Technology Beijing, Beijing, China, casun@ustb.edu.cn.

Permission to make digital or hard copies of all or part of this work for personal or classroom use is granted without fee provided that copies are not made or distributed for profit or commercial advantage and that copies bear this notice and the full citation on the first page. Copyrights for components of this work owned by others than the author(s) must be honored. Abstracting with credit is permitted. To copy otherwise, or republish, to post on servers or to redistribute to lists, requires prior specific permission and/or a fee. Request permissions from permissions@acm.org. © 2018 Copyright held by the owner/author(s). Publication rights licensed to ACM. ACM 1557-735X/2018/8-ART111 https://doi.org/XXXXXXX.XXXXXXX J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

111:2

Kai Gao, Yu Sun, and Chang-ai Sun

ACM Reference Format: Kai Gao, Yu Sun, and Chang-ai Sun. 2018. Bridge: Automatically Mining Ecosystem-Scale API Update Mappings and Client Update Instances. J. ACM 37, 4, Article 111 (August 2018), 34 pages. https://doi.org/XXXXXXX. XXXXXXX

1

Introduction

Modern software systems depend extensively on third-party libraries for reusable functionality. New library versions provide security patches, bug fixes, and new features, making timely library updates an important dependency management practice for software security and quality [17, 58, 70]. However, new releases may deprecate or remove APIs [65, 75], breaking client code [4, 5] and imposing substantial maintenance effort on developers [3, 43]. Consequently, developers often adopt the conservative practice of “if it ain’t broke, don’t fix it” and forgo library updates [10, 43, 64]. Automating library updates requires information about what APIs should be replaced and how client code should be adapted. Specifically, API update mappings identify relations between legacy and replacement APIs, their applicable version transitions specify when these replacements occur, and client update instances capture concrete API call changes performed during library updates. Such information underpins rule-based techniques that derive and apply code transformation rules [12, 16, 25, 27, 44, 51, 54, 84]. Recent LLM-based techniques similarly incorporate API mappings, update examples, or natural-language instructions into prompts to adapt client code [2, 47, 67, 71]. These three forms of information therefore provide useful data for developing and evaluating automated library update techniques. Existing library evolution datasets [7, 36, 42, 74, 81] capture different subsets of this information, but none simultaneously provides all three. They also typically cover a small number of third-party libraries, limiting the diversity of API updates they capture. As shown in Figure 1, their construction generally follows a library-driven workflow: they begin with a predefined collection of libraries, identify API changes or mappings within them, and then prepare corresponding code examples from sources such as documentation [42, 81], client projects [74], manual construction [36], or LLM generation [7]. Scaling this workflow is challenging because API update mappings identified from library artifacts must be connected to the version transitions and client code changes in which they are actually observed, which requires analysis across large numbers of library releases and client projects. Moreover, client projects typically exercise only a small subset of the APIs exposed by their dependencies [35, 74], so even a known mapping may have few or no observable client update instances. Consequently, ecosystem-scale library update datasets that connect API update mappings, version transitions, and client update instances remain scarce. To address this challenge, we present Bridge, a client-driven framework for automatically constructing library update datasets from observed client dependency updates. As illustrated in Figure 1, instead of first identifying API update mappings and subsequently obtaining code examples, Bridge starts from dependency update commits in client projects. Such commits directly provide the updated library and its old and new versions, while associated source code changes provide candidate adaptations for that version transition. Bridge therefore first mines candidate update instances from client-side API call changes, validates the candidates using library-side evidence, and then derives API update mappings from validated instances. Its key design principle is that client code provides plausible replacement candidates, while library artifacts provide evidence for validating them. Consequently, the resulting library update dataset connects API update mappings, version transitions, and client update instances, with each retained mapping associated with a version transition and grounded in at least one client update instance. Built on the World of Code (WoC) infrastructure [45, 46], Bridge realizes this client-driven workflow in four phases. It first identifies commits that update dependency versions and also J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

Bridge : Automatically Mining Ecosystem-Scale API Update Mappings and Client Update Instances

Library Releases

API Changes/ Mappings

Code Examples

Library-driven Dataset Construction

Client Dependency Updates

111:3

Candidate Update Library Update Instances Dataset

Bridge: Client-driven Dataset Construction

Fig. 1. Comparison of library-driven and Bridge’s client-driven workflows to constructing library update datasets.

modify source files, which naturally links version transitions and client code changes. It then extracts API call metadata from the old and new source blobs. Next, Bridge identifies changed calls associated with the updated library and applies similarity-based matching to generate candidate update instances. Finally, it validates the candidates against the involved library versions by verifying API existence and the removal or deprecation of the legacy API, and then derives API update mappings from the validated instances. We implement Bridge for two popular and substantially different ecosystems, Java and Python, and evaluate it from four perspectives. First, we evaluate its accuracy in mining client update instances against a manually annotated ground truth dataset containing 344 and 242 genuine update instances in 638 Java and 609 Python API call change records, respectively. Bridge achieves 91.6% precision, 88.7% recall, and a 90.1% F1 score for Java, and 90.1% precision, 64.0% recall, and a 74.9% F1 score for Python. Second, we analyze the similarity parameters used for client-side candidate generation and the contribution of library-side validation. Similarity weights have limited impact on the F1 score, while the matching threshold controls the precision–recall tradeoff. More importantly, library-side validation improves precision by 40.3 percentage points for Java and 43.3 points for Python, empirically supporting the design of combining client-side candidate generation with library-side validation. Third, we apply Bridge to WoC V3 and construct a dataset containing 381,661 client update instances and 18,900 API update mappings across 2,557 Java libraries, together with 277,259 instances and 4,456 mappings across 999 Python libraries. The mined mappings exhibit a pronounced long-tail distribution: the median mapping appears in only two client update instances, while a small number recur in thousands or tens of thousands of instances. Finally, we demonstrate one application of the dataset by evaluating four large language models on replacement API recommendation, a key step in library updates. The best recommendation accuracy reaches only 37.1% for Java and 44.4% for Python, and all evaluated models perform substantially worse on mappings observed in only a few client update instances. By connecting API update mappings with their occurrences in client updates, the dataset enables such frequency-aware analyses and highlights the challenge current LLMs face in recommending replacements for mappings in the long tail. In summary, this paper makes the following contributions: • We propose Bridge, a client-driven framework for automatically constructing library update datasets that connect API update mappings, version transitions, and client update instances. • We implement Bridge for Java and Python and systematically evaluate its effectiveness and key design choices, demonstrating its effectiveness for high-precision library update dataset construction. • We construct an ecosystem-scale dataset spanning thousands of Java and Python libraries and hundreds of thousands of client update instances, with a pronounced long-tail distribution of API replacements. J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

111:4

Kai Gao, Yu Sun, and Chang-ai Sun

• We demonstrate the utility of the dataset through a replacement API recommendation study, revealing that LLMs have substantially greater difficulty in recommending replacements for mappings in the long tail. The remainder of this paper is organized as follows. Section 2 introduces the background and related work, Section 3 presents the Bridge framework, Section 4 reports the evaluation, and Section 5 discusses the implications and threats to validity. Section 6 concludes the paper. The implementation of Bridge and the mined dataset are publicly available at https://github.com/ROCKSE/Bridge. 2

Background and Related Work

This section defines related terminology, reviews existing library evolution datasets and approaches for mining API update mappings and client update instances, and introduces the World of Code infrastructure used by Bridge. 2.1

Terminology

Many programming language ecosystems provide centralized registries, such as Maven Central in Java and PyPI in Python, for distributing reusable software libraries. In this paper, a library refers to a third-party project published on such a registry. A Java library is identified by its group ID and artifact ID [48], such as junit:junit, while a Python library is identified by its normalized PyPI name [61], such as django. When a project uses a library, we refer to the library as the project’s dependency and the project as the library’s client. A library typically releases multiple versions, each exposing a set of public Application Programming Interfaces (APIs). We use API signature to denote the user-facing identity of an API. For Python, we represent an API signature by its fully qualified name (FQN), such as django.urls.reverse, following common practice in Python API evolution datasets. For Java, an API signature consists of the FQN and formal parameter types [59], such as org.junit.Assert.assertEquals(long, long), because Java supports method overloading. An API call is a concrete invocation of an API in client code, including its actual arguments. When a client updates a dependency from one version to another, its source code may require adaptation to API changes in the updated library. Figure 2 shows a concrete example in which a client updates Apache PDFBox from version 2.0.24 to 3.0.0 and replaces the removed org.apache.pdfbox.pdmodel.PDDocument.load(File) API with org.apache.pdfbox.pdmodel.Loader. loadPDF(File), consistent with the library’s upgrade guide1 . Prior work has used terms such as API migration [44, 63, 84], code migration [7, 71], and library migration [2, 54] for such adaptation. In this paper, we choose the term library update. We avoid using “migration” for this process because this term is also widely used to denote replacing one library with another that provides similar functionality [11, 20–23, 29, 30, 37–39]. Given a library 𝑙 and two versions 𝑣𝑜 and 𝑣𝑛 , where 𝑣𝑜 denotes the old version and 𝑣𝑛 the new version, we define three types of information in our library update dataset, as illustrated by Figure 2. First, an API update mapping is a 3-tuple (𝑙, 𝑎𝑜 , 𝑎𝑛 ), where 𝑎𝑜 is a legacy API signature and 𝑎𝑛 is its replacement API signature. This definition is consistent with prior work [74]. An API update mapping captures a replacement relation independently of a particular version transition. For example, Figure 2 shows the mapping from org.apache.pdfbox.pdmodel.PDDocument.load(File) to org.apache.pdfbox.Loader.loadPDF(File). Second, an API update pair is a 5-tuple (𝑙, 𝑣𝑜 , 𝑎𝑜 , 𝑣𝑛 , 𝑎𝑛 ) that associates an API update mapping with a particular version transition. A single mapping may therefore correspond to multiple update pairs when the same replacement relation applies across different version transitions. Third, an client update instance is a 5-tuple (𝑙, 𝑣𝑜 , 𝑐𝑜 , 𝑣𝑛 , 𝑐𝑛 ), 1 https://pdfbox.apache.org/3.0/migration.html#use-loader-to-get-a-pdf-document

J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

Bridge : Automatically Mining Ecosystem-Scale API Update Mappings and Client Update Instances

111:5

Library: org.apache.pdfbox:pdfbox PDFBox 3.0 Migration Guide The new class org.apache.pdfbox.Loader is used for loading a PDF. It offers several methods to load a pdf using different kind of sources. All load methods have been removed from org.apache.pdfbox.pdmodel.PDDocument. The same is true for loading a FDF document.

Library API Evolution

Version 2.0.24 org.apache.pdfbox.pdmodel.PDDocument.load(File) Dependency

Version 3.0.0 org.apache.pdfbox.Loader.loadPDF(File)

Dependency Update org.apache.pdfbox:pdfbox 2.0.24 -> 3.0.0

Dependency

Client: fhoeben/hsac-fitnesse-pdf Before Commit 0b8c7c import org.apache.pdfbox.pdmodel.PDDocument; import java.io.File; PDDocument doc = PDDocument.load(new File(file));

After Commit 0b8c7c Client code adaptation import org.apache.pdfbox.Loader; import org.apache.pdfbox.pdmodel.PDDocument; import java.io.File; PDDocument doc = Loader.loadPDF(new File(file));

Fig. 2. A library update example from commit 0b8c7c in the fhoeben/hsac-fitnesse-pdf project.

where 𝑐𝑜 and 𝑐𝑛 are legacy and replacement API calls observed in client code when the client updates 𝑙 from 𝑣𝑜 to 𝑣𝑛 . For example, Figure 2 shows an instance in which the client replaces PDDocument.load(new File(file)) with Loader.loadPDF(new File(file)). Thus, mappings capture general replacement relations, update pairs capture their applicability to specific version transitions, and update instances capture how clients perform the replacement in code. 2.2

Library Evolution Datasets

Automated library update techniques rely on different forms of information about API updates and client code adaptations. Rule-based approaches represent code transformation rules using domainspecific languages [16, 25, 27, 28, 63], edit scripts [12, 13, 26, 44, 50, 54, 84], or configuration files [51]. Such approaches commonly rely on knowledge about which APIs correspond across versions and on concrete examples of how API usages should be adapted. More recently, LLM-based techniques have been explored for updating client code that depends on Android API [47], SQLAlchemy [2], and JUnit [71]. These techniques similarly benefit from API replacement knowledge and representative update examples. API update mappings, their applicable version transitions, and client update instances therefore are essential for developing and evaluating automated library update techniques. Recent library evolution datasets, as summarized in Table 1, focus on tasks such as version-aware code completion [36, 42, 74] and code updates [7, 81]. However, they remain limited in the API update information they provide, the number of third-party libraries they cover, and the inclusion of update instances from real client dependency updates. First, existing datasets do not simultaneously provide API update mappings, version transitions, and client update instances. GitChameleon [36] and LibEvolutionEval [42] focus on code completion for specific library versions without providing explicit API update mappings or version transitions. Wang et al. [74] provide API update mappings but do not associate them with version transitions. VersiCode Editing [81] and CodeMEnv [7] capture API update mappings across version transitions, but their code examples are not from real client dependency updates. Consequently, none of these datasets connects API update mappings and version transitions with client update instances. Second, existing datasets cover a small number of third-party libraries. Most focus exclusively on Python [36, 42, 74, 81], covering 8 to 16 third-party libraries. CodeMEnv [7] supports both Java and Python, but covers only four third-party Python libraries and no third-party Java libraries. Real projects, however, commonly depend on dozens or hundreds of third-party libraries [1, 35]. J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

111:6

Kai Gao, Yu Sun, and Chang-ai Sun

Table 1. Comparison of representative library evolution datasets in terms of API update information, coverage, and code sources. Version Transition indicates whether the dataset explicitly associates an API update mapping with source and target library versions. Client Update Instances indicates whether the dataset contains API call changes observed in actual client dependency updates.

# API Update Version Client Update # Third-party Code Source Mappings Transition Instances Libraries

Dataset

Language

GitChameleon [36]

Python

✗

✗

✗

11

LibEvolutionEval [42] Python

✗

✗

✗

8

145 83 0/136

✗ ✓ ✓

✗ ✗ ✗

8 16 0/4*

Handwritten GitHub & documentation GitHub Docstrings LLM-generated

✓

✓

2,557/999

Client updates

Wang et al. [74] Python VersiCode Editing [81] Python CodeMEnv [7] Java/Python Bridge

Java/Python 18,900/4,456

* CodeMEnv additionally contains 7 Python and 8 Java built-in libraries.

Consequently, datasets constructed from a small collection of libraries may not capture the diversity of API updates across third-party libraries. Third, existing datasets do not obtain update instances from real client dependency updates. Their code examples may be handwritten [36], generated by LLMs [7], or derived from documentation and docstrings [42, 81]. Such examples are useful for controlled evaluation, but may not capture how independent clients adapt API usages during library updates [16, 44]. Even datasets [42, 74] that obtain code from GitHub do not systematically connect API call changes with dependency version transitions in which clients perform the updates. Taken together, existing library evolution datasets provide complementary forms of API update information, but none simultaneously connects API update mappings, version transitions, and client update instances across a large number of third-party libraries. 2.3

Mining API Update Mappings and Client Update Instances

The library-driven workflow for constructing ecosystem-scale library update datasets generally involves two steps. The first step is to identify API update mappings. One source is library documentation, including changelogs, release notes, and upgrade guides [80]. Such documentation can explicitly describe recommended replacements, but its availability and completeness vary substantially across projects [79], and it may not describe updates between nonadjacent library versions [84]. Prior work has also inferred API correspondences using library developers’ input [8, 31, 55] or API definition information such as signatures and implementations [16, 19, 33, 41, 54, 82, 83]. Other approaches analyze API usage changes within the library itself [9, 66]. Such internal usages provide useful evidence for identifying API correspondences, but may not reflect how external clients use and adapt APIs during library updates. Scaling these mapping identification approaches to a large library ecosystem requires analyzing API evolution across numerous library releases. Given the millions of library releases on registries such as Maven Central [53] and PyPI [14], exhaustively considering version pairs can incur prohibitive analysis cost, while restricting analysis to selected libraries reduces the coverage of the resulting dataset. The second step is to obtain client update instances for the identified API update mappings. It requires locating projects that use the relevant library, perform an applicable version transition, and exercise the affected APIs among hundreds of millions of public repositories [18]. Client API usage is also sparse: projects generally use only a small subset of the APIs exposed by their J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

Bridge : Automatically Mining Ecosystem-Scale API Update Mappings and Client Update Instances

111:7

dependencies [28, 74, 76]. Consequently, mappings identified from library artifacts may have few or no observable client update instances [24, 74, 85]. In summary, scaling the library-driven workflow requires identifying API update mappings across numerous library releases and locating their client update instances among large numbers of client projects. Consequently, constructing ecosystem-scale library update datasets that connect API update mappings, version transitions, and client update instances remains challenging. 2.4

World of Code

World of Code (WoC) [45, 46] is a large-scale research infrastructure for analyzing version control data. It aggregates Git objects [6], including commits, trees, and blobs2 , from public repositories hosted on platforms such as GitHub, Bitbucket, and GitLab. WoC organizes these objects into key–value databases that support efficient cross-referencing among commits, files, blobs, and projects, and provides APIs for querying these databases and retrieving raw object contents. This infrastructure enables dependency file changes and their corresponding source code changes to be queried at ecosystem scale without locally cloning hundreds of millions of repositories, making it suitable for mining client dependency updates. In this study, we use WoC V3, updated in May 2024, which contains more than 4.7 billion commits and 19.6 billion blobs across 234 million repositories [78]. 3 The Bridge Framework This section first introduces the client-driven workflow adopted by Bridge and then describes the design and language-specific implementation of each phase. 3.1

Overview

To automatically construct ecosystem-scale library update datasets that connect API update mappings, version transitions, and client update instances, we propose Bridge, a client-driven framework built on WoC. We instantiate Bridge for Java and Python for two reasons. First, they are among the most widely used programming languages. Second, they differ in language design (static vs. dynamic type, compiled vs. interpreted) and library packaging mechanism, allowing us to examine whether the client-driven framework can be instantiated across substantially different ecosystems. Unlike the library-driven dataset construction workflow discussed in Section 1, Bridge adopts a client-driven workflow that starts from dependency updates observed in client projects. A dependency update directly identifies the updated library and its old and new versions, while associated source code changes provide candidate adaptations for that version transition. From these changes, Bridge mines candidate update instances, validates them against the involved library versions, and derives API update mappings from the validated instances. Consequently, each retained mapping is associated with a version transition and grounded in at least one client update instance. Bridge consists of four phases, as show in Figure 3. First, Update Commit Collection identifies commits in WoC that update dependency versions and also modify source files, which naturally links version transitions and client code changes. Second, API Call Metadata Extraction parses source files before and after each dependency update and extracts API call metadata. Third, Candidate Update Instance Mining identifies changed calls associated with the updated library and applies similarity-based matching to obtain plausible legacy–replacement API call pairs (i.e., candidate update instances). Finally, Mapping Resolution and Validation resolves the involved API signatures 2 A blob stores the content of a particular file version.

J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

111:8

Kai Gao, Yu Sun, and Chang-ai Sun

1. Update Commit Collection

2. API Call Metadata Extraction

Update Commits

before

after

Import-based Filtering

API Call Metadata

before

after

Fully Qualified Name

Arguments

3. Candidate Update Instance Mining API Call Change Records

Caller Context

API Call Similarity Scorer

c2fbb database Fully Qualified Name Similarity

Argument Similarity

Version-bumping Commits

AST Analyzer

Dependency Parser

Declared Variable Caller Import alias Type Resolution Identification Resolution

Candidate Update Instances

Source Files

4. Mapping Resolution and Validation

Blob content

Candidate Update Commits pom.xml

pyproject.toml

requirements.txt

setup.py

Signature Resolver

setup.cfg

c2fbb database

Blob content

World of Code

Deprecation and Removal Checker

API Update Mappings, Pairs, and Instances

Fig. 3. Overview of the Bridge framework. Light blue blocks represent data artifacts, light orange blocks represent components requiring language-dependent implementations, and the dark red block represents the final dataset.

for each candidate and validates the candidate using library-side evidence. From the validated instances, Bridge derives API update mappings and API update pairs. 3.2

Phase 1: Update Commit Collection

Design. The client-driven workflow begins by identifying commits in which a client updates a library dependency and also modifies source code. Such commits provide two pieces of information needed by subsequent phases: library version transitions and associated client code changes from which candidate update instances can be mined. Consistent with prior work [16, 37, 84], Bridge assumes that a library update and its associated source code adaptations are typically performed within the same commit. The collection process progressively filters commits according to changes in dependency configuration files, dependency versions, and source files. Bridge first queries WoC for candidate update commits that modify dependency configuration files. WoC provides the c2fbb database, which maps each commit to the paths of changed files and the SHA-1 hashes of their old and new blobs. Because programming language ecosystems commonly use recognizable dependency configuration files, such as pom.xml for Maven projects, Bridge uses their filenames to retrieve such commits from c2fbb. A modification to a dependency configuration file does not necessarily represent a library update because a commit may instead add, remove, or reorganize dependencies [20, 30]. Bridge therefore parses the old and new configuration blobs, extracts dependency names and version constraints, and retains commits that change the version of at least one dependency as version-bumping commits. Following prior work [42, 84], we consider only pinned version constraints (e.g., ==5.2), which allow the old and new dependency versions to be identified precisely. Range-based constraints (e.g., >=3.1.0) and unconstrained dependencies are excluded because their exact resolved versions cannot be determined from the configuration file alone [34, 52, 73, 77]. Finally, it queries c2fbb again and retains version-bumping commits that also modify source files, yielding the update commits processed in subsequent phases. Implementation for Java. In the Java ecosystem, pom.xml is the primary Maven dependency configuration file and has been widely used to extract dependencies from Java projects [30, 40, 56]. J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

Bridge : Automatically Mining Ecosystem-Scale API Update Mappings and Client Update Instances

111:9

Table 2. Statistics for data mined in Phase 1. CU, VB, and CFG are short for candidate update commits, version-bumping commits, and configuration blobs, respectively.

Language Configuration File Java

Python

# Commits # CU # VB # Update

# Blobs # Libraries # Versions # CFG # Source

pom.xml

31,852,062 6,103,952 1,049,834 63,959,850 27,252,177

50,450

630,405

requirements.txt setup.py pyproject.toml setup.cfg

14,677,782 7,719,071 7,622,076 238,418 2,725,506 64,965 1,174,085 29,832

672,536 10,189,499 78,275 5,525,611 16,586 2,045,404 7,886 131,717

6,745,851 1,394,187 266,739 719,294

22,889 6,337 1,830 1,442

210,326 58,544 10,898 7,857

Total

25,002,699 7,993,598

753,902 18,479,562

7,794,556

25,397

236,292

We therefore use changes to pom.xml to identify candidate update commits. We implement a specialized XML parser following the Maven POM specification [48] to extract dependency names and version constraints from relevant elements, such as <dependency>. As shown in Table 2, we identify 31.9 million candidate update commits associated with 64.0 million unique pom.xml blobs, of which 6.1 million (19.2%) are version-bumping commits. Among these version-bumping commits, 17.2% also modify Java source files, yielding 1.0 million update commits and 27.3 million unique Java source blobs. Collectively, these commits involve 50,450 distinct Java libraries and 630,405 library versions. Implementation for Python. Python projects use multiple configuration files to declare dependencies. We consider four common files: requirements.txt, setup.py, pyproject.toml, and setup.cfg. Unlike the executable setup.py, the other three files represent dependency declarations in structured formats: plain text, TOML, and INI, respectively. We therefore implement specialized parsers following their specifications [60, 62, 68]. Parsing setup.py is more challenging because dependencies can be programmatically declared through the install_requires and extras_require parameters of the setup() function provided by setuptools [69]. The install_requires parameter specifies a list of dependency strings (e.g., ["BazSpam==1.1"]), whereas extras_require maps optional feature names to dependency lists (e.g., {"PDF": ["ReportLab>=1.2"]}). To statically recover these declarations from executable setup.py files, we implement the lightweight data-flow analysis formalized in Algorithm 1. The parser first constructs an abstract syntax tree (AST) from the source code and then performs a top-down traversal to build a data-flow graph (DFG) (lines 17–18). The DFG represents data dependencies among program elements. Its nodes may represent variables (e.g., a), subscripts (e.g., a["b"] and l[0]), and constant values. A variable node is represented by its identifier, whereas a subscript node is represented by its target and index (e.g., (a, "b") and (l, 0)). To track values stored in lists and dictionaries, the parser further decomposes their elements and items into individual DFG nodes. The DFG is then constructed using the following rules: • For an import statement (e.g., from setuptools import setup), the parser records the mapping from the imported alias (e.g., setup) to its fully qualified name (e.g., setuptools.setup) (lines 4–5), enabling subsequent identification of calls to the setup API. • For an assignment, the parser creates DFG nodes for the left-hand side (LHS) and right-hand side (RHS) respectively and adds directed edges from the LHS node to the RHS node (lines 6–7). • For a call to the setuptools.setup or distutils.core.setup API, the parser similarly creates edges from keyword parameters to their actual arguments (lines 8–11). To handle keyword argument unpacking (e.g., setup(**kwargs)), it creates dummy nodes for install_requires and J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

111:10

Kai Gao, Yu Sun, and Chang-ai Sun

Algorithm 1: setup.py Parser Input: The source code of a setup.py blob: 𝑠𝑜𝑢𝑟𝑐𝑒 Output: Dependency names and version constraints: D 1 Function build_DFG(AST ): 2 aliases ← ∅, DFG ← ∅ 3 for node 𝑛 ∈ 𝐴𝑆𝑇 do // top-down traversal 4 if is_import_node(n) then 5 aliases ← aliases ∪ parse_alias(n) 6 if is_assignment_node(n) then 7 resolve_edges(n.lhs, n.rhs, DFG) 8 if is_setup_call(n, aliases) then 9 for 𝑘𝑤 ∈ 𝑛.𝑘𝑤𝑎𝑟𝑔𝑠 do 10 if exists(kw.key) then // setup(install_requires=...) case 11 resolve_edges(kw.key, kw.value, DFG) 12 else // setup(**kwargs) case 13 create_dummy_edges(“install_requires”, kw[“install_requires”], DFG) 14 create_dummy_edges(“extras_require”, kw[“extras_require”], DFG) 15 return DFG 16 Function parse(source): 17 Parse 𝑠𝑜𝑢𝑟𝑐𝑒 into an abstract syntax tree 𝐴𝑆𝑇 18 DFG ← build_DFG(AST ) 19 D ← traverse(“install_requires”, DFG) ∪ traverse(“extras_require”, DFG) 20 return D

extras_require and connects them to corresponding items in the unpacked argument (lines 13–14). Finally, the parser traverses the DFG from the install_requires and extras_require nodes, collects reachable constant strings, and extracts dependency names and version constraints from the collected strings (line 19). In total, we identify 25.0 million candidate update commits associated with 18.5 million unique Python configuration blobs. Parsing their dependency declarations identifies 8.0 million (32.0%) version-bumping commits, of which 9.4% also modify Python source files, yielding 753,902 update commits and 7.8 million unique Python source blobs. Collectively, these update commits involve 25,397 distinct Python libraries and 236,292 library versions. Among the four configuration files, requirements.txt contributes the largest number of update commits, followed by setup.py, consistent with their widespread use for dependency management in Python projects.

3.3

Phase 2: API Call Metadata Extraction

Design. Given the update commits and associated old and new source blobs collected in Phase 1, Bridge extracts structured metadata for API calls in each blob. This metadata transforms raw client code changes into call-level information for similarity-based matching in Phase 3 and API signature resolution in Phase 4. Specifically, Bridge extracts three types of metadata for each API call: • Fully Qualified Name (FQN). The FQN identifies the called API and constitutes a fundamental part of an API signature. It has been widely used to compare Java APIs [33, 54]. J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

Bridge : Automatically Mining Ecosystem-Scale API Update Mappings and Client Update Instances

111:11

• Actual Arguments. Actual arguments provide call-site information for assessing whether an API call removed from the old blob and one added to the new blob may represent a replacement. In addition to argument expressions, Bridge extracts language-specific information useful for matching and signature resolution, including statically resolved argument types for Java and keyword names for Python. • Caller Context. We represent the caller context of an API call as the sequence of enclosing declaration nodes from the AST root to the call node. Phase 3 compares removed and added API calls within the same caller context, based on the intuition that API replacements associated with a library update are typically performed in place. This constraint also reduces the number of call pairs that need to be compared. Precisely resolving all API calls could require building each client project and resolving its dependencies, which is computationally prohibitive at the scale of the update commits collected in Phase 1. Bridge therefore performs lightweight static analysis on individual source blobs without constructing project build environments. The analysis includes import alias resolution, caller identification, and declared variable type resolution. We implement the analysis for both languages using tree-sitter [72], a high-performance parser generator that provides concrete syntax trees and query support for locating relevant constructs such as API calls, import statements, and variable declarations. The language-specific implementations are described below. Implementation for Java. The Java implementation performs import resolution, declared variable type resolution, caller identification, and API call metadata extraction, as summarized in Algorithm 2 and illustrated in Figure 4(a). (1) AST Generation. The extractor first parses each Java source blob into an AST using tree-sitter (line 16). (2) Import Resolution. It locates import statement nodes using a tree-sitter query and records mappings from imported class names to their FQNs (line 17). For example, for the first import statement in Figure 4(a), it records Gson ↦→ com.google.gson.Gson. These mappings are subsequently used to resolve FQNs for API calls (line 21). (3) Variable Type Extraction. The extractor collects explicitly declared variable types throughout the source file (line 18). A tree-sitter query identifies relevant declaration nodes, including fields, local variables, formal parameters, try-with-resources variables, and variables declared in enhanced for statements (line 11). For each declaration, the extractor records the variable name, declared type, and caller context (line 12). The caller context is identified through a bottom-up traversal from the declaration node to the AST root that records enclosing declaration nodes, such as classes, methods, and interfaces (lines 1–7). For example, the extractor records (json, String, GaeInfoServlet.parseJson(String)) for the formal parameter in the sixth statement in Figure 4(a). (4) API Call Metadata Extraction. Finally, the extractor locates API call nodes using another tree-sitter query and extracts metadata for each call (line 19). It first identifies the call’s caller context (line 20). For a call with a receiver object, it attempts to resolve the API FQN using the receiver’s declared type (line 21). Specifically, it searches the recorded variable type information in the current caller context and its enclosing contexts for the receiver’s declared type. It then restores the call’s API FQN by searching the declared type against the import mappings. The extractor also records argument expressions and attempts to resolve their declared types from the recorded variable type information (line 22). Figure 4(a) shows the metadata extracted for the two API calls in the eighth statement. Bridge cannot statically determine the type of the argument in gson.toJson(jp.parse(json)) because doing so would require resolving the return J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

111:12

Kai Gao, Yu Sun, and Chang-ai Sun

Algorithm 2: Java API Call Metadata Extractor Input: The source code of a Java source blob: 𝑠𝑜𝑢𝑟𝑐𝑒 Output: API call metadata: M 1 Function identify_caller(node): 2 C ← ∅, cur_node ← node 3 while cur_node ≠ ROOT do // bottom-up traversal to extract caller context 4 if is_declaration_node(cur_node) then 5 C.add(cur_node) 6 cur_node ← cur_node.parent 7 return C 8 Function extract_variable_declared_types(AST ): 9 T ←∅ 10 for node 𝑑 ∈ query_variable_declaration_nodes(AST ) do // find all variable declaration nodes 11 caller ← identify_caller(d) 12 T .add(d.name, d.type, caller) 13 return T 14 Function extract_api_call_metadata(source): 15 M←∅ 16 Parse 𝑠𝑜𝑢𝑟𝑐𝑒 into an abstract syntax tree 𝐴𝑆𝑇 17 import_name_mappings ← parse_import_nodes(AST ) 18 variable_types ← extract_variable_declared_types(AST ) 19 for node 𝑐 ∈ query_api_call_nodes(AST ) do // extract metadata for each API call 20 caller ← identify_caller(c) 21 fqn ← resolve_fully_qualified_name(c.name, caller, variable_types, import_name_mappings) 22 arguments ← resolve_argument_types(c.arguments, caller, variable_types) 23 M.add(fqn, arguments, caller) 24 return M

type of another API call. Bridge intentionally omits such interprocedural or dependency-aware type resolution to keep metadata extraction scalable across millions of source blobs. Implementation for Python. The Python implementation focuses on import alias resolution and caller identification. Because Python is dynamically typed, reliably resolving variable types through lightweight static analysis is difficult and time-consuming. We therefore do not perform variable type inference and instead resolve API FQNs when they can be determined from import and alias information. Figure 4(b) illustrates the extraction process. (1) AST Generation. The extractor first parses each Python source blob into an AST. (2) Alias Resolution. It locates import statement nodes using a tree-sitter query and records mappings from imported names and aliases to their FQNs. For example, for the second statement in Figure 4(b), it records rev ↦→ django.urls.reverse. These mappings are used to resolve FQNs for imported API calls. (3) API Call Metadata Extraction. Finally, the extractor locates API call nodes using another tree-sitter query and, for each call, attempts to resolve its FQN, records its argument expressions, and identifies its caller context using the same bottom-up procedure as the Java J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

Bridge : Automatically Mining Ecosystem-Scale API Update Mappings and Client Update Instances

"FQN": "com.google.gson.Gson.toJson", "arguments": [ {"value": "jp.parse(json)", "type": null} ], "caller": "GaeInfoServlet.parseJson(String)"

1 import com.google.gson.Gson; 2 import com.google.gson.GsonBuilder; 3 import com.google.gson.JsonParser; 4 public class GaeInfoServlet { 5 private Gson gson = new GsonBuilder() .setPrettyPrinting() .create() 6 String parseJson(String json) { 7 JsonParser jp = new JsonParser(); 8 return gson.toJson(jp.parse(json)); } }

111:13

"FQN": "com.google.gson.JsonParser.parse", "arguments": [ {"value": "json", "type": "String"} ], "caller": "GaeInfoServlet.parseJson(String)"

(a) Java API call metadata extraction

"FQN": "yaml.safe_load", "arguments": [ {"value": "secret", "kind": "positional"} ], "caller": "@ROOT"

1 import yaml 2 from django.urls import reverse as rev 3 yaml.safe_load(secret) 4 class BaseWallpostAdmin: 5 def reaction_link(self, obj): 6 url = rev( 'admin', args=(obj.id, ) )

"FQN": "django.urls.reverse", "arguments": [ {"value": "'admin'", "kind": "positional"}, {"value": "(obj.id, )", "kind": "keyword", "key": "args"} ], "caller": "BaseWallpostAdmin.reaction_link"

(b) Python API call metadata extraction

Fig. 4. Examples of API call metadata extraction for Java and Python.

implementation. For each argument, it further distinguishes positional and keyword arguments and records the keyword name when present. This syntactic information is useful for comparing Python API calls because keyword names explicitly identify argument roles. For example, the call rev(...) in the sixth statement contains a positional argument ’admin’ and a keyword argument args=(obj.id, ). Figure 4(b) shows the metadata extracted for the two API calls. 3.4

Phase 3: Candidate Update Instance Mining

Design. Using the API call metadata extracted in Phase 2, Phase 3 mines candidate update instances associated with each dependency version transition identified in Phase 1. The key intuition is that, when a client adapts its code to an updated dependency, an API call removed from the old code may be replaced by a related API call added to the new code within the same caller context. Bridge therefore first identifies changed API calls belonging to the updated library and then matches removed and added calls based on their FQN and argument similarities. At this stage, these similarities provide only client-side replacement signals and the mined candidate update instances are further validated using library-side evidence in Phase 4. API Call Change Detection. The first challenge is to determine which API calls belong to the updated library. A Library and its API FQNs are not directly linked, because a published library may expose one or more importable prefixes that differ from its name. Bridge therefore constructs a mapping from each updated library to its importable top-level prefixes. Specifically, it downloads the latest available artifact of each updated library and extracts top-level import prefixes from the artifact. For Java, these prefixes are derived from class file paths in JARs, whereas for Python they are derived from importable Python module paths in wheels. Using the latest artifact avoids downloading every historical release and assumes that a library’s top-level import prefixes remain sufficiently stable across releases for identifying calls belonging to that library. Bridge associates each changed source file with dependency updates occurred in its nearest configuration file. It then uses the import prefix mapping to identify API calls belonging to each updated library and groups calls by library and caller context. Within each group, Bridge compares the calls extracted from the old and new blobs and retains calls whose FQNs occur exclusively on one side. Calls appearing only in the old blob and new blob form 𝐶𝑜 and 𝐶𝑛 , respectively. Calls with J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

111:14

Kai Gao, Yu Sun, and Chang-ai Sun

the same FQN on both sides are excluded even when their arguments differ. This conservative design focuses the mining process on replacements between different APIs and avoids interpreting regular argument changes, overloaded Java calls, or changes enabled by Python’s flexible argument passing as API replacements. Each API call change record is represented as (𝑐, 𝑓 , 𝑙, 𝑣𝑜 , 𝑣𝑛 , 𝑐𝑡𝑥, 𝑏𝑜 , 𝑏𝑛 , 𝐶𝑜 , 𝐶𝑛 ), where 𝑐 denotes the update commit, 𝑓 the source file path, 𝑙 the updated library, 𝑣𝑜 and 𝑣𝑛 the old and new library versions, 𝑐𝑡𝑥 the caller context, 𝑏𝑜 and 𝑏𝑛 the old and new blob hashes, and 𝐶𝑜 and 𝐶𝑛 the removed and added API calls, respectively. Threshold-Based Bipartite Matching. An API call change record may contain multiple removed and added calls within the same caller context. Bridge models all possible correspondences between 𝐶𝑜 and 𝐶𝑛 as a weighted bipartite graph, where each edge (𝑐𝑜 , 𝑐𝑛 ) represents a possible replacement and is assigned a language-specific similarity score computed from the calls’ FQN and actual arguments. As formalized in Algorithm 3, Bridge computes the similarity of every removed–added call pair and discards edges whose scores do not exceed a language-specific threshold 𝜃 . It then sorts the remaining edges by descending similarity and greedily selects edges subject to a one-to-one constraint. The selected edges form candidate update instances and are passed to Phase 4 for library-side resolution and validation. Algorithm 3: Threshold-based Bipartite Matching Input: An API call change record 𝑟 = (𝑐, 𝑓 , 𝑙, 𝑣𝑜 , 𝑣𝑛 , 𝑐𝑡𝑥, 𝑏𝑜 , 𝑏𝑛 , 𝐶𝑜 , 𝐶𝑛 ), similarity function 𝑆, threshold 𝜃 Output: Candidate update instances I 1 𝐸 ← ∅ 2 for 𝑖 ← 1 to |𝐶𝑜 | do // Pairwise API call similarity calculation 3 for 𝑗 ← 1 to |𝐶𝑛 | do 4 𝑠 ← 𝑆 (𝐶𝑜 [𝑖], 𝐶𝑛 [ 𝑗]) 5 if 𝑠 > 𝜃 then // Keep edges above the similarity threshold 6 𝐸 ← 𝐸 ∪ {(𝑖, 𝑗, 𝑠)} 7 Sort 𝐸 by descending similarity 𝑠, then ascending old API call index 𝑖 8 I ← ∅, 𝑈𝑜 ← ∅, 𝑈𝑛 ← ∅ 9 for (𝑖, 𝑗, 𝑠) ∈ 𝐸 do 10 if 𝑖 ∉ 𝑈𝑜 and 𝑗 ∉ 𝑈𝑛 then // Enforce one-to-one matching 11 I ← I ∪ {(𝑙, 𝑣𝑜 , 𝐶𝑜 [𝑖], 𝑣𝑛 , 𝐶𝑛 [ 𝑗])} 12 𝑈𝑜 ← 𝑈𝑜 ∪ {𝑖} 13 𝑈𝑛 ← 𝑈𝑛 ∪ { 𝑗 } 14 return I Implementation for Java. Table 3 summarizes the API call changes detected before bipartite matching. For Java, Bridge identifies 342,018 API call change records from 42,885 update commits (4.1% of those collected in Phase 1) and 222,243 unique code blobs. These records involve 5,352 libraries, 31,084 library versions, and 138,396 unique API FQNs. To measure the similarity between two Java API calls, Bridge uses three signals: Class Name Similarity (𝐶𝑆), Method Name Similarity (𝑀𝑆), and Argument Similarity (𝐴𝑆 𝑗 ). For 𝐶𝑆 and 𝑀𝑆, identifiers are tokenized according to CamelCase and snake_case conventions, and token overlap is measured using a Jaccard-style score. To reduce high similarity between lexically related but semantically contrasting names, Bridge applies conservative rules that set name similarity to zero for patterns such as different leading action verbs (e.g., get versus set), incompatible primitive J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

Bridge : Automatically Mining Ecosystem-Scale API Update Mappings and Client Update Instances

111:15

Table 3. Statistics of API call changes detected before bipartite matching.

Language

# Records

# Commits

# Blobs

# Libraries

# Versions

# API FQNs

Java Python

342,018 172,999

42,885 31,379

222,243 125,861

5,352 2,641

31,084 15,540

138,396 36,804

type tokens, different logging levels, and mismatched negation markers. For common factory-style method names such as of, from, and getInstance, which carry little replacement information by themselves, Bridge uses the class name as the method name signal. For 𝐴𝑆 𝑗 , Bridge compares the ordered lists of actual argument expressions using the Levenshtein ratio. The resulting Java API Call Similarity (𝐽𝐴𝐶𝑆) combines the three signals as follows: 𝐽𝐴𝐶𝑆 (𝑐𝑜 , 𝑐𝑛 ) = 𝑤𝐶𝑆 × 𝐶𝑆 (𝑐𝑜 , 𝑐𝑛 ) + 𝑤 𝑀𝑆 × 𝑀𝑆 (𝑐𝑜 , 𝑐𝑛 ) + 𝑤 𝐴𝑆 𝑗 × 𝐴𝑆 𝑗 (𝑐𝑜 , 𝑐𝑛 )

(1)

Implementation for Python. As shown in Table 3, Bridge identifies 172,999 Python API call change records from 31,379 update commits (4.2% of those collected in Phase 1) and 125,861 unique code blobs. These records involve 2,641 libraries, 15,540 library versions, and 36,804 unique API FQNs. Because Phase 2 does not infer receiver or argument types, Bridge measures Python API call similarity using FQN Similarity (𝐹𝑆) and Argument Similarity (𝐴𝑆𝑝 ). For 𝐹𝑆, Bridge primarily compares the final component of each FQN, corresponding to the function or method name. Inspection of API mappings in prior library evolution datasets [7, 74, 81] suggests that replacement APIs may express related functionality using different naming conventions or abbreviations. Accordingly, Bridge first normalizes names by removing underscores and converting characters to lowercase, such that arg_max and argmax receive full similarity. It also treats a compact name as equivalent to an expanded name when the compact form consists of the initials of the expanded tokens, as in mse and mean_squared_error. Otherwise, names are tokenized according to snake_case and CamelCase conventions, and token overlap is measured using a Jaccard-style score. For 𝐴𝑆𝑝 , Bridge compares arguments according to Python’s argument passing mechanisms. Specifically, Python allows four types of arguments [15]: positional arguments (e.g., arg), variadic positional arguments (e.g., *args), keyword arguments (e.g., mode="fast"), and variadic keyword arguments (e.g., **kwargs). Positional arguments and variadic positional arguments are compared as ordered sequences using a weighted edit distance, where insertion and deletion have a cost of one and substitution has a cost of two. Their contribution is computed as the total length of the two sequences minus their edit distance. Keyword arguments are compared using both keys and values: matching keys contribute to the score, while matching values provide additional evidence. Variadic keyword arguments are treated as sets of unpacked argument expressions, and their contribution is the size of their exact intersection. The contributions from all the four types of arguments are summed and normalized by the total number of arguments in the two calls to obtain 𝐴𝑆𝑝 . For example, consider f(x, y, mode="fast") and g(z, y, mode="safe"). Their positional argument sequences, [x, y] and [z, y], have an edit distance of 2 and therefore contribute |[𝑥, 𝑦] | + | [𝑧, 𝑦] | − 2 = 2. The keyword argument mode contributes one additional unit because its key matches, whereas its values provide no additional contribution because "fast" and "safe" differ. The three matched argument units are normalized by the six actual arguments in the two calls, giving 𝐴𝑆𝑝 = (2 + 1)/6 = 0.5. J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

111:16

Kai Gao, Yu Sun, and Chang-ai Sun

The resulting Python API Call Similarity (𝑃𝐴𝐶𝑆) combines FQN and argument similarities as follows: 𝑃𝐴𝐶𝑆 (𝑐𝑜 , 𝑐𝑛 ) = 𝑤 𝐹𝑆 × 𝐹𝑆 (𝑐𝑜 , 𝑐𝑛 ) + 𝑤 𝐴𝑆𝑝 × 𝐴𝑆𝑝 (𝑐𝑜 , 𝑐𝑛 ) (2) 3.5

Phase 4: Mapping Resolution and Validation

Design. Phase 3 generates candidate update instances by similarity-based matching of client-side API call changes, but these similarity signals alone are insufficient to validate the candidates. Phase 4 therefore resolves the API signatures involved in each candidate and validates the candidate using library-side API evolution evidence. Candidate update instances mined in Phase 3 may contain false positives for two main reasons. First, Phase 3 associates API calls with updated libraries through import prefixes, but different libraries may expose the same prefixes, causing calls to be incorrectly attributed to the updated library. Second, similar API calls does not necessarily indicate an API replacement. Calls with similar FQNs and arguments may provide different functionality, while, particularly in Python, calls with different FQNs may resolve to the same underlying API through re-exports. API Signature Resolution. To ensure that the paired calls belong to the updated library and are available in the involved versions, Bridge resolves their API signatures against the library artifacts corresponding to the version transition. As shown in Algorithm 4, for each candidate (𝑙, 𝑣𝑜 , 𝑐𝑜 , 𝑣𝑛 , 𝑐𝑛 ), Bridge resolves the call 𝑐𝑜 against version 𝑣𝑜 of library 𝑙 and the call 𝑐𝑛 against version 𝑣𝑛 . If either call cannot be resolved to an API exposed by its respective library artifact, the candidate is discarded. This version-specific resolution can filter candidates incorrectly attributed to the updated library. Removal and Deprecation Validation. Successful signature resolution alone is insufficient to establish that a candidate represents an update instance. Bridge therefore additionally requires evidence that the legacy API is removed from or deprecated in the new library version. To obtain this evidence, Bridge attempts to resolve the call 𝑐𝑜 against the new library version. If 𝑐𝑜 can no longer be resolved, Bridge treats this absence as evidence that the legacy API has been removed. If 𝑐𝑜 remains resolvable but the resolved API carries deprecation evidence, Bridge treats the candidate as supported by deprecation. Otherwise, the candidate is discarded. This conservative criterion favors precision over exhaustive coverage and intentionally excludes replacements for which the legacy API remains available without detectable deprecation evidence. For each retained candidate, the resolved legacy and replacement API signatures 𝑎𝑜 and 𝑎𝑛 form the API update mapping (𝑙, 𝑎𝑜 , 𝑎𝑛 ). Associating this mapping with the version transition identified in Phase 1 yields the API update pair (𝑙, 𝑣𝑜 , 𝑎𝑜 , 𝑣𝑛 , 𝑎𝑛 ), while the client-side call change forms the validated client update instance. Phase 4 therefore connects API update mappings, version transitions, and client update instances. Each language-specific implementation provides two capabilities for this validation: API signature resolution and deprecation checking. Implementation for Java. API Signature Resolution. As defined in Section 2.1, a Java API signature consists of an FQN and its formal parameter types [59]. Because Java supports method overloading, an FQN may resolve to multiple API signatures. Given an API call and a library version, Bridge downloads the sources JAR for that version and resolves the call against method definitions in its Java and Scala source files. The resolver first locates the source file exposing the call’s FQN, parses it with tree-sitter, and searches for method definitions with the same FQN. It also follows class inheritance when the called method may be inherited from a superclass or implemented interface defined within the library. Candidate definitions are filtered based on whether their numbers of formal parameters are compatible with the actual arguments. When multiple signatures remain, Bridge uses the argument information extracted in Phase 2 to identify the most plausible signature. Specifically, it compares the declared types of the actual arguments J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

Bridge : Automatically Mining Ecosystem-Scale API Update Mappings and Client Update Instances

111:17

Algorithm 4: Mapping Resolution and Validation Input: Candidate update instances I Output: Validated update instances V, mappings M, and update pairs P 1 V, M, P ← ∅ 2 for 𝑟 = (𝑙, 𝑣 𝑜 , 𝑐 𝑜 , 𝑣 𝑛 , 𝑐 𝑛 ) ∈ I do 3 𝑎𝑜 ← resolve_API_signature(𝑙, 𝑣𝑜 , 𝑐𝑜 ) 4 if 𝑎𝑜 = ∅ then // The old call does not resolve to an API in the old library version 5 continue 6 𝑎𝑛 ← resolve_API_signature(𝑙, 𝑣𝑛 , 𝑐𝑛 ) 7 if 𝑎𝑛 = ∅ then // The new call does not resolve to an API in the new library version 8 continue 9 𝑎𝑜𝑛 ← resolve_API_signature(𝑙, 𝑣𝑛 , 𝑐𝑜 ) 10 if 𝑎𝑜𝑛 = ∅ or is_deprecated(𝑎𝑜𝑛 ) then // The legacy API is removed or deprecated in the new library version 11 V ← V ∪ {𝑟 } 12 M ← M ∪ {(𝑙, 𝑎𝑜 , 𝑎𝑛 )} 13 P ← P ∪ {(𝑙, 𝑣𝑜 , 𝑎𝑜 , 𝑣𝑛 , 𝑎𝑛 )} 14 return V, M, P

with the formal parameter types of each candidate signature and selects the signature with the highest type compatibility. Deprecation Checking. For a resolved API, Bridge checks for deprecation evidence following common deprecation practices in Java projects. Specifically, it recognizes the @Deprecated annotation and the @deprecated Javadoc tag. Deprecation is checked at both the method and enclosing-class levels because an API may become deprecated when its declaring class is deprecated. A Java candidate is retained only when the old call resolves to an API in the old version, the new call resolves to an API in the new version, and the legacy API is removed from or identified as deprecated in the new version. Implementation for Python. API Signature Resolution. For Python, Bridge uses the FQN as the API signature because Python does not use formal parameter types to distinguish overloaded methods. Given an API call and a library version, Bridge downloads the wheel for that version and resolves the call against APIs exposed in its Python files. The resolver first identifies the Python file exposing the API by performing longest-prefix matching between the call’s FQN and Python file paths in the wheel. It then parses the matched file and determines whether the remaining FQN components resolve to a function, class, or class member defined in the file. If an FQN component is imported from another Python file, the resolver follows the import and repeats the resolution procedure on the target file. Deprecation Checking. For a resolved API, Bridge searches its definition for deprecation evidence. Prior work [75] shows that Python libraries deprecate APIs through diverse mechanisms, including decorators, warning messages, and documentation text. Following this observation, Bridge examines decorators of the API’s definition and searches its docstrings and string literals for deprecation cues, including “deprecated”, “removed”, “legacy”, “renamed”, and “moved”. A Python candidate is retained only when the old call resolves to an API in the old version, the new call resolves to an API in the new version, and the legacy API is removed from or identified as deprecated in the new version. J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

111:18

4

Kai Gao, Yu Sun, and Chang-ai Sun

Evaluation

We evaluate Bridge with respect to its accuracy of mining client update instances, the impact of its key design choices, the characteristics of the mined dataset, and the utility enabled by the dataset. Specifically, we investigate the following research questions (RQs): • RQ1: How accurately does Bridge mine client update instances from API call changes? We evaluate the precision, recall, and F1 score of the client update instances produced by Phases 3 and 4 against a manually annotated ground truth dataset. • RQ2: How do similarity-based matching and library-side validation affect the effectiveness of Bridge? We analyze the sensitivity of Bridge to alternative similarity weights and matching thresholds and quantify the contribution of Phase 4 through an ablation study. • RQ3: What are the scale and distributional characteristics of the dataset mined by Bridge? We characterize the mined API update mappings, API update pairs, and client update instances across libraries and versions, with particular attention to how mappings and instances are distributed. • RQ4: What does the mined dataset reveal about LLM-based replacement API recommendation? As one example application of the dataset, we evaluate four large language models (LLMs) on replacement API recommendation, a key step in automated library updates, and investigate how recommendation performance relates to the frequency of API update mappings in client updates. 4.1

Ground Truth Dataset

RQ1 and RQ2 aim to evaluate the effectiveness of Bridge in mining client update instances, particularly its similarity-based candidate matching in Phase 3 and library-side validation in Phase 4. We therefore construct a manually annotated ground truth dataset from the API call change records identified in Phase 3. Starting from these records allows us to evaluate the two key designs that determine which API call change pairs are retained as client update instances: Phase 3 matches removed and added calls to generate candidate update instances, while Phase 4 resolves their API signatures and validates the candidates using library-side API evolution evidence. Sampling. Naively sampling from all API call change records could cause frequently updated libraries and repeatedly changed APIs to dominate the ground truth dataset. We therefore adopt a two-stage sampling strategy to increase diversity across both libraries and API calls. For each language, we first sample 100 libraries with probabilities proportional to their numbers of update commits, giving libraries with more observed update activity a greater probability of selection while maintaining coverage across libraries. For each selected library, we then randomly sample API call change records and retain a record only if its old-side API FQN has not been previously selected for that library. We continue sampling until at least ten distinct old-side API FQNs are covered or no additional records remain for the library. This procedure reduces repeated observations of frequently changed APIs and increases the diversity of API call changes represented in the ground truth. Accordingly, the ground truth is designed to evaluate Bridge across diverse libraries and API calls rather than to estimate population-weighted accuracy over all API call change records. The resulting ground truth dataset contains 638 Java and 609 Python API call change records. Annotation. The first two authors independently inspect each sampled record and label all possible one-to-one pairs between its old-side and new-side API calls. A pair is labeled as a genuine client update instance only when external evidence supports that the new-side API replaces the old-side API under the observed library version transition. The annotators seek evidence from J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

Bridge : Automatically Mining Ecosystem-Scale API Update Mappings and Client Update Instances

111:19

Table 4. Performance of Bridge on the ground truth dataset. GT, TP, FP, and FN denote the numbers of annotated instances, true positives, false positives, and false negatives, respectively. Precision, recall, and F1 score are reported as percentages.

Language Records GT Predicted TP FP FN Precision Recall F1 score Java Python

638 344 609 242

333 305 172 155

28 17

39 87

91.6 90.1

88.7 64.0

90.1 74.9

official API documentation, release notes and upgrade guides, and the library’s source repository; when necessary, they additionally consult Stack Overflow discussions. For each positive instance, they record the supporting evidence together with the legacy and replacement API signatures. We compute inter-rater agreement over all 2,283 Java and 1,988 Python API call pairs, with genuine client update instances labeled as positive and all other pairs as negative. The two annotators achieve a Cohen’s 𝜅 of 0.92, indicating almost perfect agreement. They subsequently discuss all disagreements and determine the final annotations by consensus. The resulting ground truth contains 344 Java and 242 Python client update instances. 4.2

Mining Effectiveness (RQ1)

4.2.1 Approach. We evaluate the effectiveness of Bridge in mining client update instances from API call changes by running Bridge on the ground truth dataset and comparing the mined instances with the manual annotations. For Java, we assign equal weights of 1/3 to 𝐶𝑆, 𝑀𝑆, and 𝐴𝑆 𝑗 and set the similarity threshold to 0.45. For Python, we assign equal weights of 0.5 to 𝐹𝑆 and 𝐴𝑆𝑝 and set the threshold to 0.35. RQ2 examines the sensitivity of these parameter choices and the contribution of library-side validation. A mined instance is considered a true positive only when its resolved legacy and replacement API signatures match those of an annotated client update instance. 4.2.2 Results. Overall effectiveness. Table 4 reports the performance of Bridge on the ground truth dataset. For Java, Bridge correctly identifies 305 of the 344 annotated instances, with 28 false positives and 39 false negatives, achieving 91.6% precision, 88.7% recall, and a 90.1% F1 score. For Python, Bridge correctly identifies 155 of the 242 annotated instances, with 17 false positives and 87 false negatives, achieving 90.1% precision, 64.0% recall, and a 74.9% F1 score. Thus, Bridge achieves precision above 90% for both languages, consistent with our objective of favoring precision when automatically constructing a reusable dataset, while achieving substantially lower recall for Python than for Java. Error Analysis. To understand the mining errors, we manually inspect every false positive and false negative and classify their primary causes. False Positive Analysis. Phase 4 verifies whether the calls in a candidate can be resolved to APIs in the involved library versions and whether the resolved legacy API is removed from or identified as deprecated in the new version. These conditions establish the availability and evolution status of the involved APIs, but do not necessarily establish a replacement relation between them. Consequently, an incorrect candidate produced by similarity-based matching in Phase 3 may still be retained through either the deprecation path, where the legacy API remains available but is identified as deprecated, or the removal path, where the legacy API can no longer be resolved in the new version. Of the 28 Java false positives, 4 (14.3%) are retained through the deprecation path and 24 (85.7%) through the removal path. In contrast, 13 (76.5%) of the 17 Python false positives are retained through the deprecation path, while only 4 (23.5%) are retained through the removal path. The prevalence of the deprecation path among Python false positives mainly stems from the permissive J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

111:20

Kai Gao, Yu Sun, and Chang-ai Sun

deprecation checking required to accommodate diverse Python deprecation practices. Specifically, Bridge examines decorators, docstrings, and string literals within the resolved API definition for deprecation cues. While this strategy captures diverse forms of deprecation evidence, unrelated text containing such cues may be incorrectly interpreted as deprecation evidence, allowing an incorrect candidate to survive validation. False Negative Analysis. False negatives arise from three main sources corresponding to similarity-based matching and library-side validation. First, an annotated instance may not exceed the similarity threshold and is therefore not selected as a candidate in Phase 3. Second, Phase 4 may fail to resolve one or both calls in a candidate to APIs in the involved library versions. Third, both calls may be resolved successfully, but the resolved legacy API remains available in the new version without deprecation evidence recognized by Bridge. For Java, 16 (41.0%) of the 39 false negatives have similarity scores that do not exceed the selected threshold of 0.45 and are therefore not selected as candidates in Phase 3. Another 22 (56.4%) result from failures to resolve one or both calls in Phase 4: 12 involve APIs inherited from classes defined outside the library, four involve methods generated by annotation processors, and six involve unsupported source constructs or unexpected source JAR layouts. The remaining false negative results from deprecation evidence not recognized by Bridge: the legacy API remains resolvable in the new version, while its deprecation is documented only in an issue comment in the library’s source repository3 . For Python, 22 (25.3%) of the 87 false negatives have similarity scores that do not exceed the selected threshold of 0.35 and are therefore not selected as candidates in Phase 3. Another 51 (58.6%) result from failures to resolve one or both calls in Phase 4: 31 involve an unavailable wheel for at least one version, ten involve APIs exposed only at runtime, seven involve APIs defined in an external library, and three involve APIs defined in a binary module. The remaining 14 (16.1%) result from deprecation evidence not recognized by Bridge because the involved libraries use deprecation mechanisms outside those supported by our checker. For example, PyYAML communicates the deprecation of certain uses of yaml.load through runtime warnings issued by a dedicated helper function outside the API definition4 . The definition-level checker therefore cannot capture this evidence. These results indicate that the lower Python recall primarily stems from API resolution and deprecation-checking limitations rather than similarity-based matching alone. Answer to RQ1: Bridge achieves precision, recall, and F1 scores of 91.6%, 88.7%, and 90.1% for Java, and 90.1%, 64.0%, and 74.9% for Python, respectively. The lower Python recall mainly results from limitations in API signature resolution and deprecation checking. Overall, precision above 90% for both languages demonstrates that Bridge can mine client update instances from API call changes with high precision. 4.3

Design Analysis (RQ2)

4.3.1 Approach. We analyze two key design choices that determine which API call changes are retained as client update instances: the similarity-based matching used to generate candidates in Phase 3 and the library-side validation performed in Phase 4. Weight Sensitivity. We enumerate positive weight configurations in increments of 0.1 that sum to one, producing 36 configurations for Java and nine for Python; we additionally evaluate the equal Java weights of 1/3 used in RQ1. For each configuration, we conduct grouped 5-fold cross-validation, keeping all possible call pairs from the same API call change record in the same fold. In each round, 3 https://github.com/jpmml/jpmml-evaluator/issues/54#issuecomment-313649349 4 https://github.com/yaml/pyyaml/blob/0cedb2a0697b2bc49e4f3841b8d4590b6b15657e/lib/yaml/__init__.py#L109

J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

Bridge : Automatically Mining Ecosystem-Scale API Update Mappings and Client Update Instances

0.888 0.8 ±0.069

0.82

0.6 0.887 0.897 0.881

0.890

0.885 0.891 0.899 0.885 0.5 ±0.056 ±0.065 ±0.062 ±0.062

0.885

0.888 0.883 0.896 0.882 0.885 0.4 ±0.052 ±0.063 ±0.053 ±0.065 ±0.064

0.880

0.883 0.892 0.889 0.898 0.883 0.879 0.3 ±0.049 ±0.049 ±0.053 ±0.056 ±0.067 ±0.060

0.875

0.888 0.891 0.891 0.883 0.884 0.872 0.2 0.871 ±0.059 ±0.050 ±0.051 ±0.055 ±0.060 ±0.060 ±0.062

0.870

0.871 0.867 0.885 0.882 0.877 0.884 0.882 0.878 0.1 ±0.062 ±0.059 ±0.050 ±0.053 ±0.065 ±0.062 ±0.060 ±0.058 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8

Weight of CS

0.80 0.78

Mean F1 Score

0.895

Mean F1 Score

0.891 0.876 0.7 ±0.067 ±0.074 ±0.063 ±0.061 ±0.065

Weight of MS

111:21

0.76 0.74

0.726 0.727 0.730

0.733 0.731 0.737

0.72 ±0.040 ±0.042 ±0.044 ±0.045 ±0.044 0.70

±0.045

0.724 ±0.065

0.734 0.734 ±0.072 ±0.072

0.68 0.66 0.1

± one fold SD 0.2 0.3

0.4

0.5

0.6

Weight of FS

0.7

0.8

0.9

Fig. 5. Weight sensitivity for Java (left) and Python (right). Each value is the mean F1 score across five held-out folds, with its standard deviation. For Java, the argument similarity weight is 1 − 𝑤𝐶𝑆 − 𝑤 𝑀𝑆 ; the equal configuration is reported in the text because it does not lie on the 0.1 grid. For Python, the argument similarity weight is 1 − 𝑤 𝐹𝑆 .

we select the threshold between 0 and 1, in increments of 0.05, that maximizes the F1 score on the other four folds and then measure precision, recall, and F1 score on the held-out fold. We report the mean and standard deviation across the five folds. Threshold Sensitivity. We fix the equal weights used in RQ1 and vary the matching threshold from 0 to 0.95 in increments of 0.05. At each threshold, we calculate the precision, recall, and F1 score. This analysis quantifies the precision–recall tradeoff of similarity-based candidate matching and motivates the selected thresholds of 0.45 for Java and 0.35 for Python. Phase 4 Ablation. Phase 4 resolves the calls in each candidate against the involved library versions and retains only candidates for which the resolved legacy API is removed from or identified as deprecated in the new version. While this library-side validation filters false candidates produced by similarity-based matching, failures in API signature resolution or deprecation checking may also discard genuine client update instances. To quantify this tradeoff, we repeat the threshold analysis without Phase 4 and treat every candidate generated by Phase 3 as a client update instance. We compare the resulting precision, recall, and F1 score with those of the complete framework across thresholds and report the comparison at the thresholds selected in RQ1. 4.3.2 Results. Weight Sensitivity. Figure 5 shows that the similarity weights have a limited effect on the F1 score. For Java, the mean F1 score ranges from 86.7% to 89.9% across the 37 configurations, a difference of 3.2 percentage points. The equal configuration obtains the highest mean F1 score of 89.9% (SD = 5.5 percentage points). For Python, the mean F1 score ranges from 72.4% to 73.7%, a difference of only 1.3 percentage points. The equal configuration reaches a mean F1 score of 73.1% (SD = 4.4 percentage points), only 0.6 percentage points below the highest value of 73.7%. These results indicate that similarity-based matching is not highly sensitive to the weight configuration and support equal weighting as a simple and uniform choice across languages. Threshold Sensitivity. The solid curves in Figure 6 show how the matching threshold controls the tradeoff between precision and recall. For Java, increasing the threshold from 0 to 0.45 raises precision from 84.0% to 91.6%, while decreasing recall from 91.3% to 88.7%. The selected threshold of 0.45 yields the highest F1 score of 90.1%. For Python, increasing the threshold from 0 to 0.35 raises precision from 80.7% to 90.1%, while recall decreases from 67.4% to 64.0%. Although the F1 score is J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

Metric value

111:22

1.0 0.9 0.8 0.7 0.6 0.5 0.4 0.3 0.2 0.1 0.0

Kai Gao, Yu Sun, and Chang-ai Sun

Precision

Precision with Phase 4 Precision without Phase 4 0.0 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9

1.0 0.9 0.8 0.7 0.6 0.5 0.4 0.3 0.2 0.1 0.0

Metric value

Threshold j

1.0 0.9 0.8 0.7 0.6 0.5 0.4 0.3 0.2 0.1 0.0

Precision

Precision with Phase 4 Precision without Phase 4 0.0 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9

Recall

Recall with Phase 4 Recall without Phase 4 0.0 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9

1.0 0.9 0.8 0.7 0.6 0.5 0.4 0.3 0.2 0.1 0.0

Threshold j

1.0 0.9 0.8 0.7 0.6 0.5 0.4 0.3 0.2 0.1 0.0

Threshold p

Recall

Recall with Phase 4 Recall without Phase 4 0.0 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9

Threshold p

F1 Score

F1 Score with Phase 4 F1 Score without Phase 4 0.0 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9

Threshold j

1.0 0.9 0.8 0.7 0.6 0.5 0.4 0.3 0.2 0.1 0.0

F1 Score

F1 Score with Phase 4 F1 Score without Phase 4 0.0 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9

Threshold p

Fig. 6. Threshold sensitivity and Phase 4 ablation for Java (top) and Python (bottom). Solid lines show the complete framework, while dashed lines show the framework without Phase 4.

Table 5. Phase 4 ablation at the selected thresholds (0.45 for Java and 0.35 for Python).

Precision (%)

Java Recall (%)

F1 (%)

Precision (%)

Python Recall (%)

F1 (%)

91.6 51.3 ↑ 40.3

88.7 95.3 ↓ 6.7

90.1 66.7 ↑ 23.4

90.1 46.8 ↑ 43.3

64.0 90.9 ↓ 26.9

74.9 61.8 ↑ 13.1

Phase 4 With Phase 4 Without Phase 4 Δ

highest at 0.30, selecting 0.35 increases precision by 2.8 percentage points while reducing recall by 1.7 points and F1 by only 0.1 points. We therefore select 0.35 because precision is particularly important when automatically mined instances are released as a reusable dataset. Ablation of Phase 4. Table 5 reports the ablation results at the selected thresholds, while the dashed curves in Figure 6 show the effect across all thresholds. For Java, library-side validation increases precision from 51.3% to 91.6%, an improvement of 40.3 percentage points, while recall decreases from 95.3% to 88.7%. Consequently, the F1 score increases by 23.4 points, from 66.7% to 90.1%. For Python, library-side validation increases precision from 46.8% to 90.1%, an improvement of 43.3 percentage points, while recall decreases from 90.9% to 64.0%. The larger recall reduction for Python mainly stems from failures in API signature resolution and deprecation checking, as identified in the RQ1 false negative analysis. Nevertheless, the F1 score increases by 13.1 points, from 61.8% to 74.9%. These results demonstrate that library-side validation substantially improves the precision of similarity-based candidate matching for both languages, although this improvement comes with a larger recall reduction for Python. J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

Bridge : Automatically Mining Ecosystem-Scale API Update Mappings and Client Update Instances

111:23

Table 6. Scale of the resulting dataset. Releases are distinct (library, version) combinations, version transitions are distinct (library, old version, new version) combinations.

Language # Libraries # Releases # Version Transitions # Mappings # Pairs # Instances # Commits Java Python

2,557 999

12,165 4,908

10,637 5,190

18,900 4,456

35,532 11,393

381,661 277,259

17,266 7,850

Answer to RQ2: Similarity weights have limited impact on the F1 score and the matching threshold controls the precision–recall tradeoff of similarity-based candidate matching. At the selected thresholds, library-side validation improves precision by 40.3 percentage points for Java and 43.3 points for Python, demonstrating its critical role in achieving high-precision client update instance mining, although with a larger recall reduction for Python. 4.4

Dataset Characteristics (RQ3)

4.4.1 Approach. We apply the configured Bridge framework to the complete API call change record collection described in Section 3.4 and characterize the resulting library update dataset at multiple granularities. We first measure its scale in terms of libraries, releases, version transitions, API update mappings, API update pairs, client update instances, and distinct update commits. These units capture complementary aspects of the dataset: mappings represent API replacement relations, pairs associate mappings with version transitions, and instances capture the client-side API call changes in which the replacements are observed. We then report the numbers of client update instances retained through the removal and deprecation validation paths in Phase 4. Finally, we analyze the distributions of update commits, API update mappings, and client update instances across libraries, as well as the distribution of client update instances across mappings. 4.4.2 Results. Dataset Scale. Table 6 summarizes the dataset mined from the complete collection. Phase 3 identifies 686,608 Java and 561,018 Python candidate update instances from 342,018 Java and 172,999 Python API call change records. Phase 4 discards 238,403 (34.7%) Java and 85,926 (15.3%) Python candidates because one or both calls cannot be resolved to APIs in the involved library versions, and another 66,544 (9.7%) Java and 197,833 (35.3%) Python candidates because the resolved legacy API is neither removed from nor identified as deprecated in the new version. After library-side validation, Bridge retains 381,661 Java client update instances from 17,266 update commits, representing 35,532 API update pairs and 18,900 API update mappings across 10,637 version transitions of 2,557 libraries. For Python, Bridge retains 277,259 client update instances from 7,850 update commits, representing 11,393 API update pairs and 4,456 API update mappings across 5,190 version transitions of 999 libraries. Among the retained Java instances, 269,736 (70.7%) are retained through the deprecation path and 111,925 (29.3%) through the removal path. The distribution is reversed for Python: 48,419 (17.5%) are retained through the deprecation path and 228,840 (82.5%) through the removal path. Distribution of Mappings and Instances. Figure 7 shows the distributions of update commits, API update mappings, and client update instances across libraries, as well as client update instances across mappings. Across all four measures, both ecosystems exhibit highly skewed distributions, with most libraries or mappings accounting for relatively few observations and a small number accounting for substantially more. Commits per Library. Java and Python exhibit similar distributions of update commits across libraries. The median library appears in two distinct update commits, with an interquartile range of one to three for both languages. Approximately half of the libraries appear in only one update J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

Kai Gao, Yu Sun, and Chang-ai Sun

100

100

80

80

80

80

60 40 20 0

Java Python 100 101 102 103 (a) Update commits per library

60 40 20 0

Java Python

60 40 20

101 100 102 103 (b) Mappings per library

0

Java Python 100 101 102 103 104 105 (c) Instances per library

Mappings (%)

100 Libraries (%)

100 Libraries (%)

Libraries (%)

111:24

60 40 20 0

Java Python 100 101 102 103 104 (d) Instances per mapping

Fig. 7. Distributions of the resulting dataset. Each curve gives the percentage of libraries or mappings whose count is at most the corresponding x-axis value.

commit (49.0% for Java and 46.9% for Python), and 91.9% in both languages appear in at most ten update commits. At the other extreme, the Java library org.mockito:mockito-core appears in 1,549 update commits and the Python library django appears in 2,867 update commits, showing that a small number of libraries are represented by substantially more observed client updates. Mappings per Library. The median library contains two API update mappings in both languages, with an interquartile range of one to five for Java and one to three for Python. Overall, 37.5% of Java libraries and 49.1% of Python libraries contain only one API update mapping, while 87.4% and 93.2%, respectively, contain at most ten mappings. The distributions nevertheless have long tails: the Java library org.elasticsearch:elasticsearch contains 1,048 API update mappings, while the Python library tensorflow contains 361 API update mappings. Instances per Library. The median Java library appears in five client update instances, with an interquartile range of two to 17, whereas the median Python library appears in four, with an interquartile range of two to 11. Although 92.6% of Java libraries and 95.1% of Python libraries appears in at most 100 instances, the maxima reach 132,630 for the Java library junit:junit and 124,226 for the Python library wagtail. Thus, the hundreds of thousands of instances reported in Table 6 are highly unevenly distributed across libraries, with most libraries appearing in relatively few instances and a small number accounting for a large proportion of the dataset. Instances per Mapping. The median API update mapping appears in two client update instances in both languages, with interquartile ranges of one to four for Java and one to six for Python. Overall, 42.1% of Java mappings appear in only one client update instance and 89.0% in at most ten instances. For Python, 37.1% of mappings appear in only one instance and 84.4% in at most ten instances. At the other extreme, the most frequent Java mapping, from junit.framework.Assert.assertEquals(int, int) to org.junit.Assert.assertEquals(long, long), appears in 33,678 instances. The most frequent Python mapping, from django.core.urlresolvers.reverse to django.urls.reverse, appears in 58,780 instances. These results reveal a pronounced long-tail distribution of API update mappings: many mappings are observed in only one or a few client update instances, whereas a small number of recurrent mappings appear in thousands or even tens of thousands of instances. Answer to RQ3: Bridge mines 381,661 Java and 277,259 Python client update instances, representing 18,900 and 4,456 API update mappings across 2,557 and 999 libraries, respectively. The dataset exhibits highly skewed distributions across libraries and a pronounced long-tail distribution of API update mappings, with most mappings appearing in only a few client update instances and a small number appearing substantially more frequently. J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

Bridge : Automatically Mining Ecosystem-Scale API Update Mappings and Client Update Instances

4.5

111:25

Dataset Utility (RQ4)

4.5.1 Approach. The dataset mined by Bridge can support empirical studies of library evolution and the development and evaluation of automated library update techniques. As one example application, we use the dataset to evaluate LLMs on replacement API recommendation. Identifying the API that should replace a deprecated or removed API is a key step in automated library updates, yet the capability of current LLMs to perform this task remains unclear. The three connected units in the dataset support complementary parts of this evaluation: API update mappings provide reference replacements, API update pairs specify the applicable version transitions, and client update instances provide real-world call contexts. Moreover, the pronounced long-tail distribution identified in RQ3 enables us to examine how recommendation performance varies with the frequency of API update mappings in client update instances. We therefore investigate the overall recommendation accuracy, the effect of providing client call contexts, and the relationship between mapping frequency and recommendation performance. We conduct the evaluation under two input settings. The signature input is constructed from an API update pair and provides the library, old version, new version, and legacy API signature. The context input additionally provides focused client call context extracted from a client update instance. The context consists of relevant import statements and the legacy API call. For Java, the context additionally consists of variable declaration statements of the call’s receiver object and arguments. Evaluation Data. A legacy API can occasionally be paired with multiple replacement APIs in the mined dataset because clients may replace the same API differently depending on its usage context. We therefore group client update instances by library, old version, new version, and legacy API, and retain the most frequent replacement only when it accounts for more than half of the instances in the group. This strict majority requirement reduces ambiguity among alternative replacements observed for the same legacy API and version transition. We then sample one API update pair for each distinct API update mapping and, for the context input, one associated client update instance. This procedure produces 18,166 Java and 4,360 Python examples. The two input settings use identical mappings, version transitions, and reference replacements. Models and Prompts. We evaluate GPT-5.4, DeepSeek-V4-Pro, DeepSeek-V4-Flash, and GLM5.1. Listing 1 presents the shared prompt template. For the signature input, <CONTEXT_BLOCK> is omitted; for the context input, it contains the focused client call context described above. The <SIGNATURE_FORMAT> requires a FQN with parameter types for Java and a FQN for Python. We use zero temperature and a maximum output length of 128 tokens, and disable optional thinking mode for endpoints that expose it. SYSTEM You are an expert in library API evolution. Given a library version update and a legacy API, identify the API in the new library version that should replace the legacy API. Return exactly one JSON object and no additional text: {"replacement_api": "<API signature>"} The replacement must belong to the specified library and be available in the new version. If uncertain, return your single best recommendation. USER A project updates the following <LANGUAGE> library: Library: <LIBRARY> Old version: <OLD_VERSION> New version: <NEW_VERSION> J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

111:26

Kai Gao, Yu Sun, and Chang-ai Sun

Table 7. The recommendation accuracy across the four evaluated LLMs and two input settings. FQN and Full denote FQN accuracy and full signature accuracy, respectively.

Model

GPT-5.4 DeepSeek-V4-Pro DeepSeek-V4-Flash GLM-5.1

Java Signature Input Context Input FQN (%) Full (%) FQN (%) Full (%) 37.1 32.1 25.7 26.2

27.5 24.2 21.2 23.2

36.1 31.0 25.8 25.3

26.5 22.2 20.6 21.7

Python Signature Input Context Input FQN (%) FQN (%) 42.5 36.4 30.0 32.5

44.4 36.1 29.1 32.2

The following legacy API is deprecated or removed: <LEGACY_API> <CONTEXT_BLOCK> Recommend the replacement API in the new version and represent the replacement using <SIGNATURE_FORMAT>. Listing 1. Prompt template for replacement API recommendation. Text in angle brackets denotes an examplespecific placeholder.

Metrics. We use exact-match accuracy as the primary metric. For Python, a prediction is correct when its FQN exactly matches the reference. For Java, full signature accuracy additionally requires the exact formal parameter types. We also report the FQN accuracy for Java, which ignores the parameter types, to distinguish replacement API identification from overload selection. To compare the two input settings, we use McNemar’s exact test [49] on their paired correctness outcomes for the same API update mapping and version transition, and apply Holm correction [32] across the model and language comparisons. RQ3 reveals a pronounced long-tail distribution of API update mappings, with most mappings appearing in only a few client update instances and a small number appearing substantially more frequently. To examine how recommendation performance varies across this distribution, we analyze accuracy by mapping frequency, defined as the number of validated client update instances associated with an API update mapping in the Bridge dataset. We divide mappings into five frequency groups: one, two to five, six to ten, 11 to 100, and more than 100 instances. 4.5.2 Results. Overall Recommendation Accuracy. Table 7 reports the recommendation accuracy across the four evaluated LLMs and two input settings. GPT-5.4 achieves the highest accuracy in every language and input setting. For Java, the full signature accuracy ranges from 21.2% to 27.5% under the signature input and from 20.6% to 26.5% under the context input. For Python, the FQN accuracy ranges from 30.0% to 42.5% and from 29.1% to 44.4%, respectively. For Java, the FQN accuracy is 3.0 to 9.7 percentage points higher than full signature accuracy. Thus, some errors occur even when a model identifies the correct package, class, and method name because it predicts incorrect formal parameter types. Even when considering only FQNs, however, the highest accuracy reaches 37.1% for Java and 44.4% for Python. These results indicate that reliably identifying replacement APIs remains challenging for the evaluated LLMs. Effect of Client Call Context. Providing focused client call context does not consistently improve recommendation accuracy. For Java, the full signature accuracy decreases for all four models by 0.6 to 2.0 percentage points. The paired outcomes show that context changes predictions in both directions. For example, for GPT-5.4, context changes 959 incorrect predictions to correct ones but changes 1,145 correct predictions to incorrect ones. For Python, context increases GPT-5.4’s J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

Exact match accuracy (%)

Bridge : Automatically Mining Ecosystem-Scale API Update Mappings and Client Update Instances

90 80 70 60 50 40 30 20 10

GPT-5.4 90 80 70 60 50 40 30 20 10 2-5 6-10 11-100 >100 1

Java, Signature input

1

DeepSeek V4 Pro Java, Context input

2-5 6-10 11-100 >100

90 80 70 60 50 40 30 20 10

111:27

DeepSeek V4 Flash GLM-5.1 Python, Signature input Python, Context input 90 80 70 60 50 40 30 20 10 1 2-5 6-10 11-100 >100 1 2-5 6-10 11-100 >100

The number of instances per mapping

Fig. 8. Recommendation accuracy by mapping frequency. Java panels report full signature accuracy.

FQN accuracy by 1.8 percentage points, with 294 incorrect predictions becoming correct and 214 correct predictions becoming incorrect. After Holm correction, the decreases in Java full signature accuracy for all four models and the increase in Python FQN accuracy for GPT-5.4 are statistically significant at 𝛼 = 0.05, whereas the Python differences for the other three models are not. Overall, focused client call contexts can change recommendation outcomes, but the evaluated models do not benefit from it consistently. Recommendation Performance by Mapping Frequency. Figure 8 shows a strong association between mapping frequency and recommendation accuracy. Under the signature input, the accuracy ranges from 15.4% to 21.1% for Java and from 23.9% to 36.9% for Python among mappings appearing in only one client update instance. For mappings appearing in more than 100 instances, accuracy increases to 48.5%–55.8% for Java and 73.8%–79.4% for Python. The context input exhibits a similar pattern. Across the evaluated models, languages, and input settings, recommendation accuracy is substantially higher for frequently observed mappings than for mappings observed in only a few client update instances. This result connects the long-tail distribution identified in RQ3 with a practical challenge for replacement API recommendation: many mappings lie in the long tail where recommendation accuracy is substantially lower. Answer to RQ4: The best FQN accuracy reaches only 37.1% for Java and 44.4% for Python, and focused client call context provides no consistent improvement. More importantly, all evaluated models achieve substantially lower accuracy on sparsely observed mappings than on recurrent mappings, highlighting their limitations in reliably identifying replacements for the long tail of API updates captured by our dataset. 5 5.1

Discussion Implications

The Bridge dataset provides reusable information for developing and evaluating automated library update techniques. RQ3 shows that the mined dataset connects API update mappings, version transitions, and client update instances across thousands of libraries. These three units provide complementary information about what API is replaced, between which library versions the replacement is observed, and how clients adapt the code. This information can support automated library update techniques in multiple ways. First, LLM-based techniques can retrieve mappings and associated client update instances from the dataset as replacement knowledge and real-world examples instead of relying solely on information manually supplied in prompts [2, 47, 71]. Second, the mappings and client update instances can provide examples for constructing transformation rules for recurring API changes [51, 57]. Finally, since the dataset retains the originating dependency update commits, it can facilitate the construction of project-level J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

111:28

Kai Gao, Yu Sun, and Chang-ai Sun

benchmarks by identifying candidate projects and version transitions for further curation and build-based validation. High-precision library update dataset construction benefits from combining client-side candidate generation with library-side validation. RQ2 shows that similarity weights have limited impact on the F1 score, whereas library-side validation in Phase 4 increases precision by 40.3 percentage points for Java and 43.3 points for Python at the selected thresholds. This result supports the central design of Bridge: client code provides plausible replacement candidates, while library artifacts provide evidence for validating them. Mining approaches for related software evolution tasks may similarly benefit from using lightweight client-side signals for candidate generation and authoritative artifacts for subsequent validation rather than relying on increasingly complex similarity models alone. The matching threshold can then be selected according to the intended use: reusable dataset construction may favor precision, whereas interactive tools with developer review may tolerate lower precision in exchange for higher recall. Replacement API recommendation remains challenging for current LLMs, particularly for mappings in the long tail. RQ4 shows that the evaluated LLMs achieve limited accuracy in replacement API recommendation and do not consistently benefit from focused client call context. Because selecting an appropriate replacement API is a necessary step in library updates, these results suggest that replacement selection should be treated explicitly rather than assumed to be reliably handled by an LLM. A practical workflow therefore can separate replacement API selection from code adaptation: an update system can first identify which legacy APIs need to be replaced and select their replacement APIs, verify that the selected APIs are available in the target library version, and then adapt the affected client code. Compilation, type checking, and testing can subsequently validate the generated code changes. RQ4 further shows that recommendation accuracy is substantially lower for mappings observed in only a few client update instances than for frequently observed mappings. For mappings in this long tail, future LLM-based techniques may need to complement historical client examples with library-side information such as release notes, API documentation, and source code. 5.2

Threats to Validity

Internal Validity. First, the ground truth dataset is sampled from API call change records produced in Phase 3 and therefore evaluates candidate matching and library-side validation rather than the end-to-end recall of the complete Bridge pipeline. Dependencies or API calls missed in earlier phases, as well as changes excluded during API call change detection, cannot enter the ground truth dataset. Therefore, the RQ1 recall should not be interpreted as the fraction of all client update instances in the studied ecosystems recovered by Bridge. Second, the collection and extraction process makes several assumptions to enable ecosystemscale mining. Bridge assumes that dependency updates and their associated code adaptations occur within the same commit, although some co-occurring code changes may be unrelated to the dependency update. We mitigate this threat by restricting candidate API call changes to the updated library and validating the resulting candidates against the involved library versions. Phase 3 also uses the latest library artifact to identify import prefixes, assuming that these prefixes remain sufficiently stable across releases. Changes in import prefixes may cause API calls from earlier versions to be missed, reducing the coverage of candidate update instance mining. Moreover, the lightweight and conservative static analysis used to process millions of dependency configuration and code blobs may miss dependencies or API calls. Accordingly, the dataset characterized in RQ3 represents the library updates captured by Bridge rather than an exhaustive census of API updates in the Java and Python ecosystems. J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

Bridge : Automatically Mining Ecosystem-Scale API Update Mappings and Client Update Instances

111:29

Third, candidate matching and library-side validation can introduce false positives and false negatives. Similarity-based matching may miss replacements with low similarity or pair similar but unrelated API calls. Although Phase 4 substantially improves precision, removal or deprecation of a legacy API does not establish that the paired replacement API is the intended replacement. Conversely, API signature resolution failures and unrecognized deprecation mechanisms can discard genuine update instances. The RQ1 error analysis characterizes these cases, and the evaluation shows precision above 90% for both languages. Nevertheless, applications requiring manually verified replacement relations should account for the remaining errors in the automatically mined dataset. Finally, manual annotation in the ground truth onstruction and the reference replacements used in RQ4 may contain uncertainty. To reduce annotation errors, two authors independently annotated all possible API call pairs using external evidence, resolved disagreements through discussion, and achieved a Cohen’s 𝜅 of 0.92. For RQ4, the reference mappings are automatically mined by Bridge and therefore have high but imperfect precision. To increase the reliability of the reference replacements, we retain a replacement only when it accounts for a strict majority of the client update instances for the same library, version transition, and legacy API. Besides, the same legacy API may have multiple valid replacements for a version transition. Since each RQ4 example uses only one reference replacement, exact-match accuracy may treat other valid replacements as incorrect. RQ4 should therefore be interpreted as evaluating recommendation against the replacement relations captured by the dataset rather than all potentially valid replacements. External Validity. First, the current implementation of Bridge covers only a subset of dependency updates. It targets pinned dependency updates declared through Maven POM files and four common Python dependency files and requires the dependency version change and associated code changes to occur in the same commit. Consequently, the resulting dataset does not cover updates expressed through unsupported dependency configuration files, unpinned version constraints, or client adaptations distributed across multiple commits. The dataset is constructed from World of Code V3 and therefore reflects the projects and development history captured by this snapshot. Its scale and distribution characteristics may differ for newer snapshots or other software repositories. Moreover, Bridge currently supports only Java and Python. Applying the framework to other ecosystems requires implementing the language-dependent components in Figure 3 according to their packaging practices, language features, and deprecation mechanisms. Second, the ground truth dataset covers 100 sampled libraries per language, and the mining effectiveness of Bridge may differ for libraries and APIs outside this sample. Our two-stage sampling strategy promotes diversity across libraries and old-side APIs rather than allowing frequently updated libraries or APIs to dominate the evaluation. Therefore, the reported precision, recall, and F1 scores should not be interpreted as population-weighted estimates over all API call change records. Finally, RQ4 evaluates four LLMs using one prompt template and two input settings. The recommendation accuracy may therefore differ for other models, prompts, or input settings. The association between mapping frequency and recommendation accuracy should be interpreted as an empirical finding for the evaluated models and dataset rather than as a causal relationship. Mapping frequency may correlate with other factors, such as API popularity and the availability of documentation and code examples. 6

Conclusion

We present Bridge, a client-driven framework for automatically constructing ecosystem-scale library update datasets from client dependency updates. Bridge mines candidate update instances from client-side code changes, validates the candidates against involved library versions, and derives J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

111:30

Kai Gao, Yu Sun, and Chang-ai Sun

API update mappings from the validated instances. This design connects API update mappings, version transitions, and client update instances while grounding each retained mapping in at least one client update instance. On a manually annotated ground truth dataset, Bridge achieves precision of 91.6% for Java and 90.1% for Python, with library-side validation improving precision by more than 40 percentage points for both languages. Applied to World of Code V3, Bridge mines 381,661 Java and 277,259 Python client update instances, representing 18,900 and 4,456 API update mappings across 2,557 and 999 libraries, respectively. The mined mappings exhibit a pronounced long-tail distribution, with most appearing in only a few client update instances and a small number appearing substantially more frequently. Using replacement API recommendation as one application of the dataset, we find that the four evaluated LLMs achieve limited accuracy and perform substantially better on frequently observed mappings than on mappings observed in only a few client update instances. This result highlights replacement API recommendation for mappings in the long tail as a challenge for current LLMs. Overall, Bridge provides an automated approach to constructing ecosystem-scale library update datasets that connect what APIs are replaced, between which library versions, and how clients perform the updates. In future work, we plan to extend Bridge to additional dependency configurations and programming language ecosystems and investigate how the mined mappings and client update instances can support automated library updates. Acknowledgments This work is supported by the National Natural Science Foundation of China (62502030, 92582119, 62272037), China Postdoctoral Science Foundation (2025M781455), and Fundamental Research Funds for the Central Universities (No. FRF-TP-25-030). References [1] Mahmoud Alfadel, Diego Elias Costa, and Emad Shihab. 2023. Empirical analysis of security vulnerabilities in Python packages. Empirical Software Engineering 28, 3 (25 Mar 2023), 59. doi:10.1007/s10664-022-10278-4 [2] Aylton Almeida, Laerte Xavier, and Marco Tulio Valente. 2024. Automatic Library Migration Using Large Language Models: First Results. In Proceedings of the 18th ACM/IEEE International Symposium on Empirical Software Engineering and Measurement (Barcelona, Spain) (ESEM ’24). Association for Computing Machinery, New York, NY, USA, 427–433. doi:10.1145/3674805.3690746 [3] Gabriele Bavota, Gerardo Canfora, Massimiliano Di Penta, Rocco Oliveto, and Sebastiano Panichella. 2015. How the Apache community upgrades dependencies: an evolutionary study. Empirical Softw. Engg. 20, 5 (Oct. 2015), 1275–1317. doi:10.1007/s10664-014-9325-9 [4] Christopher Bogart, Christian Kästner, James Herbsleb, and Ferdian Thung. 2016. How to break an API: cost negotiation and community values in three software ecosystems. In Proceedings of the 2016 24th ACM SIGSOFT International Symposium on Foundations of Software Engineering (Seattle, WA, USA) (FSE 2016). Association for Computing Machinery, New York, NY, USA, 109–120. doi:10.1145/2950290.2950325 [5] Chris Bogart, Christian Kästner, James Herbsleb, and Ferdian Thung. 2021. When and How to Make Breaking Changes: Policies and Practices in 18 Open Source Software Ecosystems. ACM Trans. Softw. Eng. Methodol. 30, 4, Article 42 (July 2021), 56 pages. doi:10.1145/3447245 [6] Scott Chacon and Ben Straub. 2025. Git Objects. https://git-scm.com/book/en/v2/Git-Internals-Git-Objects. [Accessed 16-07-2025]. [7] Keyuan Cheng, Xudong Shen, Yihao Yang, TengyueWang TengyueWang, Yang Cao, Muhammad Asif Ali, Hanbin Wang, Lijie Hu, and Di Wang. 2025. CODEMENV: Benchmarking Large Language Models on Code Migration. In Findings of the Association for Computational Linguistics: ACL 2025, Wanxiang Che, Joyce Nabende, Ekaterina Shutova, and Mohammad Taher Pilehvar (Eds.). Association for Computational Linguistics, Vienna, Austria, 2719–2744. doi:10.18653/v1/2025.findings-acl.140 [8] Chow and Notkin. 1996. Semi-automatic update of applications in response to library changes. In 1996 Proceedings of International Conference on Software Maintenance. 359–368. doi:10.1109/ICSM.1996.565039 [9] Barthélémy Dagenais and Martin Robillard. 2008. Recommending adaptive changes for framework evolution. In 2008 ACM/IEEE 30th International Conference on Software Engineering. 481–490. doi:10.1145/1368088.1368154 J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

Bridge : Automatically Mining Ecosystem-Scale API Update Mappings and Client Update Instances

111:31

[10] Erik Derr, Sven Bugiel, Sascha Fahl, Yasemin Acar, and Michael Backes. 2017. Keep me Updated: An Empirical Study of Third-Party Library Updatability on Android. In Proceedings of the 2017 ACM SIGSAC Conference on Computer and Communications Security (Dallas, Texas, USA) (CCS ’17). Association for Computing Machinery, New York, NY, USA, 2187–2200. doi:10.1145/3133956.3134059 [11] Juri Di Rocco, Phuong T. Nguyen, Claudio Di Sipio, Riccardo Rubei, Davide Di Ruscio, and Massimiliano Di Penta. 2025. DeepMig: A transformer-based approach to support coupled library and code migrations. Inf. Softw. Technol. 177, C (Jan. 2025), 19 pages. doi:10.1016/j.infsof.2024.107588 [12] Mattia Fazzini, Qi Xin, and Alessandro Orso. 2019. Automated API-usage update for Android apps. In Proceedings of the 28th ACM SIGSOFT International Symposium on Software Testing and Analysis (Beijing, China) (ISSTA 2019). Association for Computing Machinery, New York, NY, USA, 204–215. doi:10.1145/3293882.3330571 [13] Mattia Fazzini, Qi Xin, and Alessandro Orso. 2020. APIMigrator: an API-usage migration tool for Android apps. In Proceedings of the IEEE/ACM 7th International Conference on Mobile Software Engineering and Systems (Seoul, Republic of Korea) (MOBILESoft ’20). Association for Computing Machinery, New York, NY, USA, 77–80. doi:10.1145/3387905. 3388608 [14] Python Software Foundation. 2025. PyPI: The Python Package Index. https://pypi.org/. [Accessed 21-12-2025]. [15] Python Software Foundation. 2026. Defining Functions. https://docs.python.org/3/tutorial/controlflow.html. [Accessed 13-01-2026]. [16] Xiang Gao, Arjun Radhakrishna, Gustavo Soares, Ridwan Shariffdeen, Sumit Gulwani, and Abhik Roychoudhury. 2021. APIfix: output-oriented program synthesis for combating breaking changes in libraries. Proc. ACM Program. Lang. 5, OOPSLA, Article 161 (Oct. 2021), 27 pages. doi:10.1145/3485538 [17] GitHub. 2025. Best practices for maintaining dependencies. https://docs.github.com/en/code-security/dependabot/ maintain-dependencies/best-practices-for-maintaining-dependencies. [Accessed 03-12-2025]. [18] GitHub. 2025. Octoverse: A new developer joins GitHub every second as AI leads TypeScript to #1. https://github.blog/ news-insights/octoverse/octoverse-a-new-developer-joins-github-every-second-as-ai-leads-typescript-to-1/. [Accessed 16-12-2025]. [19] M.W. Godfrey and L. Zou. 2005. Using origin analysis to detect merging and splitting of source code entities. IEEE Transactions on Software Engineering 31, 2 (2005), 166–181. doi:10.1109/TSE.2005.28 [20] Haiqiao Gu, Hao He, and Minghui Zhou. 2023. Self-Admitted Library Migrations in Java, JavaScript, and Python Packaging Ecosystems: A Comparative Study. In 2023 IEEE International Conference on Software Analysis, Evolution and Reengineering (SANER). 627–638. doi:10.1109/SANER56733.2023.00064 [21] Haiqiao Gu, Yiliang Zhao, Kai Gao, and Minghui Zhou. 2025. Analyzing C/C++ Library Migrations at the Package-level: Prevalence, Domains, Targets and Rationals across Seven Package Management Tools. arXiv:2507.03263 [cs.SE] https://arxiv.org/abs/2507.03263 [22] Haiqiao Gu, Yiliang Zhao, Kai Gao, and Minghui Zhou. 2026. Analyzing C/C++ Library Migrations at the Package-level: Prevalence, Domains, Targets and Rationales across Seven Package Management Tools. ACM Trans. Softw. Eng. Methodol. (May 2026). doi:10.1145/3816022 Just Accepted. [23] Junxiao Han, Yarong Wang, Xiaodong Gu, Cuiyun Gao, Yao Wan, Song Han, David Lo, and Shuiguang Deng. 2025. LibRec: Benchmarking Retrieval-Augmented LLMs for Library Migration Recommendations. arXiv:2508.09791 [cs.SE] https://arxiv.org/abs/2508.09791 [24] Nicolas Harrand, Amine Benelallam, César Soto-Valero, François Bettega, Olivier Barais, and Benoit Baudry. 2022. API beauty is in the eye of the clients: 2.2 million Maven dependencies reveal the spectrum of client–API usages. Journal of Systems and Software 184 (2022), 111134. doi:10.1016/j.jss.2021.111134 [25] Stefanus A. Haryono, Ferdian Thung, Hong Jin Kang, Lucas Serrano, Gilles Muller, Julia Lawall, David Lo, and Lingxiao Jiang. 2020. Automatic Android Deprecated-API Usage Update by Learning from Single Updated Example. In Proceedings of the 28th International Conference on Program Comprehension (Seoul, Republic of Korea) (ICPC ’20). Association for Computing Machinery, New York, NY, USA, 401–405. doi:10.1145/3387904.3389285 [26] Stefanus A. Haryono, Ferdian Thung, David Lo, Lingxiao Jiang, Julia Lawall, Hong Jin Kang, Lucas Serrano, and Gilles Muller. 2022. AndroEvolve: automated Android API update with data flow analysis and variable denormalization. Empirical Softw. Engg. 27, 3 (May 2022), 31 pages. doi:10.1007/s10664-021-10096-0 [27] Stefanus A. Haryono, Ferdian Thung, David Lo, Julia Lawall, and Lingxiao Jiang. 2021. Characterization and Automatic Updates of Deprecated Machine-Learning API Usages. In 2021 IEEE International Conference on Software Maintenance and Evolution (ICSME). 137–147. doi:10.1109/ICSME52107.2021.00019 [28] Stefanus A. Haryono, Ferdian Thung, David Lo, Julia Lawall, and Lingxiao Jiang. 2021. MLCatchUp: Automated Update of Deprecated Machine-Learning APIs in Python. In 2021 IEEE International Conference on Software Maintenance and Evolution (ICSME). 584–588. doi:10.1109/ICSME52107.2021.00061 [29] Hao He, Runzhi He, Haiqiao Gu, and Minghui Zhou. 2021. A large-scale empirical study on Java library migrations: prevalence, trends, and rationales. In Proceedings of the 29th ACM Joint Meeting on European Software Engineering

J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

111:32

Kai Gao, Yu Sun, and Chang-ai Sun

Conference and Symposium on the Foundations of Software Engineering (Athens, Greece) (ESEC/FSE 2021). Association for Computing Machinery, New York, NY, USA, 478–490. doi:10.1145/3468264.3468571 [30] Hao He, Yulin Xu, Yixiao Ma, Yifei Xu, Guangtai Liang, and Minghui Zhou. 2021. A Multi-Metric Ranking Approach for Library Migration Recommendations. In 2021 IEEE International Conference on Software Analysis, Evolution and Reengineering (SANER). 72–83. doi:10.1109/SANER50967.2021.00016 [31] Johannes Henkel and Amer Diwan. 2005. CatchUp! capturing and replaying refactorings to support API evolution. In Proceedings of the 27th International Conference on Software Engineering (St. Louis, MO, USA) (ICSE ’05). Association for Computing Machinery, New York, NY, USA, 274–283. doi:10.1145/1062455.1062512 [32] Sture Holm. 1979. A Simple Sequentially Rejective Multiple Test Procedure. Scandinavian Journal of Statistics 6, 2 (1979), 65–70. doi:10.2307/4615733 [33] Kaifeng Huang, Bihuan Chen, Linghao Pan, Shuai Wu, and Xin Peng. 2021. RepFinder: finding replacements for missing APIs in library update. In Proceedings of the 36th IEEE/ACM International Conference on Automated Software Engineering (Melbourne, Australia) (ASE ’21). IEEE Press, 266–278. doi:10.1109/ASE51524.2021.9678905 [34] Kaifeng Huang, Bihuan Chen, Bowen Shi, Ying Wang, Congying Xu, and Xin Peng. 2020. Interactive, effort-aware library version harmonization. In Proceedings of the 28th ACM Joint Meeting on European Software Engineering Conference and Symposium on the Foundations of Software Engineering (Virtual Event, USA) (ESEC/FSE 2020). Association for Computing Machinery, New York, NY, USA, 518–529. doi:10.1145/3368089.3409689 [35] Kaifeng Huang, Bihuan Chen, Congying Xu, Ying Wang, Bowen Shi, Xin Peng, Yijian Wu, and Yang Liu. 2022. Characterizing usages, updates and risks of third-party libraries in Java projects. Empirical Softw. Engg. 27, 4 (July 2022), 41 pages. doi:10.1007/s10664-022-10131-8 [36] Nizar Islah, Justine Gehring, Diganta Misra, Eilif B. Müller, Irina Rish, Terry Yue Zhuo, and Massimo Caccia. 2024. GitChameleon: Unmasking the Version-Switching Capabilities of Code Generation Models. CoRR abs/2411.05830 (2024). arXiv:2411.05830 doi:10.48550/ARXIV.2411.05830 [37] Mohayeminul Islam, Ajay Kumar Jha, Ildar Akhmetov, and Sarah Nadi. 2024. Characterizing Python Library Migrations. Proc. ACM Softw. Eng. 1, FSE, Article 5 (July 2024), 23 pages. doi:10.1145/3643731 [38] Mohayeminul Islam, Ajay Kumar Jha, Sarah Nadi, and Ildar Akhmetov. 2023. PyMigBench: A Benchmark for Python Library Migration. In 2023 IEEE/ACM 20th International Conference on Mining Software Repositories (MSR). 511–515. doi:10.1109/MSR59073.2023.00075 [39] Md Mohayeminul Islam, Ajay Kumar Jha, Ildar Akhmetov, and Sarah Nadi. 2025. An Empirical Study of Python Library Migration Using Large Language Models. In Proceedings of the 40th IEEE/ACM International Conference on Automated Software Engineering (Seoul, South Korea) (ASE ’25). IEEE Press, 1–13. [40] Dhanushka Jayasuriya, Valerio Terragni, Jens Dietrich, Samuel Ou, and Kelly Blincoe. 2023. Understanding Breaking Changes in the Wild. In Proceedings of the 32nd ACM SIGSOFT International Symposium on Software Testing and Analysis (Seattle, WA, USA) (ISSTA 2023). Association for Computing Machinery, New York, NY, USA, 1433–1444. doi:10.1145/3597926.3598147 [41] Sunghun Kim, Kai Pan, and E.J. Whitehead. 2005. When functions change their names: automatic detection of origin relationships. In 12th Working Conference on Reverse Engineering (WCRE’05). 10 pp.–152. doi:10.1109/WCRE.2005.33 [42] Sachit Kuhar, Wasi Uddin Ahmad, Zijian Wang, Nihal Jain, Haifeng Qian, Baishakhi Ray, Murali Krishna Ramanathan, Xiaofei Ma, and Anoop Deoras. 2025. LibEvolutionEval: A Benchmark and Study for Version-Specific Code Generation. In Proceedings of the 2025 Conference of the Nations of the Americas Chapter of the Association for Computational Linguistics: Human Language Technologies (Volume 1: Long Papers), Luis Chiruzzo, Alan Ritter, and Lu Wang (Eds.). Association for Computational Linguistics, Albuquerque, New Mexico, 6826–6840. doi:10.18653/v1/2025.naacl-long.348 [43] Raula Gaikovina Kula, Daniel M. German, Ali Ouni, Takashi Ishio, and Katsuro Inoue. 2018. Do developers update their library dependencies? Empirical Softw. Engg. 23, 1 (Feb. 2018), 384–417. doi:10.1007/s10664-017-9521-5 [44] Maxime Lamothe, Weiyi Shang, and Tse-Hsun Peter Chen. 2022. A3: Assisting Android API Migrations Using Code Examples. IEEE Transactions on Software Engineering 48, 2 (2022), 417–431. doi:10.1109/TSE.2020.2988396 [45] Yuxing Ma, Chris Bogart, Sadika Amreen, Russell Zaretzki, and Audris Mockus. 2019. World of code: an infrastructure for mining the universe of open source VCS data. In Proceedings of the 16th International Conference on Mining Software Repositories (Montreal, Quebec, Canada) (MSR ’19). IEEE Press, 143–154. doi:10.1109/MSR.2019.00031 [46] Yuxing Ma, Tapajit Dey, Chris Bogart, Sadika Amreen, Marat Valiev, Adam Tutko, David Kennard, Russell Zaretzki, and Audris Mockus. 2021. World of code: enabling a research workflow for mining and analyzing the universe of open source VCS data. Empirical Software Engineering 26, 2 (25 Feb 2021), 22. doi:10.1007/s10664-020-09905-9 [47] Tarek Mahmud, Bin Duan, Meiru Che, Awatif Yasmin, Anne H. H. Ngu, and Guowei Yang. 2025. Automated Update of Android Deprecated API Usages with Large Language Models . IEEE Transactions on Software Engineering 01 (Nov. 2025), 1–15. doi:10.1109/TSE.2025.3627897 [48] Maven. 2025. POM Reference. https://maven.apache.org/pom.html. [Accessed 17-07-2025].

J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

Bridge : Automatically Mining Ecosystem-Scale API Update Mappings and Client Update Instances

111:33

[49] Quinn McNemar. 1947. Note on the Sampling Error of the Difference Between Correlated Proportions or Percentages. Psychometrika 12, 2 (1947), 153–157. doi:10.1007/BF02295996 [50] Na Meng, Miryung Kim, and Kathryn S. McKinley. 2013. LASE: locating and applying systematic edits by learning from examples. In Proceedings of the 2013 International Conference on Software Engineering (San Francisco, CA, USA) (ICSE ’13). IEEE Press, 502–511. [51] Moderne. 2025. OpenRewrite. https://docs.openrewrite.org/. [Accessed 18-12-2025]. [52] Suchita Mukherjee, Abigail Almanza, and Cindy Rubio-González. 2021. Fixing dependency errors for Python build reproducibility. In Proceedings of the 30th ACM SIGSOFT International Symposium on Software Testing and Analysis (Virtual, Denmark) (ISSTA 2021). Association for Computing Machinery, New York, NY, USA, 439–451. doi:10.1145/ 3460319.3464797 [53] MvnRepository. 2025. Maven Central Repository. https://mvnrepository.com/repos/central. [Accessed 21-12-2025]. [54] Hoan Anh Nguyen, Tung Thanh Nguyen, Gary Wilson, Anh Tuan Nguyen, Miryung Kim, and Tien N. Nguyen. 2010. A graph-based approach to API usage adaptation. In Proceedings of the ACM International Conference on Object Oriented Programming Systems Languages and Applications (Reno/Tahoe, Nevada, USA) (OOPSLA ’10). Association for Computing Machinery, New York, NY, USA, 302–321. doi:10.1145/1869459.1869486 [55] Marius Nita and David Notkin. 2010. Using twinning to adapt programs to alternative APIs. In Proceedings of the 32nd ACM/IEEE International Conference on Software Engineering - Volume 1 (Cape Town, South Africa) (ICSE ’10). Association for Computing Machinery, New York, NY, USA, 205–214. doi:10.1145/1806799.1806832 [56] Lina Ochoa, Thomas Degueule, Jean-Rémy Falleri, and Jurgen Vinju. 2022. Breaking bad? Semantic versioning and impact of breaking changes in Maven Central. Empirical Software Engineering 27, 3 (17 Mar 2022), 61. doi:10.1007/s10664021-10052-y [57] OpenRewrite. 2025. Migrate Log4j 1.x to Log4j 2.x. https://docs.openrewrite.org/recipes/java/logging/log4j/ log4j1tolog4j2. [Accessed 18-12-2025]. [58] OpenSSF. 2025. OpenSSF Scorecard. https://scorecard.dev/. [Accessed 03-12-2025]. [59] Oracle. 2025. Defining Methods. https://docs.oracle.com/javase/tutorial/java/javaOO/methods.html. [Accessed 18-07-2025]. [60] pip. 2025. Requirements File Format. https://pip.pypa.io/en/stable/reference/requirements-file-format/. [Accessed 17-07-2025]. [61] PyPA. 2025. Names and normalization. https://packaging.python.org/en/latest/specifications/name-normalization/ #name-normalization. [Accessed 18-11-2025]. [62] PyPA. 2025. pyproject.toml specification. https://packaging.python.org/en/latest/specifications/pyproject-toml/. [Accessed 17-07-2025]. [63] Daniel Ramos, Hailie Mitchell, Inês Lynce, Vasco Manquinho, Ruben Martins, and Claire Le Goues. 2024. MELT: Mining Effective Lightweight Transformations from Pull Requests. In Proceedings of the 38th IEEE/ACM International Conference on Automated Software Engineering (Echternach, Luxembourg) (ASE ’23). IEEE Press, 1516–1528. doi:10. 1109/ASE56229.2023.00117 [64] Pasquale Salza, Fabio Palomba, Dario Di Nucci, Cosmo D’Uva, Andrea De Lucia, and Filomena Ferrucci. 2018. Do developers update third-party libraries in mobile apps?. In Proceedings of the 26th Conference on Program Comprehension (Gothenburg, Sweden) (ICPC ’18). Association for Computing Machinery, New York, NY, USA, 255–265. doi:10.1145/ 3196321.3196341 [65] Anand Ashok Sawant, Maurício Aniche, Arie van Deursen, and Alberto Bacchelli. 2018. Understanding developers’ needs on deprecation as a language feature. In Proceedings of the 40th International Conference on Software Engineering (Gothenburg, Sweden) (ICSE ’18). Association for Computing Machinery, New York, NY, USA, 561–571. doi:10.1145/ 3180155.3180170 [66] Thorsten Schäfer, Jan Jonas, and Mira Mezini. 2008. Mining framework usage changes from instantiation code. In Proceedings of the 30th International Conference on Software Engineering (Leipzig, Germany) (ICSE ’08). Association for Computing Machinery, New York, NY, USA, 471–480. doi:10.1145/1368088.1368153 [67] Amazon Web Services. 2025. Amazon Q Developer. https://aws.amazon.com/q/developer/transform/. [Accessed 15-12-2025]. [68] setuptools. 2024. Configuring setuptools using setup.cfg files. https://setuptools.pypa.io/en/latest/userguide/ declarative_config.html. [Accessed 17-07-2025]. [69] setuptools. 2024. Keywords in setup() function. https://setuptools.pypa.io/en/latest/references/keywords.html. [Accessed 30-12-2025]. [70] Sonatype. 2025. Optimizing Software Dependency Management for Better Results. https://www.sonatype.com/blog/ dependency-management-versions-choice-and-the-software-supply-chain. [Accessed 03-12-2025]. [71] Nikolov Stoyan, Codecasa Daniele, Sjovall Anna, Tabachnyk Maxim, Chandra Satish, Taneja Siddharth, and Ziftci Celal. 2025. How is Google using AI for internal code migrations?. In Proceedings of the 47st International Conference

J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

111:34

Kai Gao, Yu Sun, and Chang-ai Sun

on Software Engineering: Software Engineering in Practice (Ottawa, Ontario, Canada) (ICSE-SEIP ’25). Association for Computing Machinery, New York, NY, USA, 1–12. doi:10.1109/ICSE-SEIP.2019.00042 [72] Tree-sitter Contributors. 2025. Tree-sitter. https://tree-sitter.github.io/tree-sitter/. [Accessed 18-07-2025]. [73] Daniel Venturini, Filipe Roseiro Cogo, Ivanilton Polato, Marco A. Gerosa, and Igor Scaliante Wiese. 2023. I Depended on You and You Broke Me: An Empirical Study of Manifesting Breaking Changes in Client Packages. ACM Trans. Softw. Eng. Methodol. 32, 4, Article 94 (May 2023), 26 pages. doi:10.1145/3576037 [74] Chong Wang, Kaifeng Huang, Jian Zhang, Yebo Feng, Lyuye Zhang, Yang Liu, and Xin Peng. 2025. LLMs Meet Library Evolution: Evaluating Deprecated API Usage in LLM-based Code Completion. In Proceedings of the IEEE/ACM 47th International Conference on Software Engineering (Ottawa, Ontario, Canada) (ICSE ’25). Association for Computing Machinery, New York, NY, USA, 13 pages. [75] Jiawei Wang, Li Li, Kui Liu, and Haipeng Cai. 2020. Exploring how deprecated Python library APIs are (not) handled. In Proceedings of the 28th ACM Joint Meeting on European Software Engineering Conference and Symposium on the Foundations of Software Engineering (Virtual Event, USA) (ESEC/FSE 2020). Association for Computing Machinery, New York, NY, USA, 233–244. doi:10.1145/3368089.3409735 [76] Ying Wang, Bihuan Chen, Kaifeng Huang, Bowen Shi, Congying Xu, Xin Peng, Yijian Wu, and Yang Liu. 2020. An Empirical Study of Usages, Updates and Risks of Third-Party Libraries in Java Projects. In 2020 IEEE International Conference on Software Maintenance and Evolution (ICSME). 35–45. doi:10.1109/ICSME46990.2020.00014 [77] Ying Wang, Ming Wen, Yepang Liu, Yibo Wang, Zhenming Li, Chao Wang, Hai Yu, Shing-Chi Cheung, Chang Xu, and Zhiliang Zhu. 2020. Watchman: monitoring dependency conflicts for Python library ecosystem. In Proceedings of the ACM/IEEE 42nd International Conference on Software Engineering (Seoul, South Korea) (ICSE ’20). Association for Computing Machinery, New York, NY, USA, 125–135. doi:10.1145/3377811.3380426 [78] World of Code. 2025. World of Code (WoC) Overview. https://bitbucket.org/swsc/overview/src/master/. [Accessed 16-07-2025]. [79] Jianyu Wu, Hao He, Wenxin Xiao, Kai Gao, and Minghui Zhou. 2022. Demystifying software release note issues on GitHub. In Proceedings of the 30th IEEE/ACM International Conference on Program Comprehension (Virtual Event) (ICPC ’22). Association for Computing Machinery, New York, NY, USA, 602–613. doi:10.1145/3524610.3527919 [80] Jianyu Wu, Weiwei Xu, Kai Gao, Jingyue Li, and Minghui Zhou. 2023. Characterize Software Release Notes of GitHub Projects: Structure, Writing Style, and Content. In 2023 IEEE International Conference on Software Analysis, Evolution and Reengineering (SANER). 473–484. doi:10.1109/SANER56733.2023.00051 [81] Tongtong Wu, Weigang Wu, Xingyu Wang, Kang Xu, Suyu Ma, Bo Jiang, Ping Yang, Zhenchang Xing, Yuan-Fang Li, and Gholamreza Haffari. 2024. VersiCode: Towards Version-controllable Code Generation. CoRR abs/2406.07411 (2024). arXiv:2406.07411 doi:10.48550/ARXIV.2406.07411 [82] Wei Wu, Yann-Gaël Guéhéneuc, Giuliano Antoniol, and Miryung Kim. 2010. AURA: a hybrid approach to identify framework evolution. In 2010 ACM/IEEE 32nd International Conference on Software Engineering, Vol. 1. 325–334. doi:10.1145/1806799.1806848 [83] Zhenchang Xing and Eleni Stroulia. 2007. API-Evolution Support with Diff-CatchUp. IEEE Transactions on Software Engineering 33, 12 (2007), 818–836. doi:10.1109/TSE.2007.70747 [84] Shengzhe Xu, Ziqi Dong, and Na Meng. 2019. Meditor: Inference and Application of API Migration Edits. In 2019 IEEE/ACM 27th International Conference on Program Comprehension (ICPC). 335–346. doi:10.1109/ICPC.2019.00052 [85] Zhaoxu Zhang, Hengcheng Zhu, Ming Wen, Yida Tao, Yepang Liu, and Yingfei Xiong. 2020. How Do Python Framework APIs Evolve? An Exploratory Study. In 2020 IEEE 27th International Conference on Software Analysis, Evolution and Reengineering (SANER). 81–92. doi:10.1109/SANER48275.2020.9054800

Received 20 February 2007; revised 12 March 2009; accepted 5 June 2009

J. ACM, Vol. 37, No. 4, Article 111. Publication date: August 2018.

Related documents

• The AI Scientist-v2: Workshop-Level Automated Scientific Discovery via Agentic Tree Search#133422
• Structuring agentic AI for HPC code modernization#986272
• API Security Based on Automatic OpenAPI Mapping#123980
• Transformations for Evolving Property Graph Schemas#1144871
• Towards a FAIR-compliant Harmonised AI-based Automatic Metadata for Climate Research#122331