sas-linter 0.1.0

data/lib/sas_linter/rules/variable_value_out_of_known_range.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+require_relative "../../sas_linter"
+require "sas_lexer"
+require "csv"
+
+class SasLinter
+  module Rules
+    # Flag conditional comparisons against literal values that fall outside a
+    # variable's documented acceptable values, e.g.:
+    #
+    #     if AGE in (0,1,2,99) then ...   # AGE takes 0..2 — `99` is dead
+    #     if SCORE = 99 then ...          # SCORE takes 0..5
+    #     if RANK eq 7 then ...           # RANK takes 0..6
+    #
+    # Catches typos and stale literals where the source compares a variable
+    # against a value the variable can never actually take, so the branch is
+    # unreachable. Only fires inside `if`-conditions (between KW_IF and the
+    # next KW_THEN or SEMI) — assignments to the variable are not flagged.
+    #
+    # Acceptable values are loaded from one or more CSV files with two
+    # configurable columns: a name column and an acceptable-values column.
+    # Recognized value formats:
+    #
+    #     0-5                      → integer range
+    #     1,2,3                    → integer set
+    #     0-4,7,8                  → range plus extras
+    #     0-90 (99)                → range plus parenthesized extras
+    #
+    # Variables whose values column is free text or a date pattern are
+    # silently skipped (no findings, no errors).
+    #
+    # Recognized config options:
+    #     csv_paths:     ["metadata/variables.csv", ...]   # required, at least one
+    #     name_column:   "Variable"                        # default: "Variable"
+    #     values_column: "Acceptable Values"               # default: "Acceptable Values"
+    #     name_match:    case_insensitive | exact          # default: case_insensitive
+    #     autofix:       false                             # this rule has no autofix
+    #
+    # When `csv_paths` is empty the rule is a no-op — useful so projects
+    # without a variable catalog can keep the rule registered without it
+    # firing.
+    class VariableValueOutOfKnownRange < Rule
+      rule_id :variable_value_out_of_known_range
+      description "Comparison literal falls outside a variable's documented " \
+                  "acceptable values — branch is unreachable."
+      severity :warning
+
+      TT = SasLexer::Lexer::TokenType
+
+      DEFAULT_NAME_COLUMN = "Variable"
+      DEFAULT_VALUES_COLUMN = "Acceptable Values"
+      DEFAULT_DELIMITER = ","
+
+      def initialize(csv_paths: [],
+                     name_column: DEFAULT_NAME_COLUMN,
+                     values_column: DEFAULT_VALUES_COLUMN,
+                     name_match: :case_insensitive,
+                     delimiter: DEFAULT_DELIMITER,
+                     autofix: false)
+        super(autofix: autofix)
+        @csv_paths = Array(csv_paths)
+        @name_column = name_column
+        @values_column = values_column
+        @delimiter = delimiter
+        unless %i[case_insensitive exact].include?(name_match)
+          raise ArgumentError, "name_match must be :case_insensitive or :exact (got #{name_match.inspect})"
+        end
+
+        @name_match = name_match
+        @specs = nil
+      end
+
+      def self.from_config(opts = {})
+        opts = opts.transform_keys(&:to_s)
+        new(
+          csv_paths: Array(opts["csv_paths"]).map { |p| File.expand_path(p) },
+          name_column: opts["name_column"] || DEFAULT_NAME_COLUMN,
+          values_column: opts["values_column"] || DEFAULT_VALUES_COLUMN,
+          name_match: (opts["name_match"] || "case_insensitive").to_sym,
+          delimiter: opts["delimiter"] || DEFAULT_DELIMITER,
+          autofix: opts["autofix"] ? true : false
+        )
+      end
+
+      def check(tokens, path:, all_tokens: nil, source: nil) # rubocop:disable Lint/UnusedMethodArgument
+        return [] if specs.empty?
+
+        findings = []
+        in_condition = false
+        i = 0
+
+        while i < tokens.length
+          tok = tokens[i]
+
+          case tok[:type]
+          when TT::KW_IF
+            in_condition = true
+            i += 1
+            next
+          when TT::KW_THEN, TT::SEMI
+            in_condition = false
+            i += 1
+            next
+          end
+
+          if in_condition && tok[:type] == TT::IDENTIFIER
+            op = tokens[i + 1]
+            if op
+              consumed, ident_findings = check_comparison(tokens, i, tok, op, path)
+              findings.concat(ident_findings)
+              if consumed > 0
+                i += consumed
+                next
+              end
+            end
+          end
+
+          i += 1
+        end
+
+        findings
+      end
+
+      private
+
+      # Returns [tokens_consumed, findings]. consumed=0 if no recognized
+      # comparison started here.
+      def check_comparison(tokens, ident_idx, ident, op, path)
+        spec = lookup_spec(ident[:text])
+        return [0, []] unless spec
+
+        case op[:type]
+        when TT::KW_IN
+          lparen = tokens[ident_idx + 2]
+          return [0, []] unless lparen && lparen[:type] == TT::LPAREN
+
+          findings = []
+          k = ident_idx + 3
+          while k < tokens.length
+            t = tokens[k]
+            break unless t
+
+            if t[:type] == TT::RPAREN
+              return [k - ident_idx + 1, findings]
+            elsif t[:type] == TT::COMMA
+              k += 1
+              next
+            end
+
+            lit = literal_value(t)
+            if lit && !value_allowed?(spec, lit[:value])
+              findings << finding(
+                line: t[:start_line],
+                column: t[:start_column] + 1,
+                message: format_message(ident[:text], lit[:display], spec),
+                path: path
+              )
+            end
+            k += 1
+          end
+
+          [k - ident_idx + 1, findings]
+        when TT::KW_EQ, TT::ASSIGN
+          lit_tok = tokens[ident_idx + 2]
+          lit = literal_value(lit_tok)
+          return [0, []] unless lit
+          return [3, []] if value_allowed?(spec, lit[:value])
+
+          [3, [finding(
+            line: lit_tok[:start_line],
+            column: lit_tok[:start_column] + 1,
+            message: format_message(ident[:text], lit[:display], spec),
+            path: path
+          )]]
+        else
+          [0, []]
+        end
+      end
+
+      def lookup_spec(text)
+        key = @name_match == :exact ? text : text.downcase
+        specs[key]
+      end
+
+      def specs
+        @specs ||= load_specs
+      end
+
+      def load_specs
+        map = {}
+        @csv_paths.each do |path|
+          next unless File.file?(path)
+
+          CSV.foreach(path, headers: true, col_sep: @delimiter) do |row|
+            name = row[@name_column]
+            values_text = row[@values_column]
+            next if name.nil? || name.strip.empty?
+            next if values_text.nil? || values_text.strip.empty?
+
+            spec = parse_values(values_text.strip)
+            next unless spec
+
+            key = @name_match == :exact ? name : name.downcase
+            map[key] = spec
+          end
+        end
+        map
+      end
+
+      # Recognized value-string formats. Anything else (free text, date
+      # patterns, alpha ranges) returns nil and the row is skipped.
+      def parse_values(text)
+        case text
+        when /\A(-?\d+)-(-?\d+)\z/
+          { type: :range, in: ($1.to_i)..($2.to_i) }
+        when /\A-?\d+(?:\s*,\s*-?\d+)+\z/
+          { type: :set, in: text.split(/\s*,\s*/).map(&:to_i) }
+        when /\A(\d+)-(\d+)\s+\(([^)]+)\)\z/
+          base = ($1.to_i)..($2.to_i)
+          extras = Regexp.last_match(3).split(/\s*,\s*/).map { |x| Integer(x) rescue nil }.compact
+          { type: :set, in: base.to_a + extras }
+        when /\A(\d+)-(\d+)\s*,\s*(.+)\z/
+          base = ($1.to_i)..($2.to_i)
+          extras = Regexp.last_match(3).split(/\s*,\s*/).map { |x| Integer(x) rescue nil }.compact
+          return nil if extras.empty?
+
+          { type: :set, in: base.to_a + extras }
+        end
+      end
+
+      def value_allowed?(spec, value)
+        allowed = spec[:in]
+        return true if allowed.nil?
+
+        case spec[:type]
+        when :range
+          allowed.cover?(value)
+        when :set
+          allowed.include?(value)
+        else
+          true
+        end
+      end
+
+      def literal_value(tok)
+        return nil unless tok
+
+        case tok[:type]
+        when TT::INTEGER_LITERAL
+          n = begin
+            Integer(tok[:text])
+          rescue StandardError
+            return nil
+          end
+          { value: n, display: tok[:text] }
+        when TT::FLOAT_LITERAL
+          f = begin
+            Float(tok[:text])
+          rescue StandardError
+            return nil
+          end
+          { value: (f == f.to_i ? f.to_i : f), display: tok[:text] }
+        when TT::STRING_LITERAL
+          { value: tok[:text].gsub(/\A['"]|['"]\z/, ""), display: tok[:text] }
+        end
+      end
+
+      def format_message(ident, display, spec)
+        allowed_str =
+          case spec[:type]
+          when :range then spec[:in].to_s
+          when :set then "{#{spec[:in].join(', ')}}"
+          end
+        "value #{display} for #{ident} is outside the documented acceptable " \
+          "values (#{allowed_str}); this branch is unreachable."
+      end
+    end
+  end
+end

data/lib/sas_linter/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class SasLinter
+  VERSION = "0.1.0"
+end

data/lib/sas_linter.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+require "sas_lexer"
+require "set"
+require "yaml"
+
+require_relative "sas_linter/version"
+
+# Configurable lint engine for SAS source files. Walks the token stream
+# produced by `SasLexer::Lexer` and applies a set of pluggable rules.
+#
+# Each rule is a subclass of `SasLinter::Rule` and is auto-registered when
+# its file is required. Use `SasLinter.new(rules: [...])` to constrain the
+# rule set, or `SasLinter.from_config(config_hash)` to honor a YAML config.
+class SasLinter
+  DEFAULT_CONFIG_PATH = "config/lint.yaml"
+
+  Finding = Struct.new(:path, :line, :column, :rule, :message, :severity, keyword_init: true) do
+    def to_s
+      "#{path}:#{line}:#{column}: [#{rule}] #{message}"
+    end
+  end
+
+  class Rule
+    class << self
+      def registry
+        @registry ||= {}
+      end
+
+      def register(klass)
+        id = klass.rule_id
+        raise ArgumentError, "Rule #{klass} did not declare a rule_id" if id.nil?
+
+        registry[id] = klass
+      end
+
+      def all
+        registry.values
+      end
+
+      def fetch(id)
+        registry.fetch(id.to_sym) do
+          raise ArgumentError, "Unknown lint rule: #{id.inspect}. Known: #{registry.keys.join(', ')}"
+        end
+      end
+
+      def inherited(subclass)
+        super
+        # Subclasses self-register once they declare an id via `rule_id :foo`.
+      end
+
+      def rule_id(value = nil)
+        if value
+          @rule_id = value.to_sym
+          Rule.register(self)
+        end
+        @rule_id
+      end
+
+      def description(value = nil)
+        @description = value if value
+        @description
+      end
+
+      def severity(value = nil)
+        @severity = value if value
+        @severity || :warning
+      end
+
+      # Build a rule instance from a config hash. Subclasses with
+      # constructor arguments should override this — the default
+      # forwards `autofix:` (the only generic option) and ignores
+      # the rest.
+      def from_config(opts = {})
+        opts = opts.transform_keys(&:to_s)
+        kwargs = {}
+        kwargs[:autofix] = opts["autofix"] ? true : false if opts.key?("autofix")
+        new(**kwargs)
+      end
+
+      # Whether this rule can rewrite source to fix the findings it
+      # reports. Rules that override `autofix(source)` should also
+      # override this to return true.
+      def supports_autofix?
+        false
+      end
+    end
+
+    # @param autofix [Boolean] when true and the rule supports
+    #   autofixing, the linter will call `#autofix(source)` after
+    #   `#check` and write the result back to disk. The default
+    #   constructor accepts this kwarg so every rule's `from_config`
+    #   can forward it uniformly; rules that don't support autofix
+    #   simply ignore it.
+    def initialize(autofix: false)
+      @autofix = autofix
+    end
+
+    attr_reader :autofix
+    alias_method :autofix?, :autofix
+
+    # Subclasses must implement check.
+    #
+    # @param tokens [Array<Hash>] default-channel tokens (no whitespace, no comments)
+    # @param path [String] file path used in Finding output
+    # @param all_tokens [Array<Hash>, nil] every token from the lexer including
+    #   the comment and whitespace channels — supplied for rules that need to
+    #   inspect comments. Default-channel rules can ignore this.
+    # @param source [String, nil] the raw source text, supplied for rules
+    #   that operate at the byte level (e.g. trailing-whitespace).
+    def check(_tokens, path:, all_tokens: nil, source: nil) # rubocop:disable Lint/UnusedMethodArgument
+      raise NotImplementedError
+    end
+
+    # Override in subclasses that can rewrite source. Return the
+    # modified source string. The base implementation is a no-op so
+    # rules without autofix can still appear in an autofix-on lint
+    # pass without special-casing.
+    def autofix(source) # rubocop:disable Lint/UnusedMethodArgument
+      source
+    end
+
+    protected
+
+    def finding(line:, column:, message:, path:)
+      Finding.new(
+        path: path,
+        line: line,
+        column: column,
+        rule: self.class.rule_id,
+        message: message,
+        severity: self.class.severity
+      )
+    end
+  end
+
+  # @param rules [Array<Symbol|Class|Rule>, nil] When nil, every registered
+  #   rule runs with default options. Symbols and classes are instantiated
+  #   via `Rule#new`; rule instances are used as-is.
+  def initialize(rules: nil)
+    classes_or_instances =
+      if rules.nil?
+        Rule.all
+      else
+        rules
+      end
+
+    @rules = classes_or_instances.map do |r|
+      case r
+      when Rule then r
+      when Class then r.new
+      else Rule.fetch(r).new
+      end
+    end
+  end
+
+  # Build a linter from a parsed config hash. Schema:
+  #
+  #   rules:
+  #     <rule_id>:
+  #       enabled: true|false        # default: true
+  #       <option>: <value>           # passed to Rule.from_config
+  #
+  # Rules omitted from the config default to enabled with no options, so
+  # adding a new rule to the gem won't silently disable it for users with
+  # an existing config file. To suppress a rule, list it with `enabled: false`.
+  def self.from_config(config)
+    config = (config || {}).transform_keys(&:to_s)
+    rules_config = (config["rules"] || {}).transform_keys(&:to_s)
+    instances = []
+
+    rules_config.each do |id, opts|
+      opts = (opts || {}).transform_keys(&:to_s)
+      next if opts["enabled"] == false
+
+      klass = Rule.fetch(id.to_sym)
+      instances << klass.from_config(opts.reject { |k, _| k == "enabled" })
+    end
+
+    Rule.all.each do |klass|
+      next if rules_config.key?(klass.rule_id.to_s)
+
+      instances << klass.new
+    end
+
+    new(rules: instances)
+  end
+
+  # Load a YAML config file and return a parsed hash. Returns an empty hash
+  # when the file is missing — the default `config/lint.yaml` is optional.
+  def self.load_config_file(path)
+    return {} unless File.file?(path)
+
+    YAML.safe_load_file(path) || {}
+  end
+
+  # Lint a SAS source string. `path` is used for finding location output.
+  # Returns just the findings array. Use `lint_with_fixes` when the caller
+  # wants the (possibly-modified) source back too.
+  def lint(source, path: "(string)")
+    lint_with_fixes(source, path: path).first
+  end
+
+  # Lint a SAS source string and apply any autofixes from rules whose
+  # `autofix?` instance flag is true. Returns `[findings, modified_source]`.
+  # When no rule has autofix enabled the modified source equals the input.
+  def lint_with_fixes(source, path: "(string)")
+    default_tokens, all_tokens = tokenize(source)
+    findings = @rules.flat_map do |rule|
+      rule.check(default_tokens, path: path, all_tokens: all_tokens, source: source)
+    end
+
+    modified = source
+    @rules.each do |rule|
+      next unless rule.autofix? && rule.class.supports_autofix?
+
+      modified = rule.autofix(modified)
+    end
+
+    [findings, modified]
+  end
+
+  # Lint a file by path. Sources are commonly Windows-1252 or ISO-8859-1
+  # rather than UTF-8 — read as binary and best-effort transcode so
+  # the lexer (which requires valid UTF-8) doesn't reject them.
+  #
+  # If any autofix-enabled rule rewrote the source, the file is updated
+  # in place. Returns the findings array regardless of write outcome.
+  #
+  # The `modified.b != original.b` guard compares raw bytes so a
+  # difference in encoding tags alone (e.g. UTF-8 vs ASCII-8BIT)
+  # doesn't trigger a write. That can happen when EncodingIssues
+  # autofix returns a binary string but no rule actually changed any
+  # bytes — without `.b` the file would be rewritten with byte-
+  # identical contents and a different encoding label, surfacing as
+  # a no-op diff in git that overwrites the user's chosen encoding.
+  def lint_file(path)
+    original = read_source(path)
+    findings, modified = lint_with_fixes(original, path: path)
+    File.write(path, modified) if modified.b != original.b
+    findings
+  end
+
+  private
+
+  def read_source(path)
+    raw = File.read(path, encoding: "BINARY")
+    return raw.force_encoding("UTF-8") if raw.dup.force_encoding("UTF-8").valid_encoding?
+
+    begin
+      raw.force_encoding("Windows-1252").encode("UTF-8", invalid: :replace, undef: :replace, replace: "'")
+    rescue StandardError
+      raw.force_encoding("ISO-8859-1").encode("UTF-8", invalid: :replace, undef: :replace, replace: "'")
+    end
+  end
+
+  # Returns [default_tokens, all_tokens]. Most rules walk default-channel
+  # tokens (no whitespace, no comments). A few — `commented_out_guard` for
+  # one — need to inspect comment tokens, so the unfiltered list is exposed
+  # to rules via the `all_tokens:` kwarg on `Rule#check`.
+  def tokenize(source)
+    lexer = SasLexer::Lexer.new
+    begin
+      all_tokens = lexer.tokenize(source)
+    ensure
+      lexer.free
+    end
+    default_tokens = all_tokens.reject do |t|
+      t[:channel] == SasLexer::Lexer::TokenChannel::HIDDEN ||
+        t[:channel] == SasLexer::Lexer::TokenChannel::COMMENT
+    end
+    [default_tokens, all_tokens]
+  end
+end
+
+require_relative "sas_linter/rules/unreachable_inner_branch_value"
+require_relative "sas_linter/rules/identical_if_else_branches"
+require_relative "sas_linter/rules/commented_out_guard"
+require_relative "sas_linter/rules/choose_one_template"
+require_relative "sas_linter/rules/trailing_whitespace"
+require_relative "sas_linter/rules/tab_expansion"
+require_relative "sas_linter/rules/source_headers"
+require_relative "sas_linter/rules/line_endings"
+require_relative "sas_linter/rules/encoding_issues"
+require_relative "sas_linter/rules/malformed_if_condition"
+require_relative "sas_linter/rules/missing_assignment_semicolon"
+require_relative "sas_linter/rules/variable_value_out_of_known_range"

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: sas-linter
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Craig McNamara
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sas-lexer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  A configurable lint engine for SAS source files. Walks the token
+  stream produced by the `sas-lexer` gem and applies a set of pluggable
+  rules covering structural defects (malformed `if` conditions,
+  identical `then`/`else` branches, unreachable inner branches),
+  cosmetic issues (trailing whitespace, tab expansion, line endings,
+  encoding gremlins), and source-header conventions. Includes a
+  `bin/sas_lint` CLI and YAML-based config.
+email:
+- craig@monami.io
+executables:
+- sas_lint
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- bin/sas_lint
+- lib/sas_linter.rb
+- lib/sas_linter/rules/choose_one_template.rb
+- lib/sas_linter/rules/commented_out_guard.rb
+- lib/sas_linter/rules/encoding_issues.rb
+- lib/sas_linter/rules/identical_if_else_branches.rb
+- lib/sas_linter/rules/line_endings.rb
+- lib/sas_linter/rules/malformed_if_condition.rb
+- lib/sas_linter/rules/missing_assignment_semicolon.rb
+- lib/sas_linter/rules/source_headers.rb
+- lib/sas_linter/rules/tab_expansion.rb
+- lib/sas_linter/rules/trailing_whitespace.rb
+- lib/sas_linter/rules/unreachable_inner_branch_value.rb
+- lib/sas_linter/rules/variable_value_out_of_known_range.rb
+- lib/sas_linter/version.rb
+homepage: https://github.com/mes-amis/sas-linter
+licenses:
+- AGPL-3.0-or-later
+metadata:
+  homepage_uri: https://github.com/mes-amis/sas-linter
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Configurable lint engine for SAS source files.
+test_files: []