PaperlayerView exact revision on arXiv

Source-linked AI summary

ASNER: Software Architecture Recovery with Adaptive Semantic Neighborhoods and Evidence-Grounded Refinement

Wenhao Wang, Zhi Jin, Jia Li, Dongming Jin, Heng Tian, Yingtao Fang, Wenguang Ye, Tiankuo Zhao

arXiv:2610.36894v1cs.SE

TL;DR

Architecture recovery needs to distinguish shared architectural responsibility from functional similarity, while fixed neighborhood rules and unconstrained refinement leave important decisions under-specified. ASNER combines structured responsibilities, project-adaptive semantic neighborhoods, and evidence-grounded boundary checks. It achieves the best common-benchmark macro-average across five metrics and improves code localization when used with LocAgent.

  • Problem

    Functional similarity may not indicate shared architectural responsibility, fixed thresholds or Top-K neighborhoods ignore repository scale and local similarity distributions, and unconstrained refinement may change assignments without sufficient evidence.

    Source: §1 · p. 2

  • Method

    ASNER derives structured file responsibilities, selects project-adaptive semantic neighborhoods to augment dependencies, recovers components through community detection, and refines uncertain boundaries only with responsibility and code evidence.

    Source: §1 · p. 3

  • Results

    ASNER achieves the best macro-average across all five metrics on the common benchmark, improving ARI and c2c@66 over GAER-GAT by 19.5% and 32.9%, respectively.

    Source: §1 · p. 3

  • Takeaways & Limitations

    ASNER-guided LocAgent improves file-, module-, and function-level code localization, supporting the value of recovered architecture for repository-level software engineering tasks.

    Source: §1 · p. 3

Abstract

from arXiv · show

Automated software architecture recovery provides architectural context for software engineering and repository-level LLM agents. Existing methods combine structural and semantic signals, but functional relatedness does not necessarily imply shared architectural responsibility. Fixed thresholds or Top-K neighborhoods also ignore repository scale and local similarity distributions, introducing errors that propagate through clustering. Unconstrained LLM refinement may further alter correct assignments without sufficient evidence. We propose ASNER (Adaptive Semantic Neighborhoods and Evidence-Grounded Refinement for Software Architecture Recovery), based on responsibility-aware, project-adaptive relation modeling and evidence-grounded boundary verification. ASNER derives structured file responsibilities with an LLM, constructs semantic neighborhoods that adapt to repository scale and local similarity distributions, and augments a static dependency graph with selected semantic relations and weak directory cues. Community detection recovers the component backbone. A Responsibility-Ownership-Aware (ROA) Agent then examines uncertain boundary files using project-level responsibilities and traceable code evidence, changing assignments only when supported. Experiments on 12 open-source projects spanning C, C++, Java, and Python show that ASNER achieves the best macro-average on all five metrics on the common benchmark, improving ARI and c2c@66 over GAER-GAT by 19.5% and 32.9%, respectively. A downstream evaluation shows that ASNER-guided LocAgent improves file-, module-, and function-level code localization, demonstrating the value of its architectural context for repository-level software engineering tasks.

1 INTRODUCTION

Automated architecture recovery is important for repository-level software engineering, but semantic similarity alone may not reflect shared architectural responsibility. ASNER combines responsibility-aware adaptive relations with evidence-grounded boundary refinement; evaluation reports strong benchmark and code-localization results.

Motivation

  • Architectural drift and missing or outdated documentation make current architecture difficult to recover, even for experienced architects.Repository-level agents need module boundaries, functional responsibilities, and dependencies alongside understanding of individual functions and files.Source: §1 · pp. 1–2

Challenges

  • Functional relatedness does not guarantee shared responsibility, while fixed thresholds and Top-K rules ignore repository scale and local similarity distributions.Even improved semantic relations leave ambiguous boundary files; unconstrained LLM refinement may alter correct assignments without sufficient evidence.Source: §1 · p. 2

Approach

  • ASNER derives structured file responsibilities, adapts semantic neighborhoods to project scale and local similarity, and uses selected semantic links with dependencies and weak directory cues to recover components.Its ROA Agent revisits uncertain boundaries and changes assignments only when project-level responsibility ownership and concrete code evidence support the alternative.Source: §1 · p. 3

Evaluation

  • ASNER achieves the best macro-average across all five metrics on the common benchmark, improving ARI and c2c@66 over GAER-GAT by 19.5% and 32.9%.Evaluation spans 12 projects across C, C++, Java, and Python; ASNER-guided LocAgent also improves file-, module-, and function-level localization.Source: §1 · p. 3

2 RELATED WORK

Architecture recovery has progressed from structural clustering through hybrid fusion and learned representations to LLM-guided methods. The cited approaches add information sources, but leave adaptation to project-specific similarity and evidence-grounded boundary correction underexplored.

2.1 STRUCTURAL CLUSTERING

  • Structural methods group files by dependency proximity, but their accuracy depends on which dependency types the input graph encodes.Bunch maximizes modularization quality, WCA merges files by weighted Jaccard, and ACDC extracts pattern-based subsystem skeletons.Source: §2.1 · p. 3

2.2 HYBRID INFORMATION FUSION

  • Hybrid methods fuse structural, textual, and directory cues, but their hand-crafted rules do not explicitly adapt to project-specific module sizes or dependency distributions.SADE reweights call graphs with semantic similarity, while SARIF combines typed dependencies with source-position-aware textual terms.Source: §2.2 · p. 3

2.3 REPRESENTATION LEARNING

  • Representation-learning methods reduce reliance on hand-crafted similarity functions, yet GAER uses one encoder configuration and cluster-selection procedure across datasets.Its semantic-neighborhood construction does not adapt to each project’s local similarity distribution.Source: §2.3 · p. 4

2.4 LLM-GUIDED RECOVERY

  • LLM-guided recovery supplies architectural semantics or maps code to known components, but prior approaches do not establish responsibility ownership or make boundary corrections traceable to code evidence.ASNER addresses these gaps with adaptive semantic neighborhoods and an ROA Agent that changes uncertain assignments only when project responsibilities and traceable code evidence support them.Source: §2.4 · p. 4

3 METHOD

ASNER recovers a component backbone from a fused dependency-semantic graph, then checks uncertain boundaries using layered responsibility context and traceable evidence. Its stages combine file-level structural and responsibility representations, adaptive semantic-neighborhood selection, and evidence-constrained refinement.

3.1 OVERVIEW

  • ASNER extracts dependencies and structured responsibilities, builds a fused graph with project-adaptive semantic neighborhoods, detects the architectural backbone, and refines uncertain assignments with traceable evidence.The ROA Agent builds responsibility cards and retrieves bounded static evidence before changing assignments.Source: §3.1 · p. 4, Figure 2 · p. 4

3.2 DEPENDENCY GRAPH AND FILE RESPONSIBILITY EXTRACTION

  • ENRE relations are mapped from entities to files and weighted by relation type, count, and entity-level contribution; each Structured Responsibility Summary encodes primary responsibility, managed entities, and state effects.An LLM distinguishes direct implementation from called or tested functionality, and SRS embeddings represent implementation semantics.Source: §3.2 · p. 5

3.3 ADAPTIVE SEMANTIC EDGES AND GRAPH FUSION

  • SGASN sets a candidate range from repository scale and retains neighbors using the largest drop in each file’s local similarity ranking, with a minimum-retention fraction.Selected semantic edges augment the ENRE graph; directory structure is only an auxiliary cue, and modularity-based community detection produces the initial partition.Source: §3.3 · p. 5

3.4 LAYERED RESPONSIBILITIES AND TRACEABLE EVIDENCE

  • Layered responsibilities summarize project scope, capabilities, and file-level implementation; only core implementors provide same-component evidence.Static dependencies are stored with files, entities, and source locations so candidate decisions can be traced to code facts.Source: §3.4 · p. 5

3.5 ROA AGENT AND EVIDENCE-CONSTRAINED REFINEMENT

  • ROA examines boundary files with anomalous dependency distributions and a clear candidate component, comparing whether to keep or move each file.It accepts at most one evidence-supported move per iteration, regenerates candidates, and retains the initial partition if no move passes.Source: §3.5 · pp. 5–6

4 EXPERIMENTS

ASNER is evaluated across diverse projects and recovery metrics, with results favoring it over baselines and ablations supporting the contributions of semantic representations, adaptive neighborhoods, and ROA refinement.

4.1 EXPERIMENTAL SETUP

  • The benchmark covers 12 systems in C, C++, Java, and Python; five higher-is-better metrics are macro-averaged with equal project weights, and ground truth is reserved for final evaluation.The comparison includes ten baseline methods.Source: §4.1 · p. 6
  • DeepSeek-V4.1-Flash generates file responsibilities, L0–L2 summaries, and ROA decisions; experiments use seed 42 and average two runs per project.The implementation uses ENRE for dependencies and Qwen3-Embedding-4B for responsibility embeddings.Source: §4.1 · p. 6

4.2 MAIN RESULTS

  • On the eight-project common benchmark, ASNER leads all five macro-average metrics and improves ARI by 19.5% and c2c@66 by 32.9% over GAER-GAT.Across all 12 projects, ASNER also exceeds SemArc on every macro-average metric, with scaled ARI rising from 43.56 to 55.29 and c2c@66 from 24.88% to 44.42%.Source: §4.2 · p. 6, Table 1 · p. 7

4.3 ABLATION STUDIES

  • Removing semantic embeddings reduces ARI by 27.34 points and c2c@66 by 32.90 points; replacing structured responsibilities with plain summaries lowers all five metrics.The structured responsibility representation includes primary responsibilities, managed entities, and state effects.Source: §4.3 · pp. 6–7, Table 2 · p. 7
  • Removing local gap truncation reduces ARI by 2.97 points, while removing both SGASN stages increases the drop to 5.97 points and degrades all other metrics.The comparison replaces SGASN with a fixed similarity threshold of 0.5 when both scale-aware candidate selection and local gap truncation are removed.Source: §4.3 · p. 7
  • Adding ROA improves ARI by 0.99 points and c2c@66 by 0.79 points, with gains on the remaining metrics as well.These smaller but consistent gains support ROA's role as boundary refinement rather than the primary source of recovery accuracy.Source: §4.3 · p. 7, Table 2 · p. 7

5 ANALYSIS

Across model configurations, ASNER retains recovery gains while exposing resource trade-offs; its Bash case study and LOC-BENCH evaluation show component-boundary and code-localization improvements.

5.1 CROSS-MODEL GENERALIZATION

  • All three model configurations outperform SemArc on every macro-averaged metric; Qwen and GLM improve ARI over SemArc by 10.48 and 7.32 points, respectively.DeepSeek is strongest overall; Qwen trails it by 0.18–3.28 points and outperforms GLM on all five metrics.Source: §5.1 · pp. 7–8, Table 3 · p. 8

5.2 EFFICIENCY AND COST

  • Extraction accounts for 99.4%/97.7% of recorded runtime and about 99.5% of tokens for Qwen/GLM, while reusing file responsibilities removes the principal cost of repeated recovery.Qwen scores higher on all five metrics without API charges but records 38.03 hours versus GLM’s 10.49 hours; GLM costs an estimated CNY 797.70 across 11 projects.Source: §5.2 · p. 8, Figure 3 · p. 8

5.3 CASE STUDY

  • On Bash’s 312 source files, ASNER produces 13 clusters versus SemArc’s 21 and keeps all files of 11 reference components together in a single recovered cluster.Six of those 11 components form unmixed clusters; SemArc splits support, libintl, libsh, and libglob into five, three, nine, and three clusters, respectively, while ASNER maps each to one unmixed cluster.Source: §5.3 · pp. 8–9, Figure 4 · p. 9

5.4 DOWNSTREAM CODE LOCALIZATION

  • ASNER-guided LocAgent raises file Acc@5 from 87.50% to 100.00% and improves module and function Acc@10 by 8.33 points across 24 LOC-BENCH issues.The sample contains 20 Dask and four pypdf issues.Source: §5.4 · p. 9, Table 4 · p. 9

6 CONCLUSION

ASNER combines structured file responsibilities, adaptive semantic neighborhoods, and evidence-grounded boundary refinement, and the paper reports improved recovery and downstream localization. The appendix specifies its procedure and inputs, while the reproducibility statement describes the experiments and planned artifact release.

6 CONCLUSION

  • ASNER combines structured file responsibilities, project-adaptive semantic neighborhoods, and evidence-grounded ROA refinement; it achieves the best macro-average on all five common-benchmark metrics and improves downstream localization.The conclusion reports gains over GAER-GAT of 0.4, 2.0, 8.4, 7.4, and 9.9 points for MoJoFM, a2a, ARI, a2aadj, and c2c@66, respectively.Source: §6 · pp. 9–10

AI USE STATEMENT

  • The authors report using generative AI only for writing and formatting assistance, not for research ideation, experimental design, data analysis, or conclusions.They state that all substantive research and writing contributions were made by the authors.Source: AI USE STATEMENT · p. 10

REPRODUCIBILITY STATEMENT

  • The reproducibility statement says experiments cover 12 open-source projects across C, C++, Java, and Python, and that code and reproduction artifacts will be made public upon publication..Source: REPRODUCIBILITY STATEMENT · p. 10

A.1 INPUTS, OUTPUTS, AND NOTATION

  • The stated input is a fixed repository revision, files in scope, static-analysis settings, and generation and embedding model configurations; outputs include file-to-component mappings and evidence references.Component count comes from community detection and refinement, not from the number of generated responsibilities.Source: §A.1 · p. 15

A.2 END-TO-END PROCEDURE

  • The appendix procedure builds a static-dependency and file-responsibility backbone, selects a stable partition, verifies boundary moves with bounded evidence, then applies deterministic split and merge rules.Ground-truth labels are loaded only after the predicted partition is frozen; generated implementation responsibilities serve as verification cues, not human architecture labels.Source: §A.2 · p. 15, A PROBLEM DEFINITION AND RECOVERY… · p. 15

B.1 ENTITY RELATIONS AND STATIC EDGE WEIGHTS

ASNER builds recovery from responsibility-aware semantic relations, adaptive graph fusion, and evidence-constrained boundary refinement. Its appendix details the relation construction, neighborhood selection, evidence views, and constrained refinement rules.

B.1 ENTITY RELATIONS AND STATIC EDGE WEIGHTS

  • Static entity relations are normalized and aggregated into weighted file-level graph edges, with explicit declaration–implementation links optionally collapsed before clustering.Ordinary calls do not trigger collapse, and compound nodes are expanded after clustering.Source: §B.1 · pp. 15–16

B.2 SEMANTIC REWEIGHTING, DIRECTORY PRIOR, AND COMMUNITY DETECTION

  • Selected semantic relations augment the dependency graph, while directory structure supplies a weak cue and community detection recovers components.Directory names do not become component labels.Source: §B.2 · p. 16

C.1 RESPONSIBILITY PROJECTION

  • File profiles encode primary responsibility, managed entities, and state effects, and their cosine similarity measures responsibility proximity rather than same-component probability.A missing primary responsibility falls back to a supported secondary responsibility.Source: §C.1 · p. 17

C.2 EXACT TWO-LEVEL NEIGHBORHOOD SELECTION

  • SGASN adapts a candidate range to project scale, then uses the largest drop in each file’s full local similarity ordering to select neighbors within that range.A gap beyond the scale cap retains all candidates allowed by that cap.Source: §C.2 · p. 17

C.3 LOCATION RERANKING AND PARTITION GATE

  • Location similarity reranks only existing semantic candidates, and a partition gate retains the responsibility-only result when location cues have negligible effect.Location reranking cannot create candidate-external edges.Source: §C.3 · p. 17

D.1 EVIDENCE IDENTITY AND STORAGE

  • The EvidenceStore preserves source-anchored relation facts and project-revision membership, while bounded evidence views retain file, entity, relation, direction, and location fields for verification.The store does not materialize a full adjacency table, semantic vectors, or LLM responses.Source: §D.1 · pp. 17–18

D.2 BOUNDED VIEWS AND OWNERSHIP ROLES; E.2 DETERMINISTIC SPLIT AND MERGE RULES

  • Ownership roles distinguish primary implementors, callers, shared supporters, and uncertain files; constrained split and merge rules narrow actions without guaranteeing improved accuracy.The specialized source/sink split requires matching base-family names and qualifying files on both sides; merge eligibility is bounded by stable scopes or endpoint membership and bidirectional relations.Source: §D.2 · p. 18, §E.2 · pp. 18–19

E.1 CANDIDATE RANKING AND VERIFICATION

  • ROA compares keeping a candidate file with moving it, while requiring evidence-backed proposals and an independent audit.It accepts at most one move per iteration and stops when no candidate passes, a partition would recur, or the iteration limit is reached.Source: §E.1 · p. 18

F EVALUATION METRICS AND AGGREGATION

The evaluation section defines partition-comparison metrics and describes the prompts and refinement trace used by ASNER. Its distributed-camera example illustrates how evidence review and deterministic rules affect a recovered partition.

F EVALUATION METRICS AND AGGREGATION

  • The evaluator compares predicted and reference partitions on their common files, and project macro-averages give each valid project equal weight.All five metrics are higher-is-better, and c2c@66 uses a strict threshold with the recovered-component count as denominator.Source: F EVALUATION METRICS AND AGGREGATION · p. 19

G.1 COMPLETE PROMPT TEMPLATES

  • The responsibility prompts require implementation-grounded hierarchies and ownership claims tied to evidence, while treating repository-derived text as untrusted data.L2 denotes cohesive implementation ownership; callers, tests, serializers, and entity users are not grouped merely for being related.Source: §G.1 · pp. 20–21
  • Move verification compares KEEP against MOVE using supplied interaction evidence, and an independent audit challenges proposed moves before acceptance.Directory matches and shared vocabulary alone are insufficient evidence for a move.Source: §G.1 · p. 22

G.2 DISTRIBUTED-CAMERA EXECUTION TRACE

  • In the distributed-camera trace, the audit rejected an IPC utility move because its shared transformation responsibility and use by flow-operation proxies supported keeping it.The deterministic split and merge steps then changed the partition from 20 to 21 components.Source: §G.2 · p. 22

H.1 EXPERIMENTAL CONFIGURATION

  • Cross-model runs regenerate file and hierarchical responsibilities and perform ROA decisions with the same generative model, while retaining Qwen3-Embedding-4B embeddings.The configurations used different hardware and network conditions.Source: §H.1 · p. 23

H.2 DATASET SELECTION AND BASELINE PROVENANCE

The benchmark combines reproduced baseline results with reruns on identifiable source snapshots. Coverage varies where artifacts, pipeline compatibility, or language configurations are unavailable.

H.2 DATASET SELECTION AND BASELINE PROVENANCE

  • SemArc was rerun on all 12 systems, GAER-GAT on nine, and SARIF on eight using released implementations and the common evaluator where available.Seven traditional baseline results came from the SARIF reproduction outputs.Source: §H.2 · p. 23, Table 9 · p. 23
  • The benchmark uses 11 systems with identifiable source snapshots plus ITK rather than substituting unmatched revisions for four systems.The unavailable revisions lacked exact public source snapshots.Source: §H.2 · p. 23
  • Unavailable Python configurations and results for several baselines are reported as missing rather than replaced with new language ports.TeamMates also lacks valid SARIF and traditional-baseline results in the reproduction package.Source: §H.2 · pp. 23–24

H.3 PER-PROJECT RECOVERY RESULTS

The appendix describes per-project result coverage, cross-model resource accounting, dataset scope, and reproducibility boundaries. It also specifies how LocAgent retrieves ASNER’s recovered architecture during localization.

H.3 PER-PROJECT RECOVERY RESULTS

H.4 CROSS-MODEL RESOURCE ACCOUNTING

  • 136,916.912 seconds for Qwen and 37,754.802 seconds for GLM are the summed phase runtimes across the aligned 11-project workflow.Runtime and cumulative request latency are separate quantities; the deployments used different hardware and network conditions.Source: §H.4 · p. 25, Table 13 · p. 25
  • Spearman correlations between repository NLOC and extraction tokens are 0.891 for Qwen and 0.900 for GLM, a positive association rather than a general linear law.The linear fits explain 57.6% and 58.6% of token variance, respectively.Source: §H.4 · p. 25, Figure 5 · p. 27

H.5 DATASET SUMMARY

  • The benchmark covers 12 systems, while the cross-model resource analysis excludes ITK and uses 11 projects.The reported repository-size range is 5K–2,143K NLOC.Source: §H.5 · p. 25, Table 15 · p. 26

H.6 ACCOUNTING FORMULA AND REPRODUCIBILITY BOUNDARIES

  • Static analysis may miss reflection, runtime registration, and dynamic communication; generated responsibilities can omit boundaries, and constrained actions do not guarantee improvement against every human reference.The cited API-price total is an estimate, not an invoiced charge.Source: §H.6 · p. 27

I.1 ARCHITECTURE TOOLS AND INTEGRATION

  • LocAgent retrieves ASNER’s read-only architecture context through tools before code retrieval and reasoning, without exposing patches or ground-truth locations.The tools return component responsibilities, file assignments, and static interaction evidence.Source: §I.1 · p. 27, Table 17 · p. 27

I.2 EXPERIMENTAL SETUP

The downstream localization experiment compares configurations under matched settings and reuses each project-version architecture across its issues. It evaluates strict top-k accuracy on a 24-issue sample.

I.2 EXPERIMENTAL SETUP

  • The hybrid single-stage configuration adds four architecture tools and mandatory initial architecture retrieval; Table 18 summarizes the experiment configuration.Both configurations share the model, decoding parameters, interaction limit, code index, and issue descriptions.Source: §I.2 · pp. 27–28, Table 18 · p. 28
  • Each project-version architecture is built once and reused across its issues.Source: §I.2 · p. 28
  • Strict Acc@k requires all ground-truth locations at a granularity among the top-k predictions; the random sample contains 20 Dask and four pypdf issues, each with one modified file.LOC-BENCH uses File Acc@5/10 and Module/Function Acc@10/15.Source: §I.2 · p. 28

I.3 PER-REPOSITORY RESULTS

Per-repository results show that the aggregate improvement comes from Dask, while the two configurations tie on the four pypdf issues.

I.3 PER-REPOSITORY RESULTS

  • The aggregate improvement comes from Dask, where architecture guidance improves all six measures; the configurations tie on the four pypdf issues.Table 19 reports per-repository code-localization accuracy for the hybrid single-stage integration.Source: Table 19 · p. 28, §I.3 · p. 28

Related papers

Loading 2610.36894v1…