feat: add explicit repo/revision/location target parsing for :Forge #144

New issue

Closed

opened 2026-04-11 19:02:32 +00:00 by barrettruth · 1 comment

barrettruth commented

2026-04-11 19:02:32 +00:00

Prerequisites

I have searched existing issues.

Problem

Issue #142 proposes first-class repo/revision/location targeting, but Forge still mostly derives remote context from the current checkout and origin URL.

That is not expressive enough for:

fork/upstream workflows
explicit repo targeting for list/actions
explicit revision targeting for CI and browse
explicit file/range targeting for browse
explicit base/head endpoints for PR creation

We need a real address model rather than a single implicit current-repo assumption.

Proposed solution

Add a dedicated target/address module for :Forge.

Address types

Repo address

Examples:

upstream
origin
owner/repo
github.com/owner/repo
gitlab.com/group/subgroup/repo

Revision address

Examples:

@main
@abc1234
upstream@main
owner/repo@v1.2.3

Location address

Examples:

upstream@main:README.md
upstream@main:lua/forge/init.lua#L10
upstream@main:lua/forge/init.lua#L10-L40

Resolution rules

Resolve repo addresses in this order:

configured alias
git remote name
explicit hosted repo path

Suggested API shape

Introduce typed parsed targets rather than a single generic “scope” blob:

RepoAddress
RevAddress
LocationAddress

The command layer can then normalize these into existing backend repo arguments (-R, --repo) as needed.

Initial consumers

pr list / issue list / release list use repo addresses
ci list uses repo + revision addresses
browse uses revision + location addresses
pr create uses head= and base= revision addresses

Acceptance criteria

a target parser exists in a dedicated module
repo/revision/location address types are parsed separately
alias + remote resolution is explicit and tested
invalid address kinds produce clear command errors
parsed targets can be threaded into current backend commands without re-deriving from checkout state
tests cover repo aliases, explicit hosted paths, @rev, repo@rev, and repo@rev:path#Lx-Ly

Alternatives considered

Continue relying on checkout-derived repo inference. This keeps defaults simple but leaves explicit fork/upstream and repo+revision workflows underspecified.
Reuse the current internal scope object directly as the public command concept. That leaks implementation language and is too weak for location/base/head addressing.

## Prerequisites - [x] I have searched existing issues. ## Problem Issue #142 proposes first-class repo/revision/location targeting, but Forge still mostly derives remote context from the current checkout and `origin` URL. That is not expressive enough for: - fork/upstream workflows - explicit repo targeting for list/actions - explicit revision targeting for CI and browse - explicit file/range targeting for browse - explicit base/head endpoints for PR creation We need a real address model rather than a single implicit current-repo assumption. ## Proposed solution Add a dedicated target/address module for `:Forge`. ### Address types #### Repo address Examples: - `upstream` - `origin` - `owner/repo` - `github.com/owner/repo` - `gitlab.com/group/subgroup/repo` #### Revision address Examples: - `@main` - `@abc1234` - `upstream@main` - `owner/repo@v1.2.3` #### Location address Examples: - `upstream@main:README.md` - `upstream@main:lua/forge/init.lua#L10` - `upstream@main:lua/forge/init.lua#L10-L40` ### Resolution rules Resolve repo addresses in this order: 1. configured alias 2. git remote name 3. explicit hosted repo path ### Suggested API shape Introduce typed parsed targets rather than a single generic “scope” blob: - `RepoAddress` - `RevAddress` - `LocationAddress` The command layer can then normalize these into existing backend repo arguments (`-R`, `--repo`) as needed. ### Initial consumers - `pr list` / `issue list` / `release list` use repo addresses - `ci list` uses repo + revision addresses - `browse` uses revision + location addresses - `pr create` uses `head=` and `base=` revision addresses ### Acceptance criteria - [ ] a target parser exists in a dedicated module - [ ] repo/revision/location address types are parsed separately - [ ] alias + remote resolution is explicit and tested - [ ] invalid address kinds produce clear command errors - [ ] parsed targets can be threaded into current backend commands without re-deriving from checkout state - [ ] tests cover repo aliases, explicit hosted paths, `@rev`, `repo@rev`, and `repo@rev:path#Lx-Ly` ## Alternatives considered - Continue relying on checkout-derived repo inference. This keeps defaults simple but leaves explicit fork/upstream and repo+revision workflows underspecified. - Reuse the current internal scope object directly as the public command concept. That leaks implementation language and is too weak for location/base/head addressing.

barrettruth commented

2026-04-11 20:54:35 +00:00

Implemented in #150.