Squan Sources

Description

Squan Sources provides basic-level analysis of your source code.

For more details, refer to http://www.squoring.com.

Note

The analyser can output info and warning messages in the build logs. Recent additions to those logs include better handling of structures in C code, which will produce these messages:

  • [Analyzer] Unknown syntax declaration for function XXXXX at line yyy to indicate that we whould have found a function but, probably due to preprocessing directives, we are not able to parse it.

  • [Analyzer] Unbalanced () blocks found in the file. Probably due to preprocessing directives, parenthesis in the file are not well balanced.

  • [Analyzer] Unbalanced {} blocks found in the file. Probably due to preprocessing directives, curly brackets in the file are not well balanced.

Tip

You can specify the languages for your source code by passing pairs of language and extensions to the languages paramater. For example, a project mixing php and javascript files can be analysed with:

--dp "type=SQuORE,languages=php:.php;javascript:.js,.JS" 

Usage

Squan Sources has the following options:

  • Languages (languages) Check the boxes for the languages used in the specified source repositories. Adjust the list of file extensions as necessary. Note that two languages cannot use the same file extension, and that the list of extensions is case-sensitive. Tip: Leave all the boxes unchecked and Squan Sources will auto-detect the language parser to use.

  • Force full analysis (rebuild_all, default: false) Analyses are incremental by default. Check this box if you want to force the source code parser to analyse all files instead of only the ones that have changed since the previous analysis. This is useful if you added new rule files or text parsing rules and you want to re-evaluate all files based on your modifications.

  • Generate control graphs (genCG, default: true) This option allows generating a control graph for every function in your code. The control graph is visible in the dashboard of the function when the analysis completes.

  • Use qualified names (qualified, default: false) Note: This option cannot be modified in subsequent runs after you create the first version of your project.

  • Limit analysis depth (depth, default: false) Use this option to limit the depth of the analysis to file-level only. This means that Squan Sources will not create any class or function artefacts for your project.

  • Add a 'Source Code' node (scnode, default: false) Using this options groups all source nodes under a common source code node instead of directly under the APPLICATION node. This is useful if other data providers group non-code artefacts like tests or requirements together under their own top-level node. This option can only be set when you create a new project and cannot be modified when creating a new version of your project.

  • 'Source Code' node label (scnode_name, default: Source Code) Specify a custom label for your main source code node. Note: this option is not modifiable. It only applies to projects where you use the "Add a 'Source Code' node" option. When left blank, it defaults to "Source Code".

  • Compact folders (compact_folder, default: true) When using this option, folders with only one son are aggregates together. This avoids creating many unnecessary levels in the artefact tree to get to the first level of files in your project. This option cannot be changed after you have created the first version of your project.

  • Content exclusion via regexp (pattern) Specify a PERL regular expression to automatically exclude files from the analysis if their contents match the regular expression. Leave this field empty to disable content-based file exclusion.

  • File Filtering (files_choice, default: Exclude) Specify a pattern and an action to take for matching file names. Leave the pattern empty to disable file filtering.

  • pattern (pattern_files) Use a shell-like wildcard e.g. '*-test.c'. * Matches any sequence of characters in string, including a null string. ? Matches any single character in string. [chars] Matches any character in the set given by chars. If a sequence of the form x-y appears in chars, then any character between x and y, inclusive, will match. On Windows, this is used with the -nocase option, meaning that the end points of the range are converted to lower case first. Whereas {[A-z]} matches '_' when matching case-sensitively ('_' falls between the 'Z' and 'a'), with -nocase this is considered like {[A-Za-z]}. \x Matches the single character x. This provides a way of avoiding the special interpretation of the characters *?[] in pattern. Tip: Use ; to separate multiple patterns.

  • Folder Filtering (dir_choice, default: Exclude) Specify a pattern and an action to take for matching folder names. Leave the pattern empty to disable folder filtering.

  • pattern (pattern_dir) Use a shell-like wildcard e.g. 'Test_*'. * Matches any sequence of characters in string, including a null string. ? Matches any single character in string. [chars] Matches any character in the set given by chars. If a sequence of the form x-y appears in chars, then any character between x and y, inclusive, will match. On Windows, this is used with the -nocase option, meaning that the end points of the range are converted to lower case first. Whereas {[A-z]} matches '_' when matching case-sensitively ('_' falls between the 'Z' and 'a'), with -nocase this is considered like {[A-Za-z]}. \x Matches the single character x. This provides a way of avoiding the special interpretation of the characters *?[] in pattern. Tip: Use ; to separate multiple patterns.

  • Detect algorithmic cloning (clAlg, default: true) When checking this box, Squan Sources launches a cloning detection tool capable of finding algorithmic cloning in your code.

  • Detect text cloning (clTxt, default: true) When checking this box, Squan Sources launches a cloning detection tool capable of finding text duplication in your code.

  • Backwards-compatible cloning (clBw, default: false) When checking this box, the cloning detection tool is run in a way that produces metrics that are backwards-compatible with earlier versions of this product (2014-A): exact matching is used for algorithmic cloning and a 5% margin is used for text duplication. This legacy behaviour should only be used if you are using an old configuration that was developed before 2014-B.

  • Cloning fault ratio (clFR, default: 0.1) This threshold defines how much cloning between two artefacts is necessary for them to be considered as clones by the cloning detection tool. For example, a fault ratio of 0.1 means that two artefacts are considered clones if less than 10% of their contents differ. Note that this option is ignored if you are using backwards-compatible cloning.

  • Detect Open Source cloning (deprecated) (clOS, default: false) This option is no longer supported and should not be used anymore.

  • Compute Textual stability (genTs, default: true) This option allows keeping track of the stability of the code analysed for each version. The computed stability is available on the dashboard as a metric called and can be interpreted as 0% meaning completely changed and 100% meaning not changed at all.

  • Compute Algorithmic stability (genAs, default: true) This option allows keeping track of the stability of the code analysed for each version. The computed stability is available on the dashboard as a metric called Stability Index (SI) and can be interpreted as 0% meaning completely changed and 100% meaning not changed at all.

  • Detect artefact renaming (clRen, default: true) This option allows Squan Sources to detect artefacts that have been moved since the previous version, ensuring that the stability metrics of the previous artefact are passed to the new one. This is typically useful if you have moved a file to a different folder in your source tree and do not want to lose the previous metrics generated for this file. If you do not use this option, moved artefacts will be considered as new artefacts.

  • Additional parameters (additional_param) These additional parameters can be used to pass instructions to external processes started by this data provider. This value is generally left empty in most cases.

The full command line syntax for Squan Sources is:

-d "type=SQuORE,languages=[multipleChoice],rebuild_all=[booleanChoice],genCG=[booleanChoice],qualified=[booleanChoice],depth=[booleanChoice],scnode=[booleanChoice],scnode_name=[text],compact_folder=[booleanChoice],pattern=[text],files_choice=[multipleChoice],pattern_files=[text],dir_choice=[multipleChoice],pattern_dir=[text],clAlg=[booleanChoice],clTxt=[booleanChoice],clBw=[booleanChoice],clFR=[text],clOS=[booleanChoice],genTs=[booleanChoice],genAs=[booleanChoice],clRen=[booleanChoice],additional_param=[text]"