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

[stiwicourage]

• 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.

Summary

• Add a shared build guard that stops build-driven workflows when a src/public file contains zero or multiple top-level functions, and add an explicit override path for maintainers who want to continue intentionally.
• This was needed because Nova currently exports every top-level function found in src/public, which makes it easy to leak helper functions into the public module surface by accident.
• Closes Build should stop when src/public files contain multiple or mismatched top-level functions #161.

Affected area

• nova CLI or command routing
• Public PowerShell cmdlet behavior
• Scaffolding or project.json handling
• Build, test, analyzer, coverage, or CI helper flow
• Package, raw upload, or package metadata workflow
• Publish, release, or GitHub Actions automation
• Self-update or notification preference behavior
• Contributor documentation (README.md, CONTRIBUTING.md, repository workflow docs)
• End-user docs (docs/*.html)
• Command help (docs/NovaModuleTools/en-US/*.md)
• src/resources/example/
• Dependency or manifest changes (project.json, workflow dependencies, release tooling)
• Security-sensitive change
• Documentation-only change
• Other

Review guidance

• Start with src/private/build/AssertNovaPublicFunctionFileLayout.ps1 and src/private/build/InvokeNovaBuildWorkflow.ps1; that is the new shared guardrail and the shared build entrypoint it plugs into.
• Then review the override plumbing across src/public/, src/private/shared/InvokeNovaBuildValidation.ps1, src/private/quality/InvokeNovaTestWorkflow.ps1, src/private/release/InvokeNovaReleaseWorkflow.ps1, and src/private/cli/.
• Docs/help/tests live under README.md, CHANGELOG.md, docs/NovaModuleTools/en-US/, and the updated/additional test files under tests/.
• Trade-off: repositories that currently keep helpers alongside the public function in a src/public file will now fail build-driven workflows by default. That is intentional, and maintainers can bypass it explicitly with -OverrideWarning / --override-warning / -o.

Validation

• Invoke-NovaBuild
• Test-NovaBuild
• ./scripts/build/Invoke-ScriptAnalyzerCI.ps1
• ./scripts/build/ci/Invoke-NovaModuleToolsCI.ps1
• Targeted Nova workflow validated (% nova build, % nova test, % nova merge, % nova deploy,
  % nova publish,
  % nova release, % nova update, % nova notification, or % nova init as relevant)
• Docs/example only; executable validation not needed

Validation notes:

Ran:
- Invoke-NovaBuild
- Test-NovaBuild
- ./scripts/build/Invoke-ScriptAnalyzerCI.ps1
- CodeScene pre_commit_code_health_safeguard

Also reran targeted Pester coverage for:
- build internals and workflow forwarding
- CLI parser and routed-command override handling
- package/publish/release workflow forwarding

Did not run ./scripts/build/ci/Invoke-NovaModuleToolsCI.ps1 or a manual `% nova ...` command in this pass.
The new CLI and workflow behavior is covered through the updated automated tests.

Documentation and release follow-up

• README.md reviewed and updated if contributor workflow, architecture, CI, release, or automation changed
• CONTRIBUTING.md reviewed and updated if contribution expectations or review guidance changed
• CHANGELOG.md reviewed and updated if the change matters to users, maintainers, or contributors
• docs/NovaModuleTools/en-US/ help updated if a public command or CLI behavior changed
• docs/*.html updated if end-user workflows or examples changed
• src/resources/example/ reviewed and updated if the real-world project layout, package model, or upload workflow
  changed
• No documentation, changelog, or example updates were needed

Maintainability, compatibility, and risk

• Code Health / maintainability impact considered
• No breaking change
• Breaking change
• Security-sensitive change
• CI, workflow, or release-pipeline impact
• Dependency-review impact

Risk, rollout, or rollback notes:

This changes default compatibility for repositories that currently keep multiple top-level functions in a single
src/public file: build-driven workflows now stop until the file layout is fixed or the maintainer explicitly opts in to
continue with the override switch.

That is intentional because the old behavior could silently expand the public API surface. The override was scoped
carefully so it only affects this build warning path and is not forwarded into publish or version-bump actions that do
not support it.

Rollback is straightforward: revert the new guard helper and the override plumbing.

Important

Do not use a public pull request to disclose a vulnerability before coordinated handling.
Use the private reporting path in SECURITY.md for new security issues.

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[codescene-delta-analysis]

Gates Passed
6 Quality Gates Passed

See analysis details in CodeScene

Quality Gate Profile: Pay Down Tech Debt
Install CodeScene MCP: safeguard and uplift AI-generated code. Catch issues early with our IDE extension and CLI tool.

[codescene-delta-analysis]

Code Coverage Gates Passed
Overall Coverage: 100.0% (required = 95%)
New & Changed Code Coverage: 100% (required = 100%)

Review details by gate

• Overall Coverage

  • Pass/Fail Reason:
    The overall coverage gate was checked for all code and meets the goal: 100.0% covered >= threshold = 95%
  • Action:
    You have 281 files with a sum of 2844 covered and 1 uncovered lines of code.

• New & Changed Code Coverage

  • Pass/Fail Reason:
    New or changed code meets coverage goal: 100% covered >= threshold = 100%
  • Action:
    You modified 21 files, and covered 89 added/modified lines of code.