gaelcolas / gaelcolas/Sampler

Add argument completer for `Build.ps1 -Tasks` to enable tab-expansion of task names

Open
#568 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
PowerShell
Stars
243
Forks
46
Avg merge
1h 41m
Merged PRs (30d)
1

Description

### Problem description

Build.ps1 exposes a rich set of tasks — imported from Sampler, from any additional task-providing modules (e.g. `Sampler.DscPipeline`), from tasks defined locally under .build, and from workflow aliases declared under `BuildWorkflow:` in build.yaml. Today the only way to discover them is to run `.Build.ps1 -Tasks ?`, read the list, and type a name back by hand.

Because `-Tasks` is a plain `[string[]]` parameter with no `ValidateSet` or `ArgumentCompleter`, PowerShell offers no tab-expansion. This is a small but very noticeable papercut in day-to-day use, especially on projects with many tasks and workflow aliases whose names are long, mix casing conventions, and contain underscores.

**Enhancement request:** Make `-Tasks` tab-completable in the Build.ps1 template that Sampler ships, so that pressing `Tab` after `-Tasks ` (or after a partial task name) cycles through the available tasks and workflow aliases.

### How to reproduce

1. Scaffold any Sampler-based project (e.g. via `New-SampleModule` or a `Sampler.DscPipeline`-based project).
2. Run `.Build.ps1 -Tasks ` and press `Tab`.
3. Observe that PowerShell offers no completions.

### Expected behavior

Pressing `Tab` after `-Tasks ` completes to available task names — for example, typing `Comp` would cycle through `CompileDatumRsop`, `CompileRootConfiguration`, `CompileRootMetaMof`, `Compress_Artifact_Collections`, `CompressModulesWithChecksum`, etc.

The completions should include:

- Workflow aliases defined under `BuildWorkflow:` in build.yaml (e.g. `build`, `pack`, `.`).
- Tasks defined locally under `./.build/**/*.ps1`.
- Tasks imported from Sampler and any other task-providing module, i.e. tasks discovered under `./output/RequiredModules/**/*.build.ps1`.
- The built-in `?` token used to list tasks.

### Current behavior

No completions are offered. Users must run `.Build.ps1 -Tasks ?` and type task names manually, which is error-prone.

### Suggested solution

Attach an `ArgumentCompleter` to the `$Tasks` parameter in the Build.ps1 template(s) Sampler ships. The completer should:

- Be self-contained and have no dependency on Sampler or Invoke-Build being loaded, so it works in a fresh shell where `Resolve-Dependency` has not run yet. In that state it would only offer local tasks and workflow aliases, which is the correct behavior.
- Discover task names by textual scanning (looking for `task ` declarations) rather than by dot-sourcing task files, to avoid side effects and keep completion fast.
- Discover workflow aliases by parsing the top-level keys under `BuildWorkflow:` in build.yaml.
- De-duplicate case-insensitively, sort alphabetically, and filter by the partially typed word.
- Fail silently (no errors surfaced to the user) if any of the source locations are missing or unreadable.

Rolling this into the template means every Sampler-based project gets tab-completion out of the box, without per-project changes.

### Verbose logs

N/A — this is an enhancement request.

### Operating system the target node is running

```text
Windows 11 (PowerShell 7.5.5). Behavior is independent of OS / PS edition;
ArgumentCompleter has been supported since PowerShell 5.0.
```

### PowerShell version and build the target node is running

```text
PSVersion 7.5.5
PSEdition Core
```

### Module version used

```text
Sampler (current main) — affects all versions that ship the Build.ps1 template.
```

Contributor guide

Open the contributing guide

Research direction

Start with the Build.ps1 template(s) Sampler ships and the existing -Tasks parameter. Inspect task declarations under .build/**/*.ps1 and output/RequiredModules/**/*.build.ps1, plus BuildWorkflow: keys in build.yaml; done means fresh shells offer matching, sorted, case-insensitively deduplicated local tasks, aliases, and ? without surfacing errors.

Written by the indexing model from the issue text.

Assessment

Tech stack
powershell
Domain
build-system, cli
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.