carson 2.19.0 → 2.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6b2ecf51c931d6c85244d96e294ce87a86583e3a807782ddd74c9058c647563
-  data.tar.gz: 19b49e67b2bdefe3443aa00500394cc479951eb074498d82b69ff3f776b42b15
+  metadata.gz: 1baa45e25838165768104a260d5641a4f3cfe25fbfe3f7c1d430a9d62dc53cf1
+  data.tar.gz: 99ea0d1c0ba2b332cd10c599ea472f8b2d0b1ca016bfc73ec879f421b32dffae
 SHA512:
-  metadata.gz: acc11f185996f6e424b18bbc55ed6194ae87d31db6de09b9b34fc50237c87ada00ab8c1c3809cf9d0b3654353e24cf1a2fb1b9fd6134610a57ded49d4fbe1a5c
-  data.tar.gz: c27ac61fba18b5cf449a33b8703337282b5a30f0cf87568e24320acd56b030b57093ba8d24466c92450745dc61f0eaa83f2c5db603cd242e0e6b2413233331d0
+  metadata.gz: f746f1fb2d74940e0e5b21d6ab0a9d5857aa78972453202016345214b5b77504792ab490ac5afda8028b1b2b07618d0451c4a996a004ca2e1908c29a3de82c78
+  data.tar.gz: 95ad47ab82a4a617d6fe590c2ead6e15c8b11e36695e0039447158f35c07790fa001997bfc180f56cc441387a32e259af19d0ef02b3d01580d9a449d1ff337ee

data/MANUAL.md

@@ -101,7 +101,7 @@ Notes:
 
 ### Canonical Templates
 
-Carson manages 5 governance files (carson.md, CLAUDE.md, AGENTS.md, copilot-instructions.md, pull_request_template.md). Beyond those, you can tell Carson about your own canonical `.github/` files — CI workflows, linter configs, dependabot settings, anything that belongs in `.github/`.
+Carson manages 5 governance files (carson.md, CLAUDE.md, AGENTS.md, copilot-instructions.md, pull_request_template.md). Beyond those, you can tell Carson about your own canonical `.github/` files — CI workflows, linter configs, labeller rules, anything that belongs in `.github/`.
 
 Set `template.canonical` in `~/.carson/config.json`:
 
@@ -120,7 +120,7 @@ That directory mirrors the `.github/` structure:
 ├── workflows/
 │   └── lint.yml          → deployed to .github/workflows/lint.yml
 ├── .mega-linter.yml      → deployed to .github/.mega-linter.yml
-└── dependabot.yml        → deployed to .github/dependabot.yml
+└── labeler.yml           → deployed to .github/labeler.yml
 ```
 
 Carson discovers files in this directory and syncs them to governed repos alongside its own governance files. `carson template check` detects drift, `carson template apply` writes them, and `carson refresh` propagates them to the remote.

data/RELEASE.md

@@ -5,6 +5,20 @@ Release-note scope rule:
 - `RELEASE.md` records only version deltas, breaking changes, and migration actions.
 - Operational usage guides live in `MANUAL.md` and `API.md`.
 
+## 2.20.0 — Prune Orphan Branches
+
+### What changed
+
+- **`carson prune` now detects orphan branches.** Local branches with no upstream tracking are pruned when GitHub confirms a merged PR matching the exact branch name and tip SHA. Previously, only branches with `[gone]` upstream tracking were detected — branches that were never pushed with `-u` or lost tracking would linger indefinitely.
+- Orphan deletions count towards the same "Pruned N stale branches." total in concise output. Verbose output uses distinct `deleted_orphan_branch:` / `skip_orphan_branch:` log lines.
+- Carson's own `carson/template-sync` branch and protected branches are excluded from orphan detection.
+
+## 2.19.1 — Remove Dependabot References
+
+### What changed
+
+- Replaced all Dependabot example references in documentation and tests with `labeler.yml`. Carson never had a Dependabot feature — these were illustrative filenames for the canonical template system.
+
 ## 2.19.0 — Canonical Templates, Lint Removed
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-2.19.0
+2.20.0

data/lib/carson/runtime/local.rb

@@ -34,35 +34,45 @@ module Carson
 				git_system!( "switch", start_branch ) if switched && branch_exists?( branch_name: start_branch )
 			end
 
-			# Removes stale local branches that track remote refs already deleted upstream.
+			# Removes stale local branches (gone upstream) and orphan branches (no tracking) with merged PR evidence.
 			def prune!
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
 
 				git_system!( "fetch", config.git_remote, "--prune" )
 				active_branch = current_branch
+				counters = { deleted: 0, skipped: 0 }
+
 				stale_branches = stale_local_branches
-				return prune_no_stale_branches if stale_branches.empty?
+				prune_stale_branch_entries( stale_branches: stale_branches, active_branch: active_branch, counters: counters )
+
+				orphan_branches = orphan_local_branches( active_branch: active_branch )
+				prune_orphan_branch_entries( orphan_branches: orphan_branches, counters: counters )
+
+				return prune_no_stale_branches if counters.fetch( :deleted ).zero? && counters.fetch( :skipped ).zero?
 
-				counters = prune_stale_branch_entries( stale_branches: stale_branches, active_branch: active_branch )
 				puts_verbose "prune_summary: deleted=#{counters.fetch( :deleted )} skipped=#{counters.fetch( :skipped )}"
 				unless verbose?
-					puts_line "Pruned #{counters.fetch( :deleted )} stale branch#{plural_suffix( count: counters.fetch( :deleted ) )}."
+					deleted_count = counters.fetch( :deleted )
+					if deleted_count.zero?
+						puts_line "No stale branches."
+					else
+						puts_line "Pruned #{deleted_count} stale branch#{plural_suffix( count: deleted_count )}."
+					end
 				end
 				EXIT_OK
 			end
 
 			def prune_no_stale_branches
 				if verbose?
-					puts_line "OK: no stale local branches tracking deleted #{config.git_remote} branches."
+					puts_line "OK: no stale or orphan branches to prune."
 				else
 					puts_line "No stale branches."
 				end
 				EXIT_OK
 			end
 
-			def prune_stale_branch_entries( stale_branches:, active_branch: )
-				counters = { deleted: 0, skipped: 0 }
+			def prune_stale_branch_entries( stale_branches:, active_branch:, counters: { deleted: 0, skipped: 0 } )
 				stale_branches.each do |entry|
 					outcome = prune_stale_branch_entry( entry: entry, active_branch: active_branch )
 					counters[ outcome ] += 1
@@ -851,10 +861,8 @@ module Carson
 				violations
 			end
 
-			# NOTE: prune only targets local branches that meet both conditions:
-			# 1) branch tracks configured remote (`github/*` by default), and
-			# 2) upstream tracking state is marked as gone after fetch --prune.
-			# Branches without upstream tracking are intentionally excluded.
+			# Detects local branches whose upstream tracking is marked [gone] after fetch --prune.
+			# Branches without upstream tracking are handled separately by orphan_local_branches.
 			def stale_local_branches
 				git_capture!( "for-each-ref", "--format=%(refname:short)\t%(upstream:short)\t%(upstream:track)", "refs/heads" ).lines.map do |line|
 					branch, upstream, track = line.strip.split( "\t", 3 )
@@ -867,6 +875,70 @@ module Carson
 				end.compact
 			end
 
+			# Detects local branches with no upstream tracking ref — candidates for orphan pruning.
+			# Filters out protected branches, the active branch, and Carson's own sync branch.
+			def orphan_local_branches( active_branch: )
+				git_capture!( "for-each-ref", "--format=%(refname:short)\t%(upstream:short)", "refs/heads" ).lines.filter_map do |line|
+					branch, upstream = line.strip.split( "\t", 2 )
+					branch = branch.to_s.strip
+					upstream = upstream.to_s.strip
+					next if branch.empty?
+					next unless upstream.empty?
+					next if config.protected_branches.include?( branch )
+					next if branch == active_branch
+					next if branch == TEMPLATE_SYNC_BRANCH
+
+					branch
+				end
+			end
+
+			# Processes orphan branches: verifies merged PR evidence via GitHub API before deleting.
+			def prune_orphan_branch_entries( orphan_branches:, counters: )
+				return counters if orphan_branches.empty?
+				return counters unless gh_available?
+
+				orphan_branches.each do |branch|
+					outcome = prune_orphan_branch_entry( branch: branch )
+					counters[ outcome ] += 1
+				end
+				counters
+			end
+
+			# Checks a single orphan branch for merged PR evidence and force-deletes if confirmed.
+			def prune_orphan_branch_entry( branch: )
+				tip_sha_text, tip_sha_error, tip_sha_success, = git_run( "rev-parse", "--verify", branch.to_s )
+				unless tip_sha_success
+					error_text = tip_sha_error.to_s.strip
+					error_text = "unable to read local branch tip sha" if error_text.empty?
+					puts_verbose "skip_orphan_branch: #{branch} reason=#{error_text}"
+					return :skipped
+				end
+				branch_tip_sha = tip_sha_text.to_s.strip
+				if branch_tip_sha.empty?
+					puts_verbose "skip_orphan_branch: #{branch} reason=unable to read local branch tip sha"
+					return :skipped
+				end
+
+				merged_pr, error = merged_pr_for_branch( branch: branch, branch_tip_sha: branch_tip_sha )
+				if merged_pr.nil?
+					reason = error.to_s.strip
+					reason = "no merged PR evidence for branch tip into #{config.main_branch}" if reason.empty?
+					puts_verbose "skip_orphan_branch: #{branch} reason=#{reason}"
+					return :skipped
+				end
+
+				force_stdout, force_stderr, force_success, = git_run( "branch", "-D", branch )
+				if force_success
+					out.print force_stdout if verbose? && !force_stdout.empty?
+					puts_verbose "deleted_orphan_branch: #{branch} merged_pr=#{merged_pr.fetch( :url )}"
+					return :deleted
+				end
+
+				force_error_text = normalise_branch_delete_error( error_text: force_stderr )
+				puts_verbose "fail_delete_orphan_branch: #{branch} reason=#{force_error_text}"
+				:skipped
+			end
+
 			# Safe delete can fail after squash merges because branch tip is no longer an ancestor.
 			def non_merged_delete_error?( error_text: )
 				error_text.to_s.downcase.include?( "not fully merged" )

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carson
 version: !ruby/object:Gem::Version
-  version: 2.19.0
+  version: 2.20.0
 platform: ruby
 authors:
 - Hailei Wang