openvox-lint

A style-guide linter for OpenVox and Puppet manifests.

openvox-lint checks your .pp manifest files against the OpenVox Language Style Guide (and Puppet equivalent) and catches common errors, deprecated patterns, legacy facts, strict-mode violations, and Puppet 8+ / OpenVox 8.x language issues.

Fully compatible with:

• OpenVox 8.x (the community-maintained open-source fork of Puppet)
• Puppet 8.x
• Legacy Puppet 7.x manifests (with deprecation warnings)

• Prerequisites
• Installation
• Quick Start
• Usage
• Enabling and Disabling Checks
• Built-in Checks (37)
• Configuration
• Output Formats
• Integration
• Writing Custom Checks
• Updating
• Uninstalling
• Development
• Contributors
• License

• macOS (Apple Silicon and Intel)
• Linux (x86_64, aarch64)
• Windows (via Ruby for Windows)

gem install openvox-lint

git clone https://github.com/cvquesty/openvox-lint.git
cd openvox-lint
gem build openvox-lint.gemspec
gem install openvox-lint-*.gem

Add to your Gemfile:

gem 'openvox-lint'

Then run:

bundle install

# Lint a single file
openvox-lint manifests/init.pp

# Lint all .pp files in a directory tree
openvox-lint manifests/

# Lint current directory
openvox-lint .

# List all available checks
openvox-lint --list-checks

# JSON output for CI
openvox-lint -f json manifests/

Usage: openvox-lint [options] [file|directory ...]

Options:
    --version                    Display version
    -f, --format FORMAT          Output format: text, json, csv, github, codeclimate
    --log-format FORMAT          Custom log format string
    --fix                        Automatically fix problems where possible
    --no-fix                     Do not automatically fix problems (overrides --fix)
    --fail-on-warnings           Exit with error code on warnings
    --no-filename                Suppress filename in output
    --no-column                  Suppress column number in output
    --relative                   Display file paths relative to the current working directory
    --only-checks CHECKS         Comma-separated list of checks to run
    --ignore-paths PATHS         Comma-separated list of glob patterns to ignore
    --list-checks                List all available checks
    -c, --config FILE            Path to configuration file
    --no-<check_name>-check      Disable a specific check

# Disable specific checks
openvox-lint --no-line_length-check --no-arrow_alignment-check .

# Run only specific checks
openvox-lint --only-checks legacy_facts,hiera3_function,top_scope_facts .

# Custom log format (compatible with puppet-lint)
openvox-lint --log-format '%{path}:%{line}:%{column}:%{KIND}:%{check}:%{message}' .

# GitHub Actions annotations
openvox-lint -f github manifests/

# Fail CI on warnings too
openvox-lint --fail-on-warnings manifests/

--fix automatically corrects problems for the checks that implement fix logic. Fixes are applied in-place and are safe for the supported cases. --fix must be passed on the command line; an RC file cannot enable it. --no-fix disables fix mode. Writes are refused when the target path is a symbolic link.

Currently supported checks:

• trailing_whitespace — removes trailing spaces/tabs
• hard_tabs — converts tabs to two spaces
• quoted_booleans — changes 'true' / 'false' (strings) to unquoted booleans
• double_quoted_strings — converts unnecessary double-quoted strings (no interpolation or escapes) to single quotes
• single_quote_string_with_variables — converts single-quoted strings containing $variables to double quotes so interpolation works

Example:

openvox-lint --fix manifests/
# or
openvox-lint --fix .

After running, re-lint to confirm. Complex structural fixes (e.g. arrow alignment) are not yet implemented.

openvox-lint gives you fine-grained control over which checks run. This is useful when your project has intentional style deviations, or when you want to focus on specific issues.

Use --no-<check_name>-check on the command line to turn off a specific check:

# Disable the line length check
openvox-lint --no-line_length-check manifests/

# Disable multiple checks at once
openvox-lint --no-line_length-check --no-arrow_alignment-check --no-strict_indent-check manifests/

Use --only-checks to run only the checks you specify (everything else is skipped):

# Only check for legacy facts and deprecated Hiera 3 functions
openvox-lint --only-checks legacy_facts,hiera3_function,top_scope_facts manifests/

# Only check for errors (skip all warnings)
openvox-lint --only-checks hiera3_function,import_statement,duplicate_params manifests/

Instead of passing flags every time, create a .openvox-lint.rc file in your project root:

# .openvox-lint.rc
# Each line is a command-line argument

# Disable checks that don't apply to our project
--no-line_length-check
--no-strict_indent-check
--no-documentation-check

# Ignore vendored code
--ignore-paths vendor/**/*.pp,pkg/**/*.pp

openvox-lint looks for this file automatically in the current directory and in ~/.openvox-lint.rc.

Use inline comments to suppress a check for a specific block of code:

# Suppress a check for the next block
# lint:ignore:line_length
$very_long_variable = 'this line intentionally exceeds the limit because it is a configuration string'
# lint:endignore

# Suppress on a single line
class myclass { # lint:ignore:documentation
  # ...
}

To see every check that openvox-lint can run:

openvox-lint --list-checks

This lists every built-in check name and whether it is currently enabled. Severity and description live in this README and in DOCUMENTATION.md.

openvox-lint ships with 37 built-in checks organized into categories:

Create .openvox-lint.rc in your project root or ~/.openvox-lint.rc. Each line is a flag (with an optional value). Only the following flags are read from the RC file; other CLI options (--fix, --relative, --no-filename, --no-column) must be passed on the command line. An RC file cannot enable --fix — pass --fix on the CLI to enable writes.

# Disable specific checks
--no-line_length-check
--no-strict_indent-check

# Only run specific checks
# --only-checks legacy_facts,hiera3_function

# Fail on warnings in CI
--fail-on-warnings

# Ignore paths
--ignore-paths vendor/**/*.pp,pkg/**/*.pp

# --fix in an RC file is ignored; pass --fix on the CLI to enable writes

# Named format or a custom --log-format string
# --format json
# --log-format %{path}:%{line}:%{KIND}:%{check}:%{message}

Suppress checks on specific lines:

# lint:ignore:line_length
$very_long_variable_name = 'a very long value that exceeds the line length limit because it is a very descriptive configuration string'
# lint:endignore

class foo { # lint:ignore:documentation
}

manifests/init.pp:5:15: WARNING: unquoted_file_mode: unquoted file mode
manifests/init.pp:9:3: ERROR: hiera3_function: deprecated Hiera 3 function 'hiera()' — use Hiera 5 lookup() instead

[
  {
    "path": "manifests/init.pp",
    "line": 5,
    "column": 15,
    "kind": "warning",
    "check": "unquoted_file_mode",
    "message": "unquoted file mode"
  }
]

::warning file=manifests/init.pp,line=5,col=15::unquoted_file_mode: unquoted file mode

path,line,column,kind,check,message
manifests/init.pp,5,15,warning,unquoted_file_mode,"unquoted file mode"

Standard Code Climate JSON format for quality dashboards.

openvox-lint --log-format '%{path}:%{line}:%{column}:%{KIND}:%{check}:%{message}' .

Available placeholders: %{path}, %{line}, %{column}, %{KIND}, %{kind}, %{check}, %{message}

openvox-lint is the default backend for the vim-openvox Vim plugin. Set in .vimrc:

let g:openvox_lint_command = 'openvox-lint'

name: Lint
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.2'
      - run: gem install openvox-lint
      - run: openvox-lint --fail-on-warnings -f github manifests/

require 'openvox-lint'

task :lint do
  linter = OpenvoxLint::Linter.new
  linter.run('manifests/')
  OpenvoxLint::Report.new(OpenvoxLint.configuration).format(linter.problems)
  exit linter.exit_code
end

#!/bin/bash
# .git/hooks/pre-commit
files=$(git diff --cached --name-only --diff-filter=ACM | grep '\.pp$')
[ -z "$files" ] && exit 0
openvox-lint --fail-on-warnings $files

openvox-lint auto-loads only the built-in files shipped in this gem (lib/openvox-lint/plugins/checks/*.rb). There is no --load FILE flag and no RubyGems plugin discovery. A third-party check is picked up only when something in the same Ruby process requires (or loads) the file after openvox-lint itself.

Create a Ruby file with a check plugin:

# my_custom_check.rb  (any path you control)
OpenvoxLint.new_check(:my_custom_check) do
  def check
    tokens.each do |tok|
      if tok.type == :NAME && tok.value == 'something_bad'
        notify :warning,
          message: 'found something bad',
          line: tok.line,
          column: tok.column
      end
    end
  end
end

Load it explicitly before you run the linter:

require 'openvox-lint'
require_relative 'my_custom_check'

linter = OpenvoxLint::Linter.new
linter.run('manifests/')

Duplicate new_check names always warn on stderr and overwrite the previous registration. Putting a file under lib/openvox-lint/plugins/checks/ in your gem does not make openvox-lint load it.

To add a check to this repository, place it in lib/openvox-lint/plugins/checks/ so the built-in auto-loader picks it up. See DOCUMENTATION.md and docs/ARCHITECTURE_REVIEW.md.

# Update to the latest version
gem update openvox-lint

# Check the installed version
openvox-lint --version

Update the version constraint in your Gemfile if needed, then:

bundle update openvox-lint

cd openvox-lint
git pull origin development
gem build openvox-lint.gemspec
gem install openvox-lint-*.gem

gem uninstall openvox-lint

If you have multiple versions installed, it will ask which one to remove. To remove all versions:

gem uninstall openvox-lint --all

These are optional — openvox-lint does not leave system-wide files, but you may have created project or user configuration:

# Remove per-user config (if you created one)
rm -f ~/.openvox-lint.rc

# Remove per-project config (in each project that has one)
rm -f /path/to/project/.openvox-lint.rc

Remove the gem 'openvox-lint' line from your Gemfile, then:

bundle install

git clone https://github.com/cvquesty/openvox-lint.git
cd openvox-lint
bundle install
bundle exec rake spec

openvox-lint/
├── bin/
│   └── openvox-lint              # CLI executable
├── lib/
│   ├── openvox-lint.rb           # Main entry point
│   └── openvox-lint/
│       ├── version.rb            # Version constant
│       ├── configuration.rb      # Configuration management
│       ├── token.rb              # Token data structure
│       ├── lexer.rb              # Puppet/OpenVox lexer/tokenizer
│       ├── check_plugin.rb       # Base class for checks
│       ├── checks.rb             # Check runner/orchestrator
│       ├── report.rb             # Output formatters
│       ├── linter.rb             # File-level orchestrator
│       ├── cli.rb                # Command-line interface
│       └── plugins/
│           └── checks/           # 37 built-in check plugins
│               ├── trailing_whitespace.rb
│               ├── legacy_facts.rb
│               ├── hiera3_function.rb
│               └── ...
├── spec/                         # RSpec test suite
├── docs/
│   └── ARCHITECTURE_REVIEW.md    # Evidence-based architecture notes
├── openvox-lint.gemspec
├── Gemfile
├── Rakefile
├── LICENSE                       # Apache 2.0
├── README.md
├── CHANGELOG.md
└── DOCUMENTATION.md

Snapshot as of 2026-09-18 against puppetlabs/puppet-lint main README and lib/puppet-lint/plugins.rb. puppet-lint remains under active maintenance; treat this table as dated evidence, not a permanent scorecard.

• RubyGems: rubygems.org/gems/openvox-lint
• GitHub: github.com/cvquesty/openvox-lint
• Issues: github.com/cvquesty/openvox-lint/issues

Apache License, Version 2.0. See LICENSE for details.

Thanks to the following people for their contributions to openvox-lint:

Want to contribute? See CONTRIBUTING.md to get started!

Jerald Sheets (@cvquesty)