This section explains the basics of looking for artefacts using filters and search. For a more automated way to find artefact that fit a specific category, take a look at the section called “Finding Artefacts Using Highlights”.

Click the Filter icon () in the top-right corner of the Explorer to reveal the Filter Panel. The Filter Panel allows you to set criteria that artefacts need to meet in order to be displayed in the artefact tree or taken into account in charts on the dashboard (new in 18.0). For this example, we want to restrict the visibility of artefacts to those rated E and lower:

The Filter Panel with the boxes checked to filter artefacts rated E and lower

Click Apply to apply the changes The Artefact Tree and the dashboard refresh to show results for the artefacts in the levels selected, as shown below:

The filtered Explorer showing artefacts rated E and lower

The notice Filter active is always displayed above the Artefact Tree and the filter icon turns orange when you are using a filter. The tree now only shows artefacts rated E and lower, along with their ancestors, which are greyed out (new in 18.0) if they are not rated E and lower. On the dashboard, the charts that support displaying filtered information are highlighted with an orange filter icon () as in the Function Complexity Map (new in 18.0).

Tip

You can save your filter for later use and even share it with other Squore users (new in 18.0) by clicking the hamburger menu in the Filter Panel and giving your filter a name.

The filter saving options

Saved filters are displayed in the dropdown list at the top of the Filter Panel so you can reuse them later.

The list of saved filters

For more details about advanced filtering functionality in Squore, consult the section called “Advanced Filtering”.

While a filter is active, you can still search for other artefacts by typing a search term in the search box. Try typing ma in the search box above the Artefact Tree, and watch the search results list get populated as you type:

The search results for the term entered in the search box

If you select the highlighted search result in the list above, you will open the dashboard for machine.h.

Let's go back to our filtered tree. The filter singled out three files whose rating deteriorated that contain functions in the required score range: player.c, machine.c and write.c. Click on the artefact player.c to view its dashboard. Note how the score card indicates that the artefact has more critical issues than in the previous analysis.

One more critical issue for player.c in this version

You can click the link in the table to directly view the new critical violation on the Findings tab. In this case, the rule BRKFINAL was broken:

A new critical issue for player.c in this version

Another convenient way to try and find why a project's quality is deteriorating is to filter on the trend of an artefact.

Select version V6 of Earth again and edit the active filter: Uncheck the boxes for levels E and lower, and select the Deteriorated category in the Evolution section. When applying the filter, you should see the artefacts in the tree that have the icon next to their name.

The artefacts that deteriorated in version V6 of Earth

The files you inspected earlier are still here, but there are more deteriorated artefacts that you can start reviewing. If you click on hi_scores_disp(int) for example, which is rated E.

In order to find out where the degradation took place, you can look at the indicators tree to understand where the decline in quality comes from. Expand all the nodes in the indicators tree to reveal the issues with the artefact:

The Indicator Tree for hi_scores_disp(int)

Squore makes it easy to spot the irregularities quickly, like the fact that the Rule Compliance indicator is one of the causes for the worse score in this version. This is probably the first item to review in this function.

By clicking the Rule Compliance indicator in the tree, you can learn more about its history and how it is computed:

The description and history of the Rule Compliance indicator for hi_scores_disp(int)

Finally, you can take a look at the Coding Rules Compliance section of the artefact's scorecard to confirm the results:

The scorecard for hi_scores_disp(int)

By clicking the link icon, you can directly view the violations for this artefact in the Findings tab.

You can dive further into the analysis results by looking at the information contained in other tabs and assign action items to your team by referring to Chapter 6, Managing Your To-Do List With Squore or report your progress as explained in Chapter 10, Communicating With Squore.

In the previous section, you learned how to filter artefacts based on their overall rating or trend, but Squore allows you to filter on more than the artefact's main indicator. This section covers filtering on more than one metric, and how you can also save and share your filters with other Squore users.

This example explores how to develop a strategy to reduce cloning in your application by finding the artefacts with the highest cloning that have also been modified since the previous analysis.

Start by displaying the dashboard for version V6 of Earth. In the Filter Panel, clear any existing filter by selecting [Default Filters] and clicking Apply to go back to an unfiltered dashboard.

The [Default Filters] in the Filter Panel

In order to find artefacts that have recently been modified, use Squore's Stability Index indicator, a feature of the source code parser that computes the amount of changes in a file since the previous analysis. Add a filtering criterion by clicking Add Filter... in the Filter Panel. A popup appears so you can type the name of the indicator to filter on. Type stability and select Code Stability Index as shown below:

The Filter Panel showing metrics whose names match stability

Clicking Add updates the Filter Panel with a section where you can select Code Stability Index levels to filter on. Since 100% means no changes, select all the levels except for 100%:

The Code Stability Index filter in the Filter Panel (other filters minimised for clarity)

In order to find artefacts with the worst cloning, click Add Filter..., select Measure and find the metric called Cloned Code (CC). Configure this filter as a slider so we can dynamically change the range of cloning to look out for:

The slider option selected for the Code Cloning metric in the filter popup

Click Add to add your filter. The slider shows you the minimum and maximum values for cloning in this project. Values can be modified either by entering values in the text boxes or by moving the sliders left and right. Move the left slider to about half the range for Code Cloning.

The slider for Code Cloning in the Filter Panel

When clicking Apply to view the results of your filter, the artefact player.c is singled out as a recently modified file with high cloning. By switching to the Tester dashboard, you can view details about its stability index in the score card.

The Stability Index Information for player.c

Clicking the Findings tab allows you to confirm that the cloning detected by Squan Sources was indeed introduced since the latest analysis.

The new cloning violation for player.c

Since this is a new finding in a recently modified file, it makes sense to address the issue to avoid creeping technical debt in the project.

If you want to repeat this exploration at a later time, you can save the filter you just created.

In order to save a filter, click the hamburger menu in the Filter Panel and select Save as.... The Save Filter popup appears and gives you the option to:

After you save a filter it becomes available in the drop down list of filters in the Filter Panel:

In the previous section (the section called “Finding Artefacts Using Filters and Search”), you got familiar with searching and filtering to find the artefact that have a negative impact on the overall rating of a project. in this section, you will learn to master the Highlights functionality, which aims to make the process of finding certain categories of artefacts easier and allows to display additional information about each artefact.

Highlights are flat lists of artefacts ordered in predefined categories for a model.

Let's try to confirm our findings about the worst and most deteriorated artefacts in Earth. Click on the version V6 of Earth and clear the filter. Click the Highlights tab of the Explorer and select the Top 10 worst artefacts category. The list appears as shown below:

The Top 10 worst artefacts in the current version of Earth

The list confirms that some fo the worst-rated artefacts are the ones you explored before. The Highlights table shows you the artefact rating, name and path, and allows you to go to the artefact's dashboard directly by clicking the artefact name.

Now you can also find the deteriorated artefact hi_scores_disp(int) that you identified with a filter earlier in the section called “Finding Artefacts Using Filters and Search”: select the Top 10 most deteriorated artefacts highlight category to see the artefact appear in the list of deteriorated artefacts in this version.

The Top 10 most deteriorated artefacts in the current version of Earth

Artefacts are sorted by degradation, i.e. the difference between the value of the main indicator in the previous baseline version compared to the current value. By clicking the Export button, you can export the selected items to a CSV file. If the Export button is greyed out, your licence does not include the option to export data to CSV files.

From the Highlights tab, you can also create new highlight categories (new in 18.0). These new categories, like your filters can be saved and shared with other Squore users.

Let's extract more data from the artefacts singled out by your advanced filter in the section called “Advanced Filtering”, where you found recently modified code with a high cloning ratio. To begin, simply select your saved filter from the Filter Panel and apply it. As you apply and modify the filter, the list of artefacts for the current highlight responds to the filter parameters:

Let's now build a highlight from scratch that uses the same filters and displays more information about the artefacts. Click the hamburger menu next to the list of highlight categories and select Add Definition. The popup that opens lets you configure the data columns to display for each artefact, as well as apply filters the same way you did in the Filter Panel:

The Highlights Definition popup

The values in the popup above reproduce conditions of the filter you used earlier:

Click Add to create the highlight and view the results. You can also clear the current filter, since the highlight category defines the same conditions.

Your basic highlight definition for modified artefacts with cloning

In order to add information about the artefacts displayed in the list, click the hamburger menu and select Edit.... The Columns section fo the popup lets you select additional data to display about each artefact. It makes sense to display the cloning ratio and stability details, as well as other indicators and metrics that will help you decide if modifying the code is risky or safe.

Adding columns to the new highlight category

When you click Update, the highlight category now shows all the requested details for the artefacts:

The extra columns for your new highlight category