Extract Facade From Base Lib

Extract Facade from Base/Lib

Migrate an existing public method from Git::Base and/or Git::Lib to a Git::Repository::* facade method. This is the second extraction step of the v5.0.0 redesign — it follows Extract Command from Lib, which moves the underlying CLI invocation into a Git::Commands::* class.

In Phase 4 of the redesign, both Git::Base and Git::Lib will be deleted. This migration moves their public surface to Git::Repository. Until Phase 4, the original methods remain in place and delegate to the new facade method to preserve backward compatibility within the migration window.

Contents

• How to use this skill
• Prerequisites
• Related skills
• Input
• Source patterns
  • Pattern A — Git::Base wrapper + Git::Lib implementation
  • Pattern B — Git::Lib-only (public-by-exposure)
  • Pattern C — Git::Base-only (no Git::Lib method)
• Signature compatibility policy
• Keyword-arg remediation list
• Determining the option allowlist
• Workflow
  • Branch setup
  • Step 1 — Identify the source pattern
  • Step 2 — Plan the migration and get approval
  • Step 3 — Ensure adequate legacy tests
  • Step 4 — Ensure the underlying Git::Commands::* class exists
  • Step 5 — Implement the facade method
  • Step 6 — Update Git::Base and/or Git::Lib to delegate
• Commit discipline
• Quality gates
• What stays vs. what moves
• Review mode
  • Invoke
  • R1 — Source analysis
  • R2 — Legacy test coverage
  • R3 — Command class
  • R4 — Facade implementation
  • R5 — Delegation
  • R6 — Quality gates

How to use this skill

Attach this file to your Copilot Chat context, then invoke with the public method to migrate. Examples:

Using the Extract Facade from Base/Lib skill, migrate Git::Base#commit to
Git::Repository#commit.

Extract Facade: Git::Lib#branches_all (called publicly via g.lib.branches_all)

Prerequisites

Before starting, you MUST load the following skill(s):

• Facade Implementation — drives the actual scaffolding of the new facade method
• YARD Documentation — baseline YARD rules

Related skills

• Facade Implementation — used in Step 5 to scaffold the new facade method
• Facade Test Conventions — unit and integration test conventions for the new facade method
• Facade YARD Documentation — YARD docs for the new facade module/method
• Extract Command from Lib — sibling extraction skill that moves the underlying CLI call into a Git::Commands::* class. Run first when no command class exists yet.
• Command Implementation — used in Step 4 if a new Git::Commands::* class needs to be scaffolded
• Project Context — three-layer architecture and Phase 4 deletion plan

Input

Required:

1. The Git::Base and/or Git::Lib public method to migrate.
2. The git operation it performs (subcommand + flags).

Source patterns

Public methods being migrated fall into one of three patterns. Identify which pattern applies before planning the migration.

Pattern A — Git::Base wrapper + Git::Lib implementation

The most common pattern. Git::Base#foo is a thin wrapper that forwards to Git::Lib#foo, which contains the orchestration logic.

Examples: commit, diff_full, branches, worktree_add.

# lib/git/base.rb
def commit(message, opts = {})
  self.lib.commit(message, opts)
end

# lib/git/lib.rb
def commit(message, opts = {})
  opts = opts.merge(message: message) if message
  deprecate_commit_no_gpg_sign_option!(opts)
  Git::Commands::Commit.new(self).call(edit: false, **opts).stdout
end

Public contract source: Git::Base#commit signature; Git::Lib#commit implementation.

When migrating, the facade method must preserve this signature exactly (e.g. commit(message, opts = {})) — even though greenfield facade methods would prefer **options per facade-implementation REFERENCE.md — Choosing the method signature. The legacy public contract wins during migration.

Pattern B — Git::Lib-only (public-by-exposure)

The public API is g.lib.foo — Git::Base exposes Git::Lib as #lib (or through a similar accessor), so Git::Lib methods are reachable as public API even when no Git::Base wrapper exists.

Examples: branches_all, worktrees_all, current_branch_state.

# lib/git/lib.rb (no Git::Base wrapper exists)
def branches_all
  result = Git::Commands::Branch::List.new(self).call(all: true, format: ...)
  Git::Parsers::Branch.parse_list(result.stdout)
end

Public contract source: Git::Lib#foo signature and implementation.

Migration consequence: After Phase 4, callers using g.lib.foo must migrate to g.foo (or g.repository.foo). Document this in the migration plan.

Pattern C — Git::Base-only (no Git::Lib method)

The implementation lives entirely in Git::Base with no Git::Lib counterpart. The method may call command(...) directly via lib.send(...) or implement filesystem operations.

Examples: add_remote, with_index, repo_size, archive.

# lib/git/base.rb
def repo_size
  all_files_size = 0
  Find.find(repo.path) { |f| all_files_size += File.size(f) if File.file?(f) }
  all_files_size
end

Public contract source: Git::Base#foo signature and implementation.

Signature compatibility policy

Use this policy in both extraction mode and review mode:

Rules:

1. legacy-contract methods preserve the exact 4.x call shape verbatim, including rare **opts signatures; never alter the parameter list when a legacy predecessor exists.

2. 5.x-native methods use opts = {} style for consistency; a broader kwargs migration is deferred to v6.x so it can be applied uniformly across the entire public API.

3. Every extracted method must be explicitly classified as legacy-contract or 5.x-native before the PR is opened.

4. The classification must appear in the PR description and in the extracted method's YARD @note. Example:

   # @note Signature compatibility: legacy-contract — preserves the exact Git::Base#foo 4.x call shape.

Keyword-arg remediation list

See KEYWORD_ARG_REMEDIATION.md for the initial list of facade methods that use **opts/** keyword-splat where the legacy predecessor used opts = {}. Each method in this list must be resolved before Git.open/.clone/.init/.bare are changed to return Git::Repository: either fix the signature to match the legacy-contract classification, or record an explicit 5.x-native justification.

Determining the option allowlist

When the facade method uses assert_valid_opts!, the allowlist (*_ALLOWED_OPTS) must contain only the options that were accepted in the 4.x branch of this gem. Do not expand the allowlist to match everything the underlying Git::Commands::* class supports — new options are deferred to a follow-up PR so they can be properly documented and tested.

How to find the 4.x allowlist for a method:

1. Open https://github.com/ruby-git/ruby-git/blob/4.x/lib/git/lib.rb and search for the method's *_OPTION_MAP constant (e.g. ADD_OPTION_MAP, RESET_OPTION_MAP).
2. The option keys declared in that map are the only keys that were valid in 4.x. Any key not present in the map would have raised ArgumentError via ArgsBuilder.validate! — confirmed by https://github.com/ruby-git/ruby-git/blob/4.x/lib/git/args_builder.rb.
3. Use those keys — and only those keys — in the facade's *_ALLOWED_OPTS constant, @option YARD tags, and integration/unit tests.
4. If the underlying Git::Commands::* class supports additional options beyond the 4.x map, note them in a follow-up issue rather than silently including them.

Workflow

Branch setup

All work must be done on a feature branch. Never commit or push directly to main.

git checkout -b <feature-branch-name>

Step 1 — Identify the source pattern

1. Locate the public method in Git::Base and/or Git::Lib.

2. Determine which Source pattern applies (A, B, or C).

3. Note:

   • the public signature (positional args, options hash, keyword args)
   • the signature classification (legacy-contract or 5.x-native) and justification
   • the exact return value of the legacy method — read the source code to see whether it ends in .stdout, .stdout.chomp, a parser call, a domain object, nil, etc. Do not assume from the YARD @return tag, which may be stale or missing. The facade must reproduce this exact value (e.g. if Git::Lib#add ends in .stdout, the facade returns String, not Git::CommandLineResult).
   • any pre-processing (path expansion, option whitelisting, deprecation handling)
   • any post-processing (parsing, result-class assembly)
   • any execution-context arguments (timeout:, chdir:, env:)
   • the 4.x-supported options: locate the corresponding *_OPTION_MAP constant in 4.x/lib/git/lib.rb and record which option keys it declared. These become the facade's *_ALLOWED_OPTS allowlist — see Determining the option allowlist.

4. Document the method's current public contract in writing — it must be preserved exactly by the facade method.

5. Run linters and rubocop to confirm a clean baseline:

   bundle exec rubocop

Step 2 — Plan the migration and get approval

Before writing or changing any code, present a migration plan and wait for explicit confirmation from the user.

The plan must include:

Also state:

• The exact public contract to preserve (signature + return type + raised errors).
• The signature classification and why (legacy-contract or 5.x-native).
• For legacy-contract methods, confirm the exact 4.x call shape is preserved verbatim (including rare **opts signatures).
• Whether a new topic module is required (justify per facade-implementation REFERENCE.md). When extracting one method at a time, scan Git::Base / Git::Lib for siblings on the same git topic before deciding — see Choosing a module for a new facade method.
• The delegation strategy for Git::Base and/or Git::Lib (Step 6) — both remain in place during the migration window and delegate to the new facade.
• For Pattern B: explicit note that g.lib.foo callers will need to migrate before Phase 4; capture this as a follow-up issue or CHANGELOG entry.

Then ask:

Does this mapping look correct? Any changes before I start implementing?

Do not move to Step 3 until the user confirms the plan.

Step 3 — Ensure adequate legacy tests

Verify that legacy tests in tests/units/ and existing specs in spec/ adequately cover the public method. The legacy tests guarantee the migration preserves backward compatibility.

1. Search for coverage:

   grep -rn '<method_name>' tests/units/ spec/

2. If coverage is insufficient, add minimal new tests that exercise the current public contract. Use existing legacy test conventions for Test::Unit tests in tests/units/. Do not change existing tests.

3. Add or update facade tests that prove signature behavior:

   • for legacy-contract methods, test the expected legacy call shape(s) (positional hash and/or keyword-arg / **opts)

4. Run the new tests and RuboCop:

   bundle exec bin/test <test-file-basename>
   bundle exec rubocop tests/units/<test-file>

5. Commit:

   git commit -m "refactor(test): add legacy tests for <method_name>"

Step 4 — Ensure the underlying Git::Commands::* class exists

The facade method calls one or more Git::Commands::* classes. If any required command class does not exist yet, scaffold it first using Extract Command from Lib (which in turn uses Command Implementation).

For Pattern C migrations, the source Git::Base method may not currently call through a Git::Commands::* class at all (it uses command(...) directly or filesystem operations). In that case, you must scaffold the Git::Commands::* class before this step.

Skip this step when every required command class already exists.