Styling

Styles can be defined in any object-serializable file format (see Objects serialization).

We recommend to use YAML or JSON5 because are the most readable, flexible and allows comments, which are really useful writing styles.

Each style must be an object with the following keys:

  • rules (optional if extends is specified)

  • extends (optional if rules is specified)

  • plugins (optional)

At least one rule or extension is required to be a valid style. At least one rule must be collected after styles extensions to be a valid merged style.

rules (object[])

Define the actions to execute against files. It must be an array of objects with at least one object.

files (string[] or object{not{} | not[]})

Unique mandatory field for all rules. It specifies the subject of the rule, that is, the files for which the verbs will be applied.

It must be either an array of strings or an object with an unique key not.

Defining files as an array of strings enforce the existence of these files. If they don’t exist will raise errors, and additionally created in fix mode. The existence of these files and directories is mandatory for execute the rest of actions of the rule.

Examples

{
  rules: [    // Files and directories are created in `fix` mode
    {
      files: [
        "src/",             // Enforce existence of directory
        "pyproject.toml",   // Enforce existence of file
      ]
    }
  ]
}

Enforce files absence

Defining files as an object, it must be an unique key not. The value of not must be either:

  • An object whose keys are the files that must not exist and a message for each value indicating a reason that explain why this file must be absent.

  • An array of strings with the paths to the files that must not exist.

When enforcing absence of files no other actions can be defined in the rule, as this has no sense. The attempt will raise an error validating the style.

File syntax convention

  • Files are defined relative to the root directory of the project, which will be the current working directory if no other is passed in –rootdir CLI argument.

  • Paths terminated with / will be treated as directories using the Unix separator, so you must always use / as file path separators even on Windows systems.

hint (string)

Optional field for all rules. It specifies a hint that will be displayed along the error message when a checking error occurred using the check command. It is specially useful for complex rules which show abstract error messages.

Example

{
  rules: [
    {
      files: [".project-config.toml"],
      hint: "The name of the root directory must match the regex '[a-z0-9-]+$'",
      JMESPathsMatch: [["regex_match('[a-z0-9-]+$', rootdir_name())", true]]
    }
  ]
}

extends (string[])

Array of strings to define other styles from which the current will extend. Extended rules will be executed before the rules of the current style.

Can be defined with the same syntax of styles in configuration, from a local file, a URI resource… Resources fetched can be defined with relative URIs to their fetchers locations. So giving a style located at gh://author/project/path/to/file.json5 we can reference with extends to a resource located at gh://author/project/path/other/file.json5 using extends: ["../other/file.json5"] inside the style gh://author/project/path/to/file.json5.

Example

{
  extends: ["../../base/style.json5", "gh://author/project/path/to/style.json5"],
  rules: [{files: [".project-config.toml"]}]
}

plugins (string[])

Additional third party plugin names on which the rules of the style depend. Built-in plugins don’t need to be defined here, as are loaded by default.

Example

{
  plugins: ["foobar"],
  rules: [
    {
      files: [".project-config.toml"],
      verbFromFooBarPlugin: ["foo", "bar"],
    },
  ],
}

See also

Writing third party plugins