Add introspection command

Author: stefanv

example_pkg/pyproject.toml

@@ -47,6 +47,9 @@ package = 'example_pkg'
 "Pip" = [
   "spin.cmds.pip.install"
 ]
+"Meta" = [
+  "spin.cmds.meta.introspect"
+]
 
 [tool.spin.kwargs]
 ".spin/cmds.py:example" = {"test" = "default override", "default_kwd" = 3}

spin/__main__.py

@@ -148,6 +148,8 @@ def group(ctx):
                         if option.name in default_kwargs:
                             option.default = default_kwargs[option.name]
 
+                cmd_func.spec = cmd  # store where this function is defined
+                # for use in `introspect` command
                 commands[cmd] = cmd_func
 
             group.add_command(commands[cmd], section=section)

spin/cmds/meta.py

@@ -0,0 +1,55 @@
+import inspect
+
+import click
+
+from .util import get_commands, get_config
+
+
+def _highlight(src):
+    from pygments import highlight
+    from pygments.formatters import TerminalFormatter
+    from pygments.lexers import PythonLexer
+
+    return highlight(src, PythonLexer(), TerminalFormatter())
+
+
+@click.command()
+@click.argument("cmd", nargs=1)
+def introspect(*, cmd):
+    """🔍 Print a command's location and source code."""
+    cmds_by_section = get_commands()
+    overrides = get_config().get("tool.spin.kwargs")
+
+    cmds = {}
+    for section in cmds_by_section:
+        cmds.update({cmd.name: cmd for cmd in cmds_by_section[section]})
+
+    if cmd not in cmds:
+        raise SystemExit(f"Command `{cmd}` not found. Exiting.")
+
+    cmd_func = cmds[cmd]
+    try:
+        code = inspect.getsource(cmd_func.callback)
+    except TypeError:
+        code = inspect.getsource(cmd_func.callback.func)
+
+    click.secho(
+        f"The `{cmd}` command is defined in `{cmd_func.spec}`:\n",
+        bold=True,
+        fg="magenta",
+    )
+
+    try:
+        code = _highlight(code)
+    except ImportError:
+        pass
+
+    print(code)
+
+    if cmd_func.spec in overrides:
+        click.secho(
+            "The function has the following keyword overrides defined:\n",
+            bold=True,
+            fg="magenta",
+        )
+        print(overrides[cmd_func.spec])