feat(inspect): describe a module tree without running it

[rickliujh]

Adds loom inspect, a subcommand that describes what a module is made of — its submodule hierarchy, the operations each one runs, and the parameters they require — without running any of it.

Why

Composition makes a module hard to read ahead of a run. The operations that will execute live in submodules pulled from other repositories, and the parameters they need are handed down through templates rather than declared where you invoke. Until now the only way to find out what a module required was to run it and read the failure.

What it looks like

$ loom inspect ./platform-rollout -p env=prod

[≡ platform-rollout ≡] ./platform-rollout
├─ params
│    env         provided  = "prod"
│    commitHash  dynamic   $ git rev-parse --short HEAD
├─ operations (1, in order)
│    announce  shell  echo rolling out to {{ .env }}
└─ ▸ svc-a-prod (service-onboard)  ../child  if: test -d ./svc-a
   ├─ params
   │    service    provided    = "svc-a"
   │    namespace  provided    = "prod-apps" ← {{ .env }}-apps
   │    region     required    must be supplied
   │    stamp      unresolved  resolved at run time ← {{ .commitHash }}
   ├─ target  https://github.com/acme/svc-a-gitops.git (main) → loom/onboard-svc-a
   └─ operations (3, in order)
        render   newFiles  templates → manifests
        gate     shell     kubeconform manifests  if: test -f manifests/app.yaml
        open-pr  pr        github: Onboard {{ .service }}

⚠ 1 required parameter(s) not supplied — a run would fail:
  region  platform-rollout › svc-a-prod

Modules are labelled with their instance name — the parent's modules[].name, rendered — the same identity the run log and loom diff use, with metadata.name alongside when they differ. A value a parent hands down keeps the expression that produced it (← {{ .env }}-apps), so a templated hand-off stays traceable.

The summary collects every required parameter the tree is missing, each located by the module that declares it. In a composed tree that module is frequently not the one you invoke.

Flags: -p / --params-file, --depth, --no-fetch, -o tree|json.

Nothing executes

No operation runs, no dynamicParams command is evaluated, no if condition is tested, and no target repo is cloned. The sole side effect is cloning a module source that is a git URL — unavoidable if its contents are to be read — into temp dirs removed before the command returns. --no-fetch skips even that.

Templates are rendered only against params whose values are actually known, so one depending on run-time state is reported as unresolved rather than resolved to a <no value> placeholder and passed down as if real.

Reuse over new code

• module.ResolveSource resolves root and child sources (git URLs, //subdir, local paths).
• config.Load / Validate / ValidateInDir, split so a structural error fails a module while a missing newFiles.source only warns — the description stays available, which is the whole point of the command.
• cmd.parseParams for -p / --params-file.
• pkg/action/registry.go refactored so FromOperation and the new DescribeOperation read one switch. A second switch would let a new action type be wired into one and forgotten in the other, so a module could be described as one kind and run as another.
• internal/log gained a Style type exposing the pretty handler's palette. pkg/action had already forked its own copy of the escape codes for diff headers; this stops a third copy appearing, and the tree shares the run log's ≡ … ≡ chip and ▸ hand-off marker.

Robustness

• A failure is contained to the node it happens at, so a broken submodule never hides the rest of the tree.
• A module that is its own ancestor is reported as a cycle and not expanded. Identity is the absolute dir for a local source and the URL for a remote one, since each remote fetch lands in a fresh temp dir.
• --depth truncates rather than failing.

Testing

• specs/inspect.md adds rules IN1–IN15, each referenced by a test — the spectrace guard passes with nothing added to uncovered.
• 20 new tests across pkg/module and cmd. Full suite green, including -race.
• Driven end to end against an offline fixture (local git target, newFiles + patch + shell + commitPush), plus remote module sources via file:// URLs, cycles, depth limits, and --no-fetch. No temp clones leaked.
• Regression check on the registry.go refactor: run --local-run, run --dry-run, and diff --quick produce byte-identical logs and git state against a binary built from main.

Note for reviewers

-p supplies the root module only. A requirement reported deep in the tree is satisfied by the parent forwarding a value, not by another -p. This surprised me while writing the tests, so it is called out in both the reference page and the composition guide.

Commits are split by layer and each is independently green.

🤖 Generated with Claude Code

[rickliujh]

Reworked the default view: one module, submodules listed — expansion is now opt-in.

Walking the whole tree by default made the common question expensive to ask. A module composing several remote submodules cloned all of them before printing anything, and buried its own operations in a wall of output.

[≡ platform-rollout ≡] ./platform-rollout
├─ params
│    env         provided  = "prod"
│    commitHash  dynamic   $ git rev-parse --short HEAD
├─ operations (1, in order)
│    announce  shell  echo rolling out to {{ .env }}
├─ ▸ svc-a-prod  ../child  if: test -d ./svc-a  …
└─ ▸ svc-b  ../child  …

✔ every required parameter of the module(s) shown is satisfied

2 submodule(s) not expanded — they may need parameters of their own:
  platform-rollout › svc-a-prod
  platform-rollout › svc-b

  --full describes all of them; --module svc-a-prod describes one

Three ways to go deeper:

• --full — the whole tree (the old default)
• --depth N — a level or two
• -m, --module NAME — make a submodule the subject, matched on the tail of its breadcrumb, so a bare name works until two modules share one; svc-b/docs disambiguates, and matching several is an error listing the candidates rather than a silent wrong pick

A focused module is headed by its breadcrumb and shows the values its parents actually hand it:

[≡ docs ≡] ../grandchild
in platform-rollout › svc-b › docs
├─ params
│    title  provided  = "svc-b docs" ← {{ .service }} docs

Why listing, not truncating

A module past the depth limit is still reported, carrying what its parent declares (name, source, if) and marked listed. It is never resolved — so the default view does no network I/O, and a listed remote module is not cloned.

That is also what keeps the shallow default honest. Everything the summary claims is scoped to the modules actually read, and the ones skipped are named alongside: a tree can only be called fully parameterized on the strength of modules someone looked at. Same reasoning for exit status — a module that was never resolved cannot have failed to resolve, so a broken submodule surfaces at --full, not at the default depth, where it is reported as unexpanded instead.

-o json gains an unexpanded roll-up for this, so a CI check can assert both:

loom inspect ./mod --full -p env=prod -o json | jq -e '.missingParams == [] and .unexpanded == []'

Notes

• --full with an explicit --depth is rejected rather than silently picking a winner.
• The summary's --module hint is verified to resolve — it qualifies the name when submodules share one, instead of suggesting a command that errors as ambiguous.
• Spec gains IN16 (default depth) and IN17 (module selection); IN5, IN9, and IN15 updated for listing and scoping. All covered by tests.
• Full suite green. Re-confirmed run --local-run output is still byte-identical to a binary built from main.