woods 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab164a85b76d9c97fc6142836da5349a444e9c62f507622fb327f5cc8f434ed4
-  data.tar.gz: 66752a95ddb4183a6f78d47417690242cfc3ad2bdfc622b8740fe2fbc388658e
+  metadata.gz: ec72d151147ef4b43df866b6ebee48f52a26915efdb44df7bed08c24646cfb7a
+  data.tar.gz: f03a813c3f525eeba7a95269770ee80ee4c4fd91017561529800745a241cfd9c
 SHA512:
-  metadata.gz: 2d53024eefb62544ba536f23b1c9f36bebab988fc75223ef72e1d2ffd1d2ed0b46b2507781b040726b8059d14c9f6eefa3faa1c4d6b0a4b6c5019905ef41675d
-  data.tar.gz: 8d5c7a1e7ab4c7b401e61140a9ec5bea06848244d08192f05b0cc088a93980b3208cf3f22a0319545857051dc0b2a234f4d4c2ef8a5789ef108080f179aa6f99
+  metadata.gz: 75608caf708f2f4ef913653af543e983ac68abb9ab0028f9e967bda13af4e5b0c47f73a1d440696b453fb08afc69ab56cf2d70d366aa29949676e29abb6cdc85
+  data.tar.gz: a0f0e086045967cee236f4d98bd6131e5ca8c99daf7a150aa395c60dc56665bb3f4cc5a615d101480c1f8da752fd38a35893662ebf4cda02f49f008aeb6bc081

data/README.md

@@ -65,6 +65,40 @@ Woods boots your Rails app, introspects everything using runtime APIs, and write
 
 Your `User` model includes `Auditable`, `Searchable`, and `SoftDeletable`. An AI tool reading `app/models/user.rb` sees 40 lines. Woods inlines all three concerns directly into the extracted unit — the AI sees the full 200-line behavioral surface area in one block.
 
+```ruby
+# What your AI sees (app/models/user.rb) — 4 lines:
+class User < ApplicationRecord
+  include Auditable
+  include Searchable
+end
+
+# What Woods produces — full source with schema + inlined concerns:
+# == Schema Information
+# email    :string           not null
+# name     :string
+#
+# class User < ApplicationRecord
+#   include Auditable
+#   include Searchable
+#   validates :email, presence: true, uniqueness: true
+#   ...
+# end
+#
+# ┌─────────────────────────────────────────────────────────────────────┐
+# │ Included from: Auditable                                            │
+# └─────────────────────────────────────────────────────────────────────┘
+#   def audit_trail ...
+# ─────────────────────────── End Auditable ───────────────────────────
+#
+# ┌─────────────────────────────────────────────────────────────────────┐
+# │ Included from: Searchable                                           │
+# └─────────────────────────────────────────────────────────────────────┘
+#   scope :search, ->(q) { where("name ILIKE ?", "%#{q}%") }
+# ─────────────────────────── End Searchable ───────────────────────────
+```
+
+The `metadata[:inlined_concerns]` array lists which concerns were resolved, so retrieval can filter by concern inclusion.
+
 ### Schema Prepending
 
 Model source gets a header with actual column types, indexes, and foreign keys pulled from the live database. No more guessing whether `name` is a `string` or `text`, or whether there's an index on `email`.
@@ -83,6 +117,122 @@ Controller source gets a route map prepended showing the real HTTP verb + path +
 
 ---
 
+## Examples
+
+### Extracted Model with Schema and Associations
+
+After extraction, each model is a self-contained JSON file with schema, associations, validations, and inlined concern source:
+
+```json
+{
+  "type": "model",
+  "identifier": "Order",
+  "file_path": "app/models/order.rb",
+  "source_code": "# == Schema Information\n# id         :bigint  not null, pk\n# user_id    :bigint  not null, fk\n# status     :string  default(\"pending\")\n# total_cents :integer\n#\nclass Order < ApplicationRecord\n  belongs_to :user\n  has_many :line_items\n  validates :status, inclusion: { in: %w[pending paid shipped] }\n  ...\nend\n\n# ┌───────────────────────────────────────────────────────────────────┐\n# │ Included from: Auditable                                          │\n# └───────────────────────────────────────────────────────────────────┘\n#   module Auditable\n#     ...\n#   end\n# ──────────────────────── End Auditable ────────────────────────────",
+  "metadata": {
+    "associations": [
+      { "type": "belongs_to", "name": "user", "target": "User" },
+      { "type": "has_many", "name": "line_items", "target": "LineItem" }
+    ],
+    "validations": [
+      { "attribute": "status", "type": "inclusion", "options": { "in": ["pending", "paid", "shipped"] } }
+    ],
+    "enums": { "status": { "pending": 0, "active": 1, "shipped": 2 } },
+    "scopes": [{ "name": "active", "source": "-> { where(status: :active) }" }],
+    "inlined_concerns": ["Auditable"]
+  },
+  "dependencies": [
+    { "type": "model", "target": "User", "via": "belongs_to" },
+    { "type": "model", "target": "LineItem", "via": "has_many" }
+  ]
+}
+```
+
+### Callback Chain with Side-Effects
+
+Woods resolves the full callback chain in execution order and detects side-effects — which columns get written, which jobs get enqueued, which mailers fire:
+
+```json
+"callbacks": [
+  { "type": "before_validation", "filter": "normalize_email", "kind": "before", "conditions": {} },
+  { "type": "before_save", "filter": "set_slug", "kind": "before", "conditions": {},
+    "side_effects": { "columns_written": ["slug"], "jobs_enqueued": [], "services_called": [], "mailers_triggered": [], "database_reads": [], "operations": [] } },
+  { "type": "after_commit", "filter": "send_welcome", "kind": "after", "conditions": {},
+    "side_effects": { "columns_written": [], "jobs_enqueued": ["WelcomeEmailJob"], "services_called": [], "mailers_triggered": ["UserMailer"], "database_reads": [], "operations": [] } }
+]
+```
+
+Side-effects are detected by `CallbackAnalyzer`, which scans callback method bodies for patterns like `self.col =` (column writes), `perform_later` (job enqueues), and `deliver_later` (mailer triggers). This is the #1 thing AI tools get wrong about Rails models.
+
+### Route-to-Controller Lookup
+
+Every route becomes its own `ExtractedUnit` with the controller and action bound from the live routing table:
+
+```json
+{
+  "type": "route",
+  "identifier": "POST /checkout",
+  "metadata": {
+    "controller": "orders",
+    "action": "create",
+    "route_name": "checkout"
+  }
+}
+```
+
+To find which controller handles a URL, use the MCP `search` tool:
+
+```json
+{ "tool": "search", "params": { "query": "/checkout", "types": ["route"] } }
+```
+
+This returns all matching route units with their controller and action — no guessing about custom routes, nested resources, or engine mount points.
+
+### Looking Up a Model's Full Structure
+
+Use the MCP `lookup` tool to get a model's complete JSON representation — schema, associations, validations, callbacks, and inlined concerns in one call:
+
+```json
+{ "tool": "lookup", "params": { "identifier": "Order", "include_source": true } }
+```
+
+Returns the full `ExtractedUnit` JSON shown in the example above, including `source_code` (with schema header and inlined concerns), `metadata` (associations, callbacks, validations, enums, scopes), `dependencies`, and `dependents`.
+
+To get just the structured metadata without source code:
+
+```json
+{ "tool": "lookup", "params": { "identifier": "Order", "include_source": false, "sections": ["metadata"] } }
+```
+
+### Finding Jobs Enqueued by a Service
+
+Use the MCP `dependencies` tool to trace what a service triggers:
+
+```json
+{ "tool": "dependencies", "params": { "identifier": "CheckoutService", "depth": 2, "types": ["job"] } }
+```
+
+Returns all job units reachable from `CheckoutService` within 2 hops — including jobs triggered indirectly via model callbacks (e.g., `CheckoutService` → `Order` → `OrderConfirmationJob`).
+
+### Runtime-Generated Method Detection
+
+Because Woods runs inside the booted Rails process, it captures every method Rails generates dynamically — enum predicates, association builders, attribute accessors, and scope methods that static analysis tools cannot see:
+
+```json
+{
+  "identifier": "Order",
+  "metadata": {
+    "enums": { "status": { "pending": 0, "active": 1, "shipped": 2 } },
+    "scopes": [{ "name": "active", "source": "-> { where(status: :active) }" }],
+    "associations": [{ "type": "has_many", "name": "line_items", "target": "LineItem" }]
+  }
+}
+```
+
+Static tools miss `status_active?`, `status_pending?`, `build_line_item`, `create_line_item!`, and dynamically registered scopes. Woods captures all of these because it queries the runtime class via `instance_methods(false)` after Rails has processed every DSL declaration.
+
+---
+
 ## Connect to Your AI Tool
 
 Woods ships two MCP servers. Most users only need the **Index Server**.
@@ -223,6 +373,26 @@ Woods is backend-agnostic. Your app database, vector store, embedding provider,
 
 See [Backend Matrix](docs/BACKEND_MATRIX.md) for supported combinations and [Configuration Reference](docs/CONFIGURATION_REFERENCE.md) for every option with defaults.
 
+### Environment-Specific Configuration
+
+```ruby
+Woods.configure do |config|
+  config.output_dir = Rails.root.join('tmp/woods')
+
+  # CI: only extract models and controllers for faster builds
+  config.extractors = %i[models controllers] if ENV['CI']
+
+  # Environment-conditional embedding provider
+  if ENV['OPENAI_API_KEY']
+    config.embedding_provider = :openai
+    config.embedding_options = { api_key: ENV['OPENAI_API_KEY'] }
+  else
+    config.embedding_provider = :ollama
+    config.embedding_options = { base_url: 'http://localhost:11434' }
+  end
+end
+```
+
 ---
 
 ## Keeping the Index Current
@@ -289,12 +459,15 @@ Everything flows through `ExtractedUnit` — the universal data structure. Each
 |-------|-----------------|
 | `identifier` | Class name or descriptive key (`"User"`, `"POST /orders"`) |
 | `type` | Category (`:model`, `:controller`, `:service`, `:job`, etc.) |
+| `file_path` | Source file location relative to Rails root |
+| `namespace` | Module namespace (`"Admin"`, `nil` for top-level) |
 | `source_code` | Annotated source with inlined concerns and schema |
 | `metadata` | Structured data — associations, callbacks, routes, fields |
 | `dependencies` | What this unit depends on (forward edges) |
 | `dependents` | What depends on this unit (reverse edges) |
 | `chunks` | Semantic sub-sections for large units |
-| `estimated_tokens` | Token count for LLM context budgeting |
+| `extracted_at` | ISO 8601 timestamp of extraction |
+| `source_hash` | SHA-256 digest for change detection |
 
 ### Output Structure
 
@@ -323,7 +496,7 @@ tmp/woods/
 │                                                                  │
 │  ┌────────────┐    ┌─────────────┐    ┌──────────────────────┐  │
 │  │  Extract   │───>│   Resolve   │───>│   Write JSON         │  │
-│  │ 34 types   │    │   graph +   │    │   per unit           │  │
+│  │ 33 types   │    │   graph +   │    │   per unit           │  │
 │  │            │    │   git data  │    │                      │  │
 │  └────────────┘    └─────────────┘    └──────────────────────┘  │
 └──────────────────────────────────────────────────────────────────┘

data/exe/woods-console-mcp

@@ -17,6 +17,10 @@ require_relative '../lib/woods/console/server'
 config_path = ENV.fetch('WOODS_CONSOLE_CONFIG', File.expand_path('~/.woods/console.yml'))
 config = File.exist?(config_path) ? YAML.safe_load_file(config_path) : {}
 
+# Suppress json-schema MultiJSON deprecation notice that would pollute stderr
+# during MCP stdio transport. The notice fires when multi_json is in the bundle.
+JSON::Validator.use_multi_json = false if defined?(JSON::Validator) && JSON::Validator.respond_to?(:use_multi_json=)
+
 server = Woods::Console::Server.build(config: config)
 transport = MCP::Server::Transports::StdioTransport.new(server)
 transport.open

data/exe/woods-mcp

@@ -19,6 +19,10 @@ require_relative '../lib/woods/mcp/bootstrapper'
 require_relative '../lib/woods/embedding/text_preparer'
 require_relative '../lib/woods/embedding/indexer'
 
+# Suppress json-schema MultiJSON deprecation notice that would pollute stderr
+# during MCP stdio transport. The notice fires when multi_json is in the bundle.
+JSON::Validator.use_multi_json = false if defined?(JSON::Validator) && JSON::Validator.respond_to?(:use_multi_json=)
+
 index_dir = Woods::MCP::Bootstrapper.resolve_index_dir(ARGV)
 retriever = Woods::MCP::Bootstrapper.build_retriever
 snapshot_store = Woods::MCP::Bootstrapper.build_snapshot_store(index_dir)

data/lib/woods/extractors/model_extractor.rb

@@ -327,6 +327,9 @@ module Woods
           callbacks: extract_callbacks(model),
           scopes: extract_scopes(model, source),
           enums: extract_enums(model),
+          inlined_concerns: extract_included_modules(model)
+                            .select { |mod| mod.name && concern_source(mod) }
+                            .map { |mod| mod.name.demodulize },
 
           # API surface
           class_methods: model.methods(false).sort,
@@ -611,7 +614,7 @@ module Woods
       def extract_dependencies(model, source = nil)
         # Associations point to other models
         deps = model.reflect_on_all_associations.filter_map do |assoc|
-          { type: :model, target: assoc.class_name, via: :association }
+          { type: :model, target: assoc.class_name, via: assoc.macro }
         rescue NameError => e
           @warnings << "[#{model.name}] Skipping broken association dep #{assoc.name}: #{e.message}"
           nil

data/lib/woods/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Woods
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: woods
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Leah Armstrong
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-13 00:00:00.000000000 Z
+date: 2026-03-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mcp