Skip to content

Commit a40a9eb

Browse files
Native help and action descriptions state framework behavior directly (#570)
Native help and action descriptions state framework operations directly in en-US. Contributors and callers can read helper operations and action inputs without future-tense boilerplate. Runtime behavior and caller configuration remain unchanged; callers need no adoption changes. <!-- ANNOUNCEMENT STOP --> ## Changed: Native help and action descriptions state supported operations Native help uses imperative synopses and present-tense descriptions. Action descriptions identify build, documentation, installation, test-reporting, site, test, and index operations directly. The changes preserve command names, parameter names, help tags, exact examples, paths, output and error strings, YAML keys and defaults, expressions, option values, and version constraints. This is a prose-only delivery. It does not repair runtime behavior, complete every helper's help contract, or certify full STE conformance. Protected examples and unresolved contract discrepancies remain explicit follow-up work. <details> <summary>Technical details</summary> ### Delivery and immutable comparison - Delivery leaf: #558. - Base and review snapshot: `64ffb1d87f86bd5d487891fdb140b78385a00531`. - Pushed candidate: `aa992660e3eefe8d9a3881d95fe32bab491d9f52`. - Scope comparison: `git diff 64ffb1d aa99266`. - The first coherent commit, `29d8cca`, was pushed before this draft opened at `2026-11-04T12:28:44Z`. Five later small commits remain pushed: `c4319be`, `f8a4e0a`, `d25f9eb`, `a2bde66`, and `aa99266`. - The final local, origin branch, and PR head identities match. The PR is open and draft, has no labels, and has no auto-merge request. No merge or Agent merge action is requested. The manual review covers all 64 candidates: 52 PowerShell files and 12 action metadata files with 110 existing description fields. Each candidate and its surrounding implementation was read. The committed diff changes 34 paths: 22 PowerShell files and all 12 action metadata files. It revises 73 description values. No repository file is added or deleted. ### Exact acceptance evidence The four original expected-text checks failed before editing. Three additional parent-review checks failed at `a2bde6694cf238a77e21b3441066a61813a10567` before the bounded corrections below. All seven checks pass at the pushed candidate. The original text in this first table is from the immutable base above. | Location | Original text | Candidate text | | --- | --- | --- | | `Build-PSModule\src\helpers\Build\Add-ContentFromItem.ps1`, `.DESCRIPTION` | `This function will add the content of a folder or file to the root module file.` | `Add-ContentFromItem adds the content of a folder or file to the root module file.` | | `Build-PSModule\src\helpers\Build-PSModule.ps1`, `.SYNOPSIS` and `.DESCRIPTION` | Both sections say `Builds a module.` | `Build a PowerShell module from source files.` / `Build-PSModule copies the source files, creates the manifest, and combines the scripts into the root module.` | | `Get-PesterCodeCoverage\action.yml`, root `description` | `A GitHub Action that is used to gather Code Coverage for the PSModule process.` | `Collect code coverage results for the PSModule process.` | | `Get-PesterCodeCoverage\action.yml`, `inputs.WorkingDirectory.description` | `The working directory where the script will run from.` | `Working directory for the script.` | | `Build-PSModule\action.yml`, `inputs.OutputFolder.description` | `Path to the folder where the built module is outputted.` | `Path to the folder for the built module.` | | `Document-PSModule\src\helpers\Build-PSModuleDocumentation.ps1`, `.SYNOPSIS` and `.DESCRIPTION` | Both sections say `Builds a module.` | `Build documentation for a PowerShell module.` / `Build-PSModuleDocumentation creates Markdown help for exported commands and arranges the pages to match the public source folders.` | | `Test-PSModule\action.yml`, `inputs.CodeCoverage_RecursePaths.description` | `Will recurse through directories in the Path option.` | `Search subdirectories of the directories in the Path option.` | | `Test-PSModule\action.yml`, `inputs.Debug_ShowFullErrors.description` | `Show full errors including Pester internal stack. This property is deprecated, and if set to true it will override Output.StackTraceVerbosity to 'Full'.` | `Show full errors with the internal Pester stack. When true, this deprecated property overrides Output.StackTraceVerbosity with 'Full'.` | Implementation review also removes incorrect prose claims without changing behavior: base-module help describes the empty root module that the code creates; function and variable export helpers describe source-file inspection instead of manifest reads; documentation help describes Markdown generation; index API help no longer claims that its wrapper establishes an App context. The exact examples and disputed cmdlet-source claim remain protected, as recorded below. ### Bounded parent-review corrections The parent review independently confirms code tokens/flags, AST structure, BOM state, and zero parse errors in all 22 changed PowerShell files at `a2bde6694cf238a77e21b3441066a61813a10567`, plus the 73-description YAML boundary. Commit `aa99266` then changes only these two prose files: | Location | Previous draft text | Final text | | --- | --- | --- | | `Test-PSModule\action.yml`, `Run_Exit` | `If Throw is also enabled, prefer an exception.` | `Run_Throw takes precedence over Run_Exit when both are enabled.` | | `Test-PSModule\action.yml`, `Run_Throw` | `If Exit is also enabled, prefer an exception.` | `Run_Throw takes precedence over Run_Exit when both are enabled.` | | `Get-PesterCodeCoverage\src\Get-PesterCodeCoverage.Helpers.psm1`, `.OUTPUTS` | Description on the first line | `System.String` on the first line, a blank line, then the existing description | The [pinned Invoke-Pester action](https://github.com/PSModule/Invoke-Pester/blob/c5494aba3c07d7bfd81bdbbc9f301e8fa4a729fb/action.yml) forwards both flags. Its [initialization script](https://github.com/PSModule/Invoke-Pester/blob/c5494aba3c07d7bfd81bdbbc9f301e8fa4a729fb/src/init.ps1) maps them to `Run.Exit` and `Run.Throw`, and its [execution script](https://github.com/PSModule/Invoke-Pester/blob/c5494aba3c07d7bfd81bdbbc9f301e8fa4a729fb/src/exec.ps1) passes the configuration to Pester without changing that precedence. An anonymous isolated Pester 6.1.0 probe confirms the behavior with one intentional failing assertion. With both flags enabled, the child catches the expected `Pester run failed` exception and returns code 0. With only Exit enabled, the child terminates with code 1 and no fallthrough or caught exception. No repository test or fixture runs in this probe. The helper's unchanged `[OutputType([string])]` supports the output heading. Native `Get-Help` renders the exact block `System.String`, a blank line, and `The multiline string with adjusted indentation.` No help tag, association, example, or executable token changes. ### Behavior-preservation proof The baseline was captured before the first prose edit. The comparison covers all 52 candidate PowerShell files, including unchanged guidance and read-only action test files. At the candidate, all 23,371 non-comment tokens retain their kind, flags, and exact text. All 25,196 AST nodes retain their type and parent shape. Parse errors remain zero. `#Requires`, structural/test directives, help association, ordered help tags, parameter-help keys, all 36 complete examples, all three native `.LINK` entries, and forwarding/external-help metadata match the baseline. The comparison keeps here-string and string tokens intact. Generated Markdown/HTML, output text, error messages, suppression attribute strings, and embedded generated-code comments are therefore unchanged. All 34 changed files retain their original BOM state in raw-byte comparisons against the Git blobs. No generic help sections are added, and no existing help tag moves to another command. The YAML proof parses each of the 12 action files. It ignores only existing scalar values at root `description`, `inputs.<name>.description`, and `outputs.<name>.description`. All other node tags, mapping keys and order, sequence entries, scalar values, and exact text outside those description scalar spans match the base. This includes every default, required flag, action reference, environment mapping, shell command, expression, output mapping, and compatibility/version value. `git diff --name-only` also matches the 34 manually classified revised paths exactly. Every other repository path, including tests and fixture inputs, is unchanged. The verification scripts, baseline JSON, inventories, and console output are session artifacts, not repository changes. ### Validation commands and results Environment: PowerShell `7.6.9`, Pester `6.1.0`, PSScriptAnalyzer `1.25.0`, PyYAML `6.0.3`, and yamllint `1.38.0`. No package or module was installed or restored. In the commands below, `$audit` is the directory containing the retained session verification artifacts; `$PWD.Path` is this worktree. ```powershell & (Join-Path $audit 'Test-ProseBoundary.ps1') -Mode Compare -RepositoryPath $PWD.Path & (Join-Path $audit 'Test-ProseBoundary.ps1') -Mode Acceptance -RepositoryPath $PWD.Path & (Join-Path $audit 'Test-NativeHelp.ps1') -RepositoryPath $PWD.Path & (Join-Path $audit 'Test-AnalyzerBaseline.ps1') -RepositoryPath $PWD.Path python (Join-Path $audit 'test_action_descriptions.py') $PWD.Path python (Join-Path $audit 'test_action_yaml_lint.py') $PWD.Path (Join-Path $audit 'workflow-yaml-lint.yml') python (Join-Path $audit 'test_bom_preservation.py') $PWD.Path pwsh -NoLogo -NoProfile -File (Join-Path $audit 'Confirm-ThrowExitPrecedence.ps1') -ThrowOnFailure pwsh -NoLogo -NoProfile -File (Join-Path $audit 'Confirm-ThrowExitPrecedence.ps1') Import-Module Pester -RequiredVersion 6.1.0 $configuration = New-PesterConfiguration $configuration.Run.Path = '.github\actions\update-index\tests' $configuration.Run.Throw = $true $configuration.Run.PassThru = $true $configuration.Output.Verbosity = 'Normal' Invoke-Pester -Configuration $configuration git --no-pager diff --check 64ffb1d HEAD ``` | Check | Result | | --- | --- | | Parser, non-comment tokens, AST shape, directives, help association, tags, examples, and links | Pass for all 52 PowerShell files; zero parse errors | | Seven expected prose results | Four original failures before editing and three parent-review failures before correction; all seven pass at the candidate | | Rendered native help | `Get-Help -Full` resolves all 71 existing topics: 52 action topics and 19 guidance topics; the helper output block has the exact type/blank-line/description order | | Help inspection safety | Function definitions are isolated for inspection; no function body, benchmark, network example, or fixture script runs | | Throw/Exit precedence | Anonymous child-process probe passes: Throw+Exit catches the expected exception and returns 0; Exit-only terminates with expected code 1 | | BOM preservation | Raw-byte checks pass for all 34 changed files | | Repository PSScriptAnalyzer profile | Exactly the same two existing informational `PSAvoidUsingPositionalParameters` findings for `Heading` calls in `Get-PesterCodeCoverage\src\main.ps1`; no new finding | | YAML structure and non-description text | Pass for all 12 action files and 110 description fields; 73 revised descriptions | | Existing workflow YAML lint profile | Zero errors before and after; warnings decrease from 73 to 43; no new finding by file/rule/description field | | Existing update-index Pester suite | Baseline and final runs pass: one test passed, zero failed | | Whole committed diff whitespace | Pass | | Manual inventory against committed paths | Pass: all 64 candidates classified; exactly the 34 planned revised paths change | | Local/origin/PR identity and draft-only state | Pass at the candidate SHA above | The YAML profile is the exact [super-linter template](https://github.com/super-linter/super-linter/blob/4ce20838b8ab83717e78138c5b3a1407148e0918/TEMPLATES/.yaml-lint.yml) selected by this repository's pinned workflow. Lint input uses Git-normalized LF text, as the Linux workflow does. The 43 retained warnings are not presented as a clean lint result. The analyzer findings are compared by path, rule, severity, message, and source extent, not by shifted line numbers. These are local evidence and narrow regression results, not a claim that every CI job, platform, external link, help example, or STE dictionary entry is verified. CI and the requested review are separate from the prose-only proof. ### Current-head review and hosted checks The parent acceptance review accepts `aa992660e3eefe8d9a3881d95fe32bab491d9f52` after reading the final diff and independently checking the bounded corrections. The hosted review is also `APPROVED` on this exact head: review `5768802328`, submitted at `2026-11-04T13:04:57Z`, with zero inline comments. The earlier approval at `a2bde66` is dismissed after the head change and is not the final approval evidence. At the retained `2026-11-04T13:05:28Z` CI snapshot, 25 reported checks pass, three are skipped, and three remain in progress. No failing check is reported in that snapshot. These pending jobs are not presented as passes: | Pending check | State | Evidence | | --- | --- | --- | | WorkflowTestWithManifest / Lint-Repository / Lint code base | In progress | [Job](https://github.com/PSModule/Process-PSModule/actions/runs/41834197504/job/126590878494) | | WorkflowTestWithManifest / Build-Module / Build-Module | In progress | [Job](https://github.com/PSModule/Process-PSModule/actions/runs/41834197504/job/126590878718) | | WorkflowTestDefault / Plan / Plan | In progress | [Job](https://github.com/PSModule/Process-PSModule/actions/runs/41834197280/job/126588793486) | The requested handoff is a verified, pushed draft. The PR remains draft while the remaining hosted checks run; no merge or release readiness is asserted. ### Complete manual candidate inventory `Revised` means reviewed in full and changed only on an owned prose surface. `No prose` means no editable explanatory comment/help text is present. `No change` means reviewed prose is preserved under the guidance snapshot contract. `Excluded` means reviewed but read-only test/configuration implementation. There is no wholly blocked candidate file; blocked portions and decisions are listed after the inventory. | Exact path | Classification | Review result | | --- | --- | --- | | `.github\actions\Build-PSModule\action.yml` | Revised | Direct build, output-folder, prerelease, and working-directory descriptions | | `.github\actions\Build-PSModule\src\main.ps1` | No prose | Only code and suppression attribute strings | | `.github\actions\Build-PSModule\src\helpers\Build-PSModule.ps1` | Revised | Distinct synopsis/description and direct folder comments | | `.github\actions\Build-PSModule\src\helpers\Build\Add-ContentFromItem.ps1` | Revised | Present-tense description; exact example preserved | | `.github\actions\Build-PSModule\src\helpers\Build\Build-PSModuleBase.ps1` | Revised | Direct copy/root-module description; protected example gap | | `.github\actions\Build-PSModule\src\helpers\Build\Build-PSModuleManifest.ps1` | Revised | Direct manifest description; protected example gap | | `.github\actions\Build-PSModule\src\helpers\Build\Build-PSModuleRootModule.ps1` | Revised | Direct build-order prose; protected example and cmdlet-source claim | | `.github\actions\Build-PSModule\src\helpers\Build\Get-PSModuleAliasesToExport.ps1` | Revised | Direct manifest-read help | | `.github\actions\Build-PSModule\src\helpers\Build\Get-PSModuleClassesToExport.ps1` | Revised | Direct class/enum discovery help; exact example preserved | | `.github\actions\Build-PSModule\src\helpers\Build\Get-PSModuleCmdletsToExport.ps1` | Revised | Direct manifest-read help | | `.github\actions\Build-PSModule\src\helpers\Build\Get-PSModuleFunctionsToExport.ps1` | Revised | Source-file and filter discovery, not manifest reads | | `.github\actions\Build-PSModule\src\helpers\Build\Get-PSModuleVariablesToExport.ps1` | Revised | Public variable source inspection, not manifest reads | | `.github\actions\Build-PSModule\src\helpers\Build\Get-RootLevelVariables.ps1` | Revised | Correct AST article and concise assignment comment | | `.github\actions\Build-PSModule\src\helpers\Build\Update-PSModuleManifestAliasesToExport.ps1` | Revised | Imperative synopsis and direct folder/file comments | | `.github\actions\Build-ZensicalSite\action.yml` | Revised | Build location, not a stale output-normalization claim | | `.github\actions\Build-ZensicalSite\src\main.ps1` | Revised | Imperative synopsis and direct build description | | `.github\actions\Build-ZensicalSite\src\build-zensical-site.ps1` | No prose | No comments or help | | `.github\actions\Document-PSModule\action.yml` | Revised | Direct summary and working-directory descriptions | | `.github\actions\Document-PSModule\src\main.ps1` | No prose | Only code and suppression attribute strings | | `.github\actions\Document-PSModule\src\helpers\Build-PSModuleDocumentation.ps1` | Revised | Documentation operation, output folders, and section-index rationale | | `.github\actions\Expose-TestData\action.yml` | Revised | Active validation and environment export description | | `.github\actions\Get-PesterCodeCoverage\action.yml` | Revised | Direct collection and inputs; exact NuGet range example retained | | `.github\actions\Get-PesterCodeCoverage\src\Get-PesterCodeCoverage.Helpers.psm1` | Revised | Direct indentation help, typed output block, and removal of a stray comment character | | `.github\actions\Get-PesterCodeCoverage\src\main.ps1` | Revised | Combined-report comments and accurate action-failure wording | | `.github\actions\Get-PesterTestResults\action.yml` | Revised | Direct collection/expected-suite descriptions; exact-version constraint retained | | `.github\actions\Get-PesterTestResults\src\main.ps1` | Revised | Accurate report-name comments and direct failure wording | | `.github\actions\Inject-SiteScripts\action.yml` | Revised | Clear checked-out repository modifier | | `.github\actions\Inject-SiteScripts\src\main.ps1` | Revised | Imperative synopsis and direct injection description | | `.github\actions\Inject-SiteScripts\src\inject-site-scripts.ps1` | No prose | No comments or help | | `.github\actions\Install-PSModule\action.yml` | Revised | Identifies the bundled helper module | | `.github\actions\Install-PSModule\src\main.ps1` | No prose | Only code and suppression attribute strings | | `.github\actions\Install-PSModule\src\PSModule\PSModule.psm1` | Revised | Native helper help and explanatory comments; all examples and links preserved | | `.github\actions\Install-Zensical\action.yml` | Revised | Direct CLI purpose | | `.github\actions\Install-Zensical\src\main.ps1` | Revised | Imperative synopsis and direct package-install description | | `.github\actions\Install-Zensical\src\install-zensical.ps1` | No prose | No comments or help | | `.github\actions\Structure-Site\action.yml` | Revised | Direct documentation/configuration purpose | | `.github\actions\Structure-Site\src\main.ps1` | Revised | Imperative synopsis and direct copy/configuration description | | `.github\actions\Structure-Site\src\structure-site.ps1` | No prose | No comments or help | | `.github\actions\Test-PSModule\action.yml` | Revised | Direct option descriptions; exact option values, examples, deprecation, and compatibility constraints retained | | `.github\actions\Test-PSModule\src\main.ps1` | No prose | No comments or help | | `.github\actions\Test-PSModule\src\tests\Module\Module.Configuration.ps1` | Excluded | Read-only test configuration | | `.github\actions\Test-PSModule\src\tests\Module\PSModule\PSModule.Container.ps1` | Excluded | Read-only container data | | `.github\actions\Test-PSModule\src\tests\Module\PSModule\PSModule.Tests.ps1` | Excluded | Read-only assertions and discovery implementation | | `.github\actions\Test-PSModule\src\tests\SourceCode\SourceCode.Configuration.ps1` | Excluded | Read-only test configuration | | `.github\actions\Test-PSModule\src\tests\SourceCode\PSModule\PSModule.Container.ps1` | Excluded | Read-only container data | | `.github\actions\Test-PSModule\src\tests\SourceCode\PSModule\PSModule.Tests.ps1` | Excluded | Read-only assertions and discovery implementation | | `.github\actions\update-index\action.yml` | Revised | Direct index update description | | `.github\actions\update-index\src\main.ps1` | No prose | No comments or help | | `.github\actions\update-index\src\Helper.psm1` | Revised | Direct native help; generated output and exact examples preserved | | `.github\actions\update-index\tests\Update-Index.Helpers.Tests.ps1` | Excluded | Existing narrow regression test; no assertion change | | `guidance\Add-Array.ps1` | No change | Complete guidance snapshot preserved | | `guidance\Add-HashTable.ps1` | No change | Complete guidance snapshot preserved | | `guidance\Add-String.ps1` | No prose | No comments or help; snapshot preserved | | `guidance\Caller.ps1` | No change | Synopsis changes require a source/provenance decision | | `guidance\ClassExtension.ps1` | No change | Complete guidance snapshot preserved | | `guidance\Loops.ps1` | No change | Synopsis changes require a source/provenance decision | | `guidance\Out-Null.ps1` | No prose | No comments or help; snapshot preserved | | `guidance\PipelineExecution.ps1` | No change | Synopsis changes require a source/provenance decision | | `guidance\PSCallStack.ps1` | No change | Synopsis changes require a source/provenance decision | | `guidance\PSCmdlet.ps1` | No change | Synopsis changes require a source/provenance decision | | `guidance\PSModuleTest.psm1` | No change | Snapshot preserved; dot-source comment differs from Import-Module | | `guidance\Read-File.ps1` | No change | Snapshot preserved; greater-than token is redirection, not a Boolean comparison | | `guidance\root.ps1` | No change | PSScriptAnalyzer loader snapshot preserved | | `guidance\WebCalls.ps1` | No change | Complete guidance snapshot preserved | Totals: 34 revised, 11 no-prose, 12 reviewed/no-change, and seven excluded candidates. The reviewed CSV classifications match the committed path set. ### Additional exclusions and blocked portions | Surface | Disposition and evidence | | --- | --- | | `Build-PSModule\src\helpers\Build\PSScriptAnalyzer.Tests.psd1`; `Install-PSModule\src\PSModule\PSModule.psd1`; `Install-PSModule\src\PSModule\PSScriptAnalyzer.Tests.psd1` | Three additional data/configuration files were read and left unchanged; no configuration redesign or string edits | | `.github\actions\Cleanup-PSModulePrereleases\**` | Entire reserved source/metadata area excluded; existing release/recovery ownership retained | | `.github\actions\Get-PSModuleSettings\**`, including `Settings.schema.json` | Entire reserved source/metadata/schema area excluded | | `.github\actions\Publish-PSModule\**` | Entire reserved source/metadata/test area excluded | | `.github\actions\Release-PSModule\**` | Entire reserved source/metadata/test area excluded | | `.github\actions\Resolve-PSModuleVersion\**` | Entire reserved source/metadata/test area excluded | | `tests\srcTestRepo\**`; `tests\srcWithManifestTestRepo\**` | Functional fixture inputs excluded entirely from local reading, parsing, execution, and edits | | All README/Markdown, plugin, TOML, JSON, HTML, and workflow files | Read-only sibling surfaces; the full diff proves that none changes | | Exact examples and export descriptions | #574 records invalid example parameters, the mismatched Get-PSModuleManifest example name, class output shape, the disputed `cmdlets/public` claim, and missing substantive helper help. The protected text is not claimed to be corrected here | | `Test-PSModule` `Run_Path` input | #575 records the public input versus fixed `steps.paths.outputs.CodePath` forwarding. Its caller contract needs a separate decision and behavior checks | | Guidance writing and behavior | The [complete-blob preservation contract](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/reference/guidance-scripts.md#maintenance) and the existing policy question in #481 require a source decision. The [audit comment](#481 (comment)) records the `Read-File.ps1` FileRedirectionAst at line 15 and the PSModuleTest import/comment discrepancy | | Dependency resolver roadmap notes | Native help states the existing manifest-based interface rather than future plans. Prerequisite/parameter-set work remains separate; #476 is relevant context | | Release route | `.github\workflows\Release.yml` pins `Release-GHRepository` at `750abed0ecab02394554b610dc3aa191e75e3248`. Its interface uses legacy label defaults, not a verified canonical `release:*` mapping. No release label or release-readiness claim is added, and no release route changes | Missing help sections and preserved output declarations are not evidence of complete native-help contract coverage. This delivery does not add copied/generated help or blanket section scaffolding. Existing native `.LINK` values are preserved; preservation is not a claim that every external target resolves. ### Ownership, plan progress, and convergence Every commit follows a fresh live open-PR path check. Each check reads all paginated file lists and compares exact paths, rather than assuming directory ownership from a title. The checks cover 15 open PRs before the first commit and 16 before later commits, excluding this PR itself. The last pre-commit check is `2026-11-04T13:59:19+01:00`: all 34 proposed paths have no conflict. Reserved release/recovery areas and the #551 test work remain untouched. The delivery issue's inventory, baseline, early-draft, prose-edit, and local-verification steps are complete. The issue retains the plan and links this audit. The requested handoff is a pushed draft, not a ready/merged PR. The scoped convergence sweep searches open issues for native help, `Run_Path`, `Read-File`, and help examples. It includes the documentation-writing siblings and the existing guidance/dependency issues. Only #558 converges with this prose diff. #574, #575, #481, and #476 remain non-closing references. No additional issue is closed by this PR. ### Writing and framework sources The writing criteria use `MSXOrg/docs@1b0d4893c8fefabe604d04393068a8ff6f848082`, not an unpinned recollection: | Source | Applied criterion | | --- | --- | | [Documentation Model](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/Documentation-Model.md) | Evergreen resource prose; per-change evidence stays in the delivery issue and PR | | [Natural Language](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Natural-Language.md) | en-US, direct and specific statements, present tense, exact technical meaning | | [Writing Guide](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Writing-Guide.md) | Consult official STE rules/dictionary; preserve native formats and contracts | | [Markdown](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Markdown.md) | GFM for this audit; no repository Markdown edits | | [Documentation](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Documentation.md) | Native help near code; concise explanatory comments, not copied scaffolding | | [PowerShell Functions](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/PowerShell/Functions.md) and [Scripts](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/PowerShell/Scripts.md) | Imperative synopses and native comment-based help; preserve tags and association | | [YAML](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/YAML.md) and [GitHub Actions](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/GitHub-Actions.md) | Preserve metadata syntax and execution/security configuration; use the existing lint profile | | [Microsoft native-help syntax](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_comment_based_help?view=powershell-7.5) | Help keyword and script/function association checks | | [STEMG overview](https://www.asd-ste100.org/about_STE.html), [FAQ](https://www.asd-ste100.org/STE_faq.html), and [Issue 9](https://doi.org/10.5281/zenodo.23666006) | Active voice, short sentences, imperative instructions, consistent technical terms, and American spelling | | [Pinned Task format](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/Issues/Types/Task.md) and [PR format](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/PR-Format.md) | One delivery leaf, early draft, audience-facing result, section-scoped evidence | The official Issue 9 PDF is available locally and matches the published MD5 `9c720341c350ed77943b2c73d01c716f`. The review consults rules 1.14, 3.2, 3.4, 3.6, 4.1, 5.3, and 6.3; technical-term categories in rules 1.5 and 1.12; and relevant dictionary entries, including the `gather` to `collect` choice. No required writing source is unavailable. The PDF and its extracted text remain local and are not republished. Manual review and scans support these changes; they do not prove full STE conformance. | Changed surface | Standards checked | Framework documentation checked | Result | | --- | --- | --- | --- | | Build and documentation native help/comments | Pinned Documentation, Natural Language, Writing Guide, PowerShell Functions | [Module layout guidance](https://psmodule.io/Process-PSModule/guides/structuring-your-module/) and complete local build/documentation implementation | Fixed in this PR; protected contract gaps recorded in #574 | | Installation and index helper native help | Same pinned PowerShell/native-writing sources | Local manifest, installation, TestData, and index implementations; [framework overview](https://psmodule.io/Process-PSModule/) | Fixed in this PR; no runtime or generated-output change | | Site and test-report native help/comments | Pinned PowerShell Scripts and writing sources | Local action entry points and [pipeline reference](https://psmodule.io/Process-PSModule/reference/pipeline-stages/) | Fixed in this PR | | Action metadata description values | Pinned YAML, GitHub Actions, and writing sources | All owned `action.yml` files and their complete implementations | Fixed in this PR; Run_Path contract remains #575 | | Reviewed guidance snapshots | Pinned documentation/native-writing sources | [Guidance scripts](https://psmodule.io/Process-PSModule/reference/guidance-scripts/) and immutable maintenance contract | Exception - #481; all contents preserved | </details> <details> <summary>Related references</summary> - Resolves #558 - References #574 - References #575 - References #481 - References #476 </details>
1 parent 96a4f16 commit a40a9eb

34 files changed

Lines changed: 317 additions & 313 deletions

‎.github/actions/Build-PSModule/action.yml‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,27 @@
11
name: Build-PSModule
2-
description: Build a PowerShell module to the PowerShell Gallery.
2+
description: Build a PowerShell module for the PowerShell Gallery.
33
author: PSModule
44

55
inputs:
66
Name:
77
description: Name of the module to build. Defaults to the repository name.
88
required: false
99
OutputFolder:
10-
description: Path to the folder where the built module is outputted.
10+
description: Path to the folder for the built module.
1111
required: false
1212
default: '.PSModule/module'
1313
Version:
1414
description: Module version to stamp into the manifest.
1515
required: true
1616
Prerelease:
17-
description: Prerelease tag to stamp into the manifest's `PrivateData.PSData.Prerelease`. When empty, no prerelease tag is written.
17+
description: Prerelease tag for the manifest's `PrivateData.PSData.Prerelease`. An empty value omits the prerelease tag.
1818
required: false
1919
ArtifactName:
2020
description: Name of the artifact to upload.
2121
required: false
2222
default: module
2323
WorkingDirectory:
24-
description: The working directory where the script will run from.
24+
description: Working directory for the script.
2525
required: false
2626
default: '.'
2727

‎.github/actions/Build-PSModule/src/helpers/Build-PSModule.ps1‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
function Build-PSModule {
22
<#
33
.SYNOPSIS
4-
Builds a module.
4+
Build a PowerShell module from source files.
55
66
.DESCRIPTION
7-
Builds a module.
7+
Build-PSModule copies the source files, creates the manifest, and combines the scripts into the root module.
88
#>
99
[OutputType([void])]
1010
[CmdletBinding()]
@@ -21,19 +21,19 @@
2121
[Parameter(Mandatory)]
2222
[string] $ModuleName,
2323

24-
# Path to the folder where the modules are located.
24+
# Path to the module source folder.
2525
[Parameter(Mandatory)]
2626
[string] $ModuleSourceFolderPath,
2727

28-
# Path to the folder where the built modules are outputted.
28+
# Path to the folder for the built module.
2929
[Parameter(Mandatory)]
3030
[string] $ModuleOutputFolderPath,
3131

3232
# Module version to stamp into the manifest.
3333
[Parameter(Mandatory)]
3434
[string] $ModuleVersion,
3535

36-
# Prerelease tag to stamp into the manifest. When empty, no prerelease tag is written.
36+
# Prerelease tag for the manifest. An empty value omits the prerelease tag.
3737
[Parameter()]
3838
[string] $ModulePrerelease
3939
)

‎.github/actions/Build-PSModule/src/helpers/Build/Add-ContentFromItem.ps1‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ function Add-ContentFromItem {
44
Add the content of a folder or file to the root module file.
55
66
.DESCRIPTION
7-
This function will add the content of a folder or file to the root module file.
7+
Add-ContentFromItem adds the content of a folder or file to the root module file.
88
99
.EXAMPLE
1010
Add-ContentFromItem -Path 'C:\MyModule\src\MyModule' -RootModuleFilePath 'C:\MyModule\src\MyModule.psm1' -RootPath 'C:\MyModule\src'

‎.github/actions/Build-PSModule/src/helpers/Build/Build-PSModuleBase.ps1‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
function Build-PSModuleBase {
22
<#
33
.SYNOPSIS
4-
Compiles the base module files.
4+
Build the base module files.
55
66
.DESCRIPTION
7-
This function will compile the base module files.
8-
It will copy the source files to the output folder and remove the files that are not needed.
7+
Build-PSModuleBase copies source files to the output folder.
8+
It creates an empty root module file.
99
1010
.EXAMPLE
1111
Build-PSModuleBase -SourceFolderPath 'C:\MyModule\src\MyModule' -OutputFolderPath 'C:\MyModule\build\MyModule'
@@ -24,11 +24,11 @@
2424
[Parameter(Mandatory)]
2525
[string] $ModuleName,
2626

27-
# Path to the folder where the module source code is located.
27+
# Path to the module source folder.
2828
[Parameter(Mandatory)]
2929
[System.IO.DirectoryInfo] $ModuleSourceFolder,
3030

31-
# Path to the folder where the built modules are outputted.
31+
# Path to the folder for the built module.
3232
[Parameter(Mandatory)]
3333
[System.IO.DirectoryInfo] $ModuleOutputFolder
3434
)

‎.github/actions/Build-PSModule/src/helpers/Build/Build-PSModuleManifest.ps1‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
11
function Build-PSModuleManifest {
22
<#
33
.SYNOPSIS
4-
Compiles the module manifest.
4+
Build the module manifest.
55
66
.DESCRIPTION
7-
This function will compile the module manifest.
8-
It will generate the module manifest file and copy it to the output folder.
7+
Build-PSModuleManifest creates the module manifest in the output folder.
98
109
.EXAMPLE
1110
Build-PSModuleManifest -SourceFolderPath 'C:\MyModule\src\MyModule' -OutputFolderPath 'C:\MyModule\build\MyModule'
@@ -28,7 +27,7 @@
2827
[Parameter(Mandatory)]
2928
[string] $ModuleName,
3029

31-
# Folder where the built module is outputted. '.PSModule/module/MyModule'
30+
# Folder for the built module files. '.PSModule/module/MyModule'
3231
[Parameter(Mandatory)]
3332
[System.IO.DirectoryInfo] $ModuleOutputFolder,
3433

‎.github/actions/Build-PSModule/src/helpers/Build/Build-PSModuleRootModule.ps1‎

Lines changed: 13 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,29 @@
11
function Build-PSModuleRootModule {
22
<#
33
.SYNOPSIS
4-
Compiles the module root module files.
4+
Build the root module file from source scripts.
55
66
.DESCRIPTION
7-
This function will compile the modules root module from source files.
8-
It will copy the source files to the output folder and start compiling the module.
9-
During compilation, the source files are added to the root module file in the following order:
7+
Build-PSModuleRootModule combines source scripts in the output folder into the root module file.
8+
It adds content in this order:
109
11-
1. Module header from header.ps1 file. Usually to suppress code analysis warnings/errors and to add [CmdletBinding()] to the module.
12-
2. Data loader is added if data files are available.
13-
3. Combines *.ps1 files from the following folders in alphabetical order from each folder:
10+
1. The header.ps1 module header, which can suppress code analysis warnings and errors or add [CmdletBinding()].
11+
2. A data loader, if data files are available.
12+
3. The *.ps1 files from these folders, in alphabetical order within each folder:
1413
1. init
1514
2. classes/private
1615
3. classes/public
1716
4. functions/private
1817
5. functions/public
1918
6. variables/private
2019
7. variables/public
21-
8. Any remaining *.ps1 on module root.
22-
4. Adds a class loader for classes found in the classes/public folder.
23-
5. Export-ModuleMember by using the functions, cmdlets, variables and aliases found in the source files.
24-
- `Functions` will only contain functions that are from the `functions/public` folder.
20+
8. Any remaining *.ps1 files in the module root.
21+
4. A class loader for classes in the classes/public folder.
22+
5. An Export-ModuleMember call with the functions, cmdlets, variables, and aliases from the source files.
23+
- `Functions` contains only functions from the `functions/public` folder.
2524
- `Cmdlets` will only contain cmdlets that are from the `cmdlets/public` folder.
26-
- `Variables` will only contain variables that are from the `variables/public` folder.
27-
- `Aliases` will only contain aliases that are from the functions from the `functions/public` folder.
25+
- `Variables` contains only variables from the `variables/public` folder.
26+
- `Aliases` contains only aliases from functions in the `functions/public` folder.
2827
2928
.EXAMPLE
3029
Build-PSModuleRootModule -SourceFolderPath 'C:\MyModule\src\MyModule' -OutputFolderPath 'C:\MyModule\build\MyModule'
@@ -43,7 +42,7 @@
4342
[Parameter(Mandatory)]
4443
[string] $ModuleName,
4544

46-
# Folder where the built module is outputted. '.PSModule/module/MyModule'
45+
# Folder for the built module files. '.PSModule/module/MyModule'
4746
[Parameter(Mandatory)]
4847
[System.IO.DirectoryInfo] $ModuleOutputFolder
4948
)

‎.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleAliasesToExport.ps1‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
function Get-PSModuleAliasesToExport {
22
<#
33
.SYNOPSIS
4-
Gets the aliases to export from the module manifest.
4+
Get the aliases to export from the module manifest.
55
66
.DESCRIPTION
7-
This function will get the aliases to export from the module manifest.
7+
Get-PSModuleAliasesToExport reads AliasesToExport from the module manifest.
88
99
.EXAMPLE
1010
Get-PSModuleAliasesToExport -SourceFolderPath 'C:\MyModule\src\MyModule'
@@ -13,7 +13,7 @@
1313
[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '', Scope = 'Function', Justification = 'Want to just write to the console, not the pipeline.')]
1414
[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidLongLines', '', Scope = 'Function', Justification = 'Contains long links.')]
1515
param(
16-
# Path to the folder where the module source code is located.
16+
# Path to the module source folder.
1717
[Parameter(Mandatory)]
1818
[string] $SourceFolderPath
1919
)

‎.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleClassesToExport.ps1‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
function Get-PSModuleClassesToExport {
22
<#
33
.SYNOPSIS
4-
Gets the classes to export from the module source code.
4+
Get the classes and enums to export from the module source code.
55
66
.DESCRIPTION
7-
This function will get the classes to export from the module source code.
7+
Get-PSModuleClassesToExport finds class and enum declarations in source files.
88
99
.EXAMPLE
1010
Get-PSModuleClassesToExport -SourceFolderPath 'C:\MyModule\src\MyModule'

‎.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleCmdletsToExport.ps1‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
function Get-PSModuleCmdletsToExport {
22
<#
33
.SYNOPSIS
4-
Gets the cmdlets to export from the module manifest.
4+
Get the cmdlets to export from the module manifest.
55
66
.DESCRIPTION
7-
This function will get the cmdlets to export from the module manifest.
7+
Get-PSModuleCmdletsToExport reads CmdletsToExport from the module manifest.
88
99
.EXAMPLE
1010
Get-PSModuleCmdletsToExport -SourceFolderPath 'C:\MyModule\src\MyModule'
@@ -13,7 +13,7 @@
1313
[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '', Scope = 'Function', Justification = 'Want to just write to the console, not the pipeline.')]
1414
[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidLongLines', '', Scope = 'Function', Justification = 'Contains long links.')]
1515
param(
16-
# Path to the folder where the module source code is located.
16+
# Path to the module source folder.
1717
[Parameter(Mandatory)]
1818
[string] $SourceFolderPath
1919
)

‎.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleFunctionsToExport.ps1‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
function Get-PSModuleFunctionsToExport {
22
<#
33
.SYNOPSIS
4-
Gets the functions to export from the module manifest.
4+
Get the functions and filters to export from the module source code.
55
66
.DESCRIPTION
7-
This function will get the functions to export from the module manifest.
7+
Get-PSModuleFunctionsToExport reads public source files to identify the functions and filters to export.
88
99
.EXAMPLE
1010
Get-PSModuleFunctionsToExport -SourceFolderPath 'C:\MyModule\src\MyModule'
@@ -14,7 +14,7 @@
1414
[Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidLongLines', '', Scope = 'Function', Justification = 'Contains long links.')]
1515
[OutputType([array])]
1616
param(
17-
# Path to the folder where the module source code is located.
17+
# Path to the module source folder.
1818
[Parameter(Mandatory)]
1919
[string] $SourceFolderPath
2020
)

0 commit comments

Comments
 (0)