feat: implement 'locate' command for resource-to-module mapping by AshokThangavel · Pull Request #1081 · intersystems/ipm

AshokThangavel · 2026-02-27T19:24:26Z

Add `locate` command to identify resource owner modules

Description

This PR introduces the locate command (alias loc) to the IPM shell. It allows developers to quickly identify which module "owns" a specific resource (Class, Routine, Include file, etc.). The locate command provides a native CLI wrapper around the existing FindHomeModule logic to get the owning module and its current version in a format consistent with the list command.

fixes: #1073

Key Features

Alias Support: Supports both locate and the shorthand loc.
Resource Versatility: Works with .cls, .inc, .mac, and other registered resource types.
Consistent UI: Output matches the standard ZPM list format: <ModuleName> <Version>.
Robust Error Handling: Validates required arguments and provides clear feedback if a resource is unmapped.

Unit Test

A new test suite TestLocateCommand was added to verify the command's behavior across different scenarios.

Unit Test Results:

zpm:USER>loc %IPM.Main.cls

zpm 0.10.6-SNAPSHOT
zpm:USER>loc %IPM.Main.cls

zpm 0.10.6-SNAPSHOT
zpm:USER>loc Testify.Home.cls

testify 1.0.2
zpm:USER>loc Test.Main.cls
Resource 'Test.Main.cls' is not currently mapped to an installed module.
zpm:USER>

Success: loc %IPM.Common.inc returns the correct module.
Success: locate %IPM.Main.cls returns the correct module.
Resilience: Gracefully handles non-existent resources.
Validation: Correctly catches missing arguments via shell validation.

- Added 'locate' (alias 'loc') to identify the owning module of a resource. - Uses %IPM.ExtensionBase.Utils:GetHomeModuleName for reliable lookup. - Formatted output to match 'list' command (Name + Version). - Added unit tests for various resource types (.cls, .inc). - Validated handling of various resource types (.inc, .cls). - Confirmed graceful error handling for missing arguments and non-existent resources.

isc-kiyer

@AshokThangavel Thanks for contributing this! Just a few small notes

isc-kiyer · 2026-03-02T16:39:09Z

src/cls/IPM/Main.cls


+<command name="locate" aliases="loc">
+    <description>Find the module that owns a specific resource.</description>
+    <parameter name="resource" description="resource: The full name of the resource (e.g., My.Class.cls, Utils.inc)." />


The parameter should be marked required

Thank you. I've updated the parameter as required.

isc-kiyer · 2026-03-02T16:40:05Z

src/cls/IPM/Main.cls

+ClassMethod Locate(ByRef CommandInfo)
+{
+    set resource = $get(CommandInfo("parameters","resource"))
+    if resource="" {


This won't be needed once the parameter is marked required

removed the condition as well

isc-kiyer · 2026-03-02T16:43:05Z

src/cls/IPM/Main.cls

 	<example description="Show details of history item with ID 3 and information for each undergone lifecyle phase">history details 3 -phases</example>
 </command>

+<command name="locate" aliases="loc">


Nit: I would call this locate-resource with no alias since locate is a bit ambiguous and seems to overlap with search

Thank you. I've updated the command from locate to locate-resource

isc-kiyer · 2026-03-02T16:49:05Z

src/cls/IPM/Main.cls

+    }
+    set moduleName = ##class(%IPM.ExtensionBase.Utils).GetHomeModuleName(resource)
+    if (moduleName="") {
+        write $$$FormattedLine($$$Red, "Resource '"_ resource_"' is not currently mapped to an installed module.")


Nit: I would replace "mapped to" as "part of" since mappings are an overloaded term at the IRIS level

fixed the message string!

* **Rename** `locate` command to `locate-resource` and **remove alias** per maintainer feedback to avoid ambiguity with system commands. * **Update** error message to use "part of" instead of "mapped to" to avoid confusion with InterSystems IRIS mapping terminology.

isc-dchui · 2026-03-04T16:38:10Z

tests/unit_tests/Test/PM/Unit/CLI.cls

+Method TestLocateCommand()
+{
+    do $$$LogMessage("Testing 'loc' alias with .inc resource")
+    set status = ..RunCommand("loc %IPM.Common.inc")


I believe all these commands will need to be changed to locate-resource

Updated the unit test code. Thank you!

isc-dchui · 2026-03-04T16:38:27Z

CHANGELOG.md


 ### Added
 - #1024: Added flag -export-python-deps to publish command
+- #1081: implement locate command for resource-to-module mapping


Nit: capitalize "implement" and move to 0.10.7

Moved to 1.10.7 release. Thank you!

Looks like you need to pull from main to resolve the conflict here.

pulled from main and resolved the conflicts as well. Thank you!

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

docs: Add changelog entry

85019bc

isc-kiyer requested changes Mar 2, 2026

View reviewed changes

AshokThangavel added 2 commits March 3, 2026 14:52

refactor: Method name updated

c53ff92

isc-dchui reviewed Mar 4, 2026

View reviewed changes

AshokThangavel closed this Mar 5, 2026

AshokThangavel reopened this Mar 5, 2026

AshokThangavel and others added 2 commits March 5, 2026 19:10

updated unit test code and changelog

370d931

Merge branch 'main' into feat/locate-command

c292317

Conversation

AshokThangavel commented Feb 27, 2026

Add locate command to identify resource owner modules

Description

Key Features

Unit Test

Uh oh!

isc-kiyer 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

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Add `locate` command to identify resource owner modules