EiffelStudio: an EiffelSoftware project - User contributions [en]

User:Stefan

2014-05-02T10:14:54Z

Stefan: update

I am a student of Computer Science at the ETH Zürich, Switzerland. There, for my Master thesis, I created ''Inspector Eiffel'', a [[/Code Analysis/]] tool for EiffelStudio. Prior to this I earned my Bachelors degree in Mathematics from the Universität Bern, Switzerland. I also did an IT internship with an airline company.

CA UI Implementation

2014-03-20T14:09:17Z

Stefan: new name

<center>[[User:Stefan/Code Analysis/Library Implementation|<< 7. Library Implementation]] |</center>
----
 

== Graphical User Interface ==

The classes of the graphical user interface of Inspector Eiffel are all located in the ''interface'' cluster of EiffelStudio, in the subfolder ''graphical > tools > code_analysis''. Here is a short overview of what the single classes do:

; <e>{ES_CODE_ANALYSIS_TOOL}</e> : Represents the code analysis GUI tool. Contains the tool title and icon, otherwise not much interesting stuff.
; <e>{ES_CODE_ANALYSIS_TOOL_PANEL}</e> : The graphical panel for the code analysis tool. It contains buttons, labels, the rule violations table view, and other user interface elements.
; <e>{ES_CODE_ANALYSIS_COMMAND}</e> : The command to launch the code analyzer. It can be added to toolbars and menus. It can be executed using stones. This class also handles the caching.
; <e>{ES_CODE_ANALYSIS_BENCH_HELPER}</e> : A helper class for the integration of the code analysis tool. It contains shared instances of <e>{CA_CODE_ANALYZER}</e> and <e>{ES_CODE_ANALYSIS_COMMAND}</e>, which are used by the GUI.
; <e>{ES_CA_SHOW_PREFERENCES_COMMAND}</e> : The command is used by the ''Preferences'' button in the panel.
; <e>{ES_CA_FIX_EXECUTOR}</e> : This class [[User:Stefan/Code Analysis/Using Analysis Results#Fixing Rule Violations|fixes]] a rule violation that has been found by the code analysis tool.

These are roughly the class relations for the Inspector Eiffel GUI:
[[File:CA GUI Diagram.png|thumb|center|650px|The most interesting class relations of the Inspector Eiffel GUI.]]

=== Caching ===

It is a common case that GUI users run the code analyzer again after having made some changes to the code. We do not need to analyze the same unchanged code again and again. Therefore code analysis caches the results in memory. This only applies to the GUI mode.

Code analysis uses cached results exactly in one case: when the whole system is analyzed and the previous analysis was on the whole system, too.

The caching functionality is implemented in <e>{ES_CODE_ANALYSIS_COMMAND}</e>. When the command for analyzing the system is executed, the timestamps of the last modification of the classes are stored in <e>analysis_timestamp : HASH_TABLE [INTEGER, CLASS_I]</e> before the analysis. Note that the cached results (the rule violations) themselves are managed by <e>{CA_CODE_ANALYZER}</e>. The only difference to a non-cached analysis is that the rule violations are not deleted by <e>{ES_CODE_ANALYSIS_COMMAND}</e> before the next analysis. Then, in case the next command is also for analyzing the whole system, the current timestamps are compared to the stored timestamps. Any class that has been changed in the meantime will be analyzed again; for any unchanged class the rule violations are taken from the cache.

=== Example Command: Analyze One Class ===

We will now roughly go through the code that is executed on the GUI part when the user wants to analyze a single class. As mentioned in Chapter [[User:Stefan/Code Analysis/Running the Analyzer|Running the Analyzer]], this can be done using the class context menu or by dropping the class stone on the button ''Analyze Item''.

In any case <e>{ES_CODE_ANALYSIS_COMMAND}.execute_with_stone</e> is called, which delegates to <e>execute_with_stone_content</e>:

<e>
execute_with_stone (a_stone: STONE)
-- Execute with `a_stone'.
do
execute_with_stone_content (a_stone, Void)
end

execute_with_stone_content (a_stone: STONE; a_content: SD_CONTENT)
-- Execute with `a_stone'.
local
l_save_confirm: ES_DISCARDABLE_COMPILE_SAVE_FILES_PROMPT
l_classes: DS_ARRAYED_LIST [CLASS_I]
do
-- Show the tool right from the start.
show_ca_tool

if not eiffel_project.is_compiling then
if window_manager.has_modified_windows then
create l_classes.make_default
window_manager.all_modified_classes.do_all (agent l_classes.force_last)
create l_save_confirm.make (l_classes)
l_save_confirm.set_button_action (l_save_confirm.dialog_buttons.yes_button, agent save_compile_and_analyze (a_stone))
l_save_confirm.set_button_action (l_save_confirm.dialog_buttons.no_button, agent compile_and_analyze (a_stone))
l_save_confirm.show_on_active_window
else
compile_and_analyze (a_stone)
end
end
end
</e>

If there are modified, unsaved windows a save confirmation dialog is displayed. Eventually program flow passes on to <e>compile_and_analyze</e>:

<e>
compile_and_analyze (a_stone: STONE)
-- Compile project and perform analysis of stone `a_stone'.
local
l_helper: ES_CODE_ANALYSIS_BENCH_HELPER
l_dialog: ES_INFORMATION_PROMPT
do
-- Compile the project and only analyze if the compilation was successful.
eiffel_project.quick_melt (True, True, True)
if eiffel_project.successful then
create l_helper
if l_helper.code_analyzer.is_running then
create l_dialog.make_standard (ca_messages.already_running_long)
l_dialog.show_on_active_window
else
perform_analysis (a_stone)
end
end
end
</e>

<e>eiffel_project.quick_melt</e> starts the compilation. A successful compilation is required for code analysis; otherwise nothing is analyzed. After compilation has succeeded we check if code analysis is already running. If this is the case then a dialog is displayed. If on the other hand this last possible obstacle is not present we finally start analyzing by calling <e>perform_analysis</e>.

<e>
perform_analysis (a_stone: STONE)
-- Analyze `a_stone' only.
local
l_helper: ES_CODE_ANALYSIS_BENCH_HELPER
l_scope_label: EV_LABEL
do
-- For simplicity let us assume that `a_stone' does not
-- correspond to the system or is equivalent to it.
last_was_analyze_all := False

create l_helper
code_analyzer := l_helper.code_analyzer
code_analyzer.clear_classes_to_analyze
code_analyzer.rule_violations.wipe_out

l_scope_label := ca_tool.panel.scope_label

if attached {CLASSC_STONE} a_stone as s then
code_analyzer.add_class (s.class_i.config_class)
l_scope_label.set_text (s.class_name)
l_scope_label.set_foreground_color (create {EV_COLOR}.make_with_8_bit_rgb (140, 140, 255))
l_scope_label.set_pebble (s)
l_scope_label.set_pick_and_drop_mode
l_scope_label.set_tooltip (ca_messages.class_scope_tooltip)
elseif [...]
[...]
end

disable_tool_button
window_manager.display_message (ca_messages.status_bar_running)
code_analyzer.add_completed_action (agent analysis_completed)
code_analyzer.analyze
end
</e>

(The code that deals with stones other than classes is omitted.)

At the start of the routine the code analyzer instance is retrieved from the helper class. All classes that may have been addedbefore, are removed. All previous rule violations are removed as well. The if clause creates a stone for the ''Last Scope'' label in the graphical panel. Then, the button in the tool is disabled so that starting another analysis is prevented until the current one has completed. Finally, the analysis is started. As soon as the analysis has completed <e>{ES_CODE_ANALYSIS_COMMAND}.analysis_completed</e> is called. In this procedure the rule violations (and possibly the exceptions) are retrieved from the code analyzer and displayed in the list in the tool panel.

== Command-Line Interface ==

The whole command-line functionality of the code analyzer is located in the class <e>{EWB_CODE_ANALYSIS}</e>. It is located in the ''tty'' cluster of EiffelStudio. <e>{EWB_CODE_ANALYSIS}</e> is invoked by <e>{ES}</e>, the root class for the ''batch'' (command-line) version of EiffelStudio. In <e>{ES}</e>, the invocation looks as follows:

<e>
elseif option.is_equal ("-code-analysis") then
l_at_args := arguments_in_range (current_option + 1, argument_count)
current_option := argument_count + 1
create {EWB_CODE_ANALYSIS} command.make_with_arguments (l_at_args)
</e>

Any command-line arguments after ''-code-analysis'' are passed on to <e>{EWB_CODE_ANALYSIS}</e>. This class, in its creation procedure, processes the arguments as described in [[User:Stefan/Code_Analysis/Command Line Usage|Command Line Usage]]. Classes that were passed as command-line arguments are added to the analyzer. Then the actual execution happens in the procedure <e>execute</e>. <e>EWB_CODE_ANALYSIS</e> of course uses the ''code_analysis'' library and the previously described interface of <e>CA_CODE_ANALYZER</e>. After analysis a list of rule violations is output to the command-line. In the code it looks like this:

<e>
across l_code_analyzer.rule_violations as l_vlist loop
if not l_vlist.item.is_empty then
l_has_violations := True
-- Always sort the rule violations by the class they are referring to.
output_window.add (ca_messages.cmd_class + l_vlist.key.name + "':%N")

-- See `{CA_RULE_VIOLATION}.is_less' for information on the sorting.
across l_vlist.item as ic loop
l_rule_name := ic.item.rule.title
l_rule_id := ic.item.rule.id
if attached ic.item.location as l_loc then
l_line := ic.item.location.line.out
l_col := ic.item.location.column.out
output_window.add (" (" + l_line + ":" + l_col + "): "
+ l_rule_name + " (" + l_rule_id + "): ")
else -- No location attached. Print without location.
output_window.add (" " + l_rule_name + " (" + l_rule_id + "): ")
end
ic.item.format_violation_description (output_window)
output_window.add ("%N")
end
end
end

if not l_has_violations then output_window.add (ca_messages.no_issues + "%N") end
</e>

CA Library Implementation

2014-03-20T14:08:24Z

Stefan: new name

<center>[[User:Stefan/Code Analysis/Adding New Rules|<< 6. Adding New Rules]] | [[User:Stefan/Code Analysis/UI Implementation|8. UI Implementation > >]]</center>
----
 

The code for Inspector Eiffel is located at three different places in the EiffelStudio source:
# The framework—by far the largest part, with the rule checking, the rules, the control flow graph functionality, and more—is represented as a ''library'';
# The graphical user interface can be found in the ''interface'' cluster of EiffelStudio;
# The command-line interface for code analysis is a single class in the ''tty'' cluster of EiffelStudio.

The whole '''Inspector Eiffel framework''' is located in the '''library ''code_analysis'''''.

== Class Relations ==

The following diagram shows an overview of the relations between the classes of the code analysis framework. All classes are located in the ''code_analysis'' library except for <e>CLASS_C</e> (EiffelStudio), <e>ROTA_TIMED_TASK_I</e> (''ecosystem'' cluster), <e>EWB_CODE_ANALYSIS</e> (command-line interface), and <e>ES_CODE_ANALYSIS_BENCH_HELPER</e> (GUI).

[[File:CA Framework Diagram.png|thumb|center|800px|The most interesting classes of the code analysis framework.]]

== Interface ==

In this section it is explained from a client view how to use the code analyzer. The code analyzer is represented by the class <e>CA_CODE_ANALYZER</e>, so a client must have or access an instance of this class. Before the analyzer can be launched all the classes that shall be analyzed must be added using one of the following features. If you use more than one of these commands then the added classes from all commands will be conjoined.
; <e>{CA_CODE_ANALYZER}.add_whole_system</e> : Adds all the classes that are part of the current system. Classes of referenced libraries will not be added. So, for example, if your system consists of the classes <e>MY_MAIN</e>, <e>MY_BOX</e>, and <e>MY_ITEM</e> then these three classes will be added to the list of classes to be analyzed.
; <e>.add_class (a_class: attached CONF_CLASS)</e> : Adds a single class.
; <e>.add_classes (a_classes: attached ITERABLE [attached CONF_CLASS])</e> : Adds a list of classes.
; <e>.add_cluster (a_cluster: attached CLUSTER_I)</e> : Adds all classes of a cluster (and all the classes of the sub-clusters recursively).
; <e>.add_group (a_group: attached CONF_GROUP)</e> : Adds all classes of a configuration group. An example of a configuration group is a ''library''.

Here are other features which can be called before starting to analyze:
; <e>{CA_CODE_ANALYZER}.clear_classes_to_analyze</e> : Removes all classes that have been added to the list of classes to analyze.
; <e>.add_completed_action (a_action: attached PROCEDURE [ANY, TUPLE [ITERABLE [TUPLE [detachable EXCEPTION, CLASS_C]]]])</e> : Adds <e>`a_action'</e> to the list of procedures that will be called when analysis has completed. The procedures have one argument, a list of exceptions (with the corresponding class). In the case an exception is thrown during analysis the exception is caught by the code analyzer and is added to this list. In the graphical user interface such exceptions would show up as errors at the top of the list of rule violations.
; <e>.add_output_action (a_action: attached PROCEDURE [ANY, TUPLE [READABLE_STRING_GENERAL]])</e> : Adds <e>`a_action'</e> to the procedures that are called for outputting the status. The final results (rule violations) are not given to these procedures. These output actions are used by the command-line mode and by the status bar in the GUI.
; <e>.is_rule_checkable (a_rule: attached CA_RULE): BOOLEAN</e> : Tells whether <e>`a_rule'</e> will be checked based on the current preferences and based on the current checking scope (whole system or custom set of classes).

Then, to start analyzing simply call <e>{CA_CODE_ANALYZER}.analyze</e>.

== Rule Checking ==

In the GUI we want to be able to continue to work while the code analyzer is running. Analyzing larger sets of classes (such as whole libraries) can take from several seconds to several minutes. For this reason the code analyzer uses an ''asynchronous task'', <e>{CA_RULE_CHECKING_TASK}</e>. In <e>{CA_CODE_ANALYZER}.analyze</e> this task (<e>l_task</e>) is invoked as follows:

=== In <e>{CA_CODE_ANALYZER}.analyze</e>: ===

<e>
create l_task.make (l_rules_checker, l_rules_to_check, classes_to_analyze, agent analysis_completed)
l_task.set_output_actions (output_actions)
rota.run_task (l_task)
</e>

<e>{CA_RULE_CHECKING_TASK}</e> essentially runs the whole analysis. Like all other conformants to <e>{ROTA_TASK_I}</e> this class executes a series of ''steps'' between which the user interface gets some time to process its events. In <e>{CA_RULE_CHECKING_TASK}</e> each step analyses one class. This means that a class is checked by ''all'' the rules for violations. The following code does that:

=== From <e>{CA_RULE_CHECKING_TASK}</e>: ===

<e>
step
-- <Precursor>
do
if has_next_step then
-- Gather type information
type_recorder.clear
type_recorder.analyze_class (classes.item)
context.set_node_types (type_recorder.node_types)
context.set_checking_class (classes.item)

across rules as l_rules loop
-- If rule is non-standard then it will not be checked by l_rules_checker.
-- We will have the rule check the current class here:
if
l_rules.item.is_enabled.value
and then attached {CA_CFG_RULE} l_rules.item as l_cfg_rule
then
l_cfg_rule.check_class (classes.item)
end
end

-- Status output.
if output_actions /= Void then
output_actions.call ([ca_messages.analyzing_class (classes.item.name)])
end

rules_checker.run_on_class (classes.item)

classes.forth
has_next_step := not classes.after
if not has_next_step then
completed_action.call ([exceptions])
end
end
rescue
-- Instant error output.
if output_actions /= Void then
output_actions.call ([ca_messages.error_on_class (classes.item.name)])
end
exceptions.extend ([exception_manager.last_exception, classes.item])
-- Jump to the next class.
classes.forth
has_next_step := not classes.after
if not has_next_step then
completed_action.call ([exceptions])
end
retry
end
</e>

<e>type_recorder</e> is of type <e>{CA_AST_TYPE_RECORDER}</e>. It uses a functionality of the Eiffel compiler to determine the type of some AST nodes in the current class. The AST itself (as provided by the Eiffel compiler) does not contain any type information. <e>context</e> has type <e>{CA_ANALYSIS_CONTEXT}</e> and contains any side-information such as the previously mentioned types and the current class. The rules were given this context before so that they can access it when needed.

The <e>across</e> loop only checks ''control flow graph rules''. All the ''standard'' rules are checked by the line <e>rules_checker.run_on_class (classes.item)</e>. <e>rules_checker</e> has type <e>{CA_ALL_RULES_CHECKER}</e>. This is the class where each rule must register the AST nodes the rule visits. <e>run_on_class</e> iterates over the AST and calls all the actions that were registered by the standard rules. So this is the way all rules are used to check the current class. <e>step</e> is executed repeatedly until there are no classes left to analyze.

In the <e>rescue</e> clause all possible exceptions are caught and recorded. In case of such an exception it then proceeds to the next class.

=== Checking ''Standard'' Rules ===

The relatively large class <e>{CA_ALL_RULES_CHECKER}</e> is responsible for checking ''standard rules''. It does this in a straightforward way. It is a subclass of <e>{AST_ITERATOR}</e>, a realization of a visitor on the AST.

Rules can register their actions with <e>{CA_ALL_RULES_CHECKER}</e> by calling a procedure like <e>add_bin_lt_pre_action (a_action: attached PROCEDURE [ANY, TUPLE [BIN_LT_AS]])</e> or <e>add_if_post_action (a_action: attached PROCEDURE [ANY, TUPLE [IF_AS]])</e>. These "pre" and "post" actions exist for many other types of AST nodes as well. All the registered actions are stored in <e>ACTION_SEQUENCE</e> variables:
<e>
if_pre_actions, if_post_actions: ACTION_SEQUENCE [TUPLE [IF_AS]]

add_if_post_action (a_action: attached PROCEDURE [ANY, TUPLE [IF_AS]])
do
if_post_actions.extend (a_action)
end

-- And similar for all other relevant AST nodes...
</e>

The corresponding visitor procedures are redefined. This is done is the following way:
<e>
process_if_as (a_if: IF_AS)
do
if_pre_actions.call ([a_if])
Precursor (a_if)
if_post_actions.call ([a_if])
end

-- And similar for all other relevant AST nodes...
</e>

Since the actual iteration over the AST is done in the ancestor we need only very little code to analyze a class:
<e>
feature {CA_RULE_CHECKING_TASK} -- Execution Commands

run_on_class (a_class_to_check: CLASS_C)
-- Check all rules that have added their agents.
local
l_ast: CLASS_AS
do
last_run_successful := False
l_ast := a_class_to_check.ast
class_pre_actions.call ([l_ast])
process_class_as (l_ast)
class_post_actions.call ([l_ast])
last_run_successful := True
end
</e>

This code analyzes a class for all active ''standard'' rules. <e>class_pre_actions</e> and <e>class_post_actions</e> are action sequences that are identical to those for the AST nodes. <e>process_class_as</e>, which is implemented in <e>{AST_ITERATOR}</e> will recursively visit all relevant AST nodes and execute their action sequences.

== Example: Rule # 71: ''Self-comparison'' ==

We will go through the implementation of rule # 71 (''Self-comparison'') in detail.

The heart of this implementation lies in the feature <e>analyze_self</e>. There it is tested whether a binary expression is s self-comparison. <e>is_self</e>, a <e>BOOLEAN</e> attribute, is set to true if and only if the argument is a comparison between two identical variables.

<e>
analyze_self (a_bin: attached BINARY_AS)
-- Is `a_bin' a self-comparison?
do
is_self := False

if
attached {EXPR_CALL_AS} a_bin.left as l_e1
and then attached {ACCESS_ID_AS} l_e1.call as l_l
and then attached {EXPR_CALL_AS} a_bin.right as l_e2
and then attached {ACCESS_ID_AS} l_e2.call as l_r
then
is_self := l_l.feature_name.is_equal (l_r.feature_name)
self_name := l_l.access_name_32
end
end

is_self: BOOLEAN
-- Is `a_bin' from last call to `analyze_self' a self-comparison?

self_name: detachable STRING_32
-- Name of the self-compared variable.
</e>

Both sides of the comparison, <e>a_bin.left</e> and <e>a_bin.right</e>, are tested to have the types that indicate that they are variable or feature accesses. If the tests succeed then <e>is_self</e> is set according to the equality of the two feature names. Then the name is stored in an internal attribute.

<e>analyze_self</e> is used in <e>process_comparison</e>, which creates a rule violation if a self-comparison was detected.

<e>
process_comparison (a_comparison: BINARY_AS)
-- Checks `a_comparison' for rule violations.
local
l_viol: CA_RULE_VIOLATION
do
if not in_loop then
analyze_self (a_comparison)
if is_self then
create l_viol.make_with_rule (Current)
l_viol.set_location (a_comparison.start_location)
l_viol.long_description_info.extend (self_name)
violations.extend (l_viol)
end
end
end
</e>

First we check that we are not dealing with a loop condition. Self-comparisons in loop conditions are more dangerous and need special treatment (see below). For the rule violation, we set the location to the start location of the binary comparison. We add the variable or feature name to the violation.

Different kinds of comparisons also have different types in the AST. That is why in an AST iterator they are processed independently. Thus, we need to add some delegation to each of the actions that are called when processing a comparison.

<e>
process_bin_eq (a_bin_eq: BIN_EQ_AS)
do
process_comparison (a_bin_eq)
end

process_bin_ge (a_bin_ge: BIN_GE_AS)
do
process_comparison (a_bin_ge)
end

process_bin_gt (a_bin_gt: BIN_GT_AS)
do
process_comparison (a_bin_gt)
end

process_bin_le (a_bin_le: BIN_LE_AS)
do
process_comparison (a_bin_le)
end

process_bin_lt (a_bin_lt: BIN_LT_AS)
do
process_comparison (a_bin_lt)
end
</e>

In the case that a loop condition is a self-comparison, the loop is either never entered or it is never exited. The last case is more severe; the first case only arises with an equality comparison. For this reason we analyze loop conditions separately. If we find such a violation we set <e>in_loop</e> to <e>True</e> so that any further self-comparisons are ignored until we have left the loop.

<e>
pre_process_loop (a_loop: LOOP_AS)
-- Checking a loop `a_loop' for self-comparisons needs more work. If the until expression
-- is a self-comparison that does not compare for equality then the loop will
-- not terminate, which is more severe consequence compared to other self-comparisons.
local
l_viol: CA_RULE_VIOLATION
do
if attached {BINARY_AS} a_loop.stop as l_bin then
analyze_self (l_bin)
if is_self then
create l_viol.make_with_rule (Current)
l_viol.set_location (a_loop.stop.start_location)
l_viol.long_description_info.extend (self_name)
if not attached {BIN_EQ_AS} l_bin then
-- It is only a dangerous loop stop condition if we do not have
-- an equality comparison.
l_viol.long_description_info.extend ("loop_stop")
end
violations.extend (l_viol)
in_loop := True
end
end
end
</e>

<e>format_violation_description</e>, which is declared in <e>CA_RULE</e> as <e>deferred</e>, must be implemented. Here, together with a predefined localized text, we mention the name of the self-compared variable. If the self-comparison is located in a loop stop condition we add an additional warning text.

<e>
format_violation_description (a_violation: attached CA_RULE_VIOLATION; a_formatter: attached TEXT_FORMATTER)
local
l_info: LINKED_LIST [ANY]
do
l_info := a_violation.long_description_info
a_formatter.add ("'")
if l_info.count >= 1 and then attached {STRING_32} l_info.first as l_name then
a_formatter.add_local (l_name)
end
a_formatter.add (ca_messages.self_comparison_violation_1)

l_info.compare_objects
if l_info.has ("loop_stop") then
-- Dangerous loop stop condition.
a_formatter.add (ca_messages.self_comparison_violation_2)
end
end
</e>

Then we must implement the usual properties.

<e>
title: STRING_32
do
Result := ca_names.self_comparison_title
end

id: STRING_32 = "CA071"
-- <Precursor>

description: STRING_32
do
Result := ca_names.self_comparison_description
end
</e>

Finally, in the initialization we use the default settings, which can be set by calling <e>{CA_RULE}.make_with_defaults</e>. To the default severity score we assign a custom value. In <e>register_actions</e> we must add all the agents for processing the loop and comparison nodes of the AST.

<e>
feature {NONE} -- Initialization

make
-- Initialization.
do
make_with_defaults
default_severity_score := 70
end

feature {NONE} -- Activation

register_actions (a_checker: attached CA_ALL_RULES_CHECKER)
do
a_checker.add_bin_eq_pre_action (agent process_bin_eq)
a_checker.add_bin_ge_pre_action (agent process_bin_ge)
a_checker.add_bin_gt_pre_action (agent process_bin_gt)
a_checker.add_bin_le_pre_action (agent process_bin_le)
a_checker.add_bin_lt_pre_action (agent process_bin_lt)
a_checker.add_loop_pre_action (agent pre_process_loop)
a_checker.add_loop_post_action (agent post_process_loop)
end
</e>

The complete source code of this rule is available in the [https://svn.eiffel.com/eiffelstudio/branches/eth/eve/Src/framework/code_analysis/rules/expressions/ca_self_comparison_rule.e SVN repository].

== Example: Rule # 2: ''Unused argument'' ==

The ''unused argument'' rule processes the ''feature'', ''body'', ''access id'', and ''converted expression'' AST nodes. The feature node is stored for the description and for ignoring ''deferred'' features. The body node is used to retrieve the arguments. The ''access id'' and ''converted expression'' nodes may represent used arguments, so the nodes are used to mark arguments as read. We register the ''pre'' actions for all the AST nodes as well as the ''post'' action for the ''body'' node in <e>register_actions</e>.

<e>
feature {NONE} -- Activation

register_actions (a_checker: attached CA_ALL_RULES_CHECKER)
do
a_checker.add_feature_pre_action (agent process_feature)
a_checker.add_body_pre_action (agent process_body)
a_checker.add_body_post_action (agent post_process_body)
a_checker.add_access_id_pre_action (agent process_access_id)
a_checker.add_converted_expr_pre_action (agent process_converted_expr)
end
</e>

On processing a feature we store the feature instance, which will be used later.

<e>
process_feature (a_feature_as: FEATURE_AS)
-- Sets the current feature.
do
current_feature := a_feature_as
end
</e>

Before processing the body of a feature we store a list of all the argument names. This is however only done if the feature is a routine, if it has arguments, and if it is not external. In the code we need two nested loops since the arguments are grouped by type. For example, two consecutive <e>STRING</e> arguments as in <e>feature print(first, second: STRING)</e> are in one entry of <e>{BODY_AS}.arguments</e>. This single entry is itself a list of arguments.

<e>
process_body (a_body_as: BODY_AS)
-- Retrieves the arguments from `a_body_as'.
local
j: INTEGER
do
has_arguments := (a_body_as.arguments /= Void)
create args_used.make (0)
n_arguments := 0
if
attached a_body_as.as_routine as l_rout
and then has_arguments
and then not l_rout.is_external
then
routine_body := a_body_as
create arg_names.make (0)
across a_body_as.arguments as l_args loop
from
j := 1
until
j > l_args.item.id_list.count
loop
arg_names.extend (l_args.item.item_name (j))
args_used.extend (False)
n_arguments := n_arguments + 1
j := j + 1
end
end
end
end

has_arguments: BOOLEAN
-- Does current feature have arguments?

current_feature: FEATURE_AS
-- Currently checked feature.

routine_body: BODY_AS
-- Current routine body.

n_arguments: INTEGER
-- # arguments for current routine.

arg_names: ARRAYED_LIST [STRING_32]
-- Argument names of current routine.

args_used: ARRAYED_LIST [BOOLEAN]
-- Which argument has been used?
</e>

Both the nodes <e>{ACCESS_ID_AS}</e> and <e>{CONVERTED_EXPR_AS}</e> may represent used arguments. <e>{ACCESS_ID_AS}</e> is a usual variable usage, while <e>{CONVERTED_EXPR_AS}</e> stands for an argument used in inline C code (the dollar sign syntax: <e>$arg</e>). In both routines <e>check_arguments</e> is called eventually, which updates the internal data structures of our rule class.

<e>
process_access_id (a_aid: ACCESS_ID_AS)
-- Checks if `a_aid' is an argument.
do
check_arguments (a_aid.feature_name.name_32)
end

process_converted_expr (a_conv: CONVERTED_EXPR_AS)
-- Checks if `a_conv' is an argument used in the
-- form `$arg'.
local
j: INTEGER
do
if
attached {ADDRESS_AS} a_conv.expr as l_address
and then attached {FEAT_NAME_ID_AS} l_address.feature_name as l_id
then
check_arguments (l_id.feature_name.name_32)
end
end

check_arguments (a_var_name: attached STRING_32)
-- Mark an argument as used if it corresponds to `a_aid'.
local
j: INTEGER
do
from
j := 1
until
j > n_arguments
loop
if not args_used [j] and then arg_names [j].is_equal (a_var_name) then
args_used [j] := True
end
j := j + 1
end
end
</e>

<e>post_process_body</e> finally checks if there exist unused arguments. If this is the case then all the relevant variable names are stored in the rule violation. Also, the feature is stored (for the feature name). The location of the violation is set to the start of the routine body. No rule violation is issued if the feature is deferred.

<e>
post_process_body (a_body: BODY_AS)
-- Adds a violation if the feature contains unused arguments.
local
l_violation: CA_RULE_VIOLATION
j: INTEGER
do
if
a_body.content /= Void
and then not current_feature.is_deferred
and then has_arguments
and then args_used.has (False)
then
create l_violation.make_with_rule (Current)
l_violation.set_location (routine_body.start_location)
l_violation.long_description_info.extend (current_feature)
from
j := 1
until
j > n_arguments
loop
if not args_used.at (j) then
l_violation.long_description_info.extend (arg_names.at (j))
end
j := j + 1
end
violations.extend (l_violation)
end
end
</e>

All the information that was stored in the rule violation is used for the formatted description:

<e>
format_violation_description (a_violation: attached CA_RULE_VIOLATION; a_formatter: attached TEXT_FORMATTER)
local
j: INTEGER
do
a_formatter.add (ca_messages.unused_argument_violation_1)
from
j := 2
until
j > a_violation.long_description_info.count
loop
if j > 2 then a_formatter.add (", ") end
a_formatter.add ("'")
if attached {STRING_32} a_violation.long_description_info.at (j) as l_arg then
a_formatter.add_local (l_arg)
end
a_formatter.add ("'")
j := j + 1
end
a_formatter.add (ca_messages.unused_argument_violation_2)
if attached {FEATURE_AS} a_violation.long_description_info.first as l_feature then
a_formatter.add_feature_name (l_feature.feature_name.name_32, a_violation.affected_class)
end
a_formatter.add (ca_messages.unused_argument_violation_3)
end
</e>

The complete source code of this rule is available in the [https://svn.eiffel.com/eiffelstudio/branches/eth/eve/Src/framework/code_analysis/rules/features/ca_unused_argument_rule.e SVN repository].

CA Adding New Rules

2014-03-20T14:05:34Z

Stefan: new name

<center>[[User:Stefan/Code Analysis/Command Line Usage|<< 5. Command Line Usage]] | [[User:Stefan/Code Analysis/Library Implementation|7. Library Implementation >>]] </center>
----
 
The Inspector Eiffel framework was designed with regard to the fact that '''adding new rules''' should be as simple and as fast as possible. Looking at the initial set of rules that were implemented, nearly all of them have an implementation of less than 200 lines of code. Many of them use even less than 100 lines of code. Rules that search the code for certain patterns (this applies to the vast majority of rules) are particularly simple to implement.

This page shows you how to implement a rule in the form of a class. After you have written such a class you must add the rule to the list of rules. This list is populated in <e>{CA_CODE_ANALYZER}.make</e>. There, just below the lines where all the other rules are added add a line like

<e>rules.extend (create {YOUR_RULE}.make)</e>,

where <e>YOUR_RULE</e> must be replaced by the name of your rule class and the creation procedure (<e>make</e>) must be adapted if necessary.

== Standard Rules ==

All rules must conform to <e>CA_RULE</e>. The class you implement for a rule is on one hand responsible for checking the rule and contains metadata about the rule (i. e. title, description) on the other hand. As of now, rules must moreover conform to either <e>CA_STANDARD_RULE</e> or <e>CA_CFG_RULE</e>, both of which are subtypes of <e>CA_RULE</e>. A large number of possible rules are ''standard rules'', no matter whether they are trivial or more complicated.

All ''Standard rules'' are checked by iterating over the [http://en.wikipedia.org/wiki/Abstract_syntax_tree abstract syntax tree] (AST) of the class code. The developer who adds a new rule can very well ignore the details thereof. He needs to know however which AST nodes his rule needs to process. For each type of AST node you need to add an agent so your routine will be called during the iteration on the AST.

To start implementing your rule you have basically two possibilities. (1) You start from scratch, implementing all deferred features of <e>CA_STANDARD_RULE</e> or (2) you use the following template.

=== Standard Rule Template ===

<e>
class
CA_YOUR_RULE

inherit
CA_STANDARD_RULE

create
make

feature {NONE} -- Initialization

make (a_pref_manager: attached PREFERENCE_MANAGER)
-- Initialization for `Current'.
do
make_with_defaults
-- This initializes the attributes to their default values:
-- Severity = warning
-- Default Severity Score = 50 (`severity score' can be changed by user)
-- Rule enabled by default = True (`Rule enabled' can be changed by user)
-- Only for system wide checks = False
-- Checks library classes = True
-- Checks nonlibrary classes = True

initialize_options (a_pref_manager)

-- TODO: Add your initialization here.
end

initialize_options (a_pref_manager: attached PREFERENCE_MANAGER)
-- Initializes the rule preferences.
local
l_factory: BASIC_PREFERENCE_FACTORY
do
create l_factory

-- TODO: Add the initialization of your custom preferences here.
-- Example:
-- threshold := l_factory.new_integer_preference_value (a_pref_manager,
-- preference_namespace + "Threshold",
-- 30) -- default value
-- min_local_name_length.set_default_value ("30") -- default value, too
-- min_local_name_length.set_validation_agent (agent is_integer_string_within_bounds (?, 1, 1_000_000))
end

feature {NONE} -- Activation

register_actions (a_checker: attached CA_ALL_RULES_CHECKER)
do
-- TODO: Add agents for the features in section `Rule checking' here.
end

feature {NONE} -- Rule checking

-- TODO: Add the AST processing here.

feature -- Properties

title: STRING_32
do
-- TODO: Add the title of your rule here.
Result := "(Your title)"
end

-- TODO: Add the ID of your rule here. Should be unique!
id: STRING_32 = "(YourID)"

description: STRING_32
do
-- TODO: Add the rule description here.
Result := "(Your description)"
end

format_violation_description (a_violation: attached CA_RULE_VIOLATION; a_formatter: attached TEXT_FORMATTER)
do
-- TODO: Add a formatted description of a concrete violation of this rule here.
end

end
</e>

Let us have a closer look at the various parts of a rule class.

=== Initialization ===

Calling <e>make_with_defaults</e> initializes the attributes to their default values and makes sure that the class invariant is true. If you want to set an attribute to a custom value you can do so by setting it after the call to <e>make_with_defaults</e>.

The creation procedure from the template takes an argument of type <e>PREFERENCE_MANAGER</e>. This is used for initializing preferences that are specific to your rule. Such preferences usually represent integral or boolean values. If you do ''not'' need any custom preferences then you can leave out the argument <e>a_pref_manager</e> of <e>make</e> and you can remove the whole <e>initialize_options</e> feature.

=== AST Processing ===

The main part of your rule implementation consists of checking the source code for rule violations. Say, for example, that you want to check <e>if</e> instructions to have certain properties. Then you would add a feature like <e>process_if (a_if_ast: IF_AS)</e> to the section ''Rule checking''. Also, you would need to modify the <e>register_actions</e> feature by adding the line

<e>a_checker.add_if_pre_action (agent process_if)</e>.

Of course you may register as many such agents as you want.

=== Properties ===

The ''title'' and the ''description'' of the rule may be constant strings, they may also be localized strings. The ''rule ID'' must be unique among all rules. It should not contain spaces and should be reasonably short. The main rules that come with ''Code Analysis'' have IDs that are numbered from CA001 to CA999 (many of which are not used).

=== Formatted Violation Description ===

Your rule should be able to produce a formatted description of a concrete rule violation. This description is for example used in the Code Analysis tool panel of the GUI. There, class names and feature names are enabled for pick-and-drop. Variable names, numbers, and strings will be displayed in a nice way, too. In addition, this description is used in command line mode. In order to produce normal, unformatted text, use <e>{TEXT_FORMATTER}.add</e>. For adding formatted elements use features like <e>{TEXT_FORMATTER}.add_local</e>, <e>{TEXT_FORMATTER}.add_feature_name</e> and similar.

You should store all the data you need for this description (variables names, numbers, etc.) in <e>{CA_RULE_VIOLATION}.long_description_info</e>. <e>format_violation_description</e> can then retrieve this data for the formatted output. Here is a simple example of producing a formatted description:

<e>
a_formatter.add ("Feature ")
if attached {STRING_32} a_violation.long_description_info.first as l_feat_name then
a_formatter.add_feature_name (l_feat_name, a_violation.affected_class)
end
a_formatter.add (" is very long.")
</e>

== More Customized Rules ==

For rules that do not fit into a simple AST visitor scheme you best inherit your rule from <e>{CA_STANDARD_RULE}</e>, too. You can for example register agents that get called when a ''class'' or a ''feature'' is processed. Based on these agents you can perform your customized analysis on the classes and/or features. Using ''multiple inheritance'' or just aggregation it should hardly be a problem to include any functionality you need for your analysis.

== Accessing Type Information ==

The AST classes do not contain ''type information''. Suppose your rule processes function calls. Feature calls in the AST do not contain any information on the types, such as the type of the result.

The code analysis framework however provides functionality to retrieve the type of AST nodes. Before the analyzer lets a class be analyzed by all the rules it computes the types of the AST nodes of a class. Hence this data will be available to your rule afterwards.

While your rule is being checked you can retrieve the type of node <e>a_node</e> from feature <e>a_feature</e> by calling <e>current_context.node_type (a_node: AST_EIFFEL; a_feature: FEATURE_I)</e>. <e>{CA_RULE}.current_context</e> is of type <e>{CA_ANALYSIS_CONTEXT}</e> and contains other information about current rule checking, too, such as the currently processed class or the matchlist for this class.

== Accessing the Control Flow Graph ==

Some kinds of static code analysis need and use the ''control flow graph'' of a program. The code analysis framework supports rules that use the control flow graph. If there is at least one such rule, the code analyzer computes the control flow graph of the procedures of the analyzed class before letting the ''rule'' check this class.

=== Worklist Algorithms ===

''Control flow graph rules'' iterate over the control flow graph. They do it using a ''worklist''—a list of CFG edges that still have to be processed. At the beginning, the worklist contains all edges of the control flow graph. The algorithm will pick edges from the worklist for processing in an arbitrary order. The iteration stops as soon as there are no more edges left in the worklist. How will the worklist get smaller? Each edge that is processed is removed from the worklist. After processing you will have to decide dynamically whether to add all the outgoing (or incoming, depending on the direction) edges to the worklist. Like this you can take the fact into account that some analyses need certain edges to be processed more than once (a fixed point iteration is such an example).

=== Implementation ===

A control flow analysis may iterate in either direction. For a forward-directed analysis inherit your rule from <e>{CA_CFG_FORWARD_RULE}</e>, for a backward analysis use <e>{CA_CFG_BACKWARD_RULE}</e> instead. In either case you will then have to implement the following deferred features:

; <e>initialize_processing (a_cfg: attached CA_CONTROL_FLOW_GRAPH)</e> : This is called before a routine is processed using the worklist. Essentially you may use it to initialize and prepare all the data structures you will need during analysis.
; <e>visit_edge (a_from, a_to: attached CA_CFG_BASIC_BLOCK): BOOLEAN</e> : This will be called when an edge is being visited. Here, you can put the analysis. If you let <e>Result = False</e> then no further edges will be added to the worklist. If in contrary you let <e>Result = True</e> then edges will be added to the worklist: In a ''forward'' analysis all the ''outgoing'' edges of the current one will be added; in a ''backward'' analysis all the ''incoming'' edges will be added.

=== Non-Worklist algorithms ===

If your control flow graph does not fit into the structure of an algorithm as described above you may directly inherit from <e>{CA_CFG_RULE}</e> and implement the feature <e>process_cfg (a_cfg: attached CA_CONTROL_FLOW_GRAPH)</e> (in addition to the features explained above). In this case you do not have to use a worklist; basically you can process the control flow graph in any way you want.

File:CA Cluster Context Menu.png

2014-03-20T13:55:42Z

Stefan: Stefan uploaded a new version of "File:CA Cluster Context Menu.png"

File:CA Class Context Menu.png

2014-03-20T13:55:12Z

Stefan: Stefan uploaded a new version of "File:CA Class Context Menu.png"

File:CA Analysis Buttons.png

2014-03-20T13:54:31Z

Stefan: Stefan uploaded a new version of "File:CA Analysis Buttons.png"

File:CA Sample Results.png

2014-03-20T13:53:48Z

Stefan: Stefan uploaded a new version of "File:CA Sample Results.png"

2014-03-11T11:52:53Z

Stefan: /* Example: Rule # 2: Unused argument */

<center>[[User:Stefan/Code Analysis/Adding New Rules|<< 6. Adding New Rules]] | [[User:Stefan/Code Analysis/UI Implementation|8. UI Implementation > >]]</center>
----
 

The code for Code Analysis is located at three different places in the ''EVE'' source:
# The framework—by far the largest part, with the rule checking, the rules, the control flow graph functionality, and more—is represented as a ''library'';
# The graphical user interface can be found in the ''interface'' cluster of ''EVE'';
# The command-line interface for code analysis is a single class in the ''tty'' cluster of ''EVE''.

The whole '''code analysis framework''' is located in the '''library ''code_analysis'''''.

== Class Relations ==

The following diagram shows an overview of the relations between the classes of the code analysis framework. All classes are located in the ''code_analysis'' library except for <e>CLASS_C</e> (EiffelStudio), <e>ROTA_TIMED_TASK_I</e> (''ecosystem'' cluster), <e>EWB_CODE_ANALYSIS</e> (command-line interface), and <e>ES_CODE_ANALYSIS_BENCH_HELPER</e> (GUI).

[[File:CA Framework Diagram.png|thumb|center|800px|The most interesting classes of the code analysis framework.]]

== Interface ==

In this section it is explained from a client view how to use the code analyzer. The code analyzer is represented by the class <e>CA_CODE_ANALYZER</e>, so a client must have or access an instance of this class. Before the analyzer can be launched all the classes that shall be analyzed must be added using one of the following features. If you use more than one of these commands then the added classes from all commands will be conjoined.
; <e>{CA_CODE_ANALYZER}.add_whole_system</e> : Adds all the classes that are part of the current system. Classes of referenced libraries will not be added. So, for example, if your system consists of the classes <e>MY_MAIN</e>, <e>MY_BOX</e>, and <e>MY_ITEM</e> then these three classes will be added to the list of classes to be analyzed.
; <e>.add_class (a_class: attached CONF_CLASS)</e> : Adds a single class.
; <e>.add_classes (a_classes: attached ITERABLE [attached CONF_CLASS])</e> : Adds a list of classes.
; <e>.add_cluster (a_cluster: attached CLUSTER_I)</e> : Adds all classes of a cluster (and all the classes of the sub-clusters recursively).
; <e>.add_group (a_group: attached CONF_GROUP)</e> : Adds all classes of a configuration group. An example of a configuration group is a ''library''.

Here are other features which can be called before starting to analyze:
; <e>{CA_CODE_ANALYZER}.clear_classes_to_analyze</e> : Removes all classes that have been added to the list of classes to analyze.
; <e>.add_completed_action (a_action: attached PROCEDURE [ANY, TUPLE [ITERABLE [TUPLE [detachable EXCEPTION, CLASS_C]]]])</e> : Adds <e>`a_action'</e> to the list of procedures that will be called when analysis has completed. The procedures have one argument, a list of exceptions (with the corresponding class). In the case an exception is thrown during analysis the exception is caught by the code analyzer and is added to this list. In the graphical user interface such exceptions would show up as errors at the top of the list of rule violations.
; <e>.add_output_action (a_action: attached PROCEDURE [ANY, TUPLE [READABLE_STRING_GENERAL]])</e> : Adds <e>`a_action'</e> to the procedures that are called for outputting the status. The final results (rule violations) are not given to these procedures. These output actions are used by the command-line mode and by the status bar in the GUI.
; <e>.is_rule_checkable (a_rule: attached CA_RULE): BOOLEAN</e> : Tells whether <e>`a_rule'</e> will be checked based on the current preferences and based on the current checking scope (whole system or custom set of classes).

Then, to start analyzing simply call <e>{CA_CODE_ANALYZER}.analyze</e>.

== Rule checking ==

In the GUI we want to be able to continue to work while the code analyzer is running. Analyzing larger sets of classes (such as whole libraries) can take from several seconds to several minutes. For this reason the code analyzer uses an ''asynchronous task'', <e>{CA_RULE_CHECKING_TASK}</e>. In <e>{CA_CODE_ANALYZER}.analyze</e> this task (<e>l_task</e>) is invoked as follows:

=== In <e>{CA_CODE_ANALYZER}.analyze</e>: ===

<e>
create l_task.make (l_rules_checker, l_rules_to_check, classes_to_analyze, agent analysis_completed)
l_task.set_output_actions (output_actions)
rota.run_task (l_task)
</e>

<e>{CA_RULE_CHECKING_TASK}</e> essentially runs the whole analysis. Like all other conformants to <e>{ROTA_TASK_I}</e> this class executes a series of ''steps'' between which the user interface gets some time to process its events. In <e>{CA_RULE_CHECKING_TASK}</e> each step analyses one class. This means that a class is checked by ''all'' the rules for violations. The following code does that:

=== From <e>{CA_RULE_CHECKING_TASK}</e>: ===

<e>
step
-- <Precursor>
do
if has_next_step then
-- Gather type information
type_recorder.clear
type_recorder.analyze_class (classes.item)
context.set_node_types (type_recorder.node_types)
context.set_checking_class (classes.item)

across rules as l_rules loop
-- If rule is non-standard then it will not be checked by l_rules_checker.
-- We will have the rule check the current class here:
if
l_rules.item.is_enabled.value
and then attached {CA_CFG_RULE} l_rules.item as l_cfg_rule
then
l_cfg_rule.check_class (classes.item)
end
end

-- Status output.
if output_actions /= Void then
output_actions.call ([ca_messages.analyzing_class (classes.item.name)])
end

rules_checker.run_on_class (classes.item)

classes.forth
has_next_step := not classes.after
if not has_next_step then
completed_action.call ([exceptions])
end
end
rescue
-- Instant error output.
if output_actions /= Void then
output_actions.call ([ca_messages.error_on_class (classes.item.name)])
end
exceptions.extend ([exception_manager.last_exception, classes.item])
-- Jump to the next class.
classes.forth
has_next_step := not classes.after
if not has_next_step then
completed_action.call ([exceptions])
end
retry
end
</e>

<e>type_recorder</e> is of type <e>{CA_AST_TYPE_RECORDER}</e>. It uses a functionality of the Eiffel compiler to determine the type of some AST nodes in the current class. The AST itself (as provided by the Eiffel compiler) does not contain any type information. <e>context</e> has type <e>{CA_ANALYSIS_CONTEXT}</e> and contains any side-information such as the previously mentioned types and the current class. The rules were given this context before so that they can access it when needed.

The <e>across</e> loop only checks ''control flow graph rules''. All the ''standard'' rules are checked by the line <e>rules_checker.run_on_class (classes.item)</e>. <e>rules_checker</e> has type <e>{CA_ALL_RULES_CHECKER}</e>. This is the class where each rule must register the AST nodes the rule visits. <e>run_on_class</e> iterates over the AST and calls all the actions that were registered by the standard rules. So this is the way all rules are used to check the current class. <e>step</e> is executed repeatedly until there are no classes left to analyze.

In the <e>rescue</e> clause all possible exceptions are caught and recorded. In case of such an exception it then proceeds to the next class.

=== Checking ''Standard'' Rules ===

The relatively large class <e>{CA_ALL_RULES_CHECKER}</e> is responsible for checking ''standard rules''. It does this in a straightforward way. It is a subclass of <e>{AST_ITERATOR}</e>, a realization of a visitor on the AST.

Rules can register their actions with <e>{CA_ALL_RULES_CHECKER}</e> by calling a procedure like <e>add_bin_lt_pre_action (a_action: attached PROCEDURE [ANY, TUPLE [BIN_LT_AS]])</e> or <e>add_if_post_action (a_action: attached PROCEDURE [ANY, TUPLE [IF_AS]])</e>. These "pre" and "post" actions exist for many other types of AST nodes as well. All the registered actions are stored in <e>ACTION_SEQUENCE</e> variables:
<e>
if_pre_actions, if_post_actions: ACTION_SEQUENCE [TUPLE [IF_AS]]

add_if_post_action (a_action: attached PROCEDURE [ANY, TUPLE [IF_AS]])
do
if_post_actions.extend (a_action)
end

-- And similar for all other relevant AST nodes...
</e>

The corresponding visitor procedures are redefined. This is done is the following way:
<e>
process_if_as (a_if: IF_AS)
do
if_pre_actions.call ([a_if])
Precursor (a_if)
if_post_actions.call ([a_if])
end

-- And similar for all other relevant AST nodes...
</e>

Since the actual iteration over the AST is done in the ancestor we need only very little code to analyze a class:
<e>
feature {CA_RULE_CHECKING_TASK} -- Execution Commands

run_on_class (a_class_to_check: CLASS_C)
-- Check all rules that have added their agents.
local
l_ast: CLASS_AS
do
last_run_successful := False
l_ast := a_class_to_check.ast
class_pre_actions.call ([l_ast])
process_class_as (l_ast)
class_post_actions.call ([l_ast])
last_run_successful := True
end
</e>

This code analyzes a class for all active ''standard'' rules. <e>class_pre_actions</e> and <e>class_post_actions</e> are action sequences that are identical to those for the AST nodes. <e>process_class_as</e>, which is implemented in <e>{AST_ITERATOR}</e> will recursively visit all relevant AST nodes and execute their action sequences.

== Example: Rule # 71: ''Self-comparison'' ==

We will go through the implementation of rule # 71 (''Self-comparison'') in detail.

The heart of this implementation lies in the feature <e>analyze_self</e>. There it is tested whether a binary expression is s self-comparison. <e>is_self</e>, a <e>BOOLEAN</e> attribute, is set to true if and only if the argument is a comparison between two identical variables.

<e>
analyze_self (a_bin: attached BINARY_AS)
-- Is `a_bin' a self-comparison?
do
is_self := False

if
attached {EXPR_CALL_AS} a_bin.left as l_e1
and then attached {ACCESS_ID_AS} l_e1.call as l_l
and then attached {EXPR_CALL_AS} a_bin.right as l_e2
and then attached {ACCESS_ID_AS} l_e2.call as l_r
then
is_self := l_l.feature_name.is_equal (l_r.feature_name)
self_name := l_l.access_name_32
end
end

is_self: BOOLEAN
-- Is `a_bin' from last call to `analyze_self' a self-comparison?

self_name: detachable STRING_32
-- Name of the self-compared variable.
</e>

Both sides of the comparison, <e>a_bin.left</e> and <e>a_bin.right</e>, are tested to have the types that indicate that they are variable or feature accesses. If the tests succeed then <e>is_self</e> is set according to the equality of the two feature names. Then the name is stored in an internal attribute.

<e>analyze_self</e> is used in <e>process_comparison</e>, which creates a rule violation if a self-comparison was detected.

<e>
process_comparison (a_comparison: BINARY_AS)
-- Checks `a_comparison' for rule violations.
local
l_viol: CA_RULE_VIOLATION
do
if not in_loop then
analyze_self (a_comparison)
if is_self then
create l_viol.make_with_rule (Current)
l_viol.set_location (a_comparison.start_location)
l_viol.long_description_info.extend (self_name)
violations.extend (l_viol)
end
end
end
</e>

First we check that we are not dealing with a loop condition. Self-comparisons in loop conditions are more dangerous and need special treatment (see below). For the rule violation, we set the location to the start location of the binary comparison. We add the variable or feature name to the violation.

Different kinds of comparisons also have different types in the AST. That is why in an AST iterator they are processed independently. Thus, we need to add some delegation to each of the actions that are called when processing a comparison.

<e>
process_bin_eq (a_bin_eq: BIN_EQ_AS)
do
process_comparison (a_bin_eq)
end

process_bin_ge (a_bin_ge: BIN_GE_AS)
do
process_comparison (a_bin_ge)
end

process_bin_gt (a_bin_gt: BIN_GT_AS)
do
process_comparison (a_bin_gt)
end

process_bin_le (a_bin_le: BIN_LE_AS)
do
process_comparison (a_bin_le)
end

process_bin_lt (a_bin_lt: BIN_LT_AS)
do
process_comparison (a_bin_lt)
end
</e>

In the case that a loop condition is a self-comparison, the loop is either never entered or it is never exited. The last case is more severe; the first case only arises with an equality comparison. For this reason we analyze loop conditions separately. If we find such a violation we set <e>in_loop</e> to <e>True</e> so that any further self-comparisons are ignored until we have left the loop.

<e>
pre_process_loop (a_loop: LOOP_AS)
-- Checking a loop `a_loop' for self-comparisons needs more work. If the until expression
-- is a self-comparison that does not compare for equality then the loop will
-- not terminate, which is more severe consequence compared to other self-comparisons.
local
l_viol: CA_RULE_VIOLATION
do
if attached {BINARY_AS} a_loop.stop as l_bin then
analyze_self (l_bin)
if is_self then
create l_viol.make_with_rule (Current)
l_viol.set_location (a_loop.stop.start_location)
l_viol.long_description_info.extend (self_name)
if not attached {BIN_EQ_AS} l_bin then
-- It is only a dangerous loop stop condition if we do not have
-- an equality comparison.
l_viol.long_description_info.extend ("loop_stop")
end
violations.extend (l_viol)
in_loop := True
end
end
end
</e>

<e>format_violation_description</e>, which is declared in <e>CA_RULE</e> as <e>deferred</e>, must be implemented. Here, together with a predefined localized text, we mention the name of the self-compared variable. If the self-comparison is located in a loop stop condition we add an additional warning text.

<e>
format_violation_description (a_violation: attached CA_RULE_VIOLATION; a_formatter: attached TEXT_FORMATTER)
local
l_info: LINKED_LIST [ANY]
do
l_info := a_violation.long_description_info
a_formatter.add ("'")
if l_info.count >= 1 and then attached {STRING_32} l_info.first as l_name then
a_formatter.add_local (l_name)
end
a_formatter.add (ca_messages.self_comparison_violation_1)

l_info.compare_objects
if l_info.has ("loop_stop") then
-- Dangerous loop stop condition.
a_formatter.add (ca_messages.self_comparison_violation_2)
end
end
</e>

Then we must implement the usual properties.

<e>
title: STRING_32
do
Result := ca_names.self_comparison_title
end

id: STRING_32 = "CA071"
-- <Precursor>

description: STRING_32
do
Result := ca_names.self_comparison_description
end
</e>

Finally, in the initialization we use the default settings, which can be set by calling <e>{CA_RULE}.make_with_defaults</e>. To the default severity score we assign a custom value. In <e>register_actions</e> we must add all the agents for processing the loop and comparison nodes of the AST.

<e>
feature {NONE} -- Initialization

make
-- Initialization.
do
make_with_defaults
default_severity_score := 70
end

feature {NONE} -- Activation

register_actions (a_checker: attached CA_ALL_RULES_CHECKER)
do
a_checker.add_bin_eq_pre_action (agent process_bin_eq)
a_checker.add_bin_ge_pre_action (agent process_bin_ge)
a_checker.add_bin_gt_pre_action (agent process_bin_gt)
a_checker.add_bin_le_pre_action (agent process_bin_le)
a_checker.add_bin_lt_pre_action (agent process_bin_lt)
a_checker.add_loop_pre_action (agent pre_process_loop)
a_checker.add_loop_post_action (agent post_process_loop)
end
</e>

The complete source code of this rule is available in the [https://svn.eiffel.com/eiffelstudio/branches/eth/eve/Src/framework/code_analysis/rules/expressions/ca_self_comparison_rule.e SVN repository].

== Example: Rule # 2: ''Unused argument'' ==

The ''unused argument'' rule processes the ''feature'', ''body'', ''access id'', and ''converted expression'' AST nodes. The feature node is stored for the description and for ignoring ''deferred'' features. The body node is used to retrieve the arguments. The ''access id'' and ''converted expression'' nodes may represent used arguments, so the nodes are used to mark arguments as read. We register the ''pre'' actions for all the AST nodes as well as the ''post'' action for the ''body'' node in <e>register_actions</e>.

<e>
feature {NONE} -- Activation

register_actions (a_checker: attached CA_ALL_RULES_CHECKER)
do
a_checker.add_feature_pre_action (agent process_feature)
a_checker.add_body_pre_action (agent process_body)
a_checker.add_body_post_action (agent post_process_body)
a_checker.add_access_id_pre_action (agent process_access_id)
a_checker.add_converted_expr_pre_action (agent process_converted_expr)
end
</e>

On processing a feature we store the feature instance, which will be used later.

<e>
process_feature (a_feature_as: FEATURE_AS)
-- Sets the current feature.
do
current_feature := a_feature_as
end
</e>

Before processing the body of a feature we store a list of all the argument names. This is however only done if the feature is a routine, if it has arguments, and if it is not external. In the code we need two nested loops since the arguments are grouped by type. For example, two consecutive <e>STRING</e> arguments as in <e>feature print(first, second: STRING)</e> are in one entry of <e>{BODY_AS}.arguments</e>. This single entry is itself a list of arguments.

<e>
process_body (a_body_as: BODY_AS)
-- Retrieves the arguments from `a_body_as'.
local
j: INTEGER
do
has_arguments := (a_body_as.arguments /= Void)
create args_used.make (0)
n_arguments := 0
if
attached a_body_as.as_routine as l_rout
and then has_arguments
and then not l_rout.is_external
then
routine_body := a_body_as
create arg_names.make (0)
across a_body_as.arguments as l_args loop
from
j := 1
until
j > l_args.item.id_list.count
loop
arg_names.extend (l_args.item.item_name (j))
args_used.extend (False)
n_arguments := n_arguments + 1
j := j + 1
end
end
end
end

has_arguments: BOOLEAN
-- Does current feature have arguments?

current_feature: FEATURE_AS
-- Currently checked feature.

routine_body: BODY_AS
-- Current routine body.

n_arguments: INTEGER
-- # arguments for current routine.

arg_names: ARRAYED_LIST [STRING_32]
-- Argument names of current routine.

args_used: ARRAYED_LIST [BOOLEAN]
-- Which argument has been used?
</e>

Both the nodes <e>{ACCESS_ID_AS}</e> and <e>{CONVERTED_EXPR_AS}</e> may represent used arguments. <e>{ACCESS_ID_AS}</e> is a usual variable usage, while <e>{CONVERTED_EXPR_AS}</e> stands for an argument used in inline C code (the dollar sign syntax: <e>$arg</e>). In both routines <e>check_arguments</e> is called eventually, which updates the internal data structures of our rule class.

<e>
process_access_id (a_aid: ACCESS_ID_AS)
-- Checks if `a_aid' is an argument.
do
check_arguments (a_aid.feature_name.name_32)
end

process_converted_expr (a_conv: CONVERTED_EXPR_AS)
-- Checks if `a_conv' is an argument used in the
-- form `$arg'.
local
j: INTEGER
do
if
attached {ADDRESS_AS} a_conv.expr as l_address
and then attached {FEAT_NAME_ID_AS} l_address.feature_name as l_id
then
check_arguments (l_id.feature_name.name_32)
end
end

check_arguments (a_var_name: attached STRING_32)
-- Mark an argument as used if it corresponds to `a_aid'.
local
j: INTEGER
do
from
j := 1
until
j > n_arguments
loop
if not args_used [j] and then arg_names [j].is_equal (a_var_name) then
args_used [j] := True
end
j := j + 1
end
end
</e>

<e>post_process_body</e> finally checks if there exist unused arguments. If this is the case then all the relevant variable names are stored in the rule violation. Also, the feature is stored (for the feature name). The location of the violation is set to the start of the routine body. No rule violation is issued if the feature is deferred.

<e>
post_process_body (a_body: BODY_AS)
-- Adds a violation if the feature contains unused arguments.
local
l_violation: CA_RULE_VIOLATION
j: INTEGER
do
if
a_body.content /= Void
and then not current_feature.is_deferred
and then has_arguments
and then args_used.has (False)
then
create l_violation.make_with_rule (Current)
l_violation.set_location (routine_body.start_location)
l_violation.long_description_info.extend (current_feature)
from
j := 1
until
j > n_arguments
loop
if not args_used.at (j) then
l_violation.long_description_info.extend (arg_names.at (j))
end
j := j + 1
end
violations.extend (l_violation)
end
end
</e>

All the information that was stored in the rule violation is used for the formatted description:

<e>
format_violation_description (a_violation: attached CA_RULE_VIOLATION; a_formatter: attached TEXT_FORMATTER)
local
j: INTEGER
do
a_formatter.add (ca_messages.unused_argument_violation_1)
from
j := 2
until
j > a_violation.long_description_info.count
loop
if j > 2 then a_formatter.add (", ") end
a_formatter.add ("'")
if attached {STRING_32} a_violation.long_description_info.at (j) as l_arg then
a_formatter.add_local (l_arg)
end
a_formatter.add ("'")
j := j + 1
end
a_formatter.add (ca_messages.unused_argument_violation_2)
if attached {FEATURE_AS} a_violation.long_description_info.first as l_feature then
a_formatter.add_feature_name (l_feature.feature_name.name_32, a_violation.affected_class)
end
a_formatter.add (ca_messages.unused_argument_violation_3)
end
</e>

The complete source code of this rule is available in the [https://svn.eiffel.com/eiffelstudio/branches/eth/eve/Src/framework/code_analysis/rules/features/ca_unused_argument_rule.e SVN repository].

CA Library Implementation

<center>[[User:Stefan/Code Analysis/Command Line Usage|<< 5. Command Line Usage]] | [[User:Stefan/Code Analysis/Library Implementation|7. Library Implementation >>]] </center>
----
 
The Code Analysis framework was designed with regard to the fact that '''adding new rules''' should be as simple and as fast as possible. Looking at the initial set of rules that were implemented, nearly all of them have an implementation of less than 200 lines of code. Many of them use even less than 100 lines of code. Rules that search the code for certain patterns (this applies to the vast majority of rules) are particularly simple to implement.

This page shows you how to implement a rule in the form of a class. After you have written such a class you must add the rule to the list of rules. This list is populated in <e>{CA_CODE_ANALYZER}.make</e>. There, just below the lines where all the other rules are added add a line like

<e>rules.extend (create {YOUR_RULE}.make)</e>,

where <e>YOUR_RULE</e> must be replaced by the name of your rule class and the creation procedure (<e>make</e>) must be adapted if necessary.

== Standard Rules ==

All rules must conform to <e>CA_RULE</e>. The class you implement for a rule is on one hand responsible for checking the rule and contains metadata about the rule (i. e. title, description) on the other hand. As of now, rules must moreover conform to either <e>CA_STANDARD_RULE</e> or <e>CA_CFG_RULE</e>, both of which are subtypes of <e>CA_RULE</e>. A large number of possible rules are ''standard rules'', no matter whether they are trivial or more complicated.

All ''Standard rules'' are checked by iterating over the [http://en.wikipedia.org/wiki/Abstract_syntax_tree abstract syntax tree] (AST) of the class code. The developer who adds a new rule can very well ignore the details thereof. He needs to know however which AST nodes his rule needs to process. For each type of AST node you need to add an agent so your routine will be called during the iteration on the AST.

To start implementing your rule you have basically two possibilities. (1) You start from scratch, implementing all deferred features of <e>CA_STANDARD_RULE</e> or (2) you use the following template.

=== Standard Rule Template ===

<e>
class
CA_YOUR_RULE

inherit
CA_STANDARD_RULE

create
make

feature {NONE} -- Initialization

make (a_pref_manager: attached PREFERENCE_MANAGER)
-- Initialization for `Current'.
do
make_with_defaults
-- This initializes the attributes to their default values:
-- Severity = warning
-- Default Severity Score = 50 (`severity score' can be changed by user)
-- Rule enabled by default = True (`Rule enabled' can be changed by user)
-- Only for system wide checks = False
-- Checks library classes = True
-- Checks nonlibrary classes = True

initialize_options (a_pref_manager)

-- TODO: Add your initialization here.
end

initialize_options (a_pref_manager: attached PREFERENCE_MANAGER)
-- Initializes the rule preferences.
local
l_factory: BASIC_PREFERENCE_FACTORY
do
create l_factory

-- TODO: Add the initialization of your custom preferences here.
-- Example:
-- threshold := l_factory.new_integer_preference_value (a_pref_manager,
-- preference_namespace + "Threshold",
-- 30) -- default value
-- min_local_name_length.set_default_value ("30") -- default value, too
-- min_local_name_length.set_validation_agent (agent is_integer_string_within_bounds (?, 1, 1_000_000))
end

feature {NONE} -- Activation

register_actions (a_checker: attached CA_ALL_RULES_CHECKER)
do
-- TODO: Add agents for the features in section `Rule checking' here.
end

feature {NONE} -- Rule checking

-- TODO: Add the AST processing here.

feature -- Properties

title: STRING_32
do
-- TODO: Add the title of your rule here.
Result := "(Your title)"
end

-- TODO: Add the ID of your rule here. Should be unique!
id: STRING_32 = "(YourID)"

description: STRING_32
do
-- TODO: Add the rule description here.
Result := "(Your description)"
end

format_violation_description (a_violation: attached CA_RULE_VIOLATION; a_formatter: attached TEXT_FORMATTER)
do
-- TODO: Add a formatted description of a concrete violation of this rule here.
end

end
</e>

Let us have a closer look at the various parts of a rule class.

=== Initialization ===

Calling <e>make_with_defaults</e> initializes the attributes to their default values and makes sure that the class invariant is true. If you want to set an attribute to a custom value you can do so by setting it after the call to <e>make_with_defaults</e>.

The creation procedure from the template takes an argument of type <e>PREFERENCE_MANAGER</e>. This is used for initializing preferences that are specific to your rule. Such preferences usually represent integral or boolean values. If you do ''not'' need any custom preferences then you can leave out the argument <e>a_pref_manager</e> of <e>make</e> and you can remove the whole <e>initialize_options</e> feature.

=== AST processing ===

The main part of your rule implementation consists of checking the source code for rule violations. Say, for example, that you want to check <e>if</e> instructions to have certain properties. Then you would add a feature like <e>process_if (a_if_ast: IF_AS)</e> to the section ''Rule checking''. Also, you would need to modify the <e>register_actions</e> feature by adding the line

<e>a_checker.add_if_pre_action (agent process_if)</e>.

Of course you may register as many such agents as you want.

=== Properties ===

The ''title'' and the ''description'' of the rule may be constant strings, they may also be localized strings. The ''rule ID'' must be unique among all rules. It should not contain spaces and should be reasonably short. The main rules that come with ''Code Analysis'' have IDs that are numbered from CA001 to CA999 (many of which are not used).

=== Formatted Violation Description ===

Your rule should be able to produce a formatted description of a concrete rule violation. This description is for example used in the Code Analysis tool panel of the GUI. There, class names and feature names are enabled for pick-and-drop. Variable names, numbers, and strings will be displayed in a nice way, too. In addition, this description is used in command line mode. In order to produce normal, unformatted text, use <e>{TEXT_FORMATTER}.add</e>. For adding formatted elements use features like <e>{TEXT_FORMATTER}.add_local</e>, <e>{TEXT_FORMATTER}.add_feature_name</e> and similar.

You should store all the data you need for this description (variables names, numbers, etc.) in <e>{CA_RULE_VIOLATION}.long_description_info</e>. <e>format_violation_description</e> can then retrieve this data for the formatted output. Here is a simple example of producing a formatted description:

<e>
a_formatter.add ("Feature ")
if attached {STRING_32} a_violation.long_description_info.first as l_feat_name then
a_formatter.add_feature_name (l_feat_name, a_violation.affected_class)
end
a_formatter.add (" is very long.")
</e>

== More Customized Rules ==

For rules that do not fit into a simple AST visitor scheme you best inherit your rule from <e>{CA_STANDARD_RULE}</e>, too. You can for example register agents that get called when a ''class'' or a ''feature'' is processed. Based on these agents you can perform your customized analysis on the classes and/or features. Using ''multiple inheritance'' or just aggregation it should hardly be a problem to include any functionality you need for your analysis.

== Accessing Type Information ==

The AST classes do not contain ''type information''. Suppose your rule processes function calls. Feature calls in the AST do not contain any information on the types, such as the type of the result.

The code analysis framework however provides functionality to retrieve the type of AST nodes. Before the analyzer lets a class be analyzed by all the rules it computes the types of the AST nodes of a class. Hence this data will be available to your rule afterwards.

While your rule is being checked you can retrieve the type of node <e>a_node</e> from feature <e>a_feature</e> by calling <e>current_context.node_type (a_node: AST_EIFFEL; a_feature: FEATURE_I)</e>. <e>{CA_RULE}.current_context</e> is of type <e>{CA_ANALYSIS_CONTEXT}</e> and contains other information about current rule checking, too, such as the currently processed class or the matchlist for this class.

== Accessing the Control Flow Graph ==

Some kinds of static code analysis need and use the ''control flow graph'' of a program. The code analysis framework supports rules that use the control flow graph. If there is at least one such rule, the code analyzer computes the control flow graph of the procedures of the analyzed class before letting the ''rule'' check this class.

=== Worklist algorithms ===

''Control flow graph rules'' iterate over the control flow graph. They do it using a ''worklist''—a list of CFG edges that still have to be processed. At the beginning, the worklist contains all edges of the control flow graph. The algorithm will pick edges from the worklist for processing in an arbitrary order. The iteration stops as soon as there are no more edges left in the worklist. How will the worklist get smaller? Each edge that is processed is removed from the worklist. After processing you will have to decide dynamically whether to add all the outgoing (or incoming, depending on the direction) edges to the worklist. Like this you can take the fact into account that some analyses need certain edges to be processed more than once (a fixed point iteration is such an example).

=== Implementation ===

A control flow analysis may iterate in either direction. For a forward-directed analysis inherit your rule from <e>{CA_CFG_FORWARD_RULE}</e>, for a backward analysis use <e>{CA_CFG_BACKWARD_RULE}</e> instead. In either case you will then have to implement the following deferred features:

; <e>initialize_processing (a_cfg: attached CA_CONTROL_FLOW_GRAPH)</e> : This is called before a routine is processed using the worklist. Essentially you may use it to initialize and prepare all the data structures you will need during analysis.
; <e>visit_edge (a_from, a_to: attached CA_CFG_BASIC_BLOCK): BOOLEAN</e> : This will be called when an edge is being visited. Here, you can put the analysis. If you let <e>Result = False</e> then no further edges will be added to the worklist. If in contrary you let <e>Result = True</e> then edges will be added to the worklist: In a ''forward'' analysis all the ''outgoing'' edges of the current one will be added; in a ''backward'' analysis all the ''incoming'' edges will be added.

=== Non-worklist algorithms ===

If your control flow graph does not fit into the structure of an algorithm as described above you may directly inherit from <e>{CA_CFG_RULE}</e> and implement the feature <e>process_cfg (a_cfg: attached CA_CONTROL_FLOW_GRAPH)</e> (in addition to the features explained above). In this case you do not have to use a worklist; basically you can process the control flow graph in any way you want.

User:Stefan/Code Analysis/Architectural Overview

2014-03-07T11:03:59Z

Stefan: Stefan moved page User:Stefan/Code Analysis/Architectural Overview to User:Stefan/Code Analysis/Library Implementation

#REDIRECT [[User:Stefan/Code Analysis/Library Implementation]]

CA Library Implementation

2014-03-07T11:03:58Z

Stefan: Stefan moved page User:Stefan/Code Analysis/Architectural Overview to User:Stefan/Code Analysis/Library Implementation

<center>[[User:Stefan/Code Analysis/Adding New Rules|<< 6. Adding New Rules]] |</center>
----
 

The code for Code Analysis is located at three different places in the ''EVE'' source:
# The framework—the by far largest part, with the rule checking, the rules, the control flow graph functionality, and more—is represented as a ''library'';
# The graphical user interface can be found in the ''interface'' cluster of ''EVE'';
# The command-line interface for code analysis is a single class in the ''tty'' cluster of ''EVE''.

== ''code_analysis'' library ==

The whole code analysis framework is located in the library ''code_analysis''.

=== Interface ===

In this section it is explained from a client view how to use the code analyzer. The code analyzer is represented by the class <e>CA_CODE_ANALYZER</e>, so a client must have or access an instance of this class. Before the analyzer can be launched all the classes that shall be analyzed must be added using one of the following features. If you use more than one of these commands then the added classes from all commands will be conjoined.
; <e>{CA_CODE_ANALYZER}.add_whole_system</e> : Adds all the classes that are part of the current system. Classes of referenced libraries will not be added. So, for example, if your system consists of the classes <e>MY_MAIN</e>, <e>MY_BOX</e>, and <e>MY_ITEM</e> then these three classes will be added to the list of classes to be analyzed.
; <e>.add_class (a_class: attached CONF_CLASS)</e> : Adds a single class.
; <e>.add_classes (a_classes: attached ITERABLE [attached CONF_CLASS])</e> : Adds a list of classes.
; <e>.add_cluster (a_cluster: attached CLUSTER_I)</e> : Adds all classes of a cluster (and all the classes of the sub-clusters recursively).
; <e>.add_group (a_group: attached CONF_GROUP)</e> : Adds all classes of a configuration group. An example of a configuration group is a ''library''.

Here are other features which can be called before starting to analyze:
; <e>{CA_CODE_ANALYZER}.clear_classes_to_analyze</e> : Removes all classes that have been added to the list of classes to analyze.
; <e>.add_completed_action (a_action: attached PROCEDURE [ANY, TUPLE [ITERABLE [TUPLE [detachable EXCEPTION, CLASS_C]]]])</e> : Adds <e>`a_action'</e> to the list of procedures that will be called when analysis has completed. The procedures have one argument, a list of exceptions (with the corresponding class). In the case an exception is thrown during analysis the exception is caught by the code analyzer and is added to this list. In the graphical user interface such exceptions would show up as errors at the top of the list of rule violations.
; <e>.add_output_action (a_action: attached PROCEDURE [ANY, TUPLE [READABLE_STRING_GENERAL]])</e> : Adds <e>`a_action'</e> to the procedures that are called for outputting the status. The final results (rule violations) are not given to these procedures. These output actions are used by the command-line mode and by the status bar in the GUI.
; <e>.is_rule_checkable (a_rule: attached CA_RULE): BOOLEAN</e> : Tells whether <e>`a_rule'</e> will be checked based on the current preferences and based on the current checking scope (whole system or custom set of classes).

Then, to start analyzing simply call <e>{CA_CODE_ANALYZER}.analyze</e>.

=== Rule checking ===

In the GUI we want to be able to continue to work while the code analyzer is running. Analyzing larger sets of classes (such as whole libraries) can take from several seconds to several minutes. For this reason the code analyzer uses an ''asynchronous task'', <e>{CA_RULE_CHECKING_TASK}</e>. In <e>{CA_CODE_ANALYZER}.analyze</e> this task (<e>l_task</e>) is invoked as follows:

==== In <e>{CA_CODE_ANALYZER}.analyze</e>: ====

<e>
create l_task.make (l_rules_checker, l_rules_to_check, classes_to_analyze, agent analysis_completed)
l_task.set_output_actions (output_actions)
rota.run_task (l_task)
</e>

<e>{CA_RULE_CHECKING_TASK}</e> essentially runs the whole analysis. Like all other conformants to <e>{ROTA_TASK_I}</e> this class executes a series of ''steps'' between which the user interface gets some time to process its events. In <e>{CA_RULE_CHECKING_TASK}</e> each step analyses one class. This means that a class is checked by ''all'' the rules for violations. The following code does that:

==== From <e>{CA_RULE_CHECKING_TASK}</e>: ====

<e>
step
-- <Precursor>
do
if has_next_step then
-- Gather type information
type_recorder.clear
type_recorder.analyze_class (classes.item)
context.set_node_types (type_recorder.node_types)
context.set_checking_class (classes.item)

across rules as l_rules loop
-- If rule is non-standard then it will not be checked by l_rules_checker.
-- We will have the rule check the current class here:
if
l_rules.item.is_enabled.value
and then attached {CA_CFG_RULE} l_rules.item as l_cfg_rule
then
l_cfg_rule.check_class (classes.item)
end
end

-- Status output.
if output_actions /= Void then
output_actions.call ([ca_messages.analyzing_class (classes.item.name)])
end

rules_checker.run_on_class (classes.item)

classes.forth
has_next_step := not classes.after
if not has_next_step then
completed_action.call ([exceptions])
end
end
rescue
-- Instant error output.
if output_actions /= Void then
output_actions.call ([ca_messages.error_on_class (classes.item.name)])
end
exceptions.extend ([exception_manager.last_exception, classes.item])
-- Jump to the next class.
classes.forth
has_next_step := not classes.after
if not has_next_step then
completed_action.call ([exceptions])
end
retry
end
</e>

<e>type_recorder</e> is of type <e>{CA_AST_TYPE_RECORDER}</e>. It uses a functionality of the Eiffel compiler to determine the type of some AST nodes in the current class. The AST itself (as provided by the Eiffel compiler) does not contain any type information. <e>context</e> has type <e>{CA_ANALYSIS_CONTEXT}</e> and contains any side-information such as the previously mentioned types and the current class. The rules were given this context before so that they can access it when needed.

The <e>across</e> loop only checks ''control flow graph rules''. All the ''standard'' rules are checked by the line <e>rules_checker.run_on_class (classes.item)</e>. <e>rules_checker</e> has type <e>{CA_ALL_RULES_CHECKER}</e>. This is the class where each rule must register the AST nodes the rule visits. <e>run_on_class</e> iterates over the AST and calls all the actions that were registered by the standard rules. So this is the way all rules are used to check the current class. <e>step</e> is executed repeatedly until there are no classes left to analyze.

In the <e>rescue</e> clause all possible exceptions are caught and recorded. In case of such an exception it then proceeds to the next class.

== Graphical User Interface ==

The classes of the graphical user interface of the code analyzer are all located in the ''interface'' cluster of ''EVE'', in the subfolder ''graphical > tools > code_analysis''. Here is a short overview of what the single classes do:

; <e>{ES_CODE_ANALYSIS_TOOL}</e> : Represents the code analysis GUI tool. Contains the tool title and icon, otherwise not much interesting stuff.
; <e>{ES_CODE_ANALYSIS_TOOL_PANEL}</e> : The graphical panel for the code analysis tool. It contains buttons, labels, the rule violations table view, and other user interface elements.
; <e>{ES_CODE_ANALYSIS_COMMAND}</e> : The command to launch the code analyzer. It can be added to toolbars and menus. It can be executed using stones. This class also handles the caching.
; <e>{ES_CODE_ANALYSIS_BENCH_HELPER}</e> : A helper class for the integration of the code analysis tool. It contains shared instances of <e>{CA_CODE_ANALYZER}</e> and <e>{ES_CODE_ANALYSIS_COMMAND}</e>, which are used by the GUI.
; <e>{ES_CA_SHOW_PREFERENCES_COMMAND}</e> : The command is used by the ''Preferences'' button in the panel.
; <e>{ES_CA_FIX_EXECUTOR}</e> : This class [[User:Stefan/Code Analysis/Using Analysis Results#Fixing Rule Violations|fixes]] a rule violation that has been found by the code analysis tool.

=== Caching ===

== Command-line Interface ==

The whole command-line functionality of the code analyzer is located in the class <e>{EWB_CODE_ANALYSIS}</e>. It is located in the ''tty'' cluster of ''EVE''. <e>{EWB_CODE_ANALYSIS}</e> is invoked by <e>{ES}</e>, the root class for the ''batch'' (command-line) version of EiffelStudio. In <e>{ES}</e>, the invocation looks as follows:

<e>
elseif option.is_equal ("-code-analysis") then
l_at_args := arguments_in_range (current_option + 1, argument_count)
current_option := argument_count + 1
create {EWB_CODE_ANALYSIS} command.make_with_arguments (l_at_args)
</e>

Any command-line arguments after ''-code-analysis'' are passed on to <e>{EWB_CODE_ANALYSIS}</e>. This class, in its creation procedure, processes the arguments as described in [[User:Stefan/Code_Analysis/Command Line Usage|Command Line Usage]]. Classes that were passed as command-line arguments are added to the analyzer. Then the actual execution happens in the procedure <e>execute</e>. <e>EWB_CODE_ANALYSIS</e> of course uses the ''code_analysis'' library and the previously described interface of <e>CA_CODE_ANALYZER</e>. After analysis a list of rule violations is output to the command-line. In the code it looks like this:

<e>
across l_code_analyzer.rule_violations as l_vlist loop
if not l_vlist.item.is_empty then
l_has_violations := True
-- Always sort the rule violations by the class they are referring to.
output_window.add (ca_messages.cmd_class + l_vlist.key.name + "':%N")

-- See `{CA_RULE_VIOLATION}.is_less' for information on the sorting.
across l_vlist.item as ic loop
l_rule_name := ic.item.rule.title
l_rule_id := ic.item.rule.id
if attached ic.item.location as l_loc then
l_line := ic.item.location.line.out
l_col := ic.item.location.column.out
output_window.add (" (" + l_line + ":" + l_col + "): "
+ l_rule_name + " (" + l_rule_id + "): ")
else -- No location attached. Print without location.
output_window.add (" " + l_rule_name + " (" + l_rule_id + "): ")
end
ic.item.format_violation_description (output_window)
output_window.add ("%N")
end
end
end

if not l_has_violations then output_window.add (ca_messages.no_issues + "%N") end
</e>

CA Library Implementation

2014-03-06T15:52:03Z

Stefan: /* Graphical User Interface */ additions

CA Library Implementation

2014-03-06T15:36:10Z

Stefan: /* code_analysis library */

<center>[[User:Stefan/Code Analysis/Adding New Rules|<< 6. Adding New Rules]] |</center>
----
 

The code for Code Analysis is located at three different places in the ''EVE'' source:
# The framework—the by far largest part, with the rule checking, the rules, the control flow graph functionality, and more—is represented as a ''library'';
# The graphical user interface can be found in the ''interface'' cluster of ''EVE'';
# The command-line interface for code analysis is a single class in the ''tty'' cluster of ''EVE''.

== ''code_analysis'' library ==

The whole code analysis framework is located in the library ''code_analysis''.

=== Interface ===

In this section it is explained from a client view how to use the code analyzer. The code analyzer is represented by the class <e>CA_CODE_ANALYZER</e>, so a client must have or access an instance of this class. Before the analyzer can be launched all the classes that shall be analyzed must be added using one of the following features. If you use more than one of these commands then the added classes from all commands will be conjoined.
; <e>{CA_CODE_ANALYZER}.add_whole_system</e> : Adds all the classes that are part of the current system. Classes of referenced libraries will not be added. So, for example, if your system consists of the classes <e>MY_MAIN</e>, <e>MY_BOX</e>, and <e>MY_ITEM</e> then these three classes will be added to the list of classes to be analyzed.
; <e>.add_class (a_class: attached CONF_CLASS)</e> : Adds a single class.
; <e>.add_classes (a_classes: attached ITERABLE [attached CONF_CLASS])</e> : Adds a list of classes.
; <e>.add_cluster (a_cluster: attached CLUSTER_I)</e> : Adds all classes of a cluster (and all the classes of the sub-clusters recursively).
; <e>.add_group (a_group: attached CONF_GROUP)</e> : Adds all classes of a configuration group. An example of a configuration group is a ''library''.

Here are other features which can be called before starting to analyze:
; <e>{CA_CODE_ANALYZER}.clear_classes_to_analyze</e> : Removes all classes that have been added to the list of classes to analyze.
; <e>.add_completed_action (a_action: attached PROCEDURE [ANY, TUPLE [ITERABLE [TUPLE [detachable EXCEPTION, CLASS_C]]]])</e> : Adds <e>`a_action'</e> to the list of procedures that will be called when analysis has completed. The procedures have one argument, a list of exceptions (with the corresponding class). In the case an exception is thrown during analysis the exception is caught by the code analyzer and is added to this list. In the graphical user interface such exceptions would show up as errors at the top of the list of rule violations.
; <e>.add_output_action (a_action: attached PROCEDURE [ANY, TUPLE [READABLE_STRING_GENERAL]])</e> : Adds <e>`a_action'</e> to the procedures that are called for outputting the status. The final results (rule violations) are not given to these procedures. These output actions are used by the command-line mode and by the status bar in the GUI.
; <e>.is_rule_checkable (a_rule: attached CA_RULE): BOOLEAN</e> : Tells whether <e>`a_rule'</e> will be checked based on the current preferences and based on the current checking scope (whole system or custom set of classes).

Then, to start analyzing simply call <e>{CA_CODE_ANALYZER}.analyze</e>.

=== Rule checking ===

In the GUI we want to be able to continue to work while the code analyzer is running. Analyzing larger sets of classes (such as whole libraries) can take from several seconds to several minutes. For this reason the code analyzer uses an ''asynchronous task'', <e>{CA_RULE_CHECKING_TASK}</e>. In <e>{CA_CODE_ANALYZER}.analyze</e> this task (<e>l_task</e>) is invoked as follows:

==== In <e>{CA_CODE_ANALYZER}.analyze</e>: ====

<e>
create l_task.make (l_rules_checker, l_rules_to_check, classes_to_analyze, agent analysis_completed)
l_task.set_output_actions (output_actions)
rota.run_task (l_task)
</e>

<e>{CA_RULE_CHECKING_TASK}</e> essentially runs the whole analysis. Like all other conformants to <e>{ROTA_TASK_I}</e> this class executes a series of ''steps'' between which the user interface gets some time to process its events. In <e>{CA_RULE_CHECKING_TASK}</e> each step analyses one class. This means that a class is checked by ''all'' the rules for violations. The following code does that:

==== From <e>{CA_RULE_CHECKING_TASK}</e>: ====

<e>
step
-- <Precursor>
do
if has_next_step then
-- Gather type information
type_recorder.clear
type_recorder.analyze_class (classes.item)
context.set_node_types (type_recorder.node_types)
context.set_checking_class (classes.item)

across rules as l_rules loop
-- If rule is non-standard then it will not be checked by l_rules_checker.
-- We will have the rule check the current class here:
if
l_rules.item.is_enabled.value
and then attached {CA_CFG_RULE} l_rules.item as l_cfg_rule
then
l_cfg_rule.check_class (classes.item)
end
end

-- Status output.
if output_actions /= Void then
output_actions.call ([ca_messages.analyzing_class (classes.item.name)])
end

rules_checker.run_on_class (classes.item)

classes.forth
has_next_step := not classes.after
if not has_next_step then
completed_action.call ([exceptions])
end
end
rescue
-- Instant error output.
if output_actions /= Void then
output_actions.call ([ca_messages.error_on_class (classes.item.name)])
end
exceptions.extend ([exception_manager.last_exception, classes.item])
-- Jump to the next class.
classes.forth
has_next_step := not classes.after
if not has_next_step then
completed_action.call ([exceptions])
end
retry
end
</e>

<e>type_recorder</e> is of type <e>{CA_AST_TYPE_RECORDER}</e>. It uses a functionality of the Eiffel compiler to determine the type of some AST nodes in the current class. The AST itself (as provided by the Eiffel compiler) does not contain any type information. <e>context</e> has type <e>{CA_ANALYSIS_CONTEXT}</e> and contains any side-information such as the previously mentioned types and the current class. The rules were given this context before so that they can access it when needed.

The <e>across</e> loop only checks ''control flow graph rules''. All the ''standard'' rules are checked by the line <e>rules_checker.run_on_class (classes.item)</e>. <e>rules_checker</e> has type <e>{CA_ALL_RULES_CHECKER}</e>. This is the class where each rule must register the AST nodes the rule visits. <e>run_on_class</e> iterates over the AST and calls all the actions that were registered by the standard rules. So this is the way all rules are used to check the current class. <e>step</e> is executed repeatedly until there are no classes left to analyze.

In the <e>rescue</e> clause all possible exceptions are caught and recorded. In case of such an exception it then proceeds to the next class.

== Graphical User Interface ==

The classes of the graphical user interface of the code analyzer are all located in the ''interface'' cluster of ''EVE'', in the subfolder ''graphical > tools > code_analysis''. Here is a short overview of what the single classes do:

; <e>{ES_CODE_ANALYSIS_TOOL}</e> : Represents the code analysis GUI tool. Contains the tool title and icon, otherwise not much interesting stuff.
; <e>{ES_CODE_ANALYSIS_TOOL_PANEL}</e> : The graphical panel for the code analysis tool. It contains buttons, labels, the rule violations table view, and other user interface elements.
; <e>{ES_CODE_ANALYSIS_COMMAND}</e> : The command to launch the code analyzer. It can be added to toolbars and menus. It can be executed using stones.
; <e>{ES_CA_SHOW_PREFERENCES_COMMAND}</e> : The command is used by the ''Preferences'' button in the panel.
; <e>{ES_CA_FIX_EXECUTOR}</e> : This class [[User:Stefan/Code Analysis/Using Analysis Results#Fixing Rule Violations|fixes]] a rule violation that has been found by the code analysis tool.

== Command-line Interface ==

The whole command-line functionality of the code analyzer is located in the class <e>{EWB_CODE_ANALYSIS}</e>. It is located in the ''tty'' cluster of ''EVE''. <e>{EWB_CODE_ANALYSIS}</e> is invoked by <e>{ES}</e>, the root class for the ''batch'' (command-line) version of EiffelStudio. In <e>{ES}</e>, the invocation looks as follows:

<e>
elseif option.is_equal ("-code-analysis") then
l_at_args := arguments_in_range (current_option + 1, argument_count)
current_option := argument_count + 1
create {EWB_CODE_ANALYSIS} command.make_with_arguments (l_at_args)
</e>

Any command-line arguments after ''-code-analysis'' are passed on to <e>{EWB_CODE_ANALYSIS}</e>. This class, in its creation procedure, processes the arguments as described in [[User:Stefan/Code_Analysis/Command Line Usage|Command Line Usage]]. Classes that were passed as command-line arguments are added to the analyzer. Then the actual execution happens in the procedure <e>execute</e>. <e>EWB_CODE_ANALYSIS</e> of course uses the ''code_analysis'' library and the previously described interface of <e>CA_CODE_ANALYZER</e>. After analysis a list of rule violations is output to the command-line. In the code it looks like this:

<e>
across l_code_analyzer.rule_violations as l_vlist loop
if not l_vlist.item.is_empty then
l_has_violations := True
-- Always sort the rule violations by the class they are referring to.
output_window.add (ca_messages.cmd_class + l_vlist.key.name + "':%N")

-- See `{CA_RULE_VIOLATION}.is_less' for information on the sorting.
across l_vlist.item as ic loop
l_rule_name := ic.item.rule.title
l_rule_id := ic.item.rule.id
if attached ic.item.location as l_loc then
l_line := ic.item.location.line.out
l_col := ic.item.location.column.out
output_window.add (" (" + l_line + ":" + l_col + "): "
+ l_rule_name + " (" + l_rule_id + "): ")
else -- No location attached. Print without location.
output_window.add (" " + l_rule_name + " (" + l_rule_id + "): ")
end
ic.item.format_violation_description (output_window)
output_window.add ("%N")
end
end
end

if not l_has_violations then output_window.add (ca_messages.no_issues + "%N") end
</e>

CA Library Implementation

2014-03-06T14:27:04Z

Stefan: /* Graphical User Interface */

CA Library Implementation

2014-03-06T14:11:02Z

Stefan: /* Command-line Interface */

User:Stefan

2014-03-06T13:50:43Z

Stefan: +link

I am a student of Computer Science at the ETH Zürich, Switzerland. There, for my Master thesis, I am currently working on a [[/Code Analysis/]] tool for EVE (the ETH branch of EiffelStudio). Prior to this I earned my Bachelors degree in Mathematics from the Universität Bern, Switzerland. I also did an IT internship with an airline company.

CA Library Implementation

2014-03-06T13:40:46Z

Stefan: CA_CODE_ANALYZER interface

CA Adding New Rules

2014-03-06T13:31:00Z

Stefan:

<center>[[User:Stefan/Code Analysis/Command Line Usage|<< 5. Command Line Usage]] | [[User:Stefan/Code Analysis/Architectural Overview|7. Architectural Overview >>]] </center>
----
 
The Code Analysis framework was designed with regard to the fact that '''adding new rules''' should be as simple and as fast as possible. Looking at the initial set of rules that were implemented, nearly all of them have an implementation of less than 200 lines of code. Many of them use even less than 100 lines of code. Rules that search the code for certain patterns (this applies to the vast majority of rules) are particularly simple to implement.

This page shows you how to implement a rule in the form of a class. After you have written such a class you must add the rule to the list of rules. This list is populated in <e>{CA_CODE_ANALYZER}.make</e>. There, just below the lines where all the other rules are added add a line like

<e>rules.extend (create {YOUR_RULE}.make)</e>,

where <e>YOUR_RULE</e> must be replaced by the name of your rule class and the creation procedure (<e>make</e>) must be adapted if necessary.

== Standard Rules ==

All rules must conform to <e>CA_RULE</e>. The class you implement for a rule is on one hand responsible for checking the rule and contains metadata about the rule (i. e. title, description) on the other hand. As of now, rules must moreover conform to either <e>CA_STANDARD_RULE</e> or <e>CA_CFG_RULE</e>, both of which are subtypes of <e>CA_RULE</e>. A large number of possible rules are ''standard rules'', no matter whether they are trivial or more complicated.

All ''Standard rules'' are checked by iterating over the [http://en.wikipedia.org/wiki/Abstract_syntax_tree abstract syntax tree] (AST) of the class code. The developer who adds a new rule can very well ignore the details thereof. He needs to know however which AST nodes his rule needs to process. For each type of AST node you need to add an agent so your routine will be called during the iteration on the AST.

To start implementing your rule you have basically two possibilities. (1) You start from scratch, implementing all deferred features of <e>CA_STANDARD_RULE</e> or (2) you use the following template.

=== Standard Rule Template ===

<e>
class
CA_YOUR_RULE

inherit
CA_STANDARD_RULE

create
make

feature {NONE} -- Initialization

make (a_pref_manager: attached PREFERENCE_MANAGER)
-- Initialization for `Current'.
do
make_with_defaults
-- This initializes the attributes to their default values:
-- Severity = warning
-- Default Severity Score = 50 (`severity score' can be changed by user)
-- Rule enabled by default = True (`Rule enabled' can be changed by user)
-- Only for system wide checks = False
-- Checks library classes = True
-- Checks nonlibrary classes = True

initialize_options (a_pref_manager)

-- TODO: Add your initialization here.
end

initialize_options (a_pref_manager: attached PREFERENCE_MANAGER)
-- Initializes the rule preferences.
local
l_factory: BASIC_PREFERENCE_FACTORY
do
create l_factory

-- TODO: Add the initialization of your custom preferences here.
-- Example:
-- threshold := l_factory.new_integer_preference_value (a_pref_manager,
-- preference_namespace + "Threshold",
-- 30) -- default value
-- min_local_name_length.set_default_value ("30") -- default value, too
-- min_local_name_length.set_validation_agent (agent is_integer_string_within_bounds (?, 1, 1_000_000))
end

feature {NONE} -- Activation

register_actions (a_checker: attached CA_ALL_RULES_CHECKER)
do
-- TODO: Add agents for the features in section `Rule checking' here.
end

feature {NONE} -- Rule checking

-- TODO: Add the AST processing here.

feature -- Properties

title: STRING_32
do
-- TODO: Add the title of your rule here.
Result := "(Your title)"
end

-- TODO: Add the ID of your rule here. Should be unique!
id: STRING_32 = "(YourID)"

description: STRING_32
do
-- TODO: Add the rule description here.
Result := "(Your description)"
end

format_violation_description (a_violation: attached CA_RULE_VIOLATION; a_formatter: attached TEXT_FORMATTER)
do
-- TODO: Add a formatted description of a concrete violation of this rule here.
end

end
</e>

Let us have a closer look at the various parts of a rule class.

=== Initialization ===

Calling <e>make_with_defaults</e> initializes the attributes to their default values and makes sure that the class invariant is true. If you want to set an attribute to a custom value you can do so by setting it after the call to <e>make_with_defaults</e>.

The creation procedure from the template takes an argument of type <e>PREFERENCE_MANAGER</e>. This is used for initializing preferences that are specific to your rule. Such preferences usually represent integral or boolean values. If you do ''not'' need any custom preferences then you can leave out the argument <e>a_pref_manager</e> of <e>make</e> and you can remove the whole <e>initialize_options</e> feature.

=== AST processing ===

The main part of your rule implementation consists of checking the source code for rule violations. Say, for example, that you want to check <e>if</e> instructions to have certain properties. Then you would add a feature like <e>process_if (a_if_ast: IF_AS)</e> to the section ''Rule checking''. Also, you would need to modify the <e>register_actions</e> feature by adding the line

<e>a_checker.add_if_pre_action (agent process_if)</e>.

Of course you may register as many such agents as you want.

=== Properties ===

The ''title'' and the ''description'' of the rule may be constant strings, they may also be localized strings. The ''rule ID'' must be unique among all rules. It should not contain spaces and should be reasonably short. The main rules that come with ''Code Analysis'' have IDs that are numbered from CA001 to CA999 (many of which are not used).

=== Formatted Violation Description ===

Your rule should be able to produce a formatted description of a concrete rule violation. This description is for example used in the Code Analysis tool panel of the GUI. There, class names and feature names are enabled for pick-and-drop. Variable names, numbers, and strings will be displayed in a nice way, too. In addition, this description is used in command line mode. In order to produce normal, unformatted text, use <e>{TEXT_FORMATTER}.add</e>. For adding formatted elements use features like <e>{TEXT_FORMATTER}.add_local</e>, <e>{TEXT_FORMATTER}.add_feature_name</e> and similar.

You should store all the data you need for this description (variables names, numbers, etc.) in <e>{CA_RULE_VIOLATION}.long_description_info</e>. <e>format_violation_description</e> can then retrieve this data for the formatted output. Here is a simple example of producing a formatted description:

<e>
a_formatter.add ("Feature ")
if attached {STRING_32} a_violation.long_description_info.first as l_feat_name then
a_formatter.add_feature_name (l_feat_name, a_violation.affected_class)
end
a_formatter.add (" is very long.")
</e>

== More Customized Rules ==

For rules that do not fit into a simple AST visitor scheme you best inherit your rule from <e>{CA_STANDARD_RULE}</e>, too. You can for example register agents that get called when a ''class'' or a ''feature'' is processed. Based on these agents you can perform your customized analysis on the classes and/or features. Using ''multiple inheritance'' or just aggregation it should hardly be a problem to include any functionality you need for your analysis.

== Accessing Type Information ==

The AST classes do not contain ''type information''. Suppose your rule processes function calls. Feature calls in the AST do not contain any information on the types, such as the type of the result.

The code analysis framework however provides functionality to retrieve the type of AST nodes. Before the analyzer lets a class be analyzed by all the rules it computes the types of the AST nodes of a class. Hence this data will be available to your rule afterwards.

While your rule is being checked you can retrieve the type of node <e>a_node</e> from feature <e>a_feature</e> by calling <e>current_context.node_type (a_node: AST_EIFFEL; a_feature: FEATURE_I)</e>. <e>{CA_RULE}.current_context</e> is of type <e>{CA_ANALYSIS_CONTEXT}</e> and contains other information about current rule checking, too, such as the currently processed class or the matchlist for this class.

== Accessing the Control Flow Graph ==

Some kinds of static code analysis need and use the ''control flow graph'' of a program. The code analysis framework supports rules that use the control flow graph. If there is at least one such rule, the code analyzer computes the control flow graph of the procedures of the analyzed class before letting the ''rule'' check this class.

=== Worklist algorithms ===

''Control flow graph rules'' iterate over the control flow graph. They do it using a ''worklist''—a list of CFG edges that still have to be processed. At the beginning, the worklist contains all edges of the control flow graph. The algorithm will pick edges from the worklist for processing in an arbitrary order. The iteration stops as soon as there are no more edges left in the worklist. How will the worklist get smaller? Each edge that is processed is removed from the worklist. After processing you will have to decide dynamically whether to add all the outgoing (or incoming, depending on the direction) edges to the worklist. Like this you can take the fact into account that some analyses need certain edges to be processed more than once (a fixed point iteration is such an example).

=== Implementation ===

A control flow analysis may iterate in either direction. For a forward-directed analysis inherit your rule from <e>{CA_CFG_FORWARD_RULE}</e>, for a backward analysis use <e>{CA_CFG_BACKWARD_RULE}</e> instead. In either case you will then have to implement the following deferred features:

; <e>initialize_processing (a_cfg: attached CA_CONTROL_FLOW_GRAPH)</e> : This is called before a routine is processed using the worklist. Essentially you may use it to initialize and prepare all the data structures you will need during analysis.
; <e>visit_edge (a_from, a_to: attached CA_CFG_BASIC_BLOCK): BOOLEAN</e> : This will be called when an edge is being visited. Here, you can put the analysis. If you let <e>Result = False</e> then no further edges will be added to the worklist. If in contrary you let <e>Result = True</e> then edges will be added to the worklist: In a ''forward'' analysis all the ''outgoing'' edges of the current one will be added; in a ''backward'' analysis all the ''incoming'' edges will be added.

=== Non-worklist algorithms ===

If your control flow graph does not fit into the structure of an algorithm as described above you may directly inherit from <e>{CA_CFG_RULE}</e> and implement the feature <e>process_cfg (a_cfg: attached CA_CONTROL_FLOW_GRAPH)</e> (in addition to the features explained above). In this case you do not have to use a worklist; basically you can process the control flow graph in any way you want.

CA Adding New Rules

2014-03-06T13:30:08Z

Stefan:

<center>[[User:Stefan/Code Analysis/Command Line Usage|<< 5. Command Line Usage]] | [[User:Stefan/Code Analysis/Architectural Overview|7. Architectural Overview >>]] </center>
----
 
The Code Analysis framework was designed with regard to the fact that '''adding new rules''' should be as simple and as fast as possible. Looking at the initial set of rules that were implemented, nearly all of them have an implementation of less than 200 lines of code. Many of them use even less than 100 lines of code. Rules that search the code for certain patterns (this applies to the vast majority of rules) are particularly simple to implement.

This page shows you how to implement a rule in the form of a class. After you have written such a class you must add the rule to the list of rules. This list is populated in <e>{CA_CODE_ANALYZER}.make</e>. There, just below the lines where all the other rules are added add a line like

<e>rules.extend (create {YOUR_RULE}.make)</e>,

where <e>YOUR_RULE</e> must be replaced by the name of your rule class and the creation procedure must be adapted if necessary.

== Standard Rules ==

All rules must conform to <e>CA_RULE</e>. The class you implement for a rule is on one hand responsible for checking the rule and contains metadata about the rule (i. e. title, description) on the other hand. As of now, rules must moreover conform to either <e>CA_STANDARD_RULE</e> or <e>CA_CFG_RULE</e>, both of which are subtypes of <e>CA_RULE</e>. A large number of possible rules are ''standard rules'', no matter whether they are trivial or more complicated.

All ''Standard rules'' are checked by iterating over the [http://en.wikipedia.org/wiki/Abstract_syntax_tree abstract syntax tree] (AST) of the class code. The developer who adds a new rule can very well ignore the details thereof. He needs to know however which AST nodes his rule needs to process. For each type of AST node you need to add an agent so your routine will be called during the iteration on the AST.

To start implementing your rule you have basically two possibilities. (1) You start from scratch, implementing all deferred features of <e>CA_STANDARD_RULE</e> or (2) you use the following template.

=== Standard Rule Template ===

<e>
class
CA_YOUR_RULE

inherit
CA_STANDARD_RULE

create
make

feature {NONE} -- Initialization

make (a_pref_manager: attached PREFERENCE_MANAGER)
-- Initialization for `Current'.
do
make_with_defaults
-- This initializes the attributes to their default values:
-- Severity = warning
-- Default Severity Score = 50 (`severity score' can be changed by user)
-- Rule enabled by default = True (`Rule enabled' can be changed by user)
-- Only for system wide checks = False
-- Checks library classes = True
-- Checks nonlibrary classes = True

initialize_options (a_pref_manager)

-- TODO: Add your initialization here.
end

initialize_options (a_pref_manager: attached PREFERENCE_MANAGER)
-- Initializes the rule preferences.
local
l_factory: BASIC_PREFERENCE_FACTORY
do
create l_factory

-- TODO: Add the initialization of your custom preferences here.
-- Example:
-- threshold := l_factory.new_integer_preference_value (a_pref_manager,
-- preference_namespace + "Threshold",
-- 30) -- default value
-- min_local_name_length.set_default_value ("30") -- default value, too
-- min_local_name_length.set_validation_agent (agent is_integer_string_within_bounds (?, 1, 1_000_000))
end

feature {NONE} -- Activation

register_actions (a_checker: attached CA_ALL_RULES_CHECKER)
do
-- TODO: Add agents for the features in section `Rule checking' here.
end

feature {NONE} -- Rule checking

-- TODO: Add the AST processing here.

feature -- Properties

title: STRING_32
do
-- TODO: Add the title of your rule here.
Result := "(Your title)"
end

-- TODO: Add the ID of your rule here. Should be unique!
id: STRING_32 = "(YourID)"

description: STRING_32
do
-- TODO: Add the rule description here.
Result := "(Your description)"
end

format_violation_description (a_violation: attached CA_RULE_VIOLATION; a_formatter: attached TEXT_FORMATTER)
do
-- TODO: Add a formatted description of a concrete violation of this rule here.
end

end
</e>

Let us have a closer look at the various parts of a rule class.

=== Initialization ===

Calling <e>make_with_defaults</e> initializes the attributes to their default values and makes sure that the class invariant is true. If you want to set an attribute to a custom value you can do so by setting it after the call to <e>make_with_defaults</e>.

The creation procedure from the template takes an argument of type <e>PREFERENCE_MANAGER</e>. This is used for initializing preferences that are specific to your rule. Such preferences usually represent integral or boolean values. If you do ''not'' need any custom preferences then you can leave out the argument <e>a_pref_manager</e> of <e>make</e> and you can remove the whole <e>initialize_options</e> feature.

=== AST processing ===

The main part of your rule implementation consists of checking the source code for rule violations. Say, for example, that you want to check <e>if</e> instructions to have certain properties. Then you would add a feature like <e>process_if (a_if_ast: IF_AS)</e> to the section ''Rule checking''. Also, you would need to modify the <e>register_actions</e> feature by adding the line

<e>a_checker.add_if_pre_action (agent process_if)</e>.

Of course you may register as many such agents as you want.

=== Properties ===

The ''title'' and the ''description'' of the rule may be constant strings, they may also be localized strings. The ''rule ID'' must be unique among all rules. It should not contain spaces and should be reasonably short. The main rules that come with ''Code Analysis'' have IDs that are numbered from CA001 to CA999 (many of which are not used).

=== Formatted Violation Description ===

Your rule should be able to produce a formatted description of a concrete rule violation. This description is for example used in the Code Analysis tool panel of the GUI. There, class names and feature names are enabled for pick-and-drop. Variable names, numbers, and strings will be displayed in a nice way, too. In addition, this description is used in command line mode. In order to produce normal, unformatted text, use <e>{TEXT_FORMATTER}.add</e>. For adding formatted elements use features like <e>{TEXT_FORMATTER}.add_local</e>, <e>{TEXT_FORMATTER}.add_feature_name</e> and similar.

You should store all the data you need for this description (variables names, numbers, etc.) in <e>{CA_RULE_VIOLATION}.long_description_info</e>. <e>format_violation_description</e> can then retrieve this data for the formatted output. Here is a simple example of producing a formatted description:

<e>
a_formatter.add ("Feature ")
if attached {STRING_32} a_violation.long_description_info.first as l_feat_name then
a_formatter.add_feature_name (l_feat_name, a_violation.affected_class)
end
a_formatter.add (" is very long.")
</e>

== More Customized Rules ==

For rules that do not fit into a simple AST visitor scheme you best inherit your rule from <e>{CA_STANDARD_RULE}</e>, too. You can for example register agents that get called when a ''class'' or a ''feature'' is processed. Based on these agents you can perform your customized analysis on the classes and/or features. Using ''multiple inheritance'' or just aggregation it should hardly be a problem to include any functionality you need for your analysis.

== Accessing Type Information ==

The AST classes do not contain ''type information''. Suppose your rule processes function calls. Feature calls in the AST do not contain any information on the types, such as the type of the result.

The code analysis framework however provides functionality to retrieve the type of AST nodes. Before the analyzer lets a class be analyzed by all the rules it computes the types of the AST nodes of a class. Hence this data will be available to your rule afterwards.

While your rule is being checked you can retrieve the type of node <e>a_node</e> from feature <e>a_feature</e> by calling <e>current_context.node_type (a_node: AST_EIFFEL; a_feature: FEATURE_I)</e>. <e>{CA_RULE}.current_context</e> is of type <e>{CA_ANALYSIS_CONTEXT}</e> and contains other information about current rule checking, too, such as the currently processed class or the matchlist for this class.

== Accessing the Control Flow Graph ==

Some kinds of static code analysis need and use the ''control flow graph'' of a program. The code analysis framework supports rules that use the control flow graph. If there is at least one such rule, the code analyzer computes the control flow graph of the procedures of the analyzed class before letting the ''rule'' check this class.

=== Worklist algorithms ===

''Control flow graph rules'' iterate over the control flow graph. They do it using a ''worklist''—a list of CFG edges that still have to be processed. At the beginning, the worklist contains all edges of the control flow graph. The algorithm will pick edges from the worklist for processing in an arbitrary order. The iteration stops as soon as there are no more edges left in the worklist. How will the worklist get smaller? Each edge that is processed is removed from the worklist. After processing you will have to decide dynamically whether to add all the outgoing (or incoming, depending on the direction) edges to the worklist. Like this you can take the fact into account that some analyses need certain edges to be processed more than once (a fixed point iteration is such an example).

=== Implementation ===

A control flow analysis may iterate in either direction. For a forward-directed analysis inherit your rule from <e>{CA_CFG_FORWARD_RULE}</e>, for a backward analysis use <e>{CA_CFG_BACKWARD_RULE}</e> instead. In either case you will then have to implement the following deferred features:

; <e>initialize_processing (a_cfg: attached CA_CONTROL_FLOW_GRAPH)</e> : This is called before a routine is processed using the worklist. Essentially you may use it to initialize and prepare all the data structures you will need during analysis.
; <e>visit_edge (a_from, a_to: attached CA_CFG_BASIC_BLOCK): BOOLEAN</e> : This will be called when an edge is being visited. Here, you can put the analysis. If you let <e>Result = False</e> then no further edges will be added to the worklist. If in contrary you let <e>Result = True</e> then edges will be added to the worklist: In a ''forward'' analysis all the ''outgoing'' edges of the current one will be added; in a ''backward'' analysis all the ''incoming'' edges will be added.

=== Non-worklist algorithms ===

If your control flow graph does not fit into the structure of an algorithm as described above you may directly inherit from <e>{CA_CFG_RULE}</e> and implement the feature <e>process_cfg (a_cfg: attached CA_CONTROL_FLOW_GRAPH)</e> (in addition to the features explained above). In this case you do not have to use a worklist; basically you can process the control flow graph in any way you want.

CA Adding New Rules

2014-03-06T13:29:32Z

Stefan: +add the rule to the hardcoded list

<center>[[User:Stefan/Code Analysis/Command Line Usage|<< 5. Command Line Usage]] | [[User:Stefan/Code Analysis/Architectural Overview|7. Architectural Overview >>]] </center>
----
 
The Code Analysis framework was designed with regard to the fact that '''adding new rules''' should be as simple and as fast as possible. Looking at the initial set of rules that were implemented, nearly all of them have an implementation of less than 200 lines of code. Many of them use even less than 100 lines of code. Rules that search the code for certain patterns (this applies to the vast majority of rules) are particularly simple to implement.

This page shows you how to implement a rule in the form of a class. After you have written such a class you must add the rule to the list of rules. This list is populated in <e>{CA_CODE_ANALYZER}.make</e>. Just below the lines where all the other rules are added add a line like

<e>rules.extend (create {YOUR_RULE}.make)</e>,

where <e>YOUR_RULE</e> must be replaced by the name of your rule class and the creation procedure must be adapted if necessary.

== Standard Rules ==

All rules must conform to <e>CA_RULE</e>. The class you implement for a rule is on one hand responsible for checking the rule and contains metadata about the rule (i. e. title, description) on the other hand. As of now, rules must moreover conform to either <e>CA_STANDARD_RULE</e> or <e>CA_CFG_RULE</e>, both of which are subtypes of <e>CA_RULE</e>. A large number of possible rules are ''standard rules'', no matter whether they are trivial or more complicated.

All ''Standard rules'' are checked by iterating over the [http://en.wikipedia.org/wiki/Abstract_syntax_tree abstract syntax tree] (AST) of the class code. The developer who adds a new rule can very well ignore the details thereof. He needs to know however which AST nodes his rule needs to process. For each type of AST node you need to add an agent so your routine will be called during the iteration on the AST.

To start implementing your rule you have basically two possibilities. (1) You start from scratch, implementing all deferred features of <e>CA_STANDARD_RULE</e> or (2) you use the following template.

=== Standard Rule Template ===

<e>
class
CA_YOUR_RULE

inherit
CA_STANDARD_RULE

create
make

feature {NONE} -- Initialization

make (a_pref_manager: attached PREFERENCE_MANAGER)
-- Initialization for `Current'.
do
make_with_defaults
-- This initializes the attributes to their default values:
-- Severity = warning
-- Default Severity Score = 50 (`severity score' can be changed by user)
-- Rule enabled by default = True (`Rule enabled' can be changed by user)
-- Only for system wide checks = False
-- Checks library classes = True
-- Checks nonlibrary classes = True

initialize_options (a_pref_manager)

-- TODO: Add your initialization here.
end

initialize_options (a_pref_manager: attached PREFERENCE_MANAGER)
-- Initializes the rule preferences.
local
l_factory: BASIC_PREFERENCE_FACTORY
do
create l_factory

-- TODO: Add the initialization of your custom preferences here.
-- Example:
-- threshold := l_factory.new_integer_preference_value (a_pref_manager,
-- preference_namespace + "Threshold",
-- 30) -- default value
-- min_local_name_length.set_default_value ("30") -- default value, too
-- min_local_name_length.set_validation_agent (agent is_integer_string_within_bounds (?, 1, 1_000_000))
end

feature {NONE} -- Activation

register_actions (a_checker: attached CA_ALL_RULES_CHECKER)
do
-- TODO: Add agents for the features in section `Rule checking' here.
end

feature {NONE} -- Rule checking

-- TODO: Add the AST processing here.

feature -- Properties

title: STRING_32
do
-- TODO: Add the title of your rule here.
Result := "(Your title)"
end

-- TODO: Add the ID of your rule here. Should be unique!
id: STRING_32 = "(YourID)"

description: STRING_32
do
-- TODO: Add the rule description here.
Result := "(Your description)"
end

format_violation_description (a_violation: attached CA_RULE_VIOLATION; a_formatter: attached TEXT_FORMATTER)
do
-- TODO: Add a formatted description of a concrete violation of this rule here.
end

end
</e>

Let us have a closer look at the various parts of a rule class.

=== Initialization ===

Calling <e>make_with_defaults</e> initializes the attributes to their default values and makes sure that the class invariant is true. If you want to set an attribute to a custom value you can do so by setting it after the call to <e>make_with_defaults</e>.

The creation procedure from the template takes an argument of type <e>PREFERENCE_MANAGER</e>. This is used for initializing preferences that are specific to your rule. Such preferences usually represent integral or boolean values. If you do ''not'' need any custom preferences then you can leave out the argument <e>a_pref_manager</e> of <e>make</e> and you can remove the whole <e>initialize_options</e> feature.

=== AST processing ===

The main part of your rule implementation consists of checking the source code for rule violations. Say, for example, that you want to check <e>if</e> instructions to have certain properties. Then you would add a feature like <e>process_if (a_if_ast: IF_AS)</e> to the section ''Rule checking''. Also, you would need to modify the <e>register_actions</e> feature by adding the line

<e>a_checker.add_if_pre_action (agent process_if)</e>.

Of course you may register as many such agents as you want.

=== Properties ===

The ''title'' and the ''description'' of the rule may be constant strings, they may also be localized strings. The ''rule ID'' must be unique among all rules. It should not contain spaces and should be reasonably short. The main rules that come with ''Code Analysis'' have IDs that are numbered from CA001 to CA999 (many of which are not used).

=== Formatted Violation Description ===

Your rule should be able to produce a formatted description of a concrete rule violation. This description is for example used in the Code Analysis tool panel of the GUI. There, class names and feature names are enabled for pick-and-drop. Variable names, numbers, and strings will be displayed in a nice way, too. In addition, this description is used in command line mode. In order to produce normal, unformatted text, use <e>{TEXT_FORMATTER}.add</e>. For adding formatted elements use features like <e>{TEXT_FORMATTER}.add_local</e>, <e>{TEXT_FORMATTER}.add_feature_name</e> and similar.

You should store all the data you need for this description (variables names, numbers, etc.) in <e>{CA_RULE_VIOLATION}.long_description_info</e>. <e>format_violation_description</e> can then retrieve this data for the formatted output. Here is a simple example of producing a formatted description:

<e>
a_formatter.add ("Feature ")
if attached {STRING_32} a_violation.long_description_info.first as l_feat_name then
a_formatter.add_feature_name (l_feat_name, a_violation.affected_class)
end
a_formatter.add (" is very long.")
</e>

== More Customized Rules ==

For rules that do not fit into a simple AST visitor scheme you best inherit your rule from <e>{CA_STANDARD_RULE}</e>, too. You can for example register agents that get called when a ''class'' or a ''feature'' is processed. Based on these agents you can perform your customized analysis on the classes and/or features. Using ''multiple inheritance'' or just aggregation it should hardly be a problem to include any functionality you need for your analysis.

== Accessing Type Information ==

The AST classes do not contain ''type information''. Suppose your rule processes function calls. Feature calls in the AST do not contain any information on the types, such as the type of the result.

The code analysis framework however provides functionality to retrieve the type of AST nodes. Before the analyzer lets a class be analyzed by all the rules it computes the types of the AST nodes of a class. Hence this data will be available to your rule afterwards.

While your rule is being checked you can retrieve the type of node <e>a_node</e> from feature <e>a_feature</e> by calling <e>current_context.node_type (a_node: AST_EIFFEL; a_feature: FEATURE_I)</e>. <e>{CA_RULE}.current_context</e> is of type <e>{CA_ANALYSIS_CONTEXT}</e> and contains other information about current rule checking, too, such as the currently processed class or the matchlist for this class.

== Accessing the Control Flow Graph ==

Some kinds of static code analysis need and use the ''control flow graph'' of a program. The code analysis framework supports rules that use the control flow graph. If there is at least one such rule, the code analyzer computes the control flow graph of the procedures of the analyzed class before letting the ''rule'' check this class.

=== Worklist algorithms ===

''Control flow graph rules'' iterate over the control flow graph. They do it using a ''worklist''—a list of CFG edges that still have to be processed. At the beginning, the worklist contains all edges of the control flow graph. The algorithm will pick edges from the worklist for processing in an arbitrary order. The iteration stops as soon as there are no more edges left in the worklist. How will the worklist get smaller? Each edge that is processed is removed from the worklist. After processing you will have to decide dynamically whether to add all the outgoing (or incoming, depending on the direction) edges to the worklist. Like this you can take the fact into account that some analyses need certain edges to be processed more than once (a fixed point iteration is such an example).

=== Implementation ===

A control flow analysis may iterate in either direction. For a forward-directed analysis inherit your rule from <e>{CA_CFG_FORWARD_RULE}</e>, for a backward analysis use <e>{CA_CFG_BACKWARD_RULE}</e> instead. In either case you will then have to implement the following deferred features:

; <e>initialize_processing (a_cfg: attached CA_CONTROL_FLOW_GRAPH)</e> : This is called before a routine is processed using the worklist. Essentially you may use it to initialize and prepare all the data structures you will need during analysis.
; <e>visit_edge (a_from, a_to: attached CA_CFG_BASIC_BLOCK): BOOLEAN</e> : This will be called when an edge is being visited. Here, you can put the analysis. If you let <e>Result = False</e> then no further edges will be added to the worklist. If in contrary you let <e>Result = True</e> then edges will be added to the worklist: In a ''forward'' analysis all the ''outgoing'' edges of the current one will be added; in a ''backward'' analysis all the ''incoming'' edges will be added.

=== Non-worklist algorithms ===

If your control flow graph does not fit into the structure of an algorithm as described above you may directly inherit from <e>{CA_CFG_RULE}</e> and implement the feature <e>process_cfg (a_cfg: attached CA_CONTROL_FLOW_GRAPH)</e> (in addition to the features explained above). In this case you do not have to use a worklist; basically you can process the control flow graph in any way you want.

CA Library Implementation

2014-03-06T13:01:35Z

Stefan:

CA Library Implementation

2014-03-06T11:56:41Z

Stefan: intermediate initial version

CA Library Implementation

2014-02-18T15:50:23Z

Stefan: draft

<center>[[User:Stefan/Code Analysis/Adding New Rules|<< 6. Adding New Rules]] |</center>
----
 

== ''code_analysis'' library ==

=== Rule checking ===

== Graphical User Interface ==

== Command-line Interface ==

User:Stefan/Code Analysis/Screenshots

2014-02-18T15:48:06Z

Stefan: Initial version

File:CA Fixing.png

2014-02-18T13:31:19Z

Stefan:

File:CA Rule Preferences.png

2014-02-18T13:30:52Z

Stefan: