PSDependencyCanary

1.1.0

en-US/PSDependencyCanary-help.xml

<?xml version="1.0" encoding="utf-8"?>
<helpItems schema="maml" xmlns="http://msh">
  <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
    <command:details>
      <command:name>Clear-PSDependencyCanaryEnvironment</command:name>
      <command:verb>Clear</command:verb>
      <command:noun>PSDependencyCanaryEnvironment</command:noun>
      <maml:description>
        <maml:para>Removes a project's installed PowerShell dependencies before bootstrapping.</maml:para>
      </maml:description>
    </command:details>
    <maml:description>
      <maml:para>Removes every installed version of PSDepend, PSDependencyCanary, modules declared in requirements.psd1, and modules declared by RequiredModules in the project manifest. Pester 3.x is preserved for Windows PowerShell compatibility.</maml:para>
      <maml:para>Run this command in its own process or CI step. The executing PSDependencyCanary module remains loaded in memory until the process exits even after its installed files have been removed. The next process can then install only the project's committed dependency pins.</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>Clear-PSDependencyCanaryEnvironment</maml:name>
        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none">
          <maml:name>ProjectRoot</maml:name>
          <maml:description>
            <maml:para>Root directory of the PowerShell module project. Defaults to BHProjectPath when available and otherwise to the current directory.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="false">String</command:parameterValue>
          <dev:type>
            <maml:name>String</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>None</dev:defaultValue>
        </command:parameter>
        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none">
          <maml:name>ModulePath</maml:name>
          <maml:description>
            <maml:para>Module roots to clean. Defaults to the current process PSModulePath entries. This parameter is primarily useful for isolated validation.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
          <dev:type>
            <maml:name>String[]</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>None</dev:defaultValue>
        </command:parameter>
        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
          <maml:name>AllowPreinstalledModules</maml:name>
          <maml:description>
            <maml:para>Warn instead of failing when a protected or locked dependency cannot be removed.</maml:para>
          </maml:description>
          <dev:type>
            <maml:name>SwitchParameter</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>False</dev:defaultValue>
        </command:parameter>
        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi">
          <maml:name>WhatIf</maml:name>
          <maml:description>
            <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para>
          </maml:description>
          <dev:type>
            <maml:name>SwitchParameter</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>False</dev:defaultValue>
        </command:parameter>
        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf">
          <maml:name>Confirm</maml:name>
          <maml:description>
            <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para>
          </maml:description>
          <dev:type>
            <maml:name>SwitchParameter</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>False</dev:defaultValue>
        </command:parameter>
        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga">
          <maml:name>ProgressAction</maml:name>
          <maml:description>
            <maml:para>{{ Fill ProgressAction Description }}</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue>
          <dev:type>
            <maml:name>ActionPreference</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>None</dev:defaultValue>
        </command:parameter>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters>
      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none">
        <maml:name>ProjectRoot</maml:name>
        <maml:description>
          <maml:para>Root directory of the PowerShell module project. Defaults to BHProjectPath when available and otherwise to the current directory.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="false">String</command:parameterValue>
        <dev:type>
          <maml:name>String</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>None</dev:defaultValue>
      </command:parameter>
      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none">
        <maml:name>ModulePath</maml:name>
        <maml:description>
          <maml:para>Module roots to clean. Defaults to the current process PSModulePath entries. This parameter is primarily useful for isolated validation.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="false">String[]</command:parameterValue>
        <dev:type>
          <maml:name>String[]</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>None</dev:defaultValue>
      </command:parameter>
      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
        <maml:name>AllowPreinstalledModules</maml:name>
        <maml:description>
          <maml:para>Warn instead of failing when a protected or locked dependency cannot be removed.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
        <dev:type>
          <maml:name>SwitchParameter</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>False</dev:defaultValue>
      </command:parameter>
      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi">
        <maml:name>WhatIf</maml:name>
        <maml:description>
          <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
        <dev:type>
          <maml:name>SwitchParameter</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>False</dev:defaultValue>
      </command:parameter>
      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf">
        <maml:name>Confirm</maml:name>
        <maml:description>
          <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
        <dev:type>
          <maml:name>SwitchParameter</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>False</dev:defaultValue>
      </command:parameter>
      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga">
        <maml:name>ProgressAction</maml:name>
        <maml:description>
          <maml:para>{{ Fill ProgressAction Description }}</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue>
        <dev:type>
          <maml:name>ActionPreference</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>None</dev:defaultValue>
      </command:parameter>
    </command:parameters>
    <command:inputTypes />
    <command:returnValues />
    <maml:alertSet>
      <maml:alert>
        <maml:para></maml:para>
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title>
        <dev:code>Clear-PSDependencyCanaryEnvironment -ProjectRoot . -Confirm:$false</dev:code>
        <dev:remarks>
          <maml:para>Cleans installed project dependencies before the committed bootstrap.</maml:para>
        </dev:remarks>
      </command:example>
      <command:example>
        <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title>
        <dev:code>Clear-PSDependencyCanaryEnvironment -ProjectRoot . -WhatIf</dev:code>
        <dev:remarks>
          <maml:para>Shows which installed dependency directories would be removed.</maml:para>
        </dev:remarks>
      </command:example>
    </command:examples>
    <command:relatedLinks />
  </command:command>
  <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
    <command:details>
      <command:name>Test-PSDependencyCanary</command:name>
      <command:verb>Test</command:verb>
      <command:noun>PSDependencyCanary</command:noun>
      <maml:description>
        <maml:para>Runs a module project's complete test build for a dependency candidate.</maml:para>
      </maml:description>
    </command:details>
    <maml:description>
      <maml:para>Executes the project's Test task in a clean child PowerShell process with dependency bootstrap enabled, then verifies the expected module artifact. This lower-level command is primarily useful for validating an already-created candidate under another PowerShell edition. Scheduled CI/CD should normally invoke the shared Canary task.</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>Test-PSDependencyCanary</maml:name>
        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none">
          <maml:name>ProjectRoot</maml:name>
          <maml:description>
            <maml:para>Root directory of the candidate project.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="false">String</command:parameterValue>
          <dev:type>
            <maml:name>String</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>None</dev:defaultValue>
        </command:parameter>
        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga">
          <maml:name>ProgressAction</maml:name>
          <maml:description>
            <maml:para>{{ Fill ProgressAction Description }}</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue>
          <dev:type>
            <maml:name>ActionPreference</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>None</dev:defaultValue>
        </command:parameter>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters>
      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none">
        <maml:name>ProjectRoot</maml:name>
        <maml:description>
          <maml:para>Root directory of the candidate project.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="false">String</command:parameterValue>
        <dev:type>
          <maml:name>String</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>None</dev:defaultValue>
      </command:parameter>
      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga">
        <maml:name>ProgressAction</maml:name>
        <maml:description>
          <maml:para>{{ Fill ProgressAction Description }}</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue>
        <dev:type>
          <maml:name>ActionPreference</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>None</dev:defaultValue>
      </command:parameter>
    </command:parameters>
    <command:inputTypes />
    <command:returnValues />
    <maml:alertSet>
      <maml:alert>
        <maml:para></maml:para>
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title>
        <dev:code>Test-PSDependencyCanary -ProjectRoot .</dev:code>
        <dev:remarks>
          <maml:para>Validates an already-created candidate in the current PowerShell edition and verifies its staged module manifest.</maml:para>
        </dev:remarks>
      </command:example>
    </command:examples>
    <command:relatedLinks />
  </command:command>
  <command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
    <command:details>
      <command:name>Update-PSDependencyCanary</command:name>
      <command:verb>Update</command:verb>
      <command:noun>PSDependencyCanary</command:noun>
      <maml:description>
        <maml:para>Updates a module project's dependencies only after baseline and candidate tests pass.</maml:para>
      </maml:description>
    </command:details>
    <maml:description>
      <maml:para>Finds newer PSGallery versions for dependencies declared in requirements.psd1 and RequiredModules. When updates are available, the unchanged project must pass its Test build task before any files are edited. The complete candidate is then applied temporarily and tested again with dependency bootstrap enabled. Failed candidates are restored. Build-only updates do not change the module version; a RequiredModules update patch-bumps the shipped module manifest and updates the changelog. The applying behavior of this lower-level API is used by the shared Canary task; invoke that task to create dependency candidates.</maml:para>
    </maml:description>
    <command:syntax>
      <command:syntaxItem>
        <maml:name>Update-PSDependencyCanary</maml:name>
        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none">
          <maml:name>ProjectRoot</maml:name>
          <maml:description>
            <maml:para>Root directory of the PowerShell module project. Defaults to BHProjectPath when available and otherwise to the current directory.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="false">String</command:parameterValue>
          <dev:type>
            <maml:name>String</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>None</dev:defaultValue>
        </command:parameter>
        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none">
          <maml:name>ModuleManifestPath</maml:name>
          <maml:description>
            <maml:para>Optional module manifest path. Conventional src layouts are auto-discovered.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="false">String</command:parameterValue>
          <dev:type>
            <maml:name>String</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>None</dev:defaultValue>
        </command:parameter>
        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none">
          <maml:name>RequirementsPath</maml:name>
          <maml:description>
            <maml:para>PSDepend build requirements file. Defaults to requirements.psd1.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="false">String</command:parameterValue>
          <dev:type>
            <maml:name>String</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>None</dev:defaultValue>
        </command:parameter>
        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="4" aliases="none">
          <maml:name>ChangelogPath</maml:name>
          <maml:description>
            <maml:para>Keep a Changelog document updated when RequiredModules changes. Defaults to CHANGELOG.md.</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="false">String</command:parameterValue>
          <dev:type>
            <maml:name>String</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>None</dev:defaultValue>
        </command:parameter>
        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
          <maml:name>SkipChangelog</maml:name>
          <maml:description>
            <maml:para>Patch-bump runtime dependency candidates without reading or updating a changelog.</maml:para>
          </maml:description>
          <dev:type>
            <maml:name>SwitchParameter</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>False</dev:defaultValue>
        </command:parameter>
        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi">
          <maml:name>WhatIf</maml:name>
          <maml:description>
            <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para>
          </maml:description>
          <dev:type>
            <maml:name>SwitchParameter</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>False</dev:defaultValue>
        </command:parameter>
        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf">
          <maml:name>Confirm</maml:name>
          <maml:description>
            <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para>
          </maml:description>
          <dev:type>
            <maml:name>SwitchParameter</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>False</dev:defaultValue>
        </command:parameter>
        <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga">
          <maml:name>ProgressAction</maml:name>
          <maml:description>
            <maml:para>{{ Fill ProgressAction Description }}</maml:para>
          </maml:description>
          <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue>
          <dev:type>
            <maml:name>ActionPreference</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>None</dev:defaultValue>
        </command:parameter>
      </command:syntaxItem>
    </command:syntax>
    <command:parameters>
      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none">
        <maml:name>ProjectRoot</maml:name>
        <maml:description>
          <maml:para>Root directory of the PowerShell module project. Defaults to BHProjectPath when available and otherwise to the current directory.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="false">String</command:parameterValue>
        <dev:type>
          <maml:name>String</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>None</dev:defaultValue>
      </command:parameter>
      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none">
        <maml:name>ModuleManifestPath</maml:name>
        <maml:description>
          <maml:para>Optional module manifest path. Conventional src layouts are auto-discovered.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="false">String</command:parameterValue>
        <dev:type>
          <maml:name>String</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>None</dev:defaultValue>
      </command:parameter>
      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none">
        <maml:name>RequirementsPath</maml:name>
        <maml:description>
          <maml:para>PSDepend build requirements file. Defaults to requirements.psd1.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="false">String</command:parameterValue>
        <dev:type>
          <maml:name>String</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>None</dev:defaultValue>
      </command:parameter>
      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="4" aliases="none">
        <maml:name>ChangelogPath</maml:name>
        <maml:description>
          <maml:para>Keep a Changelog document updated when RequiredModules changes. Defaults to CHANGELOG.md.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="false">String</command:parameterValue>
        <dev:type>
          <maml:name>String</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>None</dev:defaultValue>
      </command:parameter>
      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none">
        <maml:name>SkipChangelog</maml:name>
        <maml:description>
          <maml:para>Patch-bump runtime dependency candidates without reading or updating a changelog.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
        <dev:type>
          <maml:name>SwitchParameter</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>False</dev:defaultValue>
      </command:parameter>
      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="wi">
        <maml:name>WhatIf</maml:name>
        <maml:description>
          <maml:para>Shows what would happen if the cmdlet runs. The cmdlet is not run.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
        <dev:type>
          <maml:name>SwitchParameter</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>False</dev:defaultValue>
      </command:parameter>
      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="cf">
        <maml:name>Confirm</maml:name>
        <maml:description>
          <maml:para>Prompts you for confirmation before running the cmdlet.</maml:para>
        </maml:description>
        <command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
        <dev:type>
          <maml:name>SwitchParameter</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>False</dev:defaultValue>
      </command:parameter>
      <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="proga">
        <maml:name>ProgressAction</maml:name>
        <maml:description>
          <maml:para>{{ Fill ProgressAction Description }}</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="false">ActionPreference</command:parameterValue>
        <dev:type>
          <maml:name>ActionPreference</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>None</dev:defaultValue>
      </command:parameter>
    </command:parameters>
    <command:inputTypes />
    <command:returnValues />
    <maml:alertSet>
      <maml:alert>
        <maml:para></maml:para>
      </maml:alert>
    </maml:alertSet>
    <command:examples>
      <command:example>
        <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title>
        <dev:code>Update-PSDependencyCanary -ProjectRoot . -WhatIf</dev:code>
        <dev:remarks>
          <maml:para>Reports available dependency changes without bootstrapping, testing, or editing.</maml:para>
        </dev:remarks>
      </command:example>
    </command:examples>
    <command:relatedLinks />
  </command:command>
</helpItems>