DOCSEARCHbyAlgolia
Submit Docs

lintnet

website·Indexed 30 days ago

https://lintnet.github.io/

A general purpose command-line linter written in Go that uses Jsonnet to define lint rules. It supports various data formats, including YAML, and allows for parameterized rules, custom output formats, and the sharing of lint rule modules.

Tokens
7.1K
Snippets
49
Records
67
Agent score
75%

What's inside lintnet

  1. Overview of lintnet Policy as Code linter

    lintnet is a general-purpose command-line linter that implements Policy as Code. Unlike traditional linters, lintnet does not provide built-in rules; instead, it executes user-defined lint rules written in Jsonnet. It is compatible with Terraform, Kubernetes, GitHub Actions, and other configuration files. It leverages go-jsonnet's native functions to extend the capabilities of the Jsonnet configuration language.

  2. Overview of lintnet general purpose linter

    lintnet is a command-line tool used for linting any kind of file. Unlike many linters, it does not come with built-in rules; instead, users define their own lint rules freely. It supports multiple data formats including JSON, YAML, TOML, and HCL.

  3. Diagnose environment with lintnet info

    The lintnet info command outputs diagnostic information about the current lintnet environment, including version, configuration file path, root directories, and environment variables. This is primarily used for troubleshooting and sharing environment details in GitHub Issues.
    # Get full environment info
lintnet info

# Mask the current user name for privacy
lintnet info -mask-user

# Show only the root directory where modules are installed
lintnet info -module-root-dir

  4. Perform cross-file linting using combined data

    By default, lintnet lints each data file independently. To lint across multiple files (e.g., ensuring unique names across all GitHub Actions workflow files), name your lint file with the suffix _combine.jsonnet.

    When using this naming convention, the top-level arguments for the lint rule change: instead of using param.data (which represents a single file), use param.combined_data, which is an array containing the data from all processed files.

  5. Cache lintnet modules in GitHub Actions

    To optimize CI performance, you can cache the module root directory. Use lintnet info -module-root-dir to dynamically determine the path for the cache action.
    - run: echo "module_root_dir=$(lintnet info -module-root-dir)" >> "$GITHUB_OUTPUT"
  id: lintnet

- uses: actions/cache@v6.1.0
  with:
    path: |
      ${{steps.lintnet.outputs.module_root_dir}}
    key: ${{ hashFiles('lintnet.jsonnet') }}

- run: lintnet lint
  env:
    GITHUB_TOKEN: ${{github.token}}

  6. Test Jsonnet behavior using the Web Editor or CLI

    When writing lintnet rules, you can verify Jsonnet behavior using two primary methods: the official web editor for instant testing or the Jsonnet CLI for local execution. Because lintnet uses the Go implementation of Jsonnet, it is recommended to use go-jsonnet for local testing to ensure consistency.
    # Install go-jsonnet via Homebrew
brew install go-jsonnet

# Install go-jsonnet via aqua
aqua g -i google/go-jsonnet

# Evaluate a Jsonnet file
jsonnet hello.jsonnet

  7. Share and distribute lintnet rules via Modules

    lintnet supports the sharing of lint rules through Modules. This allows developers to utilize third-party rules, reuse internal rules across multiple projects, and distribute rules as either open-source software (OSS) or in-house libraries.

  8. Filter lint and data files using command line arguments

    Lintnet allows you to filter which lint files and data files are processed by providing specific command line arguments during execution. For concrete implementation details and usage patterns, refer to the official filter-files example repository.
    # Refer to the examples repository for specific filtering flags
# https://github.com/lintnet/examples/tree/main/filter-files

  9. Manage lintnet error levels and output visibility

    lintnet uses two distinct error level settings to determine the outcome of a lint run and the visibility of results:

    1. Error Level: Determines the threshold for command failure. If all detected errors have a level lower than the lint command's error level, the command succeeds. The default is error.
    2. Shown Error Level: Determines which errors are printed to the output. If a lint error's level is lower than the shown error level, it is excluded from the output. The default is info.

    Supported levels (in increasing order of severity):

    • debug (1)
    • info (2)
    • warn (3)
    • error (4)

    Note: If the lint command's error level is set to a value lower than the current shown error level (e.g., setting error level to debug), the shown error level will automatically be lowered to match it.

  10. Handle multiple documents in YAML files

    lintnet parses YAML files as a sequence of documents, regardless of whether the file contains one or multiple documents (separated by ---). When writing lint rules, you must either iterate through all documents or access a specific document by its index using param.data.value.
    # Example YAML with multiple documents
---
name: foo
---
name: bar

    In lint rules:

    To iterate through all documents:

    for doc in param.data.value

    To get the first document:

    param.data.value[0]

  11. Define the structure of a lintnet test file

    To test a lint file named x.jsonnet, create a test file named x_test.jsonnet in the same directory. A test file must be a function that returns a list of test case objects. Each test case consists of test data and an expected result.
    function(param) [
  {
    name: 'Test case name',
    param: {
      config: {},
    },
    result: [
      // expected return value of the lint file
    ],
  }
]

  12. Install lintnet

    lintnet is a single binary written in Go. It can be installed into your $PATH using several different methods depending on your preferred package manager or environment.
    # Using Homebrew
brew install lintnet/lintnet/lintnet

# Using Scoop
scoop bucket add lintnet https://github.com/lintnet/scoop-bucket
scoop install lintnet

# Using aqua
aqua g -i lintnet/lintnet

# Using Go
go install github.com/lintnet/lintnet/cmd/lintnet@latest