carson 2.26.0 → 2.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9a6bf9aa88547c46e4d2138f5da872e38684d10056d948ce7d97124173b37ac
-  data.tar.gz: 285255f7661b92a7943d92b0b421858064980b9cfdfa39c1eb643c40590948e6
+  metadata.gz: 7117079168b4f8472a4324f954bc087122e0ded0d253252b73702c41d3996283
+  data.tar.gz: 21484878bcafe5799dfd87a18c223b5982d6b2ff1ab988c78f929de9cd642bdd
 SHA512:
-  metadata.gz: 10b6caadf5c171c80052bab4f02c124b52d4f5808f3381ceca0735755e411bf3704654c7f130fe386557f0c31034036630d4df8ce1da571f00fce6c2e91bf0e5
-  data.tar.gz: c7f53dfd624afef9d54dd6df6b2eb2f6e8ccefe59f5d092692335c75a2a5854ab8d2d8fc5c178815816746a74196691fff8105f5b3cc5f594ca6017db2938c92
+  metadata.gz: bb4b347d7ace09997a93b40fc7ec179baf4eb8aee75a620e3511d4ac7b9c46545380f7157ac442807e09cc1a679e8709a62df1a237a41618501688162f99c511
+  data.tar.gz: 91aaf60433a82548170eb66eef14ce90c0eb730a3a56e06f7c154449d2355ca50f9a1e282d1b26e372c34b1df2946cb804587854875c14d1ffec3da5d6658bff

data/RELEASE.md

@@ -5,6 +5,45 @@ 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.28.0 — Non-Interactive CLI Flags for Setup
+
+### What changed
+
+- **`carson setup` now accepts optional CLI flags** to configure settings without interactive prompts:
+  - `--remote NAME` sets `git.remote`
+  - `--main-branch NAME` sets `git.main_branch`
+  - `--workflow STYLE` sets `workflow.style` (branch or trunk)
+  - `--merge METHOD` sets `govern.merge.method` (squash, rebase, or merge)
+  - `--canonical PATH` sets `template.canonical`
+- When any flag is present, interactive prompts are skipped and only the specified values are written.
+- When no flags are present, existing behaviour is preserved (interactive in TTY, silent detection in non-TTY).
+
+### Why
+
+Running `carson setup` in non-TTY environments (CI pipelines, agent scripts) previously required manually editing `config.json`. CLI flags allow fully automated configuration without file manipulation.
+
+### Migration
+
+No action required. Existing behaviour is unchanged when no flags are provided.
+
+## 2.27.0 — Absorbed Branch Pruning
+
+### What changed
+
+- **`carson prune` now detects and removes absorbed branches.** An absorbed branch is one whose upstream still exists but whose content is already on main — every file the branch changed has identical content on main. This catches branches whose work landed via a different PR, cherry-pick, or independent re-implementation.
+- Detection uses a two-step evidence check: (1) find the merge-base, (2) compare only the files the branch changed. If all are identical on main, the branch is absorbed.
+- Fast path: branches that are strict ancestors of main (fully merged via fast-forward) are also detected.
+- Safety: absorbed branches are only deleted when no open PR exists. If `gh` is unavailable, absorbed detection is skipped entirely.
+- Both local and remote branches are cleaned up.
+
+### Why
+
+Carson already pruned stale branches (upstream deleted) and orphan branches (no tracking, merged PR evidence). But branches whose remote still existed and had tracking were invisible to prune — even when their content had already landed on main through other means. This gap left repositories cluttered with dead branches that required manual investigation to clean up.
+
+### Migration
+
+No action required. `carson prune` gains the new detection automatically.
+
 ## 2.26.0 — Baseline Check No Longer Blocks Commits
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-2.26.0
+2.28.0

data/lib/carson/cli.rb

@@ -53,7 +53,7 @@ module Carson
 
 		def self.build_parser
 			OptionParser.new do |opts|
-				opts.banner = "Usage: carson [setup|audit|sync|prune|onboard [repo_path]|refresh [--all|repo_path]|offboard [repo_path]|template check|template apply|review gate|review sweep|govern [--dry-run] [--json] [--loop SECONDS]|version]"
+				opts.banner = "Usage: carson [setup [--remote NAME] [--main-branch NAME] [--workflow STYLE] [--merge METHOD] [--canonical PATH]|audit|sync|prune|onboard [repo_path]|refresh [--all|repo_path]|offboard [repo_path]|template check|template apply|review gate|review sweep|govern [--dry-run] [--json] [--loop SECONDS]|version]"
 			end
 		end
 
@@ -74,6 +74,8 @@ module Carson
 			when "version"
 				parser.parse!( argv )
 				{ command: "version" }
+			when "setup"
+				parse_setup_command( argv: argv, parser: parser, err: err )
 			when "onboard", "offboard"
 				parse_repo_path_command( command: command, argv: argv, parser: parser, err: err )
 			when "refresh"
@@ -90,6 +92,28 @@ module Carson
 			end
 		end
 
+		def self.parse_setup_command( argv:, parser:, err: )
+			options = {}
+			setup_parser = OptionParser.new do |opts|
+				opts.banner = "Usage: carson setup [--remote NAME] [--main-branch NAME] [--workflow STYLE] [--merge METHOD] [--canonical PATH]"
+				opts.on( "--remote NAME", "Git remote name" ) { |v| options[ "git.remote" ] = v }
+				opts.on( "--main-branch NAME", "Main branch name" ) { |v| options[ "git.main_branch" ] = v }
+				opts.on( "--workflow STYLE", "Workflow style (branch or trunk)" ) { |v| options[ "workflow.style" ] = v }
+				opts.on( "--merge METHOD", "Merge method (squash, rebase, or merge)" ) { |v| options[ "govern.merge.method" ] = v }
+				opts.on( "--canonical PATH", "Canonical template directory path" ) { |v| options[ "template.canonical" ] = v }
+			end
+			setup_parser.parse!( argv )
+			unless argv.empty?
+				err.puts "#{BADGE} Unexpected arguments for setup: #{argv.join( ' ' )}"
+				err.puts setup_parser
+				return { command: :invalid }
+			end
+			{ command: "setup", cli_choices: options }
+		rescue OptionParser::ParseError => e
+			err.puts "#{BADGE} #{e.message}"
+			{ command: :invalid }
+		end
+
 		def self.parse_repo_path_command( command:, argv:, parser:, err: )
 			parser.parse!( argv )
 			if argv.length > 1
@@ -209,7 +233,7 @@ module Carson
 
 			case command
 			when "setup"
-				runtime.setup!
+				runtime.setup!( cli_choices: parsed.fetch( :cli_choices, {} ) )
 			when "audit"
 				runtime.audit!
 			when "sync"

data/lib/carson/runtime/local/prune.rb

@@ -1,7 +1,8 @@
 module Carson
 	class Runtime
 		module Local
-			# Removes stale local branches (gone upstream) and orphan branches (no tracking) with merged PR evidence.
+			# Removes stale local branches (gone upstream), orphan branches (no tracking) with merged PR evidence,
+			# and absorbed branches (content already on main, no open PR).
 			def prune!
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
@@ -16,6 +17,9 @@ module Carson
 				orphan_branches = orphan_local_branches( active_branch: active_branch )
 				prune_orphan_branch_entries( orphan_branches: orphan_branches, counters: counters )
 
+				absorbed_branches = absorbed_local_branches( active_branch: active_branch )
+				prune_absorbed_branch_entries( absorbed_branches: absorbed_branches, counters: counters )
+
 				return prune_no_stale_branches if counters.fetch( :deleted ).zero? && counters.fetch( :skipped ).zero?
 
 				puts_verbose "prune_summary: deleted=#{counters.fetch( :deleted )} skipped=#{counters.fetch( :skipped )}"
@@ -147,6 +151,107 @@ module Carson
 				end
 			end
 
+			# Detects local branches whose upstream still exists but whose content is already on main.
+			# Two-step evidence: (1) find the merge-base, (2) verify every file the branch changed
+			# relative to the merge-base has identical content on main.
+			def absorbed_local_branches( active_branch: )
+				git_capture!( "for-each-ref", "--format=%(refname:short)\t%(upstream:short)\t%(upstream:track)", "refs/heads" ).lines.filter_map do |line|
+					branch, upstream, track = line.strip.split( "\t", 3 )
+					branch = branch.to_s.strip
+					upstream = upstream.to_s.strip
+					track = track.to_s
+					next if branch.empty?
+					next if upstream.empty?
+					next if track.include?( "gone" )
+					next if config.protected_branches.include?( branch )
+					next if branch == active_branch
+					next if branch == TEMPLATE_SYNC_BRANCH
+
+					next unless branch_absorbed_into_main?( branch: branch )
+
+					{ branch: branch, upstream: upstream }
+				end
+			end
+
+			# Returns true when the branch has no unique content relative to main.
+			def branch_absorbed_into_main?( branch: )
+				# Fast path: branch is a strict ancestor of main (fully merged).
+				_, _, is_ancestor, = git_run( "merge-base", "--is-ancestor", branch, config.main_branch )
+				return true if is_ancestor
+
+				# Find the merge-base between main and the branch.
+				merge_base_text, _, mb_success, = git_run( "merge-base", config.main_branch, branch )
+				return false unless mb_success
+
+				merge_base = merge_base_text.to_s.strip
+				return false if merge_base.empty?
+
+				# List every file the branch changed relative to the merge-base.
+				changed_text, _, changed_success, = git_run( "diff", "--name-only", merge_base, branch )
+				return false unless changed_success
+
+				changed_files = changed_text.to_s.strip.lines.map( &:strip ).reject( &:empty? )
+				return true if changed_files.empty?
+
+				# Compare only those files between branch tip and main tip.
+				# If identical, every branch change is already on main.
+				_, _, identical, = git_run( "diff", "--quiet", branch, config.main_branch, "--", *changed_files )
+				identical
+			end
+
+			# Processes absorbed branches: verifies no open PR exists before deleting local and remote.
+			def prune_absorbed_branch_entries( absorbed_branches:, counters: )
+				return counters if absorbed_branches.empty?
+				return counters unless gh_available?
+
+				absorbed_branches.each do |entry|
+					outcome = prune_absorbed_branch_entry( branch: entry.fetch( :branch ), upstream: entry.fetch( :upstream ) )
+					counters[ outcome ] += 1
+				end
+				counters
+			end
+
+			# Checks a single absorbed branch for open PRs and deletes local + remote if safe.
+			def prune_absorbed_branch_entry( branch:, upstream: )
+				if branch_has_open_pr?( branch: branch )
+					puts_verbose "skip_absorbed_branch: #{branch} reason=open PR exists"
+					return :skipped
+				end
+
+				force_stdout, force_stderr, force_success, = git_run( "branch", "-D", branch )
+				unless force_success
+					error_text = normalise_branch_delete_error( error_text: force_stderr )
+					puts_verbose "fail_delete_absorbed_branch: #{branch} reason=#{error_text}"
+					return :skipped
+				end
+
+				out.print force_stdout if verbose? && !force_stdout.empty?
+
+				remote_branch = upstream.sub( "#{config.git_remote}/", "" )
+				git_run( "push", config.git_remote, "--delete", remote_branch )
+
+				puts_verbose "deleted_absorbed_branch: #{branch} (upstream=#{upstream})"
+				:deleted
+			end
+
+			# Returns true if the branch has at least one open PR.
+			def branch_has_open_pr?( branch: )
+				owner, repo = repository_coordinates
+				stdout_text, _, success, = gh_run(
+					"api", "repos/#{owner}/#{repo}/pulls",
+					"--method", "GET",
+					"-f", "state=open",
+					"-f", "head=#{owner}:#{branch}",
+					"-f", "per_page=1"
+				)
+				return true unless success
+
+				results = Array( JSON.parse( stdout_text ) )
+				!results.empty?
+			rescue StandardError
+				true
+			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?

data/lib/carson/runtime/setup.rb

@@ -6,13 +6,17 @@ module Carson
 		module Setup
 			WELL_KNOWN_REMOTES = %w[origin github upstream].freeze
 
-			def setup!
+			def setup!( cli_choices: {} )
 				puts_verbose ""
 				puts_verbose "[Setup]"
 
 				unless inside_git_work_tree?
 					puts_line "WARN: not a git repository. Skipping remote and branch detection."
-					return write_setup_config( choices: {} )
+					return write_setup_config( choices: cli_choices )
+				end
+
+				unless cli_choices.empty?
+					return write_setup_config( choices: cli_choices )
 				end
 
 				if self.in.respond_to?( :tty? ) && self.in.tty?

metadata

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