carson 3.22.0 → 3.23.0

data/lib/carson/delivery.rb

@@ -0,0 +1,64 @@
+# Passive ledger record for one branch-to-authority delivery attempt.
+module Carson
+	class Delivery
+		ACTIVE_STATES = %w[preparing gated queued integrating escalated].freeze
+		BLOCKED_STATES = %w[gated escalated].freeze
+		READY_STATES = %w[queued].freeze
+		TERMINAL_STATES = %w[integrated failed superseded].freeze
+
+		attr_reader :id, :repository, :branch, :head, :worktree_path, :authority, :status,
+			:pull_request_number, :pull_request_url, :revision_count, :cause, :summary,
+			:created_at, :updated_at, :integrated_at, :superseded_at
+
+		def initialize(
+			id:, repository:, branch:, head:, worktree_path:, authority:, status:,
+			pull_request_number:, pull_request_url:, revision_count:, cause:, summary:,
+			created_at:, updated_at:, integrated_at:, superseded_at:
+		)
+			@id = id
+			@repository = repository
+			@branch = branch
+			@head = head
+			@worktree_path = worktree_path
+			@authority = authority
+			@status = status
+			@pull_request_number = pull_request_number
+			@pull_request_url = pull_request_url
+			@revision_count = revision_count
+			@cause = cause
+			@summary = summary
+			@created_at = created_at
+			@updated_at = updated_at
+			@integrated_at = integrated_at
+			@superseded_at = superseded_at
+		end
+
+		def active?
+			ACTIVE_STATES.include?( status )
+		end
+
+		def blocked?
+			BLOCKED_STATES.include?( status )
+		end
+
+		def ready?
+			READY_STATES.include?( status )
+		end
+
+		def integrated?
+			status == "integrated"
+		end
+
+		def failed?
+			status == "failed"
+		end
+
+		def superseded?
+			status == "superseded"
+		end
+
+		def terminal?
+			TERMINAL_STATES.include?( status )
+		end
+	end
+end

data/lib/carson/ledger.rb

@@ -0,0 +1,305 @@
+# SQLite-backed ledger for Carson's deliveries and revisions.
+require "fileutils"
+require "sqlite3"
+require "time"
+
+module Carson
+	class Ledger
+		UNSET = Object.new
+		ACTIVE_DELIVERY_STATES = %w[preparing gated queued integrating escalated].freeze
+
+		def initialize( path: )
+			@path = File.expand_path( path )
+			prepare!
+		end
+
+		attr_reader :path
+
+		# Ensures the SQLite schema exists before Carson uses the ledger.
+		def prepare!
+			FileUtils.mkdir_p( File.dirname( path ) )
+
+			with_database do |database|
+				database.execute_batch( <<~SQL )
+					CREATE TABLE IF NOT EXISTS deliveries (
+						id INTEGER PRIMARY KEY AUTOINCREMENT,
+						repo_path TEXT NOT NULL,
+						branch_name TEXT NOT NULL,
+						head TEXT NOT NULL,
+						worktree_path TEXT,
+						authority TEXT NOT NULL,
+						status TEXT NOT NULL,
+						pr_number INTEGER,
+						pr_url TEXT,
+						revision_count INTEGER NOT NULL DEFAULT 0,
+						cause TEXT,
+						summary TEXT,
+						created_at TEXT NOT NULL,
+						updated_at TEXT NOT NULL,
+						integrated_at TEXT,
+						superseded_at TEXT
+					);
+
+					CREATE UNIQUE INDEX IF NOT EXISTS index_deliveries_on_identity
+						ON deliveries ( repo_path, branch_name, head );
+
+					CREATE INDEX IF NOT EXISTS index_deliveries_on_state
+						ON deliveries ( repo_path, status, created_at );
+
+					CREATE TABLE IF NOT EXISTS revisions (
+						id INTEGER PRIMARY KEY AUTOINCREMENT,
+						delivery_id INTEGER NOT NULL,
+						number INTEGER NOT NULL,
+						cause TEXT NOT NULL,
+						provider TEXT NOT NULL,
+						status TEXT NOT NULL,
+						started_at TEXT NOT NULL,
+						finished_at TEXT,
+						summary TEXT,
+						FOREIGN KEY ( delivery_id ) REFERENCES deliveries ( id )
+					);
+
+					CREATE UNIQUE INDEX IF NOT EXISTS index_revisions_on_delivery_number
+						ON revisions ( delivery_id, number );
+				SQL
+			end
+		end
+
+		# Creates or refreshes a delivery for the same branch head.
+		def upsert_delivery( repository:, branch_name:, head:, worktree_path:, authority:, pr_number:, pr_url:, status:, summary:, cause: )
+			timestamp = now_utc
+
+			with_database do |database|
+				row = database.get_first_row(
+					"SELECT * FROM deliveries WHERE repo_path = ? AND branch_name = ? AND head = ? LIMIT 1",
+					[ repository.path, branch_name, head ]
+				)
+
+					if row
+						database.execute(
+							<<~SQL,
+							UPDATE deliveries
+							SET worktree_path = ?, authority = ?, status = ?, pr_number = ?, pr_url = ?,
+							cause = ?, summary = ?, updated_at = ?
+							WHERE id = ?
+							SQL
+							[ worktree_path, authority, status, pr_number, pr_url, cause, summary, timestamp, row.fetch( "id" ) ]
+						)
+					return fetch_delivery( database: database, id: row.fetch( "id" ), repository: repository )
+				end
+
+				supersede_branch!( database: database, repository: repository, branch_name: branch_name, timestamp: timestamp )
+				database.execute(
+					<<~SQL,
+						INSERT INTO deliveries (
+							repo_path, branch_name, head, worktree_path, authority, status,
+							pr_number, pr_url, revision_count, cause, summary, created_at, updated_at
+						) VALUES ( ?, ?, ?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ? )
+					SQL
+					[
+						repository.path, branch_name, head, worktree_path, authority, status,
+						pr_number, pr_url, cause, summary, timestamp, timestamp
+					]
+				)
+				fetch_delivery( database: database, id: database.last_insert_row_id, repository: repository )
+			end
+		end
+
+		# Looks up the active delivery for a branch, if one exists.
+		def active_delivery( repo_path:, branch_name: )
+			with_database do |database|
+				row = database.get_first_row(
+					<<~SQL,
+					SELECT * FROM deliveries
+					WHERE repo_path = ? AND branch_name = ? AND status IN ( #{active_state_placeholders} )
+					ORDER BY updated_at DESC
+					LIMIT 1
+					SQL
+					[ repo_path, branch_name, *ACTIVE_DELIVERY_STATES ]
+				)
+				build_delivery( row: row ) if row
+			end
+		end
+
+		# Lists active deliveries for a repository in creation order.
+		def active_deliveries( repo_path: )
+			with_database do |database|
+				rows = database.execute(
+					<<~SQL,
+					SELECT * FROM deliveries
+					WHERE repo_path = ? AND status IN ( #{active_state_placeholders} )
+					ORDER BY created_at ASC, id ASC
+					SQL
+					[ repo_path, *ACTIVE_DELIVERY_STATES ]
+				)
+				rows.map { |row| build_delivery( row: row ) }
+			end
+		end
+
+		# Lists queued deliveries ready for integration.
+		def queued_deliveries( repo_path: )
+			with_database do |database|
+				database.execute(
+					"SELECT * FROM deliveries WHERE repo_path = ? AND status = ? ORDER BY created_at ASC, id ASC",
+					[ repo_path, "queued" ]
+				).map { |row| build_delivery( row: row ) }
+			end
+		end
+
+		# Updates a delivery record in place.
+		def update_delivery(
+			delivery:,
+			status: UNSET,
+			pr_number: UNSET,
+			pr_url: UNSET,
+			cause: UNSET,
+			summary: UNSET,
+			worktree_path: UNSET,
+			revision_count: UNSET,
+			integrated_at: UNSET,
+			superseded_at: UNSET
+		)
+			updates = {}
+			updates[ "status" ] = status unless status.equal?( UNSET )
+			updates[ "pr_number" ] = pr_number unless pr_number.equal?( UNSET )
+			updates[ "pr_url" ] = pr_url unless pr_url.equal?( UNSET )
+			updates[ "cause" ] = cause unless cause.equal?( UNSET )
+			updates[ "summary" ] = summary unless summary.equal?( UNSET )
+			updates[ "worktree_path" ] = worktree_path unless worktree_path.equal?( UNSET )
+			updates[ "revision_count" ] = revision_count unless revision_count.equal?( UNSET )
+			updates[ "integrated_at" ] = integrated_at unless integrated_at.equal?( UNSET )
+			updates[ "superseded_at" ] = superseded_at unless superseded_at.equal?( UNSET )
+			updates[ "updated_at" ] = now_utc
+
+			with_database do |database|
+				assignments = updates.keys.map { |key| "#{key} = ?" }.join( ", " )
+				database.execute(
+					"UPDATE deliveries SET #{assignments} WHERE id = ?",
+					updates.values + [ delivery.id ]
+				)
+				fetch_delivery( database: database, id: delivery.id, repository: delivery.repository )
+			end
+		end
+
+		# Records one revision cycle against a delivery and bumps the delivery counter.
+		def record_revision( delivery:, cause:, provider:, status:, summary: )
+			timestamp = now_utc
+
+			with_database do |database|
+				next_number = database.get_first_value(
+					"SELECT COALESCE( MAX(number), 0 ) + 1 FROM revisions WHERE delivery_id = ?",
+					[ delivery.id ]
+				).to_i
+				database.execute(
+					<<~SQL,
+						INSERT INTO revisions ( delivery_id, number, cause, provider, status, started_at, finished_at, summary )
+						VALUES ( ?, ?, ?, ?, ?, ?, ?, ? )
+					SQL
+					[
+						delivery.id, next_number, cause, provider, status, timestamp,
+						( status == "completed" || status == "failed" || status == "stalled" ) ? timestamp : nil,
+						summary
+					]
+				)
+				database.execute(
+					"UPDATE deliveries SET revision_count = ?, updated_at = ? WHERE id = ?",
+					[ next_number, timestamp, delivery.id ]
+				)
+				build_revision(
+					row: database.get_first_row( "SELECT * FROM revisions WHERE id = ?", [ database.last_insert_row_id ] )
+				)
+			end
+		end
+
+		# Lists revisions for a delivery in ascending order.
+		def revisions_for_delivery( delivery_id: )
+			with_database do |database|
+				database.execute(
+					"SELECT * FROM revisions WHERE delivery_id = ? ORDER BY number ASC, id ASC",
+					[ delivery_id ]
+				).map { |row| build_revision( row: row ) }
+			end
+		end
+
+	private
+
+		def with_database
+			database = SQLite3::Database.new( path )
+			database.results_as_hash = true
+			database.busy_timeout = 5_000
+			database.execute( "PRAGMA journal_mode = WAL" )
+			yield database
+		ensure
+			database&.close
+		end
+
+		def fetch_delivery( database:, id:, repository: nil )
+			row = database.get_first_row( "SELECT * FROM deliveries WHERE id = ?", [ id ] )
+			build_delivery( row: row, repository: repository )
+		end
+
+		def build_delivery( row:, repository: nil )
+			return nil unless row
+
+			repository ||= Repository.new(
+				path: row.fetch( "repo_path" ),
+				authority: row.fetch( "authority" ),
+				runtime: nil
+			)
+
+			Delivery.new(
+				id: row.fetch( "id" ),
+				repository: repository,
+				branch: row.fetch( "branch_name" ),
+				head: row.fetch( "head" ),
+				worktree_path: row.fetch( "worktree_path" ),
+				authority: row.fetch( "authority" ),
+				status: row.fetch( "status" ),
+				pull_request_number: row.fetch( "pr_number" ),
+				pull_request_url: row.fetch( "pr_url" ),
+				revision_count: row.fetch( "revision_count" ).to_i,
+				cause: row.fetch( "cause" ),
+				summary: row.fetch( "summary" ),
+				created_at: row.fetch( "created_at" ),
+				updated_at: row.fetch( "updated_at" ),
+				integrated_at: row.fetch( "integrated_at" ),
+				superseded_at: row.fetch( "superseded_at" )
+			)
+		end
+
+		def build_revision( row: )
+			return nil unless row
+
+			Revision.new(
+				id: row.fetch( "id" ),
+				delivery_id: row.fetch( "delivery_id" ),
+				number: row.fetch( "number" ).to_i,
+				cause: row.fetch( "cause" ),
+				provider: row.fetch( "provider" ),
+				status: row.fetch( "status" ),
+				started_at: row.fetch( "started_at" ),
+				finished_at: row.fetch( "finished_at" ),
+				summary: row.fetch( "summary" )
+			)
+		end
+
+			def supersede_branch!( database:, repository:, branch_name:, timestamp: )
+				database.execute(
+					<<~SQL,
+					UPDATE deliveries
+					SET status = ?, superseded_at = ?, updated_at = ?
+					WHERE repo_path = ? AND branch_name = ? AND status IN ( #{active_state_placeholders} )
+					SQL
+					[ "superseded", timestamp, timestamp, repository.path, branch_name, *ACTIVE_DELIVERY_STATES ]
+				)
+		end
+
+		def active_state_placeholders
+			ACTIVE_DELIVERY_STATES.map { "?" }.join( ", " )
+		end
+
+		def now_utc
+			Time.now.utc.iso8601
+		end
+	end
+end

data/lib/carson/repository.rb

@@ -0,0 +1,47 @@
+# Passive repository record reconstructed from git state and Carson's ledger.
+module Carson
+	class Repository
+		attr_reader :path, :authority
+
+		def initialize( path:, authority:, runtime: )
+			@path = File.expand_path( path )
+			@authority = authority
+			@runtime = runtime
+		end
+
+		# Human-readable repository name derived from the filesystem path.
+		def name
+			File.basename( path )
+		end
+
+		# Returns a passive branch record for the given branch name.
+		def branch( name )
+			Branch.new( repository: self, name: name, runtime: runtime )
+		end
+
+		# Lists local branches as passive branch records.
+		def branches
+			runtime.git_capture!( "for-each-ref", "--format=%(refname:short)", "refs/heads" )
+				.lines
+				.map( &:strip )
+				.reject( &:empty? )
+				.map { |branch_name| branch( branch_name ) }
+		rescue StandardError
+			[]
+		end
+
+		# Reports the repository's delivery-centred state for status surfaces.
+		def status
+			{
+				name: name,
+				path: path,
+				authority: authority,
+				branches: runtime.ledger.active_deliveries( repo_path: path ).map { |delivery| delivery.branch }
+			}
+		end
+
+	private
+
+		attr_reader :runtime
+	end
+end

data/lib/carson/revision.rb

@@ -0,0 +1,30 @@
+# Passive ledger record for one feedback-driven revision cycle.
+module Carson
+	class Revision
+		attr_reader :id, :delivery_id, :number, :cause, :provider, :status, :started_at, :finished_at, :summary
+
+		def initialize( id:, delivery_id:, number:, cause:, provider:, status:, started_at:, finished_at:, summary: )
+			@id = id
+			@delivery_id = delivery_id
+			@number = number
+			@cause = cause
+			@provider = provider
+			@status = status
+			@started_at = started_at
+			@finished_at = finished_at
+			@summary = summary
+		end
+
+		def open?
+			%w[queued running].include?( status )
+		end
+
+		def completed?
+			status == "completed"
+		end
+
+		def failed?
+			%w[failed stalled].include?( status )
+		end
+	end
+end

data/lib/carson/runtime/audit.rb

@@ -26,6 +26,12 @@ module Carson
 				puts_verbose ""
 				puts_verbose "[Working Tree]"
 				puts_verbose git_capture!( "status", "--short", "--branch" ).strip
+				working_tree = audit_working_tree_report
+				if working_tree.fetch( :status ) == "block"
+					puts_verbose "ACTION: #{working_tree.fetch( :error )}; #{working_tree.fetch( :recovery )}."
+					audit_state = "block"
+					audit_concise_problems << "Working tree: #{working_tree.fetch( :error )} — #{working_tree.fetch( :recovery )}."
+				end
 				puts_verbose ""
 				puts_verbose "[Hooks]"
 				hooks_ok = hooks_health_report
@@ -72,7 +78,7 @@ module Carson
 					failing_count = checks.fetch( :failing_count )
 					pending_count = checks.fetch( :pending_count )
 					total = checks.fetch( :required_total )
-					fail_names = checks.fetch( :failing ).map { it.fetch( :name ) }.join( ", " )
+					fail_names = checks.fetch( :failing ).map { |entry| entry.fetch( :name ) }.join( ", " )
 					if failing_count.positive? && pending_count.positive?
 						audit_concise_problems << "Checks: #{failing_count} failing (#{fail_names}), #{pending_count} pending of #{total} required."
 					elsif failing_count.positive?
@@ -89,11 +95,11 @@ module Carson
 				if baseline_status == "block"
 					parts = []
 					if default_branch_baseline.fetch( :failing_count ).positive?
-						names = default_branch_baseline.fetch( :failing ).map { it.fetch( :name ) }.join( ", " )
+						names = default_branch_baseline.fetch( :failing ).map { |entry| entry.fetch( :name ) }.join( ", " )
 						parts << "#{default_branch_baseline.fetch( :failing_count )} failing (#{names})"
 					end
 					if default_branch_baseline.fetch( :pending_count ).positive?
-						names = default_branch_baseline.fetch( :pending ).map { it.fetch( :name ) }.join( ", " )
+						names = default_branch_baseline.fetch( :pending ).map { |entry| entry.fetch( :name ) }.join( ", " )
 						parts << "#{default_branch_baseline.fetch( :pending_count )} pending (#{names})"
 					end
 					parts << "no check-runs for active workflows" if default_branch_baseline.fetch( :no_check_evidence )
@@ -101,19 +107,19 @@ module Carson
 				elsif baseline_status == "attention"
 					parts = []
 					if default_branch_baseline.fetch( :advisory_failing_count ).positive?
-						names = default_branch_baseline.fetch( :advisory_failing ).map { it.fetch( :name ) }.join( ", " )
+						names = default_branch_baseline.fetch( :advisory_failing ).map { |entry| entry.fetch( :name ) }.join( ", " )
 						parts << "#{default_branch_baseline.fetch( :advisory_failing_count )} advisory failing (#{names})"
 					end
 					if default_branch_baseline.fetch( :advisory_pending_count ).positive?
-						names = default_branch_baseline.fetch( :advisory_pending ).map { it.fetch( :name ) }.join( ", " )
+						names = default_branch_baseline.fetch( :advisory_pending ).map { |entry| entry.fetch( :name ) }.join( ", " )
 						parts << "#{default_branch_baseline.fetch( :advisory_pending_count )} advisory pending (#{names})"
 					end
 					audit_concise_problems << "Baseline (#{default_branch_baseline.fetch( :default_branch, config.main_branch )}): #{parts.join( ', ' )}."
 				end
-				if config.template_canonical.nil? || config.template_canonical.to_s.empty?
+				if config.lint_canonical.nil? || config.lint_canonical.to_s.empty?
 					puts_verbose ""
-					puts_verbose "[Canonical Templates]"
-					puts_verbose "HINT: canonical templates not configured — run carson setup to enable."
+					puts_verbose "[Canonical Lint Policy]"
+					puts_verbose "HINT: lint.canonical not configured — run carson setup to enable."
 				end
 				write_and_print_pr_monitor_report(
 					report: monitor_report.merge(
@@ -128,6 +134,7 @@ module Carson
 						command: "audit",
 						status: audit_state,
 						branch: current_branch,
+						working_tree: working_tree,
 						hooks: { status: hooks_status },
 						main_sync: main_sync,
 						pr: monitor_report[ :pr ],
@@ -175,7 +182,7 @@ module Carson
 				repos.each do |repo_path|
 					repo_name = File.basename( repo_path )
 					unless Dir.exist?( repo_path )
-						puts_line "#{repo_name}: FAIL (path not found)"
+						puts_line "#{repo_name}: not found"
 						record_batch_skip( command: "audit", repo_path: repo_path, reason: "path not found" )
 						failed += 1
 						next
@@ -190,15 +197,15 @@ module Carson
 							clear_batch_success( command: "audit", repo_path: repo_path )
 							passed += 1
 						when EXIT_BLOCK
-							puts_line "#{repo_name}: BLOCK" unless verbose?
+							puts_line "#{repo_name}: needs attention" unless verbose?
 							blocked += 1
 						else
-							puts_line "#{repo_name}: FAIL" unless verbose?
+							puts_line "#{repo_name}: could not complete" unless verbose?
 							record_batch_skip( command: "audit", repo_path: repo_path, reason: "audit failed" )
 							failed += 1
 						end
 					rescue StandardError => exception
-						puts_line "#{repo_name}: FAIL (#{exception.message})"
+						puts_line "#{repo_name}: could not complete (#{exception.message})"
 						record_batch_skip( command: "audit", repo_path: repo_path, reason: exception.message )
 						failed += 1
 					end
@@ -207,11 +214,30 @@ module Carson
 				puts_line ""
 				puts_line "Audit all complete: #{passed} ok, #{blocked} blocked, #{failed} failed."
 				blocked.zero? && failed.zero? ? EXIT_OK : EXIT_BLOCK
-			end
+				end
 
-		private
-			def pr_and_check_report
-				report = {
+			# rubocop:disable Layout/AccessModifierIndentation -- tab-width calculation produces unfixable mixed tabs+spaces
+			private
+			# rubocop:enable Layout/AccessModifierIndentation
+				def audit_working_tree_report
+					dirty_reason = dirty_worktree_reason
+					return { dirty: false, context: nil, status: "ok" } if dirty_reason.nil?
+
+					if dirty_reason == "main_worktree"
+						{
+							dirty: true,
+							context: dirty_reason,
+							status: "block",
+							error: "main working tree has uncommitted changes",
+							recovery: "create a worktree with carson worktree create <name>"
+						}
+					else
+						{ dirty: true, context: dirty_reason, status: "ok" }
+					end
+				end
+
+				def pr_and_check_report
+					report = {
 					generated_at: Time.now.utc.iso8601,
 					branch: current_branch,
 					status: "ok",
@@ -262,7 +288,7 @@ module Carson
 					return report
 				end
 				checks_data = JSON.parse( checks_stdout )
-				pending = checks_data.select { it[ "bucket" ].to_s == "pending" }
+				pending = checks_data.select { |entry| entry[ "bucket" ].to_s == "pending" }
 				failing = checks_data.select { |entry| check_entry_failing?( entry: entry ) }
 				report[ :checks ][ :status ] = checks_success ? "ok" : ( checks_exit == 8 ? "pending" : "attention" )
 				report[ :checks ][ :required_total ] = checks_data.count