hr_lite 0.1.0

data/lib/hr_lite/configuration.rb

@@ -0,0 +1,60 @@
+module HrLite
+  # All host integration points. Every attribute has a working default so the
+  # engine boots in any Rails app; a real host overrides what it needs in an
+  # initializer. See README for the full annotated example.
+  class Configuration
+    attr_accessor :user_class, :parent_controller, :current_user_method,
+                  :authenticate_method, :admin_check, :display_name_method,
+                  :employees_scope, :mentionable_users, :notify, :render_pdf, :company,
+                  :time_zone, :currency_symbol, :on_designation_change,
+                  :leadership_emails, :leadership_check, :extra_stylesheets,
+                  :mailer_from, :public_url_base, :notification_matrix, :back_link
+
+    # 0.1.0 pre-release name for public_url_base; kept as an alias so early
+    # adopters' initializers don't break.
+    alias_method :mail_link_base, :public_url_base
+    alias_method :mail_link_base=, :public_url_base=
+
+    def initialize
+      @user_class            = "User"
+      @parent_controller     = "ActionController::Base"
+      @current_user_method   = :current_user
+      @authenticate_method   = :authenticate_user!
+      @admin_check           = ->(user) { user.respond_to?(:admin?) && user.admin? }
+      @display_name_method   = :display_name
+      @employees_scope       = -> { HrLite.user_klass.all }
+      @mentionable_users     = ->(query) { HrLite.default_mentionable_users(query) }
+      @notify                = ->(user:, kind:, title:, body:, path:) { }
+      @render_pdf            = nil
+      @company               = -> { { name: "Company", address: nil, logo_path: nil } }
+      @time_zone             = "Asia/Kolkata"
+      @currency_symbol      = "₹"
+      @on_designation_change = ->(user, designation) { }
+      @leadership_emails     = []
+      @leadership_check      = ->(user) do
+        emails = HrLite.config.leadership_emails.map { |e| e.to_s.downcase.strip }
+        emails.include?(user.email.to_s.downcase)
+      end
+      @extra_stylesheets     = [] # host stylesheets linked AFTER hr_lite.css (CSS-var overrides)
+      @mailer_from           = "hr@example.com"
+      @public_url_base       = nil # e.g. "https://hr.example.com" — enables email links + HrLite.public_url
+      @notification_matrix   = nil # resolved lazily to Notifications::DEFAULT_MATRIX
+      @back_link             = nil # optional {label:, url:} for the shell nav
+    end
+  end
+
+  class << self
+    # Default @mention source: name/email prefix match on the host user table.
+    # Uses LOWER(...) LIKE so it works on sqlite and postgres alike; hosts
+    # with pg_trgm or scopes of their own override config.mentionable_users.
+    def default_mentionable_users(query)
+      q = "%#{ActiveRecord::Base.sanitize_sql_like(query.to_s.downcase)}%"
+      klass = user_klass
+      columns = %w[name email].select { |c| klass.column_names.include?(c) }
+      return klass.none if columns.empty?
+
+      where_sql = columns.map { |c| "LOWER(#{klass.table_name}.#{c}) LIKE :q" }.join(" OR ")
+      klass.where(where_sql, q: q).order(:id).limit(8)
+    end
+  end
+end

data/lib/hr_lite/current.rb

@@ -0,0 +1,7 @@
+module HrLite
+  # Request-scoped actor for audit logging. Set by ApplicationController,
+  # readable from any model callback without threading it through.
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :actor
+  end
+end

data/lib/hr_lite/engine.rb

@@ -0,0 +1,39 @@
+module HrLite
+  class Engine < ::Rails::Engine
+    isolate_namespace HrLite
+
+    config.generators do |g|
+      g.test_framework :rspec
+    end
+
+    # Make the engine's plain CSS/JS visible to whichever asset pipeline the
+    # host runs (Propshaft or Sprockets both read config.assets.paths).
+    initializer "hr_lite.assets" do |app|
+      if app.config.respond_to?(:assets)
+        app.config.assets.paths << root.join("app/assets/stylesheets")
+        app.config.assets.paths << root.join("app/assets/javascripts")
+      end
+    end
+
+    # Serve the engine's migrations straight from the gem: `bin/rails
+    # db:migrate` in the host just works, and gem upgrades ship their
+    # migrations automatically — nothing to copy, nothing to drift.
+    #
+    # Skipped when the host already copied them via
+    # `hr_lite:install:migrations` (files named *.hr_lite.rb) — otherwise the
+    # same tables would be created twice under different version stamps.
+    initializer "hr_lite.migrations" do |app|
+      next if app.root.to_s == root.to_s
+      next unless HrLite::Engine.append_migrations?(app)
+
+      config.paths["db/migrate"].expanded.each do |path|
+        app.config.paths["db/migrate"] << path
+      end
+    end
+
+    def self.append_migrations?(app)
+      host_migrate_dirs = app.config.paths["db/migrate"].expanded
+      host_migrate_dirs.none? { |dir| Dir.glob(File.join(dir, "*.hr_lite.rb")).any? }
+    end
+  end
+end

data/lib/hr_lite/geo.rb

@@ -0,0 +1,22 @@
+module HrLite
+  # Pure-Ruby haversine — no geocoding gem needed to answer "how far is
+  # this punch from the office?" at office-radius precision.
+  module Geo
+    EARTH_RADIUS_M = 6_371_000.0
+
+    def self.distance_m(lat1, lng1, lat2, lng2)
+      rlat1 = deg2rad(lat1)
+      rlat2 = deg2rad(lat2)
+      dlat = deg2rad(lat2.to_f - lat1.to_f)
+      dlng = deg2rad(lng2.to_f - lng1.to_f)
+
+      a = Math.sin(dlat / 2)**2 + Math.cos(rlat1) * Math.cos(rlat2) * Math.sin(dlng / 2)**2
+      c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a))
+      EARTH_RADIUS_M * c
+    end
+
+    def self.deg2rad(deg)
+      deg.to_f * Math::PI / 180
+    end
+  end
+end

data/lib/hr_lite/mention_parser.rb

@@ -0,0 +1,18 @@
+module HrLite
+  # Kudos messages carry mentions as visible plain-text markers:
+  #   "Great save @[Asha Rao](42) during the outage"
+  # The picker inserts them; this parser extracts the ids server-side.
+  module MentionParser
+    MARKER = /@\[([^\]\n]{1,80})\]\((\d+)\)/
+    LIMIT = 10 # notification-spam cap
+
+    def self.user_ids(text)
+      text.to_s.scan(MARKER).map { |(_name, id)| id.to_i }.uniq.first(LIMIT)
+    end
+
+    # Bell/email bodies show "@Asha Rao", never the raw marker.
+    def self.strip_markers(text)
+      text.to_s.gsub(MARKER) { "@#{Regexp.last_match(1)}" }
+    end
+  end
+end

data/lib/hr_lite/money.rb

@@ -0,0 +1,33 @@
+module HrLite
+  # Central rounding discipline. Each statutory line rounds by its own rule
+  # exactly once; nets are plain subtraction of already-rounded lines.
+  module Money
+    module_function
+
+    def d(value)
+      return BigDecimal(0) if value.nil?
+
+      value.is_a?(BigDecimal) ? value : BigDecimal(value.to_s)
+    end
+
+    # Nearest rupee, half-up (PF, TDS monthly).
+    def round_rupee(value)
+      d(value).round(0, BigDecimal::ROUND_HALF_UP)
+    end
+
+    # Next rupee (ESIC rounds contributions UP).
+    def ceil_rupee(value)
+      d(value).ceil(0)
+    end
+
+    # Paise precision (earnings proration).
+    def round2(value)
+      d(value).round(2)
+    end
+
+    # Section 288B: annual tax to the nearest ten rupees.
+    def round_to_10(value)
+      (d(value) / 10).round(0, BigDecimal::ROUND_HALF_UP) * 10
+    end
+  end
+end

data/lib/hr_lite/notifications.rb

@@ -0,0 +1,99 @@
+module HrLite
+  # Central event bus. Domain code publishes an event; the per-event channel
+  # row (host-overridable via config.notification_matrix) decides which
+  # channels fire. Channel semantics:
+  #
+  #   bell:             in-app notification (config.notify) to `bell_to` users
+  #   email:            EventMailer to each `email_to` user
+  #   leadership_email: ONE email to every configured leadership address
+  #   leadership_bell:  in-app notification to each leadership user record
+  #
+  # Recipients are computed by the publishing site (it knows the domain);
+  # the matrix is purely the on/off routing table.
+  module Notifications
+    DEFAULT_MATRIX = {
+      "leave.requested"       => { bell: true,  email: false, leadership_email: true,  leadership_bell: true  },
+      "leave.approved"        => { bell: true,  email: true,  leadership_email: true,  leadership_bell: false },
+      "leave.rejected"        => { bell: true,  email: true,  leadership_email: true,  leadership_bell: false },
+      "leave.cancelled"       => { bell: true,  email: false, leadership_email: true,  leadership_bell: false },
+      "attendance.flagged"    => { bell: true,  email: false, leadership_email: false, leadership_bell: false },
+      "attendance.regularized" => { bell: true, email: true,  leadership_email: true,  leadership_bell: false },
+      "payroll.finalized"     => { bell: false, email: false, leadership_email: true,  leadership_bell: true  },
+      "payroll.published"     => { bell: true,  email: true,  leadership_email: true,  leadership_bell: false },
+      "kudos.mentioned"       => { bell: true,  email: true,  leadership_email: false, leadership_bell: false },
+      "appraisal.shared"      => { bell: true,  email: true,  leadership_email: true,  leadership_bell: false },
+      "promotion.recorded"    => { bell: true,  email: true,  leadership_email: true,  leadership_bell: true  },
+      "policy.changed"        => { bell: false, email: false, leadership_email: true,  leadership_bell: true  },
+      "digest.daily"          => { bell: false, email: false, leadership_email: true,  leadership_bell: false }
+    }.freeze
+
+    class << self
+      def matrix
+        HrLite.config.notification_matrix || DEFAULT_MATRIX
+      end
+
+      def publish(event, title:, body: nil, path: nil, bell_to: [], email_to: [], lines: [], diff: nil)
+        row = matrix[event.to_s]
+        unless row
+          Rails.logger.warn("[hr_lite] unknown notification event #{event}")
+          return
+        end
+
+        deliver_bells(event, row, bell_to, title, body, path)
+        deliver_emails(row, email_to, title, body, path, lines)
+        deliver_leadership_email(event, row, title, body, path, lines, diff)
+        deliver_leadership_bells(event, row, bell_to, title, body, path)
+        nil
+      end
+
+      private
+
+      def deliver_bells(event, row, bell_to, title, body, path)
+        return unless row[:bell]
+
+        Array(bell_to).compact.uniq.each do |user|
+          HrLite.notify(user: user, kind: event.to_s, title: title, body: body, path: path)
+        end
+      end
+
+      def deliver_emails(row, email_to, title, body, path, lines)
+        return unless row[:email]
+
+        Array(email_to).compact.uniq.each do |user|
+          next if user.email.blank?
+
+          EventMailer.event(to: user.email, subject: title, heading: title,
+                            body: body, lines: lines, path: path).deliver_later
+        end
+      rescue => e
+        Rails.logger.error("[hr_lite] event email failed: #{e.class}: #{e.message}")
+      end
+
+      def deliver_leadership_email(event, row, title, body, path, lines, diff)
+        return unless row[:leadership_email]
+
+        recipients = HrLite.config.leadership_emails.map { |e| e.to_s.strip }.reject(&:empty?)
+        return if recipients.empty?
+
+        EventMailer.leadership(to: recipients, subject: "[HR] #{title}", heading: title,
+                               body: body, lines: lines, diff: diff, path: path, event: event.to_s)
+                   .deliver_later
+      rescue => e
+        Rails.logger.error("[hr_lite] leadership email failed: #{e.class}: #{e.message}")
+      end
+
+      def deliver_leadership_bells(event, row, bell_to, title, body, path)
+        return unless row[:leadership_bell]
+
+        already = Array(bell_to).compact
+        HrLite.leadership_users.each do |leader|
+          next if already.any? { |u| u.id == leader.id }
+
+          HrLite.notify(user: leader, kind: event.to_s, title: title, body: body, path: path)
+        end
+      rescue => e
+        Rails.logger.error("[hr_lite] leadership bell failed: #{e.class}: #{e.message}")
+      end
+    end
+  end
+end

data/lib/hr_lite/seeds.rb

@@ -0,0 +1,42 @@
+module HrLite
+  # Idempotent reference data. Hosts run it on every deploy
+  # (`rake hr_lite:seed`); re-runs never overwrite operator edits.
+  module Seeds
+    DEFAULT_LEAVE_TYPES = [
+      { code: "CL", name: "Casual leave", color: "#0ea5e9", paid: true, annual_quota: 12, accrual: "monthly", carry_forward_cap: 0, position: 1 },
+      { code: "SL", name: "Sick leave", color: "#f59e0b", paid: true, annual_quota: 6, accrual: "yearly_upfront", carry_forward_cap: 0, position: 2 },
+      { code: "EL", name: "Earned leave", color: "#10b981", paid: true, annual_quota: 15, accrual: "monthly", carry_forward_cap: 30, position: 3 },
+      { code: "LWP", name: "Leave without pay", color: "#6b7280", paid: false, annual_quota: nil, accrual: "yearly_upfront", carry_forward_cap: 0, position: 4 },
+      { code: "CO", name: "Comp off", color: "#8b5cf6", paid: true, annual_quota: 0, accrual: "yearly_upfront", carry_forward_cap: 0, position: 5 }
+    ].freeze
+
+    def self.run!
+      seed_leave_types! + seed_holidays!
+    end
+
+    def self.seed_leave_types!
+      DEFAULT_LEAVE_TYPES.filter_map do |attrs|
+        next if LeaveType.exists?(code: attrs[:code])
+
+        LeaveType.create!(attrs)
+        "leave_type #{attrs[:code]}"
+      end
+    end
+
+    # Only the three fixed-date national holidays — festival dates shift
+    # every year and belong to the admin bulk-paste flow.
+    def self.seed_holidays!
+      year = Date.current.year
+      [
+        [ Date.new(year, 1, 26), "Republic Day" ],
+        [ Date.new(year, 8, 15), "Independence Day" ],
+        [ Date.new(year, 10, 2), "Gandhi Jayanti" ]
+      ].filter_map do |date, name|
+        next if Holiday.exists?(date: date)
+
+        Holiday.create!(date: date, name: name)
+        "holiday #{name} #{year}"
+      end
+    end
+  end
+end

data/lib/hr_lite/statutory_rate_card.rb

@@ -0,0 +1,60 @@
+module HrLite
+  # Config-driven statutory rates, keyed by effective date — a budget change
+  # is a one-hash edit that gets code review and a spec diff, never an
+  # inline-constant hunt.
+  #
+  # VERIFY WITH A CA before the first run of any new financial year; the
+  # FY 2026-27 card ships with FY 2025-26 figures pending confirmation of
+  # the Feb 2026 Finance Act.
+  module StatutoryRateCard
+    def self.r(value) = BigDecimal(value.to_s)
+    private_class_method :r
+
+    CARDS = {
+      Date.new(2025, 4, 1) => {
+        pf: {
+          employee_rate: r("0.12"), employer_rate: r("0.12"), eps_rate: r("0.0833"),
+          wage_ceiling: r("15000"), eps_wage_ceiling: r("15000"),
+          edli_rate: r("0.005"), edli_ceiling: r("15000"), admin_rate: r("0.005")
+        },
+        esi: { employee_rate: r("0.0075"), employer_rate: r("0.0325"), gross_ceiling: r("21000") },
+        pt: {
+          # Neither UP nor Uttarakhand levies professional tax today; both
+          # ship empty (PT = 0). Karnataka included as a worked template.
+          "none" => [],
+          "uttar_pradesh" => [],
+          "uttarakhand" => [],
+          "karnataka" => [ { above: r("24999"), monthly: r("200") } ]
+        },
+        income_tax: {
+          "new" => {
+            standard_deduction: r("75000"), rebate_cap: r("1200000"), cess_rate: r("0.04"),
+            slabs: [
+              [ r("0"), r("400000"), r("0") ],
+              [ r("400000"), r("800000"), r("0.05") ],
+              [ r("800000"), r("1200000"), r("0.10") ],
+              [ r("1200000"), r("1600000"), r("0.15") ],
+              [ r("1600000"), r("2000000"), r("0.20") ],
+              [ r("2000000"), r("2400000"), r("0.25") ],
+              [ r("2400000"), nil, r("0.30") ]
+            ]
+          },
+          "old" => {
+            standard_deduction: r("50000"), rebate_cap: r("500000"), cess_rate: r("0.04"),
+            slabs: [
+              [ r("0"), r("250000"), r("0") ],
+              [ r("250000"), r("500000"), r("0.05") ],
+              [ r("500000"), r("1000000"), r("0.20") ],
+              [ r("1000000"), nil, r("0.30") ]
+            ]
+          }
+        }
+      }
+    }.freeze
+
+    def self.for(period_month)
+      effective = CARDS.keys.sort.reverse.find { |date| date <= period_month }
+      effective ? CARDS[effective] : CARDS[CARDS.keys.min]
+    end
+  end
+end

data/lib/hr_lite/version.rb

@@ -0,0 +1,3 @@
+module HrLite
+  VERSION = "0.1.0"
+end

data/lib/hr_lite.rb

@@ -0,0 +1,104 @@
+require "hr_lite/version"
+require "hr_lite/engine"
+require "hr_lite/configuration"
+require "hr_lite/current"
+require "hr_lite/mention_parser"
+require "hr_lite/notifications"
+require "hr_lite/seeds"
+require "hr_lite/geo"
+require "hr_lite/money"
+require "hr_lite/statutory_rate_card"
+
+module HrLite
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    # Test-only escape hatch: swap the whole configuration object.
+    def config=(configuration)
+      @config = configuration
+    end
+
+    def user_klass
+      config.user_class.constantize
+    end
+
+    def admin?(user)
+      user.present? && !!config.admin_check.call(user)
+    end
+
+    def leadership?(user)
+      user.present? && !!config.leadership_check.call(user)
+    end
+
+    # Leadership members resolvable to actual user records (for bell
+    # notifications). Emails configured but absent from the user table are
+    # still reachable by email — see Notifications.
+    def leadership_users
+      emails = config.leadership_emails.map { |e| e.to_s.downcase.strip }.reject(&:empty?)
+      return user_klass.none if emails.empty?
+
+      user_klass.where("LOWER(#{user_klass.table_name}.email) IN (?)", emails)
+    end
+
+    def admin_users
+      user_klass.all.select { |u| admin?(u) }
+    end
+
+    # Everyone HR tracks (host-overridable to exclude bots/test accounts),
+    # sorted by display name for team screens.
+    def employees
+      config.employees_scope.call.sort_by { |u| display_name(u).downcase }
+    end
+
+    def display_name(user)
+      return "" if user.nil?
+
+      [ config.display_name_method, :display_name, :name, :email ].each do |m|
+        next unless m && user.respond_to?(m)
+        value = user.public_send(m).presence
+        return value if value
+      end
+      "User ##{user.id}"
+    end
+
+    # Absolute public URL for an engine-relative path, from
+    # config.public_url_base. Nil when no base is configured — callers (and
+    # emails) then simply carry no link. Hosts use this to build bell
+    # deep-links and profile links without re-deriving the HR host.
+    def public_url(path = "/")
+      base = config.public_url_base.to_s.chomp("/")
+      return nil if base.empty?
+
+      "#{base}#{path}"
+    end
+
+    # True when the given absolute URL points at the configured public HR
+    # host — the allowlist check for hosts that follow stored notification
+    # links (an open-redirect guard stays intact on their side).
+    def public_url?(candidate)
+      base = public_url
+      return false if base.nil?
+
+      candidate_uri = URI.parse(candidate.to_s)
+      base_uri = URI.parse(base)
+      %w[http https].include?(candidate_uri.scheme) && candidate_uri.host == base_uri.host
+    rescue URI::InvalidURIError
+      false
+    end
+
+    # Host bell hook. Never raises — a notification must not break the
+    # domain action that triggered it.
+    def notify(user:, kind:, title:, body: nil, path: nil)
+      config.notify.call(user: user, kind: kind, title: title, body: body, path: path)
+    rescue => e
+      Rails.logger.error("[hr_lite] notify failed: #{e.class}: #{e.message}")
+      nil
+    end
+  end
+end

data/lib/tasks/hr_lite_tasks.rake

@@ -0,0 +1,8 @@
+namespace :hr_lite do
+  desc "Idempotently seed HR reference data (leave types, national holidays)"
+  task seed: :environment do
+    require "hr_lite/seeds"
+    created = HrLite::Seeds.run!
+    puts created.any? ? "hr_lite:seed created: #{created.join(', ')}" : "hr_lite:seed — nothing to do"
+  end
+end