CodeSanity 2.3.0

Welcome to CodeSanity - created and maintained by Sascha Wildgrube.

Features

The CodeSanity app contains a number of instance scan checks to validate source code and other application files.

The CodeSanity scan suite can act as the foundation and master source for a coding guideline document.

Execution rules can be used to control which checks run on which applications and which do not.

Disclaimer

CodeSanity is NOT an officially supported ServiceNow product.

CodeSanity does NOT come with any kind of warranty. If you use it, you own it!

System Requirements

Installation

  1. Create an account on GitHub - if not done already.
  2. Create a personal access token for your GitHub account.
  3. Add credentials to access GitHub - use "Basic Auth".
  4. Fork the repository https://github.com/saschawildgrube/servicenow-devtools.
  5. Go to Studio and import the DevTools application from source control.
  6. Perform all installation steps for the DevTools application documented here: https://www.wildgrube.com/servicenow-devtools 
  7. Fork the repository https://github.com/saschawildgrube/servicenow-codesanity.
  8. Go to Studio and import the CodeSanity application from source control.
  9. The x_snc_codesanity.AppInstall() function must be executed.
    Run the following script as a background script in scope x_snc_codesanity:
  10. x_snc_codesanity.AppInstall();
  11. Set the sn_atf.runner.enabled system property to "true" to activate the ATF test execution - if not set already.
  12. Run the CodeSanity test suite.

Instance Scan checks contained in the CodeSanity app

Testing the CodeSanity scan suite

Each CodeSanity check comes with a corresponding ATF test to ensure its function. All tests are part of the CodeSanity test suite. The check "CodeSanity - ATF tests for checks" verifies that there is an ATF test for each CodeSanity check.

Adding checks to the CodeSanity scan suite

  1. Change the scope to the app which should contain your new check - this should NOT be the CodeSanity app. If you do not yet have a separate app, create one first.
  2. Navigate to the "CodeSanity" menu.
  3. Select "Add new check" in the menu.
  4. Create and save the new check - it will automatically be added to the CodeSanity scan suite.

Execution rules

In a larger developer community there might be variations in the coding guideline. Each and every project might have different rules - sometimes because a coding guideline has been introduced when many applications are already built or just because there are special considerations or coding patterns in use in a project.

Execution rules can be used to define which checks in the CodeSanity scan suite should run on which records and which should not.

Blacklisting

Blacklisting rules specify which checks should NOT run on records in specific app scopes. Use blacklisting rules if there are checks that just do not apply to one or more applications or which should be deactivated completely.

Whitelisting

Whitelisting rules specify checks that should ONLY run on records in specific app scopes. Use whitelisting rules if there are checks that only apply to one or more applications.

Whitelisting rules override blacklisting rules.

Setup

Follow these steps to set up execution rules:

  1. If not done already create a new application that contains the execution rules.
  2. Open the new app in Studio.
  3. Create a script include based on the CodeSanity extension point example code.
  4. Modify the function GetExecutionRules() - the examples demostrate how it works.
  5. Create an extension point implementation and link it to the script include and the CodeSanity extension point.

Checks and scopes can be referenced by Sys Id or by their name. Both options obviously have pros and cons. Sys Ids are not going to change, but names are easier to read - a tough decision.

Creating a coding guideline document

CodeSanity checks can become the foundation of a coding guideline document. The CodeSanity app contains the function HtmlRenderCodingGuideline which outputs the descriptions of all checks contained in the CodeSanity scan suite so that they can be integrated into an html page. Follow these steps to create a UI page that can act as the organization's coding guideline document:

  1. Switch the scope to the app that should contain the new UI page - this should NOT be "CodeSanity".
  2. Create a new UI page.
  3. Add the following code to the html template of the UI page:
    <g2:no_escape>$[x_snc_codesanity.HtmlRenderCodingGuideline();]</g2:no_escape>

The output of the UI page can then be transferred into a corporate wiki or the ui page acts as the coding guideline document itself.

There might be guidelines which are difficult to check mechanically. However a check could be created that does not produce any findings but that contains the documentation of the guideline. CodeSanity checks may hence become the master source for all coding guidelines - no matter if they can be checked mechanically or not.

Limitations and Caveats

  • Under yet unspecified circumstances a suite scan triggered via the "Execute Scan Suite" button on the suite form against an app may not produce all relevant findings. The ServiceNow product development team is made aware of that problem. Use the "CodeSanity Scan" button on the application form instead!
  • Instance Scan does not work with scripts in Flow Designer. When scripted action steps are used such scripts are not considered in scans. The ServiceNow product development team is made aware of that problem.

Helpful links on Instance Scan

Reference

UI Actions

Configuration Options

Extension Points

  • CodeSanity

    The extension point allows to define additional execution rules. The function GetExecutionRules() can set (or remove) rules that will be considered by all CodeSanity checks.

    var CodeSanity = Class.create();
    CodeSanity.prototype = {
    	initialize: function()
    	{	
    	},
    
    	GetExecutionRules: function(rules)
    	{
    		// To disable the check "CodeSanity - Throwing exceptions" on scope "x_your_scope"
    		rules.blacklist.push(
    			{
    				scopes : ['x_your_scope'],
    				checks : ['CodeSanity - Throwing exceptions'],
    			});
    			
    		// To disable the check "CodeSanity - Bracket-dot anti-pattern"
    		rules.blacklist.push(
    			{
    				all: true,
    				checks : ['CodeSanity - Bracket-dot anti-pattern'],
    			});
    		
    		// To run the check "CodeSanity - Your specific check" only in scope "x_your_scope" and scope "x_your_other_scope"
    		rules.whitelist.push(
    			{
    				scopes : ['x_your_scope','x_your_other_scope'],
    				checks : ['CodeSanity - Your specific check'],
    			});	
    
    		return rules;
    	},	
    
    	type: 'CodeSanity'
    };

License

Copyright 2022 by Sascha Wildgrube

Licensed under the Apache License, Version 2.0 (the "License")

You may not use CodeSanity except in compliance with the License.

You may obtain a copy of the License at: https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Release Notes

2.3.0 - 2022-11-30

  1. DevTools 1.48.0 is now required.
  2. Added check "CodeSanity - Script Include description".
  3. Added check "CodeSanity - UI Script description".
  4. The UI action "CodeSanity Scan" now handles already running Instance Scans properly.
  5. The function IsCheckApplicableToRecord() is now using DevTools IsTestRunning() to determine whether an instance scan check is executed as part of an ATF. This allows to test checks via ATF even if they are blacklisted.
  6. Added ATF test for function GetAppIdentifiers().

2.2.0 - 2022-11-29

  1. DevTools 1.47.0 is now required.
  2. Tokyo is now actively supported.
  3. Added the UI action "CodeSanity Scan" to the custom application form.
  4. Renamed the CodeSanity category to "CodeSanity".
  5. Added check "CodeSanity - App documentation".
  6. Added check "CodeSanity - ATF test must be in an ATF suite".
  7. Added check "CodeSanity - ATF tests for script includes".
  8. The check "CodeSanity - Constant array index anti-pattern" produced false positives on string literals that contained the pattern. This has been fixed.
  9. Improved documentation in check "CodeSanity - Constant array index anti-pattern".
  10. The check "CodeSanity - Script include must contain a class or function" now also supports modern JavaScript class syntax as supported starting with Tokyo.
  11. The scan result list now uses an improved list layout displaying more details on the scan.
  12. The coding guideline is now rendered using "clean" application names (without "WORK IN PROGRESS" post-fixes).
  13. Added UI actions to the manual.
  14. Added system properties to the manual.
  15. Added ATF test for function GetAppIdentifier().

2.1.0 - 2022-11-02

  1. Execution rules now also support application names of global scoped apps.
  2. Added check "CodeSanity - GlideRecord without new".
  3. Added check "CodeSanity - Application ATF Test Suite".
  4. Added check "CodeSanity - Avoid engine.current".
  5. Added check "CodeSanity - Modules must require a role".
  6. The check "CodeSanity - Avoid arrow functions" was inactive and not effective. This has been fixed.
  7. The check "CodeSanity - Sys IDs in scripts" does no longer check Fix Scripts (sys_script_fix).
  8. The check "CodeSanity - Sys IDs in scripts" now detects simple obfuscation strategies (i.e. splitting a sys_id in two or more concatenated strings).
  9. The check "CodeSanity - Application names in code" now considers a few exceptions as a view name may be the same as an application name - this covers sysrule_view records and a limited number of script includes.
  10. The check "CodeSanity - String concatenation anti-pattern" has been removed as it turned out not to provide any real value.
  11. The code template used when adding a new check has been improved.
  12. When creating a new check, the priority is set to 1 by default.
  13. AppInstall() now also executes DevTools' AppInstall() function.
  14. Removed the function HtmlRenderOtherInstanceScanChecks().
  15. Improved performance of GetExecutionRules() by using transaction caching.
  16. Improved installation instructions contained in the manual.

2.0.1 - 2022-08-25

  1. A defect in IsCheckApplicableToRecord() caused checks not to run which are part of another scope than CodeSanity. This has been fixed.

2.0.0 - 2022-08-18

  1. DevTools 1.42.0 is now required.
  2. Introducing the "Execution Rules" feature to control which checks should run on which records - this requires ALL CodeSanity checks to use new function IsCheckApplicableToRecord() to check if the check should run on the given record.
  3. Added guidance to the manual on how to create a coding guideline document based on CodeSanity checks.
  4. The function HtmlRenderCodingGuideline() now also renders the execution rules that apply to a check.
  5. When adding a new check the script field is prepopulated with the essential logic of a CodeSanity check.
  6. Added check "CodeSanity - CodeSanity table checks apply rules" to make sure all CodeSanity table checks use the new function IsCheckApplicableToRecord().
  7. Added check "CodeSanity - CodeSanity linter checks apply rules" to make sure all CodeSanity linter checks use the new function IsCheckApplicableToRecord().
  8. Added check "CodeSanity - CodeSanity column type checks apply rules" to make sure all CodeSanity column type checks use the new function IsCheckApplicableToRecord().
  9. Added check "CodeSanity - Checks must be tested using ATF" to ensure that all checks are covered by ATF tests.
  10. Added check "CodeSanity - Temporary tables" to test if there are temporary import tables left.
  11. Added check "CodeSanity - Do not run flows from scripts" to make sure that no script triggers flows or subflows.
  12. Priority of new checks is set to "Critical" by default.
  13. Added function IsCheckApplicableToRecord() to check if a check whould be applied to the given record.
  14. Added extension point "CodeSanity" including the GetExecutionRules() function and added GetExecutionRules() function to collect execution rules from multiple extension point implementations.
  15. The function HtmlRenderCodingGuideline() now renders line breaks in check descriptions properly.
  16. Added ATF tests for various checks.
  17. Updated manual on testing the CodeSanity scan suite.

1.6.0 - 2022-07-27 - Birthday Edition

  1. Added check "CodeSanity - Script include has a valid name".
  2. Added check "CodeSanity - InstallerAPI without context".
  3. Added check "CodeSanity - Avoid arrow functions". Although arrow functions are not yet supported in ServiceNow.
  4. Added check "CodeSanity - Widget checks for input".
  5. The check "Checks for the bracket-dot anti-pattern" now allows the pattern "gs.getUser()." because we can assume that gs.getUser() always returns GlideUser object.
  6. The check "Checks for the bracket-dot anti-pattern" now allows patterns like "$('needle')." to support jquery in sp_widget client code.
  7. Renamed check "CodeSanity - [0] anti-pattern" to "CodeSanity - Constant array index anti-pattern".
  8. Added the function HtmlrenderCodingGuideline() to produce ui pages that can serve as a coding guideline document.
  9. This manual page no longer shows instance scan checks that are contained in other apps.

1.5.0 - 2022-07-08

  1. DevTools 1.40.0 is now required.
  2. Check "CodeSanity - Bracket-dot anti-pattern" is now making an exception for sp_widget records to allow the pattern: "server.update().then(".
  3. Check "CodeSanity - Sys IDs in scripts" has been updated to check only against letters from 'a' to 'f'.
  4. Check "CodeSanity - String concatenation anti-pattern" now allows concatenated strings if the second string starts with a backslash and hence indicates an escaped character.

1.4.0 - 2022-06-12

  1. DevTools 1.39.0 is now required.
  2. Added check "CodeSanity - logging.verbosity system property".
  3. The check "CodeSanity - Script include must contain a class or function" was improved to avoid false negatives.
  4. The check "CodeSanity - Throwing exceptions" was improved to avoid false positives.
  5. Added the "logging.verbosity" system property.
  6. Added first ATF tests to verify the checks and removed the "AntiPattern" script includes.

1.3.0 - 2022-06-10

  1. Added the check "CodeSanity - UI Actions without comments".
  2. The check "CodeSanity - Application names in code" now considers the AppInstall() function as an exception.
  3. The check "CodeSanity - Script include must contain a class or function" is now considering comments at the top of the script.

1.2.0 - 2022-05-31

  1. DevTools 1.38.0 is now required.
  2. Added check "CodeSanity - Script include must contain a class or function".
  3. Added check "CodeSanity - Table check code pattern".
  4. The check against application names in code now considers application name postfixes (like "WORK IN PROGRESS" etc.).
  5. The check against application names in code now considers specific code patterns as exceptions where it is unlikely that the string is actually the application name - i.e. where the string is more likely a class name or the name of an extension point.
  6. The check against application names in code now considers the function x_snc_codesanity.GetScanSuiteRecord() and any script include containing "GetLinkDirectory" in the name as an exception.
  7. The check against the [0] anti pattern is now considering any constant number pre or postfixed by whitespace characters.
  8. More exceptions have been added for the check against Sys IDs in scripts.

1.1.0 - 2022-04-19

  1. DevTools 1.37.0 is now required.
  2. Priority of all checks is now set to "Critical".
  3. Refactored CodeSanity's own code not to trigger any findings other than in the honey pot script include "AntiPatterns".
  4. Added a check against the use of application names in source code.
  5. Added a check if the field "short_description" is used in a condition statement.
  6. Added a check against using the Date class constructor without parameters.
  7. Added a check against the bracket-dot anti-pattern.
  8. Added a check against the string concatenation anti-pattern.
  9. Several exceptions have been added for the check against Sys IDs in scripts as some specific functions will need to contain Sys IDs no matter what.
  10. Corrected a defect in the check against Sys IDs in source code.

1.0.0 - 2022-03-15

First baselined version