{"id":15065254,"url":"https://github.com/refactorfirst/refactorfirst","last_synced_at":"2025-05-15T06:02:20.640Z","repository":{"id":39658449,"uuid":"300295554","full_name":"refactorfirst/RefactorFirst","owner":"refactorfirst","description":"Identifies and prioritizes God Classes Highly Coupled classes, and Class Cycles in Java codebases you should refactor first.","archived":false,"fork":false,"pushed_at":"2025-04-06T19:33:43.000Z","size":1208,"stargazers_count":488,"open_issues_count":43,"forks_count":42,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-04-14T11:16:18.507Z","etag":null,"topics":["cycle-analysis","cycle-detection","java","maven","maven-plugin","refactoring","refactoring-tools","report","static-analysis"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/refactorfirst.png","metadata":{"files":{"readme":"README.md","changelog":"change-proneness-ranker/pom.xml","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"jimbethancourt","open_collective":"RefactorFirst","ko_fi":"jimbethancourt","liberapay":"jimbethancourt","patreon":"jimbethancourt"}},"created_at":"2020-10-01T13:48:21.000Z","updated_at":"2025-04-11T23:27:47.000Z","dependencies_parsed_at":"2023-02-18T00:30:36.734Z","dependency_job_id":"dcf21411-6810-476d-87e5-194f2eda15ef","html_url":"https://github.com/refactorfirst/RefactorFirst","commit_stats":{"total_commits":247,"total_committers":21,"mean_commits":"11.761904761904763","dds":0.2753036437246964,"last_synced_commit":"03b29edac98d4db8e6c1c67488bb77c681a64bd9"},"previous_names":["refactorfirst/refactorfirst","jimbethancourt/refactorfirst"],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refactorfirst%2FRefactorFirst","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refactorfirst%2FRefactorFirst/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refactorfirst%2FRefactorFirst/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refactorfirst%2FRefactorFirst/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/refactorfirst","download_url":"https://codeload.github.com/refactorfirst/RefactorFirst/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248868767,"owners_count":21174758,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cycle-analysis","cycle-detection","java","maven","maven-plugin","refactoring","refactoring-tools","report","static-analysis"],"created_at":"2024-09-25T00:35:50.725Z","updated_at":"2025-04-14T11:16:36.647Z","avatar_url":"https://github.com/refactorfirst.png","language":"Java","readme":"# RefactorFirst\n\nThis tool for Java codebases will help you identify what you should refactor first:\n- God Classes\n- Highly Coupled classes\n- Class Cycles (with cycle images!)\n\nIt scans your Git repository generates a single page application by runing:\n- Cycle analysis on your source code using the [OpenRewrite](https://github.com/openrewrite/rewrite) Java parser and [JGraphT](https://jgrapht.org/)\n- What-if analysis to identify the most optimal relationships in a class cycle to remove\n- PMD's God Class Rule\n- PMD's Coupling Between Objects\n\nCode map viewers are powered by [3D Force Graph](https://vasturiano.github.io/3d-force-graph), [sigma.js](https://www.sigmajs.org/), and [GraphViz DOT](https://graphviz.org/docs/layouts/dot/)\n\u003cbr\u003eIf there are more than 4000 classes + relationships, a simplified 3D viewer will be used to avoid slowdowns.  Features will be toggleable in the 3D UI in a future release.\n\nTake a look at the [Spring Petclinic REST project sample report](https://rawcdn.githack.com/refactorfirst/RefactorFirst/c46d26211a91ffbe08d4089e04a85ff31eb093c0/spring-petclinic-rest-report.html)!\n\nThe graphs generated in the report will look similar to this one:\n![image info](./RefactorFirst_Sample_Report.png)\n\n## Please Note: Java 11 (or newer) required to run RefactorFirst\n**Java 21 codebase analysis is supported!**\nThe change to require Java 11 is needed to address vulnerability CVE-2023-4759 in JGit \nPlease use a recent JDK release of the Java version you are using.  \nIf you use an old JDK release of your chosen Java version, you may encounter issues during analysis.\n\n\n## There are several ways to run the analysis on your codebase:\n\n### From The Command Line As an HTML Report\nRun the following command from the root of your project (the source code does not need to be built):\n\n```bash\nmvn org.hjug.refactorfirst.plugin:refactor-first-maven-plugin:0.7.1:htmlReport\n```\nView the report at ```target/site/refactor-first-report.html```\n\n### [As Part of GitHub Actions Output](https://github.blog/news-insights/product-news/supercharging-github-actions-with-job-summaries/)\nThis will generate a simplified HTML report (no graphs or images) as the output of a GitHub Action step\n```bash\nmvn -B clean test \\\norg.hjug.refactorfirst.plugin:refactor-first-maven-plugin:0.7.1:simpleHtmlReport \\\n\u0026\u0026 echo \"$(cat target/site/refactor-first-report.html)\" \u003e\u003e $GITHUB_STEP_SUMMARY\n```\n\n### As Part of a Build\nAdd the following to your project in the build section.  **showDetails** will show God Class metrics and rankings in the generated table.\n```xml\n\u003cbuild\u003e\n    \u003cplugins\u003e\n        ...\n        \u003cplugin\u003e\n            \u003cgroupId\u003eorg.hjug.refactorfirst.plugin\u003c/groupId\u003e\n            \u003cartifactId\u003erefactor-first-maven-plugin\u003c/artifactId\u003e\n            \u003cversion\u003e0.7.1\u003c/version\u003e       \n            \u003c!-- optional --\u003e\n            \u003cconfiguration\u003e\n                \u003cshowDetails\u003efalse\u003c/showDetails\u003e\n            \u003c/configuration\u003e\n        \u003c/plugin\u003e\n        ...\n    \u003c/plugins\u003e\n\u003c/build\u003e\n```\n\n### As a Maven Report\nAdd the following to your project in the reports section.   \nA RefactorFirst report will show up in the site report when you run ```mvn site```\n```xml\n\u003creporting\u003e\n    \u003cplugins\u003e\n        ...\n        \u003cplugin\u003e\n            \u003cgroupId\u003eorg.hjug.refactorfirst.plugin\u003c/groupId\u003e\n            \u003cartifactId\u003erefactor-first-maven-plugin\u003c/artifactId\u003e\n            \u003cversion\u003e0.7.1\u003c/version\u003e       \n        \u003c/plugin\u003e\n        ...\n    \u003c/plugins\u003e\n\u003c/reporting\u003e\n```\n\n## Configuraiton Options\nCare has been taken to use sensible defaults, though if you wish to override these defaults you can specify the following parameters.\nSpecify with -D if running on the command line.  e.g. ```-DbackEdgeAnalysisCount=0 `DanalyzeCycles=false``` or in the configuration section (as in the above examples) if including in a Maven build.\n\n|Option|Action|Default|\n|------|------|-------|\n|showDetails|Shows God Class metrics|false|\n|backEdgeAnalysisCount|Number of back edges in a cycle to analyze.  \u003cbr\u003eIf total number of back edges is greater than the value specified, it analyzes the number of minimum weight edges specified.\u003cbr\u003e**If 0 is specified, all back edges will be analyzed**|50|\n|analyzeCycles|Analyzes the 10 largest cycles (will be configurable in the future)|true|\n|minifyHtml|Minifies the generated HTML report.  Only available on ```htmlReport``` and ```simpleHtmlReport``` goals.  May cause issues with large reports.|false|\n|excludeTests|Exclude test classes from analysis|true|\n|testSrcDirectory|Excludes classes containing this pattern from analysis|```src/test``` and ```src/test```|\n|projectName|The name of your project to be displayed on the report|Your Maven project name|\n|projectVersion|The version of your project to be displayed on the report|Your Maven project version|\n|outputDirectory|The location the project report will be written|```${projectDir}/target/site/refactor-first-report.html```\n\n\n### Seeing Errors?\n\nIf you see an error similar to\n```\n Execution default-site of goal org.apache.maven.plugins:maven-site-plugin:3.3:site failed: A required class was missing while executing org.apache.maven.plugins:maven-site-plugin:3.3:site: org/apache/maven/doxia/siterenderer/DocumentContent\n```\nyou will need to add the following to your pom.xml:\n```xml\n  \u003cbuild\u003e\n    \u003cplugins\u003e        \n      \u003cplugin\u003e\n        \u003cgroupId\u003eorg.apache.maven.plugins\u003c/groupId\u003e\n        \u003cartifactId\u003emaven-site-plugin\u003c/artifactId\u003e\n        \u003cversion\u003e3.12.1\u003c/version\u003e\n      \u003c/plugin\u003e\n      \u003cplugin\u003e\n        \u003cgroupId\u003eorg.apache.maven.plugins\u003c/groupId\u003e\n        \u003cartifactId\u003emaven-project-info-reports-plugin\u003c/artifactId\u003e\n        \u003cversion\u003e3.4.5\u003c/version\u003e\n      \u003c/plugin\u003e\n    \u003c/plugins\u003e\n  \u003c/build\u003e\n```\n\n\n## But I'm using Gradle / my project layout isn't typical!\nI would like to create a Gradle plugin and (possibly) support non-conventional projects in the future, but in the meantime you can create a dummy POM file in the same directory as your .git directory:\n\n```xml\n\u003cproject xmlns=\"http://maven.apache.org/POM/4.0.0\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n  xsi:schemaLocation=\"http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd\"\u003e\n  \u003cmodelVersion\u003e4.0.0\u003c/modelVersion\u003e\n \n  \u003cgroupId\u003ecom.mycompany.app\u003c/groupId\u003e\n  \u003cartifactId\u003emy-app\u003c/artifactId\u003e\n  \u003cversion\u003e1.0-SNAPSHOT\u003c/version\u003e\n\u003c/project\u003e\n```\nand then (assuming Maven is installed) run\n\n```bash\nmvn org.hjug.refactorfirst.plugin:refactor-first-maven-plugin:0.7.1:htmlReport\n```\n\n## Viewing the Report\nView the report at ```target/site/refactor-first-report.html```   \nOnce the plugin finishes executing (it may take a while for a large / old codebase), open the file **target/site/refactor-first-report.html** in the root of the project.  It will contain a graph similar to the one above, and a table that lists God classes in the recommended order that they should be refactored.  The classes in the top left of the graph are the easiest to refactor while also having the biggest positive impact to team productivity.  \nIf highly coupled classes are detected, a graph and table listing Highly Coupled Classes in will be generated.\n\n## I have the report.  Now What???\nWork with your Product Owner to prioritize the technical debt that has been identified.  It may help to explain it as hidden negative value that is slowing team porductivity.  \nIf you have IntelliJ Ultimate, you can install the [Method Reference Diagram](https://plugins.jetbrains.com/plugin/7996-java-method-reference-diagram) plugin to help you determine how the identified God classes and Highly Coupled classes can be refactored.\n\n\n## Additional Details\nThis plugin will work on both single module and multi-module Maven projects that have a typical Maven project layout.\n \nThis tool is based on the paper **[Prioritizing Design Debt Investment Opportunities](https://dl.acm.org/doi/10.1145/1985362.1985372)** by Nico Zazworka, Carolyn Seaman, and Forrest Shull.  The presentation based on the paper is available at https://resources.sei.cmu.edu/asset_files/Presentation/2011_017_001_516911.pdf \n\n## Limitations\n* My time.  This is a passion project and is developed in my spare time.\n\n## Feedback and Collaboration Welcome\nThere is still much to be done.  Your feedback and collaboration would be greatly appreciated in the form of feature requests, bug submissions, and PRs.  \nIf you find this plugin useful, please star this repository and share with your friends \u0026 colleagues and on social media.\n\n## Future Plans\n* Improve class cycle analysis\n* Add a Gradle plugin.\n* Incorporate Unit Test coverage metrics to quickly identify the safety of refactoring classes.\n* Incorporate bug counts per class to the Impact (Y-Axis) calculation.\n* Incorporate more disharmonies from Object Oriented Metrics In Practice (Lanza and Marinescu, 2004).\n\n## Note:\nIf you are a user of Version 0.1.0 or 0.1.1, you may notice that the list of God classes found by the plugin has changed.  This is due to changes in PMD.\n\n# Thank You!  Enjoy!\n","funding_links":["https://github.com/sponsors/jimbethancourt","https://opencollective.com/RefactorFirst","https://ko-fi.com/jimbethancourt","https://liberapay.com/jimbethancourt","https://patreon.com/jimbethancourt"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frefactorfirst%2Frefactorfirst","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frefactorfirst%2Frefactorfirst","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frefactorfirst%2Frefactorfirst/lists"}