Skip to content

refactor: rename backend ref->scope, hard-remove legacy --name modifier syntax#413

Merged
barrettruth merged 1 commit intomainfrom
refactor/rename-ref-to-scope
Apr 26, 2026
Merged

refactor: rename backend ref->scope, hard-remove legacy --name modifier syntax#413
barrettruth merged 1 commit intomainfrom
refactor/rename-ref-to-scope

Conversation

@barrettruth
Copy link
Copy Markdown
Owner

Problem

Two related cleanups, no backwards compatibility kept (per AGENTS.md's
"Backwards compatibility" rule).

(1) The forge.Forge interface in lua/forge/types.lua declares
methods with scope?: forge.Scope, and the github backend already uses
scope. The gitlab and codeberg backends used ref as the local
parameter name, an unforced inconsistency that costs readability and
pattern-matching across backends. Issue #409.

(2) :Forge accepted a legacy --name / --name=value modifier
syntax in parallel with the canonical name=value form. The legacy
syntax was carried as documented "compatibility sugar", supported by a
parallel legacy_modifiers field on forge.CommandVerbDef /
forge.Command, a separate M.legacy_modifier_names public function,
dedicated branches in the parser and completion, and a separate
"legacy_flag" path in M.complete. None of the verbs in the families
table actually declared legacy_modifiers, so the field was dormant
production-wise — but the parsing/completion paths still accepted
--name=value for any modifier, providing a second way to do the same
thing.

Solution

(1) Mechanically rename ref -> scope across all method
signatures and bodies in lua/forge/backends/gitlab.lua and
lua/forge/backends/codeberg.lua, plus the local repo_arg(scope) /
project(scope) / hostname(scope) helpers. Surgical reverts for
'--ref' (CLI flag for glab ci list), entry.ref /
json.head.ref / json.base.ref (external API field names), and
normalize_run's local ref (a git ref like
refs/merge-requests/N/head, not a scope). Renamed gitlab.lua's
module import from local scope = require('forge.scope') to
local scope_mod = ... to free scope for parameter use and to match
the convention already in init.lua, resolve.lua, and log.lua.

(2) Hard-remove the legacy --name syntax. No deprecation, no
shims:

  • forge.CommandVerbDef.legacy_modifiers and
    forge.Command.declared_legacy_modifiers /
    forge.Command.legacy_modifiers fields removed from
    lua/forge/types.lua.
  • M.legacy_modifier_names removed from lua/forge/cmd.lua.
  • token_is_modifier_like no longer treats ^-- as modifier-like;
    only name=value and bare flag tokens are considered.
  • Parser body simplified: the if token:match('^--') branch and the
    parallel legacy_modifiers allowed-set are gone. Only name=value
    and bare flag tokens (when the modifier is declared kind = 'flag')
    parse.
  • completion_state and filtered_modifier_completion_items lose
    the legacy branch and the legacy parameter.
  • M.complete loses the legacy_flag block at the top and the two
    if arglead:match('^--') branches in family-slot and
    argument-slot completion.
  • completion_policy.declares_modifier no longer falls back to
    legacy-modifier checks.
  • Help text drops the "Compatibility sugar is still accepted ..."
    paragraph from the canonical-syntax section.
  • :Forge pr create --draft --fill --web and
    :Forge issue create --blank --template=bug test cases updated to
    canonical draft fill web / blank template=bug.
  • cmd.parse({ 'review', '42', '--wat=1' }) test updated to
    wat=1.

User-visible: any :Forge invocation that used --name / --name=value
must switch to name=value (or bare flag for draft / fill / web /
blank / all). Any tab-completion that previously offered --name
candidates after -- arglead no longer does. No migration window. The
canonical syntax has been the documented primary interface throughout.

just ci clean: nix fmt, stylua, biome, selene, lua-language-server
check, vimdoc-language-server, 633/0/0 busted.

Closes #409.

… 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.
@barrettruth barrettruth merged commit 50c7a13 into main Apr 26, 2026
3 checks passed
@barrettruth barrettruth deleted the refactor/rename-ref-to-scope branch April 26, 2026 19:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

refactor: align gitlab/codeberg parameter names with forge.Scope (ref → scope)

1 participant