Repository navigation
chore(license): enforce licence headers on PowerShell files - #369
Conversation
19b9533 to
72b0311
Compare
|
Reviewed the diff. Looks correct, no issues. Two things I checked specifically rather than took on faith: the new The BOM-avoidance reasoning is sound too — a BOM really would survive into the CI is green ( |
juhovainio
left a comment
There was a problem hiding this comment.
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
left a comment
There was a problem hiding this comment.
🔴 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 newtypes_orentries conflict with a fix already merged onmain—.pre-commit-config.yaml:96,xtask/src/workflow_contract.rs:4159-4187(onmain, not touched by this diff).
Between this branch's merge-base and currentmain, a later commit (chore(hooks): close hawkeye pin/coverage gaps...) replaced thelicense-headershook'stypes_orfilter withalways_run: truespecifically so the hook no longer needs a file-type list kept in sync withlicenserc.toml'sincludes— the exact problem this PR solves instead by addingpowershell/markdowntags totypes_or.mainalso added a regression-guard test,license_headers_hook_has_no_file_type_filter, asserting the hook's block contains notypes_or:/types:/files:/exclude:key at all, andCONTRIBUTING.mdonmainnow documents "It has no file-type filter...". This PR's branch still carries the pre-existingtypes_orpattern (now with two more entries), predating thatmain-branch change. Runninggit merge-tree --write-tree --name-only origin/main pr/369reproduces a realCONFLICT (content) in .pre-commit-config.yaml. Landing this PR as-is — or rebasing it and keeping its version of that hunk — reintroduces the filtermaindeliberately removed and fails that regression test.
Confidence 100 · architectural · Fix: rebase onto currentmainand drop the.pre-commit-config.yamlhunk entirely —always_run: truealready fires the hook on.ps1/.md-only commits, so notypes_orchange is needed there. Keep thelicenserc.tomlandinstall.ps1changes:mainhas not added**/*.ps1toincludesor headeredinstall.ps1, so both remain necessary and merge cleanly. -
PSScriptAnalyzerSettings.psd1stays outside the license-header check this PR adds —licenserc.toml:18,PSScriptAnalyzerSettings.psd1:1.
PSScriptAnalyzerSettings.psd1is a tracked, un-headered PowerShell file in this repo (confirmed by reading its contents).pre-commit'sidentifylibrary classifies it with the samepowershelltag asinstall.ps1(identify.identify.tags_from_filenamereturns{'text', 'powershell'}for both.ps1and.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 newincludesentry is**/*.ps1only, so this already-existing file stays invisible tohawkeyeexactly the wayinstall.ps1was before this PR — and stays that way after it merges.
Confidence 85 · logic · Fix: either add**/*.psd1(and**/*.psm1, if one is ever added) toincludeswith a matching[[rules]]entry, or narrow the title/description to say the fix covers.ps1scripts specifically and note the.psd1gap as a follow-up.
Non-blocking
None
Decisions for the author
- Keeping
install.ps1BOM-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 breaksirm ... | iexparsing 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.ps1carrying©still trips the rule). - The
SuppressMessageAttributeis scoped to the single file via attribute placement rather than a blanketExcludeRulesentry inPSScriptAnalyzerSettings.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
left a comment
There was a problem hiding this comment.
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 newtypes_orentries conflict with a fix already merged onmain—.pre-commit-config.yaml:96.
Since this branch's base, a later commit onmainreplaced thelicense-headershook'stypes_orfilter withalways_run: true, specifically so the hook no longer needs a file-type list kept in sync withlicenserc.toml'sincludes— the exact problem this PR solves instead by addingpowershell/markdowntags totypes_or.mainalso added a regression test (license_headers_hook_has_no_file_type_filterinxtask/src/workflow_contract.rs) asserting the hook block has notypes_or:/types:/files:/exclude:key at all, andCONTRIBUTING.mdnow documents "It has no file-type filter...". I reproduced the conflict independently:git merge-tree --write-tree --name-only origin/main pr/369reportsCONFLICT (content) in .pre-commit-config.yaml, and the PR's livemergeablestatus isCONFLICTING.
Confidence 100 · architectural · Fix: rebase onto currentmainand drop the.pre-commit-config.yamlhunk entirely —always_run: truealready fires the hook on.ps1/.md-only commits, so notypes_orchange is needed there. Thelicenserc.tomlandinstall.ps1changes remain necessary and merge cleanly (verified: no conflict on those two files in the same merge-tree run). -
PSScriptAnalyzerSettings.psd1stays outside the license-header coverage this PR adds —licenserc.toml:18,PSScriptAnalyzerSettings.psd1:1.
PSScriptAnalyzerSettings.psd1is a tracked, un-headered PowerShell file (confirmed by reading its contents, both before and after this PR). I checked with theidentifylibrary directly:tags_from_filenamereturns{'text', 'powershell'}for both.ps1and.psd1, so the two files are the same "PowerShell file" category the PR's description refers to generically. The newincludesentry is**/*.ps1only, so this file stays invisible tohawkeyeexactly the wayinstall.ps1was before this PR, and stays that way after it merges.
Confidence 85 · logic · Fix: either add**/*.psd1(and**/*.psm1, should one appear) toincludeswith a matching[[rules]]entry, or narrow the title/description to say the fix covers.ps1scripts specifically and note the.psd1gap as a follow-up.
Non-blocking
None
Decisions for the author
- Keeping
install.ps1BOM-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 breaksirm ... | iexparsing (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
.ps1carrying©still trips the rule). - The
SuppressMessageAttributeis scoped to the single file via attribute placement rather than a blanketExcludeRulesentry inPSScriptAnalyzerSettings.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
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>
72b0311 to
6542bb3
Compare
|
Addressed in the force-push (rebased on
Two follow-on changes you should know about:
I also corrected the stale comments in |
Security scan found no critical or high findings on lines changed by this pull requestView 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
left a comment
There was a problem hiding this comment.
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
licenserctemplate conditional, theincludesand 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.
Summary
install.ps1is 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 didPSScriptAnalyzerSettings.psd1and.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 thelicense-headersCI job and by the prek hook) takes its file list fromlicenserc.toml'sincludes, which covered only.rs,.py,.shand.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
includesalone would not have been enough. hawkeye v7.0.0 has no built-in comment-style rule for theps1,psm1orpsd1extensions, so it classifies such files asunsupported, 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 withincludes, 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,**/*.psm1and**/*.psd1toincludes, plus the matching[[rules]]entry. (.psm1has no file in the repo today; it is listed so a future module is covered the same way.)install.ps1,PSScriptAnalyzerSettings.psd1and.github/scripts/Invoke-WslBash.ps1. The last two came into scope onceincludesmatched them; the headers were inserted byhawkeye format..ps1,.psm1,.psd1) get an ASCIICopyright (c), every other file type keeps the copyright sign.LICENSE.TXTalready uses the(c)form.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_filesinxtask/src/powershell.rs), and note that.psm1and.psd1are licence-checked but not linted.Why
(c)for PowerShell. A file with any non-ASCII byte needs a byte order mark to satisfy PSScriptAnalyzer'sPSUseBOMForUnicodeEncodedFile, andinstall.ps1cannot have one. A BOM is incompatible withirm ... | iex, which is the install command the README, the release notes and the nightly notes all publish:Invoke-RestMethodreturns 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 theparam()block is no longer the script's first statement, so all nine installer parameters silently vanish. Measured on a BOM'd copy: first characterU+FEFF, parse errors 0,ParamBlock present False— nothing announces the breakage.install.ps1already 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 onmain) 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-unknownon the real tree -> exit 0,615 files, 0 changes, 0 conflicts, 0 unsupported..rs,.py,.shand.mdfile, and in a scratch config the template and the old fixed text produce byte-identical headers for each of those types.install.ps1,Invoke-WslBash.ps1andPSScriptAnalyzerSettings.psd1with the copyright-sign header, or with the header removed, makeshawkeye checkreportreplace/addand exit 1;.rs,.py,.shand.mdfile given the(c)form is reportedreplaceand exits 1, so the conditional really is per extension;psd1removed from the[[rules]]extensions,hawkeye checkexits 0 and reports the fileunsupported; only--fail-on-unknownexits 1 (see above)..psm1with no header is reportedadd, 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 thatPSUseBOMForUnicodeEncodedFilestays silent because the files are ASCII again, which is the rule's documented behaviour (an ASCII file needs no BOM) and whatmainshows: both scripts are ASCII-only there and theLint (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.ps1is covered by CI alone.tests/e2e-cucumber/expectations.tomlfor the fixed ticket ID and removed/narrowed any now-stale xfail rows. — Not applicable: this fixes no product bug and involves no xfail rows.