+ <% if @plan.current_content.present? %>
+
+
+
-
- <%= render_markdown(@plan.current_content) %>
+
+ <%= render_markdown(@plan.current_content) %>
-
- <%= render partial: "coplan/comment_threads/new_comment_form", locals: { plan: @plan } %>
+
+ <% @threads.select(&:anchored?).each do |thread| %>
+ <%= render partial: "coplan/comment_threads/thread_popover", locals: { thread: thread, plan: @plan, current_user: current_user } %>
+ <% end %>
+
-
-
- <% @threads.select(&:anchored?).each do |thread| %>
- <%= render partial: "coplan/comment_threads/thread_popover", locals: { thread: thread, plan: @plan, current_user: current_user } %>
- <% end %>
+ <% else %>
+
+
This plan has no content yet.
-
- <% else %>
-
-
This plan has no content yet.
-
- <% end %>
+ <% end %>
+
+
+
+ <%= render partial: "coplan/plans/references", locals: { references: @references, plan: @plan } %>
+
<% open_count = @threads.count(&:open?) %>
diff --git a/engine/config/routes.rb b/engine/config/routes.rb
index ae6fb3e..be03e39 100644
--- a/engine/config/routes.rb
+++ b/engine/config/routes.rb
@@ -3,6 +3,7 @@
patch :update_status, on: :member
patch :toggle_checkbox, on: :member
resources :versions, controller: "plan_versions", only: [:index, :show]
+ resources :references, controller: "references", only: [:create, :destroy]
resources :automated_reviews, only: [:create]
resources :comment_threads, only: [:create] do
member do
@@ -39,6 +40,10 @@
patch :resolve, on: :member
patch :discard, on: :member
end
+ resources :references, only: [:index, :create, :destroy]
+ end
+ resources :references, only: [] do
+ get :search, on: :collection
end
end
end
diff --git a/engine/db/migrate/20260410000000_create_coplan_references.rb b/engine/db/migrate/20260410000000_create_coplan_references.rb
new file mode 100644
index 0000000..6497a35
--- /dev/null
+++ b/engine/db/migrate/20260410000000_create_coplan_references.rb
@@ -0,0 +1,21 @@
+class CreateCoplanReferences < ActiveRecord::Migration[8.1]
+ def change
+ create_table :coplan_references, id: { type: :string, limit: 36 } do |t|
+ t.string :plan_id, limit: 36, null: false
+ t.string :key
+ t.string :url, null: false
+ t.string :title
+ t.string :reference_type, null: false
+ t.string :source, null: false
+ t.string :target_plan_id, limit: 36
+ t.timestamps
+ end
+
+ add_index :coplan_references, [:plan_id, :key], unique: true
+ add_index :coplan_references, [:plan_id, :url], unique: true
+ add_index :coplan_references, :target_plan_id
+ add_index :coplan_references, :source
+ add_foreign_key :coplan_references, :coplan_plans, column: :plan_id
+ add_foreign_key :coplan_references, :coplan_plans, column: :target_plan_id
+ end
+end
diff --git a/spec/factories/references.rb b/spec/factories/references.rb
new file mode 100644
index 0000000..e29b9b4
--- /dev/null
+++ b/spec/factories/references.rb
@@ -0,0 +1,13 @@
+FactoryBot.define do
+ factory :reference, class: "CoPlan::Reference" do
+ plan
+ sequence(:url) { |n| "https://example.com/page-#{n}" }
+ title { "Example Reference" }
+ reference_type { "link" }
+ source { "extracted" }
+
+ trait :extracted do
+ source { "extracted" }
+ end
+ end
+end
diff --git a/spec/models/coplan/plan_version_references_spec.rb b/spec/models/coplan/plan_version_references_spec.rb
new file mode 100644
index 0000000..cb4325a
--- /dev/null
+++ b/spec/models/coplan/plan_version_references_spec.rb
@@ -0,0 +1,19 @@
+require "rails_helper"
+
+RSpec.describe "PlanVersion reference extraction", type: :model do
+ let(:user) { create(:coplan_user) }
+ let(:plan) { create(:plan, created_by_user: user) }
+
+ it "extracts references when a new version is created" do
+ CoPlan::PlanVersion.create!(
+ plan: plan,
+ revision: plan.current_revision + 1,
+ content_markdown: "See [Rails](https://rubyonrails.org) for details.",
+ actor_type: "human",
+ actor_id: user.id
+ )
+
+ expect(plan.references.count).to eq(1)
+ expect(plan.references.first.url).to eq("https://rubyonrails.org")
+ end
+end
diff --git a/spec/models/coplan/reference_spec.rb b/spec/models/coplan/reference_spec.rb
new file mode 100644
index 0000000..41e2d7c
--- /dev/null
+++ b/spec/models/coplan/reference_spec.rb
@@ -0,0 +1,110 @@
+require "rails_helper"
+
+RSpec.describe CoPlan::Reference, type: :model do
+ describe "validations" do
+ let(:plan) { create(:plan) }
+
+ it "requires url" do
+ ref = build(:reference, plan: plan, url: nil)
+ expect(ref).not_to be_valid
+ expect(ref.errors[:url]).to include("can't be blank")
+ end
+
+ it "requires reference_type" do
+ ref = build(:reference, plan: plan, reference_type: nil)
+ expect(ref).not_to be_valid
+ end
+
+ it "requires source" do
+ ref = build(:reference, plan: plan, source: nil)
+ expect(ref).not_to be_valid
+ end
+
+ it "validates reference_type inclusion" do
+ ref = build(:reference, plan: plan, reference_type: "invalid")
+ expect(ref).not_to be_valid
+ end
+
+ it "validates source inclusion" do
+ ref = build(:reference, plan: plan, source: "invalid")
+ expect(ref).not_to be_valid
+ end
+
+ it "enforces uniqueness of url per plan" do
+ create(:reference, plan: plan, url: "https://example.com")
+ ref = build(:reference, plan: plan, url: "https://example.com")
+ expect(ref).not_to be_valid
+ end
+
+ it "allows same url on different plans" do
+ other_plan = create(:plan)
+ create(:reference, plan: plan, url: "https://example.com")
+ ref = build(:reference, plan: other_plan, url: "https://example.com")
+ expect(ref).to be_valid
+ end
+ end
+
+ describe ".classify_url" do
+ it "classifies GitHub PR URLs" do
+ expect(described_class.classify_url("https://github.com/org/repo/pull/123")).to eq("pull_request")
+ end
+
+ it "classifies GitHub repo URLs" do
+ expect(described_class.classify_url("https://github.com/org/repo")).to eq("repository")
+ expect(described_class.classify_url("https://github.com/org/repo/")).to eq("repository")
+ expect(described_class.classify_url("https://github.com/org/repo/tree/main")).to eq("repository")
+ expect(described_class.classify_url("https://github.com/org/repo/blob/main/file.rb")).to eq("repository")
+ end
+
+ it "classifies CoPlan plan URLs" do
+ expect(described_class.classify_url("https://coplan.example.com/plans/019d54a7-ea13-72d5-bc54-fc44cb9b939a")).to eq("plan")
+ end
+
+ it "classifies Google Docs URLs" do
+ expect(described_class.classify_url("https://docs.google.com/document/d/abc123")).to eq("document")
+ expect(described_class.classify_url("https://drive.google.com/file/d/abc123")).to eq("document")
+ end
+
+ it "classifies Notion URLs" do
+ expect(described_class.classify_url("https://www.notion.so/page-abc123")).to eq("document")
+ expect(described_class.classify_url("https://team.notion.site/page-abc123")).to eq("document")
+ end
+
+ it "classifies Confluence URLs" do
+ expect(described_class.classify_url("https://wiki.confluence.example.com/display/TEAM/Page")).to eq("document")
+ end
+
+ it "defaults to link for unknown URLs" do
+ expect(described_class.classify_url("https://example.com/something")).to eq("link")
+ end
+ end
+
+ describe ".extract_target_plan_id" do
+ it "extracts UUID from plan URLs" do
+ url = "https://coplan.example.com/plans/019d54a7-ea13-72d5-bc54-fc44cb9b939a"
+ expect(described_class.extract_target_plan_id(url)).to eq("019d54a7-ea13-72d5-bc54-fc44cb9b939a")
+ end
+
+ it "returns nil for non-plan URLs" do
+ expect(described_class.extract_target_plan_id("https://example.com")).to be_nil
+ end
+ end
+
+ describe "scopes" do
+ let(:plan) { create(:plan) }
+
+ it ".extracted returns only extracted references" do
+ extracted = create(:reference, :extracted, plan: plan, url: "https://a.com")
+ create(:reference, plan: plan, url: "https://b.com", source: "explicit")
+
+ expect(described_class.extracted).to eq([extracted])
+ end
+
+ it ".explicit returns only explicit references" do
+ create(:reference, :extracted, plan: plan, url: "https://a.com")
+ explicit = create(:reference, plan: plan, url: "https://b.com", source: "explicit")
+
+ expect(described_class.explicit).to eq([explicit])
+ end
+ end
+end
diff --git a/spec/requests/api/v1/references_spec.rb b/spec/requests/api/v1/references_spec.rb
new file mode 100644
index 0000000..0ea51d3
--- /dev/null
+++ b/spec/requests/api/v1/references_spec.rb
@@ -0,0 +1,102 @@
+require "rails_helper"
+
+RSpec.describe "Api::V1::References", type: :request do
+ let(:user) { create(:coplan_user) }
+ let(:token) { create(:api_token, user: user, raw_token: "test-token-refs") }
+ let(:headers) { { "Authorization" => "Bearer test-token-refs", "Content-Type" => "application/json" } }
+ let(:plan) { create(:plan, :considering, created_by_user: user) }
+
+ before { token }
+
+ describe "GET /api/v1/plans/:plan_id/references" do
+ it "lists references for a plan" do
+ create(:reference, plan: plan, url: "https://github.com/org/repo", reference_type: "repository")
+ create(:reference, plan: plan, url: "https://example.com", reference_type: "link")
+
+ get api_v1_plan_references_path(plan), headers: headers
+ expect(response).to have_http_status(:ok)
+
+ data = JSON.parse(response.body)
+ expect(data.length).to eq(2)
+ expect(data.first).to include("url", "reference_type", "source")
+ end
+
+ it "filters by type" do
+ create(:reference, plan: plan, url: "https://github.com/org/repo", reference_type: "repository")
+ create(:reference, plan: plan, url: "https://example.com", reference_type: "link")
+
+ get api_v1_plan_references_path(plan), params: { type: "repository" }, headers: headers
+ data = JSON.parse(response.body)
+ expect(data.length).to eq(1)
+ expect(data.first["reference_type"]).to eq("repository")
+ end
+ end
+
+ describe "POST /api/v1/plans/:plan_id/references" do
+ it "creates an explicit reference" do
+ post api_v1_plan_references_path(plan),
+ params: { url: "https://github.com/org/repo", title: "My Repo" }.to_json,
+ headers: headers
+
+ expect(response).to have_http_status(:created)
+ data = JSON.parse(response.body)
+ expect(data["url"]).to eq("https://github.com/org/repo")
+ expect(data["reference_type"]).to eq("repository")
+ expect(data["source"]).to eq("explicit")
+ expect(data["title"]).to eq("My Repo")
+ end
+
+ it "auto-classifies URL type" do
+ post api_v1_plan_references_path(plan),
+ params: { url: "https://github.com/org/repo/pull/42" }.to_json,
+ headers: headers
+
+ data = JSON.parse(response.body)
+ expect(data["reference_type"]).to eq("pull_request")
+ end
+ end
+
+ describe "DELETE /api/v1/plans/:plan_id/references/:id" do
+ it "deletes a reference" do
+ ref = create(:reference, plan: plan, url: "https://example.com")
+
+ delete api_v1_plan_reference_path(plan, ref), headers: headers
+ expect(response).to have_http_status(:no_content)
+ expect(plan.references.count).to eq(0)
+ end
+
+ it "returns not found for unknown reference" do
+ delete api_v1_plan_reference_path(plan, "nonexistent-id"), headers: headers
+ expect(response).to have_http_status(:not_found)
+ end
+ end
+
+ describe "GET /api/v1/references/search" do
+ it "finds plans by reference URL" do
+ create(:reference, plan: plan, url: "https://github.com/org/repo")
+
+ get search_api_v1_references_path, params: { url: "https://github.com/org/repo" }, headers: headers
+ expect(response).to have_http_status(:ok)
+
+ data = JSON.parse(response.body)
+ expect(data.length).to eq(1)
+ expect(data.first["plan_id"]).to eq(plan.id)
+ expect(data.first["plan_title"]).to eq(plan.title)
+ end
+
+ it "requires url parameter" do
+ get search_api_v1_references_path, headers: headers
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+
+ it "excludes brainstorm plans from other users" do
+ other_user = create(:coplan_user)
+ brainstorm_plan = create(:plan, :brainstorm, created_by_user: other_user)
+ create(:reference, plan: brainstorm_plan, url: "https://github.com/org/repo")
+
+ get search_api_v1_references_path, params: { url: "https://github.com/org/repo" }, headers: headers
+ data = JSON.parse(response.body)
+ expect(data.length).to eq(0)
+ end
+ end
+end
diff --git a/spec/services/coplan/references/extract_from_content_spec.rb b/spec/services/coplan/references/extract_from_content_spec.rb
new file mode 100644
index 0000000..d06c99b
--- /dev/null
+++ b/spec/services/coplan/references/extract_from_content_spec.rb
@@ -0,0 +1,120 @@
+require "rails_helper"
+
+RSpec.describe CoPlan::References::ExtractFromContent do
+ let(:user) { create(:coplan_user) }
+ let(:plan) { create(:plan, created_by_user: user) }
+
+ def update_content(plan, content)
+ version = plan.current_plan_version
+ version.update!(content_markdown: content)
+ end
+
+ describe ".call" do
+ it "extracts markdown links from content" do
+ update_content(plan, "Check out [Rails](https://rubyonrails.org) for details.")
+ described_class.call(plan: plan)
+
+ expect(plan.references.count).to eq(1)
+ ref = plan.references.first
+ expect(ref.url).to eq("https://rubyonrails.org")
+ expect(ref.title).to eq("Rails")
+ expect(ref.reference_type).to eq("link")
+ expect(ref.source).to eq("extracted")
+ end
+
+ it "classifies GitHub repo URLs" do
+ update_content(plan, "See [repo](https://github.com/org/my-repo) for code.")
+ described_class.call(plan: plan)
+
+ ref = plan.references.first
+ expect(ref.reference_type).to eq("repository")
+ end
+
+ it "classifies GitHub PR URLs" do
+ update_content(plan, "See [PR](https://github.com/org/repo/pull/123) for changes.")
+ described_class.call(plan: plan)
+
+ ref = plan.references.first
+ expect(ref.reference_type).to eq("pull_request")
+ end
+
+ it "classifies Google Docs URLs" do
+ update_content(plan, "See [doc](https://docs.google.com/document/d/abc123) for details.")
+ described_class.call(plan: plan)
+
+ ref = plan.references.first
+ expect(ref.reference_type).to eq("document")
+ end
+
+ it "removes extracted references when links are removed from content" do
+ update_content(plan, "See [Rails](https://rubyonrails.org) and [Ruby](https://ruby-lang.org).")
+ described_class.call(plan: plan)
+ expect(plan.references.count).to eq(2)
+
+ update_content(plan, "See [Rails](https://rubyonrails.org) only.")
+ described_class.call(plan: plan)
+ expect(plan.references.count).to eq(1)
+ expect(plan.references.first.url).to eq("https://rubyonrails.org")
+ end
+
+ it "does not remove explicit references" do
+ create(:reference, plan: plan, url: "https://example.com", source: "explicit")
+ update_content(plan, "No links here.")
+ described_class.call(plan: plan)
+
+ refs = plan.references.reload
+ expect(refs.count).to eq(1)
+ expect(refs.first.source).to eq("explicit")
+ end
+
+ it "does not overwrite explicit references with extracted ones" do
+ create(:reference, plan: plan, url: "https://rubyonrails.org", source: "explicit", title: "My Title")
+ update_content(plan, "See [Rails](https://rubyonrails.org).")
+ described_class.call(plan: plan)
+
+ ref = plan.references.find_by(url: "https://rubyonrails.org")
+ expect(ref.source).to eq("explicit")
+ expect(ref.title).to eq("My Title")
+ end
+
+ it "is idempotent" do
+ update_content(plan, "See [Rails](https://rubyonrails.org).")
+ described_class.call(plan: plan)
+ described_class.call(plan: plan)
+
+ expect(plan.references.count).to eq(1)
+ end
+
+ it "handles empty content" do
+ plan.current_plan_version.update_column(:content_markdown, "")
+ described_class.call(plan: plan)
+ expect(plan.references.count).to eq(0)
+ end
+
+ it "sets target_plan_id for plan references" do
+ target_plan = create(:plan, created_by_user: user)
+ update_content(plan, "See [other plan](https://coplan.example.com/plans/#{target_plan.id}).")
+ described_class.call(plan: plan)
+
+ ref = plan.references.first
+ expect(ref.reference_type).to eq("plan")
+ expect(ref.target_plan_id).to eq(target_plan.id)
+ end
+
+ it "does not set target_plan_id for self-references" do
+ update_content(plan, "See [this plan](https://coplan.example.com/plans/#{plan.id}).")
+ described_class.call(plan: plan)
+
+ ref = plan.references.first
+ expect(ref.target_plan_id).to be_nil
+ end
+
+ it "extracts bare URLs" do
+ update_content(plan, "Visit https://example.com for more info.")
+ described_class.call(plan: plan)
+
+ expect(plan.references.count).to eq(1)
+ expect(plan.references.first.url).to eq("https://example.com")
+ end
+ end
+end
diff --git a/spec/system/references_spec.rb b/spec/system/references_spec.rb
new file mode 100644
index 0000000..97e5a2a
--- /dev/null
+++ b/spec/system/references_spec.rb
@@ -0,0 +1,144 @@
+require "rails_helper"
+
+RSpec.describe "Plan references", type: :system do
+ let(:user) { create(:coplan_user, email: "refuser@example.com") }
+ let(:plan) do
+ p = CoPlan::Plan.create!(title: "Test Plan", created_by_user: user)
+ version = CoPlan::PlanVersion.create!(
+ plan: p, revision: 1,
+ content_markdown: "# Hello\n\nSome content here.",
+ actor_type: "human", actor_id: user.id
+ )
+ p.update!(current_plan_version: version, current_revision: 1)
+ p
+ end
+
+ before do
+ visit sign_in_path
+ fill_in "Email address", with: user.email
+ click_button "Sign In"
+ expect(page).to have_current_path(root_path)
+ end
+
+ describe "Stimulus tab switching" do
+ it "toggles panel visibility and updates URL via replaceState" do
+ visit plan_path(plan)
+
+ # Content visible, references hidden (display:none)
+ expect(page).to have_content("Some content here")
+ expect(page).not_to have_content("No references yet")
+
+ click_link "References"
+
+ # JS toggles the hidden class — no page reload
+ expect(page).to have_content("No references yet")
+ expect(page).not_to have_content("Some content here")
+
+ # Stimulus controller pushes ?tab=references via replaceState
+ uri = URI.parse(current_url)
+ expect(Rack::Utils.parse_query(uri.query)).to include("tab" => "references")
+
+ click_link "Content"
+
+ # Tab param removed for default tab
+ uri = URI.parse(current_url)
+ expect(uri.query.to_s).not_to include("tab=")
+
+ # Content restored
+ expect(page).to have_content("Some content here")
+ expect(page).not_to have_content("No references yet")
+ end
+ end
+
+ describe "adding references via Turbo Stream" do
+ it "appends reference to the DOM without navigating away from the tab" do
+ visit plan_path(plan, tab: "references")
+
+ # Open the
form
+ find("summary", text: "+ Add Reference").click
+ expect(page).to have_css("details[open]")
+
+ fill_in "reference[url]", with: "https://github.com/org/repo"
+ fill_in "reference[title]", with: "My Repo"
+ fill_in "reference[key]", with: "my-repo"
+ click_button "Add"
+
+ # Turbo Stream replaces the list — reference appears without navigation
+ expect(page).to have_link("My Repo", href: "https://github.com/org/repo")
+ expect(page).not_to have_content("No references yet")
+
+ # Count span updated in-place via Turbo Stream (separate stream target)
+ expect(page).to have_css("#references-count", text: "1")
+
+ # Still on references tab — Turbo Stream didn't cause a Turbo visit
+ # (content tab remains hidden, references tab content is visible)
+ expect(page).not_to have_content("Some content here")
+ expect(page).to have_content("My Repo")
+ end
+
+ it "supports sequential adds with form re-expansion" do
+ visit plan_path(plan, tab: "references")
+
+ find("summary", text: "+ Add Reference").click
+ fill_in "reference[url]", with: "https://github.com/org/repo"
+ fill_in "reference[title]", with: "Repo One"
+ click_button "Add"
+ expect(page).to have_content("Repo One")
+ expect(page).to have_css("#references-count", text: "1")
+
+ # After Turbo Stream replaces the partial, is collapsed;
+ # user must be able to re-expand and add another
+ find("summary", text: "+ Add Reference").click
+ fill_in "reference[url]", with: "https://github.com/org/other"
+ fill_in "reference[title]", with: "Repo Two"
+ click_button "Add"
+
+ expect(page).to have_content("Repo One")
+ expect(page).to have_content("Repo Two")
+ expect(page).to have_css("#references-count", text: "2")
+ end
+ end
+
+ describe "removing references via Turbo Stream" do
+ it "removes reference from DOM with confirm dialog" do
+ create(:reference, plan: plan, url: "https://example.com", title: "Doomed", source: "explicit")
+
+ visit plan_path(plan, tab: "references")
+ expect(page).to have_content("Doomed")
+ expect(page).to have_css("#references-count", text: "1")
+
+ # data-turbo-confirm triggers a browser confirm dialog
+ accept_confirm("Remove this reference?") do
+ click_button "✕"
+ end
+
+ # Turbo Stream removes the reference and updates count
+ expect(page).not_to have_content("Doomed")
+ expect(page).to have_css("#references-count", text: "0")
+ expect(page).to have_content("No references yet")
+ end
+ end
+
+ describe "tab count updates across tab switches" do
+ it "updates the references count badge visible in the tab nav" do
+ visit plan_path(plan)
+
+ # Count starts at 0
+ expect(page).to have_css("#references-count", text: "0")
+
+ # Switch to references, add one
+ click_link "References"
+ find("summary", text: "+ Add Reference").click
+ fill_in "reference[url]", with: "https://github.com/org/repo"
+ fill_in "reference[title]", with: "My Repo"
+ click_button "Add"
+
+ # Count updated via Turbo Stream — visible even in the tab nav
+ expect(page).to have_css("#references-count", text: "1")
+
+ # Switch back to content — count persists (it's outside the panels)
+ click_link "Content"
+ expect(page).to have_css("#references-count", text: "1")
+ end
+ end
+end