Skip to content

Commit 1514ac0

Browse files
MariusStorhaugCopilot
MariusStorhaug
and
Copilot
authored
📖 [Docs]: Add full dependency tree with Mermaid diagrams (#368)
## Description Adds `DEPENDENCIES.md`, a full dependency tree for Process-PSModule, and links it from the README. The document maps every layer the workflow pulls in: - **Reusable workflows** — the entry `workflow.yml` and the 15 stage workflows it calls. - **GitHub Actions** — the PSModule composite actions and the third-party actions. - **Container image** — the `super-linter` Docker action. - **PowerShell modules** — the framework tree (`GitHub` → `Context` → `Sodium`, and more) and the tooling modules (`Pester`, `PSScriptAnalyzer`, `Microsoft.PowerShell.PlatyPS`, `powershell-yaml`, `Markdown`). - **Python packages** — the MkDocs packages installed by `Build-Site`. ## What's included - Three Mermaid diagrams: workflow and action composition, action foundation with PowerShell modules, and the non-PowerShell toolchains. - A dependency-type taxonomy and explicit boundaries for where the tree stops. - Per-type reference tables with links, plus external registries and services, auxiliary workflows, and out-of-scope notes. - A `Dependency tree` section in the README linking to the new document. ## Notes - Version pins are intentionally omitted; the workflow files under `.github/workflows/` remain the source of truth. - Documentation-only change with no release impact. Validated with markdownlint, codespell, and textlint against the repository linter configuration. --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
1 parent 364ddd6 commit 1514ac0

2 files changed

Lines changed: 368 additions & 0 deletions

File tree

‎DEPENDENCIES.md‎

Lines changed: 362 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,362 @@
1+
# Dependency tree
2+
3+
Process-PSModule is a reusable GitHub Actions workflow that composes the full PowerShell module lifecycle from many smaller, single-purpose building
4+
blocks. This document maps its complete dependency tree: from the entry workflow, through the reusable workflows it calls, down to the actions,
5+
container image, PowerShell modules, and Python packages that ultimately do the work.
6+
7+
The diagrams and tables below are built by reading the `uses:` entries and install steps in the workflow files under `.github/workflows/` and in each
8+
action those workflows call.
9+
10+
- [Dependency tree](#dependency-tree)
11+
- [Dependency types](#dependency-types)
12+
- [Where the tree stops](#where-the-tree-stops)
13+
- [Workflow and action composition](#workflow-and-action-composition)
14+
- [Action foundation and PowerShell modules](#action-foundation-and-powershell-modules)
15+
- [Non-PowerShell toolchains](#non-powershell-toolchains)
16+
- [Dependency reference](#dependency-reference)
17+
- [Reusable workflows](#reusable-workflows)
18+
- [PSModule actions](#psmodule-actions)
19+
- [Third-party actions](#third-party-actions)
20+
- [PowerShell modules](#powershell-modules)
21+
- [Python packages](#python-packages)
22+
- [External registries and services](#external-registries-and-services)
23+
- [Auxiliary workflows](#auxiliary-workflows)
24+
- [Out of scope](#out-of-scope)
25+
- [Keeping this document current](#keeping-this-document-current)
26+
27+
## Dependency types
28+
29+
Process-PSModule depends on several distinct kinds of artifact. The tree tracks all of them:
30+
31+
| Layer | Type | What it is | Examples |
32+
| --- | --- | --- | --- |
33+
| 1 | Reusable workflows | GitHub Actions workflows called with `uses: ./...` | `workflow.yml` and 15 stage workflows |
34+
| 2 | PSModule actions | Composite actions maintained in the PSModule organization | `GitHub-Script`, `Build-PSModule`, `Invoke-Pester` |
35+
| 3 | Third-party actions | Actions maintained outside the PSModule organization | `actions/checkout`, `actions/deploy-pages` |
36+
| 4 | Container image | A Docker action that runs a published image | `super-linter/super-linter` |
37+
| 5 | PowerShell modules (framework) | Runtime modules that power the PSModule actions | `GitHub`, `Context`, `Sodium` |
38+
| 6 | PowerShell modules (tooling) | Runtime modules that provide build, test, lint, and docs tools | `Pester`, `PSScriptAnalyzer`, `Microsoft.PowerShell.PlatyPS` |
39+
| 7 | PowerShell module (bundled) | A module vendored inside an action instead of installed from a registry | `Helpers` |
40+
| 8 | Python packages | `pip` packages installed to build the documentation site | `mkdocs-material` and MkDocs plugins |
41+
42+
## Where the tree stops
43+
44+
Each layer has a defined boundary so the tree stays finite and stable:
45+
46+
- **Reusable workflows** — the 15 stage workflows called by `workflow.yml`. They do not call further workflows.
47+
- **PSModule actions** — expanded fully; the leaves are `GitHub-Script` and `Install-PSModuleHelpers`.
48+
- **Third-party actions** — treated as leaves at the pinned commit. Their internal steps are not expanded.
49+
- **Container image** — the leaf is the `super-linter` image. The many linters bundled inside it are not enumerated.
50+
- **PowerShell modules** — expanded through their `RequiredModules` to the leaf modules. `Helpers` is a leaf because it ships inside the action.
51+
- **Python packages** — the packages installed directly with `pip install`. Their transitive PyPI closure is left to `pip`.
52+
- **Ambient runtimes and registries** — PowerShell, Python, Node.js, Git, the runner image, and the registries the artifacts come from are listed for
53+
context but not expanded.
54+
- **Consumer dependencies** — the modules a repository declares with `#Requires -Modules` belong to that repository, not to Process-PSModule, and are
55+
out of scope.
56+
57+
## Workflow and action composition
58+
59+
The entry workflow `workflow.yml` calls 15 reusable workflows, one per lifecycle stage. Each workflow uses one or more actions. Shared actions such as
60+
`actions/checkout` receive an edge from every workflow that uses them. `super-linter` is a Docker action and is shown as a container image.
61+
62+
```mermaid
63+
flowchart LR
64+
PPM(["Process-PSModule<br/>workflow.yml"]):::entry
65+
66+
subgraph WF["Reusable workflows (jobs)"]
67+
direction TB
68+
w1["Get-Settings"]
69+
w2["Lint-Repository"]
70+
w3["Build-Module"]
71+
w4["Test-SourceCode"]
72+
w5["Lint-SourceCode"]
73+
w6["Test-Module"]
74+
w7["BeforeAll-ModuleLocal"]
75+
w8["Test-ModuleLocal"]
76+
w9["AfterAll-ModuleLocal"]
77+
w10["Get-TestResults"]
78+
w11["Get-CodeCoverage"]
79+
w12["Publish-Module"]
80+
w13["Build-Docs"]
81+
w14["Build-Site"]
82+
w15["Publish-Site"]
83+
end
84+
85+
subgraph PSA["PSModule actions"]
86+
aSettings["Get-PSModuleSettings"]
87+
aBuild["Build-PSModule"]
88+
aTest["Test-PSModule"]
89+
aISA["Invoke-ScriptAnalyzer"]
90+
aIP["Invoke-Pester"]
91+
aIH["Install-PSModuleHelpers"]
92+
aGitHubScript["GitHub-Script"]
93+
aResults["Get-PesterTestResults"]
94+
aCov["Get-PesterCodeCoverage"]
95+
aPub["Publish-PSModule"]
96+
aDoc["Document-PSModule"]
97+
end
98+
99+
subgraph EXT["Third-party actions"]
100+
xCheckout["actions/checkout"]
101+
xDl["actions/download-artifact"]
102+
xUl["actions/upload-artifact"]
103+
xPages["actions/upload-pages-artifact"]
104+
xConf["actions/configure-pages"]
105+
xDeploy["actions/deploy-pages"]
106+
end
107+
108+
subgraph DK["Container image (Docker action)"]
109+
xSL["super-linter/super-linter"]
110+
xSLslim["super-linter/super-linter/slim"]
111+
end
112+
113+
PPM --> w1 & w2 & w3 & w4 & w5 & w6 & w7 & w8 & w9 & w10 & w11 & w12 & w13 & w14 & w15
114+
115+
w1 --> xCheckout & aSettings
116+
w2 --> xCheckout & xSL
117+
w3 --> xCheckout & aBuild
118+
w4 --> xCheckout & aTest
119+
w5 --> xCheckout & aISA
120+
w6 --> xCheckout & xDl & aISA & aTest
121+
w7 --> xCheckout & aGitHubScript
122+
w8 --> xCheckout & xDl & aIH & aIP
123+
w9 --> xCheckout & aGitHubScript
124+
w10 --> aResults
125+
w11 --> aCov
126+
w12 --> xCheckout & aPub
127+
w13 --> xCheckout & xDl & xUl & aDoc & aGitHubScript & xSLslim
128+
w14 --> xCheckout & xDl & xPages & aGitHubScript & aIH
129+
w15 --> xConf & xDeploy
130+
131+
classDef entry fill:#1f6feb,color:#fff,stroke:#1f6feb;
132+
classDef docker fill:#0db7ed,color:#000,stroke:#066699;
133+
class xSL,xSLslim docker;
134+
```
135+
136+
## Action foundation and PowerShell modules
137+
138+
Most PSModule actions build on two foundations: `GitHub-Script`, which runs a script with the `GitHub` module installed and authenticated, and
139+
`Install-PSModuleHelpers`, which loads a bundled `Helpers` module. The test, lint, and docs actions add their own tooling modules. At the bottom of the
140+
tree, `GitHub` resolves its own `RequiredModules` from the PowerShell Gallery.
141+
142+
```mermaid
143+
flowchart LR
144+
subgraph PSA["PSModule actions"]
145+
aGitHubScript["GitHub-Script"]
146+
aIH["Install-PSModuleHelpers"]
147+
aIP["Invoke-Pester"]
148+
aISA["Invoke-ScriptAnalyzer"]
149+
aDoc["Document-PSModule"]
150+
aSettings["Get-PSModuleSettings"]
151+
aCov["Get-PesterCodeCoverage"]
152+
aResults["Get-PesterTestResults"]
153+
aBuild["Build-PSModule"]
154+
aPub["Publish-PSModule"]
155+
aTest["Test-PSModule"]
156+
end
157+
158+
subgraph EXT["Third-party actions"]
159+
xUl["actions/upload-artifact"]
160+
xDl["actions/download-artifact"]
161+
end
162+
163+
subgraph FRAME["PowerShell modules - framework"]
164+
mGitHub["GitHub"]
165+
mContext["Context"]
166+
mUri["Uri"]
167+
mHash["Hashtable"]
168+
mSodium["Sodium"]
169+
mCasing["CasingStyle"]
170+
mTimeSpan["TimeSpan"]
171+
mHelpers["Helpers (bundled)"]
172+
end
173+
174+
subgraph TOOL["PowerShell modules - tooling"]
175+
mPester["Pester"]
176+
mPSSA["PSScriptAnalyzer"]
177+
mPlaty["Microsoft.PowerShell.PlatyPS"]
178+
mYaml["powershell-yaml"]
179+
mMarkdown["Markdown"]
180+
end
181+
182+
aGitHubScript --> mGitHub
183+
aIH --> mHelpers
184+
aIP --> aGitHubScript & xUl & mPester & mHash & mTimeSpan & mMarkdown
185+
aISA --> aGitHubScript & aIP & mPSSA
186+
aDoc --> aIH & mPlaty
187+
aSettings --> aGitHubScript & mYaml & mHash
188+
aCov --> aGitHubScript & mMarkdown
189+
aResults --> aGitHubScript
190+
aBuild --> aIH & xUl
191+
aPub --> aIH & xDl
192+
aTest --> aIH & aIP
193+
194+
mGitHub --> mContext & mUri & mHash & mSodium & mCasing & mTimeSpan
195+
mContext --> mSodium
196+
197+
classDef bundled stroke-dasharray: 4 4;
198+
class mHelpers bundled;
199+
```
200+
201+
## Non-PowerShell toolchains
202+
203+
Two stages step outside PowerShell. `Build-Site` installs MkDocs and its plugins with `pip` and then runs `mkdocs build`. `Lint-Repository` and
204+
`Build-Docs` run `super-linter`, a Docker action.
205+
206+
```mermaid
207+
flowchart LR
208+
subgraph WFsite["Site, docs and lint workflows"]
209+
bSite["Build-Site"]
210+
bDocs["Build-Docs"]
211+
lRepo["Lint-Repository"]
212+
end
213+
214+
subgraph PY["Python toolchain (pip, runner-provided)"]
215+
pmat["mkdocs-material"]
216+
pauth["mkdocs-git-authors-plugin"]
217+
prev["mkdocs-git-revision-date-localized-plugin"]
218+
pcomm["mkdocs-git-committers-plugin-2"]
219+
mkdocs["mkdocs"]
220+
end
221+
222+
subgraph DK["Container image (Docker action)"]
223+
sl["super-linter/super-linter"]
224+
slslim["super-linter/super-linter/slim"]
225+
end
226+
227+
bSite -->|pip install| pmat & pauth & prev & pcomm
228+
pmat --> mkdocs
229+
bSite -->|mkdocs build| mkdocs
230+
lRepo --> sl
231+
bDocs --> slslim
232+
233+
classDef docker fill:#0db7ed,color:#000,stroke:#066699;
234+
classDef py fill:#ffd43b,color:#000,stroke:#997700;
235+
class sl,slslim docker;
236+
class pmat,pauth,prev,pcomm,mkdocs py;
237+
```
238+
239+
## Dependency reference
240+
241+
### Reusable workflows
242+
243+
The 15 stage workflows called by `workflow.yml`, in lifecycle order.
244+
245+
| Workflow | Stage | Key actions used |
246+
| --- | --- | --- |
247+
| Get-Settings | Load configuration | Get-PSModuleSettings |
248+
| Lint-Repository | Repository linting | super-linter |
249+
| Build-Module | Build the module | Build-PSModule |
250+
| Test-SourceCode | Source code tests | Test-PSModule |
251+
| Lint-SourceCode | Static analysis | Invoke-ScriptAnalyzer |
252+
| Test-Module | Built-module tests | Invoke-ScriptAnalyzer, Test-PSModule |
253+
| BeforeAll-ModuleLocal | Integration test setup | GitHub-Script |
254+
| Test-ModuleLocal | Local integration tests | Install-PSModuleHelpers, Invoke-Pester |
255+
| AfterAll-ModuleLocal | Integration test teardown | GitHub-Script |
256+
| Get-TestResults | Aggregate test results | Get-PesterTestResults |
257+
| Get-CodeCoverage | Aggregate code coverage | Get-PesterCodeCoverage |
258+
| Publish-Module | Publish to the PowerShell Gallery | Publish-PSModule |
259+
| Build-Docs | Generate documentation | Document-PSModule, GitHub-Script, super-linter |
260+
| Build-Site | Build the documentation site | GitHub-Script, Install-PSModuleHelpers, MkDocs |
261+
| Publish-Site | Deploy to GitHub Pages | actions/configure-pages, actions/deploy-pages |
262+
263+
### PSModule actions
264+
265+
Composite actions maintained in the [PSModule organization](https://github.com/PSModule).
266+
267+
| Action | Purpose | Depends on |
268+
| --- | --- | --- |
269+
| [GitHub-Script](https://github.com/PSModule/GitHub-Script) | Run PowerShell with the GitHub module installed | GitHub module |
270+
| [Install-PSModuleHelpers](https://github.com/PSModule/Install-PSModuleHelpers) | Load the bundled Helpers module | Helpers (bundled) |
271+
| [Get-PSModuleSettings](https://github.com/PSModule/Get-PSModuleSettings) | Read and resolve the settings file | GitHub-Script, powershell-yaml, Hashtable |
272+
| [Build-PSModule](https://github.com/PSModule/Build-PSModule) | Compile source into a module | Install-PSModuleHelpers, actions/upload-artifact |
273+
| [Test-PSModule](https://github.com/PSModule/Test-PSModule) | Run framework and module tests | Install-PSModuleHelpers, Invoke-Pester |
274+
| [Invoke-Pester](https://github.com/PSModule/Invoke-Pester) | Run Pester test suites | GitHub-Script, actions/upload-artifact, Pester, Markdown |
275+
| [Invoke-ScriptAnalyzer](https://github.com/PSModule/Invoke-ScriptAnalyzer) | Run PSScriptAnalyzer rules | GitHub-Script, Invoke-Pester, PSScriptAnalyzer |
276+
| [Get-PesterTestResults](https://github.com/PSModule/Get-PesterTestResults) | Aggregate test results | GitHub-Script |
277+
| [Get-PesterCodeCoverage](https://github.com/PSModule/Get-PesterCodeCoverage) | Aggregate code coverage | GitHub-Script, Markdown |
278+
| [Publish-PSModule](https://github.com/PSModule/Publish-PSModule) | Publish to the PowerShell Gallery | Install-PSModuleHelpers, actions/download-artifact |
279+
| [Document-PSModule](https://github.com/PSModule/Document-PSModule) | Generate documentation | Install-PSModuleHelpers, Microsoft.PowerShell.PlatyPS |
280+
281+
### Third-party actions
282+
283+
Actions maintained outside the PSModule organization, treated as leaves at their pinned commit.
284+
285+
| Action | Purpose |
286+
| --- | --- |
287+
| [actions/checkout](https://github.com/actions/checkout) | Check out the repository |
288+
| [actions/download-artifact](https://github.com/actions/download-artifact) | Download build artifacts between jobs |
289+
| [actions/upload-artifact](https://github.com/actions/upload-artifact) | Upload build and test artifacts |
290+
| [actions/upload-pages-artifact](https://github.com/actions/upload-pages-artifact) | Package the site for GitHub Pages |
291+
| [actions/configure-pages](https://github.com/actions/configure-pages) | Configure GitHub Pages |
292+
| [actions/deploy-pages](https://github.com/actions/deploy-pages) | Deploy the site to GitHub Pages |
293+
| [super-linter/super-linter](https://github.com/super-linter/super-linter) | Lint the repository and generated docs (Docker image) |
294+
| [super-linter/super-linter/slim](https://github.com/super-linter/super-linter) | Lint the repository and generated docs (Docker image, slim variant) |
295+
296+
### PowerShell modules
297+
298+
Runtime modules installed from the PowerShell Gallery, except `Helpers`, which is bundled inside `Install-PSModuleHelpers`.
299+
300+
| Module | Owner | Role | Depends on |
301+
| --- | --- | --- | --- |
302+
| [GitHub](https://www.powershellgallery.com/packages/GitHub) | PSModule | GitHub API client used by GitHub-Script | Context, Uri, Hashtable, Sodium, CasingStyle, TimeSpan |
303+
| [Context](https://www.powershellgallery.com/packages/Context) | PSModule | Credential and context store | Sodium |
304+
| [Sodium](https://www.powershellgallery.com/packages/Sodium) | PSModule | Encryption helpers | — |
305+
| [Uri](https://www.powershellgallery.com/packages/Uri) | PSModule | URI helpers | — |
306+
| [Hashtable](https://www.powershellgallery.com/packages/Hashtable) | PSModule | Hashtable helpers | — |
307+
| [CasingStyle](https://www.powershellgallery.com/packages/CasingStyle) | PSModule | String casing helpers | — |
308+
| [TimeSpan](https://www.powershellgallery.com/packages/TimeSpan) | PSModule | Time span helpers | — |
309+
| [Markdown](https://www.powershellgallery.com/packages/Markdown) | PSModule | Markdown generation for job summaries | — |
310+
| [Pester](https://www.powershellgallery.com/packages/Pester) | Pester Team | Test runner | — |
311+
| [PSScriptAnalyzer](https://www.powershellgallery.com/packages/PSScriptAnalyzer) | Microsoft | Static analysis rules | — |
312+
| [Microsoft.PowerShell.PlatyPS](https://www.powershellgallery.com/packages/Microsoft.PowerShell.PlatyPS) | PowerShell team | Documentation generation | — |
313+
| [powershell-yaml](https://www.powershellgallery.com/packages/powershell-yaml) | Community | YAML parsing for the settings file | — |
314+
| Helpers | PSModule | Shared helpers bundled in Install-PSModuleHelpers | — (not published to a registry) |
315+
316+
### Python packages
317+
318+
Installed with `pip` in `Build-Site` to build the documentation site. Their transitive dependencies are resolved by `pip`.
319+
320+
| Package | Role |
321+
| --- | --- |
322+
| [mkdocs-material](https://pypi.org/project/mkdocs-material/) | Material theme for MkDocs (pulls in `mkdocs`) |
323+
| [mkdocs-git-authors-plugin](https://pypi.org/project/mkdocs-git-authors-plugin/) | Adds Git author information to pages |
324+
| [mkdocs-git-revision-date-localized-plugin](https://pypi.org/project/mkdocs-git-revision-date-localized-plugin/) | Adds localized revision dates to pages |
325+
| [mkdocs-git-committers-plugin-2](https://pypi.org/project/mkdocs-git-committers-plugin-2/) | Adds committer information to pages |
326+
327+
## External registries and services
328+
329+
These are not nodes in the tree, but they are where the dependencies come from or where outputs go:
330+
331+
| Service | Used for |
332+
| --- | --- |
333+
| PowerShell Gallery | Installing and publishing PowerShell modules |
334+
| PyPI | Installing the MkDocs packages |
335+
| GitHub Container Registry | Pulling the super-linter image |
336+
| GitHub API | Actions that read or write repository data |
337+
| GitHub Pages | Hosting the published documentation site |
338+
| GitHub Actions artifact storage | Passing build outputs between jobs |
339+
340+
Ambient runtimes are provided by the `ubuntu-latest` runner and are not expanded here: PowerShell, Python with `pip`, Node.js, and Git.
341+
342+
## Auxiliary workflows
343+
344+
These live in the repository but are not part of the reusable workflow consumers call. They automate maintenance of Process-PSModule itself:
345+
346+
| Workflow | Trigger | Purpose |
347+
| --- | --- | --- |
348+
| Release.yml | Pull requests that change `.github/workflows/**` | Releases new versions with `Release-GHRepository`, which builds on `GitHub-Script` |
349+
| Linter.yml | Pull requests | Lints this repository with `super-linter` |
350+
| Workflow-Test-Default.yml | Self-test | Runs `workflow.yml` with the default configuration |
351+
| Workflow-Test-WithManifest.yml | Self-test | Runs `workflow.yml` with a manifest-based configuration |
352+
353+
## Out of scope
354+
355+
The modules a consuming repository declares with `#Requires -Modules` in its own source files are collected by `Build-PSModule` into the compiled
356+
manifest, but they vary per repository and are not part of the Process-PSModule dependency tree.
357+
358+
## Keeping this document current
359+
360+
Version pins (commit SHAs and tags) are intentionally omitted here because they change often; the workflow files under `.github/workflows/` are the
361+
source of truth. To refresh this document, re-read the `uses:` entries in those files and the install steps in each action, then update the diagrams
362+
and tables above.

‎README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ Depending on the labels in the pull requests, the [workflow will result in diffe
4343
- [How to get started](#how-to-get-started)
4444
- [How it works](#how-it-works)
4545
- [Workflow overview](#workflow-overview)
46+
- [Dependency tree](#dependency-tree)
4647
- [Get-Settings](#get-settings)
4748
- [Lint-Repository](#lint-repository)
4849
- [Get settings](#get-settings-1)
@@ -106,6 +107,11 @@ Depending on the labels in the pull requests, the [workflow will result in diffe
106107
- [Colocation of concerns](#colocation-of-concerns)
107108
- [Compatibility](#compatibility)
108109

110+
### Dependency tree
111+
112+
Process-PSModule composes its work from reusable workflows, actions, a container image, PowerShell modules, and Python packages. For the full
113+
dependency tree, including diagrams and a reference of every dependency, see [DEPENDENCIES.md](./DEPENDENCIES.md).
114+
109115
### Get-Settings
110116

111117
[workflow](./.github/workflows/Get-Settings.yml)

0 commit comments

Comments
 (0)