zen_apropos

Apropos-style search engine for rake tasks.

zen_apropos scans your .rake files, indexes task names, descriptions, source code, and structured annotations, then lets you search across all of them from the command line or Rails console.

Add to your Gemfile:

gem 'zen_apropos'

Or install directly:

gem install zen_apropos

Then run bundle install.

zen_apropos <query>          # interactive rich output
zen_apropos <query> --plain  # machine-readable, no colors

In rich mode, results are numbered. You can type a number to view the full source of that task, enter a new query to search again, or q to quit.

Plain mode outputs pipe-separated columns (name | description | safety | team) suitable for piping to other tools.

zen_apropos lint                 # check all rake files
zen_apropos lint --changed-only  # only files changed in the current branch

The linter checks that every desc/task pair has annotation tags or uses zen_desc. Exits with code 0 when all tasks are annotated, 1 when any are missing.

Output looks like:

⚠ lib/tasks/new_feature.rake:12 -- task "new_feature:run" has no @zen_desc annotations

2 task(s) missing annotations. Consider adding @zen_desc tags or using zen_desc.

zen_apropos --help

Free text matches against task name, description, keywords, and source code (case-insensitive substring match). You can also use structured filters:

Filters can be combined with each other and with free text. Multiple filters use implicit AND:

zen_apropos "employee team:search"
zen_apropos "team:finance safety:destructive"
zen_apropos "keyword:elasticsearch"

Every rake task should be annotated with team ownership, safety level, and keywords. There are two equivalent ways to do this.

Place annotation lines immediately before the desc line. The default tag is @zen_desc:

namespace :indexer do
  # @zen_desc team: search
  # @zen_desc safety: safe
  # @zen_desc keywords: elasticsearch, reindex
  desc 'Reindex all employees'
  task employees: :environment do
    Employee.reindex
  end
end

Replace desc with zen_desc and pass metadata as keyword arguments:

zen_desc 'Run database backup',
  team: 'devops',
  safety: :safe,
  keywords: %w[backup database postgres]

task db_backup: :environment do
  system('pg_dump ...')
end

zen_desc calls desc under the hood, so rake -T keeps working.

Note: zen_desc is opt-in. You must explicitly require it:

require 'zen_apropos/zen_desc'

By default, zen_apropos recognizes # @zen_desc comment tags. If you want a different prefix for your organization:

Run init to generate a binstub with your tag pre-configured:

bundle exec zen_apropos init --tag myapp

This creates bin/zen_apropos in your project. From then on:

bin/zen_apropos "employee"        # uses @myapp automatically
bin/zen_apropos lint               # lints for @myapp tags

Pass --tag to any command:

zen_apropos --tag myapp "employee"
zen_apropos lint --tag myapp --changed-only

In an initializer or setup file:

ZenApropos.configure do |config|
  config.tag = 'myapp'
  config.glob_patterns = ['lib/tasks/**/*.rake', 'packages/**/lib/tasks/**/*.rake']
end

# @myapp team: payments
# @myapp safety: destructive
# @myapp keywords: refund, stripe
desc 'Process pending refunds'
task process_refunds: :environment do
  # ...
end

The linter, CLI, and console helper all respect the configured tag.

Migrating from @zen: If you previously used # @zen tags, either rename them to # @zen_desc or set config.tag = 'zen' to keep the old prefix.

You can define an apropos helper for quick searching in the Rails console. Example initializer:

# config/initializers/zen_apropos.rb
return unless Rails.env.development?

require 'zen_apropos'
require 'zen_apropos/zen_desc'

ZenApropos.configure do |config|
  config.tag = 'myapp' # recognizes # @myapp instead of # @zen_desc
end

RAKE_PATHS = ['lib/tasks/**/*.rake'].freeze

def apropos(query = nil, plain: false)
  engine = ZenApropos::Engine.new(plain: plain, glob_patterns: RAKE_PATHS)

  if query.nil? || query.strip.empty?
    puts engine.help
    return
  end

  puts engine.search(query)
end

Then in the console:

apropos "employee"
apropos "team:finance safety:destructive"
apropos "reindex", plain: true
apropos  # shows help

By default, zen_apropos scans lib/tasks/**/*.rake. For monorepos or apps with tasks in non-standard locations, configure custom patterns:

ZenApropos.configure do |config|
  config.glob_patterns = ['lib/tasks/**/*.rake', 'packages/**/lib/tasks/**/*.rake']
end

This works in binstubs, initializers, and anywhere you call ZenApropos.configure. The CLI and linter both respect it. You can also pass patterns directly to the engine:

engine = ZenApropos::Engine.new(
  glob_patterns: ['lib/tasks/**/*.rake', 'packages/**/lib/tasks/**/*.rake']
)

bundle exec rake test

Or simply:

bundle exec rake

Tests use Minitest and run against fixture rake files in test/fixtures/.

Bug reports and pull requests are welcome on GitHub at https://github.com/ZenHR/zen_apropos. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

The gem is available as open source under the terms of the MIT License.