zen_apropos 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 63464f8005004d28dee7b44cd5851420b6d4e1ca757639e1b0576f0d59ec772b
+  data.tar.gz: 5626472b4d781eb408335060267ed96c1a5de249301ab5e007f10c87f2adfe02
+SHA512:
+  metadata.gz: 884a57e12504d4df0f7e414c950ce50d28f51c6f025c5cca99f02ac1ad80157498ebd3aad50db029efb9bfd7bec9848e063308555070860ca47f5454e008cd36
+  data.tar.gz: 0c2a616987e6b4fbe517d9e59c9fa8b025a8688c0ffa8939a47e7b15185cc45d5f5e9cb545601646e9fe61811e8112fe2fca3a4603d20e7038c6ecb38aaf7542

data/.gitignore

@@ -0,0 +1,2 @@
+tmp/
+*.gem

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 0.2.0
+
+### Breaking Changes
+
+- **Default tag renamed from `@zen` to `@zen_desc`.** Rename your annotations or set `config.tag = 'zen'` to keep the old prefix.
+
+### Improvements
+
+- `zen_desc` DSL now uses a pending-consumption pattern instead of a description-keyed registry, preventing collisions when two tasks share the same description
+- Index cache no longer deserializes the cache file twice on cache hits
+- Cache writing gracefully handles permission errors instead of raising
+
+## 0.1.0
+
+- Initial release
+- CLI search with free text and structured filters (`team:`, `safety:`, `namespace:`, `keyword:`)
+- `# @zen_desc` comment annotations and `zen_desc` DSL
+- Interactive result viewer with source inspection
+- Plain mode (`--plain`) for machine-readable output
+- Annotation linter with `--changed-only` support
+- Configurable tag prefix via `ZenApropos.configure`
+- Custom glob patterns for monorepo support
+- Mtime-based index caching

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers 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, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at a.keewan@zenhr.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [https://contributor-covenant.org/version/1/4][version]
+
+[homepage]: https://contributor-covenant.org
+[version]: https://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,21 @@
+PATH
+  remote: .
+  specs:
+    zen_apropos (0.2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    minitest (5.25.1)
+    rake (13.2.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  minitest (~> 5.0)
+  rake (~> 13.0)
+  zen_apropos!
+
+BUNDLED WITH
+   2.1.4

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 ZenHR Engineering
+
+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,262 @@
+# zen_apropos
+
+[![Gem Version](https://badge.fury.io/rb/zen_apropos.svg)](https://badge.fury.io/rb/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.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'zen_apropos'
+```
+
+Or install directly:
+
+```bash
+gem install zen_apropos
+```
+
+Then run `bundle install`.
+
+## CLI Usage
+
+### Search
+
+```bash
+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.
+
+### Lint
+
+```bash
+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.
+```
+
+### Help
+
+```bash
+zen_apropos --help
+```
+
+## Query Syntax
+
+Free text matches against task name, description, keywords, and source code (case-insensitive substring match). You can also use structured filters:
+
+| Filter | Example | Matches |
+|--------|---------|---------|
+| `team:` | `team:search` | Tasks owned by the "search" team |
+| `safety:` | `safety:destructive` | Tasks marked as destructive |
+| `namespace:` | `namespace:indexer` | Tasks in the `indexer` namespace |
+| `keyword:` | `keyword:elasticsearch` | Tasks tagged with that keyword |
+
+Filters can be combined with each other and with free text. Multiple filters use implicit AND:
+
+```bash
+zen_apropos "employee team:search"
+zen_apropos "team:finance safety:destructive"
+zen_apropos "keyword:elasticsearch"
+```
+
+## Annotation System
+
+Every rake task should be annotated with team ownership, safety level, and keywords. There are two equivalent ways to do this.
+
+### Option A: Comment Tags
+
+Place annotation lines immediately before the `desc` line. The default tag is `@zen_desc`:
+
+```ruby
+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
+```
+
+### Option B: `zen_desc` DSL
+
+Replace `desc` with `zen_desc` and pass metadata as keyword arguments:
+
+```ruby
+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:
+
+```ruby
+require 'zen_apropos/zen_desc'
+```
+
+### Supported Fields
+
+| Field | Type | Values |
+|-------|------|--------|
+| `team` | String | Any team name (e.g. `search`, `hr-platform`, `devops`) |
+| `safety` | String/Symbol | `safe`, `caution`, `destructive` |
+| `keywords` | Array/CSV | Comma-separated in comment tags, `%w[]` array in `zen_desc` |
+
+## Custom Tag Prefix
+
+By default, zen_apropos recognizes `# @zen_desc` comment tags. If you want a different prefix for your organization:
+
+### Project setup (recommended)
+
+Run `init` to generate a binstub with your tag pre-configured:
+
+```bash
+bundle exec zen_apropos init --tag myapp
+```
+
+This creates `bin/zen_apropos` in your project. From then on:
+
+```bash
+bin/zen_apropos "employee"        # uses @myapp automatically
+bin/zen_apropos lint               # lints for @myapp tags
+```
+
+### Per-command flag
+
+Pass `--tag` to any command:
+
+```bash
+zen_apropos --tag myapp "employee"
+zen_apropos lint --tag myapp --changed-only
+```
+
+### Ruby configuration
+
+In an initializer or setup file:
+
+```ruby
+ZenApropos.configure do |config|
+  config.tag = 'myapp'
+  config.glob_patterns = ['lib/tasks/**/*.rake', 'packages/**/lib/tasks/**/*.rake']
+end
+```
+
+### Then annotate with your custom tag
+
+```ruby
+# @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.
+
+## Rails Console Integration
+
+You can define an `apropos` helper for quick searching in the Rails console. Example initializer:
+
+```ruby
+# 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:
+
+```ruby
+apropos "employee"
+apropos "team:finance safety:destructive"
+apropos "reindex", plain: true
+apropos  # shows help
+```
+
+## Custom Glob Patterns
+
+By default, zen_apropos scans `lib/tasks/**/*.rake`. For monorepos or apps with tasks in non-standard locations, configure custom patterns:
+
+```ruby
+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:
+
+```ruby
+engine = ZenApropos::Engine.new(
+  glob_patterns: ['lib/tasks/**/*.rake', 'packages/**/lib/tasks/**/*.rake']
+)
+```
+
+## Running Tests
+
+```bash
+bundle exec rake test
+```
+
+Or simply:
+
+```bash
+bundle exec rake
+```
+
+Tests use Minitest and run against fixture rake files in `test/fixtures/`.
+
+## Contributing
+
+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](CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,7 @@
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/**/test_*.rb']
+end
+
+task default: :test

data/bin/zen_apropos

@@ -0,0 +1,181 @@
+#!/usr/bin/env ruby
+# ZenApropos CLI — search rake tasks and lint annotations
+#
+# Usage:
+#   zen_apropos <query> [--plain] [--tag TAG]  Search rake tasks
+#   zen_apropos lint [--changed-only] [--tag TAG]  Check for missing annotations
+#   zen_apropos init [--tag TAG]               Generate a project binstub
+#   zen_apropos --help                         Show help
+
+require 'fileutils'
+require 'zen_apropos'
+
+def extract_tag!(args)
+  index = args.index('--tag')
+  return nil unless index
+
+  args.delete_at(index) # remove --tag
+  args.delete_at(index) # remove the value
+end
+
+def apply_tag!(args)
+  tag = extract_tag!(args)
+  ZenApropos.configure { |c| c.tag = tag } if tag
+end
+
+def run_search(args)
+  apply_tag!(args)
+  plain = args.delete('--plain')
+  query = args.join(' ')
+
+  engine = ZenApropos::Engine.new(root_path: Dir.pwd, plain: plain, glob_patterns: ZenApropos.configuration.glob_patterns)
+
+  if query.empty? || query == '--help' || query == '-h'
+    puts engine.help
+    exit 0
+  end
+
+  output = engine.search(query)
+
+  if output.strip.empty?
+    puts "\n❌ No rake tasks found matching: '#{query}'"
+    puts "\nTry:"
+    puts "  • zen_apropos --help"
+    exit 0
+  end
+
+  puts "\n#{output}\n"
+
+  # Interactive mode (rich mode only)
+  exit 0 if plain
+
+  loop do
+    print "\nEnter a number, new query, or q to quit: "
+    input = $stdin.gets&.strip
+    break if input.nil? || input == 'q' || input.empty?
+
+    if input.match?(/^\d+$/) && engine.last_results&.any?
+      index = input.to_i - 1
+      if index < 0 || index >= engine.last_results.length
+        puts "Invalid number. Enter 1-#{engine.last_results.length}."
+        next
+      end
+
+      entry = engine.last_results[index]
+      puts "\n\e[36m━━━ rake #{entry.name} \e[0m#{'━' * [0, 50 - entry.name.length].max}"
+      puts "  \e[2m#{entry.relative_path}:#{entry.line_number}\e[0m\n\n"
+      puts entry.source
+      puts "\e[36m#{'━' * 58}\e[0m"
+    else
+      output = engine.search(input)
+      if output.strip.empty?
+        puts "\n❌ No rake tasks found matching: '#{input}'"
+      else
+        puts "\n#{output}\n"
+      end
+    end
+  end
+end
+
+def run_lint(args)
+  if args.include?('--help') || args.include?('-h')
+    tag = ZenApropos.configuration.tag
+    puts <<~HELP
+
+      🔍 zen_apropos lint - Rake Task Annotation Linter
+
+      Warns when rake tasks are missing @#{tag} annotations.
+
+      Usage:
+        zen_apropos lint                  # Check all rake files
+        zen_apropos lint --changed-only   # Check only files changed in current branch
+        zen_apropos lint --tag myapp      # Use a custom annotation tag
+
+      Exit codes:
+        0  All tasks have annotations
+        1  Some tasks are missing annotations
+
+    HELP
+    exit 0
+  end
+
+  apply_tag!(args)
+  changed_only = args.include?('--changed-only')
+  exit ZenApropos::Linter.new(changed_only: changed_only).run
+end
+
+def run_init(args)
+  tag = extract_tag!(args) || 'zen'
+  binstub_path = File.join(Dir.pwd, 'bin', 'zen_apropos')
+
+  if File.exist?(binstub_path)
+    puts "#{binstub_path} already exists. Overwrite? [y/N] "
+    answer = $stdin.gets&.strip
+    unless answer&.downcase == 'y'
+      puts 'Aborted.'
+      exit 0
+    end
+  end
+
+  FileUtils.mkdir_p(File.dirname(binstub_path))
+
+  content = <<~RUBY
+    #!/usr/bin/env ruby
+    require 'bundler/setup'
+    require 'zen_apropos'
+
+    ZenApropos.configure do |config|
+      config.tag = '#{tag}'
+    end
+
+    load Gem.bin_path('zen_apropos', 'zen_apropos')
+  RUBY
+
+  File.write(binstub_path, content)
+  File.chmod(0o755, binstub_path)
+
+  puts "Created #{binstub_path} with tag '#{tag}'"
+  puts "Run: bin/zen_apropos <query>"
+end
+
+def show_help
+  puts <<~HELP
+
+    🔍 ZenApropos - Rake Task Search & Lint
+
+    Usage:
+      zen_apropos <query> [--plain] [--tag TAG]  Search rake tasks
+      zen_apropos lint [--changed-only] [--tag TAG]  Check for missing annotations
+      zen_apropos init [--tag TAG]               Generate a project binstub
+      zen_apropos --help                         Show this help
+
+    Search examples:
+      zen_apropos employee
+      zen_apropos "team:finance safety:destructive"
+      zen_apropos reindex --plain
+      zen_apropos --tag myapp employee
+
+    Lint examples:
+      zen_apropos lint
+      zen_apropos lint --changed-only
+      zen_apropos lint --tag myapp
+
+    Setup:
+      zen_apropos init --tag myapp   # creates bin/zen_apropos with tag pre-configured
+
+  HELP
+end
+
+# Route to subcommand
+case ARGV.first
+when 'lint'
+  ARGV.shift
+  run_lint(ARGV)
+when 'init'
+  ARGV.shift
+  run_init(ARGV)
+when '--help', '-h', nil
+  show_help
+else
+  run_search(ARGV.dup)
+end

data/lib/zen_apropos/annotations_parser.rb

@@ -0,0 +1,38 @@
+# Parses annotation comment tags from lines preceding a task definition
+#
+# By default, recognizes # @zen_desc tags. Configure with:
+#   ZenApropos.configure { |c| c.tag = 'myapp' }
+#
+# Supported format:
+#   # @zen_desc team: hr-platform
+#   # @zen_desc safety: caution
+#   # @zen_desc keywords: sync, external, api
+module ZenApropos
+  class AnnotationsParser
+    def initialize(lines)
+      @lines = lines
+    end
+
+    def parse
+      annotations = {}
+
+      @lines.each do |line|
+        next unless ZenApropos.configuration.tag_pattern.match?(line)
+        next unless line =~ /@\w+\s+(\w+):\s*(.+)$/
+
+        key   = Regexp.last_match(1).strip.to_sym
+        value = Regexp.last_match(2).strip
+
+        annotations[key] = key == :keywords ? value.split(/,\s*/) : value
+      end
+
+      annotations
+    end
+
+    class << self
+      def parse(lines)
+        new(lines).parse
+      end
+    end
+  end
+end

data/lib/zen_apropos/configuration.rb

@@ -0,0 +1,14 @@
+module ZenApropos
+  class Configuration
+    attr_accessor :tag, :glob_patterns
+
+    def initialize
+      @tag           = 'zen_desc'
+      @glob_patterns = nil
+    end
+
+    def tag_pattern
+      /^\s*#\s*@#{Regexp.escape(tag)}\s+/
+    end
+  end
+end