Plugins

Plugins are the basic unit for rules application. Plugins defines actions which can be either verbs or conditionals.

conditionals filter the execution of verbs in a rule. If all the conditionals of a rule returns true, the verbs are executed. Conditionals are identified because they start with the prefix if.
verbs execute actions against the files defined in the special files property of each rule. They act like asserters.

inclusion

Plain content inclusion management.

includeLines

Check that the files include all lines passed as argument.

If the files don’t include all lines specified as argument, it will raise a checking error. Newlines are ignored, so they should not be specified.

Example

{
  rules: [
    files: [".gitignore"],
    includeLines: ["venv*/", "/dist/"]
  ]
}

New in version 0.1.0.

ifIncludeLines

Conditional to exclude rule only if some files include a set of lines.

If one file don’t include all lines passed as parameter, the rule will be ignored.

Accepts an object mapping files to lines that must be included in order to execute the rule.

Example

If the license defined in the LICENSE file is BSD-3, tool.poetry.license must correspont:

{
  rules: [
    files: ["pyproject.toml"],
    ifIncludeLines: {
      LICENSE: ["BSD 3-Clause License"],
    },
    JMESPathsMatch: [
      ["tool.poetry.license", "BSD-3-License"],
    ]
  ]
}

New in version 0.1.0.

excludeContent

Check that the files do not include certain content.

The specified partial contents can match multiple lines and line ending characters.

Example

Don’t allow code blocks in RST documentation files:

Bash is not a POSIX compliant shell.
Pygments’ JSON5 lexer is not implemented yet.

{
  rules: [
    files: ["docs/**/*.rst"],
    excludeContent: [
      ".. code-block:: bash",
      ".. code-block:: json5",
    ],
  ]
}

New in version 0.3.0.

existence

Check existence of files.

ifFilesExist

Check if a set of files and/or directories exists.

It acceepts an array of paths. If a path ends with / character it is considered a directory.

Examples

If the directory src/ exists, a pyproject.toml file must exist also:

{
  rules: [
    files: ["pyproject.toml"],
    ifFilesExist: ["src/"],
  ]
}

If the file .pre-commit-hooks.yaml exists, must be declared as an array:

{
  rules: [
    files: [".pre-commit-hooks.yaml"],
    ifFilesExist: [".pre-commit-hooks.yaml"],
    JMESPathsMatch: [["type(@)", "array"]]
  ]
}

New in version 0.4.0.

jmespath

JMES paths manipulation against files.

The actions of this plugin operates against object-serialized versions of files, so only files that can be serialized can be targetted (see Objects serialization).

You can use in expressions all JMESPath builtin functions plus a set of convenient functions defined by the plugin internally:

regex_match(pattern: str, string: str) → bool: Match a regular expression against a string using the Python’s built-in re.match() function.

New in version 0.1.0.

regex_matchall(pattern: str, strings: list[str]) → bool: Match a regular expression against a set of strings defined in an array using the Python’s built-in re.match() function.

New in version 0.1.0.

Deprecated since version 0.4.0.

regex_search(pattern: str, string: str) → list[str]: Search using a regular expression against a string using the Python’s built-in re.search() function. Returns all found groups in an array or an array with the full match as the unique item if no groups are defined. If no results are found, returns an empty array.

New in version 0.1.0.

op(source: type, operation: str, target: type) → bool

Applies the operator operator between the two values using the operators for two values defined in op. The next operators are available:

If source and target are both of type array and the operator is one of the next ones, the arrays are converted to sets before applying the operator:

New in version 0.1.0.

Changed in version 0.4.0: Convert to sets before applying operators if both arguments are arrays.

shlex_split(cmd_str: str) → list: Split a string using the Python’s built-in shlex.split() function.

New in version 0.4.0.

shlex_join(cmd_list: list) → str: Join a list of strings using the Python’s built-in shlex.join() function.

New in version 0.4.0.

JMESPathsMatch

Compares a set of JMESPath expressions against results.

Object-serializes each file in the files property of the rule and executes each expression given in the first item of the tuples passed as value. If a result don’t match, report an error.

Example

The .editorconfig file must have the next content:

root = true

[*]
end_of_line = lf
charset = utf-8
indent_style = space
trim_trailing_whitespace = true

{
  rules: [
    {
      files: [".editorconfig"],
      JMESPathsMatch: [
        ['"".root', true],
        ['"*".end_of_line', "lf"],
        ['"*".indent_style', "space"],
        ['"*".charset', "utf-8"],
        ['"*".trim_trailing_whitespace', true],
      ],
    }
  ]
}

New in version 0.1.0.

crossJMESPathsMatch

JMESPaths matching between multiple files.

It accepts an array of arrays. Each one of these arrays must have the syntax:

[
  "filesJMESPathExpression",  // expression to query each file in `files` property of the rule
  ["otherFile.ext", "JMESPathExpression"]...,  // optionally other files
  "finalJMESPathExpression",  // an array with results of previous expressions as input
  expectedValue,  // value to compare with the result of final JMESPath expression
]

The executed steps are:

For each object-serialized file in files property of the rule.
Execute "filesJMESPathExpression" and append the result to a temporal array.
For each pair of ["otherFile.ext", "JMESPathExpression"], execute "JMESPathExpression" against the object-serialized version of "otherFile.ext" and append each result to the temporal array.
Execute "finalJMESPathExpression" against the temporal array.
Compare the final result with expectedValue and raise error if not match.

Tip

Other file paths can be URLs if you want to match against online sources.

Example

The release field of a Sphinx configuration defined in a file docs/conf.py must be the same that the version of the project metadata defined in th file pyproject.toml, field tool.poetry.version:

{
  rules: [
    {
      files: ["pyproject.toml"],
      crossJMESPathsMatch: [
        [
          "tool.poetry.metadata",
          ["docs/conf.py", "release"],
          "op([0], '==', [1])",
          true,
        ],
      ],
      hint: "Versions of documentation and metadata must be the same"
    }
  ]
}

Note that you can pass whatever number of other files, even 0 and just apply files and final expressions to each file in files property of the rule. For example, the next configuration would not raise errors:

{
  rules: [
    {
      files: ["foo.json"],
      crossJMESPathsMatch: [
        ["bar", "[0].baz", 7],
      ]
    }
  ]
}

{"bar": {"baz": 7}}

New in version 0.4.0.

ifJMESPathsMatch

Compares a set of JMESPath expressions against results.

JSON-serializes each file in the ifJMESPathsMatch property of the rule and executes each expression given in the first item of the tuples passed as value for each file. If a result don’t match, skips the rule.

Example

If inline-quotes config of flake8 is defined to use double quotes, Black must be configured as the formatting tool in pyproject.toml:

{
  rules: [
    {
      files: ["pyproject.toml"],
      ifJMESPathsMatch: {
        "pyproject.toml": [
           ["tool.flakeheaven.inline_quotes", "double"],
         ],
      },
      JMESPathsMatch: [
        ["contains(keys(@), 'tool')", true],
        ["contains(keys(tool), 'black')", true],
      }
    }
  ]
}

New in version 0.1.0.