Summary
nova build currently exports every top-level function found in each file under src/public.
That means helper functions become public when a src/public file contains more than one top-level function.
Example from KeepAChangelog
These files are under src/public and contain helper functions as extra top-level functions:
src/public/Initialize-KeepAChangelogFile.ps1src/public/Convert-ChangelogReleaseNotesToTagMessage.ps1
The resulting built manifest exports helpers such as:
Assert-KeepAChangelogInitializationGet-KeepAChangelogHeadingLinesGet-KeepAChangelogFooterLineNew-KeepAChangelogTemplateAdd-ChangelogTagMessageBlankLineGet-ChangelogTagMessageLineRemove-ChangelogTagMessageTrailingBlanks
This happens because Build-Manifest gathers function names from every file in src/public, and Get-FunctionNameFromFile returns every top-level function in the file.
Problem
The current behavior makes it easy to accidentally publish private helpers just because they live in a public file.
Proposed behavior
Do not change how Nova discovers top-level functions.
Instead, before continuing the build, validate every file in src/public:
- Each file must contain exactly one top-level function.
- If a file contains more than one top-level function, write a clear build warning/error and stop the build.
This keeps the guardrail focused on accidental API-surface leaks without forcing a project-specific file naming convention.
Commands that should surface this warning/stop
This validation should not only affect Invoke-NovaBuild / % nova build.
It should affect every public command that reaches the build workflow directly or through shared build validation.
Direct build callers
These commands invoke the build workflow directly, so they should surface the warning directly:
Invoke-NovaBuild% nova buildTest-NovaBuild -Build% nova test --build% nova test -b
Shared build-validation callers
These commands currently go through Invoke-NovaBuildValidation, which calls Invoke-NovaBuild and then Test-NovaBuild unless tests are skipped:
New-NovaModulePackage% nova packagePublish-NovaModule% nova publish
The skip-tests variants should still hit this validation, because they still build:
New-NovaModulePackage -SkipTests% nova package --skip-tests% nova package -sPublish-NovaModule -SkipTests ...% nova publish --skip-tests ...
Release callers
Invoke-NovaRelease / % nova release should also surface the warning. The release workflow currently builds before testing/version bump and builds again after the version bump:
Invoke-NovaRelease% nova releaseInvoke-NovaRelease -SkipTests ...% nova release --skip-tests ...% nova release -s
Even with -SkipTests, release still runs the build steps, so the validation should still stop there unless explicitly overridden.
Commands that should NOT be affected
These public commands do not use the build workflow and should not need this warning:
Deploy-NovaPackageGet-NovaProjectInfoGet-NovaUpdateNotificationPreferenceInitialize-NovaModuleInstall-NovaCliInvoke-NovaCli in general, except when it routes to one of the affected commands aboveSet-NovaUpdateNotificationPreferenceUpdate-NovaModuleToolUpdate-NovaModuleVersionTest-NovaBuild without -Build
Override behavior
The stop should be bypassable only when the user explicitly accepts this warning:
- PowerShell parameter:
-OverrideWarning
- CLI long option:
--override-warning
- CLI short option:
-o
This keeps the override scoped to warning bypasses and leaves room for future override categories.
Warning/error message expectation
The message should explain:
- which
src/public file failed validation
- which top-level functions were found
- which commands are affected because they build or trigger build validation
- that the user can fix the file layout or continue intentionally with
-OverrideWarning / --override-warning / -o
Why this is a good fit
This keeps the current top-level function discovery logic intact, but adds a guardrail that prevents accidental API-surface leaks while still allowing advanced users to override the check intentionally.
Summary
nova buildcurrently exports every top-level function found in each file undersrc/public.That means helper functions become public when a
src/publicfile contains more than one top-level function.Example from KeepAChangelog
These files are under
src/publicand contain helper functions as extra top-level functions:src/public/Initialize-KeepAChangelogFile.ps1src/public/Convert-ChangelogReleaseNotesToTagMessage.ps1The resulting built manifest exports helpers such as:
Assert-KeepAChangelogInitializationGet-KeepAChangelogHeadingLinesGet-KeepAChangelogFooterLineNew-KeepAChangelogTemplateAdd-ChangelogTagMessageBlankLineGet-ChangelogTagMessageLineRemove-ChangelogTagMessageTrailingBlanksThis happens because
Build-Manifestgathers function names from every file insrc/public, andGet-FunctionNameFromFilereturns every top-level function in the file.Problem
The current behavior makes it easy to accidentally publish private helpers just because they live in a public file.
Proposed behavior
Do not change how Nova discovers top-level functions.
Instead, before continuing the build, validate every file in
src/public:This keeps the guardrail focused on accidental API-surface leaks without forcing a project-specific file naming convention.
Commands that should surface this warning/stop
This validation should not only affect
Invoke-NovaBuild/% nova build.It should affect every public command that reaches the build workflow directly or through shared build validation.
Direct build callers
These commands invoke the build workflow directly, so they should surface the warning directly:
Invoke-NovaBuild% nova buildTest-NovaBuild -Build% nova test --build% nova test -bShared build-validation callers
These commands currently go through
Invoke-NovaBuildValidation, which callsInvoke-NovaBuildand thenTest-NovaBuildunless tests are skipped:New-NovaModulePackage% nova packagePublish-NovaModule% nova publishThe skip-tests variants should still hit this validation, because they still build:
New-NovaModulePackage -SkipTests% nova package --skip-tests% nova package -sPublish-NovaModule -SkipTests ...% nova publish --skip-tests ...Release callers
Invoke-NovaRelease/% nova releaseshould also surface the warning. The release workflow currently builds before testing/version bump and builds again after the version bump:Invoke-NovaRelease% nova releaseInvoke-NovaRelease -SkipTests ...% nova release --skip-tests ...% nova release -sEven with
-SkipTests, release still runs the build steps, so the validation should still stop there unless explicitly overridden.Commands that should NOT be affected
These public commands do not use the build workflow and should not need this warning:
Deploy-NovaPackageGet-NovaProjectInfoGet-NovaUpdateNotificationPreferenceInitialize-NovaModuleInstall-NovaCliInvoke-NovaCliin general, except when it routes to one of the affected commands aboveSet-NovaUpdateNotificationPreferenceUpdate-NovaModuleToolUpdate-NovaModuleVersionTest-NovaBuildwithout-BuildOverride behavior
The stop should be bypassable only when the user explicitly accepts this warning:
-OverrideWarning--override-warning-oThis keeps the override scoped to warning bypasses and leaves room for future override categories.
Warning/error message expectation
The message should explain:
src/publicfile failed validation-OverrideWarning/--override-warning/-oWhy this is a good fit
This keeps the current top-level function discovery logic intact, but adds a guardrail that prevents accidental API-surface leaks while still allowing advanced users to override the check intentionally.