isml-linter

ISML Linter

ISML Linter is a tool for examining if your project's templates follow a specified set of rules defined by your dev team. The available rules can be roughly grouped into:

• Styles that are defined by your team;
• Syntactic errors related to <is* > tags;
• Coding conventions recommended by Salesforce;
• Git conflicts that may accidentally be left unresolved;

Please feel free to make suggestions and help make this linter better. :) The set of currently available rules can be found below.

ISML Linter is also available as a VSCode extension, give it a try!

Installation

Prerequisite: Node.js (>=10.0.0).

Simply run in your project's root directory:

$ npm install isml-linter --save-dev

and add the following to package.json:

"scripts": {
    "init:isml":  "./node_modules/.bin/isml-linter --init",
    "lint:isml":  "./node_modules/.bin/isml-linter",
    "build:isml": "./node_modules/.bin/isml-linter --build",
    "fix:isml":   "./node_modules/.bin/isml-linter --autofix"
}

Here's what each script does:

• init:isml creates a config file;
• lint:isml simply lists the broken rules in the console;
• build:isml raises an error if there is any broken rule, thus can be used in your build process;
• fix:isml applies fixes for the enabled rules;

Configuration

After adding the above scripts to package.json, run the following command to generate a config file containing all available rules:

npm run init:isml

Alternatively, you can manually create a configuration file, make sure it is in the project root directory and has one of the following names: ismllinter.config.js, .ismllintrc.js or .ismllinter.json.

You can disable any rule by removing it from the config file. You may also find these configuration options useful:

Config	Description
rootDir	The root directory under which the linter will run. Defaults to the directory where the package.json file is
disableHtml5	Disallows HTML5-defined unclosed tags, such as input, img and meta. Default: false
ignoreUnparseable	Does not raise an error if an unparsable template is found. Default: false. Please check "Parse Modes - Tree" section below
ignore	If a template path contains (as a substring) any string defined here, that template will be ignored by the linter
indent	[Deprecated] Please check indent docs. Indentation size. Default: 4
linebreakStyle	unix or windows. Default: unix
eslintConfig	Path to a eslint configuration file, to be applied within <isscript> tags. Default: .eslintrc.json
enableCache	[Deprecated] Please check cache docs. Default: false
autoFix	Applies fixes for enabled rules. Default: false
printPartialResults	Limits issues or rule occurrences listed in the console to up to 30 items. Useful to get overall picture in case of many errors. Default: false
verbose	Provides additional details of the linting process in the console. Default: false
disableTreeParse	Enables only rules that do not depend on building an ISML tree. Check below when this might be useful. Default: false
rules	Defines which rules to check. See available rules below

Note: If you explicitly set "ignoreUnparseable" config to true, unparsable templates may contain errors that will not be detected by ISML Linter.

Example configuration:

{
    "rootDir": "./cartridges",
    "ignore": [
        "this_directory_is_to_be_ignored"
        "Email.isml"
    ],
    "rules" : {
        "no-br" : {}, 
        "enforce-require" : {}
    }
}

Note that according to the above configurations, the following templates would be ignored by ISML Linter:

• registerEmail.isml
• some/path/welcomeEmail.isml
• this_directory_is_to_be_ignored/producttile.isml
• some/path/this_directory_is_to_be_ignored/confirmationpage.isml

Parse Modes

Tree (disableTreeParse : false)

This is the default, and most powerful mode. It analyses the template and tries to build an "ISML DOM" tree to then apply the enabled rules. It is required that the template is parsable.

For example, if a template contains a snippet like the following, IT IS NOT considered a parsable template:

<isif condition="${aCondition}">
    <div class="info">
</isif>
        Some content
<isif condition="${aCondition}">
    </div>
</isif>

since the linter is not able to make an association between the opening and the corresponding closing <div> elements. This is the only known limitation for this parse mode. One possible solution to turn such templates into parsable is to replace that snippet by:

<isif condition="${aCondition}">
    <div class="info">
        <isinclude template="myTemplate" />
    </div>
<iselse/>
    <isinclude template="myTemplate" />
</isif>

There are other possible, potentially more "best practice" approaches, but it goes beyond the scope of this article.

And, to avoid possible doubts, here is an extra piece of information: it is allowed to have ISML tags within HTML tags, such as:

<div <isif ...> </isif> />

Line by Line (disableTreeParse : true)

This is a more robust, less powerful mode. It only has a few set of rules available and is indicated for cases where there are many, many lint errors and you want fix them gradually. It is also recommended in cases you don't want to force templates to be parsable (see previous section). This mode is ideally temporary, as it cannot take advantages of even some simple rules, such as indentation checking.

Command Line Interface

Please check CLI docs.

Git Hooks (Optional)

To prevent new errors to be introduced in next pushes, we recommend using some git hook npm package, such as husky or ghooks. The following example works for ghook:

"config": {
    "ghooks": {
      "pre-push": "npm run build:isml"
    }
}

API

Check the API docs.

Available Rules

Please check the Generic Configurations for Rules page.

Rule	Description
:exclamation: no-br	[Deprecated] Disallows <br/> tags. Enable this rule if you prefer to use CSS to handle vertical spacing
no-git-conflict	Disallows unresolved Git conflicts
no-import-package	Disallows importPackage() function. It is recommended by Salesforce to use require() instead
:exclamation: no-isscript	[Deprecated] Disallows <isscript/> tag in template. Enable this rule if you prefer logic to be kept in a separate .ds/.js file
:wrench: no-trailing-spaces	Disallows trailing blank spaces
:wrench: no-space-only-lines	Disallows lines that contain only blank spaces, i.e., unnecessarily indented
no-inline-style	Disallows use of style HTML attribute. Enable this rule if you prefer style to be fully handled via CSS
:wrench: no-tabs	Disallows use of tabs
enforce-isprint	[KNOWN BUG] Enforces every ${string} to be wrapped by an <isprint/> tag
enforce-require	Disallows direct calls to a DigitalScript class, such as in: var PaymentMgr = dw.order.PaymentMgr; For this case, it is recommended to use instead: var PaymentMgr = require('dw/order/PaymentMgr');
lowercase-filename	Disallows template names to have uppercase characters
max-lines	Limits the size of templates
:small_orange_diamond: no-hardcode	Disallows hardcoded strings outside ISML expressions
:wrench: :small_orange_diamond: indent	Sets indentation size
:small_orange_diamond: no-require-in-loop	No require() calls from within a loop in the template
:small_orange_diamond: no-embedded-isml	Disallows embedded isml tags, such as in <div <isif /> />, except for <isprint />
:small_orange_diamond: max-depth	Sets the maximum of nested elements in a template
:small_orange_diamond: disallow-tags	Disallows tags specified at rule level
:small_orange_diamond: one-element-per-line	One element per line
:wrench: :small_orange_diamond: leading-iscontent	Ensures <iscontent> tag is the first element in the template if present
:wrench: :small_orange_diamond: leading-iscache	Ensures <iscache> tag is among the first element in the template if present
:small_orange_diamond: no-deprecated-attrs	Disallows deprecated attributes or attribute values
:small_orange_diamond: contextual-attrs	Disallows presence of mutually exclusive attributes
:small_orange_diamond: custom-tags	Checks if "util/modules" template is actually needed or if it is missing
:wrench: :small_orange_diamond: eslint-to-isscript	Applies ESLint rules to <isscript> tag content
:wrench: :small_orange_diamond: no-iselse-slash	Disallows self-closing <iselse> and <iselseif> tags
:small_orange_diamond: empty-eof	Enforces a empty line at the end of the template
:small_orange_diamond: align-isset	Aligns contiguous <isset> tags attributes' columns
:small_orange_diamond: enforce-security	Enforces security measures
:wrench: :small_orange_diamond: no-redundant-context	Prevents use of unnecessary contexts, such as dw.web.Resource
:small_orange_diamond: strict-void-elements	Disallows closing tags for void elements, such as <input> and <img>

You are more than welcome to contribute with us! Please check the contribute section.

Donations

This project was conceived by its author without any financial support, with the intention to help the community improving and speeding up any projects that involve ISML templates. If you think ISML Linter has helped you and your team, please consider making a donation, it will be much appreciated!

Iconography

:exclamation: Deprecated feature
:boom: New feature
:small_orange_diamond: Rules that require "disableTreeParse" configuration not to be true.
:wrench: Auto-fix available

Changelog

[5.43.9] - 2023-03-05

Fixed

• "leading-iscache" and "leading-iscontent" rules - update tree data after move nodes on autofix mode;