USING THE ANALYSIS ENGINE
Last updated
Last updated
iCR for Python supports the analysis of projects being managed by Cloud-Based services such as GitHub, GitLab or Bitbucket as well as locally accessible projects. For the purposes of demonstrating the Analysis Engine and the Reviewer, we will use examples using the cloud-based repositories. The behavior when using locally accessible projects is nearly identical and should be easy to infer from the following descriptions. The Analysis Engine works on your Python source code by focusing only on executable lines of code. It does process some of the comments but the Analysis Engine does not count blank lines or most comments in its OpenRefactory Bundled Lines of Code (OBLoC) count. You can use the cloc Linux command to get an estimate of how many executable lines of code are in your project.
To begin the analysis of a project, you will have logged into your Version-Control System (VCS) such as GitHub, which is being used in our examples. You connected to the Navigator using your server’s Public IP address and port 3002 (See Section 2 Getting Started). Once connected to the Navigator, you selected the project you want to analyze, cloned it and then selected the branch that you wish to analyze (See Section 4.5 Selecting Your Source Code).
To begin the analysis of the branch, click on the Analyze button.
Smaller projects (< 100,000 Lines of Code) tend to be less complex in terms of number of files and methods. These may be analyzed within minutes. However, larger projects (> 1M LoC) may take much longer to analyze. That’s OK. You don’t have to sit and watch as it could take many hours for a large, complex project to be thoroughly analyzed.
Clicking the Analyze button gives you the option of requesting an email notification when the analysis completes. If you select the box requesting a notification, an email prompt is displayed. Enter the email to which iCR will address your notification.
To begin the analysis, click Yes. A new tab opens which takes you to the Monitor Analysis screen.
The first step that the analysis undertakes is a check of the license. The license is used to authenticate this instance of iCR and manages the number of OBLoCs that are authorized for this instance. The Checking License Information step requires access to the Internet in order to reach the License Management software and may take a minute or two to complete. Once the license is validated, the Analysis Engine will pull the desired Python library version from the Internet. The class libraries are large and this may take a few minutes. The Monitor display will present a progress indicator during this download process:
This Monitor Analysis screen displays the progress of the analysis of a project.
The window on the left displays information about the project including: • The current state of analysis; • The name of the project; • The branch within that project being analyzed; • The User ID of the User who initiated this analysis; • The cumulative count of errors corrected; • Time when the analysis began; • There is also an Abort button to stop the analysis.
The window on the right displays the phases of the analysis and their progress. A total count of the number of errors that have been corrected so far is at the top of the window. Various phases of the analysis are shown with progress bars to give you a sense of how far the analysis has progressed.
Once analysis completes, the end time is added to the state display along with a display of how many OBLoCs were consumed by the analysis.
While you may choose to watch the Monitor Analysis display, as noted earlier, analysis make take a long time for complex projects. In some cases, it may take many hours. So, you can go back to the Navigator tab and Exit iCR and return when you are notified that the analysis is done. Or from the Navigator, you may choose to review the results from an earlier analysis in a different project or branch.
If you return to the Navigator home screen, you will see that the Analysis Status has changed.
The status now shows that there is a project running. The name and branch of what is being analyzed is displayed. You will also note that a new button has appeared. It is the Monitor Analysis button. Clicking on this button will open a new Monitor tab so that you can check up on progress.
It could happen that you started an analysis on a project with the wrong branch and want to start over. Or, after watching the progress for some time (remember, many large and complex projects could take many hours to analyze) you may decide to abandon the analysis.
In either case, you may decide to Abort the analysis. If so, click on the Abort button at the top of the left window. This will terminate the analysis. If you terminate the analysis, you will lose any information you produced to that point. Any OBLoCs analyzed during an aborted analysis are NOT deducted from your subscription value.
You can help out OpenRefactory determine if there was an issue with your analysis by clicking on Send Crash Report which is the button at the bottom left of the left window. Selecting this is at your discretion but it will help us to help you complete your analysis.
When clicked, a crash report window appears. You can enter the experience that you encountered as to why you aborted the analysis. For example, it could be as simple as “I was analyzing the wrong branch”. Or it may be that you thought the analysis was not progressing.
In the latter case, we request that you consider clicking on the option labeled “Send the console log of the run”. From the log, we may be able to determine whether the analysis was in the wrong or if it was progressing but just taking longer than you expected.
We want to be clear that the log may contain various snippets of your source code such as Method and Class names. We made this optional so that if you have a concern about OpenRefactory seeing even a tiny fragment of your source code, you can refuse to forward the log. Of course, this means that we will not likely be able to determine the cause of a failure if one occurred. But we believe that having you retain complete control of your source code is necessary for you to be able to trust that we treat your code with the utmost privacy.
When an analysis completes normally, you will receive an email notification if you requested that at the time you initiated the analysis. Once complete, the Navigator will present the prompt on the right. You will also be informed of the number if OBLoCs used during this analysis.
It is helpful for OpenRefactory to collect some summary data on as many analyses as possible. This helps us to better understand what bugs are most common and where our performance could be improved. Sending a summary is completely up to you and the report contains none of your source code information of any kind. To reassure you that is the case, check out Appendix D which shows a typical summary report from the django project which we have been using as our example in this guide. If you have exhausted your licensed capacity of OBLoCs, you cannot initiate further analyses. Please contact OpenRefactory to learn how you can extend your license.
