[isc-dchui]

Description

Fixes #1019

There's no way in the shell to see what an installed module contains or what it touched without opening its module.xml. list -tree shows forward dependencies for the whole namespace, which is hard to read on large trees. The issue proposes list <module> -v, but list takes a wildcard search and is built for scanning many modules. This view is about one module, so it gets its own command, show <module>.

The output answers three questions: which copy is this and how do I use it, what did it put on the system, and what does it need and what needs it. It includes only what a user can understand by reading the line, so anything you'd have to trace through code to interpret is left out.

Example Output

zpm:USER>show ipm

IPM (zpm) 0.10.11-SNAPSHOT
    Description:    InterSystems Package Manager (IPM) provides development tools and infrastructure for defining, building, distributing, and installing modules and applications.
    Root:           /home/irisowner/zpm/
    Last updated:   2026-11-04 20:43:57

    Code
        %IPM.PKG
        %IPM.Common.INC
        %IPM.Formatting.INC
        IPM.Installer.CLS
    Files
        modules/python/rpds.py  -> ${mgrdir}python/rpds.py
        ipm                     -> ${ipmdir}bin/ipm
        iriscli                 -> ${ipmdir}bin/iriscli
    Python
        wheels: attrs-25.1.0-py3-none-any.whl, certifi-2026.10.19-py3-none-any.whl, charset_normalizer-2.1.1-py3-none-any.whl, idna-3.15-py3-none-any.whl, jsonschema-4.23.0-py3-none-any.whl, jsonschema_specifications-2024.10.1-py3-none-any.whl, oras-0.1.30-py3-none-any.whl, referencing-0.36.2-py3-none-any.whl, requests-2.32.3-py3-none-any.whl, typing_extensions-4.12.2-py3-none-any.whl, urllib3-2.6.3-py3-none-any.whl

    System requirements
        IRIS >=2022.1

Review notes

• Attribute values print as declared, with ${...} unexpanded. Evaluating them at show time could disagree with what install produced.
• Left out: Scope="test"/"verify" resources and dependencies, UnitTest/Test resources, Invoke, and build details (Packaging, SourcesRoot, lifecycle and installer class, and so on). Scoped dependencies usually aren't installed outside dev mode, so they would show as misleading "not installed" lines.
• "Required by directly" lists only installed modules in this namespace, so it needs no repository access. list-dependents still covers transitive and remote dependents.
• A dependency whose installed version doesn't satisfy the declared version, exact or range, is marked unsatisfied. In a list of dozens, that row would otherwise look like every other.
• The module can be named by Name or ExternalName.

Large dependency graphs

Tried against 52 generated modules with 274 dependency edges:

                         perf-hub
                            │  depends on all 50 below
           ┌────────────────┴────────────────┐
           ▼                                 ▼
   perf-app-01 … perf-app-30  ──────►  perf-lib-01 … perf-lib-20
   each: core + 4 libs                 each: core + up to 3 earlier libs
           │                                 │
           └────────────────┬────────────────┘
                            ▼
                        perf-core
                   required by all 50

A module in the middle of the graph, with one stored version requirement raised to ^2.0.0 so the mismatch shows:

zpm:USER>show perf-app-07

perf-app-07 1.0.0
    Description:    Synthetic module perf-app-07 for show perf.
    Root:           /tmp/showperf/perf-app-07/
    Last updated:   2026-11-05 21:31:53

    Code
        perfapp07.PKG

    Depends on (5)
        perf-core ^1.0.0    installed 1.0.0
        perf-lib-02 ^1.0.0  installed 1.0.0
        perf-lib-07 ^1.0.0  installed 1.0.0
        perf-lib-12 ^2.0.0  installed 1.0.0, unsatisfied
        perf-lib-17 ^1.0.0  installed 1.0.0

    Required by directly (1)
        perf-hub 1.0.0

The two ends of the graph, with the header lines and the middle rows cut:

zpm:USER>show perf-hub
    ...
    Depends on (50)
        perf-app-01 ^1.0.0  installed 1.0.0
        ...
        perf-app-30 ^1.0.0  installed 1.0.0
        perf-lib-01 ^1.0.0  installed 1.0.0
        ...
        perf-lib-20 ^1.0.0  installed 1.0.0

zpm:USER>show perf-core
    ...
    Required by directly (50)
        perf-app-01 1.0.0
        ...
        perf-lib-20 1.0.0

Every module in the graph took under 7 ms, averaged over 20 runs. Show reads only direct relationships, so the cost grows with the module's own edge count, apart from the "Required by" query, which scans every dependency row in the namespace.

Testing

• Test.PM.Unit.ModuleSummary
• Test.PM.Unit.ResourceReference:TestResolvedProcessorClass
• Test.PM.Integration.Show

Checklist

• This branch has the latest changes from the main branch rebased or merged.
• Changelog entry added.
• Unit (zpm test -only) and integration tests (zpm verify -only) pass.
• Style matches the style guide in the contributing guide.
• Documentation has been/will be updated
  • Source controlled docs, e.g. README.md, should be included in this PR and Wiki changes should be made after this PR is merged (add an extra issue for this if needed)
• Pull request correctly renders in the "Preview" tab.

🤖 Generated with Claude Code

[isc-kiyer]

@isc-dchui can you add some examples for what it looks like when there are many modules in play and a module has many dependencies/dependents? Also, what is the performance like for such a module? May be worth having some flags for skipping parts of the dependencies/dependents search if its slow?

[isc-dchui]

@isc-kiyer I've updated the description with an example (and improved the display in a few cases). Performance is essentially a none issue in this test case.

[isc-kiyer]

Nit: why not just use ReadLine() instead of reading to a string first and then splitting? That should handle OS specific line endings right?

[isc-dchui]

Ah good call