USING THE NAVIGATOR
Last updated
Last updated
This section will introduce you to the iCR Navigator, which is used to help you manage you project analyses. It assumes that you are familiar with the Getting Started procedures outlined in Section 3 and have already installed iCR for Python on your host server. You know your server’s IP address and have created the OAuth credentials to allow your developers to securely log into your cloud-based version-control service (VCS). In the examples to follow, we will work with GitHub as the example cloud-based VCS.
The iCR for Python service is accessible using any industry standard browser such as Chrome, Firefox, Safari or Edge. To begin working with iCR, you need to access your server via the browser. It is reached using your server’s IP address. In our examples we are using 3.237.77.219 as the public IP address. ICR uses port 3002 to reach the Navigator which is the application that will help you to manage your interactions with iCR for Python. Access the Navigator by entering your Server IP address followed by port 3002 into your browser. Using our IP address as an example, this is the URL to enter: http://3.237.77.219:3002 Entering this URL will take you to the welcome screen for iCR for Python:
You are presented with a window that prompts the user to enter a passphrase. Since the IP address to your Server is public, it is possible to have uninvited “guests” attempt to access your service. To protect the service from unwanted access, you must enter the secret passphrase before you can access the service. The initial, default passphrase is set to icrforpython.
NOTE: You can reset the default passphrase to a different string if you wish using the command icrforpython -p So, type in the default passphrase: icrforpython to enter iCR for Python.
Entering the passphrase will bring you to the Navigator where you will be prompted immediately to alter the passphrase to something other than the default. The phrase should be at least 8 characters long and you may use any alphanumeric values as well as special characters
Once the passphrase is updated, you are presented with the Navigator Home screen. From here, you can select and open project repositories with your projects, analyze one of more branches of any of these projects and then, following analysis, you can review and apply corrections to flaws detected in those branches.
At the top of screen, on the right side, you see 5 buttons: • Settings • Help • Comments • Usage • Exit iCR
The Settings button is used to change or configure a number of optional properties for iCR for Python.
The security passphrase can be updated using the Change Passphrase setting. This was used when you first connected to the Navigator to change your password from the default.
Similarly, when you first accessed your cloud-based VCS, you were prompted for OAuth credentials. Should you need to update those later, for example, if your IP address changed, you can use the Change github/gitlab/bitbucket credentials settings to update those.
When a new User is authorized to allow analyses to be triggered using a CI/CD framework, then the Change GitHub App credentials need to be used. Details on setting these are outlined in the companion document: iCR - Workflow Integration User Guide v1.1.
You can add contact information using the Update Contact Info setting, if you choose to send OpenRefactory either crash information or other feedback about the operation of iCR.
The Help button will take you to the OpenRefactory Website where you can download help documents, such as this guide, and view the Video Tutorials to help you learn how to use iCR for Python. Under the Help menu is also the About request. Selecting this will display the current operating version of the software.
The Comment button allows you to send your feedback to OpenRefactory. Your feedback helps us to improve the interface and also helps us to improve the quality of the service by getting feedback concerning potential false positives or improvements on the Fixers.
The Usage button helps you to learn how much time you have spent doing analysis and reviewing. This gives you the knowledge of how much time you have accumulated doing both Analysis and Reviewing fixes. It also provides a summary of the number of OpenRefactory Bundled Lines of Code (OBLoC) that were analyzed and how many are remaining in your subscription.
Finally, the Exit iCR button takes you out of iCR for Python and back to the welcome screen. To re-enter, you would, of course, have to enter your new passphrase.
These buttons will be presented on all other screens in the application so that you can always Exit iCR at any time or provide feedback and get help. You may only change the settings from this Home Screen, however.
Below the top banner, the status of the Analysis Engine is displayed on the right side. Since the analysis process is very RAM and CPU-intensive, iCR currently only support one analysis at a time. The status window lets you know that the engine is available for a new analysis. Or, if an analysis is in progress, it will display a brief summary of the ongoing analysis.
From Section 3.3 Accessing your source code, you will have already set up the OAuth credentials to allow logins to your preferred VCS. Assuming that you have done that, select your VCS from the pull-down menu. For our examples, we will be using GitHub.
The very first time a user attempts to reach GitHub following the OAuth configuration, the Navigator will pop up a window requesting you to enter the Client ID and Secret keys from the OAuth configuration. As explained in Section 3.3 Accessing your source code, hopefully you copied the Client ID and Secret somewhere so that you can enter them here. Once done, users may login into their GitHub accounts without needed to repeat this process.
If there is some reason to change the OAuth Client ID and Secret, you can get back to this window using the Settings button on the main menu.
If you are already logged into GitHub from earlier activity on your browser, then your repository will become available right away. If your login session is no longer active, you may be asked to renew it with this prompt. After selecting Yes, you will need to re-select the GitHub repository.
Once logged in, you will now see all of your available GitHub projects.
Each project is presented with a “+” sign so that you can open it up to view its branches. Before you can browse the project branches, however, you need to “clone” a copy of the project from GitHub. The Clone button is to the right of the project name box.
For our example, we will use a project called django, which we show below as cloned and ready for analysis. Note that, once cloned, the Clone button is replaced by Remove. This provides you with a way of removing a project if you desire. When you remove a project, however, note that ALL RESULTS WILL BE REMOVED. That is, any analysis that you have performed and not applied to your project will be lost. Clicking on the “+” will enumerate all of the available branches:
Python employs a class library to provide the standard suite of runtime classes needed to execute your Python scripts. The libraries are frequently updated and each project branch may depend upon a particular version of the libraries. iCR for Python allows you to select the library version needed for each branch. When the project is opened after clicking on the “+” icon, the available branches are displayed along with a new button labeled: Version.
In this example, it is the first time we are analyzing this project so the Version dropdown menu will display all the available library versions. Select your required version from this list. In this example, we will select 3.7 as our desired version. This will set 3.7 as the default version for all branches. Once selected, we can choose the branch that we want to analyze.
Only one branch at a time can be selected. That is reflected using
the radio buttons to choose which branch to examine. Let’s look at the main branch. Selecting its radio button causes three new options to appear: • Analyze • Review • Update
The first button, Analyze, is always available and allows you to perform an analysis on the branch. Clicking on it will take you to the Analysis screen which will display status on the ongoing analysis. Section 5 will describe the Analysis Engine further.
The second button, Review, is not available unless one of more analyses of this branch have been executed. Once an analysis is complete, you would want to click Review so that you can begin the process of looking at the detected problems and the corrections that iCR has provided. Section 6.4 Handling Results covers the details of the Reviewer within iCR for Python.
The third button, Update, is made available when the current status of the branch is out of date with the currently checked-in status. That is, it may be “behind” the current master copy of the branch on the VCS repository. This is not unusual in that your developers may be working with a branch while others are also working on it. If you have made updates to the branch using the Reviewer those changes may already have been incorporated into the “main” branch.
Even though you may not have completed reviewing all of the corrections offered in the last analysis, you may decide to interrupt that process and perform a more up-to-date analysis using the latest “main” version. If so, you can select the Update button. This will cause the Navigator to pull-down the most recent version of source code to the iCR for Python server.
Naturally, this will make further review of the old source invalid and so should be followed by a click of the Analyze button, to perform a new analysis of the updated source code. In such a case, you may also decide to simply Remove the project entirely and Clone it again. Doing so removes all past history of earlier analyses.
You may choose to not access source code from a cloud-based repository. iCR for Python also supports accessing projects that are accessible directly on your server. Any of your developers may be given login access to your server. From a shell console, you can upload projects to it or, you may mount a network attached file system. In this case, it would need to be mounted as a subdirectory of your configured anchor point in the file system.
To select one of these local projects instead of a Git repository, choose the “LOCAL” option on the “Select Repository” drop-down menu.
Selecting this option brings up the Select Project window on the left side of the screen. By default, it is anchored at /home. However, you can reposition this anchor point using the icrforpython -d as noted earlier in Section 3.2.2. From the Select Project frame, you can scroll down through directories and subdirectories looking for the desired project for analysis.
In this example, we will select a project called django which is located within the directory python-projects (which is displayed as the Base Directory Path). Clicking on Add Project brings the project into our list of available projects.
The project has now been added to the list of locally accessible projects available for analysis. Note that the Analyze, Review and Remove buttons are now available. The Review button is grayed out until an analysis is complete and results are available for review. The Version button allows you to specify the required Python library version needed for this local project and operates as described in Section 4.5.24.5.2. The Remove button allows you to drop this project form the list of available projects.
Note: If you choose to remove a project ALL OF ITS RESULTS will also be deleted. This includes ALL of the history of Rejected bugs (See Section 6.4.5).
You can add as many projects as you wish.
The status shown on the left indicates that the Analysis Engine is available for use.
Below the banner on the left side opposite the Engine Status is where you start the process of selecting your source code to be analyzed or reviewed. Your first step is to select the repository where your project resides. iCR for Python is best used when working with a commercial Version-Control System (VCS) like GitHub, GitLab or Bitbucket. The button is a drop-down menu from which you can select your VCS. Or you can set up a path to a local directory on your server where you have uploaded your project.
