Skip to content

chore(license): enforce licence headers on PowerShell files - #369

Merged
siloteemu merged 1 commit into
mainfrom
chore/license-header-powershell
Nov 17, 2026
Merged

siloteemu merged 1 commit into
mainfrom
chore/license-header-powershell

Conversation

@siloteemu

@siloteemu siloteemu commented Sep 9, 2026 •

Copy link
Copy Markdown
Contributor

Summary

install.ps1 is the Windows installer — one of the first files anyone reads before running anything from this project — and it shipped with no copyright or licence header. So did PSScriptAnalyzerSettings.psd1 and .github/scripts/Invoke-WslBash.ps1.

The licence-header check did not catch any of them, and would not have caught a future PowerShell file either. hawkeye (run by the license-headers CI job and by the prek hook) takes its file list from licenserc.toml's includes, which covered only .rs, .py, .sh and .md. PowerShell files were invisible to it, so the check was passing because it never looked at them, not because they complied.

The non-obvious part: adding the globs to includes alone would not have been enough. hawkeye v7.0.0 has no built-in comment-style rule for the ps1, psm1 or psd1 extensions, so it classifies such files as unsupported, skips them silently, and still exits 0 — surfaced only under --fail-on-unknown, which neither the CI job nor the prek hook passes. The explicit [[rules]] entry (style_out = "script") is what makes the check actually enforce anything. It is load-bearing, not redundant with includes, and the config carries a comment saying so, so it is not pruned later as dead weight. Because neither CI nor the hook passes the flag, deleting that entry would still leave the check green; this PR documents the hazard but does not change how hawkeye is invoked.

Changes (one commit)

  • licenserc.toml: add **/*.ps1, **/*.psm1 and **/*.psd1 to includes, plus the matching [[rules]] entry. (.psm1 has no file in the repo today; it is listed so a future module is covered the same way.)
  • Add the missing header to install.ps1, PSScriptAnalyzerSettings.psd1 and .github/scripts/Invoke-WslBash.ps1. The last two came into scope once includes matched them; the headers were inserted by hawkeye format.
  • Make the header text a template with one conditional: PowerShell files (.ps1, .psm1, .psd1) get an ASCII Copyright (c), every other file type keeps the copyright sign. LICENSE.TXT already uses the (c) form.
  • Correct the comments in PSScriptAnalyzerSettings.psd1, which named scripts that do not exist (scripts/*.ps1, "acceptance/packaging scripts"). They now say the lint covers every tracked .ps1 (discover_ps1_files in xtask/src/powershell.rs), and note that .psm1 and .psd1 are licence-checked but not linted.

Why (c) for PowerShell. A file with any non-ASCII byte needs a byte order mark to satisfy PSScriptAnalyzer's PSUseBOMForUnicodeEncodedFile, and install.ps1 cannot have one. A BOM is incompatible with irm ... | iex, which is the install command the README, the release notes and the nightly notes all publish: Invoke-RestMethod returns a string, not a file, so the mark survives into it and the parser glues it onto the following token. The leading comment becomes a command named #, and the param() block is no longer the script's first statement, so all nine installer parameters silently vanish. Measured on a BOM'd copy: first character U+FEFF, parse errors 0, ParamBlock present False — nothing announces the breakage. install.ps1 already carries a comment saying it is kept ASCII-only for exactly this reason, and an earlier revision of this PR broke that by adding the copyright sign; with (c) the file is ASCII-only again (0 non-ASCII bytes, as on main) and needs no analyzer suppression. The other two PowerShell files follow so the family reads the same.

Risk: low — comment headers and check configuration; no product code path changes. No Gherkin scenario is added: nothing a CLI user can observe changes, so this falls under the carve-out for purely internal changes.

Test plan

With the pinned hawkeye v7.0.0 (the aarch64 build of that release, run locally):

  • hawkeye check --fail-on-unknown on the real tree -> exit 0, 615 files, 0 changes, 0 conflicts, 0 unsupported.
  • Headers of non-PowerShell files are unchanged: the check is green over every existing .rs, .py, .sh and .md file, and in a scratch config the template and the old fixed text produce byte-identical headers for each of those types.
  • Negative cases, showing the check is not passing vacuously:
    • each of install.ps1, Invoke-WslBash.ps1 and PSScriptAnalyzerSettings.psd1 with the copyright-sign header, or with the header removed, makes hawkeye check report replace/add and exit 1;
    • a .rs, .py, .sh and .md file given the (c) form is reported replace and exits 1, so the conditional really is per extension;
    • with psd1 removed from the [[rules]] extensions, hawkeye check exits 0 and reports the file unsupported; only --fail-on-unknown exits 1 (see above).
  • A new .psm1 with no header is reported add, so that extension is enforced too.
  • grep -P '[^\x00-\x7F]' finds no non-ASCII byte in any of the three PowerShell files.

Not run locally: PSScriptAnalyzer — there is no PowerShell on the machine this was prepared on, so the Lint (PowerShell) job (PowerShell 7 and Windows PowerShell 5.1) is the only check of the two scripts. The expectation is that PSUseBOMForUnicodeEncodedFile stays silent because the files are ASCII again, which is the rule's documented behaviour (an ASCII file needs no BOM) and what main shows: both scripts are ASCII-only there and the Lint (PowerShell) job reports success on its head. That job only runs its analyzer steps when the change filter flags lint-relevant files, so this is suggestive rather than proof. Invoke-WslBash.ps1 is covered by CI alone.

  • If this PR fixes a bug, searched tests/e2e-cucumber/expectations.toml for the fixed ticket ID and removed/narrowed any now-stale xfail rows. — Not applicable: this fixes no product bug and involves no xfail rows.

@siloteemu
siloteemu force-pushed the chore/license-header-powershell branch from 19b9533 to 72b0311 Compare September 9, 2026 10:07
@siloteemu
siloteemu marked this pull request as ready for review September 9, 2026 10:32
@siloteemu
siloteemu requested a review from a team as a code owner September 9, 2026 10:32
@siloteemu
siloteemu requested a review from fredespi September 9, 2026 10:32
@juhovainio

Copy link
Copy Markdown
Collaborator

Reviewed the diff. Looks correct, no issues.

Two things I checked specifically rather than took on faith: the new [[rules]] block in licenserc.toml really is load-bearing, not redundant with includes — hawkeye has no built-in comment style for .ps1, so without that rule the file would be silently marked unsupported and skipped at exit 0, matching the PR's own negative test. And the SuppressMessageAttribute placement directly before param() in install.ps1 is the correct documented spot for a script-level (rather than function-level) PSScriptAnalyzer suppression.

The BOM-avoidance reasoning is sound too — a BOM really would survive into the irm | iex string and silently drop the param block with zero parse errors, so keeping the file BOM-less and suppressing just this one rule for just this one file is the right call over the alternative of adding a BOM.

CI is green (Lint (PowerShell) in particular exercises this exact file/config combo). Looks safe to approve.

@juhovainio juhovainio left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirmed as low-risk config/tooling. The [[rules]] block in licenserc.toml is genuinely load-bearing — hawkeye has no built-in comment style for .ps1, so without it the file is silently classified unsupported and skipped. The SuppressMessageAttribute placement in install.ps1 is the correct documented spot for a script-level PSScriptAnalyzer suppression, and the BOM-avoidance reasoning behind it is sound. CI is green. Approving.

@nowycondro nowycondro left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 Automated review · pr-review-watcher · 72b0311

Review — needs work

Full review of the whole change (3 files, 25 insertions, 1 deletion — reviewed as a single pass, per the change's size).
No ticket named. The PR description is thorough and accurate about what the diff itself does; see Blocking #2 for where the title/description's framing ("PowerShell files", generically) outruns what licenserc.toml ends up covering.

Blocking

  • .pre-commit-config.yaml's new types_or entries conflict with a fix already merged on main — .pre-commit-config.yaml:96, xtask/src/workflow_contract.rs:4159-4187 (on main, not touched by this diff).
    Between this branch's merge-base and current main, a later commit (chore(hooks): close hawkeye pin/coverage gaps...) replaced the license-headers hook's types_or filter with always_run: true specifically so the hook no longer needs a file-type list kept in sync with licenserc.toml's includes — the exact problem this PR solves instead by adding powershell/markdown tags to types_or. main also added a regression-guard test, license_headers_hook_has_no_file_type_filter, asserting the hook's block contains no types_or:/types:/files:/exclude: key at all, and CONTRIBUTING.md on main now documents "It has no file-type filter...". This PR's branch still carries the pre-existing types_or pattern (now with two more entries), predating that main-branch change. Running git merge-tree --write-tree --name-only origin/main pr/369 reproduces a real CONFLICT (content) in .pre-commit-config.yaml. Landing this PR as-is — or rebasing it and keeping its version of that hunk — reintroduces the filter main deliberately removed and fails that regression test.
    Confidence 100 · architectural · Fix: rebase onto current main and drop the .pre-commit-config.yaml hunk entirely — always_run: true already fires the hook on .ps1/.md-only commits, so no types_or change is needed there. Keep the licenserc.toml and install.ps1 changes: main has not added **/*.ps1 to includes or headered install.ps1, so both remain necessary and merge cleanly.

  • PSScriptAnalyzerSettings.psd1 stays outside the license-header check this PR adds — licenserc.toml:18, PSScriptAnalyzerSettings.psd1:1.
    PSScriptAnalyzerSettings.psd1 is a tracked, un-headered PowerShell file in this repo (confirmed by reading its contents). pre-commit's identify library classifies it with the same powershell tag as install.ps1 (identify.identify.tags_from_filename returns {'text', 'powershell'} for both .ps1 and .psd1). The PR's title and description frame the fix generically as covering "PowerShell files" ("would not have caught any future PowerShell file either"), but the new includes entry is **/*.ps1 only, so this already-existing file stays invisible to hawkeye exactly the way install.ps1 was before this PR — and stays that way after it merges.
    Confidence 85 · logic · Fix: either add **/*.psd1 (and **/*.psm1, if one is ever added) to includes with a matching [[rules]] entry, or narrow the title/description to say the fix covers .ps1 scripts specifically and note the .psd1 gap as a follow-up.

Non-blocking

None

Decisions for the author

  • Keeping install.ps1 BOM-less accepts permanent mojibake in the header comment under Windows PowerShell 5.1 — tradeoff. Already reasoned through and tested in the PR (a BOM silently breaks irm ... | iex parsing vs. cosmetic mojibake without one). Flagging only so it's an explicit, confirmed choice rather than an accepted stopgap: the © in that comment renders as mojibake for every 5.1 user, indefinitely.

Positive signals

  • The BOM-vs-parse-break investigation is unusually rigorous: it measures actual parse results (ParamBlock present True/False, first-byte/char values) rather than reasoning from documentation alone, and records a negative control (a fresh .ps1 carrying © still trips the rule).
  • The SuppressMessageAttribute is scoped to the single file via attribute placement rather than a blanket ExcludeRules entry in PSScriptAnalyzerSettings.psd1, so the rule keeps protecting every other (and future) PowerShell file — a deliberately narrow fix.
  • Three atomic, well-explained commits, each independently SSH-signed and DCO'd, each describing a distinct root cause rather than being squashed into one "fix" commit.

Deployment notes

This PR cannot land as currently written: rebasing onto current main surfaces a real .pre-commit-config.yaml merge conflict (Blocking #1). Whoever merges it needs to resolve that in main's favor (drop the PR's types_or hunk) rather than taking the PR's version of that file.

What this covered

Every line of the diff (.pre-commit-config.yaml, install.ps1, licenserc.toml) read in full against the merge-base and the PR head (03c46b58…72b03114). Also read: current origin/main tip for the same three files plus xtask/src/workflow_contract.rs and CONTRIBUTING.md, to check what main had changed since this branch diverged; git merge-tree run read-only to confirm the conflict; the identify Python package queried directly to verify the file-type-tag claims; each commit object inspected for an SSH signature and DCO sign-off; gh pr view --json statusCheckRollup showing every applicable check green (E2E jobs skipped as expected for a non-code change).

Did not run: multi-worker fan-out — the whole change is 3 files / 25 lines, small enough for one pass per this method's sizing rule, so it was read as a single pass rather than split across workers. Prior-changes pass: the PR's one existing review is an approval carrying no findings text to reconcile; per this method, only its metadata (author, state, head commit) was used, to confirm no existing review from this account needed updating — its content was not read as input to any finding above.

Not reconciled against any discussion on the PR.

@juhovainio juhovainio left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review — needs work

Full review of the whole change (3 files, .pre-commit-config.yaml, install.ps1, licenserc.toml).
No ticket named. The description accurately matches the diff's three commits.

Blocking

  • .pre-commit-config.yaml's new types_or entries conflict with a fix already merged on main — .pre-commit-config.yaml:96.
    Since this branch's base, a later commit on main replaced the license-headers hook's types_or filter with always_run: true, specifically so the hook no longer needs a file-type list kept in sync with licenserc.toml's includes — the exact problem this PR solves instead by adding powershell/markdown tags to types_or. main also added a regression test (license_headers_hook_has_no_file_type_filter in xtask/src/workflow_contract.rs) asserting the hook block has no types_or:/types:/files:/exclude: key at all, and CONTRIBUTING.md now documents "It has no file-type filter...". I reproduced the conflict independently: git merge-tree --write-tree --name-only origin/main pr/369 reports CONFLICT (content) in .pre-commit-config.yaml, and the PR's live mergeable status is CONFLICTING.
    Confidence 100 · architectural · Fix: rebase onto current main and drop the .pre-commit-config.yaml hunk entirely — always_run: true already fires the hook on .ps1/.md-only commits, so no types_or change is needed there. The licenserc.toml and install.ps1 changes remain necessary and merge cleanly (verified: no conflict on those two files in the same merge-tree run).

  • PSScriptAnalyzerSettings.psd1 stays outside the license-header coverage this PR adds — licenserc.toml:18, PSScriptAnalyzerSettings.psd1:1.
    PSScriptAnalyzerSettings.psd1 is a tracked, un-headered PowerShell file (confirmed by reading its contents, both before and after this PR). I checked with the identify library directly: tags_from_filename returns {'text', 'powershell'} for both .ps1 and .psd1, so the two files are the same "PowerShell file" category the PR's description refers to generically. The new includes entry is **/*.ps1 only, so this file stays invisible to hawkeye exactly the way install.ps1 was before this PR, and stays that way after it merges.
    Confidence 85 · logic · Fix: either add **/*.psd1 (and **/*.psm1, should one appear) to includes with a matching [[rules]] entry, or narrow the title/description to say the fix covers .ps1 scripts specifically and note the .psd1 gap as a follow-up.

Non-blocking

None

Decisions for the author

  • Keeping install.ps1 BOM-less accepts permanent mojibake in the header comment under Windows PowerShell 5.1 — tradeoff.
    Already reasoned through and tested in the PR: a BOM in this file breaks irm ... | iex parsing (the param block silently stops being the first statement, with zero parse errors) versus cosmetic mojibake in a comment without one. Flagging only so it stays an explicit, confirmed choice: the © in that comment renders as mojibake for every PowerShell 5.1 user, indefinitely.

Positive signals

  • The BOM-vs-parse-break investigation is unusually rigorous: it measures actual parse results rather than reasoning from documentation alone, and records a negative control (a fresh .ps1 carrying © still trips the rule).
  • The SuppressMessageAttribute is scoped to the single file via attribute placement rather than a blanket ExcludeRules entry in PSScriptAnalyzerSettings.psd1, so the rule keeps protecting every other PowerShell file.
  • Three atomic, DCO-signed commits, each describing a distinct root cause rather than being squashed into one commit.

Deployment notes

This PR cannot land as currently written: rebasing onto current main surfaces a real .pre-commit-config.yaml merge conflict (see Blocking). Whoever merges it needs to resolve that in main's favor (drop this PR's types_or hunk) rather than taking this PR's version of that file.

What this covered

Every line of the diff (.pre-commit-config.yaml, install.ps1, licenserc.toml) read in full against the merge-base and the PR head. Reviewed as a single pass (3 files, small change). Also read: current origin/main tip for the same three files plus xtask/src/workflow_contract.rs and CONTRIBUTING.md to see what changed since this branch diverged; git merge-tree run read-only to confirm the conflict and GitHub's own mergeable/mergeStateStatus fields to corroborate it; the identify Python package queried directly to verify the file-tagging claim; commit history of .pre-commit-config.yaml/licenserc.toml to confirm when and why the conflicting main change landed; each commit's trailers checked for DCO sign-off; CI status checked via the forge API, all applicable checks green (self-hosted E2E lanes skipped as expected for a non-code change).

Did not run: multi-worker fan-out — the whole change is 3 files / ~25 lines, small enough for one pass per this method's sizing rule. History/prior-changes passes were folded into the single pass rather than run separately, given the size.
Not reconciled against any discussion on the PR.


🤖 Automated by an AI agent

Comment thread .pre-commit-config.yaml Resolved
Comment thread licenserc.toml Resolved
install.ps1 shipped without the MIT/copyright header that every other
source file in the repo carries, because the header check never looked at
PowerShell files at all: `licenserc.toml` did not include them. The same
was true of PSScriptAnalyzerSettings.psd1 and of the WSL helper script
under .github/scripts, which also had no header.

Adding the globs alone is not enough. hawkeye has no built-in comment style
for the `ps1`, `psm1` or `psd1` extensions, so a file matched by `includes`
but with no matching rule is classified `unsupported` and silently skipped
while the command still exits 0 -- the check would look green without
inspecting the file. The explicit `[[rules]]` block mapping those extensions
to the `script` comment style is what makes the files actually get checked.
Only `hawkeye check --fail-on-unknown` exposes the gap, and neither the CI job
nor the hook passes it.

PowerShell files get an ASCII `Copyright (c)` header, rendered from a
conditional in the header template, instead of the copyright sign the other
file types use. A file with any non-ASCII byte needs a byte order mark to
satisfy PSScriptAnalyzer, and install.ps1 cannot have one: the documented
install path is `irm ... | iex`, which hands the parser a string, so the mark
survives into it and the param() block stops being the script's first
statement, silently dropping every installer parameter. Keeping the headers
ASCII leaves install.ps1 as ASCII-only as its existing comment says and needs
no analyzer suppression. The other PowerShell files follow for consistency,
and LICENSE.TXT already uses the `(c)` form. Headers for every other file type
render byte-for-byte as before.

The license-headers hook already runs on every commit (it has no file-type
filter), so no hook change is needed: a PowerShell-only edit reaches it.

PSScriptAnalyzerSettings.psd1's comments named scripts that do not exist; they
now describe what the lint covers (every tracked .ps1) and note that .psm1 and
.psd1 are licence-checked but not linted.

Signed-off-by: Teemu Kuusisto <teemu.kuusisto@amd.com>
@siloteemu
siloteemu force-pushed the chore/license-header-powershell branch from 72b0311 to 6542bb3 Compare November 17, 2026 13:32
@siloteemu

Copy link
Copy Markdown
Contributor Author

Addressed in the force-push (rebased on main, now a single commit):

  1. .pre-commit-config.yaml: the types_or hunk and the Markdown-only commit are dropped; the file is identical to main. always_run: true already runs the hook on PowerShell-only and Markdown-only commits.
  2. .psd1 coverage: took the first option. licenserc.toml now includes **/*.ps1, **/*.psm1 and **/*.psd1 with one [[rules]] entry for all three, and PSScriptAnalyzerSettings.psd1 has its header.

Two follow-on changes you should know about:

  • Rebasing surfaced .github/scripts/Invoke-WslBash.ps1, added on main after this branch was cut. It had no header, so the check would have failed on it; it has one now.
  • The PowerShell headers now use an ASCII Copyright (c) (a per-extension conditional in the header template; other file types are unchanged). This replaces the earlier BOM-less-plus-suppression approach: with no non-ASCII byte there is no BOM question, install.ps1 is ASCII-only again as its own comment says, and no analyzer suppression is needed.

I also corrected the stale comments in PSScriptAnalyzerSettings.psd1. The PR description is updated to match the diff. PSScriptAnalyzer could not be run where this was prepared, so Lint (PowerShell) in CI is the check for the two scripts.

@siloteemu
siloteemu requested a review from juhovainio November 17, 2026 13:33
@github-actions

Copy link
Copy Markdown
Contributor
Security scan found no critical or high findings on lines changed by this pull request

View the security scan run for complete reports.

“New” means the finding is located in a changed file on an added or modified line; it is not a base-versus-head findings delta.

@juhovainio juhovainio left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good. The diff is comment and config only, and the claims in the new comments check out against the code (discover_ps1_files in xtask/src/powershell.rs uses git ls-files '*.ps1', and the prek hook is files: \.ps1$). Headers are ASCII, nothing internal leaks, single signed commit.

Two non-blocking notes:

  • The PowerShell extension list is repeated in the licenserc template conditional, the includes and the [[rules]] entry; a future edit could update one and miss the others.
  • The [[rules]] entry that carries the enforcement is guarded only by a comment, since CI and prek don't pass --fail-on-unknown. Passing that flag in CI would be a cheap follow-up.

Lint (PowerShell) is the only check on the two scripts, so please let it finish green before merging.

@siloteemu
siloteemu added this pull request to the merge queue Nov 17, 2026
Merged via the queue into main with commit f4b9945 Nov 17, 2026
48 checks passed
@siloteemu
siloteemu deleted the chore/license-header-powershell branch November 17, 2026 17:33
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.

3 participants