openvox-lint 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fd99ac3fc7637de4bda009ad83ca4b89fbf861316db186f039a8b0405c062cbc
+  data.tar.gz: 4747a1300a899ede28ddaea30a3f5488ae7ee5e294cad55ad1f4721fc55110fa
+SHA512:
+  metadata.gz: e260e0c5a26c9da084e03b835da830981d79fc6af3e32f5fd6644e80da03c4e01d095e4a6badeb581ff8e47467d21802efe6ad3ab1197be0c8046154c6cf37e8
+  data.tar.gz: 6ef7e4f2244b3247012fc5e446505f1d373418e9c226c3c62e003aae26ef3d970f3a84cd63b1d66237a6176a3af85a3a41b9c8368036e2e34f8ff8d220404c9c

data/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to openvox-lint will be documented in this file.
+
+## [1.0.0] - 2025-02-09
+
+### Added
+
+- **Core Engine**
+  - Complete Puppet / OpenVox manifest lexer/tokenizer
+  - Token-based check plugin architecture with `OpenvoxLint.new_check` DSL
+  - Doubly-linked token list for efficient navigation
+  - Support for all Puppet 8 / OpenVox 8.x language constructs
+  - Heredoc, EPP tag, regex, and string interpolation tokenization
+
+- **38 Built-in Checks**
+  - **Whitespace**: `trailing_whitespace`, `hard_tabs`, `line_length`, `space_before_arrow`, `strict_indent`
+  - **Alignment**: `arrow_alignment`
+  - **Strings**: `double_quoted_strings`, `only_variable_string`, `single_quote_string_with_variables`, `variables_not_enclosed`, `quoted_booleans`
+  - **Variables**: `variable_is_lowercase`, `variable_contains_dash`
+  - **Resources**: `ensure_first_param`, `ensure_not_symlink_target`, `file_mode`, `unquoted_file_mode`, `unquoted_resource_title`, `duplicate_params`, `trailing_comma`
+  - **Classes**: `documentation`, `nested_classes_or_defines`, `parameter_order`, `class_inherits_params`, `inherits_across_namespaces`
+  - **Conditionals**: `case_without_default`, `selector_inside_resource`
+  - **References**: `leading_zero`, `resource_reference_without_title_capital`, `relative_classname_inclusion`, `autoloader_layout`
+  - **Comments**: `star_comments`
+  - **URLs**: `puppet_url_without_modules`
+  - **Nodes**: `node_name_unquoted`
+  - **Puppet 8 / OpenVox 8** ⭐: `legacy_facts`, `top_scope_facts`, `hiera3_function`, `import_statement`
+
+- **Output Formats**
+  - Text (default), JSON, CSV, GitHub Actions, Code Climate, Custom
+
+- **CLI Features**
+  - `--fix` auto-fix support
+  - `--fail-on-warnings` for strict CI
+  - `--only-checks` and `--no-<check>-check` granular control
+  - `--list-checks` to enumerate all checks
+  - `.openvox-lint.rc` configuration file support
+  - `# lint:ignore:check_name` inline suppression
+
+- **Integration**
+  - vim-openvox plugin compatibility
+  - GitHub Actions workflow support
+  - Rake task integration
+  - Pre-commit hook support
+
+### Compatibility
+
+- OpenVox 8.x (community fork of Puppet)
+- Puppet 8.x
+- Puppet 7.x (with deprecation warnings)
+- Ruby ≥ 3.1.0

data/DOCUMENTATION.md

@@ -0,0 +1,481 @@
+# openvox-lint Technical Documentation
+
+## Overview
+
+openvox-lint is a Ruby gem that statically analyses OpenVox / Puppet manifest
+(`.pp`) files.  It tokenises each file with a purpose-built lexer, then runs
+a configurable set of check plugins against the token stream.  Problems are
+reported in multiple output formats suitable for humans, CI systems, and IDEs.
+
+This document covers the architecture, every public API, every built-in check,
+the lexer token types, the plugin system, and integration guidance.
+
+---
+
+## Architecture
+
+```
+┌─────────────┐     ┌───────┐     ┌────────┐     ┌──────────┐
+│  CLI / API  │────▶│ Linter │────▶│ Lexer  │────▶│  Tokens  │
+│             │     │        │     │        │     │  (array)  │
+└─────────────┘     └───┬────┘     └────────┘     └────┬─────┘
+                        │                              │
+                        │         ┌────────┐           │
+                        └────────▶│ Checks │◀──────────┘
+                                  │        │
+                                  └───┬────┘
+                                      │
+                                  ┌───▼────┐
+                                  │ Report │
+                                  └────────┘
+```
+
+### Pipeline
+
+1. **CLI** parses command-line arguments and loads configuration
+2. **Linter** expands file arguments, reads each `.pp` file
+3. **Lexer** tokenises the manifest into `Token` objects
+4. **Checks** runs each enabled check plugin against the token stream
+5. **Report** formats and outputs the collected problems
+
+---
+
+## Module: OpenvoxLint
+
+### Constants
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+| `VERSION` | `'1.0.0'` | Gem version |
+
+### Class Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `.configuration` | `Configuration` | Global configuration singleton |
+| `.configure { \|c\| }` | `Configuration` | Yields configuration for block-style setup |
+| `.checks` | `Hash{Symbol => Class}` | Registry of loaded check classes |
+| `.new_check(name, &block)` | `Class` | Register a new check plugin |
+
+### Exceptions
+
+| Exception | Inherits | Usage |
+|-----------|----------|-------|
+| `OpenvoxLint::Error` | `StandardError` | General errors |
+| `OpenvoxLint::NoFix` | `StandardError` | Raised to skip fixing a problem |
+
+---
+
+## Class: OpenvoxLint::Token
+
+Represents a single token from the lexer.
+
+### Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `type` | `Symbol` | Token type (see Token Types below) |
+| `value` | `String` | Raw text value |
+| `line` | `Integer` | 1-based line number |
+| `column` | `Integer` | 1-based column number |
+| `prev_token` | `Token\|nil` | Previous token in doubly-linked list |
+| `next_token` | `Token\|nil` | Next token in doubly-linked list |
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `#formatting?` | `Boolean` | True if whitespace/comment/indent/newline |
+| `#to_s` | `String` | Human-readable representation |
+
+### Token Types
+
+#### Keywords
+
+| Type | Puppet Keyword |
+|------|---------------|
+| `:AND` | `and` |
+| `:APPLICATION` | `application` |
+| `:ATTR` | `attr` |
+| `:CASE` | `case` |
+| `:CLASS` | `class` |
+| `:CONSUMES` | `consumes` |
+| `:DEFAULT` | `default` |
+| `:DEFINE` | `define` |
+| `:ELSE` | `else` |
+| `:ELSIF` | `elsif` |
+| `:FALSE` | `false` |
+| `:FUNCTION` | `function` |
+| `:IF` | `if` |
+| `:IMPORT` | `import` |
+| `:IN` | `in` |
+| `:INHERITS` | `inherits` |
+| `:NODE` | `node` |
+| `:NOT` | `not` |
+| `:OR` | `or` |
+| `:PRIVATE` | `private` |
+| `:PRODUCES` | `produces` |
+| `:SITE` | `site` |
+| `:TRUE` | `true` |
+| `:TYPE` | `type` |
+| `:UNDEF` | `undef` |
+| `:UNLESS` | `unless` |
+
+#### Identifiers & Literals
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `:NAME` | Identifier / bare word | `ensure`, `myclass` |
+| `:CLASSREF` | Capitalised reference | `File`, `String`, `Stdlib::Absolutepath` |
+| `:VARIABLE` | Variable | `$foo`, `$::bar::baz` |
+| `:NUMBER` | Numeric literal | `42`, `0xFF`, `3.14` |
+| `:SSTRING` | Single-quoted string | `'hello'` |
+| `:STRING` | Double-quoted string (no interpolation) | `"hello"` |
+| `:DQSTRING` | Double-quoted string (with interpolation) | `"hello ${name}"` |
+| `:REGEX` | Regular expression | `/^foo/` |
+| `:HEREDOC_OPEN` | Heredoc opening tag | `@("END")` |
+| `:HEREDOC` | Heredoc body | content |
+
+#### Operators
+
+| Type | Operator | Type | Operator |
+|------|----------|------|----------|
+| `:FARROW` | `=>` | `:PARROW` | `+>` |
+| `:ISEQUAL` | `==` | `:NOTEQUAL` | `!=` |
+| `:MATCH` | `=~` | `:NOMATCH` | `!~` |
+| `:LESSEQUAL` | `<=` | `:GREATEREQUAL` | `>=` |
+| `:LESSTHAN` | `<` | `:GREATERTHAN` | `>` |
+| `:LSHIFT` | `<<` | `:RSHIFT` | `>>` |
+| `:IN_EDGE` | `->` | `:OUT_EDGE` | `<-` |
+| `:IN_EDGE_SUB` | `~>` | `:OUT_EDGE_SUB` | `<~` |
+| `:APPENDS` | `+=` | `:EQUALS` | `=` |
+| `:LCOLLECT` | `<\|` | `:RCOLLECT` | `\|>` |
+| `:LLCOLLECT` | `<<\|` | `:RRCOLLECT` | `\|>>` |
+
+#### Punctuation
+
+| Type | Character | Type | Character |
+|------|-----------|------|-----------|
+| `:LBRACE` | `{` | `:RBRACE` | `}` |
+| `:LPAREN` | `(` | `:RPAREN` | `)` |
+| `:LBRACK` | `[` | `:RBRACK` | `]` |
+| `:COMMA` | `,` | `:SEMIC` | `;` |
+| `:DOT` | `.` | `:COLON` | `:` |
+| `:PIPE` | `\|` | `:AT` | `@` |
+| `:QMARK` | `?` | `:BACKSLASH` | `\\` |
+| `:PLUS` | `+` | `:MINUS` | `-` |
+| `:TIMES` | `*` | `:MODULO` | `%` |
+| `:DIV` | `/` | `:NOT` | `!` |
+
+#### Formatting
+
+| Type | Description |
+|------|-------------|
+| `:WHITESPACE` | Spaces/tabs (not at line start) |
+| `:INDENT` | Spaces/tabs at line start |
+| `:NEWLINE` | Line break |
+| `:COMMENT` | `#` comment |
+| `:MLCOMMENT` | `/* */` comment |
+| `:SLASH_COMMENT` | `//` comment |
+
+---
+
+## Class: OpenvoxLint::Lexer
+
+### Constructor
+
+```ruby
+lexer = OpenvoxLint::Lexer.new(code_string)
+```
+
+### Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `tokens` | `Array<Token>` | All tokens (doubly-linked) |
+| `manifest_lines` | `Array<String>` | Source lines (for line-based checks) |
+
+---
+
+## Class: OpenvoxLint::CheckPlugin
+
+Base class for all checks. Created via `OpenvoxLint.new_check`.
+
+### Subclass Interface
+
+| Method | Required | Description |
+|--------|----------|-------------|
+| `#check` | **Yes** | Main check logic; call `notify` to report |
+| `#fix(problem)` | No | Auto-fix a problem; raise `NoFix` to skip |
+
+### Helper Methods Available in Checks
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `tokens` | `Array<Token>` | Full token stream |
+| `manifest_lines` | `Array<String>` | Source lines |
+| `semantic_tokens` | `Array<Token>` | Non-formatting tokens only |
+| `resource_indexes` | `Array<Hash>` | Resource body locations |
+| `class_indexes` | `Array<Hash>` | Class definition locations |
+| `defined_type_indexes` | `Array<Hash>` | Defined type locations |
+| `node_indexes` | `Array<Hash>` | Node definition locations |
+| `title_tokens` | `Array<Token>` | Resource title tokens |
+| `fullpath` | `String` | Full file path |
+| `filename` | `String` | Base filename |
+| `notify(kind, details)` | — | Report a problem |
+
+### `notify` Parameters
+
+```ruby
+notify :warning,    # or :error
+  message: 'description of problem',
+  line:    42,
+  column:  5
+```
+
+---
+
+## Class: OpenvoxLint::Configuration
+
+### Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `log_format` | `String` | `'text'` | Output format |
+| `with_filename` | `Boolean` | `true` | Show filename in output |
+| `fail_on_warnings` | `Boolean` | `false` | Exit 1 on warnings |
+| `fix` | `Boolean` | `false` | Auto-fix mode |
+| `only_checks` | `Array<Symbol>` | `[]` | Run only these checks |
+| `disabled_checks` | `Array<Symbol>` | `[]` | Skip these checks |
+| `ignore_paths` | `Array<String>` | vendor, pkg, spec | Glob patterns to ignore |
+| `config_file` | `String` | `.openvox-lint.rc` | RC file path |
+| `relative` | `Boolean` | `false` | Use relative paths |
+| `column` | `Boolean` | `true` | Show column numbers |
+| `custom_log_format` | `String\|nil` | `nil` | Custom format string |
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `#load_from_rc(path)` | Load config from an RC file |
+| `#check_enabled?(name)` | Is a check enabled? |
+
+---
+
+## Class: OpenvoxLint::Linter
+
+### Usage
+
+```ruby
+linter = OpenvoxLint::Linter.new
+linter.run('manifests/')
+linter.problems    # => Array of problem hashes
+linter.errors?     # => true/false
+linter.exit_code   # => 0 or 1
+```
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `#run(*paths)` | — | Lint files/directories |
+| `#problems` | `Array<Hash>` | All detected problems |
+| `#file_count` | `Integer` | Number of files checked |
+| `#errors?` | `Boolean` | Any errors found? |
+| `#warnings?` | `Boolean` | Any warnings found? |
+| `#exit_code` | `Integer` | 0=clean, 1=problems |
+
+---
+
+## Class: OpenvoxLint::Report
+
+### Usage
+
+```ruby
+report = OpenvoxLint::Report.new(config)
+report.format(problems)           # to $stdout
+report.format(problems, io: file) # to file
+```
+
+### Supported Formats
+
+| Format | Flag | Description |
+|--------|------|-------------|
+| `text` | `-f text` (default) | `path:line:col: KIND: check: message` |
+| `json` | `-f json` | JSON array |
+| `csv` | `-f csv` | CSV with headers |
+| `github` | `-f github` | GitHub Actions annotations |
+| `codeclimate` | `-f codeclimate` | Code Climate JSON |
+| `custom` | `--log-format` | User-defined format string |
+
+---
+
+## Complete Check Reference
+
+### Puppet 8 / OpenVox 8 Migration Checks
+
+These are the most important checks for users upgrading from Puppet 7 or
+migrating to OpenVox.
+
+#### `legacy_facts` (WARNING)
+
+Legacy (unstructured) top-scope facts are excluded by default in Puppet 8 /
+OpenVox 8.  Variables like `$osfamily`, `$fqdn`, `$ipaddress`, and
+`$operatingsystem` must be replaced with structured facts.
+
+**Bad:**
+```puppet
+if $osfamily == 'RedHat' { }
+```
+
+**Good:**
+```puppet
+if $facts['os']['family'] == 'RedHat' { }
+```
+
+Covers 80+ legacy fact names.
+
+#### `top_scope_facts` (WARNING)
+
+Top-scope fact variables (`$::hostname`) should use the `$facts` hash.
+
+**Bad:**
+```puppet
+$hostname = $::hostname
+```
+
+**Good:**
+```puppet
+$hostname = $facts['networking']['hostname']
+```
+
+#### `hiera3_function` (ERROR)
+
+Hiera 3 functions are removed in Puppet 8. This is an error, not a warning.
+
+**Bad:**
+```puppet
+$val = hiera('mykey')
+$hash = hiera_hash('myhash')
+```
+
+**Good:**
+```puppet
+$val = lookup('mykey')
+$hash = lookup('myhash', Hash, 'hash')
+```
+
+#### `import_statement` (ERROR)
+
+The `import` keyword was removed in Puppet 4.
+
+**Bad:**
+```puppet
+import 'foo'
+```
+
+**Good:**
+Use module autoloading.
+
+---
+
+## Puppet 8 / OpenVox 8 Language Context
+
+openvox-lint is designed with full awareness of the Puppet 8 / OpenVox 8
+language changes:
+
+### Changes from Puppet 7
+
+| Change | Impact | openvox-lint Check |
+|--------|--------|-------------------|
+| Strict mode enabled by default | Undefined vars → errors | (runtime) |
+| Legacy facts excluded | `$osfamily` etc. unavailable | `legacy_facts` |
+| Top-scope facts deprecated | `$::fact` pattern obsolete | `top_scope_facts` |
+| Hiera 3 removed | `hiera()` functions gone | `hiera3_function` |
+| PSON removed | Binary serialization changed | (runtime) |
+| String literals frozen | Immutable strings | (runtime) |
+| Ruby 3.2 required | API changes | (gemspec) |
+| `Deferred` lazy evaluation | Resource ordering matters | (runtime) |
+| `Sensitive` auto-protection | Deferred functions protected | (runtime) |
+
+### OpenVox Compatibility
+
+OpenVox 8.x is a **fully compatible fork** of Puppet 8.x:
+- **Identical language syntax** — no changes to the Puppet DSL
+- **Identical module compatibility** — all Puppet Forge modules work
+- **Different package names** — `openvox-agent` replaces `puppet-agent`
+- **Same configuration paths** — `/etc/puppetlabs/`
+- **Community maintained** by Vox Pupuli
+
+openvox-lint works identically with both OpenVox and Puppet manifests.
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | No errors (warnings allowed unless `--fail-on-warnings`) |
+| `1` | Errors found, or warnings with `--fail-on-warnings` |
+
+---
+
+## Plugin Development
+
+### Creating a Check Plugin
+
+```ruby
+# my_check.rb
+OpenvoxLint.new_check(:my_check) do
+  def check
+    tokens.each do |tok|
+      if tok.type == :NAME && tok.value == 'bad_thing'
+        notify :warning,
+          message: 'found bad_thing',
+          line: tok.line,
+          column: tok.column
+      end
+    end
+  end
+
+  # Optional: auto-fix
+  def fix(problem)
+    # Modify tokens in-place
+    raise OpenvoxLint::NoFix  # if can't fix
+  end
+end
+```
+
+### Distributing as a Gem
+
+```ruby
+# my-openvox-lint-check.gemspec
+Gem::Specification.new do |s|
+  s.name = 'openvox-lint-my_check'
+  s.add_runtime_dependency 'openvox-lint', '~> 1.0'
+end
+```
+
+Place the check file in `lib/openvox-lint/plugins/checks/my_check.rb`.
+
+---
+
+## File Inventory
+
+| File | Lines | Description |
+|------|-------|-------------|
+| `bin/openvox-lint` | 7 | CLI entry point |
+| `lib/openvox-lint.rb` | 47 | Main module, auto-loader |
+| `lib/openvox-lint/version.rb` | 5 | Version constant |
+| `lib/openvox-lint/configuration.rb` | 59 | Configuration management |
+| `lib/openvox-lint/token.rb` | 38 | Token data structure |
+| `lib/openvox-lint/lexer.rb` | 342 | Puppet/OpenVox lexer |
+| `lib/openvox-lint/check_plugin.rb` | 147 | Base check class |
+| `lib/openvox-lint/checks.rb` | 46 | Check runner |
+| `lib/openvox-lint/report.rb` | 86 | Output formatters |
+| `lib/openvox-lint/linter.rb` | 72 | File orchestrator |
+| `lib/openvox-lint/cli.rb` | 87 | CLI parser |
+| `lib/openvox-lint/plugins/checks/*.rb` | 38 files | Check plugins |
+| `spec/spec_helper.rb` | 41 | Test helper |
+| `spec/unit/lexer_spec.rb` | 85 | Lexer tests |
+| `spec/unit/checks_spec.rb` | 142 | Check tests |

data/LICENSE

@@ -0,0 +1,83 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form.
+
+      "Work" shall mean the work of authorship made available under
+      the License.
+
+      "Contribution" shall mean any work of authorship submitted to the
+      Licensor for inclusion in the Work.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor.
+
+   2. Grant of Copyright License.
+      Subject to the terms of this License, each Contributor grants to You
+      a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+      irrevocable copyright license to reproduce, prepare Derivative Works
+      of, publicly display, publicly perform, sublicense, and distribute
+      the Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License.
+      Subject to the terms of this License, each Contributor grants to You
+      a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+      irrevocable patent license to make, have made, use, offer to sell,
+      sell, import, and otherwise transfer the Work.
+
+   4. Redistribution.
+      You may reproduce and distribute copies of the Work or Derivative
+      Works thereof in any medium, provided that You meet the conditions
+      of this License.
+
+   5. Submission of Contributions.
+      Unless You explicitly state otherwise, any Contribution submitted
+      for inclusion in the Work shall be under the terms of this License.
+
+   6. Trademarks.
+      This License does not grant permission to use the trade names,
+      trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty.
+      The Work is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+      CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability.
+      In no event shall any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+      You may choose to offer acceptance of support, warranty, indemnity,
+      or other liability obligations consistent with this License.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 Johnny Sheets
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.