columnlens 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f014ac1f374469c92d5161bea7ad72efb86a3a70292fc304a98bde5c494b9e5c
+  data.tar.gz: 57065f1a89c2300f1ff1f081a244e75d1df502e011622faf994916051516515a
+SHA512:
+  metadata.gz: 66396ebec94c1ba101aedf36d2a23ca3bdc30d18f1dca4f21cd7c902c240af651387b8edc065a6029c2c449a0f98f6b34805f04837ba7412dd86e47b71808a33
+  data.tar.gz: b7fbf7af6247cb4fa59f94137613663af8f6e8f35cace68fb9ddc936b1a6b759a433fc05c7175183d5318f61d46a71510b5965f7e09fe36ae3a32df7431b8682

data/.rubocop.yml

@@ -0,0 +1,14 @@
+AllCops:
+  TargetRubyVersion: 3.0
+
+Metrics/MethodLength:
+  Max: 20
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Fai Wong
+
+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,136 @@
+# ColumnLens
+
+[![Gem Version](https://badge.fury.io/rb/columnlens.svg)](https://badge.fury.io/rb/columnlens)
+
+**columnlens** is a CLI tool to analyze your Ruby on Rails database schema. It helps detect unused, read-only, and orphaned columns, providing insight into schema hygiene and technical debt.
+
+---
+
+## ✨ Features
+
+- Scan your full Rails database schema
+- Detect actively used, write-only, read-only, and orphaned columns
+- Respect system tables and configurable ignore rules
+
+---
+
+## 🧰 Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'columnlens'
+```
+
+Then execute:
+
+```sh
+$ bundle install
+```
+
+Or install it globally:
+
+```sh
+$ gem install columnlens
+```
+
+---
+
+## 🚀 Usage
+
+From any Rails project:
+
+```sh
+$ bundle exec columnlens scan
+```
+
+Output example:
+
+```
+🔍 ColumnLens Scan Mode
+Scanning full schema...
+
+posts.title          read_write
+users.email          read_write
+users.last_seen_at   orphaned
+...
+```
+
+---
+
+## ⚙️ Configuration
+
+ColumnLens uses a .columnlens.yml in your project root:
+
+```yaml
+system_tables:
+  - "^active_storage_"
+  - "^schema_migrations$"
+  - "^ar_internal_metadata$"
+
+ignore:
+  scan:
+    orphaned:
+      - "posts"
+      - "users.created_at"
+      - "users.updated_at"
+  deep:
+    orphaned: []
+```
+
+Defaults are provided in lib/config/default.yml and merged with the project config.
+
+---
+
+## 🔧 Development
+
+To set up the project locally:
+
+```sh
+$ git clone https://github.com/BestBitsLab/columnlens.git
+$ cd columnlens
+$ bin/setup
+```
+
+You can experiment with the code via:
+
+```sh
+$ bin/console
+```
+
+To build and install the gem locally:
+
+```sh
+$ bundle exec rake install
+```
+
+To release a new version:
+
+1. Update the version in `lib/columnlens/version.rb`
+2. Run:
+
+```sh
+$ bundle exec rake release
+```
+
+This will tag, push, and publish to [RubyGems.org](https://rubygems.org).
+
+---
+
+## 🤝 Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/BestBitsLab/columnlens). This project is intended to be a safe, welcoming space for collaboration. Please read and follow the [code of conduct](https://github.com/BestBitsLab/columnlens/blob/main/CODE_OF_CONDUCT.md).
+
+---
+
+## 🪪 License
+
+This gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+---
+
+## 📜 Code of Conduct
+
+Everyone interacting in the ColumnLens project's codebase, issue trackers, and other community spaces is expected to follow the [Code of Conduct](https://github.com/BestBitsLab/columnlens/blob/main/CODE_OF_CONDUCT.md).
+
+---

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: :rubocop

data/exe/columnlens

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/columnlens"
+
+Columnlens.run(ARGV)

data/lib/columnlens/classifier.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Columnlens
+  class Classifier
+    def self.classify(table, column, usage)
+      status =
+        case usage
+        when :read_write then :active
+        when :write_only then :write_only
+        when :read_only  then :read_only
+        when :orphaned   then :orphaned
+        when :system     then :system
+        else :unknown
+        end
+
+      {
+        table: table,
+        column: column,
+        status: status
+      }
+    end
+  end
+end

data/lib/columnlens/config/default.yml

@@ -0,0 +1,10 @@
+system_tables:
+  - "^active_storage_"
+  - "^schema_migrations$"
+  - "^ar_internal_metadata$"
+
+ignore:
+  scan:
+    orphaned: []
+  deep:
+    orphaned: []

data/lib/columnlens/config.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "paths"
+
+# Handles loading and merging default and project configurations for ColumnLens
+module Columnlens
+  class Config
+    def self.load
+      defaults = load_yaml(Paths.default_config)
+      project  = load_yaml(Paths.project_config)
+
+      deep_merge(defaults, project)
+    end
+
+    def self.load_yaml(path)
+      return {} unless path && File.exist?(path)
+
+      YAML.load_file(path) || {}
+    end
+
+    def self.deep_merge(base_config, project_config)
+      base_config.merge(project_config) do |_key, old, new|
+        old.is_a?(Hash) && new.is_a?(Hash) ? deep_merge(old, new) : new
+      end
+    end
+  end
+end

data/lib/columnlens/core/schema_loader.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "../project_root"
+
+module Columnlens
+  module Core
+    class SchemaLoader
+      TABLE_REGEX  = /create_table "([^"]+)"/
+      COLUMN_REGEX = /t\.\w+\s+"([^"]+)"/
+
+      def self.load
+        schema_path = File.join(ProjectRoot.detect, "db/schema.rb")
+
+        raise "Columnlens: db/schema.rb not found at #{schema_path}" unless File.exist?(schema_path)
+
+        schema_content = File.read(schema_path)
+        parse_tables(schema_content)
+      end
+
+      def self.parse_tables(schema_content)
+        tables = {}
+        current_table = nil
+
+        schema_content.each_line do |line|
+          if line.match?(TABLE_REGEX)
+            current_table = line[TABLE_REGEX, 1]
+            tables[current_table] ||= []
+
+          elsif current_table && line.match?(COLUMN_REGEX)
+            column = line[COLUMN_REGEX, 1]
+            tables[current_table] << column
+
+          elsif line.strip == "end"
+            current_table = nil
+          end
+        end
+
+        tables
+      end
+    end
+  end
+end

data/lib/columnlens/core/usage_scanner.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Columnlens
+  module Core
+    class UsageScanner
+      attr_reader :tables, :usage_results
+
+      def initialize(tables)
+        # tables: array of { name: "table_name", columns: ["col1", "col2"] }
+        @tables = tables
+        @usage_results = {}
+      end
+
+      def scan!
+        tables.each do |table|
+          table_name = table[:name]
+          columns = table[:columns]
+
+          columns.each do |col|
+            status = detect_column_usage(table_name, col)
+            mark_used(table_name, col, status)
+          end
+        end
+        usage_results
+      end
+
+      private
+
+      # Mark column usage
+      def mark_used(table_name, column, status)
+        usage_results[table_name] ||= {}
+        usage_results[table_name][column] = status
+      end
+
+      # Detect usage using multiple heuristics
+      def detect_column_usage(table_name, column)
+        return :read_write if association_column?(table_name, column)
+        return :read_write if scanned_in_code?(table_name, column)
+
+        :orphaned
+      end
+
+      # Detect foreign keys for associations
+      def association_column?(table_name, column)
+        # Common Rails convention: belongs_to :model → model_id
+        return true if column =~ /_id$/ && belongs_to_exists?(table_name, column)
+
+        false
+      end
+
+      def belongs_to_exists?(table_name, column)
+        model_class = table_name.singularize.camelize.safe_constantize
+        return false unless model_class.respond_to?(:reflect_on_all_associations)
+
+        model_class.reflect_on_all_associations(:belongs_to).any? do |assoc|
+          "#{assoc.name}_id" == column
+        end
+      rescue NameError
+        false
+      end
+
+      # Scan Ruby + view templates
+      def scanned_in_code?(_table_name, column)
+        patterns = [
+          "app/models/**/*.rb",
+          "app/controllers/**/*.rb",
+          "app/jobs/**/*.rb",
+          "app/views/**/*.erb",
+          "app/views/**/*.slim",
+          "app/views/**/*.haml",
+          "app/serializers/**/*.rb"
+        ]
+
+        patterns.any? do |pattern|
+          Dir.glob(pattern).any? do |file|
+            File.read(file).include?(column)
+          end
+        end
+      rescue Errno::ENOENT
+        false
+      end
+    end
+  end
+end

data/lib/columnlens/ignore_rules.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Columnlens
+  class IgnoreRules
+    def initialize(config)
+      @config = config
+    end
+
+    def system_table_patterns
+      Array(@config["system_tables"]).map { |p| Regexp.new(p) }
+    end
+
+    def ignored?(mode:, category:, table:, column:)
+      entries = Array(
+        @config.dig("ignore", mode.to_s, category.to_s)
+      )
+
+      entries.any? do |e|
+        e == table || e == "#{table}.#{column}"
+      end
+    end
+  end
+end

data/lib/columnlens/paths.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Columnlens
+  module Paths
+    def self.project_root
+      ProjectRoot.detect
+    end
+
+    def self.project_config
+      File.join(project_root, ".columnlens.yml")
+    end
+
+    def self.default_config
+      File.expand_path("../columnlens/config/default.yml", __dir__)
+    end
+  end
+end

data/lib/columnlens/project_root.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Columnlens
+  module ProjectRoot
+    def self.detect
+      return ENV["GITHUB_WORKSPACE"] if ENV["GITHUB_WORKSPACE"]
+      return Rails.root.to_s if defined?(Rails)
+
+      Dir.pwd
+    end
+  end
+end

data/lib/columnlens/reporter.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Columnlens
+  class Reporter
+    ICONS = {
+      active: "🟢",
+      write_only: "🟡",
+      read_only: "🟠",
+      orphaned: "🔴"
+    }.freeze
+
+    def self.print(results)
+      grouped = results.group_by { |r| r[:status] }
+
+      grouped.each do |status, items|
+        puts "\n#{ICONS[status]} #{status.to_s.upcase} (#{items.count})"
+        items.each do |r|
+          puts "  - #{r[:table]}.#{r[:column]}"
+        end
+      end
+    end
+  end
+end

data/lib/columnlens/result_filter.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Columnlens
+  class ResultFilter
+    def initialize(config, mode:)
+      @config = config
+      @mode   = mode
+    end
+
+    def filter(results)
+      results.reject do |r|
+        system_table?(r[:table]) ||
+          ignored?(r)
+      end
+    end
+
+    private
+
+    def system_table?(table)
+      @config.system_table_patterns.any? { |p| table.match?(p) }
+    end
+
+    def ignored?(record)
+      @config.ignored?(
+        mode: @mode,
+        category: record[:status],
+        table: record[:table],
+        column: record[:column]
+      )
+    end
+  end
+end

data/lib/columnlens/scan_mode.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "core/schema_loader"
+require_relative "core/usage_scanner"
+require_relative "classifier"
+require_relative "config"
+require_relative "ignore_rules"
+require_relative "result_filter"
+require_relative "reporter"
+
+# Handles scanning the database schema and classifying column usage.
+module Columnlens
+  class ScanMode
+    MODE = :scan
+
+    def self.run
+      puts "🔍 Columnlens Scan Mode"
+      puts "Scanning full schema...\n\n"
+
+      results = process_schema
+
+      Reporter.print(results)
+    end
+
+    def self.process_schema
+      schema  = Core::SchemaLoader.load
+      scanner = Core::UsageScanner.new(map_tables(schema))
+      raw     = scanner.scan!
+
+      results = classify_columns(raw)
+      filter_results(results)
+    end
+
+    def self.map_tables(schema)
+      schema.map { |table, columns| { name: table, columns: columns } }
+    end
+
+    def self.classify_columns(raw)
+      raw.flat_map do |table, columns|
+        columns.map do |column, usage|
+          Classifier.classify(table, column, usage)
+        end
+      end
+    end
+
+    def self.filter_results(results)
+      config = IgnoreRules.new(Config.load)
+      ResultFilter.new(config, mode: MODE).filter(results)
+    end
+  end
+end

data/lib/columnlens/version.rb

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

data/lib/columnlens.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "columnlens/scan_mode"
+
+module Columnlens
+  def self.run(args)
+    case args.first
+    when "scan"
+      Columnlens::ScanMode.run
+    else
+      puts <<~USAGE
+        Usage:
+          columnlens scan     # Full schema inventory
+      USAGE
+      exit 1
+    end
+  end
+end

data/sig/columnlens.rbs

@@ -0,0 +1,4 @@
+module Columnlens
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: columnlens
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Fai Wong
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-12-18 00:00:00.000000000 Z
+dependencies: []
+description: |
+  ColumnLens analyzes your Ruby on Rails codebase and database schema
+  to identify actively used, write-only, read-only, and orphaned columns.
+  Designed for CI, GitHub Actions, and continuous schema hygiene.
+email:
+- wongwf82@gmail.com
+executables:
+- columnlens
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/columnlens
+- lib/columnlens.rb
+- lib/columnlens/classifier.rb
+- lib/columnlens/config.rb
+- lib/columnlens/config/default.yml
+- lib/columnlens/core/schema_loader.rb
+- lib/columnlens/core/usage_scanner.rb
+- lib/columnlens/ignore_rules.rb
+- lib/columnlens/paths.rb
+- lib/columnlens/project_root.rb
+- lib/columnlens/reporter.rb
+- lib/columnlens/result_filter.rb
+- lib/columnlens/scan_mode.rb
+- lib/columnlens/version.rb
+- sig/columnlens.rbs
+homepage: https://github.com/BestBitsLab/columnlens
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/BestBitsLab/columnlens
+  source_code_uri: https://github.com/BestBitsLab/columnlens
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.3
+signing_key:
+specification_version: 4
+summary: Detect unused, read-only, and orphaned database columns in Rails apps
+test_files: []