Merge branch 'main' into RSATDependencies

Author: tablackburn

.github/FUNDING.yml

@@ -0,0 +1,80 @@
+name: CI
+on:
+  push:
+    branches: [main]
+    paths:
+      - "PSDepend/**"
+      - "Tests/**"
+      - "build.ps1"
+      - "psakeFile.ps1"
+      - "requirements.psd1"
+  pull_request:
+    paths:
+      - "PSDepend/**"
+      - "Tests/**"
+      - "build.ps1"
+      - "psakeFile.ps1"
+      - "requirements.psd1"
+  workflow_dispatch:
+
+jobs:
+  test_pwsh:
+    name: Test (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macOS-latest]
+    steps:
+      - uses: actions/checkout@v6
+      - name: Bootstrap
+        shell: pwsh
+        run: ./build.ps1 -Bootstrap -Task Init
+      - name: Test
+        shell: pwsh
+        run: ./build.ps1 -Task Test
+      - name: Upload Test Results
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: testResults-${{ matrix.os }}
+          path: ./Tests/out/testResults.xml
+
+  test_ps51:
+    name: Test (Windows PowerShell 5.1)
+    runs-on: windows-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+      - name: Bootstrap
+        shell: powershell
+        run: ./build.ps1 -Bootstrap -Task Init
+      - name: Test
+        shell: powershell
+        run: ./build.ps1 -Task Test
+      - name: Upload Test Results
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: testResults-ps51
+          path: ./Tests/out/testResults.xml
+  publish-test-results:
+    name: Publish Test Results
+    needs:
+      - test_pwsh
+      - test_ps51
+    runs-on: ubuntu-latest
+    permissions:
+      checks: write
+      pull-requests: write
+    if: ${{ !cancelled() }}
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          path: artifacts
+      - uses: EnricoMi/publish-unit-test-result-action@v2
+        with:
+          files: artifacts/**/*.xml

.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: Mark stale issues and PRs
+
+on:
+  schedule:
+    - cron: '0 8 * * *'
+  workflow_dispatch: 
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/stale@v9
+        with:
+          stale-issue-message: 'This issue has had no activity for 60 days. It will be closed in 30 days unless there is new activity or a maintainer removes the stale label.'
+          stale-pr-message: 'This PR has had no activity for 60 days. It will be closed in 30 days unless there is new activity or a maintainer removes the stale label.'
+          close-issue-message: 'Closing due to inactivity. Please re-open if this is still relevant against the current version.'
+          days-before-stale: 60
+          days-before-close: 30
+          stale-issue-label: 'status: stale'
+          stale-pr-label: 'status: stale'
+          exempt-issue-labels: 'priority: high'

.github/workflows/stale.yml

@@ -1 +1,4 @@
-nuget.exe
+nuget.exe
+Output/**
+Tests/Output/**
+Tests/out/**

.gitignore

@@ -3,5 +3,7 @@
     "powershell.codeFormatting.ignoreOneLineBlock": false,
     "powershell.codeFormatting.whitespaceAfterSeparator": false,
     "powershell.codeFormatting.whitespaceAroundOperator": false,
-    "powershell.codeFormatting.whitespaceBeforeOpenParen": false
-}
+    "powershell.codeFormatting.whitespaceBeforeOpenParen": false,
+    "powershell.codeFormatting.preset": "OTBS",
+    "powershell.codeFormatting.trimWhitespaceAroundPipe": true
+}

.vscode/settings.json

@@ -0,0 +1,22 @@
+# CLAUDE.md
+
+## Build and Test
+
+Bootstrap: `.\build.ps1 -Bootstrap`
+
+Always run `.\build.ps1 StageFiles` before running tests — tests import from `Output\`, not source.
+
+## Architecture
+
+No compilation; files are staged verbatim to `Output\` — do not edit files under `Output\`.
+
+### Extending with new dependency types
+
+Two files must be updated together:
+
+1. **`PSDepend/PSDependScripts/<Type>.ps1`** — handler script. Must include comment-based help and a `PSDependAction` parameter accepting `Install`, `Test`, and `Import` values.
+2. **`PSDepend/PSDependMap.psd1`** — registers the type, maps it to the script, and sets `Supports` to control platform filtering (`windows`, `core`, `macos`, `linux`).
+
+See `Git.ps1` and `PSGalleryModule.ps1` as reference implementations.
+
+`PSDepend/PSDepend.Config` — path variables (`NuGetPath`, etc.) resolved at module load.

CLAUDE.md

@@ -0,0 +1,66 @@
+# PSDepend
+
+A PowerShell dependency handler that resolves, installs, imports, and tests dependencies declared in `.psd1` files using a pluggable set of DependencyScripts.
+
+## Language
+
+**Dependency**:
+The unit of work — a named, versioned item to be resolved, with a DependencyType, Target, Tags, and optional Prerequisites.
+_Avoid_: package, module, requirement
+
+**DependencyFile**:
+A `.psd1` file that declares one or more Dependencies. Filename is arbitrary; `requirements.psd1` is conventional, not canonical.
+_Avoid_: requirements file, depend file, manifest
+
+**DependencyType**:
+The registered identifier that selects which DependencyScript handles a Dependency (e.g., `PSGalleryModule`, `Git`, `Chocolatey`).
+_Avoid_: type, provider, handler type
+
+**DependencyScript**:
+A `PSDependScripts/<Type>.ps1` file that implements a DependencyType. Receives a typed Dependency object and a set of PSDependAction flags.
+_Avoid_: handler, plugin, provider
+
+**PSDependAction**:
+A set of flags (`Install`, `Test`, `Import`) passed to a DependencyScript. Flags are combinable; DependencyScripts must handle each valid combination.
+_Avoid_: mode, command, operation
+
+**Target**:
+A Dependency field with dual semantics: a scope keyword (`AllUsers`, `CurrentUser`) or a filesystem path. DependencyScripts branch explicitly on which it is.
+_Avoid_: destination, scope, path (use Target regardless of which semantic applies)
+
+**PSDependOptions**:
+A reserved key in a DependencyFile that sets default field values applied to all Dependencies in that file.
+_Avoid_: defaults, global options, file options
+
+**Prerequisite**:
+A declared ordering constraint between Dependencies. Expressed via the `DependsOn` field; resolved into topological execution order before dispatch.
+_Avoid_: dependency (to avoid confusion with the Dependency concept), requirement
+
+**Tag**:
+A label on a Dependency that controls inclusion when `Invoke-PSDepend` is called with `-Tags`.
+_Avoid_: filter, category, label
+
+## Relationships
+
+- A **DependencyFile** contains one or more **Dependencies** and at most one **PSDependOptions** block
+- A **Dependency** has exactly one **DependencyType**, which selects exactly one **DependencyScript**
+- A **Dependency** may declare zero or more **Prerequisites** (other Dependencies that must resolve first)
+- A **Dependency** may carry zero or more **Tags**
+- A **DependencyScript** receives a **Dependency** and a set of **PSDependAction** flags on each invocation
+- **Target** is a field on a **Dependency** interpreted differently by each **DependencyScript**
+
+## Example dialogue
+
+> **Dev:** "Should I add the new module as a dependency or a requirement?"
+> **Domain expert:** "It's a **Dependency** — declared in a **DependencyFile** with `DependencyType = 'PSGalleryModule'`."
+
+> **Dev:** "Where does it get installed — do I set the path or the scope?"
+> **Domain expert:** "Both are **Target**. If you want `CurrentUser`, set `Target = 'CurrentUser'`. If you want a specific folder, set `Target = 'C:\MyModules'`. The **DependencyScript** branches on which one it sees."
+
+> **Dev:** "I need psake to install before PowerShellBuild. How do I express that?"
+> **Domain expert:** "Declare a **Prerequisite** on PowerShellBuild: `DependsOn = 'psake'`. The engine resolves all **Prerequisites** into topological order before dispatching any **DependencyScript**."
+
+## Flagged ambiguities
+
+- "dependency" collides with **Prerequisite** in natural speech ("psake is a dependency of PowerShellBuild") — resolved: use **Prerequisite** for the ordering relationship, **Dependency** only for a declared entry in a DependencyFile.
+- "handler" was used in early CLAUDE.md — resolved: canonical term is **DependencyScript**.

CONTEXT.md

@@ -1,10 +1,10 @@
 # How Do I
 
-Rather than scour the documentation, which may or may not be scenario focused, here is a quick list of common scenarios and recipes.
+Common scenarios and recipes for working with PSDepend.
 
 ## Specify global defaults
 
-You can use the special PSDependOptions node for default options:
+Use the special `PSDependOptions` node to set defaults that apply to all dependencies in the file:
 
 ```powershell
 @{
@@ -13,29 +13,29 @@ You can use the special PSDependOptions node for default options:
         DependencyType = 'PSGalleryNuget'
     }
 
-    'PSDeploy' = 'latest'
-    'BuildHelpers' = 'latest'
-    'Pester' = 'latest'
-    'InvokeBuild' = 'latest'
+    'PSDeploy'      = 'latest'
+    'BuildHelpers'  = 'latest'
+    'Pester'        = 'latest'
+    'InvokeBuild'   = 'latest'
 }
 ```
 
-This downloads any dependency without an explicit override to `C:\MyProject`, using PSGalleryNuget
+All dependencies without an explicit override will be downloaded to `C:\MyProject` using `PSGalleryNuget`.
 
-You can specify the following in PSDependOptions:
+The following properties can be set in `PSDependOptions`:
 
-* Parameters
-* Source
-* Target
-* AddToPath
-* Tags
-* DependsOn
-* PreScripts
-* PostScripts
+- `Parameters`
+- `Source`
+- `Target`
+- `AddToPath`
+- `Tags`
+- `DependsOn`
+- `PreScripts`
+- `PostScripts`
 
-## Specify global defaults, with overrides
+## Override a global default for specific dependencies
 
-You can override global defaults:
+Individual dependencies can override any value set in `PSDependOptions`:
 
 ```powershell
 @{
@@ -44,7 +44,7 @@ You can override global defaults:
         DependencyType = 'PSGalleryNuget'
     }
 
-    'PSDeploy' = 'latest'
+    'PSDeploy'     = 'latest'
     'BuildHelpers' = 'latest'
     'Pester' = @{
         Target = 'C:\sc'
@@ -53,43 +53,34 @@ You can override global defaults:
 }
 ```
 
-In this example, all modules are downloaded to `C:\MyProject`, apart from Pester, which has an override.
-
-## Specify one target for all dependencies
+All modules install to `C:\MyProject` except `Pester`, which installs to `C:\sc`.
 
-You can certainly set a target on every single dependency, or:
+## Set a single target for all dependencies
 
 ```powershell
 @{
     PSDependOptions = @{
-        Target = 'C:\MyTarget'    # <<<<<<<
+        Target = 'C:\MyTarget'
     }
 
     PSDeploy = 'latest'
-    'darkoperator/ADAudit' = 'dev'
+    'PowerShellOrg/PSDepend' = 'main'
 }
 ```
 
-Just specify a target under PSDependOptions, this will be used as the default target unless you override it.
-
-## Specify one target for most dependencies
-
-If you want to specify one target for most dependencies, with a few exceptions:
+## Set a default target with per-dependency overrides
 
 ```powershell
 @{
     PSDependOptions = @{
-        Target = 'C:\MyTarget'    # <<<<<<<
+        Target = 'C:\MyTarget'
     }
 
-    PSDeploy = 'latest'
-    PSSlack = 'latest'
+    PSDeploy  = 'latest'
+    PSSlack   = 'latest'
     PSJira = @{
         Target = 'C:\OtherTarget'
     }
-    'darkoperator/ADAudit' = 'dev'
+    'PowerShellOrg/PSDepend' = 'main'
 }
 ```
-
-
-