kinship 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f7d5ced07f37ed098f40ef418d6964cbc6b6c91655365720b14150eb80435242
+  data.tar.gz: af7ec88de5e10093501c056b37e6ba1f3e5b7ed861cad54efba00a3c525682ee
+SHA512:
+  metadata.gz: 57573a41df7c60c1c2b83bf0522a6fa21d496c6246c5039983ad6b5ae25d20f801a1eb7e229b5f1de1ffb35f4b9b319e82ded6fd5b801c6613fffd2712573f16
+  data.tar.gz: a33cde8b13290fc2b5a518b1df9160684e839ca31fb636f96fe73dafc310a30b2b0f99e30acccf8fd1541381b040691f3fc876ae301498a0b7db458ddacbdfca

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-01-07
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Kurt Tamulonis
+
+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,233 @@
+# Kinship
+
+**Schema‑inferred relationship graphs for Ruby & Rails**
+
+Kinship discovers relationships between your models **automatically** by inspecting columns like `user_id`, `project_id`, etc. From that single fact, it builds a full graph of your domain — parents, children, families, paths — without `has_many`, `belongs_to`, or configuration.
+
+It exists to solve a very real problem:
+
+> *Rails knows your schema, but not your graph.*
+
+Kinship makes the graph explicit.
+
+---
+
+## Why Kinship exists
+
+Most Rails apps:
+
+* Define associations manually
+* Forget to preload
+* Accidentally ship N+1 queries
+* Duplicate schema knowledge in code
+
+Example of a **very common bad query**:
+
+```ruby
+User.all.each do |user|
+  user.projects.each do |project|
+    project.tasks.each do |task|
+      task.comments.each do |comment|
+        comment.reactions.each do |reaction|
+          reaction.kind
+        end
+      end
+    end
+  end
+end
+```
+
+Rails *allows* this. It fails silently. Performance collapses.
+
+Kinship’s philosophy:
+
+> **If the database already encodes relationships, your application should be able to reason about them automatically.**
+
+---
+
+## What Kinship gives you
+
+From nothing more than foreign keys, Kinship builds:
+
+* `parents(model)` – one layer up
+* `children(model)` – one layer down
+* `families` – connected components
+* `path(from, to)` – shortest relationship path
+* `to_dot` – visual graph output
+
+No macros. No DSL. No annotations.
+
+---
+
+## Installation
+
+### Ruby / Rails
+
+```bash
+gem install kinship
+```
+
+or in your Gemfile:
+
+```ruby
+gem "kinship"
+```
+
+---
+
+## Rails usage (recommended setup)
+
+Create an initializer:
+
+```ruby
+# config/initializers/kinship.rb
+Rails.application.config.after_initialize do
+  Rails.application.eager_load!
+
+  KINSHIP = Kinship.build(
+    models: ApplicationRecord.descendants,
+    attribute_provider: ->(model) { model.column_names }
+  )
+end
+```
+
+That’s it.
+
+Kinship now understands your entire domain graph.
+
+---
+
+## Example domain
+
+Given these tables:
+
+* `users`
+* `projects` (`user_id`)
+* `tasks` (`project_id`)
+* `comments` (`task_id`)
+* `reactions` (`comment_id`)
+
+No associations defined.
+
+---
+
+## Core API
+
+### Parents
+
+```ruby
+KINSHIP.parents(Project)
+# => { user: User }
+```
+
+### Children
+
+```ruby
+KINSHIP.children(Project)
+# => { tasks: Task }
+```
+
+### Families
+
+```ruby
+KINSHIP.families
+# => [[User, Project, Task, Comment, Reaction]]
+```
+
+### Path discovery
+
+```ruby
+KINSHIP.path(User, Reaction)
+# => [User, Project, Task, Comment, Reaction]
+```
+
+This is **the missing abstraction** Rails never gave you.
+
+---
+
+## Graph visualization
+
+```ruby
+puts KINSHIP.to_dot
+```
+
+Output:
+
+```dot
+digraph Kinship {
+  "User";
+  "Project";
+  "Task";
+  "Comment";
+  "Reaction";
+  "User" -> "Project";
+  "Project" -> "Task";
+  "Task" -> "Comment";
+  "Comment" -> "Reaction";
+}
+```
+
+You can render this with Graphviz to **see your data model**.
+
+---
+
+## What Kinship intentionally does *not* do (yet)
+
+* Execute SQL
+* Replace ActiveRecord
+* Magically rewrite queries
+
+Instead, it provides the **missing layer of understanding** required to:
+
+* detect N+1 queries
+* generate preload plans
+* reason about deep filters
+* visualize data flow
+
+Kinship is the **map**, avoiding wrong turns.
+
+---
+
+## Framework integrations
+
+Kinship is framework‑agnostic.
+
+It can be embedded into:
+
+* Rails (today)
+* Jetski (in progress)
+* Custom ORMs
+* Data tooling
+
+Once embedded, *all downstream users benefit* automatically.
+
+---
+
+## Roadmap (vision)
+
+* Declarative query intent
+* Automatic preload inference
+* N+1 detection hooks
+* Query planning helpers
+* Console inspection tools
+
+Kinship is designed to cover **the 80% of relationship problems that cause 95% of performance bugs**.
+
+---
+
+## Philosophy
+
+> Databases already encode relationships.
+>
+> Kinship makes them visible, navigable, and reason‑able.
+
+---
+
+## License
+
+MIT
+
+---
+
+**Built by Kurt Tamulonis**
+

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/lib/kinship/graph.rb

@@ -0,0 +1,145 @@
+module Kinship
+  class Graph
+    attr_reader :models, :parents, :children
+
+    def initialize(models:, attribute_provider:)
+      @models = models
+      @attribute_provider = attribute_provider
+
+      @parents  = Hash.new { |h, k| h[k] = {} }
+      @children = Hash.new { |h, k| h[k] = {} }
+
+      build!
+    end
+
+    def parents(model)
+      @parents[model] || {}
+    end
+
+    def children(model)
+      @children[model] || {}
+    end
+
+    def families
+      visited = {}
+      groups = []
+
+      @models.each do |model|
+        next if visited[model]
+        groups << bfs(model, visited)
+      end
+
+      groups
+    end
+
+    def path(from, to)
+      return [from] if from == to
+
+      queue = [[from]]
+      seen = { from => true }
+
+      until queue.empty?
+        current = queue.shift
+        node = current.last
+
+        neighbors(node).each do |neighbor|
+          next if seen[neighbor]
+
+          path = current + [neighbor]
+          return path if neighbor == to
+
+          seen[neighbor] = true
+          queue << path
+        end
+      end
+
+      nil
+    end
+
+    def to_dot
+      lines = []
+      lines << "digraph Kinship {"
+
+      @models.each do |model|
+        lines << "  \"#{model.name}\";"
+      end
+
+      @parents.each do |child, parents|
+        parents.each_value do |parent|
+          lines << "  \"#{parent.name}\" -> \"#{child.name}\";"
+        end
+      end
+
+      lines << "}"
+      lines.join("\n")
+    end
+
+    private
+
+    def build!
+      lookup = @models.to_h { |m| [simple_name(m), m] }
+
+      @models.each do |child|
+        attributes_for(child).each do |attr|
+          next unless attr.end_with?("_id")
+
+          parent_key = attr.sub(/_id$/, "")
+          parent = lookup[parent_key]
+          next unless parent
+
+          @parents[child][parent_key.to_sym] = parent
+          @children[parent][pluralize(child).to_sym] = child
+        end
+      end
+    end
+
+    def attributes_for(model)
+      attrs =
+        if @attribute_provider.respond_to?(:call)
+          @attribute_provider.call(model)
+        else
+          @attribute_provider[model]
+        end
+
+      raise ArgumentError, "attribute_provider must return Array<String>" unless attrs.is_a?(Array)
+      attrs
+    end
+
+    def neighbors(model)
+      (parents(model).values + children(model).values).uniq
+    end
+
+    def bfs(start, visited)
+      queue = [start]
+      group = []
+      visited[start] = true
+
+      until queue.empty?
+        node = queue.shift
+        group << node
+
+        neighbors(node).each do |n|
+          next if visited[n]
+          visited[n] = true
+          queue << n
+        end
+      end
+
+      group
+    end
+
+    def simple_name(model)
+      model.name
+       .split("::")
+       .last
+       .gsub(/([a-z0-9])([A-Z])/, '\1_\2')
+       .downcase
+    end
+
+    def pluralize(model)
+      n = simple_name(model)
+      n.end_with?("s") ? n : "#{n}s"
+    end
+  end
+end
+

data/lib/kinship/version.rb

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

data/lib/kinship.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "kinship/version"
+require_relative "kinship/graph"
+
+module Kinship
+  def self.build(models:, attribute_provider:)
+    Graph.new(models: models, attribute_provider: attribute_provider)
+  end
+end
+

data/sig/kinship.rbs

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

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: kinship
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- hackliteracy
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-01-09 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Kinship is a schema-inferred relationship graph for Ruby applications.
+  It automatically discovers parent/child relationships between models
+  by inspecting attributes (e.g. user_id, post_id) and builds a complete
+  in-memory graph with zero configuration.
+
+  Kinship enables deep relationship traversal, automatic join planning,
+  and eliminates common N+1 query patterns without requiring has_many or
+  belongs_to declarations. It is framework-agnostic and works with Rails,
+  Jetski, and custom ORMs.
+email:
+- hackliteracy@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/kinship.rb
+- lib/kinship/graph.rb
+- lib/kinship/version.rb
+- sig/kinship.rbs
+homepage: https://github.com/ktamulonis/kinship
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ktamulonis/kinship
+  source_code_uri: https://github.com/ktamulonis/kinship
+  changelog_uri: https://github.com/ktamulonis/kinship/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Schema-inferred relationship graphs for Ruby applications
+test_files: []