carson 3.3.0 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91c767b37c33c1d69a377f509b5503ef342fef4ff4f3629439e998938d99b24b
-  data.tar.gz: 2b615ad6df7610917d400166a5d735c9bc3f7e51b52eeda33d48446be9916d9c
+  metadata.gz: 514509a6422a4c2237a48feac1bff1c10e4705afe62fb574d400b8364cf131ba
+  data.tar.gz: 1f7bbf53a01ee92d8a97d62d0a7957bb823c0aabd70e31a7e27e37de8ab3b8c6
 SHA512:
-  metadata.gz: df671d4ed658b1aa98290cfcdbc5cd47c78c702d83254bdc4e79d9ed5755320b3cd9c08f664e20633830661506fe8a0cdcb0f8c03e1314623a6074a444f7d23d
-  data.tar.gz: e05a41a7fb961deac1f63eccb77b8d03eb7d694a557baebaead88f5f38d9bab91a1b4643f71b4bf09741e51946ab2c6707a288e7a22fe2ea981ee5769e370b2f
+  metadata.gz: a536b8a85ba6b2a737ce913485e3d58b5672b6b13af40261b181dd234bf1052ffa93a5f9b51307d9ce7e433e588b92ce294e88118b758747d4bb5cbad898c6c5
+  data.tar.gz: d476ba9ed57c7c97967c0cb2fab8b8390debfa196d657ae6d2e6c51e143248f8160bc543eb0d9b4e5c3c434ba4a25aa16b8af9aa6ec3b9cfcf5b7c974cd8fa9e

data/RELEASE.md

@@ -5,6 +5,23 @@ 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`.
 
+## 3.4.0 — Audit JSON
+
+### What changed
+
+- **`carson audit --json`** — machine-readable JSON output for the audit command. The JSON envelope includes `command`, `status`, `branch`, `hooks`, `main_sync`, `pr`, `checks`, `baseline`, `problems`, and `exit_code`. Agents can parse audit results programmatically instead of regex-matching human-readable text.
+
+### UX
+
+- JSON output is only produced when `--json` is passed; default human-readable output is unchanged.
+- The `problems` array contains the same concise problem strings shown in non-verbose human output, making it easy for agents to surface actionable issues.
+- `hooks.status` is `"ok"` or `"mismatch"`, `main_sync.status` is `"ok"`, `"ahead"`, `"behind"`, or `"unknown"`.
+
+### Migration
+
+- No breaking changes. `carson audit` without `--json` behaves identically to 3.3.0.
+- The `audit!` method now accepts `json_output:` keyword argument (default `false`).
+
 ## 3.3.0 — Deliver Refinements
 
 ### What changed

data/VERSION

@@ -1 +1 @@
-3.3.0
+3.4.0

data/lib/carson/cli.rb

@@ -53,7 +53,7 @@ module Carson
 
 		def self.build_parser
 			OptionParser.new do |opts|
-				opts.banner = "Usage: carson [status [--json]|setup|audit|sync|deliver [--merge] [--json] [--title T] [--body-file F]|prune [--all]|worktree create|done|remove <name>|onboard|refresh [--all]|offboard|template check|apply|review gate|sweep|govern [--dry-run] [--json] [--loop SECONDS]|version]"
+				opts.banner = "Usage: carson [status [--json]|setup|audit [--json]|sync|deliver [--merge] [--json] [--title T] [--body-file F]|prune [--all]|worktree create|done|remove <name>|onboard|refresh [--all]|offboard|template check|apply|review gate|sweep|govern [--dry-run] [--json] [--loop SECONDS]|version]"
 			end
 		end
 
@@ -88,6 +88,8 @@ module Carson
 				parse_worktree_subcommand( argv: argv, parser: parser, err: err )
 			when "review"
 				parse_named_subcommand( command: command, usage: "gate|sweep", argv: argv, parser: parser, err: err )
+			when "audit"
+				parse_audit_command( argv: argv, err: err )
 			when "status"
 				parse_status_command( argv: argv, err: err )
 			when "deliver"
@@ -242,6 +244,15 @@ module Carson
 			{ command: :invalid }
 		end
 
+		def self.parse_audit_command( argv:, err: )
+			json_flag = argv.delete( "--json" ) ? true : false
+			unless argv.empty?
+				err.puts "#{BADGE} Unexpected arguments for audit: #{argv.join( ' ' )}"
+				return { command: :invalid }
+			end
+			{ command: "audit", json: json_flag }
+		end
+
 		def self.parse_status_command( argv:, err: )
 			json_flag = argv.delete( "--json" ) ? true : false
 			unless argv.empty?
@@ -321,7 +332,7 @@ module Carson
 			when "setup"
 				runtime.setup!( cli_choices: parsed.fetch( :cli_choices, {} ) )
 			when "audit"
-				runtime.audit!
+				runtime.audit!( json_output: parsed.fetch( :json, false ) )
 			when "sync"
 				runtime.sync!
 			when "prune"

data/lib/carson/runtime/audit.rb

@@ -1,13 +1,20 @@
+# Pre-commit audit — checks hooks, main sync, PR checks, and CI baseline.
+# Exits with EXIT_BLOCK when policy violations are found.
+# Supports --json for machine-readable structured output.
 require "cgi"
 
 module Carson
 	class Runtime
 		module Audit
-			def audit!
+			def audit!( json_output: false )
 				fingerprint_status = block_if_outsider_fingerprints!
 				return fingerprint_status unless fingerprint_status.nil?
 				unless head_exists?
-					puts_line "No commits yet — audit skipped for initial commit."
+					if json_output
+						out.puts JSON.pretty_generate( { command: "audit", status: "skipped", reason: "no commits yet", exit_code: EXIT_OK } )
+					else
+						puts_line "No commits yet — audit skipped for initial commit."
+					end
 					return EXIT_OK
 				end
 				audit_state = "ok"
@@ -22,6 +29,7 @@ module Carson
 				puts_verbose ""
 				puts_verbose "[Hooks]"
 				hooks_ok = hooks_health_report
+				hooks_status = hooks_ok ? "ok" : "mismatch"
 				unless hooks_ok
 					audit_state = "block"
 					audit_concise_problems << "Hooks: mismatch — run carson refresh."
@@ -29,23 +37,27 @@ module Carson
 				puts_verbose ""
 				puts_verbose "[Main Sync Status]"
 				ahead_count, behind_count, main_error = main_sync_counts
+				main_sync = { ahead: 0, behind: 0, status: "ok" }
 				if main_error
 					puts_verbose "main_vs_remote_main: unknown"
 					puts_verbose "WARN: unable to calculate main sync status (#{main_error})."
 					audit_state = "attention" if audit_state == "ok"
 					audit_concise_problems << "Main sync: unable to determine — check remote connectivity."
+					main_sync = { ahead: 0, behind: 0, status: "unknown", error: main_error }
 				elsif ahead_count.positive?
 					puts_verbose "main_vs_remote_main_ahead: #{ahead_count}"
 					puts_verbose "main_vs_remote_main_behind: #{behind_count}"
 					puts_verbose "ACTION: local #{config.main_branch} is ahead of #{config.git_remote}/#{config.main_branch} by #{ahead_count} commit#{plural_suffix( count: ahead_count )}; reset local drift before commit/push workflows."
 					audit_state = "block"
 					audit_concise_problems << "Main sync (#{config.git_remote}): ahead by #{ahead_count} — git fetch #{config.git_remote}, or carson setup to switch remote."
+					main_sync = { ahead: ahead_count, behind: behind_count, status: "ahead" }
 				elsif behind_count.positive?
 					puts_verbose "main_vs_remote_main_ahead: #{ahead_count}"
 					puts_verbose "main_vs_remote_main_behind: #{behind_count}"
 					puts_verbose "ACTION: local #{config.main_branch} is behind #{config.git_remote}/#{config.main_branch} by #{behind_count} commit#{plural_suffix( count: behind_count )}; run carson sync."
 					audit_state = "attention" if audit_state == "ok"
 					audit_concise_problems << "Main sync (#{config.git_remote}): behind by #{behind_count} — run carson sync."
+					main_sync = { ahead: ahead_count, behind: behind_count, status: "behind" }
 				else
 					puts_verbose "main_vs_remote_main_ahead: 0"
 					puts_verbose "main_vs_remote_main_behind: 0"
@@ -109,15 +121,40 @@ module Carson
 							audit_status: audit_state
 						)
 					)
-				puts_verbose ""
-				puts_verbose "[Audit Result]"
-				puts_verbose "status: #{audit_state}"
-				puts_verbose( audit_state == "block" ? "ACTION: local policy block must be resolved before commit/push." : "ACTION: no local hard block detected." )
-				unless verbose?
-					audit_concise_problems.each { |problem| puts_line problem }
-					puts_line "Audit: #{audit_state}"
+				exit_code = audit_state == "block" ? EXIT_BLOCK : EXIT_OK
+
+				if json_output
+					result = {
+						command: "audit",
+						status: audit_state,
+						branch: current_branch,
+						hooks: { status: hooks_status },
+						main_sync: main_sync,
+						pr: monitor_report[ :pr ],
+						checks: monitor_report.fetch( :checks ),
+						baseline: {
+							status: default_branch_baseline.fetch( :status ),
+							repository: default_branch_baseline[ :repository ],
+							failing_count: default_branch_baseline.fetch( :failing_count ),
+							pending_count: default_branch_baseline.fetch( :pending_count ),
+							advisory_failing_count: default_branch_baseline.fetch( :advisory_failing_count ),
+							advisory_pending_count: default_branch_baseline.fetch( :advisory_pending_count )
+						},
+						problems: audit_concise_problems,
+						exit_code: exit_code
+					}
+					out.puts JSON.pretty_generate( result )
+				else
+					puts_verbose ""
+					puts_verbose "[Audit Result]"
+					puts_verbose "status: #{audit_state}"
+					puts_verbose( audit_state == "block" ? "ACTION: local policy block must be resolved before commit/push." : "ACTION: no local hard block detected." )
+					unless verbose?
+						audit_concise_problems.each { |problem| puts_line problem }
+						puts_line "Audit: #{audit_state}"
+					end
 				end
-				audit_state == "block" ? EXIT_BLOCK : EXIT_OK
+				exit_code
 			end
 
 		private

metadata

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