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

A client-driven framework that constructs ecosystem-scale library update datasets linking API update mappings, version transitions, and client update instances

Kai Gao; Yu Sun; Chang-ai Sun· 2026· DOI 10.48550/arXiv.2608.30497

The core problem

Library updates frequently require adapting client code to API changes. To develop and evaluate automated library update techniques, researchers and practitioners need three interconnected artifacts: API update mappings that identify relations between legacy and replacement APIs, version transitions that specify the library versions to which these mappings apply, and client update instances that capture concrete API call changes in real projects. Existing library evolution datasets capture only subsets of this information and typically cover few third-party libraries, limiting their usefulness for ecosystem-scale analysis and tooling. This paper introduces **Bridge**, a client-driven framework for automatically constructing ecosystem-scale library update datasets that connect API update mappings, version transitions, and client update instances. The central design principle is to ground each retained mapping in at least one client update instance, ensuring that mappings reflect real-world update behavior rather than speculative or purely library-side signals. The authors evaluate Bridge on a manually annotated ground truth dataset and apply it to the World of Code V3 (WoC V3) corp

Innovation

Bridge is evaluated on a manually annotated ground truth dataset and applied to WoC V3. On the ground truth, Bridge achieves **91.6% precision** and **88.7% recall** for Java, and **90.1% precision** and **64.0% recall** for Python. The lower recall for Python suggests that some valid update instances are missed, possibly due to dynamic typing or less explicit API usage patterns. Applied to WoC V3, Bridge mines **381,661 Java** and **277,259 Python** client update instances. These instances yield **18,900 Java** and **4,456 Python** API update mappings across **2,557** and **999** libraries, respectively. The mined mappings exhibit a pronounced long-tail distribution: most mappings appear in only a few client update instances, while a small number of mappings are observed frequently. The scale of the dataset is substantial, covering thousands of libraries and hundreds of thousands of client update instances. The long-tail distribution implies that many API update mappings are rare, which has implications for automated techniques that rely on learning from frequent patterns. As an application, the authors evaluate four large language models on replacement API recommendation. The

Library updates frequently require adapting client code to API changes. To develop and evaluate automated library update techniques, researchers and practitioners need three interconnected artifacts: API update mappings that identify relations between legacy and replacement APIs, version transitions that specify the library versions to which these mappings apply, and client update instances that capture concrete API call changes in real projects. Existing library evolution datasets capture only subsets of this information and typically cover few third-party libraries, limiting their usefulness for ecosystem-scale analysis and tooling.

This paper introduces **Bridge**, a client-driven framework for automatically constructing ecosystem-scale library update datasets that connect API update mappings, version transitions, and client update instances. The central design principle is to ground each retained mapping in at least one client update instance, ensuring that mappings reflect real-world update behavior rather than speculative or purely library-side signals. The authors evaluate Bridge on a manually annotated ground truth dataset and apply it to the World of Code V3 (WoC V3) corpus to mine large-scale Java and Python update datasets. As an application, they benchmark four large language models (LLMs) on replacement API recommendation, a key step in library updates.

Why it matters

The results demonstrate that Bridge can automatically construct ecosystem-scale library update datasets with high precision and reasonable recall. The client-driven design ensures that each API update mapping is grounded in at least one real client update instance, which may improve the practical relevance of the dataset compared to library-side-only approaches. The long-tail distribution of mappings is a key finding: most mappings are rare, and LLMs struggle with these rare mappings. This suggests that current LLM-based approaches may not generalize well to the full diversity of API updates in the wild. The evaluation on replacement API recommendation shows that even the best LLM achieves only 37.1% accuracy for Java and 44.4% for Python. The performance gap between frequent and rare mappings indicates that models may be memorizing common patterns rather than learning to reason about API semantics. This has implications for the development of automated library update tools: they may need to incorporate retrieval or program analysis techniques to handle long-tail mappings. Bridge's dataset can support further research in automated library update, API migration, and empirical software engineering. The framework could be extended to other languages and ecosystems. Limitations include the recall gap for Python and the reliance on library-side evidence, which may not be available for all libraries. Future work could improve validation and derivation steps, and explore hybrid approaches combining LLMs with program analysis for replacement API recommendation.

Who should read this

CS practitioners and researchers

Opening member content…