feat(#161): enforce single top-level function in src/public files

- Stop build-driven workflows when a src/public file contains zero or multiple top-level functions to prevent accidental public API leaks.
- Introduce -OverrideWarning option to allow intentional bypass of this guard during builds, tests, packaging, and releases.
- Update documentation to reflect new behavior and usage of -OverrideWarning.

Author: stiwicourage

CHANGELOG.md

@@ -40,6 +40,12 @@ Keep stable `Update-NovaModuleVersion` / `% nova bump` releases on the SemVer ma
 
 ### Fixed
 
+- Stop build-driven workflows when a `src/public` file contains zero or multiple top-level functions.
+    - This prevents helper functions from being exported accidentally just because they live in a public file.
+    - `Invoke-NovaBuild`, `Test-NovaBuild -Build`, packaging, publishing, and release flows now surface the warning
+      consistently.
+    - PowerShell supports `-OverrideWarning`, and the `nova` CLI supports `--override-warning` / `-o` when maintainers
+      intentionally want to continue past the warning.
 - Fix `Invoke-NovaBuild` help discovery so it only scans `docs/<ProjectName>/` for PlatyPS
   markdown.
     - Regular markdown elsewhere under `docs/` no longer breaks the help-generation step.

README.md

@@ -68,6 +68,11 @@ PS> Invoke-NovaBuild
 
 This creates the built module under `dist/NovaModuleTools/`.
 
+Files under `src/public/` are expected to contain exactly one top-level function each. Nova now stops build-driven
+workflows when a public file contains zero or multiple top-level functions, because that layout can accidentally export
+helpers as part of the public API surface. Use `-OverrideWarning` / `--override-warning` / `-o` only when you
+intentionally want to bypass that guard for a specific build, test-build, package, publish, or release run.
+
 When you want the test workflow to rebuild first, use:
 
 ```powershell

docs/NovaModuleTools/en-US/Invoke-NovaBuild.md

@@ -20,7 +20,7 @@ Builds the current NovaModuleTools project into a ready-to-import PowerShell mod
 ### __AllParameterSets
 
 ```text
-PS> Invoke-NovaBuild [-ContinuousIntegration] [-WhatIf] [-Confirm] [<CommonParameters>]
+PS> Invoke-NovaBuild [-ContinuousIntegration] [-OverrideWarning] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -33,6 +33,10 @@ build target without clearing `dist/` or generating new build output.
 Use `-ContinuousIntegration` when the same PowerShell session needs to keep using the freshly built `dist/` module after
 the build completes. In CI/self-hosting flows, that re-activates the built module before the command returns.
 
+Use `-OverrideWarning` only when you intentionally want to continue a build even though a file under `src/public`
+contains zero or multiple top-level functions. The normal build guard stops there because those layouts can leak helper
+functions into the public API surface.
+
 The command:
 
 1. clears the existing `dist/` output
@@ -126,6 +130,30 @@ AcceptedValues: [ ]
 HelpMessage: ''
 ```
 
+### -OverrideWarning
+
+Continue the build when the `src/public` layout guard reports that a public file does not contain exactly one top-level
+function.
+
+Use this only when you intentionally accept the warning and still want the current build to proceed.
+
+```yaml
+Type: System.Management.Automation.SwitchParameter
+DefaultValue: False
+SupportsWildcards: false
+Aliases: [ ]
+ParameterSets:
+  - Name: (All)
+    Position: Named
+    IsRequired: false
+    ValueFromPipeline: false
+    ValueFromPipelineByPropertyName: false
+    ValueFromRemainingArguments: false
+DontShow: false
+AcceptedValues: [ ]
+HelpMessage: ''
+```
+
 ### CommonParameters
 
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
@@ -155,6 +183,9 @@ Run this command from the project root so `project.json`, `src/`, `docs/<Project
 When `-ContinuousIntegration` is used together with a real build, the command re-imports the freshly built module after
 the build succeeds. `-WhatIf` previews remain side-effect free and do not change the loaded module state.
 
+Files under `src/public` are expected to contain exactly one top-level function each. Use `-OverrideWarning` only when
+you intentionally want to bypass that guard for the current build.
+
 ## RELATED LINKS
 
 - https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Get-NovaProjectInfo.md

docs/NovaModuleTools/en-US/Invoke-NovaRelease.md

@@ -20,19 +20,19 @@ Runs the Nova release pipeline (build, test, version bump, rebuild, publish).
 ### Local
 
 ```text
-PS> Invoke-NovaRelease [-Local] [[-ModuleDirectoryPath] <string>] [[-ApiKey] <string>] [-SkipTests] [-ContinuousIntegration] [[-Path] <string>] [-WhatIf] [-Confirm] [<CommonParameters>]
+PS> Invoke-NovaRelease [-Local] [[-ModuleDirectoryPath] <string>] [[-ApiKey] <string>] [-SkipTests] [-ContinuousIntegration] [-OverrideWarning] [[-Path] <string>] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ### Repository
 
 ```text
-PS> Invoke-NovaRelease -Repository <string> [[-ModuleDirectoryPath] <string>] [[-ApiKey] <string>] [-SkipTests] [-ContinuousIntegration] [[-Path] <string>] [-WhatIf] [-Confirm] [<CommonParameters>]
+PS> Invoke-NovaRelease -Repository <string> [[-ModuleDirectoryPath] <string>] [[-ApiKey] <string>] [-SkipTests] [-ContinuousIntegration] [-OverrideWarning] [[-Path] <string>] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ### PublishOption
 
 ```text
-PS> Invoke-NovaRelease -PublishOption <hashtable> [-SkipTests] [-ContinuousIntegration] [[-Path] <string>] [-WhatIf] [-Confirm] [<CommonParameters>]
+PS> Invoke-NovaRelease -PublishOption <hashtable> [-SkipTests] [-ContinuousIntegration] [-OverrideWarning] [[-Path] <string>] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -58,6 +58,9 @@ Use `-ContinuousIntegration` when the same CI/self-hosting session should re-act
 release workflow boundaries where session state matters. Nova forwards that CI intent into the nested build and version
 bump steps and restores the built module again after publish.
 
+Use `-OverrideWarning` only when you intentionally want the nested release builds to continue even though a file under
+`src/public` contains zero or multiple top-level functions.
+
 When local release mode is selected, the resolved local publish target is previewed consistently with
 `Publish-NovaModule -Local`. Unlike `Publish-NovaModule -Local`, `Invoke-NovaRelease` does not import the published
 module into the current session after publishing; it returns the version result for automation-friendly release flows.
@@ -316,6 +319,32 @@ AcceptedValues: [ ]
 HelpMessage: ''
 ```
 
+### -OverrideWarning
+
+Continue the nested release builds even if the `src/public` layout guard reports that a public file does not contain
+exactly one top-level function.
+
+```yaml
+Type: System.Management.Automation.SwitchParameter
+DefaultValue: False
+SupportsWildcards: false
+Aliases: [ ]
+ParameterSets:
+  - Name: Local
+    Position: Named
+  - Name: Repository
+    Position: Named
+  - Name: PublishOption
+    Position: Named
+    IsRequired: false
+    ValueFromPipeline: false
+    ValueFromPipelineByPropertyName: false
+    ValueFromRemainingArguments: false
+DontShow: false
+AcceptedValues: [ ]
+HelpMessage: ''
+```
+
 ### CommonParameters
 
 This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`,

docs/NovaModuleTools/en-US/New-NovaModulePackage.md

@@ -20,7 +20,7 @@ Builds, tests, and packages the current project as one or more configured packag
 ### __AllParameterSets
 
 ```text
-PS> New-NovaModulePackage [-SkipTests] [-WhatIf] [-Confirm] [<CommonParameters>]
+PS> New-NovaModulePackage [-SkipTests] [-OverrideWarning] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -31,6 +31,9 @@ PS> New-NovaModulePackage [-SkipTests] [-WhatIf] [-Confirm] [<CommonParameters>]
 Use `-SkipTests` when tests already ran earlier in your pipeline and you only want to skip `Test-NovaBuild` for this
 packaging run. `Invoke-NovaBuild` still runs so the package is created from fresh built output.
 
+Use `-OverrideWarning` only when you intentionally want the nested build to continue even though a file under
+`src/public` contains zero or multiple top-level functions.
+
 The package is written to `artifacts/packages/` by default. You can override generic package metadata through the
 optional `Package` section in `project.json`.
 
@@ -172,6 +175,28 @@ AcceptedValues: [ ]
 HelpMessage: ''
 ```
 
+### -OverrideWarning
+
+Continue the nested build even if the `src/public` layout guard reports that a public file does not contain exactly one
+top-level function.
+
+```yaml
+Type: System.Management.Automation.SwitchParameter
+DefaultValue: False
+SupportsWildcards: false
+Aliases: [ ]
+ParameterSets:
+  - Name: (All)
+    Position: Named
+    IsRequired: false
+    ValueFromPipeline: false
+    ValueFromPipelineByPropertyName: false
+    ValueFromRemainingArguments: false
+DontShow: false
+AcceptedValues: [ ]
+HelpMessage: ''
+```
+
 ### -WhatIf
 
 Shows what would happen if the cmdlet runs. The cmdlet is not run.
@@ -259,6 +284,9 @@ separate
 
 When `-SkipTests` is used, only `Test-NovaBuild` is skipped. Build still runs.
 
+Files under `src/public` are expected to contain exactly one top-level function each. `-OverrideWarning` bypasses that
+guard only for the current packaging run.
+
 ## RELATED LINKS
 
 - https://github.com/stiwicourage/NovaModuleTools/blob/main/docs/NovaModuleTools/en-US/Invoke-NovaBuild.md

docs/NovaModuleTools/en-US/Publish-NovaModule.md

@@ -20,13 +20,13 @@ Builds, tests, and publishes the current project either locally or to a PowerShe
 ### Local
 
 ```text
-PS> Publish-NovaModule [-Local] [[-ModuleDirectoryPath] <string>] [[-ApiKey] <string>] [-SkipTests] [-ContinuousIntegration] [-WhatIf] [-Confirm] [<CommonParameters>]
+PS> Publish-NovaModule [-Local] [[-ModuleDirectoryPath] <string>] [[-ApiKey] <string>] [-SkipTests] [-ContinuousIntegration] [-OverrideWarning] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ### Repository
 
 ```text
-PS> Publish-NovaModule [-Repository] <string> [[-ModuleDirectoryPath] <string>] [[-ApiKey] <string>] [-SkipTests] [-ContinuousIntegration] [-WhatIf] [-Confirm] [<CommonParameters>]
+PS> Publish-NovaModule [-Repository] <string> [[-ModuleDirectoryPath] <string>] [[-ApiKey] <string>] [-SkipTests] [-ContinuousIntegration] [-OverrideWarning] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -47,6 +47,9 @@ Use `-ContinuousIntegration` when the same CI/self-hosting session should switch
 publish completes. This keeps later commands aligned with the built module state instead of whatever publish imported or
 left loaded.
 
+Use `-OverrideWarning` only when you intentionally want the nested build to continue even though a file under
+`src/public` contains zero or multiple top-level functions.
+
 This command supports `-WhatIf` and `-Confirm` through PowerShell `SupportsShouldProcess`. Use `-WhatIf` to preview the
 resolved publish target and workflow without building, testing, or publishing.
 
@@ -255,6 +258,30 @@ AcceptedValues: [ ]
 HelpMessage: ''
 ```
 
+### -OverrideWarning
+
+Continue the nested build even if the `src/public` layout guard reports that a public file does not contain exactly one
+top-level function.
+
+```yaml
+Type: System.Management.Automation.SwitchParameter
+DefaultValue: False
+SupportsWildcards: false
+Aliases: [ ]
+ParameterSets:
+  - Name: Local
+    Position: Named
+  - Name: Repository
+    Position: Named
+    IsRequired: false
+    ValueFromPipeline: false
+    ValueFromPipelineByPropertyName: false
+    ValueFromRemainingArguments: false
+DontShow: false
+AcceptedValues: [ ]
+HelpMessage: ''
+```
+
 ### CommonParameters
 
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,

docs/NovaModuleTools/en-US/Test-NovaBuild.md

@@ -20,7 +20,7 @@ Runs Pester tests for the current NovaModuleTools project.
 ### __AllParameterSets
 
 ```text
-PS> Test-NovaBuild [-Build] [[-TagFilter] <string[]>] [[-ExcludeTagFilter] <string[]>]
+PS> Test-NovaBuild [-Build] [-OverrideWarning] [[-TagFilter] <string[]>] [[-ExcludeTagFilter] <string[]>]
  [[-OutputVerbosity] <string>] [[-OutputRenderMode] <string>] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
@@ -31,6 +31,9 @@ suite against the current project.
 
 Use `-Build` when you want Nova to rebuild the project output before the Pester run starts.
 
+When `-Build` is used, `-OverrideWarning` lets that nested build continue even if the `src/public` layout guard reports
+zero or multiple top-level functions in a public file.
+
 With the default
 `BuildRecursiveFolders=true`, test files in nested folders under `tests` are discovered and run. Set
 `BuildRecursiveFolders=false` to limit discovery to top-level `tests/*.Tests.ps1` files, following Pester's normal
@@ -120,6 +123,28 @@ AcceptedValues: [ ]
 HelpMessage: ''
 ```
 
+### -OverrideWarning
+
+When `-Build` is also used, continue the nested build even if the `src/public` layout guard reports that a public file
+does not contain exactly one top-level function.
+
+```yaml
+Type: System.Management.Automation.SwitchParameter
+DefaultValue: False
+SupportsWildcards: false
+Aliases: [ ]
+ParameterSets:
+  - Name: (All)
+    Position: Named
+    IsRequired: false
+    ValueFromPipeline: false
+    ValueFromPipelineByPropertyName: false
+    ValueFromRemainingArguments: false
+DontShow: false
+AcceptedValues: [ ]
+HelpMessage: ''
+```
+
 ### -ExcludeTagFilter
 
 Array of Pester tags to exclude from the run.