refactor: rename backend ref->scope, hard-remove legacy --name modifier syntax#413
Merged
barrettruth merged 1 commit intomainfrom Apr 26, 2026
Merged
Conversation
… syntax
Two related cleanups, no backwards compatibility kept.
1. ref -> scope rename in lua/forge/backends/{gitlab,codeberg}.lua.
The forge.Forge interface already declares the parameter as
scope?: forge.Scope and the github backend already uses 'scope';
the gitlab and codeberg backends are now consistent. The gitlab
module import was renamed from 'local scope = require("forge.scope")'
to 'local scope_mod = ...' to follow the convention used in init,
resolve, and log and to free 'scope' for the parameter name.
2. Hard-remove the legacy --name / --name=value modifier syntax from
:Forge. Only canonical name=value modifiers and bare flag tokens
(draft, fill, web, blank, all) are accepted. Drops the
legacy_modifiers / declared_legacy_modifiers fields on
forge.CommandVerbDef and forge.Command, the M.legacy_modifier_names
public function, the parser branch that stripped '--', the
completion-state branch, the legacy modifier-completion path, and
the legacy_flag block in M.complete.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
Two related cleanups, no backwards compatibility kept (per
AGENTS.md's"Backwards compatibility" rule).
(1) The
forge.Forgeinterface inlua/forge/types.luadeclaresmethods with
scope?: forge.Scope, and the github backend already usesscope. The gitlab and codeberg backends usedrefas the localparameter name, an unforced inconsistency that costs readability and
pattern-matching across backends. Issue #409.
(2)
:Forgeaccepted a legacy--name/--name=valuemodifiersyntax in parallel with the canonical
name=valueform. The legacysyntax was carried as documented "compatibility sugar", supported by a
parallel
legacy_modifiersfield onforge.CommandVerbDef/forge.Command, a separateM.legacy_modifier_namespublic function,dedicated branches in the parser and completion, and a separate
"
legacy_flag" path inM.complete. None of the verbs in the familiestable actually declared
legacy_modifiers, so the field was dormantproduction-wise — but the parsing/completion paths still accepted
--name=valuefor any modifier, providing a second way to do the samething.
Solution
(1) Mechanically rename
ref->scopeacross all methodsignatures and bodies in
lua/forge/backends/gitlab.luaandlua/forge/backends/codeberg.lua, plus the localrepo_arg(scope)/project(scope)/hostname(scope)helpers. Surgical reverts for'--ref'(CLI flag forglab ci list),entry.ref/json.head.ref/json.base.ref(external API field names), andnormalize_run's localref(a git ref likerefs/merge-requests/N/head, not a scope). Renamedgitlab.lua'smodule import from
local scope = require('forge.scope')tolocal scope_mod = ...to freescopefor parameter use and to matchthe convention already in
init.lua,resolve.lua, andlog.lua.(2) Hard-remove the legacy
--namesyntax. No deprecation, noshims:
forge.CommandVerbDef.legacy_modifiersandforge.Command.declared_legacy_modifiers/forge.Command.legacy_modifiersfields removed fromlua/forge/types.lua.M.legacy_modifier_namesremoved fromlua/forge/cmd.lua.token_is_modifier_likeno longer treats^--as modifier-like;only
name=valueand bare flag tokens are considered.if token:match('^--')branch and theparallel
legacy_modifiersallowed-set are gone. Onlyname=valueand bare flag tokens (when the modifier is declared
kind = 'flag')parse.
completion_stateandfiltered_modifier_completion_itemslosethe legacy branch and the
legacyparameter.M.completeloses thelegacy_flagblock at the top and the twoif arglead:match('^--')branches in family-slot andargument-slot completion.
completion_policy.declares_modifierno longer falls back tolegacy-modifier checks.
paragraph from the canonical-syntax section.
:Forge pr create --draft --fill --weband:Forge issue create --blank --template=bugtest cases updated tocanonical
draft fill web/blank template=bug.cmd.parse({ 'review', '42', '--wat=1' })test updated towat=1.User-visible: any
:Forgeinvocation that used--name/--name=valuemust switch to
name=value(or bare flag fordraft/fill/web/blank/all). Any tab-completion that previously offered--namecandidates after
--arglead no longer does. No migration window. Thecanonical syntax has been the documented primary interface throughout.
just ciclean: nix fmt, stylua, biome, selene, lua-language-servercheck, vimdoc-language-server, 633/0/0 busted.
Closes #409.