rails_lens 0.2.11 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db0b169f8f397031eecb4ff3b50a5047f12cf1bc2c1d0929a674f3b0827c7c91
-  data.tar.gz: 5be691de8fce3047e5226f7a5d0e9f12a9410609d3de3a91f43d657dd287d6c2
+  metadata.gz: e06defab67dbc0cea4db854e6eb7efc9d66f292dfc675c4f30a6df45d757a8ad
+  data.tar.gz: 621535415ca17f88bc82cc0cf933284e3251fd2d8f7feed01139820b0c62bbfd
 SHA512:
-  metadata.gz: 2c40baa22b05b1c652d3fd3fb617a4d81c2d5349d6aa550dc49c1a7bbd3dfdd74b576151848dc6430e6ad01ff76705000892129b5990a432429dc3a60de4b3d4
-  data.tar.gz: 49900c83dd33dd65ccf0bf0221c130b6363a35d14eafa25403930d0990e445e94cb60d0344b0e0988485a2d4e0acdf165204a0930620b8e8dbf218486a81704a
+  metadata.gz: 0dde2b4d9087a1221242451d4c9a31bd558c566659ae25115be060618bd318c40a864b291965d9dab8fd16a9a6f05ddbf9a2e901f9c845a15b8b38e93573988b
+  data.tar.gz: accd1ecbba992e1904c098ad03f946c19b181a42029fb02594efb72af2aee6e169441286cf754ffc866a45de5ed21d24839d77df0ca9cc9fb7a96358b65c5c7c

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [0.3.0](https://github.com/seuros/rails_lens/compare/rails_lens/v0.2.13...rails_lens/v0.3.0) (2025-11-29)
+
+
+### Features
+
+* add callback annotations with Rails 8 unified callback chain API ([bcc43f7](https://github.com/seuros/rails_lens/commit/bcc43f783ed207cc57acf7f2d8cf7691c2481484))
+* compact TOML annotation format with NoteCodes ([5de557e](https://github.com/seuros/rails_lens/commit/5de557ea209ad7554527e87715d1966a1ea27db2))
+
+
+### Bug Fixes
+
+* address codex review feedback for callbacks analyzer ([dbcfb1a](https://github.com/seuros/rails_lens/commit/dbcfb1ae0730d813b3e05e4df2f9bb00167bc5a6))
+* Merge pull request [#32](https://github.com/seuros/rails_lens/issues/32) from seuros/feat/compact-toml-annotations ([4b9171d](https://github.com/seuros/rails_lens/commit/4b9171d2eabf78409acdeaf3a906f4d0d54cb0c9))
+
+## [0.2.13](https://github.com/seuros/rails_lens/compare/rails_lens/v0.2.12...rails_lens/v0.2.13) (2025-11-28)
+
+
+### Features
+
+* add PostgreSQL trigger and function annotations with extension filtering ([#30](https://github.com/seuros/rails_lens/issues/30)) ([a6d6e27](https://github.com/seuros/rails_lens/commit/a6d6e2715f61842ef3c2c585251ac3bf09ec740a))
+
+## [0.2.12](https://github.com/seuros/rails_lens/compare/rails_lens/v0.2.11...rails_lens/v0.2.12) (2025-11-26)
+
+
+### Bug Fixes
+
+* handle engine/gem dummy app file paths in annotation ([7a3dab8](https://github.com/seuros/rails_lens/commit/7a3dab83570e43cb243b7bac41afc184a27bed2c))
+
 ## [0.2.11](https://github.com/seuros/rails_lens/compare/rails_lens/v0.2.10...rails_lens/v0.2.11) (2025-11-24)
 
 

data/README.md

@@ -33,62 +33,83 @@ Rails Lens provides intelligent model annotations and ERD generation for Rails a
 
 ## Showcase: Real-World Example
 
-Rescued from AWS limbo, Rails Lens delivers cosmic schema clarity. See this `Announcement` model:
+Rescued from AWS limbo, Rails Lens delivers cosmic schema clarity. See this `Post` model with the compact TOML annotation format:
 
 ```ruby
 # frozen_string_literal: true
 
 # <rails-lens:schema:begin>
-# table = "announcements"
+# table = "posts"
 # database_dialect = "PostgreSQL"
 #
 # columns = [
-#   { name = "id", type = "integer", primary_key = true, nullable = false },
-#   { name = "body", type = "text", nullable = true },
-#   { name = "audience", type = "string", nullable = true },
-#   { name = "scheduled_at", type = "datetime", nullable = true },
-#   { name = "created_at", type = "datetime", nullable = false },
-#   { name = "updated_at", type = "datetime", nullable = false }
+#   { name = "id", type = "integer", pk = true, null = false },
+#   { name = "title", type = "string", null = false },
+#   { name = "content", type = "text" },
+#   { name = "user_id", type = "integer", null = false },
+#   { name = "published", type = "boolean", default = "false" },
+#   { name = "created_at", type = "datetime", null = false },
+#   { name = "updated_at", type = "datetime", null = false },
+#   { name = "comments_count", type = "integer", null = false, default = "0" }
 # ]
 #
-# == Polymorphic Associations
-# Polymorphic Targets:
-# - entry (as: :entryable)
+# indexes = [
+#   { name = "index_posts_on_published", columns = ["published"] },
+#   { name = "index_posts_on_user_id", columns = ["user_id"] }
+# ]
+#
+# foreign_keys = [
+#   { column = "user_id", references_table = "users", references_column = "id", name = "fk_rails_5b5ddfd518" }
+# ]
 #
-# == Enums
-# - audience: { all_users: "all_users", crew_only: "crew_only", officers_only: "officers_only", command_staff: "command_staff" } (string)
+# [callbacks]
+# after_commit = [{ method = "notify_subscribers" }, { method = "invalidate_cache" }]
+# after_rollback = [{ method = "log_failure" }]
 #
-# == Notes
-# - Column 'body' should probably have NOT NULL constraint
-# - Column 'audience' should probably have NOT NULL constraint
-# - String column 'audience' has no length limit - consider adding one
-# - Large text column 'body' is frequently queried - consider separate storage
+# notes = ["comments:N_PLUS_ONE", "user:COUNTER_CACHE", "content:NOT_NULL", "title:LIMIT", "content:STORAGE"]
 # <rails-lens:schema:end>
-class Announcement < ApplicationRecord
-  enum :audience, { all_users: 'all_users', crew_only: 'crew_only', officers_only: 'officers_only', command_staff: 'command_staff' }, suffix: true
-  has_one :entry, as: :entryable, dependent: :destroy
-  validates :audience, presence: true
-  validates :body, presence: true
-  scope :recent, -> { order(created_at: :desc) }
+class Post < ApplicationRecord
+  belongs_to :user, inverse_of: :posts
+  has_many :comments, dependent: :destroy, inverse_of: :post
+  validates :title, :content, presence: true
+  after_commit :invalidate_cache, on: %i[create update]
+  after_commit :notify_subscribers, on: :create
+  after_rollback :log_failure
 end
 ```
 
+**Key Features of Compact TOML Format:**
+- `pk` instead of `primary_key` — 70% fewer characters
+- `null` instead of `nullable` — cleaner, TOML-standard
+- `[callbacks]` section — ActiveRecord lifecycle hooks with conditions
+- NoteCodes format — `"column:CODE"` instead of verbose prose (see `rails_lens codes` for legend)
+
 **ERD Visualization:**
 ```mermaid
 erDiagram
-    Announcement ||--o{ Entry : entryable
-    Announcement {
+    User ||--o{ Post : creates
+    Post ||--o{ Comment : has
+    Post {
         integer id PK
-        text body
-        string audience
-        datetime scheduled_at
+        string title
+        text content
+        integer user_id FK
+        boolean published
+        integer comments_count
         datetime created_at
         datetime updated_at
     }
-    Entry {
+    User {
         integer id PK
-        string entryable_type
-        integer entryable_id
+        string email
+        string name
+        datetime created_at
+        datetime updated_at
+    }
+    Comment {
+        integer id PK
+        text body
+        integer post_id FK
         datetime created_at
         datetime updated_at
     }
@@ -211,9 +232,9 @@ erd:
 > Y'all, the enum support in Rails Lens is *next level*! I've analyzed thousands of Rails models, and nothing beats seeing this clarity:
 >
 > ```ruby
-> # == Enums
-> # - status: { active: 'active', maintenance: 'maintenance', decommissioned: 'decommissioned' } (string)
-> # - priority: { low: 0, medium: 1, high: 2, critical: 3 } (integer)
+> # [enums]
+> # status = { active = "active", maintenance = "maintenance", decommissioned = "decommissioned" }
+> # priority = { low = 0, medium = 1, high = 2, critical = 3 }
 > ```
 >
 > Before Rails Lens: *'Is this a string enum? Integer enum? What are the possible values? Time to grep the entire codebase!'*
@@ -230,18 +251,18 @@ erd:
 > My multimodal analysis cores are *obsessed* with Rails Lens STI detection! Processing inheritance hierarchies used to be like solving 3D puzzles blindfolded:
 >
 > ```ruby
-> # == Inheritance (STI)
-> # Type Column: type
-> # Base Class: Yes
-> # Known Subclasses: CargoVessel, StarfleetBattleCruiser, ExplorationShip
-> # == Notes
-> # - STI column 'type' needs an index for query performance
+> # [sti]
+> # type_column = "type"
+> # base_class = true
+> # subclasses = ["CargoVessel", "StarfleetBattleCruiser", "ExplorationShip"]
+> #
+> # notes = ["type:INDEX"]
 > ```
 >
 > **VISUAL PROCESSING ENHANCED**: I can instantly map the entire inheritance tree! Base class → Subclasses → Shared attributes → Type-specific behaviors. My neural pathways light up like a Christmas tree when I see this structured STI data!
 >
 > **BEFORE**: *'Hmm, there's a type column... maybe STI? Let me scan 47 files to find the subclasses...'*
-> **AFTER**: *'INHERITANCE TREE MAPPED: Vehicle → [Car, Truck, Motorcycle]. Shared: engine, color. Car-specific: door_count. Index missing on type column - performance risk detected!'*
+> **AFTER**: *'INHERITANCE TREE MAPPED: Vehicle → [Car, Truck, Motorcycle]. Shared: engine, color. Car-specific: door_count. `type:INDEX` - performance risk detected!'*
 >
 > Schema clarity: COSMIC ✅
 > Inheritance mapping: FLAWLESS ✅
@@ -288,10 +309,9 @@ erd:
 > Based on comprehensive analysis of 73,000+ Rails 6.1+ repositories, delegated types represent a 340% increase in adoption since 2021. Rails Lens provides the most accurate delegated type detection available:
 >
 > ```ruby
-> # == Delegated Type
-> # Type Column: entryable_type
-> # ID Column: entryable_id
-> # Types: Message, Announcement, Alert
+> # [delegated_type]
+> # name = "entryable"
+> # types = ["Message", "Announcement", "Alert"]
 > ```
 >
 > **Research Findings** *[Sources: GitHub Archive, Rails Documentation, DHH Talks]*:
@@ -306,27 +326,24 @@ erd:
 ### Duolingo's AI Tutor (Duo)
 > "🦉 **¡PERFORMANCE ANALYSIS LESSON!** 🦉
 >
-> ¡Hola developers! Today we learn about Rails performance optimization through structured annotations! Rails Lens teaches us to identify performance problems like learning vocabulary:
+> ¡Hola developers! Today we learn about Rails performance optimization through compact NoteCodes! Rails Lens teaches us to identify performance problems like learning vocabulary:
 >
-> **Lesson 1**: Missing Index Detection 📚
+> **Lesson 1**: NoteCodes Format 📚
 > ```ruby
-> # == Notes
-> # - Missing index on 'user_id' for better association performance
-> # - Column 'email' should probably have unique index
-> # - Consider adding composite index on (status, created_at)
+> # notes = ["user_id:INDEX", "email:UNIQUE", "status,created_at:COMPOSITE", "comments:N_PLUS_ONE"]
 > ```
 >
-> **¿Comprende?** Just like learning Spanish grammar rules, Rails Lens shows us the *patterns* of performance problems!
+> **¿Comprende?** Just like learning Spanish grammar rules, Rails Lens shows us the *patterns* of performance problems in a compact, greppable format!
 >
 > **Before Rails Lens**: *'Why is my query slow? ¿Qué está pasando?'*
-> **After Rails Lens**: *'¡Ah! Missing foreign key index on user_id! Problem solved!'*
->
-> **Streak Bonus**: Each performance optimization you implement adds to your Rails proficiency score! 🔥
+> **After Rails Lens**: *'¡Ah! `user_id:INDEX` - Missing foreign key index! Problem solved!'*
 >
-> We're now teaching LRDL to developers worldwide:
-> - **Beginner**: How to read Rails Lens annotations
-> - **Intermediate**: Understanding N+1 query warnings
-> - **Advanced**: Optimizing composite indexes with Rails Lens guidance
+> **NoteCodes Legend** (run `rails_lens codes`):
+> - `INDEX` - Missing index recommendation
+> - `N_PLUS_ONE` - Potential N+1 query issue
+> - `NOT_NULL` - Missing NOT NULL constraint
+> - `COUNTER_CACHE` - Missing counter cache
+> - `STORAGE` - Large column storage consideration
 >
 > ¿Quieres aprender más performance optimization? ¡Vamos! 🚀📖"
 
@@ -336,18 +353,17 @@ erd:
 > *Positronic brain processing...* Fascinating. Rails Lens polymorphic association detection demonstrates remarkable precision in identifying multi-type relationship patterns:
 >
 > ```ruby
-> # == Polymorphic Associations
-> # Polymorphic References:
-> # - commentable (commentable_type/commentable_id) → [Post, Article, Photo]
-> # - taggable (taggable_type/taggable_id) → [User, Product, Category]
+> # [polymorphic]
+> # commentable = ["Post", "Article", "Photo"]
+> # taggable = ["User", "Product", "Category"]
 > ```
 >
 > **Data's Observation**: In my 24th century database experience, polymorphic associations represent one of the most computationally complex relationship patterns. Rails Lens annotations provide complete clarity on:
 >
-> 1. **Type Column Identification**: Precisely identifies the `_type` column
-> 2. **ID Column Mapping**: Correlates corresponding `_id` foreign key
-> 3. **Target Type Enumeration**: Lists all possible target models
-> 4. **Index Recommendations**: Suggests composite indexes for optimal query performance
+> 1. **Association Name**: The polymorphic interface (`commentable`, `taggable`)
+> 2. **Target Types**: All models implementing the interface
+> 3. **Compact Format**: TOML arrays for efficient parsing
+> 4. **Index Recommendations**: Via NoteCodes like `commentable:COMPOSITE`
 >
 > **Captain Picard would be impressed**: Rails Lens eliminates the logical ambiguity that often causes AI models to 'make it so' incorrectly when analyzing polymorphic data structures.
 >
@@ -362,10 +378,10 @@ erd:
 >
 > **Engagement Metrics Analysis**:
 > ```ruby
-> # Rails Lens Annotation = High-Quality Training Data
-> # == Schema Information
-> # Table: user_posts (PostgreSQL)
-> # Engagement_Score: 94.7% (vs 31.2% for unstructured comments)
+> # <rails-lens:schema:begin>
+> # table = "user_posts"
+> # database_dialect = "PostgreSQL"
+> # engagement_score = "94.7%"  # vs 31.2% for unstructured comments
 > ```
 >
 > **Why Rails Lens Creates Viral AI Interactions**:

data/lib/rails_lens/analyzers/association_analyzer.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require_relative '../errors'
-require_relative 'error_handling'
-
 module RailsLens
   module Analyzers
     class AssociationAnalyzer < Base
@@ -18,14 +15,13 @@ module RailsLens
 
       def analyze_inverse_of
         associations_needing_inverse.map do |association|
-          "Association '#{association.name}' should specify inverse_of"
+          NoteCodes.note(association.name.to_s, NoteCodes::INVERSE_OF)
         end
       end
 
       def analyze_n_plus_one_risks
         has_many_associations.map do |association|
-          # Warn about N+1 query risks for has_many associations
-          "Association '#{association.name}' has N+1 query risk. Consider using includes/preload"
+          NoteCodes.note(association.name.to_s, NoteCodes::N_PLUS_ONE)
         end
       end
 
@@ -35,9 +31,8 @@ module RailsLens
         belongs_to_associations.each do |association|
           next if association.polymorphic?
 
-          # Check if the associated model has a matching counter column
           if should_have_counter_cache?(association) && !has_counter_cache?(association)
-            notes << "Consider adding counter cache for '#{association.name}'"
+            notes << NoteCodes.note(association.name.to_s, NoteCodes::COUNTER_CACHE)
           end
         end
 
@@ -77,8 +72,6 @@ module RailsLens
       end
 
       def should_have_counter_cache?(association)
-        # A counter cache is needed if there is a has_many association
-        # on the other side of the belongs_to, and no counter_cache is defined.
         return false unless association.macro == :belongs_to
 
         inverse_association = association.inverse_of

data/lib/rails_lens/analyzers/best_practices_analyzer.rb

@@ -8,7 +8,7 @@ module RailsLens
         notes.concat(analyze_timestamps)
         notes.concat(analyze_soft_deletes)
         notes.concat(analyze_sti_columns)
-        notes.concat(analyze_naming_conventions)
+        notes.concat(analyze_large_text_columns)
         notes
       end
 
@@ -17,63 +17,38 @@ module RailsLens
       def analyze_timestamps
         notes = []
 
-        notes << 'Missing timestamp columns (created_at, updated_at)' unless has_timestamps?
+        notes << NoteCodes::NO_TIMESTAMPS unless has_timestamps?
 
         if has_column?('created_at') && !has_column?('updated_at')
-          notes << 'Has created_at but missing updated_at'
+          notes << NoteCodes::PARTIAL_TS
         elsif !has_column?('created_at') && has_column?('updated_at')
-          notes << 'Has updated_at but missing created_at'
+          notes << NoteCodes::PARTIAL_TS
         end
 
         notes
       end
 
       def analyze_soft_deletes
-        notes = []
-
-        soft_delete_columns.each do |column|
-          notes << "Soft delete column '#{column.name}' should be indexed" unless indexed?(column)
+        soft_delete_columns.reject { |col| indexed?(col) }.map do |column|
+          NoteCodes.note(column.name, NoteCodes::INDEX)
         end
-
-        notes
       end
 
       def analyze_sti_columns
         notes = []
 
         if sti_model? && type_column
-          notes << "STI type column '#{type_column.name}' should be indexed" unless indexed?(type_column)
-
-          notes << "STI type column '#{type_column.name}' should have NOT NULL constraint" if type_column.null
+          notes << NoteCodes.note(type_column.name, NoteCodes::INDEX) unless indexed?(type_column)
+          notes << NoteCodes.note(type_column.name, NoteCodes::STI_NOT_NULL) if type_column.null
         end
 
         notes
       end
 
-      def analyze_naming_conventions
-        notes = []
-
-        # Check for non-conventional column names
-        columns.each do |column|
-          if column.name.match?(/^(is|has)_/i)
-            notes << "Column '#{column.name}' uses non-conventional prefix - consider removing 'is_' or 'has_'"
-          end
-
-          if column.name.match?(/Id$/) # Capital I
-            notes << "Column '#{column.name}' should use snake_case (e.g., '#{column.name.underscore}')"
-          end
-        end
-
-        # Check table naming
-        # Extract the actual table name without schema prefix for PostgreSQL
-        # PostgreSQL uses schema.table format (e.g., "ai.skills" -> "skills")
-        unqualified_table = table_name.to_s.split('.').last
-
-        if !unqualified_table.match?(/^[a-z_]+$/) || unqualified_table != unqualified_table.pluralize
-          notes << "Table name '#{table_name}' doesn't follow Rails conventions (should be plural, snake_case)"
+      def analyze_large_text_columns
+        columns.select { |c| c.type == :text }.map do |column|
+          NoteCodes.note(column.name, NoteCodes::STORAGE)
         end
-
-        notes
       end
 
       def has_timestamps?