fix: align example scaffold tests with source coverage

Author: stiwicourage

CHANGELOG.md

@@ -22,6 +22,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - The command cheat sheet now stacks the three "Set up a project" cards vertically so the section reads top-to-bottom without a missing grid slot.
 - The Agentic Copilot starter shipped by `nova init` no longer tells generated projects to use a `run.ps1` quality wrapper that the template does not include.
     - The scaffold now points generated documentation and agent guidance to the repository quality loop wording plus the existing analyzer and `Test-NovaBuild` entrypoints instead.
+- `nova init --example` now ships the packaged example with source-mirrored tests and `Pester.CodeCoverage.Enabled = true` by default.
+    - The example scaffold now runs `Test-NovaBuild` against `src/**/*.ps1` without requiring a prior build, and the bundled docs describe that source-first coverage flow.
 
 ### Security
 

RELEASE_NOTE.md

@@ -15,6 +15,7 @@ This file summarizes the release notes for NovaModuleTools. **UNRELEASED** chang
 ### Fixed
 
 - The Agentic Copilot starter shipped by `nova init` no longer tells generated projects to use a `run.ps1` quality wrapper that the template does not include.
+- `nova init --example` now ships the packaged example with source-mirrored tests and code coverage enabled by default, so `Test-NovaBuild` works before a build and measures `src/**/*.ps1`.
 
 ### Security
 

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

@@ -27,7 +27,7 @@ PS> Initialize-NovaModule [-Path <string>] [-Example] [-WhatIf] [-Confirm] [<Com
 
 `Initialize-NovaModule` creates a new project folder, the standard `src/` layout, and a starter `project.json` file.
 
-The starter `project.json` includes Nova's standard Pester defaults, including an opt-in `CodeCoverage` block with `Enabled=false`, common `src/` coverage paths, JaCoCo output in `artifacts/coverage.xml`, and a `90` percent target that can be enabled later.
+The standard scaffold `project.json` includes Nova's standard Pester defaults, including an opt-in `CodeCoverage` block with `Enabled=false`, common `src/` coverage paths, JaCoCo output in `artifacts/coverage.xml`, and a `90` percent target that can be enabled later.
 
 The command collects project details interactively, including the module name, description, version, author, minimum PowerShell version, Git initialization, and an optional Agentic Copilot starter package. Before the first interactive question, Nova checks whether a newer `NovaModuleTools` release is available and warns without blocking the scaffold flow. When Git initialization is enabled, Nova also creates or updates a default `.gitignore` in the generated project root so common local and CI artifact paths such as `artifacts/`, `dist/`, `run.ps1`, and `reload.ps1` are ignored from the start. Existing `.gitignore` files are preserved and only receive the missing Nova-managed entries. When you enable the Agentic package, Nova also asks for a project short name used in generated guidance placeholders such as `Invoke-<ShortName>*`; for NovaModuleTools the short name is `Nova`, but it could also have been
 `NMT`. The Agentic package follows Nova's maintained agentic guidance through a filtered starter mirror, including Nova build/test/package expectations, `project.json`
@@ -40,7 +40,7 @@ Use this command when you want to start a new module in the NovaModuleTools stru
 
 Use `-Path` when you want to create the project under a specific base directory. Positional path syntax is no longer supported.
 
-Use `-Example` when you want the scaffold to start from the packaged example project instead of the minimal default layout. The example flow keeps the example source, resource, and test files, skips the Pester enable/disable question, and applies the interactive metadata values to the copied `project.json`, including the same disabled-by-default `CodeCoverage` block that the standard scaffold uses. The standard and example flows share the same upfront Nova update warning, inline validation and retry behavior for interactive answers, and optional Agentic Copilot setup prompt after the Git question. When Git is enabled in either flow, Nova also ensures the generated project root has the default `.gitignore` entries for local and CI artifacts without overwriting any existing `.gitignore` content. When you answer
+Use `-Example` when you want the scaffold to start from the packaged example project instead of the minimal default layout. The example flow keeps the example source, resource, and source-mirrored test files, skips the Pester enable/disable question, and applies the interactive metadata values to the copied `project.json`, including an enabled-by-default `CodeCoverage` block that targets `src/**/*.ps1`. The packaged example can run `Test-NovaBuild` before `Invoke-NovaBuild`, and the same test flow writes JaCoCo coverage to `artifacts/coverage.xml`. The standard and example flows share the same upfront Nova update warning, inline validation and retry behavior for interactive answers, and optional Agentic Copilot setup prompt after the Git question. When Git is enabled in either flow, Nova also ensures the generated project root has the default `.gitignore` entries for local and CI artifacts without overwriting any existing `.gitignore` content. When you answer
 `Yes`, Nova asks for the short project name, adds the same starter package to either scaffold style, and merges the example README instead of replacing it with the generic starter README outright.
 
 This command supports `-WhatIf` and `-Confirm` through PowerShell `SupportsShouldProcess`. Use `-WhatIf` to preview the scaffold target after the interactive answers have been collected, without creating folders, writing `project.json`, or initializing Git.
@@ -142,7 +142,7 @@ This cmdlet does not emit an output object.
 
 ## NOTES
 
-Generated projects start with NovaModuleTools defaults for recursive discovery, source markers, duplicate-function validation, an opt-in Pester `CodeCoverage` block (`Enabled=false`, shared `src/` paths, JaCoCo output in `artifacts/coverage.xml`, and a `90` percent target), and—when Git is enabled—a default `.gitignore` for common local and CI artifact paths. The packaged example scaffold keeps its bundled example source and tests, while still updating prompt-driven metadata such as project name, description, version, author, and PowerShell host version. The optional Agentic Copilot starter package adds repository-local Copilot workflow files under the project root and `.github/` that tell agents to keep build/test/package workflows on Nova, treat `project.json` `Manifest.PowerShellHostVersion` as the PowerShell compatibility target, run ScriptAnalyzer before build/test through the repo-standard `Invoke-ScriptAnalyzerCI.ps1` /
+Generated projects start with NovaModuleTools defaults for recursive discovery, source markers, duplicate-function validation, and—when Git is enabled—a default `.gitignore` for common local and CI artifact paths. The standard scaffold keeps Pester `CodeCoverage` opt-in (`Enabled=false`, shared `src/` paths, JaCoCo output in `artifacts/coverage.xml`, and a `90` percent target). The packaged example scaffold keeps its bundled example source and source-mirrored tests, while also enabling that same `CodeCoverage` block by default so `Test-NovaBuild` measures `src/**/*.ps1` without requiring a prior build. Both scaffold styles still update prompt-driven metadata such as project name, description, version, author, and PowerShell host version. The optional Agentic Copilot starter package adds repository-local Copilot workflow files under the project root and `.github/` that tell agents to keep build/test/package workflows on Nova, treat `project.json` `Manifest.PowerShellHostVersion` as the PowerShell compatibility target, run ScriptAnalyzer before build/test through the repo-standard `Invoke-ScriptAnalyzerCI.ps1` /
 `run.ps1` workflow, fix any ScriptAnalyzer findings before handoff, run project tests through `Test-NovaBuild` instead of direct `Invoke-Pester`, leave `.psm1` / `.psd1` files to generated
 `dist` output, generate and validate command help with the Microsoft.PowerShell.PlatyPS cmdlets instead of hand-written Markdown structure, require a matching help file for every new public entry point in the same change, mirror new tests to source files, and add a text-file-formatting guardrail helper plus a Pester guardrail test when project tests are enabled.
 

docs/commands.html

@@ -179,8 +179,9 @@ <h3>Start a new project</h3>
                             <li><strong>Use when:</strong> you are creating a fresh NovaModuleTools project</li>
                             <li><strong>Includes:</strong> a pre-question Nova release warning, best-effort
                                 <code>.gitignore</code> creation or update when Git is enabled, and Nova's default
-                                <code>Pester.CodeCoverage</code> block in <code>project.json</code> with coverage still
-                                disabled until you choose to turn it on</li>
+                                <code>Pester.CodeCoverage</code> block in <code>project.json</code>; the minimal
+                                scaffold keeps coverage opt-in, while the packaged example scaffold starts with coverage
+                                enabled against <code>src/**/*.ps1</code></li>
                             <li><strong>Optional:</strong> add the <strong>Agentic Copilot</strong> starter package for Nova-maintained
                                 build, test, analyzer, help, and guidance files; if you enable it, Nova also asks for a
                                 short project name for placeholders such as <code>Invoke-&lt;ShortName&gt;*</code></li>

docs/core-workflows.html

@@ -147,9 +147,11 @@ <h2>Create the project</h2>
                     <code>Test-MarkdownCommandHelp</code>, with a matching help file required for every new public
                     entry point, and a strict file-ending rule for changed or generated text files.</p>
                 <p>The generated <code>project.json</code> also starts with Nova's standard <code>Pester</code>
-                    defaults, including a disabled <code>CodeCoverage</code> block with explicit source coverage paths
-                    for <code>src/public/</code>, nested <code>src/private/</code> helper folders, and
-                    <code>src/classes/</code>, so you can enable coverage later without hand-authoring the structure.</p>
+                    defaults, including explicit source coverage paths for <code>src/public/</code>, nested
+                    <code>src/private/</code> helper folders, and <code>src/classes/</code>. The minimal scaffold keeps
+                    <code>CodeCoverage</code> disabled until you opt in, while the packaged example scaffold enables it
+                    by default so <code>Test-NovaBuild</code> can measure <code>src/**/*.ps1</code> without requiring a
+                    prior build.</p>
                 <p>When you answer <code>Yes</code>, Nova also asks for a short project name used in generated guidance
                     placeholders such as <code>Invoke-&lt;ShortName&gt;*</code>. For NovaModuleTools the short name is
                     <code>Nova</code>, but it could also have been <code>NMT</code>.</p>

docs/getting-started.html

@@ -218,10 +218,12 @@ <h2>4. Scaffold the packaged example</h2>
                     entry point, and a strict file-ending rule for changed or generated text files.</p>
                 <p>Nova then creates a project folder under the path you selected.</p>
                 <p>The generated <code>project.json</code> also starts with Nova's standard <code>Pester</code>
-                    defaults, including an opt-in <code>CodeCoverage</code> block with <code>Enabled=false</code>,
-                    explicit source coverage paths for <code>src/public/</code>, nested <code>src/private/</code>
-                    helper folders, and <code>src/classes/</code>, JaCoCo output in <code>artifacts/coverage.xml</code>,
-                    and a <code>90</code> percent target you can enable later.</p>
+                    defaults, including explicit source coverage paths for <code>src/public/</code>, nested
+                    <code>src/private/</code> helper folders, and <code>src/classes/</code>, JaCoCo output in
+                    <code>artifacts/coverage.xml</code>, and a <code>90</code> percent target. The minimal scaffold
+                    keeps that <code>CodeCoverage</code> block opt-in with <code>Enabled=false</code>, while the
+                    packaged example scaffold enables coverage by default so <code>Test-NovaBuild</code> measures
+                    <code>src/**/*.ps1</code> before any build step.</p>
                 <p>If you enable the Agentic package, Nova also asks for a short project name used in generated guidance
                     placeholders such as <code>Invoke-&lt;ShortName&gt;*</code>. For NovaModuleTools the short name is
                     <code>Nova</code>, but it could also have been <code>NMT</code>.</p>

docs/project-json-reference.html

@@ -675,10 +675,11 @@ <h2><code>Pester</code> settings</h2>
                     </table>
                 </div>
                 <p class="tiny-note">Starter projects now include the full <code>Pester.CodeCoverage</code> block with
-                    <code>Enabled=false</code> and the explicit default source globs shown above, so turning coverage on
-                    usually means changing only that switch. At runtime, <code>Test-NovaBuild</code> also lets you
-                    override verbosity and render mode temporarily with <code>-OutputVerbosity</code> and
-                    <code>-OutputRenderMode</code>.</p>
+                    the explicit default source globs shown above. The minimal scaffold keeps
+                    <code>Enabled=false</code>, while the packaged example scaffold sets <code>Enabled=true</code> so
+                    coverage works against <code>src/**/*.ps1</code> immediately. At runtime,
+                    <code>Test-NovaBuild</code> also lets you override verbosity and render mode temporarily with
+                    <code>-OutputVerbosity</code> and <code>-OutputRenderMode</code>.</p>
                 <p>When you enable coverage, Nova writes JaCoCo output to <code>artifacts/coverage.xml</code> and fails
                     the test workflow if the measured percentage is lower than
                     <code>Pester.CodeCoverage.CoveragePercentTarget</code>.</p>
@@ -698,8 +699,9 @@ <h3>Minimal module project</h3>
   }
 }</code></pre>
                 <p>Use this when you want the smallest hand-authored Nova project. Scaffolded projects start with
-                    additional <code>Pester</code> defaults, including a disabled <code>CodeCoverage</code> block, but
-                    Nova can still resolve its normal defaults when those sections are omitted.</p>
+                    additional <code>Pester</code> defaults; the minimal scaffold keeps <code>CodeCoverage</code>
+                    disabled until you opt in, while the packaged example scaffold enables it by default. Nova can
+                    still resolve its normal defaults when those sections are omitted.</p>
 
                 <h3>Create both NuGet and Zip artifacts, plus latest aliases</h3>
                 <pre><code>{

src/resources/example/README.md

@@ -7,7 +7,7 @@ It is meant to help a new user understand the smallest useful setup that can:
 - build a module
 - include a private helper
 - include a resource file
-- run Pester tests against the built module
+- run Pester tests against source files with code coverage enabled
 - show the full `project.json` configuration surface in one place
 
 ## What is in this example?
@@ -22,7 +22,8 @@ It is meant to help a new user understand the smallest useful setup that can:
 - `src/public/Get-ExampleGreeting.ps1` – a public function exported from the built module
 - `src/private/Get-ExampleConfiguration.ps1` – a private helper used by the public function
 - `src/resources/greeting-config.json` – a resource file bundled into the built module
-- `tests/Pester.Some.Tests.ps1` – tests that import the built module and verify its behavior
+- `tests/public/Get-ExampleGreeting.Tests.ps1` – source-mirrored tests for the public function
+- `tests/private/Get-ExampleConfiguration.Tests.ps1` – source-mirrored tests for the private helper and resource resolution
 
 ## Quick start
 
@@ -35,8 +36,8 @@ If `./dist/NovaModuleTools` is not available yet, build `NovaModuleTools` from t
 ```text
 PS> Import-Module ./dist/NovaModuleTools -Force
 PS> Set-Location ./src/resources/example
-PS> Invoke-NovaBuild
 PS> Test-NovaBuild
+PS> Invoke-NovaBuild
 PS> New-NovaModulePackage
 PS> $project = Get-NovaProjectInfo
 PS> Import-Module $project.OutputModuleDir -Force
@@ -51,8 +52,8 @@ PS> Install-Module NovaModuleTools
 PS> Import-Module NovaModuleTools
 PS> $module = Get-Module NovaModuleTools -ListAvailable | Select-Object -First 1
 PS> Set-Location (Join-Path $module.ModuleBase 'resources/example')
-PS> Invoke-NovaBuild
 PS> Test-NovaBuild
+PS> Invoke-NovaBuild
 PS> New-NovaModulePackage
 PS> $project = Get-NovaProjectInfo
 PS> Import-Module $project.OutputModuleDir -Force
@@ -61,6 +62,12 @@ PS> Get-ExampleGreeting
 
 ## Expected result
 
+After `Test-NovaBuild`, the example tests run against `src/**/*.ps1` and JaCoCo coverage is written to:
+
+```text
+src/resources/example/artifacts/coverage.xml
+```
+
 After `Invoke-NovaBuild`, the built module is written to:
 
 ```text
@@ -112,7 +119,7 @@ This example is intentionally small, but it demonstrates the most important Nova
 - how module-level preamble lines from `project.json` are emitted before the generated source markers and module code
 - how public and private functions are combined into one module
 - how resource files are copied and used at runtime
-- how tests should import the built module from `dist/`
+- how tests can run against source files before a build while still producing coverage
 - where the current package, packaging, and raw-upload configuration keys live in `project.json`
 
 If you want a new project scaffold, use `PS> Initialize-NovaModule` (`% nova init`). If you want a concrete project you can inspect, run, or copy through `% nova init --example` / `% nova init -e`, use this example folder.

src/resources/example/project.json

@@ -83,7 +83,7 @@
   },
   "Pester": {
     "CodeCoverage": {
-      "Enabled": false,
+      "Enabled": true,
       "Path": [
         "src/public/*.ps1",
         "src/private/*.ps1",

src/resources/example/src/private/Get-ExampleConfiguration.ps1

@@ -1,12 +1,28 @@
-function Get-ExampleConfiguration {
+function Get-ExampleConfigurationPath {
     [CmdletBinding()]
-    param()
+    param(
+        [string]$BasePath = $PSScriptRoot
+    )
+
+    $candidatePathList = @(
+        [System.IO.Path]::GetFullPath((Join-Path $BasePath 'resources/greeting-config.json'))
+        [System.IO.Path]::GetFullPath((Join-Path $BasePath '../resources/greeting-config.json'))
+    ) | Select-Object -Unique
 
-    $configurationPath = Join-Path $PSScriptRoot 'resources/greeting-config.json'
-    if (-not (Test-Path -LiteralPath $configurationPath)) {
-        Stop-NovaOperation -Message "Example configuration not found: $configurationPath" -ErrorId 'Nova.Environment.ExampleConfigurationNotFound' -Category ObjectNotFound -TargetObject $configurationPath
+    foreach ($candidatePath in $candidatePathList) {
+        if (Test-Path -LiteralPath $candidatePath) {
+            return $candidatePath
+        }
     }
 
+    Stop-NovaOperation -Message "Example configuration not found. Checked: $( $candidatePathList -join ', ' )" -ErrorId 'Nova.Environment.ExampleConfigurationNotFound' -Category ObjectNotFound -TargetObject 'resources/greeting-config.json'
+}
+
+function Get-ExampleConfiguration {
+    [CmdletBinding()]
+    param()
+
+    $configurationPath = Get-ExampleConfigurationPath
     $configuration = Get-Content -LiteralPath $configurationPath -Raw | ConvertFrom-Json
     return [pscustomobject]@{
         GreetingPrefix = $configuration.GreetingPrefix