Extract more of the plumbing around entry points for reuse

[imrekoszo]

While working on polylith-kaocha I noticed that kaocha's 3 entry points (cli, -x, repl) seemingly reimplement common functionality with some subtle differences (like cloverage not being usable from repl/run). Because I wanted to support cloverage in p-k I had to again reimplement some of the stuff that -x does.

It would be great from the perspective of other tooling calling kaocha in-process to have more of this common functionality available for reuse without having to be aware of internals. I imagine most of the benefits of this work would only be towards tooling authors mind you.

Apart from the wrappers around the main process with all hooks, one area that could be helpful is exposing the parsing of -m-style command line args so other command-line tooling calling kaocha could pass them through without calling -m or having to understand it.

Potentially related issue: #305

[plexus]

I must admit I did not anticipate so many different implementations for running kaocha from a terminal. My main assumption of which tooling would want to integrate was things like IDEs, where the cli parsing is not relevant and instead you want data structures.

The fact that the main hook isn't handled in kaocha.repl has also been deliberate. Main is meant for plugins which, based on some cli flag, want to piggie back on kaocha's execution wrapper to do a completely different task, like invoking cloverage (which is its own test runner) instead of running kaocha. In the repl the assumption is that you can just invoke the other thing.

But that's theory and I agree we want to practical here. It doesn't look like there's anything really stopping us from handling main at the kaocha.api level.

I think the main complexity stems from coordinating a number of hooks, like config, that need to be handled in a specific way, which currently each entry point implementation does on its own. Moving those patterns into kaocha.api (and updating each entry point) or moving these patterns into a utility namespace so they can be reused would both make sense.

It's ironic to me that this was designed in this way specifically to accommodate tooling. Kaocha gives you loosely coupled pieces, kaocha.config, kaocha.api, which you can use and compose as you see fit, because we don't want to overfit the API to the command line runner. And this is still a concern to me. E.g. if we push these things into api then that will make api less flexible, and we may find ourselves then implementing special cases to accommodate certain entry points. That's something I would want to avoid.

We currently have six entry points that I'm aware of (runner, -X, boot, repl, poly, kaocha-nrepl), which is good because if we can accommodate all of these we know we've generalized things well. It's not good because fiddling with this stuff will mean updating all of these, and has a high chance of breaking at least one of these, since people usually only test the one or two entry points they care about.

[imrekoszo]

I think it could be considered an indicator of success that there are more integrations than you had imagined. And the fact that all these implementations were able to function mean that the necessary puzzle pieces are available, which is great.

What I found missing are facades or pre-made compositions that let a caller

• expose pass-through cli configurability
• run stuff "as if it was run from -m" (plugins, hooks etc)
• but still be outside of kaocha being responsible for the entire process itself, like terminating it

[imrekoszo]

Related issue: imrekoszo/polylith-kaocha#6

[alysbrooks]

I don't think this addresses the issue, but some of the refactoring work in #315 is in a similar spirit.