Skip to content

Commit d009d39

Browse files
chore: sync PowerShell standards 2.0.0 (#60)
Co-authored-by: fadwen <110697945+fadwen@users.noreply.github.com>
1 parent 51e01d2 commit d009d39

14 files changed

Lines changed: 1159 additions & 63 deletions

File tree

‎.agents/skills/powershell-logging/SKILL.md‎

Lines changed: 320 additions & 0 deletions
Large diffs are not rendered by default.

‎.agents/skills/powershell-review/SKILL.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,10 +26,15 @@ loaded. Every rule has an ID such as `ERR-10`; cite it.
2626
4. Confirm each finding before reporting it. Read the surrounding code, and where behaviour is in
2727
doubt, run a small test. Do not report a rule violation in code that the change did not touch,
2828
unless it is a defect.
29+
5. A comment of the form `# Exception to ERR-11: reason` records a decision of the project (DOC-22).
30+
Do not report the code under it as a finding of that rule. Do report the comment when its reason
31+
is missing or no longer matches the code. A comment that names a security rule (SEC) excuses
32+
nothing: report the finding, and the comment. Do not propose such a comment as the fix for a
33+
finding.
2934

3035
## Report
3136

3237
List findings with the most serious first. For each one give the file and line, the rule ID or the
3338
word "defect", what is wrong, and the corrected code. Separate requirements (MUST) from
34-
recommendations (SHOULD). State what you ran and what you did not check. If nothing is wrong, say so;
35-
do not invent findings.
39+
recommendations (SHOULD). List the recorded exceptions with their reasons, apart from the findings.
40+
State what you ran and what you did not check. If nothing is wrong, say so; do not invent findings.

‎.claude/skills/powershell-logging/SKILL.md‎

Lines changed: 320 additions & 0 deletions
Large diffs are not rendered by default.

‎.claude/skills/powershell-review/SKILL.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,10 +26,15 @@ loaded. Every rule has an ID such as `ERR-10`; cite it.
2626
4. Confirm each finding before reporting it. Read the surrounding code, and where behaviour is in
2727
doubt, run a small test. Do not report a rule violation in code that the change did not touch,
2828
unless it is a defect.
29+
5. A comment of the form `# Exception to ERR-11: reason` records a decision of the project (DOC-22).
30+
Do not report the code under it as a finding of that rule. Do report the comment when its reason
31+
is missing or no longer matches the code. A comment that names a security rule (SEC) excuses
32+
nothing: report the finding, and the comment. Do not propose such a comment as the fix for a
33+
finding.
2934

3035
## Report
3136

3237
List findings with the most serious first. For each one give the file and line, the rule ID or the
3338
word "defect", what is wrong, and the corrected code. Separate requirements (MUST) from
34-
recommendations (SHOULD). State what you ran and what you did not check. If nothing is wrong, say so;
35-
do not invent findings.
39+
recommendations (SHOULD). List the recorded exceptions with their reasons, apart from the findings.
40+
State what you ran and what you did not check. If nothing is wrong, say so; do not invent findings.

‎.github/copilot-instructions.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ These are the rules for writing and reviewing PowerShell in this repository. **M
1010

1111
- Apply them to code you write or change. Do not reformat or rewrite code the task does not touch.
1212
- An explicit instruction from the user takes precedence. If following it breaks a MUST, say which
13-
one.
13+
one. A departure that is meant to stay is recorded in the code (DOC-22). Leave a recorded
14+
departure as it is, and do not record one that the user has not decided.
1415
- Do not invent facts: no made-up module names, version numbers, measurements, links, or authors. Ask,
1516
or leave it out.
1617
- When you can run commands, run PSScriptAnalyzer and the tests before you report the work as done,

‎.github/instructions/pester-supporting-docs/cicd-integration.md‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -43,11 +43,14 @@ Three more facts shape the jobs:
4343
without coverage for feedback, and a separate sequential job with the profiler for the gate.
4444
2. A file that fails discovery adds nothing to `FailedCount`. Every gate checks `Result`, and a
4545
cheap discovery-only job runs first.
46-
3. Pester 6.0 and 6.1 do not import on PowerShell 7.4.0 to 7.4.5. Their `net8.0` assembly referred
47-
to a newer `System.Management.Automation` than those releases carry, so `Import-Module` failed
48-
with `Cannot convert "PesterConfigurationDeserializer" from String to Type`. Pester 6.2 fixed it.
49-
Hosted runners carry the latest patch release, so this bites self-hosted agents and pinned
50-
container images; the pin on Pester 6.2.0 (CIC-02) avoids it.
46+
3. Pester 6.0.0, 6.0.1, and 6.1.0 do not import on PowerShell 7.4.0 to 7.4.4. Their `net8.0`
47+
assembly refers to `System.Management.Automation` 7.4.5.0, which those releases do not carry, so
48+
`Import-Module` fails where the module registers its type converter. The error is
49+
`Cannot convert the "PesterConfigurationDeserializer" value of type "System.String" to type "System.Type"`.
50+
The three versions import on 7.4.5 and later. The assembly of Pester 6.2.0 refers to 7.4.0.0,
51+
and that version imports on every 7.4 release. Measured on Linux, macOS, and Windows with
52+
PowerShell 7.4.0 to 7.4.7 and 7.4.22. Hosted runners carry the latest patch release, so this
53+
bites self-hosted agents and pinned container images; the pin on Pester 6.2.0 (CIC-02) avoids it.
5154

5255
```text
5356
validate (discovery only, fast)

‎.github/instructions/pester-supporting-docs/v6-migration.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -437,10 +437,13 @@ Describe 'Get-User' -Tag 'Unit' {
437437
reproducible, which was not checked for this guide.
438438
- `IO exception during a TestRegistry operation, retrying.` is a debug message. In 6.1 it was a
439439
warning, shown when the retry recovered. This was read from the source of both versions.
440-
- Pester imports again on PowerShell 7.4.0 to 7.4.5. 6.0 and 6.1 failed there with
441-
`Cannot convert "PesterConfigurationDeserializer" from String to Type`, because the `net8.0`
442-
assembly referenced a newer `System.Management.Automation` than those releases carry. Those
443-
PowerShell versions were not available, so this was not run for this guide.
440+
- Pester imports again on PowerShell 7.4.0 to 7.4.4. 6.0.0, 6.0.1, and 6.1.0 fail there, because
441+
their `net8.0` assembly refers to `System.Management.Automation` 7.4.5.0, which those releases do
442+
not carry. The error is
443+
`Cannot convert the "PesterConfigurationDeserializer" value of type "System.String" to type "System.Type"`.
444+
The assembly of 6.2.0 refers to 7.4.0.0. Run for this guide on Linux, macOS, and Windows: the
445+
three earlier versions failed on 7.4.0 to 7.4.4 and imported on 7.4.5, 7.4.6, 7.4.7, and 7.4.22,
446+
and 6.2.0 imported and ran a test on all nine releases.
444447

445448
### Verifying the Upgrade to 6.2
446449

‎.github/instructions/powershell-cicd.instructions.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -124,9 +124,11 @@ The runner and the Pester settings files are kept in the `Tests` folder. A `buil
124124
`Tests` is the alternative; both are one level below the repository root, so the scripts are the
125125
same in either.
126126

127-
**CIC-02.** The pin also avoids a known failure: Pester 6.0 and 6.1 do not import on PowerShell
128-
7.4.0 to 7.4.5 (`Cannot convert "PesterConfigurationDeserializer" from String to Type`), which
129-
bites self-hosted agents and pinned container images. Pester 6.2 fixed it.
127+
**CIC-02.** The pin also avoids a known failure: Pester 6.0.0, 6.0.1, and 6.1.0 do not import on
128+
PowerShell 7.4.0 to 7.4.4, which bites self-hosted agents and pinned container images. The error is
129+
`Cannot convert the "PesterConfigurationDeserializer" value of type "System.String" to type "System.Type"`.
130+
Pester 6.2.0 imports on every 7.4 release. Measured on Linux, macOS, and Windows with PowerShell
131+
7.4.0 to 7.4.7 and 7.4.22.
130132

131133
A commit ID is the stricter choice for CIC-09, because a tag can be moved. Write the tag after it in a
132134
comment, as in `actions/checkout@<commit ID> # v7.0.1`, and look the ID up; do not invent one.

‎.github/instructions/powershell-error-handling.instructions.md‎

Lines changed: 52 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,8 @@ run directly, and a function, which a caller invokes and which must leave the ca
5353
error. A non-zero exit code does not raise a PowerShell error by default.
5454
- **ERR-24** In a script, pass `-ErrorAction Stop` to a module command whose non-terminating errors
5555
must stop the script. The script's own `$ErrorActionPreference` does not reach module functions.
56+
Set the preference as well (ERR-01): `-ErrorAction Stop` on a call does not make a terminating
57+
error of that command end the script.
5658

5759
### Streams
5860

@@ -222,9 +224,13 @@ carries.
222224

223225
Each statement below was verified on PowerShell 7.6 and Windows PowerShell 5.1.
224226

225-
- `throw` is suppressed when any caller up the call stack passed `-ErrorAction SilentlyContinue` or
226-
`-ErrorAction Ignore`. Execution then continues with the statement after the `throw`, and the
227-
function returns as if it had succeeded.
227+
- `throw` is suppressed when any caller up the call stack passed `-ErrorAction SilentlyContinue`, or
228+
`-ErrorAction Ignore` on PowerShell 7. Execution then continues with the statement after the
229+
`throw`, and the function returns as if it had succeeded. A bare `throw` that passes on an error
230+
raised with `-ErrorAction Stop` is the exception, described under the table below. On Windows
231+
PowerShell 5.1, `-ErrorAction Ignore` does not suppress a `throw`: the command that was given the
232+
parameter ends with another error,
233+
`The value Ignore is not supported for an ActionPreference variable`.
228234
- `Write-Error -ErrorAction Stop` ignores the caller's `-ErrorAction`, and unless `-ErrorRecord` is
229235
passed it replaces the original exception with a `WriteErrorException`.
230236
- `$PSCmdlet.ThrowTerminatingError()` always ends the function, and the caller's `-ErrorAction` does
@@ -241,6 +247,41 @@ Each statement below was verified on PowerShell 7.6 and Windows PowerShell 5.1.
241247
- Under `$ErrorActionPreference = 'Stop'`, `Write-Error` terminates. Statements that follow it in the
242248
same block do not run.
243249

250+
### What a calling script sees (ERR-01, ERR-10, ERR-11, ERR-24)
251+
252+
A module function fails in its `begin` block, in one of three ways, and the script that calls it is
253+
started with `-File`. Measured on PowerShell 7.7.0, PowerShell 7.6.10, and Windows PowerShell 5.1:
254+
255+
| The calling script | `$PSCmdlet.ThrowTerminatingError()` | `throw $_` | `Write-Error -ErrorRecord $_ -ErrorAction Stop` |
256+
| --- | --- | --- | --- |
257+
| Has no `try` and sets no preference | Goes on, exit code 0 | Ends, exit code 1 | Ends, exit code 1 |
258+
| Passes `-ErrorAction Stop` | Goes on, exit code 0 | Ends, exit code 1 | Ends, exit code 1 |
259+
| Passes `-ErrorAction SilentlyContinue` | Goes on, exit code 0 | Goes on, and so does the function | Ends, exit code 1 |
260+
| Sets `$ErrorActionPreference = 'Stop'` | Ends, exit code 1 | Ends, exit code 1 | Ends, exit code 1 |
261+
| Makes the call inside `try` | `catch` runs | `catch` runs | `catch` runs |
262+
| Makes the call twice in a loop | Both calls run | Ends at the first | Ends at the first |
263+
264+
`throw` with text or with an exception object behaves as `throw $_` does, and so does a bare `throw`
265+
in `catch`, with one exception. A bare `throw` that passes on an error raised with
266+
`-ErrorAction Stop` behaves as the last column does, and so does such an error that no `catch`
267+
handles: the script ends under `-ErrorAction SilentlyContinue` as well.
268+
269+
A compiled cmdlet that raises a terminating error, as `ConvertFrom-Json` does for invalid text,
270+
behaves as the first column does.
271+
272+
ERR-10 chooses the first column: the function fails as a cmdlet does, and the caller decides whether
273+
the script stops. The last column ends the calling script whatever the caller asked for. `-ErrorAction`
274+
no longer works for the caller, and a loop ends at its first failure, which is why ERR-11 rules that
275+
form out even with `-ErrorRecord`.
276+
277+
The first two rows are the price of that choice. A script that does not set
278+
`$ErrorActionPreference = 'Stop'` goes on after the failure and ends with exit code 0, and
279+
`-ErrorAction Stop` on the call does not change that. A script therefore needs both: the preference
280+
for a terminating error (ERR-01), and `-ErrorAction Stop` for a non-terminating error of a module
281+
command (ERR-24). Text for callers, such as a README, a runbook, or a help example, says the same.
282+
It does not offer `-ErrorAction Stop` as the way to make a failed command end a script or fail a job
283+
step.
284+
244285
### Strict mode (ERR-02, ERR-03)
245286

246287
`Set-StrictMode` applies to the scope where it runs and to the scopes below it. At the top of a
@@ -320,6 +361,14 @@ non-zero exit code raise an error that follows `$ErrorActionPreference`. It does
320361
PowerShell 5.1, and some tools use non-zero exit codes for success (`robocopy` returns values up to 7
321362
for normal outcomes), so an explicit `$LASTEXITCODE` test is the portable form.
322363

364+
### Log files (ERR-30)
365+
366+
These rules send messages to the streams and add no logging module. A project that also wants log
367+
files adds them with the `powershell-logging` skill, which uses the PSFramework module. Its code
368+
calls `Write-PSFMessage` where these rules name `Write-Verbose`, `Write-Debug`, and `Write-Warning`,
369+
and the message still reaches the stream. A project that requires PSFramework, in its manifest or
370+
in a `#requires -Modules` line, has made that choice: do not turn those calls back.
371+
323372
### Messages in a loop (ERR-32)
324373

325374
PowerShell builds the message before `Write-Verbose` decides whether to show it. Measured with

‎.github/instructions/powershell-help.instructions.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,11 @@ in `.github/instructions/powershell-platyps.instructions.md`.
7272
code does, and commented-out code MUST NOT be left in a file.
7373
- **DOC-21** A comment MUST stay true when read on its own. References to a conversation, a review, or
7474
an earlier version of the code MUST NOT be written into a file.
75+
- **DOC-22** A deliberate departure from a rule is recorded where the code is, in a comment directly
76+
above the statement or at the end of its line: `# Exception to <rule ID>: <reason>`. One comment
77+
names one rule, and the reason says why the rule does not fit there. The user decides an
78+
exception. Such a comment MUST NOT be added to make a check pass or to settle a review finding,
79+
and MUST NOT name a security rule (SEC): a security finding is always reported.
7580

7681
## Notes and examples
7782

@@ -268,3 +273,48 @@ $pageSize = 100
268273
# Set page size to 100
269274
$pageSize = 100
270275
```
276+
277+
**DOC-22.** The comment keeps the decision with the code, where every agent and every reviewer reads
278+
it. A note in a project file that only one tool loads does not do that.
279+
280+
```powershell
281+
function Get-StaleRecord {
282+
[CmdletBinding()]
283+
[OutputType('Contoso.StaleRecord')]
284+
param()
285+
286+
try {
287+
$session = Connect-RecordStore -ErrorAction Stop
288+
} catch {
289+
# Exception to ERR-11: the scheduled cleanup that calls this command sets no error
290+
# preference, and it must end when the store cannot be reached.
291+
Write-Error -ErrorRecord $_ -ErrorAction Stop
292+
}
293+
294+
Get-RecordStoreItem -Session $session -Stale
295+
}
296+
```
297+
298+
The reason can run over several comment lines. A blank line between the comment and the statement
299+
separates the two, and the comment then excuses nothing.
300+
301+
A review lists a recorded exception with its reason, apart from the findings, and reports one whose
302+
reason is missing or is no longer true (DOC-21). The compliance check of the standards repository,
303+
`Test-StandardsCompliance.ps1`, reports the excused finding with the severity Information and does
304+
not fail on it. It reports the comment itself when the reason is missing, when the comment is not
305+
in this form, and when it names a rule that the check covers and excuses nothing.
306+
307+
A security rule is not excused this way. Under `# Exception to SEC-01: test data` a literal
308+
password would pass the check, and that comment is what an agent with a failing check is tempted to
309+
add. The check keeps a security finding at its severity and reports the comment as well. An
310+
ordinary comment can still say why the code is as it is (DOC-20).
311+
312+
The comment does not silence PSScriptAnalyzer. Suppress one of its findings with its own attribute
313+
on the function, and give the attribute a justification:
314+
315+
```powershell
316+
[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
317+
'PSAvoidUsingWriteHost', '', Justification = 'The menu needs colour.')]
318+
[CmdletBinding()]
319+
param()
320+
```

0 commit comments

Comments
 (0)