yamllint-js

This project is an unofficial Node.js port of adrienverge/yamllint, (the upstream project) originally created by Adrien Vergé.

The original project is licensed under GPL-3.0, which also applies here.

A linter for YAML files — an unofficial native Node.js port of Python yamllint.

yamllint does not only check for syntax validity, but for weirdnesses like key repetition and cosmetic problems such as lines length, trailing spaces, indentation, etc.

Why

The goal of this project is to enable the use of upstream in Node.js-only environments without requiring Python, by providing a Node.js–native port that aims for 100% compatibility with the original Python implementation.

In addition, several improvements were made during the porting process to enhance the tool itself, not just its integration with Node.js:

1. Fix a new-lines issue (https://github.com/adrienverge/yamllint/issues/475)
2. Multiple configuration files
3. Mitigated a ReDoS vulnerability

Documentation

[!NOTE] This package does not include standalone documentation. Instead, please consult the official yamllint (Python) documentation.

https://yamllint.readthedocs.io/

Overview

Screenshot

Installation

# npm
npm install yamllint-js

# yarn
yarn add yamllint-js

# bun
bun add yamllint-js

or global installation:

npm install -g yamllint-js
yarn global install yamllint-js
bun add -g yamllint-js

Upstream is also packaged for all major operating systems, see installation examples (dnf, apt-get...) in the official yamllint (Python) documentation.

Usage

[!NOTE] yarn or bun can be used as alternatives to npx.

All node_modules directories are ignored.

# Lint one or more files
npx yamllint my_file.yml my_other_file.yaml ...

# Recursively lint all YAML files in a directory
npx yamllint .

# Use a pre-defined lint configuration
npx yamllint -d relaxed file.yaml

# Use a custom lint configuration
npx yamllint -c /path/to/myconfig file-to-lint.yaml

# Output a parsable format (for syntax checking in editors like Vim, emacs...)
npx yamllint -f parsable file.yaml

Read more in the complete official yamllint (Python) documentation!

Configuration

In addition to the upstream configuration format, JavaScript and TypeScript configuration files are also supported:

• Cosmiconfig default search places: package.json ("yamllint" field), .yamllintrc.json, yamllint.config.ts, etc.
• Upstream configuration format: .yamllint, .yamllint.yaml, .yamllint.yml, etc.

Configuration can be easily defined with type hints, like:

/** @type {import("yamllint-js").UserConfig")} */

const config = {/* ... */};

modules.exports = config;

or, with an explicit type:

import { defineConfig, type UserConfig } from "yamllint-js";

const config: UserConfig = {/* ... */};

export default defineConfig(config);

Read more in the Configuration page of the official yamllint (Python) documentation!

Features

Here is a yamllint configuration file example:

extends: default

rules:
  # 80 chars should be enough, but don't fail if a line is longer
  line-length:
    max: 80
    level: warning

  # don't bother me with this rule
  indentation: disable

Within a YAML file, special comments can be used to disable checks for a single line:

This line is waaaaaaaaaay too long  # yamllint disable-line

or for a whole block:

# yamllint disable rule:colons
- Lorem       : ipsum
  dolor       : sit amet,
  consectetur : adipiscing elit
# yamllint enable

Specific files can be ignored (totally or for some rules only) using a .gitignore-style pattern:

# For all rules
ignore: |
  *.dont-lint-me.yaml
  /bin/
  !/bin/*.lint-me-anyway.yaml

rules:
  key-duplicates:
    ignore: |
      generated
      *.template.yaml
  trailing-spaces:
    ignore: |
      *.ignore-trailing-spaces.yaml
      /ascii-art/*

Read more in the complete official yamllint (Python) documentation!

License

GPL version 3