openvox-lint 1.3.2 → 1.3.4

data/docs/ARCHITECTURE_REVIEW.md

@@ -0,0 +1,229 @@
+# Architecture Review — openvox-lint
+
+**Subject:** tip `2facd76` plus this PR's remediations, rebased onto `development` after #6 (Ruby/CI matrix), #7 (fail-closed paths), #9 (release checklist), and #12 (RC/`--fix`/GHA/symlink).
+**Default branch:** `development`
+**Review date:** 2026-09-18 (rebase note same day)
+**Scope:** Architecture-owned findings only. Sibling security/systems work is now on `development` and is not re-litigated here. Remaining sibling-owned drift (`--relative`, issues #3 and #5, fail-closed unknown `-f`) is cited only as context.
+
+Severity scale:
+
+| Level | Meaning |
+|-------|---------|
+| High | Users or integrators will be misled or lose work if they trust the current contract |
+| Medium | Dead API, silent overwrite, or documented behaviour that does not match code |
+| Low | Comment / changelog / marketing overclaim with no runtime effect |
+| Info | Structural observation; no defect |
+
+Each finding lists **evidence** (path + symbol) and a **recommendation**. Items marked **Remediated here** were fixed in this architecture PR.
+
+---
+
+## 1. Lexer / token / check plugin model
+
+openvox-lint is a single-process, token-stream linter with no AST and no runtime gems.
+
+```
+CLI / API  →  Linter  →  Lexer  →  Token[]  →  Checks  →  Report
+                 │                      │
+                 └──── Configuration ───┘
+```
+
+| Stage | Symbol | Role |
+|-------|--------|------|
+| CLI | `OpenvoxLint::CLI#run` in `lib/openvox-lint/cli.rb` | Resets the configuration singleton, parses flags, loads one RC file, constructs `Linter` |
+| Orchestrator | `OpenvoxLint::Linter#lint_file` in `lib/openvox-lint/linter.rb` | `File.read` → `Lexer.new` → `Checks#run` → optional `File.write` of mutated `manifest_lines` |
+| Lexer | `OpenvoxLint::Lexer#tokenise` in `lib/openvox-lint/lexer.rb` | Hand-written scanner; emits `Token` objects and links `prev_token` / `next_token` |
+| Token | `OpenvoxLint::Token` in `lib/openvox-lint/token.rb` | `type`, `value`, `line`, `column`, `formatting?` |
+| Registry | `OpenvoxLint.new_check` / `.checks` in `lib/openvox-lint.rb` | `Class.new(CheckPlugin, &block)` stored in a process-global Hash |
+| Runner | `OpenvoxLint::Checks#run` in `lib/openvox-lint/checks.rb` | Instantiates each enabled check, collects problems, optionally calls `#fix_problems` |
+| Plugin base | `OpenvoxLint::CheckPlugin` in `lib/openvox-lint/check_plugin.rb` | `#check`, `#fix`, `notify`, `semantic_tokens`, `resource_indexes`, `class_indexes`, `defined_type_indexes`, `node_indexes`, `title_tokens` |
+| Report | `OpenvoxLint::Report#format` in `lib/openvox-lint/report.rb` | text / json / csv / github / codeclimate / custom |
+
+**Built-in load boundary.** After the module is defined, `lib/openvox-lint.rb` does:
+
+```ruby
+Dir[File.join(__dir__, 'openvox-lint', 'plugins', 'checks', '*.rb')].sort.each do |f|
+  require f
+end
+```
+
+That glob is this gem's `__dir__` only. There is no second pass over `$LOAD_PATH`, `Gem::Specification`, or a CLI `--load` path.
+
+**Fix model.** `CheckPlugin#fix` defaults to `raise OpenvoxLint::NoFix`. Five plugins override it and mutate `@manifest_lines` (chomped copies from the lexer): `trailing_whitespace`, `hard_tabs`, `quoted_booleans`, `double_quoted_strings`, `single_quote_string_with_variables`. `Linter#lint_file` then joins those lines and writes the file. This is intentionally lighter than puppet-lint's token-rewriting `PuppetLint::Data` singleton (`UPDATE_SUMMARY.md`).
+
+### F1. Lexer comment claimed EPP / dedicated type tokens — **Low** — **Remediated here**
+
+- **Evidence:** `OpenvoxLint::Lexer` class comment in `lib/openvox-lint/lexer.rb` previously said the lexer recognised "heredocs, EPP tags, Deferred/Sensitive types, type aliases". `Lexer#tokenise` has no `<%` / `%>` branch; `<` is `SINGLE_CHAR[:LESSTHAN]`. `Deferred` / `Sensitive` / `Type` become `:NAME` or `:CLASSREF` via `scan_name`. `CHANGELOG.md` `[1.0.0]` repeated "EPP tag … tokenization". `DOCUMENTATION.md` "Supported Constructs" was already honest (no EPP).
+- **Recommendation:** Keep the class comment scoped to `.pp` constructs. Do not add an EPP scanner unless `.epp` becomes a first-class target (needs tag tokens and EPP parameter lists). Sibling issue #5 owns heredoc terminator behaviour.
+
+### F2. Helpers are depth-aware and worth keeping — **Info**
+
+- **Evidence:** `CheckPlugin#compute_resource_indexes` walks `semantic_tokens`, skips `class`/`define`/`node` `NAME {` bodies, and collects `param_tokens` only at brace depth 1. `find_keyword_indexes` and `compute_title_tokens` share the same skip. Regression coverage: `spec/unit/checks_spec.rb` `:unquoted_resource_title`.
+- **Recommendation:** Keep this lighter helper model. Do not port `PuppetLint::Data` unless `#fix` needs token-list rewriting.
+
+---
+
+## 2. Dead APIs
+
+### F3. `respond_to?(:fix_problems)` guard — **Low** — **Remediated here**
+
+- **Evidence:** `Checks#run` in `lib/openvox-lint/checks.rb` called `plugin.fix_problems if @configuration.fix && plugin.respond_to?(:fix_problems)`. `CheckPlugin#fix_problems` is defined on the base class (`lib/openvox-lint/check_plugin.rb`). Every registered check is `Class.new(CheckPlugin, &block)`. The guard never skipped.
+- **Recommendation:** Call `#fix_problems` whenever `configuration.fix` is true. `#fix` still raises `NoFix` for unimplemented cases.
+
+### F4. `formatting?` walk inside `compute_resource_indexes` — **Low** — **Remediated here**
+
+- **Evidence:** `compute_resource_indexes` assigned `sem = semantic_tokens`, and `semantic_tokens` is `tokens.reject(&:formatting?)`. The backward walk then did `break unless t.formatting?`, which is always false on `sem`. The loop could only inspect `sem[i - 1]`. The same dead pattern was already removed from `duplicate_params` / `parameter_order` (`CHANGELOG.md` `[1.0.8]`).
+- **Recommendation:** Test the previous semantic token only. Do not remove `Token#formatting?` itself — `Checks#inline_ignore?` and several checks (`documentation`, `leading_zero`, `file_mode`, …) still walk the raw `tokens` stream.
+
+### F5. Duplicate `new_check` warning hidden behind `OPENVOX_LINT_DEBUG` — **Medium** — **Remediated here**
+
+- **Evidence:** `OpenvoxLint.new_check` in `lib/openvox-lint.rb` overwrote `checks[name]` and printed a warning only when `ENV['OPENVOX_LINT_DEBUG']` was set. `CHANGELOG.md` `[1.0.8]` documented that debug gate. A custom file that reused `:trailing_whitespace` would silently replace the built-in check.
+- **Recommendation:** Always warn on stderr. Keep overwrite (failing would break the spec helper, which `load`s check files into an already-populated registry). A future `--fail-on-duplicate-check` flag is optional.
+
+### F6. `--relative` / `Configuration#relative` is stored and never read — **Medium** — **Deferred (systems sibling)**
+
+- **Evidence:** `CLI#parse_options` sets `@config.relative = true` (`lib/openvox-lint/cli.rb`). `Configuration::DEFAULTS` and `attr_accessor :relative` exist (`lib/openvox-lint/configuration.rb`). `Report#format_text` / `#format_github` / `#serialise` emit `p[:path]` as the `fullpath` passed into `Checks` (`lib/openvox-lint/linter.rb`). No reader of `@config.relative`. Documented in README usage, DOCUMENTATION configuration table.
+- **Recommendation:** Sibling owns implement-or-remove. Do not change path logic here.
+
+---
+
+## 3. puppet-lint comparison honesty
+
+README and DOCUMENTATION tables previously described puppet-lint 5.x as if it were a frozen, plugin-dependent archive. puppet-lint `main` (fetched 2026-09-18) is maintained.
+
+| Previous claim | Evidence it is stale | Remediation |
+|----------------|----------------------|-------------|
+| GitHub Actions output: **No** | puppet-lint README: `--sarif`, [puppet-lint-action](https://github.com/marketplace/actions/puppet-lint-action); MegaLinter help text lists `--sarif`. Env-based `::` annotations exist in the ecosystem (voxpupuli/onceover-codequality#59). | Table now says puppet-lint has SARIF / action / env annotations; openvox-lint has `-f github`. |
+| Code Climate output: **No** | puppet-lint README: `--codeclimate-report-file` and `CODECLIMATE_REPORT_FILE`. | Table now credits both. |
+| Legacy / top-scope facts: **Via plugin** | `lib/puppet-lint/plugins/legacy_facts/legacy_facts.rb` and `top_scope_facts/` ship **in** puppet-lint; README documents YAML legacy-fact checks. | Table now says built-in on both sides. |
+| Built-in checks: **~25** | Core set has grown; count is no longer a stable differentiator. | Table describes the core set plus fact checks instead of a guessed number. |
+| Plugin system: **Yes (compatible)** | puppet-lint has `--load`, `--load-from-puppet`, and `PuppetLint::Plugins.load_from_gems` (`lib/puppet-lint/plugins.rb` walks other gems' `lib/puppet-lint/plugins/**/*.rb`). openvox-lint has none of those. The `new_check` / `notify` names look similar; loading and `#fix` do not. | Tables now say require-your-file only / not drop-in compatible. |
+| `--fix`: unqualified **Yes** | puppet-lint rewrites tokens for many core checks. openvox-lint has five line-based `#fix` methods (grep `def fix` under `lib/openvox-lint/plugins/checks/`). | Tables list the five names. |
+
+Still-valid differentiators (with current evidence):
+
+- **Hiera 3 functions** and **`import`** as built-in errors — not in puppet-lint's published core check list.
+- **OpenVox** style-guide targeting and `vim-openvox` as the default backend.
+- **Native CSV** (`Report#format_csv`) — puppet-lint help lists json/sarif/codeclimate/log-format, not CSV.
+- **Ruby floor** as declared here (`>= 2.6.0` in `openvox-lint.gemspec`). CI matrices `2.6` and `3.1`–`3.3`. Ruby 2.5 is no longer claimed.
+
+### F7. Comparison tables overclaimed vs current puppet-lint — **Medium** — **Remediated here**
+
+- **Recommendation:** Keep the tables dated. Re-check puppet-lint `main` when cutting a release that touches marketing rows. Do not claim "drop-in replacement" in the gemspec without a loading story (the gemspec still says "Drop-in replacement for the archived puppet-lint"; puppet-lint is not archived). Softening that sentence further is optional follow-up.
+
+---
+
+## 4. Design drift vs README / DOCUMENTATION
+
+### F8. Custom-plugin docs promised gem auto-discovery — **High** — **Remediated here**
+
+- **Evidence:** README "Writing Custom Checks" said "Place in `lib/openvox-lint/plugins/checks/` and it will be auto-loaded." DOCUMENTATION "Distributing as a Gem" said the same for a third-party gem. The only loader is the `__dir__` glob in `lib/openvox-lint.rb`. `CLI#parse_options` has no `--load`. Contrast puppet-lint `PuppetLint::Plugins.load_from_gems`.
+- **Recommendation (chosen):** Honest docs. A minimal `--load FILE` plus optional `Gem::Specification` walk is small but expands the CLI/security surface (path traversal, load-time code exec) and would collide with sibling CLI work. Revisit only with an explicit product request.
+
+### F9. Check count and `--list-checks` copy — **Low** — **Remediated here** (count + list-checks)
+
+- **Evidence:** README project tree said "38 built-in check plugins" while 37 files exist under `lib/openvox-lint/plugins/checks/` (`relative_classname_inclusion` removed in 1.1.0). README "Listing All Available Checks" claimed `--list-checks` prints severity and description; `CLI#list_checks` prints `✓`/`✗` and the name only. DOCUMENTATION header said "5+ checks" for `--fix`; five `#fix` methods exist.
+- **Recommendation:** Keep the badge, tree, and `--fix` counts generated from the same inventory (37 files, 5 fixes). `--list-checks` copy now matches the CLI.
+
+### F10. Documented `--relative`, unused — **Medium** — **Deferred (systems sibling)**
+
+See F6. README usage and DOCUMENTATION `Configuration` table still describe the flag because the sibling may implement it.
+
+### F11. Source-update docs pointed at `main` — **Low** — **Remediated here**
+
+- **Evidence:** README "Updating / From Source" used `git pull origin main`. Default branch is `development`.
+- **Recommendation:** Pull `development`.
+
+---
+
+## 5. Check extensibility
+
+The in-tree DSL is adequate for contributors:
+
+1. Add `lib/openvox-lint/plugins/checks/<name>.rb` calling `OpenvoxLint.new_check(:name)`.
+2. Implement `#check` (required) and optionally `#fix`.
+3. Use `notify :warning|:error, message:, line:, column:`.
+4. Use helpers on `CheckPlugin` rather than re-scanning braces.
+
+The **out-of-tree** story was the gap (F8). After this PR:
+
+- Documented contract: `require 'openvox-lint'` then `require` your file.
+- Duplicate names always warn (F5).
+- A gem can wrap that require in its own entry point; openvox-lint will not search for it.
+
+Remaining extensibility limits (not changed here):
+
+| Limit | Evidence | Notes |
+|-------|----------|-------|
+| No `--load` | `CLI#parse_options` | Preferred honest docs over a new flag |
+| No gem discovery | `lib/openvox-lint.rb` loader | Avoids loading every gem's `lib/openvox-lint/plugins/**` |
+| `#fix` is line-based | five plugins mutate `@manifest_lines` | Structural fixes (e.g. `arrow_alignment`) stay future work |
+| Registry is process-global | `OpenvoxLint.checks` | Spec helper must `instance_variable_set(:@checks, nil)` then `load` |
+| No check metadata | `CLI#list_checks` | Name + enabled only; severity lives in docs |
+
+---
+
+## 6. Versioning / release notes
+
+### F12. Semver process is documented; some historical notes overclaim — **Low** — **Partially remediated**
+
+- **Evidence:** `CONTRIBUTING.md` "Releasing" requires bumping `OpenvoxLint::VERSION` (`lib/openvox-lint/version.rb`, currently `1.3.3`), `CHANGELOG.md`, and check counts. `[1.3.0]` says "All references now 1.3.1" (version-skid from the 1.3.0→1.3.1 republish; `UPDATE_SUMMARY.md` explains it). `[1.0.0]` claimed EPP tokenization (corrected in this PR). `[1.0.8]` documented the debug-gated duplicate warning (superseded in 1.3.3).
+- **Recommendation:** Add an `[Unreleased]` section for architecture work (done). Do not rewrite unrelated historical narrative. Combined with sibling `[Unreleased]` Security notes after rebase onto #9/#12.
+
+### F13. Gemspec `--fix` "many checks" — **Low** — **Remediated here**
+
+- **Evidence:** `openvox-lint.gemspec` `spec.description` said "Includes real --fix support for many checks." Only five plugins define `#fix`.
+- **Recommendation:** Name the five. Leave the "drop-in replacement for the archived puppet-lint" sentence for a later marketing pass (F7).
+
+---
+
+## 7. Dependency boundaries
+
+### F14. Runtime boundary is clean — **Info**
+
+- **Evidence:** `openvox-lint.gemspec` has **no** `add_runtime_dependency`. Runtime requires: `optparse` (`cli.rb`), `json` (`report.rb`), plus core `File` / `Dir` / `Enumerable`. Dev-only: `rake`, `rspec`, `rubocop`. `Gemfile` is `gemspec` only. `Linter` / `Lexer` / `Checks` do not `require` Puppet, OpenVox, or psych/yaml.
+- **Recommendation:** Keep the zero-runtime-gem boundary. A future gem-discovery loader (F8) would make RubyGems a functional dependency of check loading even if not declared — another reason honest docs were preferred.
+
+### F15. Packaged files omitted `docs/` — **Low** — **Remediated here**
+
+- **Evidence:** `spec.files` listed `lib/**/*`, `bin/*`, `LICENSE`, `README.md`, `CHANGELOG.md`, `DOCUMENTATION.md`. Architecture notes would not ship.
+- **Recommendation:** Include `docs/**/*`.
+
+---
+
+## Remediations in this architecture PR
+
+| Item | Change |
+|------|--------|
+| F1 | Narrowed `Lexer` class comment; corrected `[1.0.0]` EPP line |
+| F3 | Dropped `respond_to?(:fix_problems)` |
+| F4 | Replaced formatting walk with previous-semantic-token check |
+| F5 | Duplicate `new_check` names always warn |
+| F7 / F9 / F11 | Dated comparison tables; 38→37; `--list-checks` copy; `git pull origin development` |
+| F8 | Honest README / DOCUMENTATION / CONTRIBUTING plugin docs |
+| F13 / F15 | Gemspec `--fix` wording + `docs/**/*` |
+| Report | This file |
+
+---
+
+## Sibling slices (do not re-implement here)
+
+Landed on `development` before this rebase:
+
+| Slice | PR | Topics now on `development` |
+|-------|-----|-----------------------------|
+| Security | #12 | RC cannot enable `--fix` (CLI `--[no-]fix`); no-follow / symlink `File.write`; `format_github` sanitization; CSV field escaping |
+| Systems | #6 | Ruby 2.5-safe ranges + expanded CI matrix |
+| Systems | #7 | Fail-closed `Linter#expand_files` on missing/empty inputs |
+| Systems | #9 | Release checklist: git tag + gem + GitHub Release |
+
+Still sibling-owned / open (not in this PR):
+
+| Topic | Notes |
+|-------|-------|
+| `--relative` implement-or-remove | F6/F10 — flag still stored, never read |
+| Issue #3 `variable_is_lowercase` | Not in this slice |
+| Issue #5 heredoc lexer raise / junk-after-end-tag | Not in this slice |
+| Fail-closed unknown `-f` | `Report#format` still falls through to text |
+
+Related drift called out above but not owned here: F6/F10 (`--relative`), fail-closed unknown `-f`.

data/lib/openvox-lint/check_plugin.rb

@@ -91,18 +91,16 @@ module OpenvoxLint
     def compute_resource_indexes
       results = []; i = 0; sem = semantic_tokens
       while i < sem.length
-        if sem[i].type == :NAME && i + 1 < sem.length && sem[i + 1].type == :LBRACE
-          # Skip NAME { that belong to class/define/node bodies rather than
-          # actual resources. This prevents inner statements (including other
-          # resources) from being treated as parameters of the class itself.
-          k = i - 1
-          while k >= 0
-            t = sem[k]
-            break if t.type == :CLASS || t.type == :DEFINE || t.type == :NODE
-            break unless t.formatting?
-            k -= 1
-          end
-          if k >= 0 && [:CLASS, :DEFINE, :NODE].include?(sem[k].type)
+        if (sem[i].type == :NAME || sem[i].type == :CLASSREF) &&
+           i + 1 < sem.length && sem[i + 1].type == :LBRACE
+          # Skip NAME/CLASSREF { that belong to class/define/node bodies
+          # rather than actual resources (including resource defaults such
+          # as "File {"). This prevents inner statements from being treated
+          # as parameters of the class itself.
+          # `sem` is already formatting-free, so the previous semantic token
+          # is the only one that can be the class/define/node keyword.
+          prev = i.positive? ? sem[i - 1] : nil
+          if prev && [:CLASS, :DEFINE, :NODE].include?(prev.type)
             i += 1
             next
           end

data/lib/openvox-lint/checks.rb

@@ -23,7 +23,7 @@ module OpenvoxLint
           fullpath: @fullpath, ignore_comments: @ignore_comments,
         )
         @problems.concat(results)
-        plugin.fix_problems if @configuration.fix && plugin.respond_to?(:fix_problems)
+        plugin.fix_problems if @configuration.fix
       end
       @problems.sort_by { |p| [p[:line] || 0, p[:column] || 0] }
     end

data/lib/openvox-lint/cli.rb

@@ -12,14 +12,23 @@ module OpenvoxLint
     def run
       OpenvoxLint.reset_configuration!
       @config = OpenvoxLint.configuration
-      parse_options
+      # Precedence: defaults < user RC < project RC < CLI. Load RC first so
+      # OptionParser overrides it. --config is peeked so an explicit file is
+      # used during that load; --fix from RC is ignored (see Configuration).
+      @explicit_config_file = peek_explicit_config_file
       load_rc_file
+      parse_options
       if @list_checks
         list_checks; return 0
       end
       files = @args.empty? ? ['.'] : @args
       linter = Linter.new(configuration: @config)
-      linter.run(*files)
+      begin
+        linter.run(*files)
+      rescue OpenvoxLint::Error => e
+        $stderr.puts "openvox-lint: #{e.message}"
+        return 1
+      end
       Report.new(@config).format(linter.problems)
       print_summary(linter) unless @config.log_format == 'json'
       linter.exit_code
@@ -32,16 +41,17 @@ module OpenvoxLint
         opts.banner = "Usage: openvox-lint [options] [file|directory ...]"
         opts.separator ''; opts.separator 'Options:'
         opts.on('--version', 'Display version') { puts "openvox-lint #{VERSION}"; exit 0 }
-        opts.on('-f', '--format FORMAT', 'Output format: text json csv github codeclimate') { |f| @config.log_format = f }
+        opts.on('-f', '--format FORMAT', 'Output format: text json csv github codeclimate') { |f| apply_cli_format(f) }
         opts.on('--log-format FORMAT', 'Custom log format string') { |f| @config.custom_log_format = f; @config.log_format = 'custom' }
-        opts.on('--fix', 'Automatically fix problems') { @config.fix = true }
+        opts.on('--[no-]fix', 'Automatically fix problems (CLI only; RC cannot enable)') { |v| @config.fix = v }
         opts.on('--fail-on-warnings', 'Exit 1 on warnings') { @config.fail_on_warnings = true }
         opts.on('--no-filename', 'Suppress filename') { @config.with_filename = false }
         opts.on('--no-column', 'Suppress column') { @config.column = false }
-        opts.on('--relative', 'Relative paths') { @config.relative = true }
+        opts.on('--relative', 'Display paths relative to the current working directory') { @config.relative = true }
         opts.on('--only-checks CHECKS', 'Comma-separated checks') { |c| @config.only_checks = c.split(',').map { |s| s.strip.to_sym } }
         opts.on('--ignore-paths PATHS', 'Comma-separated globs') { |p| @config.ignore_paths = p.split(',').map(&:strip) }
-        opts.on('--list-checks', 'List available checks') { @list_checks = true }
+        opts.on('--list-checks', 'List available checks (name, severity, description)') { @list_checks = true }
+        opts.separator '    --no-<check_name>-check      Disable a check (see --list-checks)'
         opts.on('-c', '--config FILE', 'Config file path') { |f| @explicit_config_file = f }
       end
       remaining = []
@@ -59,26 +69,88 @@ module OpenvoxLint
       @args.replace(remaining)
     end
 
+    def peek_explicit_config_file
+      @args.each_with_index do |arg, idx|
+        if ['-c', '--config'].include?(arg)
+          return @args[idx + 1]
+        elsif arg.start_with?('--config=')
+          return arg.split('=', 2).last
+        end
+      end
+      nil
+    end
+
     def load_rc_file
-      # Priority: explicit --config flag > local .openvox-lint.rc > ~/.openvox-lint.rc
-      # An explicit --config flag must always win.  The default value of
-      # config_file is nil until the user passes -c / --config.
+      # Precedence: defaults < ~/.openvox-lint.rc (user) < .openvox-lint.rc
+      # (project) < CLI. An explicit --config / -c file replaces the RC chain.
       candidates = if @explicit_config_file
                      [@explicit_config_file]
                    else
-                     ['.openvox-lint.rc', File.expand_path('~/.openvox-lint.rc')]
+                     [File.expand_path('~/.openvox-lint.rc'), '.openvox-lint.rc']
                    end
       candidates.each do |path|
         next unless path && File.exist?(path)
-        @config.load_from_rc(path); break
+        @config.load_from_rc(path)
       end
     end
 
+    def apply_cli_format(value)
+      if Configuration::NAMED_FORMATS.include?(value)
+        @config.log_format = value
+        return
+      end
+      $stderr.puts "error: invalid format '#{value}' (valid: #{Configuration::NAMED_FORMATS.join(', ')})"
+      exit 1
+    end
+
+    # CheckPlugin has no severity/description API. Read them from the plugin
+    # source: the kind the check passes to notify, and the file header comment.
     def list_checks
-      puts "Available checks (#{OpenvoxLint.checks.size} total):"; puts ''
-      OpenvoxLint.checks.keys.sort.each do |name|
-        puts "  #{@config.check_enabled?(name) ? '✓' : '✗'}  #{name}"
+      names = OpenvoxLint.checks.keys.sort
+      width = [names.map { |n| n.to_s.length }.max, 8].max
+      puts "Available checks (#{names.size} total):"
+      puts ''
+      names.each do |name|
+        klass = OpenvoxLint.checks[name]
+        mark = @config.check_enabled?(name) ? '✓' : '✗'
+        severity = plugin_severity(klass)
+        description = plugin_description(klass)
+        puts format("  %s  %-#{width}s  %-7s  %s", mark, name, severity, description).rstrip
+      end
+    end
+
+    def plugin_source_file(klass)
+      file, = klass.instance_method(:check).source_location
+      file
+    end
+
+    def plugin_severity(klass)
+      file = plugin_source_file(klass)
+      return 'warning' unless file && File.file?(file)
+      File.foreach(file) do |line|
+        return 'error' if line =~ /notify\s+:error\b/
+        return 'warning' if line =~ /notify\s+:warning\b/
+      end
+      'warning'
+    end
+
+    def plugin_description(klass)
+      file = plugin_source_file(klass)
+      return '' unless file && File.file?(file)
+      lines = []
+      started = false
+      File.foreach(file) do |line|
+        stripped = line.strip
+        next if !started && (stripped.empty? ||
+                             stripped == '# frozen_string_literal: true' ||
+                             stripped.start_with?('require '))
+        break unless stripped.start_with?('#')
+        started = true
+        text = stripped.sub(/\A#\s?/, '')
+        break if text.empty? && !lines.empty?
+        lines << text unless text.empty?
       end
+      lines.join(' ')
     end
 
     def print_summary(linter)

data/lib/openvox-lint/configuration.rb

@@ -3,6 +3,8 @@
 module OpenvoxLint
   # Holds all runtime configuration.
   class Configuration
+    NAMED_FORMATS = %w[text json csv github codeclimate].freeze
+
     DEFAULTS = {
       log_format: 'text', with_filename: true, fail_on_warnings: false,
       fix: false, only_checks: [], disabled_checks: [],
@@ -41,7 +43,10 @@ module OpenvoxLint
 
     def apply_flag(flag, value)
       case flag
-      when '--fix'              then self.fix = true
+      when '--fix'
+        # Destructive --fix must be requested on the CLI. An RC file must
+        # never enable writes on its own (defaults < RC < CLI).
+        $stderr.puts 'openvox-lint: ignoring --fix from RC file (pass --fix on the CLI to enable)'
       when '--no-fix'           then self.fix = false
       when '--fail-on-warnings' then self.fail_on_warnings = true
       when /\A--no-(.+)-check\z/
@@ -49,10 +54,31 @@ module OpenvoxLint
       when '--only-checks'
         self.only_checks = (value || '').split(',').map { |c| c.strip.to_sym }
       when '--log-format'
-        self.log_format = value&.strip || 'text'
+        apply_log_format_value(value)
+      when '--format', '-f'
+        apply_named_format(value)
       when '--ignore-paths'
         self.ignore_paths = (value || '').split(',').map(&:strip)
       end
     end
+
+    # --log-format accepts a named format or a custom placeholder string.
+    def apply_log_format_value(value)
+      value = value&.strip
+      return if value.nil? || value.empty?
+      if NAMED_FORMATS.include?(value)
+        self.log_format = value
+      else
+        self.custom_log_format = value
+        self.log_format = 'custom'
+      end
+    end
+
+    # -f / --format in an RC file accept named formats only (same as CLI -f).
+    def apply_named_format(value)
+      value = value&.strip
+      return unless NAMED_FORMATS.include?(value)
+      self.log_format = value
+    end
   end
 end

data/lib/openvox-lint/lexer.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
 module OpenvoxLint
-  # Tokenises a Puppet / OpenVox manifest string into an Array of Token
-  # objects.  The lexer recognises all Puppet 8 / OpenVox 8.x language
-  # constructs including heredocs, EPP tags, Deferred/Sensitive types,
-  # type aliases, and the full operator set.
+  # Tokenises a Puppet / OpenVox `.pp` manifest string into an Array of
+  # Token objects.  The lexer recognises keywords, operators, heredocs,
+  # regexes, interpolated strings, numbers, and type-reference names
+  # commonly found in Puppet 8 / OpenVox 8.x manifests.  It does not
+  # scan EPP tags (`<%` / `%>`); `.epp` templates are not a first-class
+  # target.  Deferred/Sensitive/type-alias syntax is tokenised as
+  # ordinary names and class references, not dedicated token types.
   class Lexer
     KEYWORDS = {
       'and' => :AND, 'application' => :APPLICATION, 'attr' => :ATTR,
@@ -219,6 +222,7 @@ module OpenvoxLint
     end
 
     def scan_heredoc
+      start_line = @line
       start_col = @column
       tag_match = @code[@pos..].match(/\A@\(("?)(\w+)\1\s*([\/\-|:tsnLru]*)\)/)
       unless tag_match
@@ -227,25 +231,38 @@ module OpenvoxLint
       tag = tag_match[2]; tag_len = tag_match[0].length
       add_token(:HEREDOC_OPEN, @code[@pos, tag_len], @line, start_col)
       @pos += tag_len; @column += tag_len
-      # Skip rest of current line
+      # Skip rest of current line (e.g. a trailing comma after the open tag)
       while @pos < @code.length && @code[@pos] != "\n"
         @pos += 1; @column += 1
       end
+      unless @pos < @code.length && @code[@pos] == "\n"
+        raise OpenvoxLint::Error, "unterminated heredoc starting at line #{start_line}"
+      end
       @pos += 1; @line += 1; @column = 1
-      # Read heredoc body
+      # Read heredoc body. An end tag must be a whole line matching
+      # optional strip prefix + tag + optional surrounding whitespace.
+      # Trailing junk (e.g. `| END,`) is not a terminator; the scan
+      # continues and EOF without a valid end tag is an error.
       heredoc_content = +''
+      terminated = false
+      end_tag_re = /\A[-|]?\s*#{Regexp.escape(tag)}\s*\z/
       until @pos >= @code.length
         line_start = @pos
         while @pos < @code.length && @code[@pos] != "\n"
           @pos += 1; @column += 1
         end
         current_line = @code[line_start...@pos]
-        if current_line.strip =~ /\A[-|]?\s*#{Regexp.escape(tag)}\s*\z/
-          @pos += 1 if @pos < @code.length; @line += 1; @column = 1; break
+        if current_line.strip =~ end_tag_re
+          @pos += 1 if @pos < @code.length; @line += 1; @column = 1
+          terminated = true
+          break
         end
         heredoc_content << current_line << "\n"
         @pos += 1; @line += 1; @column = 1
       end
+      if !terminated
+        raise OpenvoxLint::Error, "unterminated heredoc starting at line #{start_line}"
+      end
       add_token(:HEREDOC, heredoc_content, @line, start_col)
     end
 

data/lib/openvox-lint/linter.rb

@@ -51,7 +51,7 @@ module OpenvoxLint
         begin
           fixed_code = lexer.manifest_lines.join("\n") + "\n"
           if fixed_code != code
-            File.write(filepath, fixed_code)
+            write_fixed_file(filepath, fixed_code)
           end
         rescue StandardError => write_err
           @problems << {
@@ -67,18 +67,69 @@ module OpenvoxLint
       }
     end
 
+    # Single choke point for --fix writes: never follow a symlink (leaf or
+    # any path component) and open with O_NOFOLLOW when the platform provides it.
+    def write_fixed_file(filepath, content)
+      if symlink_in_path?(filepath)
+        @problems << {
+          path: filepath, line: 0, column: 0, kind: :error,
+          check: :fix,
+          message: "Refusing to write fixes: #{filepath} is a symbolic link or has a symlink path component",
+        }
+        return
+      end
+
+      flags = File::WRONLY | File::TRUNC
+      flags |= File::NOFOLLOW if defined?(File::NOFOLLOW)
+      File.open(filepath, flags) { |f| f.write(content) }
+    rescue Errno::ELOOP, Errno::EMLINK
+      @problems << {
+        path: filepath, line: 0, column: 0, kind: :error,
+        check: :fix,
+        message: "Refusing to write fixes: #{filepath} is a symbolic link or has a symlink path component",
+      }
+    end
+
+    def symlink_in_path?(filepath)
+      return true if File.symlink?(filepath)
+
+      # Walk each component so a symlink directory cannot redirect the write.
+      path = File.expand_path(filepath)
+      current = path.start_with?(File::SEPARATOR) ? File::SEPARATOR : nil
+      path.split(File::SEPARATOR).reject(&:empty?).each do |part|
+        current = current.nil? ? part : File.join(current, part)
+        return true if File.symlink?(current)
+      end
+      false
+    end
+
     def expand_files(fileargs)
+      if fileargs.nil? || fileargs.empty?
+        raise OpenvoxLint::Error, 'no files or directories specified'
+      end
+
       files = []
       fileargs.each do |arg|
         if File.directory?(arg)
           files.concat(Dir.glob(File.join(arg, '**', '*.pp')))
-        elsif arg.include?('*')
-          files.concat(Dir.glob(arg))
+        elsif arg.include?('*') || arg.include?('?') || arg.include?('[')
+          matches = Dir.glob(arg)
+          if matches.empty?
+            raise OpenvoxLint::Error, "glob matched no files: #{arg}"
+          end
+          files.concat(matches)
         elsif File.file?(arg)
           files << arg
+        else
+          raise OpenvoxLint::Error, "no such file or directory: #{arg}"
         end
       end
-      files.reject { |f| ignored?(f) }.uniq
+
+      files = files.reject { |f| ignored?(f) }.uniq
+      if files.empty?
+        raise OpenvoxLint::Error, 'no Puppet manifests (.pp) found to lint'
+      end
+      files
     end
 
     def ignored?(filepath)

data/lib/openvox-lint/plugins/checks/arrow_alignment.rb

@@ -41,7 +41,7 @@ OpenvoxLint.new_check(:arrow_alignment) do
   def group_arrows(arrows)
     groups = []
     current = [arrows.first]
-    arrows[1..].each do |arrow|
+    arrows[1..-1].each do |arrow|
       if arrow.line - current.last.line <= 2
         current << arrow
       else

data/lib/openvox-lint/plugins/checks/autoloader_layout.rb

@@ -17,7 +17,7 @@ OpenvoxLint.new_check(:autoloader_layout) do
       expected_path = if parts.length == 1
                         "#{parts[0]}/manifests/init.pp"
                       else
-                        "#{parts[0]}/manifests/#{parts[1..].join('/')}.pp"
+                        "#{parts[0]}/manifests/#{parts[1..-1].join('/')}.pp"
                       end
       next if fullpath.end_with?(expected_path)
       # Also check with just the filename portion

data/lib/openvox-lint/plugins/checks/space_before_arrow.rb

@@ -78,7 +78,7 @@ OpenvoxLint.new_check(:space_before_arrow) do
     groups  = []
     current = [entries.first]
 
-    entries[1..].each do |entry|
+    entries[1..-1].each do |entry|
       if entry[:arrow].line - current.last[:arrow].line <= 2
         current << entry
       else