Docs: domain object design by wanghailei · Pull Request #249 · wanghailei/carson

wanghailei · 2026-03-11T12:58:53Z

No description provided.

Design for extracting Carson::Remote, Carson::PullRequest, and Carson::Branch from the Runtime god object. Approved design with error contract (raise on failure), wiring pattern (thin Runtime delegates), and scoped extraction (lifecycle only, govern/status deferred to second pass). Tracks #246. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

16-task TDD plan covering Remote, PullRequest, Branch extraction and template sync regression test. Each task is bite-sized with exact file paths, test code, implementation code, and verification commands. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

gemini-code-assist · 2026-03-11T13:35:03Z

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces comprehensive documentation for a significant architectural refactoring within the Carson project. It outlines a design and a detailed implementation plan for extracting core Git domain concepts such as Remote, PullRequest, and Branch into dedicated, first-class objects, moving away from the existing Carson::Runtime "god object." This initiative aims to enhance the system's modularity, maintainability, and testability. Additionally, the PR establishes new linter configurations for various languages (Ruby, Python, JavaScript, CSS) to enforce consistent code quality standards across the codebase, ensuring a robust development environment for the planned refactoring.

Highlights

Architectural Design Documentation: Documented a new design for extracting Remote, PullRequest, and Branch domain objects from the Carson::Runtime "god object" to improve modularity and maintainability.
Detailed Implementation Plan: Provided a comprehensive, step-by-step plan for the extraction of these core Git domain objects, including test-driven development steps and wiring into existing runtime modules.
Standardized Linter Configurations: Introduced new linter configurations for Biome (JavaScript/CSS), ERB Linter, RuboCop (Ruby), and Ruff (Python) to enforce consistent code quality standards across the codebase.
Carson Role Clarification: Updated the .github/carson.md file to provide a more descriptive role for Carson, detailing its function as an autonomous git strategist and repositories governor.

Changelog

.github/carson.md
- Updated Carson's role description to be more specific.
.github/linters/biome.json
- Added Biome linter configuration for JavaScript and CSS, enforcing tab indentation and enabling import organization.
.github/linters/erb-lint.yml
- Added ERB Linter configuration, enabling default linters and specific checks like Rubocop, ClosingErbTagIndent, and TrailingWhitespace.
.github/linters/rubocop.yml
- Added RuboCop configuration for Ruby, setting Ruby 4.0 as target, enforcing tab indentation, and defining various style and metric rules.
.github/linters/ruff.toml
- Added Ruff linter configuration for Python, selecting common linting rules and configuring tab indentation and double quotes.
docs/design-domain-objects.md
- Added a design document detailing the problem with Carson::Runtime, the blueprint for domain object extraction, and proposed structures for Carson::Remote, Carson::PullRequest, and Carson::Branch.
docs/plan-domain-objects.md
- Added a comprehensive implementation plan for the domain object extraction, broken down into chunks and tasks with detailed steps and test cases.

Activity

No specific activity (comments, reviews, progress) has been recorded for this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces new linter configurations for Biome, RuboCop, and Ruff, enhancing code quality and consistency across different language ecosystems within the repository. Additionally, a comprehensive design document outlines a strategic refactoring of core Git domain objects, aiming to improve modularity and reduce the 'god object' anti-pattern in Carson::Runtime. The proposed architectural changes, including the introduction of Carson::Remote, Carson::PullRequest, and Carson::Branch objects, are well-articulated and follow sound design principles. However, there are a few minor issues identified in the linter configurations and the Ruby code snippets within the design document that should be addressed for correctness and clarity.

gemini-code-assist · 2026-03-11T13:40:31Z

.github/linters/rubocop.yml

+  - rubocop-performance
+
+AllCops:
+  TargetRubyVersion: 4.0 # Parse and lint as Ruby 4.0.


The TargetRubyVersion is set to 4.0, which is a future, unreleased version of Ruby. RuboCop should be configured with a currently supported Ruby version (e.g., 3.3) to ensure accurate linting and avoid potential compatibility issues.

TargetRubyVersion: 3.3 # Parse and lint as Ruby 3.3.

gemini-code-assist · 2026-03-11T13:40:31Z

.github/linters/biome.json

+	"javascript": {
+		"formatter": {
+			"indentStyle": "tab"
+		}


The indentStyle: "tab" setting is already defined at the top-level formatter configuration (line 13). Repeating it within javascript.formatter is redundant, as the top-level setting applies unless explicitly overridden by a different value.

"javascript": { }

gemini-code-assist · 2026-03-11T13:40:31Z

.github/linters/biome.json

+	"css": {
+		"formatter": {
+			"indentStyle": "tab"
+		}


Similar to the JavaScript formatter, the indentStyle: "tab" setting for css.formatter is redundant because it's already specified at the top-level formatter configuration (line 13).

"css": { }

gemini-code-assist · 2026-03-11T13:40:31Z

docs/design-domain-objects.md

+
+  def force_push_with_lease!( branch: )
+  # Returns self. Raises Remote::Error on failure.
+end


The Ruby code block for Carson::Remote is missing an end keyword for the class definition. This would result in a syntax error if executed. Please ensure all code snippets are syntactically correct.

Suggested change

end

def force_push_with_lease!( branch: )

# Returns self. Raises Remote::Error on failure.

end

end

gemini-code-assist · 2026-03-11T13:40:31Z

docs/design-domain-objects.md

+
+  def review_decision
+  # Returns :approved, :changes_requested, :review_required, or :none.
+end


The Ruby code block for Carson::PullRequest is missing an end keyword for the class definition. This would result in a syntax error if executed. Please ensure all code snippets are syntactically correct.

Suggested change

end

def review_decision

# Returns :approved, :changes_requested, :review_required, or :none.

end

end

gemini-code-assist · 2026-03-11T13:40:31Z

docs/design-domain-objects.md

+
+  def self.absorbed( runtime: )
+  # Returns array of Branch instances. Fully merged into main.
+end


The Ruby code block for Carson::Branch is missing an end keyword for the class definition. This would result in a syntax error if executed. Please ensure all code snippets are syntactically correct.

Suggested change

end

def self.absorbed( runtime: )

# Returns array of Branch instances. Fully merged into main.

end

end

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Replace push_branch! and force_push_with_lease! private methods with calls to Carson::Remote#push! and Carson::Remote#force_push_with_lease!. Update the contested-push test to exercise Remote::Error directly. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Replace all six call sites of repository_coordinates in review.rb, audit.rb, govern.rb, and prune.rb with Remote.new construction, then delete the method from data_access.rb. Update test stubs accordingly. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Introduces PullRequest domain object with find_open, for_branch, and open_for_branch? class methods, plus Error subclass with recovery contract. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Adds create! class method that raises PullRequest::Error with recovery hint on failure, and default_title helper for branch-name humanisation. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Adds instance methods for merging a PR (with error contract), querying CI check status, and querying the review decision on a PR. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Adds merged_for_branch class method that queries the GitHub REST API for closed PRs matching an exact head SHA, enabling evidence-based force deletion in prune. Accepts owner, repo, and main_branch as parameters. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Replace all PR-related private methods in deliver.rb (find_or_create_pr!, find_existing_pr, create_pr!, default_pr_title, check_pr_ci, check_pr_review, merge_pr!) with calls to the PullRequest domain object. Update the test_default_pr_title_from_branch_name test to call PullRequest.default_title directly. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Replace current_pull_request_for_branch, branch_has_open_pr?, and merged_pr_for_branch with thin adapters that delegate to PullRequest domain object methods. Add title attr_reader to PullRequest so the review gate report can surface PR titles without raw gh calls. Update tests to reflect the adapter's delegation behaviour. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

CI ruby_indentation_guard caught space-based alignment on lines 219 and 230 where .map chained after .reject used spaces instead of tabs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

wanghailei and others added 3 commits March 11, 2026 20:58

chore: sync Carson managed files

bc9f5d3

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

gemini-code-assist bot reviewed Mar 11, 2026

View reviewed changes

wanghailei and others added 18 commits March 11, 2026 22:21

feat: add Carson::Remote with owner/repo parsing

7798d89

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

feat: add push! and force_push_with_lease! to Carson::Remote

bf8c87f

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

test: fix bare remote leak and add force_push_with_lease failure test

2d71d6b

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fix: use send(:config) in govern.rb and normalise raise style in Remote

8f20cc7

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

feat: add Carson::PullRequest with lookup methods

af1358b

Introduces PullRequest domain object with find_open, for_branch, and open_for_branch? class methods, plus Error subclass with recovery contract. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

feat: add PullRequest.create! with error contract

30e3ae0

Adds create! class method that raises PullRequest::Error with recovery hint on failure, and default_title helper for branch-name humanisation. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

feat: add PullRequest merge!, ci_status, review_decision

07fdc71

Adds instance methods for merging a PR (with error contract), querying CI check status, and querying the review decision on a PR. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fix: add missing -- separator and expand PullRequest test coverage

4d7cceb

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

feat: add Carson::Branch with current and exists?

1cb485d

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

feat: add Branch classification methods (stale, orphaned, absorbed)

25a132d

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

refactor: wire Branch into runtime and prune delegates

c5eb734

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fix: sync templates in deliver before push (--no-verify skips hook)

1baa942

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

test: regression — verify remote gets canonical templates via deliver

d907970

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

github-actions bot mentioned this pull request Mar 11, 2026

Carson review sweep findings #57

Open

fix: replace space indentation with tabs in prune.rb method chains

410d4b8

CI ruby_indentation_guard caught space-based alignment on lines 219 and 230 where .map chained after .reject used spaces instead of tabs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: domain object design#249

Docs: domain object design#249
wanghailei wants to merge 22 commits intomainfrom
docs/domain-object-design

wanghailei commented Mar 11, 2026

Uh oh!

gemini-code-assist bot commented Mar 11, 2026

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot Mar 11, 2026

Uh oh!

gemini-code-assist bot Mar 11, 2026

Uh oh!

gemini-code-assist bot Mar 11, 2026

Uh oh!

gemini-code-assist bot Mar 11, 2026

Uh oh!

gemini-code-assist bot Mar 11, 2026

Uh oh!

gemini-code-assist bot Mar 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

wanghailei commented Mar 11, 2026

Uh oh!

gemini-code-assist bot commented Mar 11, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant