Add a `show` command that summarises a parsed stack definition

[ncoghlan]

While the stack definition format is relatively readable, it is presenting a directed acyclic graph as a flat list. This makes it entirely plausible that a complex stack may end up containing dependency errors that aren't obvious when reading the list, but would potentially be much clearer when listing each defined layer with a tree below it reflecting that layer's linearised dependency list.

The other key benefit of adding such a command is that it would provide a way to add cheaper end-to-end test cases of the layer selection logic (and we recently hit a problem in typer/click that showed the lack of end to end testing in the command line parsing can allow cross-platform compatibility issues to go undetected by the test suite)

[ncoghlan]

Example output for initial draft implementation.

The env_name -> deployed_name notation is used when the build layer name differs from the deployed name.

Without any valid layer locks, everything shows up as outdated (the ??? is placeholder text standing in for layer versions that aren't known due to the invalid layer lock):

$ pdm run venvstacks show tests/sample_project/venvstacks.toml
/home/acoghlan/devel/venvstacks/tests/sample_project/venvstacks.toml
├── Runtimes
│   ├── *cpython-3.11
│   └── *cpython-3.12 -> cpython-3.12@???
├── Frameworks
│   ├── *framework-scipy -> framework-scipy@???
│   │   └── *cpython-3.11
│   ├── *framework-sklearn
│   │   └── *cpython-3.12 -> cpython-3.12@???
│   └── *framework-http-client
│       └── *cpython-3.11
└── Applications
    ├── *app-scipy-import -> app-scipy-import@???
    │   ├── *framework-scipy -> framework-scipy@???
    │   └── *cpython-3.11
    ├── *app-scipy-client
    │   ├── *framework-scipy -> framework-scipy@???
    │   ├── *framework-http-client
    │   └── *cpython-3.11
    └── *app-sklearn-import
        ├── *framework-sklearn
        └── *cpython-3.12 -> cpython-3.12@???

Restoring the layer lock metadata clears the complaints about the lack of valid layer locks:

$ git restore tests/sample_project/requirements
$ pdm run venvstacks show tests/sample_project/venvstacks.toml
/home/acoghlan/devel/venvstacks/tests/sample_project/venvstacks.toml
├── Runtimes
│   ├── cpython-3.11
│   └── cpython-3.12 -> cpython-3.12@2
├── Frameworks
│   ├── framework-scipy -> framework-scipy@1
│   │   └── cpython-3.11
│   ├── framework-sklearn
│   │   └── cpython-3.12 -> cpython-3.12@2
│   └── framework-http-client
│       └── cpython-3.11
└── Applications
    ├── app-scipy-import -> app-scipy-import@3
    │   ├── framework-scipy -> framework-scipy@1
    │   └── cpython-3.11
    ├── app-scipy-client
    │   ├── framework-scipy -> framework-scipy@1
    │   ├── framework-http-client
    │   └── cpython-3.11
    └── app-sklearn-import
        ├── framework-sklearn
        └── cpython-3.12 -> cpython-3.12@2

[ncoghlan]

The build/lock/publish commands also gain --show-stack and --show-only options (the former continues with the command after rendering the stack, the latter terminates without actually running the operation).

Instead of showing the layer dependencies, these instead show the operations enabled for each layer:

$ pdm run venvstacks lock --show-only --include='app-*' tests/sample_project/venvstacks.toml
/home/acoghlan/devel/venvstacks/tests/sample_project/venvstacks.toml
├── Runtimes
│   ├── cpython-3.11 (lock-if-needed, build-if-needed)
│   └── cpython-3.12 -> cpython-3.12@2 (lock-if-needed, build-if-needed)
├── Frameworks
│   ├── framework-scipy -> framework-scipy@1 (lock-if-needed, build-if-needed)
│   ├── framework-sklearn (lock-if-needed, build-if-needed)
│   └── framework-http-client (lock-if-needed, build-if-needed)
└── Applications
    ├── app-scipy-import -> app-scipy-import@3 (lock)
    ├── app-scipy-client (lock)
    └── app-sklearn-import (lock)

[ncoghlan]

Fixing the inclusion filtering.

Unfiltered/filtered show command:

$ pdm run venvstacks show tests/sample_project/venvstacks.toml
/home/acoghlan/devel/venvstacks/tests/sample_project/venvstacks.toml
├── Runtimes
│   ├── cpython-3.11
│   └── cpython-3.12 -> cpython-3.12@2
├── Frameworks
│   ├── framework-scipy -> framework-scipy@1
│   │   └── cpython-3.11
│   ├── framework-sklearn
│   │   └── cpython-3.12 -> cpython-3.12@2
│   └── framework-http-client
│       └── cpython-3.11
└── Applications
    ├── app-scipy-import -> app-scipy-import@3
    │   ├── framework-scipy -> framework-scipy@1
    │   └── cpython-3.11
    ├── app-scipy-client
    │   ├── framework-scipy -> framework-scipy@1
    │   ├── framework-http-client
    │   └── cpython-3.11
    └── app-sklearn-import
        ├── framework-sklearn
        └── cpython-3.12 -> cpython-3.12@2

$ pdm run venvstacks show tests/sample_project/venvstacks.toml --include='*scipy*'
/home/acoghlan/devel/venvstacks/tests/sample_project/venvstacks.toml
├── Runtimes
│   └── cpython-3.11
├── Frameworks
│   ├── framework-scipy -> framework-scipy@1
│   │   └── cpython-3.11
│   └── framework-http-client
│       └── cpython-3.11
└── Applications
    ├── app-scipy-import -> app-scipy-import@3
    │   ├── framework-scipy -> framework-scipy@1
    │   └── cpython-3.11
    └── app-scipy-client
        ├── framework-scipy -> framework-scipy@1
        ├── framework-http-client
        └── cpython-3.11

Unfiltered/filtered stack display in one of the working commands:

$ pdm run venvstacks lock --show-only tests/sample_project/venvstacks.toml
/home/acoghlan/devel/venvstacks/tests/sample_project/venvstacks.toml
├── Runtimes
│   ├── cpython-3.11 (lock)
│   └── cpython-3.12 -> cpython-3.12@2 (lock)
├── Frameworks
│   ├── framework-scipy -> framework-scipy@1 (lock)
│   ├── framework-sklearn (lock)
│   └── framework-http-client (lock)
└── Applications
    ├── app-scipy-import -> app-scipy-import@3 (lock)
    ├── app-scipy-client (lock)
    └── app-sklearn-import (lock)

$ pdm run venvstacks lock --show-only tests/sample_project/venvstacks.toml --inc
lude='*scipy*'
/home/acoghlan/devel/venvstacks/tests/sample_project/venvstacks.toml
├── Runtimes
│   └── cpython-3.11 (lock-if-needed, build-if-needed)
├── Frameworks
│   ├── framework-scipy -> framework-scipy@1 (lock)
│   └── framework-http-client (lock-if-needed, build-if-needed)
└── Applications
    ├── app-scipy-import -> app-scipy-import@3 (lock)
    └── app-scipy-client (lock)