CodeSanity 2.8.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 InstallApp() function must be executed.
    Run the following script as a background script in scope x_snc_codesanity:
    10. x_snc_devtools.InstallApp("x_snc_codesanity");
  10. Set the sn_atf.runner.enabled system property to "true" to activate the ATF test execution - if not set already.
  11. 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'
};

Script Includes

  • AppGetDependencies

    Retrieves information about the app's dependencies to other apps and required versions.

  • AppGetProperty

    Gets a system property of this application.

  • AppInstall

    This script installs CodeSanity.

  • AppSetDefaults

    Sets all system properties to default values.

  • AppSetProperty

    Sets a system property of this application.

  • CodeSanityClientAPI

    The CodeSanityClientAPI class contains CodeSanity functions to be called from client side code.

  • Debug

    Produces a log output in the application log using the DevTools Debug function.

  • DevTools

    Implements the extension point for DevTools.

  • DevToolsGetApplicationStatus

    The DevToolsGetApplicationStatus is called by the DevTools extension point instance class and returns the application status object with additional status information to be displayed on the Application overview page.

  • DevToolsGetFormatConfig

    The DevToolsGetFormatConfig function is called by the DevTools extension point instance class and returns an object with field formatting information.

  • DevToolsGetLinkDirectory

    The DevToolsGetLinkDirectory function is called by the DevTools extension point instance class and returns an extended (or modified) link directory object that serves as the basis for the DevTools Link page.

  • DevToolsGetParentRecord

    The DevToolsGetParentRecord function is called by the DevTools extension point instance class and returns a parent record for the given record if it can be determined.

  • GetExecutionRules

    Retrieves all available execution rules which other apps may inject using the CodeSanity extension point.

  • GetLatestResultRecordForApp

    Returns the latest available scan result record for a given app, if it exists, otherwise false.

  • GetScanSourceRecord

    Returns the one and only scan source record that refers to the CodeSanity scan suite record.

  • GetScanSuiteRecord

    Returns the one and only scan suite contained in the CodeSanity app.

  • HtmlRenderCodingGuideline

    Renders detailed descriptions of all checks contained in the CodeSanity suite so that they can be integrated into a Coding Guideline document.

  • IsActive

    Returns true if the application is active, otherwise false.

  • IsCheckApplicableToRecord

    Returns true if the given check should be executed on the given record, false if not.

  • IsCheckApplicableToRecordByRules

    Returns true if the given check should be executed on the given record based on the given rules, false if not.

  • IsCheckInCodeSanitySuite

    Returns true if the given check is part of the CodeSanity scan suite, false if not.

  • Log

    Produces a log output in the application log.

  • ScanAppWithDependencies

    Scans an app and all of its dependencies using the CodeSanity suite.

License

Copyright 2022-2023 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.8.0 - 2023-03-07

  1. DevTools 1.56.0 is now required.
  2. Added check "CodeSanity - AppInstall".
  3. Added check "CodeSanity - Client-side logging".
  4. Added check "CodeSanity - UI Action requires a role".
  5. Added check "CodeSanity - UI Action must have a unique onClick function".
  6. Added check "CodeSanity - Business Rule description".
  7. Added check "CodeSanity - Avoid roles ending with "_user"".
  8. Added check "CodeSanity - ATF test must contain steps".
  9. Added check "CodeSanity - Application menu must have modules".
  10. Added check "CodeSanity - Comment containing "TODO"".
  11. Added check "CodeSanity - Role description".
  12. The check "CodeSanity - Avoid "Copy of"" has been refactored to filter for a specific list of classes to be scanned (instead of all except some exceptions). This is to counter a potential performance issue.
  13. The check "CodeSanity - logging.verbosity system property" no longer executes on global scoped applications.
  14. The check "CodeSanity - App must have a manual page" no longer executes on global scoped applications.
  15. The check "CodeSanity - Bracket-dot anti-pattern" does no longer produce a finding for the use of "sn_fd.Flow_API.getRunner()", as this pattern is proposed by ServiceNow (unfortunately).
  16. UI Action "CodeSanity Point Scan" now requires the "scan_user" role.
  17. Added function ScanAppWithDependencies().
  18. Added ATF test for function PrepareNewCheck().
  19. Added ATF test for function LogBeanCount().
  20. Added ATF test for function HtmlRenderCodingGuideline().

2.7.0 - 2023-01-26

  1. DevTools 1.54.0 is now required.
  2. Added check "CodeSanity - Avoid ATF suite schedules".
  3. Added UI action "CodeSanity Point Scan" to scan a single record against the CodeSanity scan suite.
  4. All UI actions are only visible if the system property "x_snc_codesanity.active" is set to true.
  5. Added business rule "scan_result - Log bean count" to log the bean count at the end of a scan.
  6. The check "CodeSanity - Avoid "Copy of"" is no longer executed on records in sys_hub_flow_variable, sys_scope_privilege, sys_atf_input_variable, sys_atf_step, sys_properties_category_m2m, x_snc_devtools_dependency, sys_extension_instance.
  7. The new system property "x_snc_codesanity.log.beancount.frequency" now controls the frequency of the beancount log output during a scan.
  8. Added ATF for function GetLinkDirectoryInstanceScan().

2.6.0 - 2023-01-17

  1. Added check "CodeSanity - App must have a manual page".
  2. Added function BeanCounter() to count all checks per check and by tables.
  3. The check "CodeSanity - ATF tests for script includes" now considers the "DevToolsRenderDebugDump" script include as an exception.
  4. The check "CodeSanity - Avoid "Copy of"" is no longer executed on records in sys_metadata_delete and sys_security_acl.

2.5.0 - 2023-01-06

  1. DevTools 1.52.0 is now required.
  2. Added check "CodeSanity - ATF suite contains at least one test".
  3. Added check 'CodeSanity - Avoid "Copy of"'.
  4. Added check "CodeSanity - Deprecated logging".
  5. Added check 'CodeSanity - Avoid "Utils" classes'.
  6. The application overview page now shows the duration of the last scan in minutes.
  7. The check "CodeSanity - App documentation" now verifies if a valid url has been provided for the documentation and repository links.
  8. The check "CodeSanity - ATF tests for script includes" now excludes "ClientAPI" script includes which are client callable.
  9. Added function GetScanSourceRecord().
  10. Added function GetLatestResultRecordForApp().
  11. Function GetScanSuiteRecord() is now accessible from all scopes.
  12. Added ATF for function IsCheckInCodeSanitySuite().
  13. AppInstall() now sets the "Scan timeout" transaction quota rule to 6 hours.
  14. AppInstall() now sets the no_truncate attribute on the scan_combo.targets column to avoid application names to be cut off in the list view.

2.4.0 - 2022-12-23

  1. DevTools 1.51.0 is now required.
  2. CodeSanity now supports the "DevTools Application Overview" page and displays the date and amount of findings of the most recent CodeSanity scan.
  3. Added check "CodeSanity - Avoid the spread operator".
  4. Added check "CodeSanity - Do not use fix scripts".
  5. Check "CodeSanity - App documentation" now detects invalid maintainer email addresses.
  6. Check "CodeSanity - Script Include description" treats the AppBuilder() function as an exception as it is only for internal use.
  7. Check "CodeSanity - Application ATF test suite" now runs on sys_app instead of sys_scope.
  8. Check "CodeSanity - ATF tests for script includes" treats the new DevToolsGetApplicationStatus() function as an exception.
  9. The UI action "CodeSanity Scan" now checks if a scan is already running using the UI script function InstanceScanIsRunning().
  10. Added the coding guideline page.
  11. Added ATF test for GetScanSuiteRecord().
  12. ATF for check "CodeSanity - Application ATF test suite" now uses ad-hoc test data to provoke a finding.

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