laerad 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9868751b6212ee096d1ca903704d4c4deb477ebd962fbf9afd4ad555851b8e56
+  data.tar.gz: e4d1b263fd9e4b5f441b2663dfb9880906cc18b7373c72d038187f60948a512a
+SHA512:
+  metadata.gz: 8d99e9f2eb8ef8e8d08323072137f6f1b0e5e06381fe7f249279a0cb6228e52a18ebad07318643abfee0af6648c90d9d59fae5fbed061715d9896c300cd033b9
+  data.tar.gz: 976b8023bed99446cf2117bbd85f92e6ab05cf701d718c7d6ba2c5b52d6ceecc6aff0645eb7318e43ebe5dccc1535415eab7b6a885df4be5f391f1f5272a3fef

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Giles
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,103 @@
+# Laerad: Eliminate Single-Use Variables
+
+A static analyzer that detects single-use variables in Ruby code.
+
+## Usage
+
+Scan a file or directory for single-use variables:
+
+```bash
+bundle exec bin/laerad scan path/to/file.rb
+bundle exec bin/laerad scan path/to/directory
+```
+
+## How It Works
+
+Laerad uses [SyntaxTree](https://github.com/ruby-syntax-tree/syntax_tree) to
+parse Ruby source files into an abstract syntax tree (AST). It then walks this
+tree, tracking every variable definition along with its references.
+
+### Detection
+
+Laerad flags variables that are used only once or not at all.
+
+### Scoping
+
+Variables are tracked per lexical scope. Each method body, block, or lambda
+creates a new scope. A variable defined inside a block is separate from a
+variable with the same name outside that block.
+
+## Architecture
+
+```
+CLI (Thor)
+ └─> Runner
+      └─> FileAnalyzer (per file)
+           ├─> SyntaxTree.parse
+           ├─> AST visitor
+           ├─> Scope stack (tracks variables)
+           └─> Result (violations)
+```
+
+- **CLI** (`lib/laerad/cli.rb`) - Thor-based command interface with `scan` and
+  `version` commands
+- **Runner** (`lib/laerad/runner.rb`) - Expands directories into file lists
+  and orchestrates analysis
+- **FileAnalyzer** (`lib/laerad/file_analyzer.rb`) - Parses Ruby, walks the
+  AST, maintains a scope stack
+- **Scope** (`lib/laerad/scope.rb`) - Tracks definitions and references with
+  usage counts
+- **Result** (`lib/laerad/result.rb`) - Collects violations and formats output
+
+### Options
+
+Short output (file:line only):
+
+```bash
+bundle exec bin/laerad scan --short path/to/file.rb
+bundle exec bin/laerad scan -s path/to/file.rb
+```
+
+Print version:
+
+```bash
+bundle exec bin/laerad version
+```
+
+## Development
+
+Install dependencies:
+
+```bash
+bundle install
+```
+
+## Example Output
+
+```
+❯ bundle exec bin/laerad scan test/fixtures/unused_variable.rb
++--------------------------------------+------+----------+------+
+| File                                 | Line | Variable | Uses |
++--------------------------------------+------+----------+------+
+| test/fixtures/unused_variable.rb     | 2    | x        | 1    |
++--------------------------------------+------+----------+------+
+
+❯ bundle exec bin/laerad scan -s test/fixtures/unused_variable.rb
+test/fixtures/unused_variable.rb:2
+```
+
+## Tests
+
+```bash
+bundle exec rake test
+```
+
+### What's in a name?
+
+This gem combines Thor with SyntaxTree. Combining Thor with trees made me think
+of Yggdrasil, the world tree of Norse mythology, but there's already a gem by
+that name. Laerad is an Anglicization of another Norse mythology tree name. It's
+[unclear](https://en.wikipedia.org/wiki/L%C3%A6ra%C3%B0r#Theories) how distinct
+this tree is from Yggdrasil — could be another name for the same tree, could
+be a separate but related tree — but that's usually how things are with
+mythologies.

data/bin/laerad

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/laerad"
+
+Laerad::CLI.start(ARGV)

data/lib/laerad/cli.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Laerad
+  class CLI < Thor
+    def self.exit_on_failure?
+      true
+    end
+
+    desc "scan PATH", "Scan Ruby files for single-use variables"
+    method_option :short, type: :boolean, aliases: "-s", desc: "Output only file:line"
+    def scan(path = ".")
+      result = Runner.new(path, options).run
+
+      if result.violations?
+        puts result.format_output(short: options[:short])
+        exit 1
+      else
+        puts "No violations found."
+        exit 0
+      end
+    end
+
+    desc "version", "Print version"
+    def version
+      puts "laerad #{VERSION}"
+    end
+
+    default_task :scan
+  end
+end

data/lib/laerad/file_analyzer.rb

@@ -0,0 +1,362 @@
+# frozen_string_literal: true
+
+require "syntax_tree"
+
+module Laerad
+  class FileAnalyzer
+    def self.analyze(path, options = {})
+      new(path, options).analyze
+    end
+
+    def initialize(path, options = {})
+      @path = path
+      @source = File.read(path)
+      @scope_stack = [Scope.new]
+      @result = Result.new(file: path)
+      @options = options
+    end
+
+    def analyze
+      ast = SyntaxTree.parse(@source)
+      visit(ast)
+      finalize_scope(@scope_stack.last)
+      @result
+    rescue SyntaxTree::Parser::ParseError
+      @result
+    end
+
+    private
+
+    def current_scope
+      @scope_stack.last
+    end
+
+    def push_scope
+      @scope_stack.push(Scope.new)
+    end
+
+    def pop_scope
+      scope = @scope_stack.pop
+      finalize_scope(scope)
+      scope
+    end
+
+    def finalize_scope(scope)
+      scope.single_use_variables.each do |name|
+        line = scope.variable_definition_line(name)
+        @result.add_variable_violation(
+          name: name,
+          line: line,
+          count: scope.variable_count(name)
+        )
+      end
+    end
+
+    def visit(node)
+      return unless node
+
+      case node
+      when SyntaxTree::Program
+        visit(node.statements)
+
+      when SyntaxTree::Statements
+        node.body.each { |stmt| visit(stmt) }
+
+      when SyntaxTree::VarField
+        name = extract_var_name(node)
+        if name
+          line = node.location.start_line
+          current_scope.register_variable_def(name, line)
+        end
+
+      when SyntaxTree::VarRef
+        name = extract_var_name(node)
+        current_scope.register_variable_ref(name) if name
+
+      when SyntaxTree::Assign
+        visit(node.target)
+        visit(node.value)
+
+      when SyntaxTree::OpAssign
+        visit(node.target)
+        visit(node.value)
+
+      when SyntaxTree::DefNode
+        push_scope
+        visit_params(node.params)
+        visit(node.bodystmt)
+        pop_scope
+
+      when SyntaxTree::BodyStmt
+        visit(node.statements)
+        node.rescue_clause&.then { |r| visit(r) }
+        node.else_clause&.then { |e| visit(e) }
+        node.ensure_clause&.then { |en| visit(en) }
+
+      when SyntaxTree::Rescue
+        if node.exception
+          visit_rescue_exception(node.exception)
+        end
+        visit(node.statements)
+        visit(node.consequent) if node.consequent
+
+      when SyntaxTree::RescueEx
+        if node.variable
+          visit(node.variable)
+        end
+
+      when SyntaxTree::MethodAddBlock
+        visit(node.call)
+        visit(node.block)
+
+      when SyntaxTree::CallNode
+        visit(node.receiver) if node.receiver
+        visit(node.arguments) if node.arguments
+
+      when SyntaxTree::Command
+        visit(node.arguments)
+
+      when SyntaxTree::CommandCall
+        visit(node.receiver) if node.receiver
+        visit(node.arguments) if node.arguments
+
+      when SyntaxTree::BlockNode
+        push_scope
+        visit_block_params(node.block_var) if node.block_var
+        visit(node.bodystmt)
+        pop_scope
+
+      when SyntaxTree::Lambda
+        push_scope
+        visit_lambda_params(node.params)
+        visit(node.statements)
+        pop_scope
+
+      when SyntaxTree::ClassDeclaration
+        visit(node.bodystmt)
+
+      when SyntaxTree::ModuleDeclaration
+        visit(node.bodystmt)
+
+      when SyntaxTree::Binary
+        visit(node.left)
+        visit(node.right)
+
+      when SyntaxTree::Unary
+        visit(node.statement)
+
+      when SyntaxTree::Paren
+        visit(node.contents)
+
+      when SyntaxTree::IfNode
+        visit(node.predicate)
+        visit(node.statements)
+        visit(node.consequent) if node.consequent
+
+      when SyntaxTree::UnlessNode
+        visit(node.predicate)
+        visit(node.statements)
+        visit(node.consequent) if node.consequent
+
+      when SyntaxTree::Elsif
+        visit(node.predicate)
+        visit(node.statements)
+        visit(node.consequent) if node.consequent
+
+      when SyntaxTree::Else
+        visit(node.statements)
+
+      when SyntaxTree::WhileNode
+        visit(node.predicate)
+        visit(node.statements)
+
+      when SyntaxTree::UntilNode
+        visit(node.predicate)
+        visit(node.statements)
+
+      when SyntaxTree::For
+        visit(node.index)
+        visit(node.collection)
+        visit(node.statements)
+
+      when SyntaxTree::Case
+        visit(node.value) if node.value
+        visit(node.consequent)
+
+      when SyntaxTree::When
+        node.arguments.parts.each { |arg| visit(arg) }
+        visit(node.statements)
+        visit(node.consequent) if node.consequent
+
+      when SyntaxTree::In
+        visit(node.pattern)
+        visit(node.statements)
+        visit(node.consequent) if node.consequent
+
+      when SyntaxTree::Begin
+        visit(node.bodystmt)
+
+      when SyntaxTree::Ensure
+        visit(node.statements)
+
+      when SyntaxTree::ReturnNode
+        visit(node.arguments) if node.arguments
+
+      when SyntaxTree::YieldNode
+        visit(node.arguments) if node.arguments
+
+      when SyntaxTree::Args
+        node.parts.each { |part| visit(part) }
+
+      when SyntaxTree::ArgParen
+        visit(node.arguments)
+
+      when SyntaxTree::ArrayLiteral
+        visit(node.contents) if node.contents
+
+      when SyntaxTree::HashLiteral
+        node.assocs.each { |assoc| visit(assoc) } if node.assocs.is_a?(Array)
+        visit(node.assocs) if node.assocs && !node.assocs.is_a?(Array)
+
+      when SyntaxTree::Assoc
+        visit(node.key)
+        visit(node.value)
+
+      when SyntaxTree::AssocSplat
+        visit(node.value)
+
+      when SyntaxTree::RangeNode
+        visit(node.left) if node.left
+        visit(node.right) if node.right
+
+      when SyntaxTree::Not
+        visit(node.statement)
+
+      when SyntaxTree::Defined
+        visit(node.value)
+
+      when SyntaxTree::ARef
+        visit(node.collection)
+        visit(node.index)
+
+      when SyntaxTree::ARefField
+        visit(node.collection)
+        visit(node.index)
+
+      when SyntaxTree::StringConcat
+        visit(node.left)
+        visit(node.right)
+
+      when SyntaxTree::StringEmbExpr
+        visit(node.statements)
+
+      when SyntaxTree::StringLiteral
+        node.parts.each { |part| visit(part) }
+
+      when SyntaxTree::DynaSymbol
+        node.parts.each { |part| visit(part) }
+
+      when SyntaxTree::XStringLiteral
+        node.parts.each { |part| visit(part) }
+
+      when SyntaxTree::RegexpLiteral
+        node.parts.each { |part| visit(part) }
+
+      when SyntaxTree::Heredoc
+        node.parts.each { |part| visit(part) }
+
+      when SyntaxTree::MAssign
+        visit(node.target)
+        visit(node.value)
+
+      when SyntaxTree::MLHS
+        node.parts.each { |part| visit(part) }
+
+      when SyntaxTree::MLHSParen
+        visit(node.contents)
+
+      when SyntaxTree::Next, SyntaxTree::Break, SyntaxTree::Redo, SyntaxTree::Retry
+        # control flow, no-op
+
+      when SyntaxTree::VoidStmt
+        # empty statement, no-op
+      end
+    end
+
+    def visit_params(params)
+      return unless params
+
+      case params
+      when SyntaxTree::Params
+        params.requireds.each { |p| register_param(p) }
+        params.optionals.each do |opt|
+          register_param(opt[0])
+          visit(opt[1])
+        end
+        register_param(params.rest) if params.rest && params.rest != :nil
+        params.posts.each { |p| register_param(p) }
+        params.keywords.each do |kw|
+          register_param(kw[0])
+          visit(kw[1]) if kw[1]
+        end
+        register_param(params.keyword_rest) if params.keyword_rest
+        register_param(params.block) if params.block
+      when SyntaxTree::Paren
+        visit_params(params.contents)
+      end
+    end
+
+    def visit_block_params(block_var)
+      return unless block_var
+
+      visit_params(block_var.params)
+      block_var.locals.each { |local| register_param(local) }
+    end
+
+    def visit_lambda_params(params)
+      case params
+      when SyntaxTree::LambdaVar
+        visit_params(params.params)
+        params.locals.each { |local| register_param(local) }
+      when SyntaxTree::Paren
+        visit_lambda_params(params.contents)
+      when SyntaxTree::Params
+        visit_params(params)
+      end
+    end
+
+    def register_param(param)
+      return unless param
+
+      name = case param
+      when SyntaxTree::Ident
+        param.value
+      when SyntaxTree::RestParam
+        param.name&.value
+      when SyntaxTree::KeywordRestParam
+        param.name&.value
+      when SyntaxTree::BlockArg
+        param.name&.value
+      when SyntaxTree::ArgsForward
+        nil
+      end
+
+      if name
+        current_scope.register_variable_def(name, param.location.start_line)
+      end
+    end
+
+    def visit_rescue_exception(exception)
+      if exception.variable
+        visit(exception.variable)
+      end
+    end
+
+    def extract_var_name(node)
+      case node.value
+      when SyntaxTree::Ident
+        node.value.value
+      end
+    end
+  end
+end

data/lib/laerad/result.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "terminal-table"
+
+module Laerad
+  class Result
+    attr_reader :file, :variable_violations
+
+    def initialize(file: nil, variable_violations: [])
+      @file = file
+      @variable_violations = variable_violations
+    end
+
+    def add_variable_violation(name:, line:, count:)
+      @variable_violations << {name: name, line: line, count: count}
+    end
+
+    def violations?
+      @variable_violations.any?
+    end
+
+    def self.merge(*results)
+      merged_variable_violations = []
+
+      results.each do |result|
+        result.variable_violations.each do |v|
+          merged_variable_violations << v.merge(file: result.file)
+        end
+      end
+
+      new(variable_violations: merged_variable_violations)
+    end
+
+    def format_output(short: false)
+      return "" if @variable_violations.empty?
+
+      if short
+        @variable_violations.map do |v|
+          file_path = v[:file] || @file
+          "#{file_path}:#{v[:line]}"
+        end.join("\n")
+      else
+        rows = @variable_violations.map do |v|
+          file_path = v[:file] || @file
+          [file_path, v[:line], v[:name], v[:count]]
+        end
+
+        table = Terminal::Table.new(
+          headings: ["File", "Line", "Variable", "Uses"],
+          rows: rows
+        )
+
+        table.to_s
+      end
+    end
+  end
+end

data/lib/laerad/runner.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Laerad
+  class Runner
+    def initialize(paths, options = {})
+      @paths = Array(paths)
+      @options = options
+    end
+
+    def run
+      files = expand_paths
+      results = files.map { |file| FileAnalyzer.analyze(file, @options) }
+      Result.merge(*results)
+    end
+
+    private
+
+    def expand_paths
+      @paths.flat_map do |path|
+        if File.directory?(path)
+          Dir.glob(File.join(path, "**", "*.rb"))
+        elsif File.file?(path) && path.end_with?(".rb")
+          [path]
+        else
+          []
+        end
+      end
+    end
+  end
+end

data/lib/laerad/scope.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Laerad
+  class Scope
+    attr_reader :variables, :variable_def_lines
+
+    def initialize
+      @variables = Hash.new(0)
+      @variable_def_lines = Hash.new { |h, k| h[k] = [] }
+    end
+
+    def register_variable_def(name, line)
+      @variables[name] += 1
+      @variable_def_lines[name] << line
+    end
+
+    def register_variable_ref(name)
+      @variables[name] += 1
+    end
+
+    def single_use_variables
+      @variables.select { |_, count| count <= 2 }.keys
+    end
+
+    def variable_definition_line(name)
+      @variable_def_lines[name].first
+    end
+
+    def variable_count(name)
+      @variables[name]
+    end
+  end
+end

data/lib/laerad/version.rb

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

data/lib/laerad.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "laerad/version"
+require_relative "laerad/scope"
+require_relative "laerad/result"
+require_relative "laerad/file_analyzer"
+require_relative "laerad/runner"
+require_relative "laerad/cli"
+
+module Laerad
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: laerad
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Giles Bowkett
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: syntax_tree
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.3'
+- !ruby/object:Gem::Dependency
+  name: terminal-table
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+executables:
+- laerad
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/laerad
+- lib/laerad.rb
+- lib/laerad/cli.rb
+- lib/laerad/file_analyzer.rb
+- lib/laerad/result.rb
+- lib/laerad/runner.rb
+- lib/laerad/scope.rb
+- lib/laerad/version.rb
+homepage: https://github.com/gilesbowkett/laerad
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.7
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Static analyzer to detect single-use variables in Ruby code
+test_files: []