feat(lifecycle): add automatic orphaned module cleanup to update command by AshokThangavel · Pull Request #1059 · intersystems/ipm

AshokThangavel · 2026-02-01T11:27:56Z

Description

This PR introduces automatic management of orphaned dependencies during the update command. When a module is updated and its new version no longer requires certain dependencies, those "orphaned" modules are now automatically uninstalled to maintain namespace hygiene. A new flag, -keep-orphans, has been added to allow users to override this behavior.
fixes: #868

2. New Command Flag

Flag: -keep-orphans
Behavior: When present, the UninstallOrphanedDependencies method is skipped, leaving all previously installed dependencies intact.

output

zpm:USER>list
IPM (zpm)                              0.10.6-SNAPSHOT
demo-module1                           1.0.0
irisjwt                                1.0.0
iris-LocalizationLab (localizationlab) 1.0.0
objectscript-math                      0.0.5
zpm:USER>update demo-module1 -p /usr/irissys/mgr/user/mod1/

Building dependency graph...Done.
[USER|demo-module1]     Initialize START
[USER|demo-module1]     Initialize SUCCESS
[USER|demo-module1]     Reload START (/usr/irissys/mgr/user/mod1/)
[USER|demo-module1]     Reload SUCCESS
[demo-module1]  Module object refreshed.
[USER|demo-module1]     Validate START
[USER|demo-module1]     Validate SUCCESS
[USER|demo-module1]     Compile START
[USER|demo-module1]     Compile SUCCESS
[USER|demo-module1]     Activate START
[USER|demo-module1]     Configure START
[USER|demo-module1]     Configure SUCCESS
[USER|demo-module1]     Activate SUCCESS
[USER|demo-module1]     ApplyUpdateSteps START
[USER|demo-module1]     ApplyUpdateSteps SUCCESS
Uninstalling orphaned dependencies
[USER|irisjwt]  Clean START
[USER|irisjwt]  Unconfigure START
[USER|irisjwt]  Unconfigure SUCCESS
[USER|irisjwt]  Clean SUCCESS
Module installed successfully! To start call USER>Do ##class(Package.Class).Run()

zpm:USER>list
IPM (zpm)                              0.10.6-SNAPSHOT
demo-module1                           1.0.0
iris-LocalizationLab (localizationlab) 1.0.0
objectscript-math                      0.0.5

- Implement logic to identify and uninstall dependencies removed in new module versions. - Introduce -keep-orphans (-ko) flag to allow users to opt-out of cleanup. - Ensure cleanup logic is scoped strictly to the 'update' command. - Add integration tests in Test.PM.Unit.OrphanCleanup to verify flag behavior. - Update command metadata and help text for 'update'.

isc-jili

@AshokThangavel functionality looks good! I left some comments. Mostly nits!
Also I think the CHANGELOG will need to be updated due to IPM version having changed in the interim

isc-jili · 2026-03-09T18:19:01Z

tests/integration_tests/Test/PM/Integration/OrphanCleanup.cls

@@ -0,0 +1,229 @@
+Class Test.PM.Integration.OrphanCleanup Extends Test.PM.Integration.Base


nit: We already have an existing Update test suite in Test.PM.Integration.Update. I suggest either adding to that suite, or naming this test suite to be explicitly update related (eg. UpdateOrphanCleanup.cls)

Thank you. I've updated the class name to Test.PM.Integration.UpdateOrphanCleanup

isc-jili · 2026-03-09T18:22:36Z

src/cls/IPM/Main.cls

 <modifier name="path" aliases="p" value="true" description="Location of local tarball containing the updated version of the module. Overrides 'version' parameter if present." />
 <modifier name="dev" dataAlias="DeveloperMode" dataValue="1" description="Sets the DeveloperMode flag for the module's lifecycle. Key consequences of this are that ^Sources will be configured for resources in the module, and installer methods will be called with the dev mode flag set." />
 <modifier name="create-lockfile" aliases="lock" dataAlias="CreateLockFile" dataValue="1" description="Upon update, creates/updates the module's lock file." />
+<modifier name="keep-orphans" aliases="ko" dataAlias="KeepOrphans" dataValue="1" description="Retains dependencies that are no longer required by the updated module. By default, these orphaned modules are automatically uninstalled." />


nit: I don't love the alias "ko" as it has "kill" implications which is the opposite of what this does (ie. "k" by itself in Objectscript means kill, "KO" means kill in other contexts) so that could be misleading. I suggest either naming keep-orphans differently, or abbreviating it differently

thank you. I agree, I've modified the alias to -ro (Retain Orphans) .

Hi @AshokThangavel thank you for the change! I discussed with my team and we believe the best way is actually to remove the alias entirely. Since "ro" also has the more widely known meaning "read-only". It's okay for this command to not have an alias.

Hi @isc-jili, thanks for confirming. I’ve removed the -ro alias for keep-orphans, and as suggested, there is now no alias for it. Thank you!

updated the pull request description as well.

isc-jili · 2026-03-09T18:25:06Z

tests/integration_tests/Test/PM/Integration/OrphanCleanup.cls

+    set depsCount = moduleObj.Dependencies.Count()
+    for i=1:1:depsCount{
+        set depsName = moduleObj.Dependencies.GetAt(i)
+        do $$$LogMessage("Module "_depsName.Name_" installed successfully")


nit: in the log make it explicit that these installed modules are dependencies of module1

updated the code!

isc-jili · 2026-03-09T18:25:24Z

tests/integration_tests/Test/PM/Integration/OrphanCleanup.cls

+        do $$$LogMessage("Module "_depsName.Name_" installed successfully")
+    }
+    if depsCount = 3 {
+        do $$$LogMessage("All 3 modules are loaded successfully")


nit: "All 3 dependency modules ..."

Fixed the message. Thank you!

isc-jili · 2026-03-09T18:26:09Z

tests/integration_tests/Test/PM/Integration/OrphanCleanup.cls

+
+    for i=1:1:depsCount{
+        set depsName = moduleObj.Dependencies.GetAt(i)
+        do $$$LogMessage("Module "_depsName.Name_" exist")


nit: "Dependency module ..."

Fixed the message.

isc-jili · 2026-03-09T18:32:11Z

tests/integration_tests/Test/PM/Integration/OrphanCleanup.cls

+{
+    if '##class(%File).DirectoryExists(Directory) {
+        set status = ##class(%File).CreateDirectoryChain(Directory)
+        do $$$AssertStatusOK(status," Directory"_Directory_" not exist. So created the directory")


nit: "Directory "Directory" does not exist. So created the directory."

modified the code.

isc-jili · 2026-03-09T18:33:05Z

tests/integration_tests/Test/PM/Integration/OrphanCleanup.cls

+        do $$$AssertStatusOK(status," Directory"_Directory_" not exist. So created the directory")
+    }
+    else {
+        do $$$LogMessage("Directory "_Directory_" is already exist")


nit: "Directory "Directory" already exists."

fixed. Thank you!

isc-jili · 2026-03-09T18:34:22Z

tests/integration_tests/Test/PM/Integration/OrphanCleanup.cls

+
+Method CreateModuleFile(
+	ModuleFile As %String = "",
+	moduleXdata As %String = "")


nit: Inconsistent capitalization of variables

Corrected the Parameter variables Inconsistency. Thank you!

isc-jili · 2026-03-09T18:34:50Z

tests/integration_tests/Test/PM/Integration/OrphanCleanup.cls

+        quit 0
+    }
+    if '##class(%File).Exists(ModuleFile) {
+        do $$$LogMessage(ModuleFile_" not exist. So creating the xml")


nit: does not exist

added the changes!

isc-jili · 2026-03-09T18:40:37Z

src/cls/IPM/Utils/Module.cls

+	Output OrphanedModules)
+{
+    kill OrphanedModules
+    merge existDeps = ExistDependencies


nit: inconsistent casing for vars
Also, what is the point of making a copy of ExistDependencies instead of acting directly on ExistDependencies? I don't see ExistDependencies being used after this method call.

I've updated the code.
Thank you!

* Added 'ro' as a short alias for the '-keep-orphans' flag. * Renamed 'OrphanCleanup' class to 'UpdateOrphanCleanup' for better architectural clarity.

…t difference.

isc-jili

@AshokThangavel it's getting really close! Left another round mostly small suggestions. Thanks for implementing this feature!

isc-jili · 2026-03-13T15:14:04Z

src/cls/IPM/Utils/Module.cls

+/// Recursively removes modules not required by the main module or other local packages.
+ClassMethod UninstallOrphanedDependencies(
+	ByRef orphanedDeps,
+	ByRef Params)


nit: inconsistent capitalization of variables.
I suggest turning on the force-formatting rules found in IPM/.vscode/settings.json if working with VSCode.

Fixed the capitalization of variables. Thank you!

These are the existing Force-formatting rules in the settings.json. Please let me know if anything missing

// Force formatting rules "intersystems.testingManager.client.relativeTestRoot": "tests/unit_tests", "objectscript.multilineMethodArgs": true, "intersystems.language-server.formatting.expandClassNames": false, "intersystems.language-server.formatting.commands.case": "lower", "intersystems.language-server.formatting.commands.length": "long", "intersystems.language-server.formatting.system.case": "lower", "intersystems.language-server.formatting.system.length": "long",

Thank you!

Ah sorry I misremembered the rules. The rules look fine! They will not change variable capitalization so that will be up to us to catch any inconsistencies

No worries. Thank you for the confirmation.

isc-jili · 2026-03-13T15:19:57Z

src/cls/IPM/Main.cls

 </command>

 <command name="update" dataPrefix="D">
 <summary>Updates a module to a newer version.</summary>


Suggest adding to update command description and summary that by default it will uninstall all orphaned modules

Thank you. Additionally, uninstalls any modules that are no longer required as dependencies by default - added this in the description

isc-jili · 2026-03-13T15:21:05Z

tests/integration_tests/Test/PM/Integration/UpdateOrphanCleanup.cls

+
+    set status = ..CreateModuleFile(v1ModuleDir, "DemoModuleV1")
+    do $$$AssertStatusOK(status, mainModule_" version 1.0.0 Module.xml created")
+    do ..CreateDependecnyModules(v1ModuleDir)


nit: typo should be CreateDependencyModules

Fixed the Method name typo. Thank you!

isc-jili · 2026-03-13T15:21:25Z

tests/integration_tests/Test/PM/Integration/UpdateOrphanCleanup.cls

+
+    do $$$LogMessage("Loading '" _ mainModule _ "' version 1.0.0")
+    set status = ..RunCommand("load "_v1ModuleDir)
+    do $$$AssertStatusOK(status, mainModule_" version 1.0.0 laoded successfully")


nit: typo should be "loaded"

Fixed the typo.

isc-jili · 2026-03-13T15:22:07Z

tests/integration_tests/Test/PM/Integration/UpdateOrphanCleanup.cls

+    set depsCount = moduleObj.Dependencies.Count()
+        for i=1:1:depsCount{
+            set depsName = moduleObj.Dependencies.GetAt(i)
+            do $$$LogMessage("Dependency module "_depsName.Name_" is exist")


nit: should be "Dependency module "depsName.Name" exists"

fixed the message. Thank you!

isc-jili · 2026-03-13T15:23:15Z

tests/integration_tests/Test/PM/Integration/UpdateOrphanCleanup.cls

+    return status
+}
+
+Method CreateDependecnyModules(Directory As %String = "")


nit: typo in method name should be "Dependency"

Updated the methodName. Thank you!

AshokThangavel requested review from isc-dchui, isc-egabhart, isc-eneil, isc-jili, isc-jlechtne, isc-kiyer, isc-pbarton and isc-tleavitt as code owners February 1, 2026 11:27

AshokThangavel added 2 commits February 1, 2026 16:59

docs: updated the changelog

61d6e7f

Merge branch 'origin/main' into feat-remove-stale-dependencies-on-update

b72105f

AshokThangavel requested a review from isc-cborbonm as a code owner February 10, 2026 15:53

AshokThangavel and others added 2 commits March 8, 2026 18:39

Merge branch 'main' into feat-remove-stale-dependencies-on-update

b5fd4b1

Merge branch 'main' into feat-remove-stale-dependencies-on-update

3a518a5

isc-jili requested changes Mar 9, 2026

View reviewed changes

AshokThangavel added 5 commits March 10, 2026 07:53

Merge branch 'main' into feat-remove-stale-dependencies-on-update

6fc576e

refactor: modify -keep-orphans alias and rename cleanup class

77d1b44

* Added 'ro' as a short alias for the '-keep-orphans' flag. * Renamed 'OrphanCleanup' class to 'UpdateOrphanCleanup' for better architectural clarity.

Refactor: Modify ExistDependencies directly to identify orphans by se…

a829109

…t difference.

Merge branch 'main' into feat-remove-stale-dependencies-on-update

32fed36

cli: removed the alias -ro from the keep-orphans

95e9456

isc-jili requested changes Mar 13, 2026

View reviewed changes

refactor: updated the code based on comments

17f0a15

isc-jili approved these changes Mar 16, 2026

View reviewed changes

		@@ -0,0 +1,229 @@
		Class Test.PM.Integration.OrphanCleanup Extends Test.PM.Integration.Base

Conversation

AshokThangavel commented Feb 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

2. New Command Flag

Uh oh!

isc-jili left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AshokThangavel Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

isc-jili left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

AshokThangavel commented Feb 1, 2026 •

edited

Loading

isc-jili left a comment •

edited

Loading

AshokThangavel Mar 10, 2026 •

edited

Loading