Cycle detected: Fix for Circular dependency report by ArchUnit (again)

[ichxorya]

I'm back after a month of hiatus, this time @h-man2 's suggestion is included right away in the temporary README of the repo (which should be useful to fully rewired into the docs folder after merging).

• 2026/05/06: Start to redone this fork by pulling the latest main version; the rationale behind this new refactor is basically due to many changes happened in the main branch, thus it would be best to do it again from scratch. Add the cycle visualization per the suggestion at Cycle detected: Fix for Circular dependency report by ArchUnit #128 (comment)
• 2026/05/07: First cycle removed (SEhumantics@8d3b7ea)
• 2026/05/15: Return to the work. Latest commit patched bug 4, 5, 8. Remaining 1, 2, 3, 6, 7
• 2026/05/16: Only bug 1 remains.

[ichxorya]

2026/05/06 example; see more hier

[ichxorya]

2026/05/07 First cycle removed

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR aims to address recurring ArchUnit-reported circular dependencies by refactoring API construction (breaking the api ↔ api.impl cycle), expanding cycle-report generation in ArchUnit tests, and adding documentation tooling to visualize cycles.

Changes:

• Introduced UseSystemApiFactory in org.tzi.use.api.impl and migrated call sites away from UseSystemApi.create(...) to break the api ↔ api.impl cycle.
• Enhanced ArchUnit cycle tests to emit per-area failure reports and results into target/archunit-* directories; added additional GUI subpackage cycle checks.
• Added Mermaid-generation tooling and a PR-notes README that embeds cycle diagrams; committed ArchUnit output snapshots under target_archunit_temp.

Reviewed changes

Copilot reviewed 33 out of 38 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
use-gui/target_archunit_temp/archunit-results/ant_cyclic_dependencies_xmlparser_results.csv	Adds a committed snapshot of ArchUnit “ant cyclic dependencies” result output.
use-gui/target_archunit_temp/archunit-results/ant_cyclic_dependencies_views_results.csv	Adds a committed snapshot of ArchUnit “ant cyclic dependencies” result output.
use-gui/target_archunit_temp/archunit-results/ant_cyclic_dependencies_util_gui_results.csv	Adds a committed snapshot of ArchUnit “ant cyclic dependencies” result output.
use-gui/target_archunit_temp/archunit-results/ant_cyclic_dependencies_main_gui_results.csv	Adds a committed snapshot of ArchUnit “ant cyclic dependencies” result output.
use-gui/target_archunit_temp/archunit-results/ant_cyclic_dependencies_graphlayout_results.csv	Adds a committed snapshot of ArchUnit “ant cyclic dependencies” result output.
use-gui/target_archunit_temp/archunit-reports/failure_report_maven_layers.txt	Adds a committed snapshot of a layers violation report used for documentation/visualization.
use-gui/target_archunit_temp/archunit-reports/failure_report_maven_cycles_shell.txt	Adds a committed snapshot of a cycle report to support diagnosis/visualization.
use-gui/target_archunit_temp/archunit-reports/failure_report_maven_cycles_gui_views.txt	Adds a committed snapshot of GUI views cycle report to support diagnosis/visualization.
use-gui/target_archunit_temp/archunit-reports/failure_report_maven_cycles_gui_main.txt	Adds a committed snapshot of GUI main cycle report to support diagnosis/visualization.
use-gui/target_archunit_temp/archunit-reports/failure_report_maven_cycles_gui.txt	Adds a committed snapshot of the broader GUI cycle report to support diagnosis/visualization.
use-gui/src/test/java/org/tzi/use/gui/views/diagrams/util/CreationTimeRecorderTest.java	Updates tests to create UseSystemApi via the new factory.
use-gui/src/test/java/org/tzi/use/architecture/MavenCyclicDependenciesGUITest.java	Improves ArchUnit cycle counting tests to write detailed failure reports and results under target/.
use-gui/src/test/java/org/tzi/use/architecture/AntCyclicDependenciesGUITest.java	Redirects ArchUnit “ant” result output into target/archunit-results.
use-core/target_archunit_temp/archunit-reports/failure_report_maven_cycles_uml.txt	Adds a committed snapshot of core UML cycle report used for tracking/visualization.
use-core/target_archunit_temp/archunit-reports/failure_report_maven_cycles_parser.txt	Adds a committed snapshot of parser cycle report used for tracking/visualization.
use-core/target_archunit_temp/archunit-reports/failure_report_maven_cycles_gen.txt	Adds a committed snapshot of generator cycle report used for tracking/visualization.
use-core/src/test/java/org/tzi/use/utilcore/AbstractBagTest.java	Updates tests to create UseSystemApi via the new factory.
use-core/src/test/java/org/tzi/use/uml/sys/soil/StatementEffectTest.java	Updates tests to create UseSystemApi via the new factory.
use-core/src/test/java/org/tzi/use/uml/sys/ObjectCreation.java	Updates helper test code to create UseSystemApi via the new factory.
use-core/src/test/java/org/tzi/use/uml/sys/MSystemStateTest.java	Updates tests to create UseSystemApi via the new factory.
use-core/src/test/java/org/tzi/use/uml/sys/MCmdDestroyObjectsTest.java	Updates tests to create UseSystemApi via the new factory.
use-core/src/test/java/org/tzi/use/uml/sys/LinkTest.java	Updates tests to create UseSystemApi via the new factory.
use-core/src/test/java/org/tzi/use/uml/sys/DeletionTest.java	Updates tests to create UseSystemApi via the new factory.
use-core/src/test/java/org/tzi/use/uml/mm/MAssociationClassTest.java	Updates tests to create UseSystemApi via the new factory.
use-core/src/main/java/org/tzi/use/api/impl/UseSystemApiFactory.java	Introduces a factory in api.impl to instantiate implementations without coupling api back to api.impl.
use-core/src/main/java/org/tzi/use/api/UseSystemApi.java	Removes static factory methods that created a circular api ↔ api.impl dependency.
use-core/src/main/java/module-info.java	Exports org.tzi.use.api.impl so UseSystemApiFactory is accessible to external modules/tests.
use-core/src/it/java/org/tzi/use/OCLExpressionIT.java	Updates integration test to create UseSystemApi via the new factory.
use-core/pom.xml	Updates dependency coordinates/versions and build properties for Java 21.
pom.xml	Adds centralized compiler plugin management and Java release property.
docs/scripts/generate_cycle_mermaid.py	Adds tooling to rewrite README marker blocks with Mermaid diagrams from ArchUnit reports.
docs/archunit-history/before-fix/bug-4_failure_report_maven_cycles_api.txt	Archives the pre-fix cycle report for the api ↔ api.impl issue.
README_nghiabt_notes_on_this_pr/nghiabt_notes_on_this_pr.md	Adds a dedicated PR-notes README tracking cycles with embedded Mermaid diagrams.
.vscode/settings.json	Adds VS Code Java settings for null analysis and build configuration updates.

Comments suppressed due to low confidence (1)

use-gui/src/test/java/org/tzi/use/architecture/MavenCyclicDependenciesGUITest.java:158

• The test ensures target/archunit-reports exists (in writeFailureReport), but does not ensure target/archunit-results exists before opening FileWriter(filename, true). This can fail on a clean checkout/CI. Create RESULTS_DIR (e.g., in setup() or inside writeResult) similarly to how REPORTS_DIR is handled.

    private void writeResult(int result, String filename) {
        try (PrintWriter out = new PrintWriter(new FileWriter(filename, true))) {
            out.println(result);
        } catch (IOException e) {
            e.printStackTrace();
        }
    }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 38 out of 43 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

use-gui/src/test/java/org/tzi/use/architecture/MavenCyclicDependenciesGUITest.java:153

• FileWriter is opened under target/archunit-results, but this class never creates that directory. On a clean checkout the write fails with FileNotFoundException; create RESULTS_DIR before opening result files, similar to the report directory handling.

        try (PrintWriter out = new PrintWriter(new FileWriter(filename, true))) {

[Copilot]

Pull request overview

Copilot reviewed 46 out of 51 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (2)

use-gui/src/test/java/org/tzi/use/architecture/MavenCyclicDependenciesGUITest.java:153

• RESULTS_DIR is never created in this class before opening the result file, so these tests can fail on a clean checkout where target/archunit-results does not already exist. Create the parent directory in setup() or inside writeResult() before constructing the FileWriter.
  use-gui/src/test/java/org/tzi/use/architecture/MavenCyclicDependenciesGUITest.java:132
• When a package's cycle count drops to zero, this returns without deleting any existing failure_report_maven_cycles_<shortName>.txt. A stale report from a previous run will remain under target/archunit-reports and can make the README generator continue showing cycles that were fixed; delete the report file (or write an empty/no-cycles report) before returning.

[h-man2]

Hi @ichxorya!
A lot of work, thanks! I'm currently double-checking the changes. A first question: there are many files in the changeset without visible changes, like for example use-gui/src/main/java/org/tzi/use/gui/views/diagrams/elements/package-info.java.
Could it be a change of teh line endings?

[ichxorya]

Hi @ichxorya!
A lot of work, thanks! I'm currently double-checking the changes. A first question: there are many files in the changeset without visible changes, like for example use-gui/src/main/java/org/tzi/use/gui/views/diagrams/elements/package-info.java.
Could it be a change of teh line endings?

Thanks for your response! This PR was initially done as AIs assisted me (mostly Claude Opus 4.7) with my work. However in later phases (from the point I forgot documenting again), I let the AI to autonomously taking the job and plan to review it later.

Sorry if any troubles happen when you do peer review @h-man2 . I should have mark this PR as draft before I'm ready with my review. You can tell me if you stop reviewing for now since I will have to take my responsible for my messy, gigantic PR with lots of breaking changes.

Thank you.

Edit: as for changes relevant that are non-showing, I will keep that in mind and see if the problem is just end-of-lines added or not. I have to check and document all these changes in order to keep the PR coherent with the repository.

[h-man2]

No worries. I was just starting to review it.
Please mark the PR as a draft and ping me if you are ready 😃